文档站开发与维护

来源和范围

2026-09-29 组件同步来源：idx-web@c480be58e30ba5ccf8ce380a2425d1fef0eb3d7b；文档站原基线：f14e027691048076232f9289b655ce1e10e674e4。62 个去重公开导出路径以 docs/.vitepress/theme/components/index.ts 为准，不据目录数量推断公开 API。

同步覆盖 core、pro、page、chart、card、editor 及公开类型。组件源码、类型、样式及必要私有依赖来自业务仓库；文档站继续独立维护主题、演示 API/Store、SSR 适配和示例。此处不是共享 npm 包，也没有自动同步任务。

目录与生成链

位置	职责
docs/.vitepress/theme/components	同步组件和文档展示组件，两者不得整体覆盖
docs/.vitepress/theme/composables	组件响应式依赖与文档站权限适配
docs/.vitepress/theme/common、pinia	本地服务、工具、配置和演示状态
docs/examples	可运行且确定性的本地示例
scripts/api-docs-supplement.mjs	生成器的文案与示例补充源
scripts/generate-api-docs.mjs	解析公开导出和 AST，更新 API 与示例区块
docs/components	生成 API 与人工介绍；不要手改生成区

修改 API 时先确认同步源码及类型，再补充缺失说明，执行生成器；重复生成应无差异。不能只手改表格制造正确外观，或把未公开的组件加入目录计数。

本地命令与版本

2026-09-29 同步验证使用 NVM 加载 Node 24.20.0，pnpm 为 11.9.0。沿用 VitePress 1.6.3、TypeScript 5.8.3 和 Vue 3.5.39；新增 Vitest 4.1.9 及其 Vite 8.1.0 测试宿主，VitePress 自身仍使用 Vite 5。Vue Test Utils 2.4.11、jsdom 29.1.1、vue-tsc 3.3.5 用于组件与类型检查；DOMPurify 3.4.15、Axios 1.18.1、SheetJS 0.20.3 与业务锁定版本对齐。锁文件记录精确解析结果，不做全量依赖升级。

pnpm docs:generate-api
pnpm check:all
pnpm typecheck
pnpm test
pnpm docs:build
pnpm docs:build:gzip
pnpm docs:preview

docs:build:gzip 会先重新构建再压缩文本资产，输出属于忽略的 dist；preview 不构建。安装使用冻结锁文件，开发/预览均以前台运行，Ctrl+C 停止。本文列出命令用途，历史执行结果见下方带日期的验证记录。

同步步骤及适配差异

1. 固定两仓库 commit 和工作区状态，对比公开导出、组件及传递依赖，不整仓覆盖。
2. 同步组件与核心回归；补齐业务项目 auto-import 原先提供的显式导入。
3. 对齐工具函数契约、断点和必要依赖；API 与 Store 保持文档站本地实现，不复制 Token、后端地址或业务权限。
4. 保留第三方 SSR 适配；FileSaver、Cropper 等替身只在服务端解析使用，浏览器必须使用真实库。SafeHtml 服务端为空、挂载后净化。
5. Prism 的自动整页扫描在 HTML head 中关闭：文档代码由 Shiki 高亮，编辑器仍可显式高亮；不屏蔽页面异常。主题开关同时同步演示 Store。Teek 的浏览器偏好控件（嵌套 Teleport、浏览器专用插槽）通过官方 teekConfigContext 延迟到挂载后启用，正文继续 SSR；不使用全局 data-allow-mismatch。
6. 适配现有 Vue/TypeScript 的显式模型泛型、旧浏览器声明及第三方 exports 类型缺口，不放宽严格检查。
7. 更新示例、生成 API、检查和浏览器验收，将仍需业务后端的事项分开交接。

VitePress 的 Vite 5 与 Vitest 的 Vite 8 分别作为构建及测试宿主；JSX 插件声明支持两者，在 VitePress 配置中仅对插件宿主类型做一次断言，并以类型检查、SSR 构建和浏览器验证该边界。

