文档关联修复报告

日期: 2026-07-05 | 维护人: 助理 | 范围: docs/ 目录重组后的断链修复

一、背景

2026-07-04 对 docs/ 执行了目录重组：从扁平结构迁移为 01-项目总览 ~ 11-历史归档 数字编号子目录，新建权威索引 01-项目总览/00-索引-20260704.md。但三处"关联"未同步更新，导致断链：

mkdocs.yml nav 导航仍指向旧的根级扁平路径
文档间 Markdown 交叉引用未更新
巡检自动化任务引用的看板路径已失效

二、修复清单

2.1 mkdocs.yml nav 重写（9 处断链 + 5 份新增）

nav 旧路径	新路径	处理
`01-项目总览与部署手册.md`	`01-项目总览/01-项目总览与部署手册-20260704.md`	更新
`ARCHITECTURE.md`	`03-技术架构/00-系统架构设计文档-v1.3.md`	指向新版
`ARCHITECTURE-admin.md`	（无新版，已归档）	移除
`DEPLOY-QUICK-v0.7.0.md`	`09-部署运维/deploy/10-一键部署操作包-v0.7.0.md`	指向新版
`DEPLOY-LOGIN-MIGRATION-v0.7.0.md`	（已过时归档）	移除
`NAS部署指南.md`	`09-部署运维/deploy/09-NAS部署指南-群晖Cloudflare.md`	更新
`OTP二次验证实现.md`	`09-部署运维/deploy/06-OTP二次验证实现.md`	更新
`IT服务台部署修复记录-2026-06-13.md`	`09-部署运维/deploy/04-部署修复记录-20260613.md`	更新
`E2E-CHECKLIST-v0.7.0.md`	`06-测试质量/testing-测试/E2E-CHECKLIST-v0.7.0.md`	更新

新增纳入 nav 的核心文档：

01-项目总览/00-索引-20260704.md（文档索引）
01-项目总览/01-智能IT服务系统运维手册-20260704.md（运维手册）
02-产品需求/02-产品需求文档PRD-v1.2-20260704.md（PRD v1.2）
10-项目管理/05-项目状态看板/01-项目状态看板.md（项目状态看板）
10-项目管理/01-任务总索引.md、10-项目管理/02-风险跟踪表.md

2.2 文档间交叉引用修复（11 处）

文件	位置	旧引用	新引用
`01-智能IT服务系统运维手册-20260704.md`	行8	`./01-项目总览与部署手册.md`	`./01-项目总览与部署手册-20260704.md`
同上	行486	`docs/01-项目总览与部署手册.md`	`docs/01-项目总览/01-项目总览与部署手册-20260704.md`
同上	行490	`docs/IT服务台部署修复记录-2026-06-13.md`	`docs/09-部署运维/deploy/04-部署修复记录-20260613.md`
`01-项目总览与部署手册-20260704.md`	行584	`docs/ARCHITECTURE.md`	`docs/03-技术架构/00-系统架构设计文档-v1.3.md`
`04-开发交付概览.md`	行12	`docs/ARCHITECTURE.md`	`docs/03-技术架构/00-系统架构设计文档-v1.3.md`
`技术分析-架构消息知识库迭代.md`	行195	`01-项目总览与部署手册.md`	`01-项目总览/01-项目总览与部署手册-20260704.md`
同上	行655	`ARCHITECTURE.md` / `PRD.md`	新架构路径 / 新PRD路径
`01-项目状态看板.md`	行74	`docs/DEPLOY-QUICK-v0.7.0.md` + `docs/E2E-CHECKLIST-v0.7.0.md`	新部署路径 + 新E2E路径
`10-一键部署操作包-v0.7.0.md`	行215	`docs/E2E-CHECKLIST-v0.7.0.md`	`docs/06-测试质量/testing-测试/E2E-CHECKLIST-v0.7.0.md`
`02-产品需求文档PRD-v1.2-20260704.md`	行2457	`docs/ARCHITECTURE.md`	`docs/03-技术架构/00-系统架构设计文档-v1.3.md`
同上	行2458	`docs/小组任务书/任务执行状态看板.md`	`docs/10-项目管理/05-项目状态看板/01-项目状态看板.md`

保留未改：

目录树展示（├── ARCHITECTURE.md 等）—— 历史结构快照，保留以保真
03-项目任务状态报告.md 中"#4 更新ARCHITECTURE.md"等历史任务标题 —— 历史任务记录

2.3 索引版本号修正

01-项目总览/00-索引-20260704.md 第64行：架构文档版本号 v1.0 → v1.3（与实际文件名一致）。

2.4 巡检自动化任务适配

automation-1782986180887（IT服务台任务巡检-早班，每日 09:30）：

项	旧	新
数据源路径	`docs\小组任务书\任务执行状态看板.md`	`docs/10-项目管理/05-项目状态看板/01-项目状态看板.md`
巡检逻辑	A/B/C 三组任务、🟢可立即启动/⏳等待中/依赖/预计完成日期	P0必做/P1重要/等用户决策/进行中
输出格式	小组进度（A组x/16 等）	全局状态（P0/P1/等决策计数 + 最近完成）

三、关键发现

3.1 巡检数据源从未存在

巡检自动化任务自创建起所依赖的"任务执行状态看板.md"及整个小组任务书体系（A组认证加固16项 / B组消息系统16项 / C组AI与数据19项）从未被实际创建——仅在归档的"文档分类与清理报告"中作为"推荐结构"出现。这意味着该每日早班巡检自始至终都在尝试读取不存在的文件，每天必然失败。

经与用户确认，已将巡检适配为基于现有"项目状态看板"的状态巡检。

3.2 索引与实际存在版本号偏差

权威索引 00-索引-20260704.md 记录架构文档为 v1.0，实际文件为 00-系统架构设计文档-v1.3.md。已修正。

四、验证建议

mkdocs 站点验证：执行 mkdocs serve 预览，确认 nav 所有条目可正常跳转
交叉引用验证：在 mkdocs 构建时检查是否有 broken link 警告
巡检验证：等待次日 09:30 自动触发，确认巡检报告正常生成

五、未处理事项（待后续决策）

事项	说明
项目根目录 README.md 缺失	原项目根目录 `README.md`（7.4KB 项目说明）在 2026-07-04 文档重组时已删除，未迁移到新结构。新入口为 `01-项目总览/01-项目总览与部署手册-20260704.md`
`01-智能IT服务系统运维手册` 行7/10	引用 `../README.md` 和 `./archive/`，docs/ 根目录无 README，archive 实为 11-历史归档。非本次旧路径范围，暂未处理
`01-项目总览与部署手册` 行645-717	历史目录树展示，保留原样。如需更新为新结构可后续单独处理
归档文档内的旧路径	`11-历史归档/` 下多个文档仍含旧路径引用，作为历史快照保留，不修改

6.2 KiB Raw Permalink Blame History Unescape Escape