Simon
106 lines
6.2 KiB
Markdown
106 lines
6.2 KiB
Markdown
# 文档关联修复报告
|
||
|
||
> **日期**: 2026-07-05 | **维护人**: 助理 | **范围**: docs/ 目录重组后的断链修复
|
||
|
||
---
|
||
|
||
## 一、背景
|
||
|
||
2026-07-04 对 `docs/` 执行了目录重组：从扁平结构迁移为 `01-项目总览` ~ `11-历史归档` 数字编号子目录，新建权威索引 `01-项目总览/00-索引-20260704.md`。但三处"关联"未同步更新，导致断链：
|
||
|
||
1. `mkdocs.yml` nav 导航仍指向旧的根级扁平路径
|
||
2. 文档间 Markdown 交叉引用未更新
|
||
3. 巡检自动化任务引用的看板路径已失效
|
||
|
||
---
|
||
|
||
## 二、修复清单
|
||
|
||
### 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`。已修正。
|
||
|
||
---
|
||
|
||
## 四、验证建议
|
||
|
||
1. **mkdocs 站点验证**：执行 `mkdocs serve` 预览，确认 nav 所有条目可正常跳转
|
||
2. **交叉引用验证**：在 mkdocs 构建时检查是否有 broken link 警告
|
||
3. **巡检验证**：等待次日 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-历史归档/` 下多个文档仍含旧路径引用，作为历史快照保留，不修改 |
|