chore: 整理项目结构，清理归档文件，更新部署配置

2026-07-04 21:01:39 +08:00
parent 8bd4ab0366
commit 64ff1bf7d5
508 changed files with 43575 additions and 14129 deletions
@@ -0,0 +1,96 @@
+# SOP-001: Gitea 部署标准作业流程
+
+**适用**: 新机器 / NAS 迁移 / Gitea 重建
+**耗时**: 30-45 分钟
+**关联**: [[Gitea部署指南]] / [[ADR-001]]
+
+---
+
+## 1. 前置检查
+
+```bash
+# 1.1 NAS 可达
+ping 100.85.152.112
+
+# 1.2 SSH 通
+ssh simon@100.85.152.112
+
+# 1.3 Tailscale 状态
+sudo tailscale status
+
+# 1.4 端口 8418 未占
+sudo lsof -i :8418
+```
+
+## 2. 装 Gitea 套件
+
+1. DSM → 套件中心
+2. 搜 `Gitea` → 安装
+3. 装好跳 `http://100.85.152.112:8418/`
+
+## 3. 初始化
+
+1. 创管理员:
+   - 用户名: `simon`
+   - 邮箱: 你的
+   - 密码: 强密码(≥16 位)
+2. 数据库: 选 **SQLite3**
+3. 站点名: `企微 IT 智能服务台 Git`
+4. 立即登录
+
+## 4. 创仓 + token
+
+1. 创仓 `wecom_it_smart_desk`(不勾 README 初始化)
+2. 创 simon access token(`simon-admin`)
+3. 创 workbuddy-claude user + token(`claude-push`)
+
+## 5. 配 Tailscale Funnel
+
+```bash
+sudo tailscale funnel --bg 8418
+# 验证
+curl -I https://ds923plus.tail58d872.ts.net/
+```
+
+## 6. 配分支保护
+
+见 [[ADR-001]] §5 + `scripts/branch-protection.sh`(待写)
+
+## 7. 部署备份
+
+```bash
+# 推备份脚本
+scp scripts/backup-gitea.sh simon@100.85.152.112:/volume1/docker/wecom-it-desk/scripts/
+
+# 配 cron
+ssh simon@100.85.152.112
+sudo crontab -e
+# 加: 0 3 * * * /volume1/docker/wecom-it-desk/scripts/backup-gitea.sh
+```
+
+## 8. 本地仓接入
+
+```bash
+cd D:\资料\03-项目开发\wecom_it_smart_desk
+git remote add origin https://simon@ds923plus.tail58d872.ts.net/simon/wecom_it_smart_desk.git
+git push -u origin main  # 弹窗输 token
+```
+
+## 9. 验证清单
+
+- [ ] Gitea Web UI 正常
+- [ ] Funnel 域名正常
+- [ ] 创仓 + token 完成
+- [ ] 分支保护已配
+- [ ] 备份 cron 已配
+- [ ] 本地 push 成功
+- [ ] workbuddy-claude user 已创 + token 已配
+
+## 10. 出错回滚
+
+| 现象 | 解决 |
+|---|---|
+| 8418 端口冲突 | Docker 版用 3000 端口 |
+| SQLite 写失败 | 检查 `/volume1/@appdata/gitea` 权限 |
+| Funnel 域名不通 | `sudo tailscale funnel --bg 8418` 重试 |
+| 推 Gitea 401 | 清 wincred,重输 token |
@@ -0,0 +1,97 @@
+# SOP-002: Gitea 备份恢复标准作业流程
+
+**适用**: 数据丢失应急 / 误操作回滚 / 异地迁移
+**耗时**: 5-15 分钟
+**关联**: [[Gitea部署指南]] §6/§7
+
+---
+
+## 1. 备份策略
+
+| 项 | 值 | 备注 |
+|---|---|---|
+| 频率 | 每天 3 点 | cron |
+| 保留 | 7 天 | 默认 |
+| 路径 | `/volume1/backups/gitea/` | NAS 本地 |
+| 异地 | OSS / COS 推 | M-1 风险,待解决 |
+| 工具 | `scripts/backup-gitea.sh` | 已写 |
+
+## 2. 手动备份(应急)
+
+```bash
+ssh simon@100.85.152.112
+sudo bash /volume1/docker/wecom-it-desk/scripts/backup-gitea.sh
+```
+
+输出:
+```
+[INFO] === Gitea 备份开始 ===
+[OK] 备份配置 app.ini
+[OK] SQLite 热备完成
+[OK] 仓库 tar 完成
+[INFO] === 备份完成 ===
+[OK] 最终备份: gitea-backup-20260615-030000.tar.gz
+```
+
+## 3. 列出可用备份
+
+```bash
+ls -lh /volume1/backups/gitea/
+# gitea-backup-20260614-180000.tar.gz  500M
+# gitea-backup-20260613-180000.tar.gz  495M
+# gitea-backup-20260612-180000.tar.gz  490M
+```
+
+## 4. 恢复到 latest
+
+```bash
+sudo bash /volume1/docker/wecom-it-desk/scripts/backup-gitea.sh --restore latest
+```
+
+**会做**:
+1. 停 Gitea 套件
+2. 解压备份
+3. 覆盖 app.ini / SQLite / repos
+4. 启动 Gitea 套件
+
+⚠️ 5 秒倒计时,Ctrl+C 取消
+
+## 5. 恢复到指定时间
+
+```bash
+# 看时间戳
+ls /volume1/backups/gitea/ | grep gitea-backup
+# gitea-backup-20260614-180000.tar.gz
+
+# 恢复
+sudo bash /volume1/docker/wecom-it-desk/scripts/backup-gitea.sh --restore 20260614-180000
+```
+
+## 6. 验证恢复
+
+1. `http://100.85.152.112:8418/` → 登录 simon
+2. 选仓 → 看 commit 历史
+3. 验证仓裸仓库大小(`du -sh /volume1/@appdata/gitea/gitea/repos/`)
+4. 验证 LFS 数据
+
+## 7. 异地推 OSS(待配)
+
+```bash
+# NAS 装 rclone
+sudo apt install rclone  # 或 synology 套件版
+
+# 配 OSS
+rclone config
+# 选 aliyun OSS / 腾讯云 COS
+
+# 加 cron
+0 4 * * * rclone copy /volume1/backups/gitea/ remote:gitea-backup/ --include "gitea-backup-*.tar.gz"
+```
+
+## 8. 故障排查
+
+| 现象 | 原因 | 解决 |
+|---|---|---|
+| 备份文件大小 0 | SQLite .backup 失败 | 改用文件复制模式(脚本已支持) |
+| 恢复后启动失败 | 数据不一致 | 试更早的备份 |
+| LFS 数据丢 | 备份脚本漏 LFS | 升级脚本(已修) |
@@ -0,0 +1,134 @@
+# SOP-003: 推送评审标准作业流程
+
+**适用**: 任何 commit 推 Gitea / PR 评审 / workbuddy 推送
+**耗时**: 5-15 分钟
+**关联**: [[CONTRIBUTING]] / [[scripts/pre-commit-check.sh]] / [[风险跟踪表]] 第九/十/十一节
+
+---
+
+## 1. 推送前自检(4 件套)
+
+```bash
+cd D:\资料\03-项目开发\wecom_it_smart_desk
+
+# 必跑
+bash scripts/pre-commit-check.sh --branch
+
+# 严格模式(任何 warn 失败)
+bash scripts/pre-commit-check.sh --branch --strict
+```
+
+**通过标准**:
+- ✅ PASS ≥ 检查项数
+- ⚠️ WARN 看是否影响评审
+- ❌ FAIL 必修
+
+## 2. Commit 规范
+
+格式: `<type>(<scope>): <subject>`
+
+| type | 用途 |
+|---|---|
+| `feat` | 新功能 |
+| `fix` | Bug 修复 |
+| `refactor` | 重构(无新功能 / 无 Bug 修复) |
+| `docs` | 文档 |
+| `chore` | 构建/工具/依赖 |
+| `security` | 安全 |
+| `perf` | 性能 |
+| `test` | 测试 |
+
+**subject**: 中文,祈使句,≤50 字
+**body**: 详细说明,每行 ≤72 字
+**footer**: 关联 Issue / workbuddy 任务
+
+## 3. 推送流程
+
+### 3.1 workbuddy 推送
+
+1. workbuddy 客户端启动 → 读 `config.json` + `memory/`
+2. 接任务(W-1 / W-2 / ...)
+3. 写代码 → 本地 commit
+4. 推 `feature/xxx` 分支(不走 main,需 PR)
+5. 通知 Claude 评审
+
+### 3.2 simon 推送(自己改)
+
+1. 本地改 + commit
+2. 推 `feature/xxx` 分支
+3. Gitea Web 开 PR
+4. 自己 approve + merge(因 `block_admin_merge: false`)
+
+## 4. 评审流程
+
+### 4.1 Claude 评审(主)
+
+1. 收到 workbuddy 推送通知
+2. Read 文件 + diff
+3. 检查 4 件套
+4. 写评审报告 `docs/评审报告/workbuddy-{date}-{topic}.md`
+5. 评级:
+   - 🟢 通过 → 通知合并
+   - 🟡 留 P1/P2 修 → 评审报告列遗留
+   - 🔴 拒绝 → 评审报告列阻断
+
+### 4.2 simon 合并
+
+1. 评审通过 → Gitea Web 合并 PR
+2. 触发 Gitea Actions CI(待配)
+3. CI 绿 → 删 feature 分支
+
+## 5. 评审失败处理
+
+| 评级 | 处理 |
+|---|---|
+| 🟢 通过 | 合并 + 部署 |
+| 🟡 留 P1 | 合并 + 写遗留表 + workbuddy 下一轮修 |
+| 🔴 拒绝 | workbuddy 修 → 重新评审 |
+
+## 6. 评审报告格式
+
+`docs/评审报告/workbuddy-{YYYY-MM-DD}-{topic}.md`:
+
+```markdown
+# 评审: {topic}
+
+**推送日期**: {date}
+**评审日期**: {date}
+**评审人**: Claude
+**关联 PR**: feature/xxx → main
+**关联 commit**: N 个
+
+## ⭐ 一句话结论
+...
+
+## 📊 评审结果
+| # | 项 | 评级 | 备注 |
+|---|---|---|---|
+
+## ✅ 已正确完成
+...
+
+## 🟡 半成品(留 P2 优化)
+...
+
+## ❌ 错误
+...
+
+## 📁 变更清单(N commit)
+...
+
+## 🔄 下一轮任务清单
+...
+
+## 🔗 推 Gitea 状态
+- 远端分支: feature/xxx (HEAD = xxx)
+- 评审: ✅ 通过 / 🟡 通过 + 留 / 🔴 拒绝
+```
+
+## 7. 不允许
+
+- ❌ 跳过评审直推 main
+- ❌ 评审失败强行合并
+- ❌ 评审未消化前叠加新功能
+- ❌ 改评审报告原文(只加节)
@@ -0,0 +1,208 @@
+# SOP-004: 应急响应标准作业流程
+
+**适用**: P0 漏洞 / 数据丢失 / 服务中断 / 安全事件
+**响应时间**: 5 分钟响应 + 30 分钟止血 + 24 小时根因
+**关联**: [[风险跟踪表]] / [[CONTRIBUTING]] §紧急修复
+
+---
+
+## 1. 事件分级
+
+| 等级 | 场景 | 响应时间 |
+|---|---|---|
+| 🔴 **P0 紧急** | P0 鉴权漏洞 + 数据泄露 + 服务全停 | 5 min |
+| 🟠 **P1 高** | P1 功能故障 + 单服务降级 | 30 min |
+| 🟡 **P2 中** | P2 性能 / UI 问题 | 4 h |
+| 🟢 **P3 低** | 体验优化 | 1 周 |
+
+## 2. P0 应急流程(5 min 响应)
+
+### 2.1 立即止血
+
+1. **服务降级**:
+   - 关闭外网访问:`sudo iptables -A INPUT -p tcp --dport 8418 -j DROP`
+   - 或:套件中心停 Gitea
+   - 或:Nginx `deny all;`
+2. **停可疑服务**:
+   - 停后端:`docker compose stop backend`
+   - 停 WebSocket:`docker compose stop nginx`(整体停)
+3. **保留现场**:
+   - 不删任何文件
+   - 复制 log 到 `/tmp/incident-{timestamp}/`
+   - 截图
+
+### 2.2 通知
+
+1. 微信 / 电话通知项目负责人 宋献
+2. 邮件群发:`wecom-it-desk-incident@servyou-it.com`
+3. 建应急群
+
+### 2.3 临时回滚
+
+```bash
+# 1. 找上一个稳定版本
+git tag -l  # 看 release tag
+git log --oneline -20  # 看 commit 历史
+
+# 2. 回滚到上一个 commit
+git revert HEAD  # 生成新 commit 撤销
+# 或
+git reset --hard HEAD~1  # 强回滚(慎用)
+
+# 3. 强推(临时,需 admin 权限)
+git push -f origin main
+```
+
+## 3. 根因分析(24h 内)
+
+### 3.1 收集证据
+
+```bash
+# 后端日志
+docker logs backend --tail 1000 > /tmp/incident/backend.log
+
+# nginx 错误日志
+sudo cat /var/log/nginx/error.log > /tmp/incident/nginx-error.log
+
+# Gitea 日志
+sudo synopkg log Gitea > /tmp/incident/gitea.log
+```
+
+### 3.2 5 Why 分析
+
+```markdown
+# 5 Why 分析
+
+**事件**: 坐席登录无鉴权
+**Why 1**: agents.py login() 函数没用 Depends(get_current_*)
+**Why 2**: workbuddy 加新端点时没跑 pre-commit-check
+**Why 3**: pre-commit-check 不在 git commit hook 里
+**Why 4**: 没用 pre-commit 框架(只是脚本)
+**Why 5**: 流程规范没强制(评审可跳)
+
+**根因**: 流程规范未自动化
+**对策**: 加 pre-commit + Gitea Actions 强制
+```
+
+### 3.3 写事故报告
+
+`docs/事故报告/incident-{date}-{topic}.md`:
+
+```markdown
+# 事故报告: {topic}
+
+**日期**: {date}
+**等级**: 🔴 P0
+**响应人**: {name}
+**持续**: X 分钟
+
+## 1. 时序
+| 时刻 | 事件 |
+|---|---|
+
+## 2. 影响范围
+- 用户: X 人受影响
+- 数据: 是否泄露
+- 服务: 停 X 分钟
+
+## 3. 5 Why 根因
+...
+
+## 4. 修复 commit
+- {commit-hash}
+- {commit-message}
+
+## 5. 防止再发
+- [ ] 加 pre-commit hook
+- [ ] 加 Gitea Actions 强制
+- [ ] 更新风险跟踪表
+- [ ] 评审 SOP 更新
+```
+
+## 4. P1 应急流程(30 min 响应)
+
+### 4.1 评估
+
+- 是否影响生产用户?
+- 是否有降级方案?
+
+### 4.2 止血
+
+- 单服务降级(关问题服务,其它继续)
+- 临时禁用相关端点(nginx `location /api/v1/xxx { return 503; }`)
+
+### 4.3 修复
+
+- hotfix 分支(从 main 拉)
+- PR + 评审 + 合并 + 部署
+
+## 5. 数据丢失应急
+
+### 5.1 Gitea 数据丢失
+
+1. **别再操作** Gitea(避免覆盖)
+2. 跑 `scripts/backup-gitea.sh --restore latest`
+3. 验证:仓 commit 数 / token 列表
+4. 不行:试更早备份
+
+### 5.2 生产数据库丢失
+
+1. 立即停所有服务(避免写入)
+2. 看 PostgreSQL 数据目录:`/var/lib/postgresql/data`
+3. 走 PITR(Point In Time Recovery)
+4. 启用只读模式 + 通知用户
+
+## 6. 安全事件
+
+### 6.1 Token 泄露
+
+1. **立即撤销** token:
+   ```bash
+   curl -X DELETE -H "Authorization: token $ADMIN_TOKEN" \
+     "http://100.85.152.112:8418/api/v1/users/{username}/tokens"
+   ```
+2. 清 wincred 缓存
+3. 创新 token + 配新凭据
+4. 改所有引用旧 token 的脚本/配置
+5. 评审日志:谁访问过 / 推过什么
+
+### 6.2 入侵检测
+
+1. 看 `auth.log` / `nginx-access.log` / `backend.log`
+2. 找异常 IP / 时间 / 路径
+3. 封 IP:`sudo iptables -A INPUT -s {ip} -j DROP`
+4. 改所有密码 / 凭据
+5. 走事件调查流程
+
+## 7. 通讯模板
+
+### 7.1 启动应急
+
+```
+【应急启动】{事件简述}
+等级: 🔴 P0
+影响: {用户/数据/服务}
+已开始止血:{动作}
+请相关人:{人名} 立即响应
+群: {微信群名}
+```
+
+### 7.2 解决通知
+
+```
+【已解决】{事件简述}
+持续: X 分钟
+修复: {commit-hash}
+根因: {5 Why 结论}
+防止再发: {动作}
+报告: docs/事故报告/{file}.md
+```
+
+## 8. 联系
+
+| 角色 | 联系人 |
+|---|---|
+| 项目负责人 | 宋献(企业微信 / 手机) |
+| 运维 | IT 支持组 |
+| Gitea | 群晖技术支持（部署在公司内网服务器） |
+| Tailscale | tailscale.com/support |
@@ -0,0 +1,343 @@
+# 项目管理文档管理规范
+
+> **版本**: v1.0 | **日期**: 2026-07-04 | **状态**: 正式发布
+
+---
+
+## 1. 目的与适用范围
+
+### 1.1 目的
+
+规范 IT 智能服务台项目的文档管理流程，确保文档的准确性、完整性和可追溯性，提高团队协作效率。
+
+### 1.2 适用范围
+
+本规范适用于 IT 智能服务台项目开发过程中的所有文档，包括但不限于：
+- 产品需求文档（PRD）
+- 技术架构文档
+- 原型设计文档
+- 代码评审报告
+- 测试文档
+- 部署运维文档
+- 项目管理文档（任务说明书、风险跟踪表等）
+
+---
+
+## 2. 文档目录结构
+
+### 2.1 顶级目录划分
+
+```
+docs/
+├── 01-项目总览/          ← 核心文档（必读）
+├── 02-产品需求/          ← PRD、功能需求
+├── 03-技术架构/          ← 架构设计、ADR、图表
+├── 04-原型设计/          ← UI/UX原型
+├── 05-用户手册/          ← 用户指南
+├── 06-测试质量/          ← 测试文档
+├── 07-代码评审/          ← Code Review
+├── 08-安全审计/          ← 安全、集成分析
+├── 09-部署运维/          ← 部署、运维、故障排查
+├── 10-项目管理/          ← SOP、项目管理
+└── 11-历史归档/          ← 历史归档
+```
+
+### 2.2 子目录命名规范
+
+| 目录类型 | 命名规则 | 示例 |
+|----------|----------|------|
+| 功能模块 | `XX-功能模块名/` | `02-技术方案/` |
+| 文档类型 | `XX-文档类型-类型名/` | `01-ADRs-架构决策/` |
+| 归档目录 | `archive/` | `prototypes-原型图/archive/` |
+
+---
+
+## 3. 文档命名规范
+
+### 3.1 核心文档
+
+```
+序号-文档名-YYYYMMDD.扩展名
+```
+
+**规则**：
+- 序号：01、02、03...（两位数字）
+- 文档名：中文描述，不超过30字
+- 日期：创建或重大更新日期（8位数字）
+
+**示例**：
+- `01-项目总览与部署手册-20260704.md`
+- `02-产品需求文档PRD-v1.2-20260704.md`
+
+### 3.2 普通文档
+
+```
+文档名-YYYYMMDD.扩展名
+```
+
+**示例**：
+- `v0.7.1-release-notes-20260623.md`
+
+### 3.3 归档文档
+
+```
+原文档名-archived-YYYYMMDD.扩展名
+```
+
+**示例**：
+- `PRD-v53-incremental-archived-20260704.md`
+
+### 3.4 ADR 文档
+
+```
+ADR-XXX-标题.扩展名
+```
+
+**示例**：
+- `ADR-001-Gitea自托管-Funnel暴露.md`
+
+### 3.5 SOP 文档
+
+```
+SOP-序号-流程名.扩展名
+```
+
+**示例**：
+- `SOP-01-Gitea部署.md`
+
+### 3.6 禁止事项
+
+- ❌ 禁止使用特殊字符（`/ \ : * ? " < > |`）
+- ❌ 禁止使用空格（用 `-` 或 `_` 代替）
+- ❌ 禁止使用 emoji
+- ❌ 禁止纯数字命名
+
+---
+
+## 4. 文档版本管理
+
+### 4.1 版本号规则
+
+采用 `主版本.次版本.修订号` 格式：
+- **主版本**：重大架构变更或功能迭代
+- **次版本**：功能新增或较大调整
+- **修订号**：文档修正、错别字修改
+
+**示例**：v1.0 → v1.1 → v2.0
+
+### 4.2 版本记录
+
+每个文档头部必须包含版本信息：
+
+```markdown
+> **版本**: v1.0 | **日期**: 2026-07-04 | **作者**: xxx | **状态**: 草稿/评审中/正式发布
+```
+
+### 4.3 变更记录
+
+重大文档必须包含变更记录：
+
+```markdown
+## 📈 版本历史
+
+| 版本 | 日期 | 变更内容 | 变更人 |
+|------|------|----------|--------|
+| v1.0 | 2026-07-04 | 初始版本 | xxx |
+| v1.1 | 2026-07-05 | 新增xxx功能 | xxx |
+```
+
+---
+
+## 5. 任务说明书要求
+
+### 5.1 必含字段
+
+根据任务类型，必须包含以下字段：
+
+| 字段 | 说明 | 必填 |
+|------|------|------|
+| 任务名称 | 任务简短描述 | ✅ |
+| 任务ID | 唯一标识（如 #90） | ✅ |
+| 优先级 | P0/P1/P2 | ✅ |
+| 状态 | 待开始/进行中/已完成/阻塞/延后 | ✅ |
+| 输入项来源 | 产品需求/技术架构/原型设计/项目看板 | ✅ |
+| 输出成果要求 | 交付物清单 | ✅ |
+| 验证方式 | 测试方法 | ✅ |
+| 完成标准 | 验收条件 | ✅ |
+
+### 5.2 输入项来源规范
+
+每项任务必须明确输入来源：
+
+```markdown
+### 📥 输入项来源
+
+#### 产品需求
+| 来源文档 | 相关章节 | 说明 |
+|----------|----------|------|
+| `02-产品需求/02-产品需求文档PRD-v1.2-20260704.md` | §4.4.5 | 登录流程要求 |
+
+#### 技术架构
+| 来源文档 | 相关章节 | 说明 |
+|----------|----------|------|
+| `03-技术架构/02-技术方案/技术方案-消息功能详细设计.md` | - | 技术实现方案 |
+
+#### 原型设计
+| 来源文档 | 页面 | 说明 |
+|----------|------|------|
+| `04-原型设计/prototypes-原型图/admin-dashboard-v1.html` | 登录页 | 登录UI要求 |
+```
+
+### 5.3 输出成果要求
+
+明确每项任务的交付物：
+
+```markdown
+### 📤 输出成果要求
+
+| # | 交付物 | 类型 | 说明 |
+|---|--------|------|------|
+| 1 | 后端登录API | 代码 | `/api/auth/login` 接口 |
+| 2 | 登录页面 | 代码 | Vue组件 |
+| 3 | API文档 | 文档 | 更新OpenAPI |
+```
+
+### 5.4 验证方式
+
+```markdown
+### 🔧 验证方式
+
+| 验证项 | 验证方法 | 预期结果 |
+|--------|----------|-----------|
+| 功能正常运行 | 手动测试 | 登录成功 |
+| 权限控制 | 越权测试 | 无法访问未授权页面 |
+| 响应时间 | 性能测试 | < 500ms |
+```
+
+### 5.5 完成标准
+
+```markdown
+### ✅ 完成标准
+
+- [ ] 代码合入主干分支
+- [ ] 所有测试通过
+- [ ] 功能测试通过
+- [ ] 安全测试通过
+- [ ] 文档已更新
+```
+
+---
+
+## 6. 文档审批流程
+
+### 6.1 审批角色
+
+| 文档类型 | 审批人 |
+|----------|--------|
+| 产品需求（PRD） | 产品经理 + 技术负责人 |
+| 技术架构文档 | 技术负责人 |
+| 代码评审报告 | 评审参与者 |
+| 部署文档 | 运维负责人 |
+
+### 6.2 审批状态
+
+| 状态 | 说明 |
+|------|------|
+| 草稿 | 初始编写 |
+| 评审中 | 等待审批 |
+| 修订中 | 评审反馈需修改 |
+| 正式发布 | 审批通过 |
+| 已废弃 | 被新版本替代 |
+
+---
+
+## 7. 文档归档要求
+
+### 7.1 归档条件
+
+满足以下任一条件应归档：
+- 文档被新版本替代
+- 对应功能已完成并稳定运行超过3个月
+- 文档内容已整合到其他文档
+
+### 7.2 归档命名
+
+归档文档添加 `-archived-YYYYMMDD` 后缀：
+
+```bash
+# 归档前
+PRD-v53-incremental.md
+
+# 归档后
+PRD-v53-incremental-archived-20260704.md
+```
+
+### 7.3 归档位置
+
+- 历史归档文档统一放置在 `11-历史归档/` 目录
+- 按时间顺序保留，最新版本在主目录
+
+---
+
+## 8. 文档索引维护
+
+### 8.1 主索引文档
+
+`01-项目总览/00-索引-YYYYMMDD.md` 为项目主索引，需保持更新。
+
+### 8.2 更新规则
+
+| 操作 | 同步要求 |
+|------|----------|
+| 新增文档 | 添加到对应目录 + 更新索引 |
+| 删除文档 | 从索引移除 |
+| 移动文档 | 更新索引路径 |
+| 重大变更 | 同步更新 CHANGELOG |
+
+---
+
+## 9. 文档质量检查清单
+
+### 9.1 基本检查
+
+- [ ] 文档命名符合规范
+- [ ] 头部包含版本信息
+- [ ] 目录结构清晰
+- [ ] 无错别字
+
+### 9.2 内容检查
+
+- [ ] 需求来源明确
+- [ ] 技术方案合理
+- [ ] 验证方式可行
+- [ ] 完成标准可衡量
+
+### 9.3 关联检查
+
+- [ ] 相关文档链接正确
+- [ ] 版本历史完整
+- [ ] 索引已更新
+
+---
+
+## 10. 附则
+
+### 10.1 生效日期
+
+本规范自 2026-07-04 起正式执行。
+
+### 10.2 解释权
+
+本规范解释权归项目负责人所有。
+
+### 10.3 修订周期
+
+每季度评审一次，根据实际执行情况进行修订。
+
+---
+
+## 📈 变更记录
+
+| 版本 | 日期 | 变更内容 | 变更人 |
+|------|------|----------|--------|
+| v1.0 | 2026-07-04 | 初始版本 | Claude |