chore(docs): docs/ 目录全面重新编号 + 重组

**重构前**（旧编号 02-11）： - docs/02-产品需求/ → 00 产品规划/PRD - docs/03-技术架构/ → 01-05 子目录散落 - docs/04-原型设计/ → 01-02 产品设计（HTML 原型） - docs/05-原型设计/ → screens/ - docs/06-测试素材/ → 02-E2E / 03-功能 / 04-版本测试 - docs/07-项目管理/ → 任务说明书/日报/计划 - docs/08-安全审计/ → 审计报告 - docs/09-堡垒运维/ → toolbox / deploy - docs/10-项目管理/ → 任务说明书（重复） - docs/11-历史归档/ → deploy-nas-archived **重构后**（新编号 00-07，语义化）： - docs/00-产品开发流程与文档管理规范.md - docs/00-版本迭代总览.md - docs/01-产品文档/ （PRD/原型/认证/会话/AI 服务/坐席/集成） - docs/02-技术文档/ （技术方案/架构图/重构记录/前端改造/实现配置） - docs/03-测试文档/ （E2E/功能用例/版本报告/缺陷单） - docs/04-运维文档/ （部署运维/运维指南） - docs/05-运营文档/ （品牌推广/用户手册） - docs/06-安全审计/ （审计报告） - docs/07-项目管理/ （任务说明书/日报/计划/看板） **净收益**： - 目录编号与产品文档管理规范对齐（按文档阶段 01-07 编号） - 消除 02-产品需求与 10-项目管理的编号重叠 - 子目录按文档类型分组（如 01-产品文档/00-产品规划、01-产品文档/01-认证与登录） - 把运维/安全/项目管理从 0X 散落改为 04/06/07 合计 494 文件 + 78495 行 / - 14076 行
2026-08-03 18:46:55 +08:00
parent 3a44141eac
commit 44e77dcb0e
494 changed files with 78494 additions and 14075 deletions
@@ -0,0 +1,459 @@
+# 企微IT智能服务台 — 标准作业流程SOP
+
+> **版本**: v1.5 | **日期**: 2026-07-10
+
+---
+
+## 目录
+
+1. [Gitea部署](#1-gitea部署)
+2. [Gitea备份恢复](#2-gitea备份恢复)
+3. [推送评审](#3-推送评审)
+4. [应急响应](#4-应急响应)
+5. [文档管理规范](#5-文档管理规范)
+6. [BugFix快捷路径](#6-bugfix-快捷路径v11-优化版)
+7. [部署运维工具箱管理](#7-部署运维工具箱管理)
+8. [任务路由表](#8-任务路由表)
+
+---
+
+## 1. Gitea部署
+
+> **适用**: 新机器 / NAS 迁移 / Gitea重建
+> **耗时**: 30-45 分钟
+
+### 1.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
+```
+
+### 1.2 装 Gitea 套件
+
+1. DSM → 套件中心
+2. 搜 `Gitea` → 安装
+3. 装好跳 `http://100.85.152.112:8418/`
+
+---
+
+## 2. Gitea备份恢复
+
+> **适用**: 数据丢失应急 / 误操作回滚 / 异地迁移
+> **耗时**: 5-15 分钟
+
+### 2.1 备份策略
+
+| 项 | 值 | 备注 |
+|---|---|---|
+| 频率 | 每天 3 点 | cron |
+| 保留 | 7 天 | 默认 |
+| 路径 | `/volume1/backups/gitea/` | NAS 本地 |
+| 工具 | `scripts/backup-gitea.sh` | 已写 |
+
+### 2.2 手动备份(应急)
+
+```bash
+ssh simon@100.85.152.112
+sudo bash /volume1/docker/wecom-it-desk/scripts/backup-gitea.sh
+```
+
+### 2.3 恢复流程
+
+```bash
+# 停止 Gitea
+sudo docker stop gitea
+
+# 恢复数据
+sudo bash /volume1/docker/wecom-it-desk/scripts/restore-gitea.sh <backup_file>
+
+# 启动 Gitea
+sudo docker start gitea
+```
+
+---
+
+## 3. 推送评审
+
+> **适用**: 任何 commit 推 Gitea / PR 评审 / workbuddy 推送
+> **耗时**: 5-15 分钟
+
+### 3.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 必修
+
+### 3.2 Commit 规范
+
+格式: `<type>(<scope>): <subject>`
+
+| type | 用途 |
+|------|------|
+| feat | 新功能 |
+| fix | Bug修复 |
+| docs | 文档 |
+| style | 格式 |
+| refactor | 重构 |
+| test | 测试 |
+| chore | 维护 |
+
+### 3.3 PR 评审要求
+
+- 所有 P0 鉴权修复必须走评审
+- 端点变更需鉴权依赖
+- 数据库 schema 变化必须 alembic 迁移
+
+---
+
+## 4. 应急响应
+
+> **适用**: P0 漏洞 / 数据丢失 / 服务中断 / 安全事件
+> **响应时间**: 5 分钟响应 + 30 分钟止血 + 24 小时根因
+
+### 4.1 事件分级
+
+| 等级 | 场景 | 响应时间 |
+|------|------|----------|
+| 🔴 **P0 紧急** | P0 鉴权漏洞 + 数据泄露 + 服务全停 | 5 min |
+| 🟠 **P1 高** | P1 功能故障 + 单服务降级 | 30 min |
+| 🟡 **P2 中** | P2 性能 / UI 问题 | 4 h |
+| 🟢 **P3 低** | 体验优化 | 1 周 |
+
+### 4.2 P0 应急流程(5 min 响应)
+
+#### 4.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. **保留现场**:
+   - 不删任何文件
+   - 不改配置
+   - 截图/录屏
+
+#### 4.2.2 快速评估
+
+| 问题 | 影响范围 | 可行方案 |
+|------|----------|----------|
+| | | |
+
+#### 4.2.3 升级上报
+
+- 5 分钟无法止血 → 升级到技术负责人
+- 30 分钟无法解决 → 升级到管理层
+
+### 4.3 P1 应急流程(30 min)
+
+1. **定位问题**: 30 分钟内确定故障范围
+2. **临时方案**: 提供绕过/降级方案
+3. **根本修复**: 24 小时内完成
+
+---
+
+## 5. 文档管理规范
+
+> **版本**: v1.0 | **日期**: 2026-07-04
+
+### 5.1 文档目录结构
+
+```
+docs/
+├── 01-产品文档/          # PRD、原型图
+├── 02-技术文档/          # 技术方案、设计
+├── 03-测试文档/          # 测试报告、E2E
+├── 04-运维文档/          # 部署、运维
+├── 05-运营文档/          # 用户手册、运营报告
+├── 06-安全审计/          # 安全相关
+├── 07-项目管理/          # 任务、风险、SOP
+└── 08-历史归档/          # 历史版本
+```
+
+### 5.2 文档命名规范
+
+| 类型 | 命名格式 | 示例 |
+|------|----------|------|
+| 需求文档 | `需求-<功能名>.md` | `需求-应急降级页.md` |
+| 技术方案 | `技术方案-<模块名>.md` | `技术方案-消息功能.md` |
+| 测试报告 | `测试-<功能>-<日期>.md` | `测试-E2E-20260708.md` |
+| 部署手册 | `部署-<环境>-<日期>.md` | `部署-生产-20260704.md` |
+
+### 5.3 文档维护
+
+| 文档状态 | 维护要求 |
+|----------|----------|
+| 正式发布 | 仅通过 PR 评审更新 |
+| 更新中 | 标注"草稿"或"进行中" |
+| 已废弃 | 移至历史归档 |
+
+### 5.4 版本管理
+
+- 重大更新 → 新版本号
+- 小修复 → 保留版本号，更新日期
+- 版本历史记录在文档末尾
+
+---
+
+## 6. BugFix 快捷路径（v1.1 优化版）
+
+> **适用**: 非紧急 Bug 修复，不涉及核心架构变更
+> **目标**: 快速响应 + 风险可控
+
+### 6.1 处理流程（6 步）
+
+| 步骤 | 操作 | 产出 | 备注 |
+|------|------|------|------|
+| 1 | 定位根因 | 问题定位文档 | 明确问题文件和行号 |
+| 2 | 影响评估 | 影响分析报告 | 正面/负面影响 + 风险等级 |
+| 3 | 方案确认 | 修复方案 | 需用户确认后执行 ⚠️ |
+| 4 | 部署执行 | 部署完成 | 上传 → cp → 重启 |
+| 5 | 功能验证 | 验证通过 | 实际触发功能测试 |
+| 6 | 状态更新 | 看板已更新 | 正在做 → 已完成 |
+
+### 6.2 部署三问（部署前必确认）
+
+| 问题 | 目的 |
+|------|------|
+| 会影响坐席和员工端使用吗？ | 评估业务影响 |
+| 会重启容器或服务吗？ | 评估可用性影响 |
+| 验证方式是什么？ | 明确如何验证修复效果 |
+
+### 6.3 复盘要求
+
+| 场景 | 是否需要复盘 | 理由 |
+|------|-------------|------|
+| **简单Bug**（单文件修改、<15分钟） | ❌ 不需要 | 流程简单，无学习价值 |
+| **复杂Bug**（多文件/多模块、涉及架构） | ✅ 建议 | 有技术沉淀价值 |
+| **重复出现的问题** | ✅ 必须 | 识别系统性风险 |
+| **有改进点** | ✅ 必须 | 沉淀到SOP，避免重复踩坑 |
+| **紧急止血**（P0/P1） | ❌ 事后补 | 先解决问题，24小时内补记录 |
+
+### 6.4 验收条件
+
+| 条件 | 说明 |
+|------|------|
+| 代码改动已确认 | 用户或自己确认修复方案 |
+| 部署后容器健康 | docker ps 显示 healthy |
+| 功能验证通过 | 按 §6.5 验证手段分层选择工具，前端类必须 agent-browser 截图 |
+| 看板状态已更新 | 正在做 → 已完成 |
+| 复盘报告（按需） | 复杂Bug/重复问题/有改进点时才需要 |
+
+### 6.5 验证手段分层
+
+验证不是"看看没报错就行"，必须按以下分层选择验证工具：
+
+| 验证类型 | 工具 | 适用场景 | 证据形式 |
+|---------|------|---------|---------|
+| API/后端 | curl / HTTP 请求 | 接口返回值、状态码、响应体 | curl 输出 + HTTP 状态码 |
+| 前端渲染/登录/交互 | **agent-browser** 技能 | 页面渲染、表单填写、按钮点击、键盘输入、登录流程 | 真实浏览器截图 |
+| 前端诊断（F12 等效） | **agent-browser** Debug 命令 | 白屏、JS 不执行、API 异常、CSP 违规 | console 日志 + errors + network 请求 + 截图 |
+| 服务器状态 | jumpserver-V2 | 容器状态、进程、日志 | docker ps / logs 输出 |
+
+**验证硬规则**：
+- 前端/登录类修复 → **必须**用 agent-browser 截图取证，不能只用 curl
+- API/后端类修复 → curl 真实返回 + 必要时代码层拦截响应体
+- **禁止**只因 `docker logs` 无报错就断言修复
+
+**前端诊断命令组合**（白屏/JS不执行/API异常/CSP违规场景必须采集）：
+
+| 采集项 | agent-browser 命令 | F12 等效面板 | 必须采集 |
+|--------|-------------------|-------------|---------|
+| JS 错误 | `errors` | Console > Errors | ✅ |
+| 控制台日志 | `console` | Console | ✅ |
+| 网络请求 | `network requests` | Network | ✅ |
+| 页面截图 | `screenshot` | — | ✅ |
+| HAR 录制 | `network har start` → 操作 → `network har stop` | Network (完整请求/响应) | API 异常时 |
+| DOM 检查 | `eval "document.documentElement.outerHTML.substring(0, 500)"` | Elements | 疑似渲染异常时 |
+| Cookie/Storage | `cookies` / `storage local` | Application | 登录态问题时 |
+
+**标准前端诊断流程**：
+```
+agent-browser open <url>
+agent-browser wait --load load
+agent-browser console --clear           # 清除旧日志
+agent-browser errors                     # 采集 JS 错误
+agent-browser console                    # 采集控制台日志
+agent-browser network requests           # 采集网络请求
+agent-browser screenshot                 # 截图取证
+agent-browser close
+```
+
+> **注意**：以上命令在同一个浏览器 session 中执行，cookie 和状态自动保持。只需在最后执行一次 `close`。
+
+---
+
+## 7. 部署运维工具箱管理
+
+> **适用**: 故障排查 / 部署运维过程中产生的可复用脚本、配置模板、调试工具
+> **工具箱位置**: `docs/04-运维文档/部署运维/toolbox/`
+
+### 7.1 工具沉淀流程
+
+每次故障排查或部署完成后，按以下流程处理排查过程中产生的脚本和工具：
+
+| 步骤 | 操作 | 说明 |
+|------|------|------|
+| 1 | **评估复用价值** | 该脚本/配置是否可能在后续排查中再次使用？ |
+| 2 | **归档** | 有复用价值 → 复制到 `toolbox/`（活跃工具）或 `toolbox/archive/`（历史脚本） |
+| 3 | **登记** | 在 `toolbox/README.md` 的工具索引表中添加条目（工具名、用途、使用方式） |
+| 4 | **清理根目录** | 删除项目根目录的临时文件（渲染输出、中间产物等），保持根目录整洁 |
+
+### 7.2 归档分类标准
+
+| 分类 | 存放位置 | 判定标准 | 示例 |
+|------|----------|----------|------|
+| **活跃工具** | `toolbox/` | 当前可复用、有通用价值的脚本或配置模板 | `fast_upload.py`、`nginx-access-control.conf` |
+| **历史脚本** | `toolbox/archive/` | 一次性修复脚本，仅供历史参考 | `fix_admin_role.py`、`patch-redis-url.py` |
+| **临时文件** | 直接删除 | 渲染输出、中间产物、调试快照 | `rendered_scan.html`、`tmp_*.html` |
+
+### 7.3 README 维护要求
+
+- 新增工具时**必须同步更新** `toolbox/README.md` 的工具索引表
+- 每个条目包含：工具名、用途、使用方式
+- archive/ 中的脚本按"修复场景 + 日期"分组登记
+- README 版本号随工具增减递增
+
+### 7.4 故障排查手册更新触发条件
+
+以下场景**必须同步更新** `00-标准故障排查手册.md`：
+
+| 触发条件 | 更新内容 |
+|----------|----------|
+| 新案例（排查耗时 > 30 分钟） | §4 案例库新增 `CASE-YYYYMMDD-序号` 条目 |
+| 发现新的排查盲点 | §1 快速诊断决策树补充检查步骤 |
+| 新的错误现象 | §2 错误码速查表新增行 |
+| nginx 新陷阱 | §4 附：nginx 配错急救流程新增步骤 |
+| 响应头相关故障 | §1 Step 0 HTTP 响应头检查更新 |
+
+### 7.5 工具箱与 SOP 的关系
+
+```
+故障排查 → 产出脚本 → 评估复用价值 → 归档到 toolbox
+                                    ↓
+                              更新 README.md
+                                    ↓
+                        更新故障排查手册（按需）
+                                    ↓
+                        更新 SOP（仅涉及流程变更时）
+```
+
+**原则**：工具箱是"弹药库"，故障排查手册是"作战手册"，SOP 是"军规"。三者各司其职，不混为一谈。
+
+---
+
+## 8. 任务路由表
+
+> **适用**: 收到任何新请求时的统一入口
+> **执行者**: 交付总监（齐活林）使用 `task-intake` 技能执行
+> **原则**: 先路由再执行，先想清楚再动手
+
+### 8.1 路由表
+
+| 输入特征 | 路由到 | 产出物 | 执行方 | 参考 |
+|---------|--------|--------|--------|------|
+| 🏗️ 新功能（中大型，>10文件） | 软件团队标准 SOP | PRD+架构+代码+测试 | PM→Architect→Engineer→QA | 软件团队 SOP |
+| ⚡ 新功能（小型，≤10文件） | 软件团队快速模式 | 代码+测试 | Engineer→QA | 软件团队 SOP |
+| 🔧 Bug 修复 | SOP §6 BugFix | 修复+验证 | Engineer→QA | SOP §6 |
+| 🚀 部署运维 | 直接执行 | 部署完成+验证 | AI+jumpserver-V2 | SOP §7 |
+| 🩺 故障排查 | deploy-troubleshoot | 定位+修复+案例 | 三步隔离法 | 故障排查手册 |
+| 🔴 应急事件（P0/P1） | SOP §4 应急响应 | 止血+根因 | 应急流程 | SOP §4 |
+| 🔍 代码调试 | diagnose 技能 | 根因+回归 | 六阶段调试 | diagnose SKILL.md |
+| 📊 技术评估/决策 | Plan 模式 | 评估报告 | AI+人 | — |
+| 📋 方案调研 | Plan 模式 | 方案文档 | AI+人 | — |
+| 📝 文档更新 | 直接执行 | 文档 | AI | SOP §5 |
+| 🛠️ 工具沉淀 | SOP §7 流程 | 工具归档+README | AI | SOP §7 |
+
+### 8.2 路由优先级
+
+当请求可能匹配多个分类时，按以下优先级路由：
+
+1. **🔴 应急事件** > 一切（先止血再说）
+2. **🩺 故障排查** > **🔧 Bug 修复**（先隔离定位再修 Bug）
+3. **🏗️/⚡ 新功能** > **📊 技术评估**（明确要做的不需要评估）
+4. **📝 文档更新** / **🛠️ 工具沉淀** 通常作为其他任务的收尾步骤
+
+### 8.3 task-intake 技能
+
+任务路由通过 `task-intake` 技能执行（项目级 skill，位置：`.workbuddy/skills/task-intake/`）。
+
+**执行流程**：
+1. **分类** — 判断请求属于哪类任务
+2. **结构化** — 输出四要素（是什么/要什么/怎么做/谁来做）
+3. **路由** — 对照 §8.1 路由表确定执行路径
+4. **移交** — 输出路由卡，交给对应执行方
+
+**路由卡格式**：
+```
+是什么：[任务分类] + [一句话描述]
+要什么：[期望产出物] + [验收标准]
+怎么做：[执行路径] + [技能/工具]
+谁来做：[执行角色] + [协作方]
+路由到：[工作流名称]
+```
+
+### 8.4 上下文隔离原则
+
+路由卡**只传递结论，不传递思考过程**。下一阶段拿到的是干净的输入，不被前一阶段的假设和试错带偏。
+
+| 正确 | 错误 |
+|------|------|
+| "故障定位在 Nginx 层，证据是 curl 返回 403" | "我一开始以为是后端，试了 A/B/C 都不对..." |
+| "根因是 CSP 缺少 unsafe-inline" | "我检查了 JS 加载、签名 URL、轮询逻辑..." |
+
+### 8.5 与齐活林（交付总监）的集成
+
+```
+请求到达 → 齐活林调用 task-intake → 输出路由卡
+  ↓
+├─ 标准SOP → TeamCreate → PM → Architect → Engineer → QA
+├─ 快速模式 → TeamCreate → Engineer → QA
+├─ BugFix → TeamCreate → Engineer → QA
+├─ 故障排查 → deploy-troubleshoot → jumpserver-V2(传输)
+├─ 应急响应 → SOP §4 流程
+├─ Plan模式 → 评估/方案文档
+└─ 直接执行 → 文档/工具沉淀
+```
+
+---
+
+## 附录：相关文档
+
+| 文档 | 位置 |
+|------|------|
+| 项目管理主文档 | `07-项目管理/任务说明书/` |
+| 风险跟踪表 | `07-项目管理/任务说明书/02-风险跟踪表.md` |
+| 技术架构 | `03-技术架构/` |
+| 部署手册 | `04-运维文档/部署运维/` |
+| 标准故障排查手册 | `04-运维文档/部署运维/00-标准故障排查手册.md` |
+| 部署运维工具箱 | `04-运维文档/部署运维/toolbox/` |
+| task-intake 技能 | `.workbuddy/skills/task-intake/SKILL.md` |
+
+---
+
+> **本文档为标准作业流程综合文档，最后更新：2026-07-10（§6.5 验证手段分层新增前端诊断 F12 等效命令 + agent-browser SKILL.md 补全 Debug/Network 文档）**