# 企微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-项目总览/          # 项目介绍、部署手册
├── 02-产品需求/          # PRD、需求文档
├── 03-技术架构/          # 技术方案、设计文档
├── 04-原型设计/          # UI原型
├── 05-用户手册/          # 用户指南
├── 06-测试质量/          # 测试报告、E2E
├── 07-代码评审/          # Code Review
├── 08-安全审计/          # 安全相关
├── 09-部署运维/          # 部署、运维
├── 10-项目管理/          # 任务、风险、SOP
└── 11-历史归档/          # 历史版本
```

### 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-ops | 容器状态、进程、日志 | 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/09-部署运维/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-ops | 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-ops(传输)
├─ 应急响应 → SOP §4 流程
├─ Plan模式 → 评估/方案文档
└─ 直接执行 → 文档/工具沉淀
```

---

## 附录：相关文档

| 文档 | 位置 |
|------|------|
| 项目管理主文档 | `10-项目管理/任务说明书/` |
| 风险跟踪表 | `10-项目管理/任务说明书/02-风险跟踪表.md` |
| 技术架构 | `03-技术架构/` |
| 部署手册 | `09-部署运维/` |
| 标准故障排查手册 | `09-部署运维/00-标准故障排查手册.md` |
| 部署运维工具箱 | `09-部署运维/toolbox/` |
| task-intake 技能 | `.workbuddy/skills/task-intake/SKILL.md` |

---

> **本文档为标准作业流程综合文档，最后更新：2026-07-10（§6.5 验证手段分层新增前端诊断 F12 等效命令 + agent-browser SKILL.md 补全 Debug/Network 文档）**