beedbaf686
- known-issues.md: 追加 9 条 P6 工作经验日志，更新 arch-scan 经验 - post-p6-followup.md: 新增 P6 后续工作手册 runbook - iam/core-edu/content/msg README: 补充健康检查端点说明
31 KiB
31 KiB
P6 后续工作手册
版本：1.0 日期：2026-07-08 状态：待执行 执行环境：
e:\Desktop\Edu维护者：架构组 关联文档：
- 004 架构影响地图
- 项目规则（已修复，迁至
.trae/rules/）- 迁移指南
- P6 硬化 Runbook
目录
- 执行前必读
- 环境准备
- 依赖安装
- 代码质量校验
- arch.db 同步
- 修复 project_rules.md（P0 紧急）
- 修复 004 架构图
- P6 集成测试补充
- Helm Chart 演化
- 文档同步
- 故障排查
- 验收清单
一、执行前必读
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.0github.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 lint0 errorspnpm run typecheck0 errorsgo vet ./...（api-gateway、push-gateway）0 errorsruff 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 架构图修复需手动执行（见文档第六、七节）'
文档结束。按顺序执行各节任务，遇问题参考第十一节故障排查。