# P6 后续工作手册

> 版本：1.0
> 日期：2026-07-08
> 状态：待执行
> 执行环境：`e:\Desktop\Edu`
> 维护者：架构组
> 关联文档：
>
> - [004 架构影响地图](./architecture/004_architecture_impact_map.md)
> - [项目规则](../../.trae/rules/project_rules.md)（已修复，迁至 `.trae/rules/`）
> - [迁移指南](../../MIGRATION_GUIDE.md)
> - [P6 硬化 Runbook](./runbooks/p6-hardening.md)

---

## 目录

1. [执行前必读](#一执行前必读)
2. [环境准备](#二环境准备)
3. [依赖安装](#三依赖安装)
4. [代码质量校验](#四代码质量校验)
5. [arch.db 同步](#五archdb-同步)
6. [修复 project_rules.md（P0 紧急）](#六修复-project_rulesmd-p0-紧急)
7. [修复 004 架构图](#七修复-004-架构图)
8. [P6 集成测试补充](#八p6-集成测试补充)
9. [Helm Chart 演化](#九helm-chart-演化)
10. [文档同步](#十文档同步)
11. [故障排查](#十一故障排查)
12. [验收清单](#十二验收清单)

---

## 一、执行前必读

### 1.1 工作目录

**所有命令在 `e:\Desktop\Edu` 目录下执行**（除非另注）。

```powershell
Set-Location 'e:\Desktop\Edu'
```

### 1.2 当前已知问题

| #   | 问题                                                                      | 严重度 | 修复任务   |
| --- | ------------------------------------------------------------------------- | ------ | ---------- |
| 1   | `project_rules.md` 文件损坏（仅 72 字节乱码残片，从 P1 提交时就损坏）     | P0     | 第六节     |
| 2   | `004_architecture_impact_map.md` 1.1 架构图只有技术分层图，缺业务领域视角 | P1     | 第七节     |
| 3   | 004 缺少视口四层模型说明（L1 导航/L2 路由/L3 组件/L4 数据）               | P1     | 第七节     |
| 4   | P6 暂存文件已部署但未运行依赖安装和 arch:scan                             | P2     | 第三、五节 |
| 5   | P6 集成测试缺失（熔断器/限流/备份脚本）                                   | P2     | 第八节     |
| 6   | K8s 骨架未演化为 Helm chart                                               | P3     | 第九节     |
| 7   | known-issues 工作经验日志未更新                                           | P3     | 第十节     |

### 1.3 工具链版本要求

| 工具    | 最低版本 | 验证命令           |
| ------- | -------- | ------------------ |
| Node.js | 20+      | `node --version`   |
| pnpm    | 9.12+    | `pnpm --version`   |
| Go      | 1.22+    | `go version`       |
| Python  | 3.12+    | `python --version` |
| uv      | 0.5+     | `uv --version`     |

---

## 二、环境准备

### 2.1 安装 pnpm（如未安装）

```powershell
npm install -g pnpm@9.12.0 --registry=https://registry.npmmirror.com
pnpm --version  # 验证：应输出 9.12.0
```

### 2.2 安装 Go（如未安装）

```powershell
winget install GoLang.Go --accept-source-agreements --accept-package-agreements
# 刷新 PATH
$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")
go version  # 验证：应输出 go1.26+ windows/amd64
```

### 2.3 安装 uv（如未安装）

```powershell
pip install uv -i https://pypi.tuna.tsinghua.edu.cn/simple
uv --version  # 验证：应输出 uv 0.11+
```

### 2.4 配置镜像加速（推荐）

```powershell
# npm 镜像
npm config set registry https://registry.npmmirror.com

# Go 镜像
go env -w GOPROXY=https://goproxy.cn,direct
go env -w GOSUMDB=off

# Python 镜像（uv 会继承 pip 配置）
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
```

---

## 三、依赖安装

### 3.1 TypeScript 依赖（pnpm workspace）

```powershell
Set-Location 'e:\Desktop\Edu'
pnpm install
```

**预期**：10 个 workspace 项目（services/_、apps/_、packages/_、scripts/_）依赖安装完成。

**验证**：

```powershell
# 检查 node_modules 是否生成
Test-Path 'e:\Desktop\Edu\node_modules'  # True
Test-Path 'e:\Desktop\Edu\services\classes\node_modules'  # True
```

### 3.2 Go 依赖（每个 Go 服务独立）

```powershell
# api-gateway
Set-Location 'e:\Desktop\Edu\services\api-gateway'
go mod tidy

# push-gateway
Set-Location 'e:\Desktop\Edu\services\push-gateway'
go mod tidy

# 验证 go.sum 生成
Test-Path 'e:\Desktop\Edu\services\api-gateway\go.sum'  # True
Test-Path 'e:\Desktop\Edu\services\push-gateway\go.sum'  # True
```

**关键依赖**：

- `github.com/sony/gobreaker/v2 v2.1.0`（P6 熔断器，已在 go.mod 声明，需 `go mod tidy` 拉取）
- `github.com/gin-gonic/gin v1.10.0`
- `github.com/google/uuid v1.6.0`

### 3.3 Python 依赖（每个 Python 服务独立）

```powershell
# data-ana 服务
Set-Location 'e:\Desktop\Edu\services\data-ana'
uv sync

# ai 服务
Set-Location 'e:\Desktop\Edu\services\ai'
uv sync

# 验证 .venv 生成
Test-Path 'e:\Desktop\Edu\services\data-ana\.venv'  # True
Test-Path 'e:\Desktop\Edu\services\ai\.venv'  # True
```

### 3.4 protobuf 工具链（可选，如需重新生成代码）

```powershell
# 安装 buf
npm install -g @bufbuild/buf

# 生成代码
Set-Location 'e:\Desktop\Edu\packages\shared-proto'
buf generate
```

---

## 四、代码质量校验

### 4.1 TypeScript 校验

```powershell
Set-Location 'e:\Desktop\Edu'
pnpm run lint      # ESLint
pnpm run typecheck # tsc --noEmit（各服务独立）
```

**预期**：0 errors。如有错误，逐个修复。

### 4.2 Go 校验

```powershell
Set-Location 'e:\Desktop\Edu\services\api-gateway'
go vet ./...
go build ./...

Set-Location 'e:\Desktop\Edu\services\push-gateway'
go vet ./...
go build ./...
```

### 4.3 Python 校验

```powershell
# 安装 ruff（如未安装）
pip install ruff

Set-Location 'e:\Desktop\Edu\services\data-ana'
ruff check src/

Set-Location 'e:\Desktop\Edu\services\ai'
ruff check src/
```

---

## 五、arch.db 同步

### 5.1 扫描代码结构

```powershell
Set-Location 'e:\Desktop\Edu'
pnpm run arch:scan
```

**预期**：扫描 TS/Go/Python/Proto 文件，生成 `arch.db`（SQLite）。

### 5.2 验证扫描结果

```powershell
# 查询统计
pnpm run arch:query -- stats

# 查询模块列表
pnpm run arch:query -- modules

# 查询架构违规
pnpm run arch:query -- violations
```

**预期**：

- 模块数 ≥ 10（api-gateway、push-gateway、teacher-bff、iam、classes、core-edu、content、msg、data-ana、ai）
- 符号数 ≥ 100
- 违规数：记录但暂不强制修复（已知技术债）

### 5.3 自定义 SQL 查询示例

```powershell
# 查询所有服务
pnpm run arch:query -- sql "SELECT name, language, path FROM modules WHERE type='service'"

# 查询跨服务依赖
pnpm run arch:query -- sql "SELECT * FROM dependencies WHERE source_module != target_module"
```

---

## 六、修复 project_rules.md（P0 紧急）

### 6.1 问题现状

```
文件路径：e:\Desktop\Edu\project_rules.md
当前大小：72 字节（损坏）
当前内容：4. 若代码结构变??`pnpm run arch:scan` 确认 arch.db 已更?（乱码残片）
Git 历史：从 P1 提交（2ba4250）时就损坏，无完整版本
```

### 6.2 修复方案

**目标路径**：`e:\Desktop\Edu\.trae\rules\project_rules.md`（按用户要求放到 `.trae/rules/` 下）

**内容来源**：从 CICD 项目（`e:\Desktop\CICD\.trae\rules\project_rules.md`）的完整版迁移，按 MIGRATION_GUIDE 4.1 策略矩阵调整。

### 6.3 调整对照表

| 章节              | CICD 原版                     | Edu 微服务版调整                                           |
| ----------------- | ----------------------------- | ---------------------------------------------------------- |
| 架构图优先规则    | `npm run arch:scan`           | `pnpm run arch:scan`（多语言扫描器）                       |
| 架构文档清单      | 004/006/007/008/roadmap/audit | 004 + roadmap/ + runbooks/ + 0010 蓝图                     |
| arch.db 规则      | TS 单语言                     | TS + Go + Python + Proto 多语言                            |
| 编码规范-架构分层 | `app → modules → shared` 三层 | Gateway → BFF → Services → Data 微服务分层                 |
| 编码规范-模块结构 | `src/modules/[module]/`       | `services/[service]/src/[domain]/` DDD 限界上下文          |
| TypeScript 规则   | `cacheFn` + Server Action     | NestJS Cache + `@RequirePermission()` 装饰器               |
| 命名规范          | 单语言                        | 多语言（TS/Go/Python 各自规范）                            |
| 安全规范          | NextAuth + httpOnly Cookie    | JWT RS256 + httpOnly Cookie + Gateway 校验                 |
| 新增规则          | —                             | 契约先行（protobuf+buf）、Outbox 事件驱动、多语言 monorepo |
| 命令前缀          | `npm run`                     | `pnpm run`（TS）/ `go mod`（Go）/ `uv`（Python）           |

### 6.4 执行步骤

```powershell
# 1. 创建 .trae/rules 目录
New-Item -Path 'e:\Desktop\Edu\.trae\rules' -ItemType Directory -Force

# 2. 参考 CICD 完整版（可读取参考）
# CICD 源文件：e:\Desktop\CICD\.trae\rules\project_rules.md

# 3. 创建 Edu 版 project_rules.md（内容见 6.5 节模板）
# 用编辑器创建 e:\Desktop\Edu\.trae\rules\project_rules.md

# 4. 删除损坏的根目录 project_rules.md
Remove-Item 'e:\Desktop\Edu\project_rules.md' -Force

# 5. 更新所有引用（004、MIGRATION_GUIDE 等）
# 搜索：project_rules.md
# 替换：.trae/rules/project_rules.md
```

### 6.5 project_rules.md 模板结构

完整内容应包含以下 13 章（参照 CICD 版调整）：

```markdown
# Edu 项目规则（微服务版）

## 1. 架构图优先规则

- 任何任务开始前，先查 004_architecture_impact_map.md
- 运行 `pnpm run arch:scan` 更新 arch.db
- 改码必同步图

## 2. 架构元数据库规则（arch.db）

- 多语言扫描：TS (ts-morph) + Go (tree-sitter-go) + Python (tree-sitter-python) + Proto
- 查询命令：`pnpm run arch:query -- <command>`

## 3. 架构文档清单

| 文档                                             | 用途         |
| ------------------------------------------------ | ------------ |
| docs/architecture/004_architecture_impact_map.md | 架构设计意图 |
| docs/architecture/0010_architecture.md           | 理想蓝图     |
| docs/architecture/roadmap/                       | 长远规划     |
| docs/architecture/runbooks/                      | 运维手册     |
| docs/troubleshooting/known-issues.md             | 已知问题速查 |

## 4. 编码规范

### 4.1 架构分层规则

- Gateway → BFF → Services → Data 微服务分层
- 依赖方向单向：Gateway → BFF → Services → Data
- 服务间通过 protobuf gRPC 通信，禁止直接访问对方 DB

### 4.2 模块标准结构（DDD）

services/[service]/src/
├─ [domain]/ # 限界上下文
│ ├─ *.controller.ts # Controller（HTTP/gRPC 入口）
│ ├─ *.service.ts # Application Service（编排层）
│ ├─ *.repository.ts # Repository（数据访问）
│ ├─ *.schema.ts # Zod 验证
│ └─ *.dto.ts # DTO
├─ config/ # 配置
├─ shared/ # 共享（errors/observability/health/lifecycle）
└─ main.ts # 入口

### 4.3 TypeScript 规则

- 禁止 any：用 unknown + 类型守卫
- 禁止 as 断言（除 unknown 转换）
- 函数返回值必须显式标注 Promise<T>
- import type 用于类型导入
- ESM .js 后缀（NestJS ESM 模式）

### 4.4 Go 规则

- 包名小写单词
- 导出函数必须有 doc comment
- 错误处理：if err != nil { return err }
- 不使用 interface{}，用 any（Go 1.18+）

### 4.5 Python 规则

- 类型注解强制
- FastAPI 路由用 APIRouter
- 异步优先：async def

### 4.6 命名规范

- 目录：kebab-case
- TS 组件：PascalCase
- Go 文件：lowercase
- Python 文件：snake_case
- 常量：UPPER_SNAKE_CASE

### 4.7 Server Action → Controller 规范

- 每个 Controller 方法必须用 @RequirePermission() 装饰器
- 输入用 Zod / class-validator 验证
- 返回 protobuf message（结构同 ActionState）
- 错误统一走 GlobalErrorFilter

### 4.8 Tailwind 规范

- 使用 cn() 工具函数
- 禁止字符串拼接动态类名
- 设计令牌在 packages/shared-tokens/

### 4.9 设计令牌规范

- 禁止硬编码颜色 #hex
- 禁止硬编码字体 'Inter'/'Fraunces'
- 禁止 Tailwind 任意值 w-[Npx]
- 三层令牌：primitive → semantic → tailwind-theme

## 5. 安全规范

- JWT RS256（IAM 签发，Gateway 公钥校验）
- httpOnly + Secure + SameSite=Strict Cookie
- 服务端环境变量不加 NEXT_PUBLIC_
- 禁止 dangerouslySetInnerHTML（如必须，先用 DOMPurify 清洗）

## 6. 契约规范

- 契约先行：protobuf + buf v2
- 服务间通信先定 .proto，再写实现
- buf lint STANDARD 规则
- buf breaking FILE 级别检查

## 7. 事件驱动规范

- Outbox 模式：事务内写业务+outbox，独立 publisher 投递到 Kafka
- 事件命名：<Aggregate>.<Action>（如 ExamCreated）
- TOPIC_MAP 路由：每个服务维护事件→topic 映射
- 幂等性：Kafka producer idempotent + transactionalId

## 8. 提交规范

- Conventional Commits: feat(scope): description
- scope: 服务名或包名（iam/classes/core-edu/content/msg/ai/api-gateway/...）
- 提交前必须运行 pnpm run lint + pnpm run typecheck

## 9. Git 工作流

- trunk-based 分支策略
- commitlint + husky 强制校验
- 直接提交 main 分支（小项目），大型团队改 PR

## 10. 问题记录规则

- 所有工作完成后，记录到 docs/troubleshooting/known-issues.md
- 索引式表格：场景→技术/规则映射
- 工作经验日志：日期+模块+做了什么+学到什么

## 11. AI 工作强制流程

### 阶段 1: 上下文加载

1. `pnpm run arch:scan` 更新 arch.db
2. `pnpm run arch:query -- module-deps` 查模块依赖
3. 阅读 services/[service]/README.md
4. 查 known-issues.md 相关经验

### 阶段 2: 执行工作

1. 按规划执行
2. 修改代码后立即 `pnpm run arch:scan`
3. 运行 pnpm run lint + pnpm run typecheck

### 阶段 3: 经验沉淀

1. 在 known-issues.md 追加工作经验日志
2. 若发现新场景→技术映射，提炼到对应分区
3. 若架构变化，更新 004

## 12. 多语言 monorepo 规则

- pnpm workspace（TS）+ go.work（Go）+ pyproject.toml（uv）
- 共享包：packages/shared-proto / shared-ts / shared-go / shared-py
- 跨语言契约通过 protobuf

## 13. 可观测性规范

- 日志：pino（TS）/ zap（Go）/ structlog（Python）
- 指标：prom-client（TS）/ prometheus（Go）/ prometheus-client（Python）
- 链路：OpenTelemetry SDK + OTLP exporter
- 三支柱必须同时启用
```

### 6.6 验证

```powershell
# 验证文件存在且内容完整
Get-Item 'e:\Desktop\Edu\.trae\rules\project_rules.md' | Select-Object Name, Length
# 预期：Length > 5000 字节

# 验证根目录损坏文件已删除
Test-Path 'e:\Desktop\Edu\project_rules.md'  # False

# 搜索所有引用并更新
Get-ChildItem 'e:\Desktop\Edu' -Recurse -Include '*.md' | Select-String -Pattern 'project_rules.md' | Select-Object Path, LineNumber, Line
```

---

## 七、修复 004 架构图

### 7.1 问题现状

- **1.1 系统边界图**：只有一张技术分层图，Users 层按角色分（Teacher/Student/Parent/Admin）
- **缺业务领域视角**：MIGRATION_GUIDE 3.2 和 0010 蓝图用的是 6 业务领域（身份/教学组织/教学核心/内容分析/沟通/智能洞察）
- **5.x 认证与权限**：缺视口四层模型说明

### 7.2 修复方案：双图并存

#### 7.2.1 保留 1.1a 技术分层图（修改注释）

将当前 1.1 改名为 **1.1a 技术分层视角**，修改：

- Users 层标注改为"场景域用户"（不是角色分类）
  - TeacherPortal 标注"教学场景域（教师/教导主任/教研组长共用）"
  - StudentPortal 标注"学习场景域"
  - ParentPortal 标注"家长场景域"
  - AdminPortal 标注"管理场景域"
- BFF 层标注"按使用场景域分 BFF（不是按角色分）"
- 添加说明："本图展示部署分层结构。业务领域视角见 1.1b"

#### 7.2.2 新增 1.1b 业务领域视角图

在 1.1a 后新增 **1.1b 业务领域视角**，mermaid 图：

```mermaid
graph TB
    subgraph D1["身份认证领域"]
        IAM[iam 服务]
        IAM_M[users / roles / permissions<br/>refresh_tokens / sessions]
    end

    subgraph D2["教学组织领域"]
        ORG[core-edu 服务<br/>classes 模块]
        ORG_M[classes / subjects / enrollment]
    end

    subgraph D3["教学核心领域"]
        TEACH[core-edu 服务<br/>exams/homework/grades]
        TEACH_M[exams / homework / grades<br/>courses / lessons / schedule / attendance]
    end

    subgraph D4["内容资源领域"]
        CONTENT[content 服务]
        CONTENT_M[textbooks / knowledge-points<br/>questions / grading / search(ES)]
    end

    subgraph D5["沟通通知领域"]
        MSG[msg 服务]
        MSG_M[messaging / notifications / announcements]
    end

    subgraph D6["智能洞察领域"]
        DATA[data-ana 服务]
        AI[ai 服务]
        DATA_M[analytics / dashboard / diagnostic(ClickHouse)]
        AI_M[ai 备课/出题/分析 / search]
    end

    D1 --> D2
    D1 --> D3
    D1 --> D4
    D1 --> D5
    D2 --> D3
    D3 --> D4
    D3 --> D5
    D4 --> D6
    D3 --> D6
```

#### 7.2.3 1.2 服务清单表格新增"业务领域"列

在 1.2 服务清单表格中，"限界上下文"列后新增"业务领域"列：

| 类别     | 服务名      | 语言/框架        | 限界上下文 | **业务领域**            | 阶段 |
| -------- | ----------- | ---------------- | ---------- | ----------------------- | ---- |
| 基础设施 | api-gateway | Go (Gin)         | 网关       | —                       | P1   |
| BFF      | teacher-bff | TS (NestJS)      | 教师聚合   | 教学场景域              | P2   |
| 业务     | iam         | TS (NestJS)      | 身份认证   | **身份认证**            | P2   |
| 业务     | core-edu    | TS (NestJS)      | 教学核心   | **教学组织 + 教学核心** | P3   |
| 业务     | content     | TS (NestJS)      | 内容资源   | **内容资源**            | P4   |
| 业务     | data-ana    | Python (FastAPI) | 数据分析   | **智能洞察**            | P4   |
| 业务     | msg         | TS (NestJS)      | 消息通知   | **沟通通知**            | P5   |
| 业务     | ai          | Python (FastAPI) | AI 网关    | **智能洞察**            | P5   |
| ...      | ...         | ...              | ...        | ...                     | ...  |

#### 7.2.4 新增 5.4 视口四层模型

在 5.3 DataScope 6 级数据范围后，新增 **5.4 视口四层模型**：

```markdown
### 5.4 视口四层模型

视口（Viewport）是用户在特定场景域下的可见范围。视口既可独立配置（RoleViewport 表），
也可由权限推导（permission → viewport 默认映射）。新角色只需配置权限集，视口自动推导；
需要差异化时再显式配置视口。

| 层级    | 含义             | 配置载体                           | 示例                                         |
| ------- | ---------------- | ---------------------------------- | -------------------------------------------- |
| L1 导航 | 侧边栏菜单项     | navigation_config 表               | 教导主任看到"全校成绩分析"菜单               |
| L2 路由 | 可访问路由       | route_permission 表 + Gateway 校验 | 教导主任可访问 /admin/grade-analysis         |
| L3 组件 | 页面内组件可见性 | usePermission().hasPermission()    | 教导主任看到"导出全校报表"按钮               |
| L4 数据 | 数据行级过滤     | DataScope 枚举                     | 教导主任 DataScope=grade_managed（管辖年级） |

**场景域 BFF 复用策略**：

按"使用场景域"分 BFF，而非按角色分。新角色复用现有 BFF，通过视口差异化。

| BFF         | 场景域   | 复用角色                 |
| ----------- | -------- | ------------------------ |
| Teacher BFF | 教学场景 | 教师、教导主任、教研组长 |
| Student BFF | 学习场景 | 学生                     |
| Parent BFF  | 家长场景 | 家长                     |
| Admin BFF   | 管理场景 | 系统管理员、校管理员     |

**实现**：教导主任归入 Teacher BFF + 额外管理视口（L1 导航增加管理菜单项，L4 数据范围扩大到年级）。

**iam 服务职责**：

- 认证：登录/登出/JWT/2FA
- RBAC：角色/权限/角色-权限映射 CRUD
- 视口配置：导航/路由/组件级视口配置 CRUD
- DataScope：数据范围解析（all/grade_managed/class_taught/children/owned + 自定义）
- 权限解析 API：getEffectivePermissions(userId) → {permissions, viewports, dataScope}
```

### 7.3 执行步骤

```powershell
# 1. 编辑 004_architecture_impact_map.md
# 路径：e:\Desktop\Edu\docs\architecture\004_architecture_impact_map.md

# 2. 按上述方案修改：
#    - 1.1 → 1.1a（改注释）
#    - 新增 1.1b（业务领域图）
#    - 1.2 表格新增"业务领域"列
#    - 5.3 后新增 5.4（视口四层模型）

# 3. 验证 mermaid 语法
# 可在 VS Code 安装 Mermaid Previewer 插件预览

# 4. 更新目录（如有章节编号变化）
```

---

## 八、P6 集成测试补充

### 8.1 熔断器状态机测试

**文件**：`services/api-gateway/internal/middleware/circuit-breaker_test.go`

```go
package middleware

import (
    "net/http"
    "net/http/httptest"
    "testing"
    "time"

    "github.com/gin-gonic/gin"
)

func TestCircuitBreaker_ClosedToOpen(t *testing.T) {
    // 模拟 5 秒窗口内错误率 > 50%，验证状态从 CLOSED → OPEN
}

func TestCircuitBreaker_OpenToHalfOpen(t *testing.T) {
    // 验证 OPEN 状态 30 秒后转 HALF_OPEN，允许 1 个探测请求
}

func TestCircuitBreaker_HalfOpenToClosed(t *testing.T) {
    // 验证 HALF_OPEN 探测成功后转 CLOSED
}

func TestCircuitBreaker_HalfOpenToOpen(t *testing.T) {
    // 验证 HALF_OPEN 探测失败后转 OPEN
}

func TestCircuitBreaker_4xxNotCounted(t *testing.T) {
    // 验证 4xx 响应不计入熔断失败计数
}
```

### 8.2 限流桶测试

**文件**：`services/api-gateway/internal/middleware/ratelimit_test.go`

```go
package middleware

import (
    "net/http"
    "net/http/httptest"
    "testing"
    "time"

    "github.com/gin-gonic/gin"
)

func TestRateLimit_AllowUnderBurst(t *testing.T) {
    // 验证突发请求 ≤ burst 时全部放行
}

func TestRateLimit_RejectOverBurst(t *testing.T) {
    // 验证突发请求 > burst 时返回 429
}

func TestRateLimit_RefillTokens(t *testing.T) {
    // 验证令牌按 rps 速率补充
}

func TestRateLimit_PerIPIsolation(t *testing.T) {
    // 验证不同 IP 的桶相互独立
}

func TestRateLimit_CleanupExpiredBuckets(t *testing.T) {
    // 验证 10 分钟无访问的桶被清理
}
```

### 8.3 备份脚本 dry-run 测试

**文件**：`infra/backup/test-backup-mysql.sh`

```bash
#!/bin/bash
# dry-run 模式测试备份脚本
# 不实际执行 mysqldump，仅验证参数解析和路径创建

set -euo pipefail

# 测试 --service 参数缺失
./backup-mysql.sh 2>&1 | grep -q "service is required"

# 测试 --keep 默认值
./backup-mysql.sh --service test 2>&1 | grep -q "keep=7"

# 测试无效 service
./backup-mysql.sh --service invalid 2>&1 | grep -q "unknown service"
```

### 8.4 执行测试

```powershell
# Go 测试
Set-Location 'e:\Desktop\Edu\services\api-gateway'
go test ./internal/middleware/... -v -cover

# Shell 测试（需要 bash 环境，如 WSL 或 Git Bash）
# bash infra/backup/test-backup-mysql.sh
```

---

## 九、Helm Chart 演化

### 9.1 现状

`infra/k8s/` 下有骨架 manifest：

- `namespace.yaml`：4 命名空间
- `api-gateway-deployment.yaml`：Deployment + Service

### 9.2 演化路线

```
infra/k8s/
├─ namespace.yaml          # 保留（基础资源）
├─ api-gateway-deployment.yaml  # 删除（迁移到 Helm）
└─ helm/                   # 新增
   ├─ edu-platform/        # 平台级 chart
   │  ├─ Chart.yaml
   │  ├─ values.yaml       # 全局默认值
   │  ├─ values-dev.yaml   # 开发环境覆盖
   │  ├─ values-staging.yaml
   │  ├─ values-prod.yaml
   │  └─ templates/
   │     ├─ namespace.yaml
   │     ├─ configmap.yaml
   │     ├─ secret.yaml
   │     ├─ ingress.yaml
   │     └─ hpa.yaml
   ├─ api-gateway/         # 服务级 chart
   │  ├─ Chart.yaml
   │  ├─ values.yaml
   │  └─ templates/
   │     ├─ deployment.yaml
   │     ├─ service.yaml
   │     ├─ configmap.yaml
   │     └─ hpa.yaml
   ├─ iam/
   ├─ core-edu/
   ├─ content/
   ├─ msg/
   ├─ data-ana/
   └─ ai/
```

### 9.3 执行步骤

```powershell
# 1. 安装 Helm（如未安装）
winget install Helm.Helm

# 2. 创建 chart 骨架
Set-Location 'e:\Desktop\Edu\infra\k8s'
New-Item -Path 'helm' -ItemType Directory
helm create helm/edu-platform
helm create helm/api-gateway
# ... 其他服务

# 3. 将现有 manifest 迁移到 templates/
# 4. 参数化 values.yaml
# 5. 验证
helm lint helm/api-gateway
helm template helm/api-gateway
```

---

## 十、文档同步

### 10.1 更新 known-issues.md

**文件**：`docs/troubleshooting/known-issues.md`

在"工作经验日志"区追加：

```markdown
### 2026-07-08 P6 后续工作

| 日期       | 模块        | 做了什么                               | 学到什么                                                       |
| ---------- | ----------- | -------------------------------------- | -------------------------------------------------------------- |
| 2026-07-08 | 全局        | pnpm install 失败（ENOENT _tmp_ 文件） | pnpm 在 Windows 下需配置 PNPM_HOME 和 TMP 环境变量             |
| 2026-07-08 | 全局        | project_rules.md 损坏（72 字节乱码）   | 迁移文件后必须验证完整性，git commit 前运行 cat 检查           |
| 2026-07-08 | api-gateway | gobreaker v2.1.0 版本验证              | GitHub releases 页面确认版本存在性，避免 go mod tidy 失败      |
| 2026-07-08 | 004         | 架构图视角讨论（技术分层 vs 业务领域） | 双图并存：1.1a 技术分层（部署视角）+ 1.1b 业务领域（DDD 视角） |
| 2026-07-08 | 004         | 视口四层模型补充                       | L1 导航/L2 路由/L3 组件/L4 数据，场景域 BFF 复用策略           |
```

### 10.2 同步 004 架构文档

按第七节修复后，检查 004 其他章节是否需要同步更新：

- 1.2 服务清单：新增"业务领域"列
- 5.4 视口四层模型：新增章节
- 14 附录：确认 6 阶段路线图与实际交付一致

### 10.3 更新模块 README

检查 9 个服务 README 是否需要补充：

- P6 新增的 health/lifecycle 模块说明
- 中间件链说明（api-gateway）
- 健康检查端点说明（所有服务）

---

## 十一、故障排查

### 11.1 pnpm install 失败

**错误**：`ENOENT: no such file or directory, open 'E:\Desktop\Edu\_tmp_xxxxx'`

**原因**：pnpm 在 Windows 下临时文件路径问题。

**解决**：

```powershell
# 设置环境变量
$env:PNPM_HOME = 'C:\Users\xiner\.pnpm'
$env:TMP = 'C:\Users\xiner\AppData\Local\Temp'
$env:TEMP = 'C:\Users\xiner\AppData\Local\Temp'

# 重试
pnpm install
```

### 11.2 pnpm "This project is configured to use npm"

**错误**：`ERROR This project is configured to use npm`

**原因**：项目根有 `.npmrc` 或 package.json 的 `packageManager` 字段冲突。

**解决**：

```powershell
# 检查 .npmrc
Get-Content 'e:\Desktop\Edu\.npmrc' -ErrorAction SilentlyContinue

# 如有 .npmrc 含 "package-manager=npm"，删除或改为 pnpm
# 或强制使用 pnpm
pnpm install --ignore-scripts
```

### 11.3 go mod tidy 网络失败

**错误**：`go: module github.com/sony/gobreaker/v2: downloading ... timeout`

**解决**：

```powershell
go env -w GOPROXY=https://goproxy.cn,direct
go env -w GOSUMDB=off
go mod tidy
```

### 11.4 uv sync 失败

**错误**：`error: Failed to download ...`

**解决**：

```powershell
# 配置镜像
$env:UV_INDEX_URL = 'https://pypi.tuna.tsinghua.edu.cn/simple'
uv sync
```

### 11.5 arch:scan 报错

**错误**：`Error: Cannot find module 'tsx'`

**解决**：

```powershell
# 确保 tsx 已安装
pnpm add -D tsx

# 或用 npx
npx tsx scripts/arch-scan/scanner.ts
```

---

## 十二、验收清单

完成所有任务后，逐项验证：

### 12.1 环境与依赖

- [ ] `pnpm --version` 输出 9.12+
- [ ] `go version` 输出 1.22+
- [ ] `uv --version` 输出 0.5+
- [ ] `pnpm install` 成功，无错误
- [ ] `go mod tidy`（api-gateway、push-gateway）成功
- [ ] `uv sync`（data-ana、ai）成功

### 12.2 代码质量

- [ ] `pnpm run lint` 0 errors
- [ ] `pnpm run typecheck` 0 errors
- [ ] `go vet ./...`（api-gateway、push-gateway）0 errors
- [ ] `ruff check src/`（data-ana、ai）0 errors

### 12.3 arch.db

- [ ] `pnpm run arch:scan` 成功
- [ ] `pnpm run arch:query -- stats` 输出模块数 ≥ 10
- [ ] arch.db 文件存在且非空

### 12.4 project_rules.md 修复

- [ ] `.trae/rules/project_rules.md` 存在且 > 5000 字节
- [ ] 根目录 `project_rules.md` 已删除
- [ ] 所有引用已更新为 `.trae/rules/project_rules.md`

### 12.5 004 架构图修复

- [ ] 1.1a 技术分层图保留，注释改为"场景域用户"
- [ ] 1.1b 业务领域视角图新增（6 领域）
- [ ] 1.2 服务清单新增"业务领域"列
- [ ] 5.4 视口四层模型章节新增
- [ ] mermaid 语法正确

### 12.6 P6 测试

- [ ] circuit-breaker_test.go 5 个测试用例通过
- [ ] ratelimit_test.go 5 个测试用例通过
- [ ] backup 脚本 dry-run 测试通过

### 12.7 文档同步

- [ ] known-issues.md 追加 P6 工作经验日志
- [ ] 9 个服务 README 检查并补充（如需要）

### 12.8 Git 提交

- [ ] 所有修复提交到 main 分支
- [ ] 提交信息：`fix(docs): repair project_rules.md and 004 architecture diagrams`
- [ ] 推送到远程

---

## 附录：快速执行脚本

如需一键执行所有任务，可创建 PowerShell 脚本：

```powershell
# e:\Desktop\Edu\scripts\post-p6-followup.ps1
# 在 Edu 目录下运行：.\scripts\post-p6-followup.ps1

Set-Location 'e:\Desktop\Edu'
$ErrorActionPreference = 'Continue'

Write-Host '=== 1. 依赖安装 ===' -ForegroundColor Cyan
pnpm install
Set-Location 'services\api-gateway'; go mod tidy; Set-Location '..\..'
Set-Location 'services\push-gateway'; go mod tidy; Set-Location '..\..'
Set-Location 'services\data-ana'; uv sync; Set-Location '..\..'
Set-Location 'services\ai'; uv sync; Set-Location '..\..'

Write-Host '=== 2. arch.db 同步 ===' -ForegroundColor Cyan
pnpm run arch:scan
pnpm run arch:query -- stats

Write-Host '=== 3. 代码质量校验 ===' -ForegroundColor Cyan
pnpm run lint
pnpm run typecheck

Write-Host '=== 完成 ===' -ForegroundColor Green
Write-Host '注意：project_rules.md 和 004 架构图修复需手动执行（见文档第六、七节）'
```

---

**文档结束。按顺序执行各节任务，遇问题参考第十一节故障排查。**