Simon
13 lines
12 KiB
HTML
13 lines
12 KiB
HTML
<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><title>项目文档治理与英文路径迁移计划</title><style>body{font-family:Arial,"Microsoft YaHei",sans-serif;background:#f6f8fa;color:#172033;margin:0}.wrap{max-width:1220px;margin:auto;padding:28px}.hero,.section{background:#fff;border:1px solid #dfe5ec;border-radius:12px;padding:22px;margin:16px 0}.hero{border-left:6px solid #07c160}.muted{color:#667085}.grid{display:grid;grid-template-columns:repeat(4,1fr);gap:12px;margin:16px 0}.stat{background:#fff;border:1px solid #e5e7eb;border-radius:10px;padding:14px}.stat b{display:block;font-size:28px}.section h2{margin-top:0}table{width:100%;border-collapse:collapse}th,td{text-align:left;vertical-align:top;border-bottom:1px solid #edf0f2;padding:10px}th{background:#f8fafc}.tag{display:inline-block;border-radius:999px;padding:3px 9px;font-weight:700;font-size:12px}.req{background:#fee4e2;color:#b42318}.new{background:#e6f4ea;color:#137333}li{margin:8px 0}pre{background:#172033;color:#f8fafc;padding:16px;border-radius:8px;overflow:auto}code{background:#f2f4f7;padding:2px 4px;border-radius:4px}pre code{background:none;padding:0}</style></head><body><main class="wrap"><section class="hero"><h1>项目文档治理与英文路径迁移计划</h1><p class="muted">依据：docs/00-产品开发流程与文档管理规范.md v1.13、outputs/itdesk-project-folder-audit-20260809.html，以及对 docs 目录的只读规则检查。</p><p class="muted">本报告是决策和实施计划，不执行迁移、不修改原文档、不删除文件。</p></section><div class="grid"><div class="stat"><span class="muted">可解析文档/配置</span><b>432</b></div><div class="stat"><span class="muted">缺少规范头部候选</span><b>118</b></div><div class="stat"><span class="muted">引用目标缺失候选</span><b>97</b></div><div class="stat"><span class="muted">文件名/内容版本不一致候选</span><b>12</b></div></div><section class="section"><h2>一、结论</h2><p>建议迁移，但<strong>不建议把中文目录直接整体重命名为英文目录后再修引用</strong>。更安全的做法是采用“英文物理目录 + 中文兼容入口 + 迁移映射清单 + 分批切换”的双轨方案。当前文档体系中存在大量中文相对路径、旧路径、缺失目标和归档引用；一次性重命名会把已有问题和迁移引入的问题混在一起，难以回滚与定位。</p><p>建议将<strong>代码/运行时根路径保持不变</strong>，只迁移 docs 内的活跃文档；不迁移 .workbuddy/memory、Git 元数据、源码目录、部署挂载路径、服务器路径和外部链接。</p></section><section class="section"><h2>二、规范已规定但当前未完全执行</h2><table><thead><tr><th>规范要求</th><th>当前证据</th><th>整改建议</th></tr></thead><tbody><tr><td><span class="tag req">已规定</span><br><strong>§2.0 / §2.0.2：源码统一在 src/，配置集中管理，部署路径同步更新</strong></td><td>根目录仍有旧 frontend-*，同时存在 src/frontend-*；根目录与 deploy-server 多套 Compose/部署事实源。</td><td>先锁定 src/ 为运行时唯一源；配置迁移单独立项，先做引用/挂载矩阵，再更新 Compose 和部署脚本。</td></tr><tr><td><span class="tag req">已规定</span><br><strong>§2.1/§2.2：文档按 01—08 类别边界组织</strong></td><td>docs 共有 432 个可解析文档/配置；根目录仍有 README、CHANGELOG、overview、openapi 等多种文档；部分旧目录引用仍存在。</td><td>将根目录文档按项目入口/治理/接口产物/历史分类；先建立权威入口。</td></tr><tr><td><span class="tag req">已规定</span><br><strong>§2.3、§3.1：命名规则与文件名/内容版本一致</strong></td><td>检测到 12 个文件名版本与头部版本不一致候选，例如技术方案 v1.4 文件头 v1.3、多个 v1.0 文件头为 v1.1/v1.2。</td><td>先生成确认表；确认后同步改文件名、头部版本和全部引用，旧版本按 .archive 规则保留。</td></tr><tr><td><span class="tag req">已规定</span><br><strong>§4.2/§4.3/§8.3：变更必须有版本号和变更记录，阶段产物齐全</strong></td><td>118 个 Markdown 文件没有检测到标准版本字段候选。README 仍为 2026-06-03，状态与当前实现有滞后。</td><td>对活跃文档补齐头部与变更记录；历史归档不强行回填，增加历史文档说明和索引。</td></tr><tr><td><span class="tag req">已规定</span><br><strong>§5.1/§5.2/§13.3：引用链完整，移动后更新所有引用并验证死链接</strong></td><td>检测到 97 个引用目标缺失候选，包含旧目录、历史文档、自身示例或跨根路径引用。</td><td>先区分真实死链、历史文档死链、模板示例和扫描误报；迁移前建立路径映射表，迁移后跑链接检查。</td></tr><tr><td><span class="tag req">已规定</span><br><strong>§2.5/§13.5：归档前分拣；仍被引用的不得直接归档</strong></td><td>08-历史归档内仍有文档包含指向其他旧文档的引用，且部分活跃文档仍引用旧目录。</td><td>采用引用扫描、活跃/历史判定、归档标记、索引更新四步，不做目录级盲搬。</td></tr><tr><td><span class="tag req">已规定</span><br><strong>§4.3/§9/§15：新增、变更、上线需按 PRD、技术、测试、任务、运维等链路留痕</strong></td><td>能确认存在多类文档，但无法证明每个功能/部署批次都完整具备三件套或七件套。</td><td>为每个 REQ 建关联矩阵；上线前将文档完备性纳入检查清单和发布门禁。</td></tr></tbody></table></section><section class="section"><h2>三、现有规范未规定或规定不足的事项</h2><table><thead><tr><th>规范缺口</th><th>建议新增规则</th></tr></thead><tbody><tr><td><span class="tag new">规范缺口</span><br><strong>英文路径/跨平台路径策略</strong></td><td>规定物理目录可使用 ASCII 英文名；文档显示名可保留中文；所有链接使用相对路径；禁止依赖 Windows 盘符、中文绝对路径或特定编辑器 URI。</td></tr><tr><td><span class="tag new">规范缺口</span><br><strong>迁移安全与回滚</strong></td><td>迁移前生成 manifest、SHA-256、引用图、Git 状态快照和外部备份；迁移后通过链接、哈希、构建/部署回归；保留旧路径兼容窗口。</td></tr><tr><td><span class="tag new">规范缺口</span><br><strong>文档与代码的边界</strong></td><td>明确 docs 只保存可审阅文档，构建产物、压缩包、截图批次、数据库分片、运行日志和个人工作区不入文档仓库；制品使用独立制品库。</td></tr><tr><td><span class="tag new">规范缺口</span><br><strong>敏感信息管理</strong></td><td>secret scan 覆盖源码、文档、历史归档、备份和压缩包；默认密码不能出现在 Compose 默认值、示例脚本和文档中；发现即按泄露处理并轮换。</td></tr><tr><td><span class="tag new">规范缺口</span><br><strong>文档质量门禁</strong></td><td>活跃文档必须具备版本/日期/状态/作者/关联文档；每个 REQ 必须具备关联矩阵；死链、版本错配、重复权威文档不得进入发布分支。</td></tr><tr><td><span class="tag new">规范缺口</span><br><strong>历史归档引用策略</strong></td><td>归档文件内部可保留历史引用，但必须标明历史引用、不作为当前事实源；活跃文档不得依赖归档文档作为唯一依据。</td></tr><tr><td><span class="tag new">规范缺口</span><br><strong>Git 与发布提交规则</strong></td><td>补充 pre-commit/CI 强制校验、分支保护、工作树冻结、远端备份和灾难恢复演练。</td></tr></tbody></table></section><section class="section"><h2>四、英文文档路径方案对比</h2><table><thead><tr><th>方案</th><th>做法</th><th>优点</th><th>风险</th><th>建议</th></tr></thead><tbody><tr><td>A：原地改名</td><td>直接把 docs 子目录改成英文。</td><td>简洁。</td><td>一次性影响大量链接、脚本和人员习惯；难以区分原有问题和迁移问题。</td><td>不建议第一步。</td></tr><tr><td>B：复制切换</td><td>复制到 docs-en/，修正引用后切主路径。</td><td>回滚简单。</td><td>双份权威文档，容易内容漂移。</td><td>只适合短期验证。</td></tr><tr><td>C：英文物理目录 + 中文兼容入口</td><td>建立 documentation/ 作为唯一物理目录；旧 docs/ 暂保留兼容说明。</td><td>安全、可回滚。</td><td>需要维护映射和兼容期。</td><td>推荐。</td></tr><tr><td>D：独立文档仓库</td><td>文档进入独立英文命名仓库。</td><td>边界清晰。</td><td>增加权限、版本协同和链接管理复杂度。</td><td>中长期可选。</td></tr></tbody></table></section><section class="section"><h2>五、推荐目标结构</h2><pre><code>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/</code></pre><p><strong>重要：</strong>“英文路径”不等于强制把所有文件名也翻译成英文。建议优先英文目录、保留中文业务文件名，以降低 REQ 编号、中文功能名和审阅习惯的迁移风险。</p></section><section class="section"><h2>六、安全迁移计划</h2><ol><li><strong>阶段 1：</strong>冻结与授权：暂停大规模文档重命名，确认未提交修改/未跟踪文件归属，创建专用迁移分支，范围仅限 docs 活跃文档。</li><li><strong>阶段 2：</strong>只读盘点：生成 document-manifest.csv（旧路径、新路径、类型、版本、状态、大小、SHA-256、是否被引用、敏感候选），生成引用图和 REQ 关联矩阵。</li><li><strong>阶段 3：</strong>外部备份：将原 docs 备份到项目外受控位置，备份后复核 SHA-256；敏感文件必须排除或加密限权。</li><li><strong>阶段 4：</strong>建立英文目录副本：复制到 documentation/，只修改路径引用，不同时做内容改写、版本升级或归档判断。</li><li><strong>阶段 5：</strong>引用与工具适配：更新 Markdown 相对引用、MkDocs、文档发布脚本、审计脚本、CI、README；代码运行时路径保持不变。</li><li><strong>阶段 6：</strong>四类验证：文件数量与哈希、Markdown/HTML 链接、文档构建预览、Git diff/secret scan/发布脚本 dry-run；任一失败即停止。</li><li><strong>阶段 7：</strong>兼容切换：将 docs/ 改为兼容入口或迁移说明，保留版本窗口；确认入口全切至 documentation/后再人工批准移除旧目录。</li><li><strong>阶段 8：</strong>收口：更新规范 v1.14，补充英文路径、迁移和质量门禁；在 00-document-normalization-log.md 记录整改，提交 PR 保留回滚点。</li></ol></section><section class="section"><h2>七、迁移前安全门槛</h2><ul><li>不得使用 git add -A、git clean -fd、批量删除或不可逆覆盖。</li><li>先备份、后复制；先复制、后切换；先验证、后清理。</li><li>原目录在验证完成前保留；新文档只允许写入新物理目录，避免双向漂移。</li><li>不触碰服务器、Nginx、前端/后端 src 和部署挂载路径。</li><li>敏感信息只做候选清单和脱敏验证，不把真实凭据写入报告或 manifest。</li></ul></section><section class="section"><h2>八、建议的决策顺序</h2><ol><li>批准“只迁移 docs、代码路径不动”。</li><li>批准目标目录名称：推荐 documentation/。</li><li>确认 docs/兼容入口和兼容期结束条件。</li><li>确认迁移分支和外部备份位置。</li><li>完成盘点后，再决定旧文档、重复文档和归档物的清理；本报告不执行清理。</li></ol></section></main></body></html> |