Edu/docs/architecture/runbooks/post-p6-followup.md

P6 后续工作手册

版本：1.0 日期：2026-07-08 状态：待执行 执行环境：e:\Desktop\Edu 维护者：架构组 关联文档：

• 004 架构影响地图
• 项目规则（已修复，迁至 .trae/rules/）
• 迁移指南
• P6 硬化 Runbook

---

目录

1. 执行前必读
2. 环境准备
3. 依赖安装
4. 代码质量校验
5. arch.db 同步
6. 修复 project_rules.md（P0 紧急）
7. 修复 004 架构图
8. P6 集成测试补充
9. Helm Chart 演化
10. 文档同步
11. 故障排查
12. 验收清单

---

一、执行前必读

1.1 工作目录

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

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（如未安装）

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

2.2 安装 Go（如未安装）

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（如未安装）

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

2.4 配置镜像加速（推荐）

# 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）

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

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

验证：

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

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

# 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 服务独立）

# 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 工具链（可选，如需重新生成代码）

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

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

---

四、代码质量校验

4.1 TypeScript 校验

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

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

4.2 Go 校验

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 校验

# 安装 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 扫描代码结构

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

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

5.2 验证扫描结果

# 查询统计
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 查询示例

# 查询所有服务
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 执行步骤

# 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 版调整）：

# 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 验证

# 验证文件存在且内容完整
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 图：

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 视口四层模型：

### 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 执行步骤

# 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

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

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

#!/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 执行测试

# 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 执行步骤

# 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

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

### 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 下临时文件路径问题。

解决：

# 设置环境变量
$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 字段冲突。

解决：

# 检查 .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

解决：

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

11.4 uv sync 失败

错误：error: Failed to download ...

解决：

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

11.5 arch:scan 报错

错误：Error: Cannot find module 'tsx'

解决：

# 确保 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 脚本：

# 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 架构图修复需手动执行（见文档第六、七节）'

---

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