示例附件位于 docs/public/templates/demo.xlsx，包含一行“演示材料”；视频 docs/public/media/demo.mp4 是 FFmpeg testsrc2 生成的两秒测试图案，无外部媒体请求。UploadExcel 示例提供真实 Excel 下载与浏览器解析；批量导入的校验/提交仍是明确标注的固定演示响应。

普通对象函数采用箭头函数；Pinia action、插件钩子等依赖动态 this 的位置保留必要方法语义。业务仓库实现是同步源，文档站适配不自动反写业务仓库。

验证与故障排查

静态检查覆盖导出/文档/示例引用和 Vue 导入；类型检查包含隐藏的 .vitepress 目录。Vitest 针对组件的可观察契约，外部服务使用受控替身。文档站没有生产账号或真实接口测试。

静态/动态图标混合导入也会产生分块提示，不影响导出与构建结果。

构建失败先看首个有效错误：缺失符号查导入和适配层；SCSS 变量查命名空间注入；SSR 报 window/document 查生命周期及 SSR-only 映射。不得全局吞掉警告或用客户端空替身假装成功。

页面验收使用独立 Playwright 浏览器，重点检查导航、弹层、表单、表格、上传、主题、图表和下载；窄屏允许 API 表格在容器内部横向滚动，页面本身不得溢出。文档宿主在 767px 以下将示例弹框宽度限制为视口减 24px，避免组件桌面默认 50% 宽度挤压表单；该样式不反写业务组件。旧临时截图不代表本次验证。

CI、证书、Nginx、Helm 和发布脚本由维护人员人工管理；文档整理不运行部署，不上传站点。部署入口与本地检查见仓库 scripts/DEPLOYMENT.md；pnpm check:all 包含不连接集群的部署契约回归检查。

2026-09-29 组件同步验证记录

以下保留上一轮组件同步的原验证日期与结果；本次文档精简仅迁移摘要，未重跑测试、生成、构建或浏览器验收。同步源及文档站原基线见本文开头，不能将这些历史结果视为后来任意 commit 的通过记录。

验证范围	2026-09-29 原执行结果
安装与 API	冻结锁文件安装通过；生成 62 个公开模块，连续两次生成后的文档 SHA-256 无变化
静态与类型	pnpm check:all、pnpm typecheck 通过，覆盖公开导出、API 表格、示例及隐藏 .vitepress 目录
核心回归	pnpm test：34 文件、131 用例通过，覆盖表格乱序/选择/编辑、表单弹框、上传同名/外部清空、HTML 净化、Excel 导出/解析、图表销毁和过期请求
构建	普通与 gzip 构建通过；gzip 生成 231 个忽略的产物，保留图标静态/动态混合导入的分块提示
页面加载	独立 Playwright 检查 62 个公开组件页面，均 HTTP 200，无控制台错误、水合警告或页面水平溢出
主题与视口	表格、表单、表单弹框、树筛选、图片上传、批量导入、Excel、SafeHtml、折线图、编辑器 10 页；亮/暗主题 × 1440、768、390、320px 共 80 组通过
实际交互	表格选择；表单必填、提交、重置；窄屏弹框编辑关闭；本地图片上传；Excel 下载后重新导入解析 1 行；批量导入本地校验/提交/完成页/关闭；编辑器输入及代码块插入

日志和截图当时保存在本机 /tmp/idx-docs-*、/tmp/idx-page-scan.log、/tmp/idx-responsive.log，属于可能被清理的临时证据。长期复验依据为上述版本、锁文件、测试与命令。示例服务使用明确标注的本地数据，没有验证真实业务后端；真实业务与生产验收缺口由业务仓库维护。

后续同步或回退应一起核对组件、依赖锁文件、适配、示例和生成 API，并审查两仓库差异，避免覆盖各自后续修改。