docs: 移动蓝绿部署指南到 troubleshooting 目录
This commit is contained in:
@@ -61,7 +61,7 @@ docs/
|
||||
|
||||
| 目录/文档 | 说明 |
|
||||
|------|------|
|
||||
| `00-系统架构设计文档-v1.0.md` | 系统架构设计(v1.0) |
|
||||
| `00-系统架构设计文档-v1.3.md` | 系统架构设计(v1.3) |
|
||||
| `01-ADRs-架构决策/` | 4 | 架构决策记录 |
|
||||
| `02-技术方案/` | 5 | 技术方案文档 |
|
||||
| `03-技术分析/` | 3 | 技术分析报告 |
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
|
||||
> **📖 关联文档**:
|
||||
> - [README.md](../README.md) — 项目快速入门
|
||||
> - [01-项目总览与部署手册.md](./01-项目总览与部署手册.md) — 完整架构设计
|
||||
> - [01-项目总览与部署手册](./01-项目总览与部署手册-20260704.md) — 完整架构设计
|
||||
> - [CHANGELOG.md](../CHANGELOG.md) — 版本变更概览
|
||||
> - [docs/archive/](./archive/) — 历史版本详情
|
||||
|
||||
@@ -483,11 +483,11 @@ docker compose logs nginx > /tmp/incident-nginx.log
|
||||
|
||||
| 文档 | 说明 |
|
||||
|------|------|
|
||||
| `docs/01-项目总览与部署手册.md` | 完整项目背景与架构设计 |
|
||||
| `docs/01-项目总览/01-项目总览与部署手册-20260704.md` | 完整项目背景与架构设计 |
|
||||
| `docs/RELEASE_NOTES_v0.7.1.md` | 版本发布说明 |
|
||||
| `docs/SOPs/SOP-004-应急响应.md` | 详细应急响应流程 |
|
||||
| `docs/deploy/快速诊断-500-错误.md` | 500 错误排查指南 |
|
||||
| `docs/IT服务台部署修复记录-2026-06-13.md` | 历史修复记录 |
|
||||
| `docs/09-部署运维/deploy/04-部署修复记录-20260613.md` | 历史修复记录 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -581,7 +581,7 @@ docker compose down # 停止新系统所有容器
|
||||
| 阶段 | 状态 | 产出 |
|
||||
|------|------|------|
|
||||
| PRD | ✅ 完成 | `PRD.md` — 31 需求(P0/P1/P2),7 用户故事 |
|
||||
| 架构设计 | ✅ 完成 | `docs/ARCHITECTURE.md` — 9 表 DDL,7 API 组,4 时序图,5 任务分解 |
|
||||
| 架构设计 | ✅ 完成 | `docs/03-技术架构/00-系统架构设计文档-v1.3.md` — 9 表 DDL,7 API 组,4 时序图,5 任务分解 |
|
||||
| T01 项目脚手架 | ✅ 完成 | 57 文件 — docker-compose, nginx, .env, 后端/前端骨架 |
|
||||
| T02 后端核心服务 | ✅ 完成 | 16 文件 — 企微加解密, 消息路由, 评分, 会话, 趣味话术, 7 API 路由 |
|
||||
| T03 坐席工作台 | ✅ 完成 | 25 文件 — 三栏布局, 会话管理, 聊天, AI助手面板(5Tab) |
|
||||
|
||||
@@ -9,7 +9,7 @@
|
||||
| 阶段 | 状态 | 产出 |
|
||||
|------|------|------|
|
||||
| PRD | ✅ 完成 | `PRD.md` — 31 需求(P0/P1/P2),7 用户故事 |
|
||||
| 架构设计 | ✅ 完成 | `docs/ARCHITECTURE.md` — 9 表 DDL,7 API 组,4 时序图,5 任务分解 |
|
||||
| 架构设计 | ✅ 完成 | `docs/03-技术架构/00-系统架构设计文档-v1.3.md` — 9 表 DDL,7 API 组,4 时序图,5 任务分解 |
|
||||
| T01 项目脚手架 | ✅ 完成 | 57 文件 — docker-compose, nginx, .env, 后端/前端骨架 |
|
||||
| T02 后端核心服务 | ✅ 完成 | 16 文件 — 企微加解密, 消息路由, 评分, 会话, 趣味话术, 7 API 路由 |
|
||||
| T03 坐席工作台 | ✅ 完成 | 25 文件 — 三栏布局, 会话管理, 聊天, AI助手面板(5Tab) |
|
||||
|
||||
@@ -0,0 +1,105 @@
|
||||
# 文档关联修复报告
|
||||
|
||||
> **日期**: 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-历史归档/` 下多个文档仍含旧路径引用,作为历史快照保留,不修改 |
|
||||
Reference in New Issue
Block a user