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>
|
|||
|
|
├── 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>
|