项目文档治理与英文路径迁移计划
依据：docs/00-产品开发流程与文档管理规范.md v1.13、outputs/itdesk-project-folder-audit-20260809.html，以及对 docs 目录的只读规则检查。
本报告是决策和实施计划，不执行迁移、不修改原文档、不删除文件。
可解析文档/配置432
缺少规范头部候选118
引用目标缺失候选97
文件名/内容版本不一致候选12
一、结论
建议迁移，但不建议把中文目录直接整体重命名为英文目录后再修引用。更安全的做法是采用“英文物理目录 + 中文兼容入口 + 迁移映射清单 + 分批切换”的双轨方案。当前文档体系中存在大量中文相对路径、旧路径、缺失目标和归档引用；一次性重命名会把已有问题和迁移引入的问题混在一起，难以回滚与定位。
建议将代码/运行时根路径保持不变，只迁移 docs 内的活跃文档；不迁移 .workbuddy/memory、Git 元数据、源码目录、部署挂载路径、服务器路径和外部链接。
二、规范已规定但当前未完全执行
| 规范要求 | 当前证据 | 整改建议 |
|---|---|---|
| 已规定 §2.0 / §2.0.2：源码统一在 src/，配置集中管理，部署路径同步更新 | 根目录仍有旧 frontend-*，同时存在 src/frontend-*；根目录与 deploy-server 多套 Compose/部署事实源。 | 先锁定 src/ 为运行时唯一源；配置迁移单独立项，先做引用/挂载矩阵，再更新 Compose 和部署脚本。 |
| 已规定 §2.1/§2.2：文档按 01—08 类别边界组织 | docs 共有 432 个可解析文档/配置；根目录仍有 README、CHANGELOG、overview、openapi 等多种文档；部分旧目录引用仍存在。 | 将根目录文档按项目入口/治理/接口产物/历史分类；先建立权威入口。 |
| 已规定 §2.3、§3.1：命名规则与文件名/内容版本一致 | 检测到 12 个文件名版本与头部版本不一致候选，例如技术方案 v1.4 文件头 v1.3、多个 v1.0 文件头为 v1.1/v1.2。 | 先生成确认表；确认后同步改文件名、头部版本和全部引用，旧版本按 .archive 规则保留。 |
| 已规定 §4.2/§4.3/§8.3：变更必须有版本号和变更记录，阶段产物齐全 | 118 个 Markdown 文件没有检测到标准版本字段候选。README 仍为 2026-06-03，状态与当前实现有滞后。 | 对活跃文档补齐头部与变更记录；历史归档不强行回填，增加历史文档说明和索引。 |
| 已规定 §5.1/§5.2/§13.3：引用链完整，移动后更新所有引用并验证死链接 | 检测到 97 个引用目标缺失候选，包含旧目录、历史文档、自身示例或跨根路径引用。 | 先区分真实死链、历史文档死链、模板示例和扫描误报；迁移前建立路径映射表，迁移后跑链接检查。 |
| 已规定 §2.5/§13.5：归档前分拣；仍被引用的不得直接归档 | 08-历史归档内仍有文档包含指向其他旧文档的引用，且部分活跃文档仍引用旧目录。 | 采用引用扫描、活跃/历史判定、归档标记、索引更新四步，不做目录级盲搬。 |
| 已规定 §4.3/§9/§15：新增、变更、上线需按 PRD、技术、测试、任务、运维等链路留痕 | 能确认存在多类文档，但无法证明每个功能/部署批次都完整具备三件套或七件套。 | 为每个 REQ 建关联矩阵；上线前将文档完备性纳入检查清单和发布门禁。 |
三、现有规范未规定或规定不足的事项
| 规范缺口 | 建议新增规则 |
|---|---|
| 规范缺口 英文路径/跨平台路径策略 | 规定物理目录可使用 ASCII 英文名；文档显示名可保留中文；所有链接使用相对路径；禁止依赖 Windows 盘符、中文绝对路径或特定编辑器 URI。 |
| 规范缺口 迁移安全与回滚 | 迁移前生成 manifest、SHA-256、引用图、Git 状态快照和外部备份；迁移后通过链接、哈希、构建/部署回归；保留旧路径兼容窗口。 |
| 规范缺口 文档与代码的边界 | 明确 docs 只保存可审阅文档，构建产物、压缩包、截图批次、数据库分片、运行日志和个人工作区不入文档仓库；制品使用独立制品库。 |
| 规范缺口 敏感信息管理 | secret scan 覆盖源码、文档、历史归档、备份和压缩包；默认密码不能出现在 Compose 默认值、示例脚本和文档中；发现即按泄露处理并轮换。 |
| 规范缺口 文档质量门禁 | 活跃文档必须具备版本/日期/状态/作者/关联文档；每个 REQ 必须具备关联矩阵；死链、版本错配、重复权威文档不得进入发布分支。 |
| 规范缺口 历史归档引用策略 | 归档文件内部可保留历史引用，但必须标明历史引用、不作为当前事实源；活跃文档不得依赖归档文档作为唯一依据。 |
| 规范缺口 Git 与发布提交规则 | 补充 pre-commit/CI 强制校验、分支保护、工作树冻结、远端备份和灾难恢复演练。 |
四、英文文档路径方案对比
| 方案 | 做法 | 优点 | 风险 | 建议 |
|---|---|---|---|---|
| A：原地改名 | 直接把 docs 子目录改成英文。 | 简洁。 | 一次性影响大量链接、脚本和人员习惯；难以区分原有问题和迁移问题。 | 不建议第一步。 |
| B：复制切换 | 复制到 docs-en/，修正引用后切主路径。 | 回滚简单。 | 双份权威文档，容易内容漂移。 | 只适合短期验证。 |
| C：英文物理目录 + 中文兼容入口 | 建立 documentation/ 作为唯一物理目录；旧 docs/ 暂保留兼容说明。 | 安全、可回滚。 | 需要维护映射和兼容期。 | 推荐。 |
| D：独立文档仓库 | 文档进入独立英文命名仓库。 | 边界清晰。 | 增加权限、版本协同和链接管理复杂度。 | 中长期可选。 |
五、推荐目标结构
documentation/ # 英文物理目录，唯一文档源
├── 00-governance/ # 规范、版本索引、整改记录
├── 01-product/ # PRD、原型、产品设计
├── 02-technical/ # 架构、接口、实现配置、重构
├── 03-testing/ # 测试规范、用例、报告、缺陷
├── 04-operations/ # 部署、监控、运维手册、发布
├── 05-operations-business/ # 用户手册、运营报告
├── 06-security/ # 安全审计、集成安全分析
├── 07-project-management/ # 任务、计划、看板、日报
└── 08-archive/ # 仅无活跃引用的历史留痕
# 根目录保留
README.md CHANGELOG.md CONTRIBUTING.md documentation/ src/ scripts/ configs/重要：“英文路径”不等于强制把所有文件名也翻译成英文。建议优先英文目录、保留中文业务文件名，以降低 REQ 编号、中文功能名和审阅习惯的迁移风险。
六、安全迁移计划
- 阶段 1：冻结与授权：暂停大规模文档重命名，确认未提交修改/未跟踪文件归属，创建专用迁移分支，范围仅限 docs 活跃文档。
- 阶段 2：只读盘点：生成 document-manifest.csv（旧路径、新路径、类型、版本、状态、大小、SHA-256、是否被引用、敏感候选），生成引用图和 REQ 关联矩阵。
- 阶段 3：外部备份：将原 docs 备份到项目外受控位置，备份后复核 SHA-256；敏感文件必须排除或加密限权。
- 阶段 4：建立英文目录副本：复制到 documentation/，只修改路径引用，不同时做内容改写、版本升级或归档判断。
- 阶段 5：引用与工具适配：更新 Markdown 相对引用、MkDocs、文档发布脚本、审计脚本、CI、README；代码运行时路径保持不变。
- 阶段 6：四类验证：文件数量与哈希、Markdown/HTML 链接、文档构建预览、Git diff/secret scan/发布脚本 dry-run；任一失败即停止。
- 阶段 7：兼容切换：将 docs/ 改为兼容入口或迁移说明，保留版本窗口；确认入口全切至 documentation/后再人工批准移除旧目录。
- 阶段 8：收口：更新规范 v1.14，补充英文路径、迁移和质量门禁；在 00-document-normalization-log.md 记录整改，提交 PR 保留回滚点。
七、迁移前安全门槛
- 不得使用 git add -A、git clean -fd、批量删除或不可逆覆盖。
- 先备份、后复制；先复制、后切换；先验证、后清理。
- 原目录在验证完成前保留；新文档只允许写入新物理目录，避免双向漂移。
- 不触碰服务器、Nginx、前端/后端 src 和部署挂载路径。
- 敏感信息只做候选清单和脱敏验证，不把真实凭据写入报告或 manifest。
八、建议的决策顺序
- 批准“只迁移 docs、代码路径不动”。
- 批准目标目录名称：推荐 documentation/。
- 确认 docs/兼容入口和兼容期结束条件。
- 确认迁移分支和外部备份位置。
- 完成盘点后，再决定旧文档、重复文档和归档物的清理；本报告不执行清理。