xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(docs): 修复 project_rules.md P0 损坏并同步所有引用

Browse Source 
- 根目录 project_rules.md 损坏（72 字节乱码），已删除
- 从 CICD 项目迁移完整版至 .trae/rules/project_rules.md（17881 字节）
- 更新 MIGRATION_GUIDE/README/coding-standards 引用至 .trae/rules/
- P0 紧急修复，影响所有 AI 工作流程
This commit is contained in:
SpecialX
2026-07-08 12:50:00 +08:00
parent 4629de1926
commit 3fbb97791d
5 changed files with 644 additions and 242 deletions
Download Patch File Download Diff File Expand all files Collapse all files

341
MIGRATION_GUIDE.md
View File

@@ -5,7 +5,8 @@
> 状态：基线发布
> 维护者：架构组
> 关联文档：
> - [项目规则](./project_rules.md)
>
> - [项目规则](./.trae/rules/project_rules.md)
> - [编码规范](./docs/standards/coding-standards.md)
> - [Git 工作流](./docs/standards/git-workflow.md)
@@ -30,13 +31,13 @@
原始项目 CICD 是基于 Next.js 16 的单应用架构，承载 K12 智慧教务系统 35 个业务模块。随着业务规模扩张与团队增长，单应用架构在以下方面暴露瓶颈：
| 维度 | 单应用瓶颈 | 微服务目标 |
|------|-----------|-----------|
| 团队协作 | 35 模块挤在同一仓库，合并冲突频繁 | 按领域拆分，6 领域团队独立迭代 |
| 部署节奏 | 全量构建发布，单模块变更牵动全站 | 服务粒度独立部署，故障爆炸半径缩小 |
| 维度 | 单应用瓶颈 | 微服务目标 |
| -------- | ---------------------------------- | ------------------------------------------------- |
| 团队协作 | 35 模块挤在同一仓库，合并冲突频繁 | 按领域拆分，6 领域团队独立迭代 |
| 部署节奏 | 全量构建发布，单模块变更牵动全站 | 服务粒度独立部署，故障爆炸半径缩小 |
| 技术选型 | TypeScript 单语言，AI/分析场景受限 | TS（业务）+ Go（网关）+ Python（AI/分析）各取所长 |
| 数据规模 | 单 MySQL，跨模块联表与读放大 | 读写分离 + CQRS，ClickHouse 承载分析负载 |
| 可演进性 | 模块间隐式耦合，重构成本高 | DDD 限界上下文显式契约，演化可控 |
| 数据规模 | 单 MySQL，跨模块联表与读放大 | 读写分离 + CQRS，ClickHouse 承载分析负载 |
| 可演进性 | 模块间隐式耦合，重构成本高 | DDD 限界上下文显式契约，演化可控 |
### 1.2 迁移原则
@@ -52,29 +53,29 @@
### 2.1 基本概况
| 属性 | 值 |
|------|-----|
| 仓库路径 | `e:\Desktop\CICD` |
| 技术栈 | Next.js 16 + React 19 + Tailwind v4 + Drizzle ORM |
| 语言 | TypeScript（全栈） |
| 架构 | 单应用 + 严格模块化（app → modules → shared 三层） |
| 业务模块数 | 35 个 |
| 数据库 | MySQL（单库） |
| 认证 | NextAuth.js |
| 部署 | Gitea Actions + Docker standalone |
| 属性 | 值 |
| ---------- | -------------------------------------------------- |
| 仓库路径 | `e:\Desktop\CICD` |
| 技术栈 | Next.js 16 + React 19 + Tailwind v4 + Drizzle ORM |
| 语言 | TypeScript（全栈） |
| 架构 | 单应用 + 严格模块化（app → modules → shared 三层） |
| 业务模块数 | 35 个 |
| 数据库 | MySQL（单库） |
| 认证 | NextAuth.js |
| 部署 | Gitea Actions + Docker standalone |
### 2.2 模块清单（按领域归类）
| 领域 | 模块 |
|------|------|
| 身份与权限 | auth、users、onboarding、settings、permissions |
| 教学组织 | classes、teachers、students、parents、subjects |
| 教学核心 | courses、lessons、schedule、attendance、leave-requests |
| 考试评价 | exams、questions、grading、scores、analytics |
| 作业内容 | homework、textbooks、resources |
| 沟通通知 | messaging、notifications、announcements |
| 智能辅助 | ai（备课/出题/分析）、search |
| 系统支撑 | audit-logs、reports、dashboard、layout |
| 领域 | 模块 |
| ---------- | ------------------------------------------------------ |
| 身份与权限 | auth、users、onboarding、settings、permissions |
| 教学组织 | classes、teachers、students、parents、subjects |
| 教学核心 | courses、lessons、schedule、attendance、leave-requests |
| 考试评价 | exams、questions、grading、scores、analytics |
| 作业内容 | homework、textbooks、resources |
| 沟通通知 | messaging、notifications、announcements |
| 智能辅助 | ai（备课/出题/分析）、search |
| 系统支撑 | audit-logs、reports、dashboard、layout |
### 2.3 已沉淀的工程资产
@@ -94,17 +95,17 @@
### 3.1 基本概况
| 属性 | 值 |
|------|-----|
| 仓库路径 | `e:\Desktop\Edu` |
| 远程仓库 | https://git.eazygame.cn/xiner/Edu.git |
| 架构范式 | DDD + EDA + CQRS 微服务 |
| 语言 | TypeScript（NestJS 10）+ Go（Gin 网关）+ Python（FastAPI 分析/AI） |
| 前端 | React + Next.js + Module Federation（4 微前端） |
| monorepo 策略 | pnpm workspace + go.work + pyproject.toml (uv) |
| 事件总线 | Kafka + Debezium CDC |
| 契约 | protobuf + buf |
| 存储 | MySQL / Redis / ClickHouse / Neo4j / Elasticsearch |
| 属性 | 值 |
| ------------- | ------------------------------------------------------------------ |
| 仓库路径 | `e:\Desktop\Edu` |
| 远程仓库 | https://git.eazygame.cn/xiner/Edu.git |
| 架构范式 | DDD + EDA + CQRS 微服务 |
| 语言 | TypeScript（NestJS 10）+ Go（Gin 网关）+ Python（FastAPI 分析/AI） |
| 前端 | React + Next.js + Module Federation（4 微前端） |
| monorepo 策略 | pnpm workspace + go.work + pyproject.toml (uv) |
| 事件总线 | Kafka + Debezium CDC |
| 契约 | protobuf + buf |
| 存储 | MySQL / Redis / ClickHouse / Neo4j / Elasticsearch |
### 3.2 整体架构
@@ -164,23 +165,23 @@ flowchart TB
### 3.3 微前端与领域服务映射
| 微前端 | 路由前缀 | 对接 BFF | 主要消费的服务 |
|--------|---------|---------|---------------|
| Admin Shell | `/admin` | Admin BFF | identity、org、insight |
| Teacher Shell | `/teacher` | Teacher BFF | teaching、content、comm |
| Student Shell | `/student` | Student/Parent BFF | teaching、content |
| Parent Shell | `/parent` | Student/Parent BFF | teaching、comm |
| 微前端 | 路由前缀 | 对接 BFF | 主要消费的服务 |
| ------------- | ---------- | ------------------ | ----------------------- |
| Admin Shell | `/admin` | Admin BFF | identity、org、insight |
| Teacher Shell | `/teacher` | Teacher BFF | teaching、content、comm |
| Student Shell | `/student` | Student/Parent BFF | teaching、content |
| Parent Shell | `/parent` | Student/Parent BFF | teaching、comm |
| 微服务 | 原始模块映射 | 主存储 | 对外契约 |
|--------|------------|--------|---------|
| identity | auth、users、onboarding、settings、permissions | MySQL + Redis | identity.proto |
| org | classes、teachers、students、parents、subjects | MySQL | org.proto |
| teaching | courses、lessons、schedule、attendance、leave-requests、exams、homework | MySQL | teaching.proto |
| content | textbooks、resources、questions、grading | MySQL + Elasticsearch | content.proto |
| comm | messaging、notifications、announcements | MySQL + Redis | comm.proto |
| insight | scores、analytics、ai、search、reports、dashboard | ClickHouse + Neo4j | insight.proto |
| auth（基础设施） | NextAuth 逻辑下沉 | MySQL + Redis | auth.proto |
| notification（基础设施） | notifications channel 抽离 | MySQL + Redis | notification.proto |
| 微服务 | 原始模块映射 | 主存储 | 对外契约 |
| ------------------------ | ----------------------------------------------------------------------- | --------------------- | ------------------ |
| identity | auth、users、onboarding、settings、permissions | MySQL + Redis | identity.proto |
| org | classes、teachers、students、parents、subjects | MySQL | org.proto |
| teaching | courses、lessons、schedule、attendance、leave-requests、exams、homework | MySQL | teaching.proto |
| content | textbooks、resources、questions、grading | MySQL + Elasticsearch | content.proto |
| comm | messaging、notifications、announcements | MySQL + Redis | comm.proto |
| insight | scores、analytics、ai、search、reports、dashboard | ClickHouse + Neo4j | insight.proto |
| auth（基础设施） | NextAuth 逻辑下沉 | MySQL + Redis | auth.proto |
| notification（基础设施） | notifications channel 抽离 | MySQL + Redis | notification.proto |
---
@@ -190,65 +191,65 @@ flowchart TB
### 4.1 规范类资产
| 资产 | 策略 | 说明 |
|------|------|------|
| 项目规则（project_rules） | 调整 | 架构图优先保留，分层规则从三层改为微服务分层，新增 DDD/契约/事件驱动规则 |
| 编码规范（coding-standards） | 调整 | TS 部分保留并补充 NestJS 装饰器/DI 规则，新增 Go、Python、protobuf 章节 |
| Git 工作流 | 调整 | trunk-based 替代分支策略，scope 改为服务/包名，新增多语言 monorepo 提交规则 |
| 提交规范（Conventional Commits） | 直接迁移 | 类型与格式完全沿用 |
| 设计令牌规范 | 调整 | 分层模型保留，分布位置从 `src/app/styles/tokens/` 改为微前端共享包 |
| 安全规范 | 直接迁移 | Cookie 策略、env 校验、XSS 防护、权限校验规则全部沿用 |
| 问题记录规则 | 直接迁移 | known-issues.md 索引式速查手册模式沿用 |
| A11y 规范 | 直接迁移 | WCAG 2.2 AA 目标与工具集沿用 |
| 资产 | 策略 | 说明 |
| -------------------------------- | -------- | --------------------------------------------------------------------------- |
| 项目规则（project_rules） | 调整 | 架构图优先保留，分层规则从三层改为微服务分层，新增 DDD/契约/事件驱动规则 |
| 编码规范（coding-standards） | 调整 | TS 部分保留并补充 NestJS 装饰器/DI 规则，新增 Go、Python、protobuf 章节 |
| Git 工作流 | 调整 | trunk-based 替代分支策略，scope 改为服务/包名，新增多语言 monorepo 提交规则 |
| 提交规范（Conventional Commits） | 直接迁移 | 类型与格式完全沿用 |
| 设计令牌规范 | 调整 | 分层模型保留，分布位置从 `src/app/styles/tokens/` 改为微前端共享包 |
| 安全规范 | 直接迁移 | Cookie 策略、env 校验、XSS 防护、权限校验规则全部沿用 |
| 问题记录规则 | 直接迁移 | known-issues.md 索引式速查手册模式沿用 |
| A11y 规范 | 直接迁移 | WCAG 2.2 AA 目标与工具集沿用 |
### 4.2 代码类资产
| 资产 | 策略 | 说明 |
|------|------|------|
| Zod schema 定义 | 直接迁移 | 各模块 schema.ts 平移至对应微服务，复用验证规则 |
| 权限点常量（Permissions） | 直接迁移 | 集中迁入 identity 服务共享包 |
| Drizzle schema（表结构） | 调整 | 按领域拆分到各微服务独占库，关系型字段保持不变 |
| ActionState 类型 | 直接迁移 | 升级为 protobuf message，结构不变 |
| Server Actions | 重写 | 改写为 NestJS Controller + Service + Application Service 三层 |
| data-access 层 | 重写 | 改写为 NestJS Repository + Domain Entity |
| UI 组件（shared/components） | 直接迁移 | 平移至微前端共享包，保持 PascalCase 命名 |
| Hook（useAuth、usePermission） | 调整 | 改为通过 BFF/gRPC client 获取，接口签名保持不变 |
| 缓存层（cacheFn） | 重写 | 改为 NestJS Cache 模块 + Redis，去除 React cache() |
| arch:scan 工具 | 调整 | 扫描器扩展为多语言（TS+Go+Python），数据库结构保持 |
| 审计日志三件套 | 直接迁移 | 平移至 notification 服务，日志结构保持 |
| CI/CD 流水线 | 重写 | Gitea Actions 改为多服务并行流水线，新增契约校验阶段 |
| 资产 | 策略 | 说明 |
| ------------------------------ | -------- | ------------------------------------------------------------- |
| Zod schema 定义 | 直接迁移 | 各模块 schema.ts 平移至对应微服务，复用验证规则 |
| 权限点常量（Permissions） | 直接迁移 | 集中迁入 identity 服务共享包 |
| Drizzle schema（表结构） | 调整 | 按领域拆分到各微服务独占库，关系型字段保持不变 |
| ActionState 类型 | 直接迁移 | 升级为 protobuf message，结构不变 |
| Server Actions | 重写 | 改写为 NestJS Controller + Service + Application Service 三层 |
| data-access 层 | 重写 | 改写为 NestJS Repository + Domain Entity |
| UI 组件（shared/components） | 直接迁移 | 平移至微前端共享包，保持 PascalCase 命名 |
| Hook（useAuth、usePermission） | 调整 | 改为通过 BFF/gRPC client 获取，接口签名保持不变 |
| 缓存层（cacheFn） | 重写 | 改为 NestJS Cache 模块 + Redis，去除 React cache() |
| arch:scan 工具 | 调整 | 扫描器扩展为多语言（TS+Go+Python），数据库结构保持 |
| 审计日志三件套 | 直接迁移 | 平移至 notification 服务，日志结构保持 |
| CI/CD 流水线 | 重写 | Gitea Actions 改为多服务并行流水线，新增契约校验阶段 |
### 4.3 文档类资产
| 资产 | 策略 | 说明 |
|------|------|------|
| 架构影响地图（004） | 重写 | 从单应用模块图改为微服务限界上下文图 |
| K12 功能清单（006） | 直接迁移 | 功能清单与架构无关，直接平移 |
| 差距审计报告（007） | 调整 | 重新审计各微服务的功能完成度 |
| 模块角色映射（008） | 直接迁移 | 角色权限矩阵不变 |
| 路线图（roadmap/） | 重写 | 6 阶段微服务路线图 |
| known-issues.md | 直接迁移 | 经验日志平移，新增"微服务"分区 |
| 各模块 README | 重写 | 改为各微服务 README，按 DDD 上下文描述 |
| 资产 | 策略 | 说明 |
| ------------------- | -------- | -------------------------------------- |
| 架构影响地图（004） | 重写 | 从单应用模块图改为微服务限界上下文图 |
| K12 功能清单（006） | 直接迁移 | 功能清单与架构无关，直接平移 |
| 差距审计报告（007） | 调整 | 重新审计各微服务的功能完成度 |
| 模块角色映射（008） | 直接迁移 | 角色权限矩阵不变 |
| 路线图（roadmap/） | 重写 | 6 阶段微服务路线图 |
| known-issues.md | 直接迁移 | 经验日志平移，新增"微服务"分区 |
| 各模块 README | 重写 | 改为各微服务 README，按 DDD 上下文描述 |
---
## 五、文档体系映射表
| CICD 文档 | Edu 对应文档 | 关系 |
|-----------|------------|------|
| `.trae/rules/project_rules.md` | `project_rules.md` | 调整（微服务版） |
| `docs/standards/coding-standards.md` | `docs/standards/coding-standards.md` | 调整（多语言版） |
| —（散落在 project_rules） | `docs/standards/git-workflow.md` | 新建 |
| `docs/architecture/004_architecture_impact_map.md` | `docs/architecture/001_architecture_overview.md` | 重写 |
| `docs/architecture/006_k12_feature_checklist.md` | `docs/architecture/feature_checklist.md` | 直接迁移 |
| `docs/architecture/007_gap_audit_report.md` | `docs/architecture/gap_audit.md` | 调整 |
| `docs/architecture/008_module_role_mapping.md` | `docs/architecture/role_mapping.md` | 直接迁移 |
| `docs/architecture/roadmap/README.md` | `docs/architecture/roadmap/README.md` | 重写 |
| `docs/architecture/roadmap/tech-debt.md` | `docs/architecture/roadmap/tech-debt.md` | 重写 |
| `docs/architecture/roadmap/decoupling.md` | `docs/architecture/roadmap/migration_phases.md` | 重写（迁移阶段化） |
| `docs/troubleshooting/known-issues.md` | `docs/troubleshooting/known-issues.md` | 直接迁移 + 新分区 |
| `src/modules/[module]/README.md` | `services/[service]/README.md` | 重写 |
| `docs/standards/coding-standards.md` §A11y | `docs/standards/accessibility.md` | 拆分独立 |
| CICD 文档 | Edu 对应文档 | 关系 |
| -------------------------------------------------- | ------------------------------------------------ | ------------------ |
| `.trae/rules/project_rules.md` | `project_rules.md` | 调整（微服务版） |
| `docs/standards/coding-standards.md` | `docs/standards/coding-standards.md` | 调整（多语言版） |
| —（散落在 project_rules） | `docs/standards/git-workflow.md` | 新建 |
| `docs/architecture/004_architecture_impact_map.md` | `docs/architecture/001_architecture_overview.md` | 重写 |
| `docs/architecture/006_k12_feature_checklist.md` | `docs/architecture/feature_checklist.md` | 直接迁移 |
| `docs/architecture/007_gap_audit_report.md` | `docs/architecture/gap_audit.md` | 调整 |
| `docs/architecture/008_module_role_mapping.md` | `docs/architecture/role_mapping.md` | 直接迁移 |
| `docs/architecture/roadmap/README.md` | `docs/architecture/roadmap/README.md` | 重写 |
| `docs/architecture/roadmap/tech-debt.md` | `docs/architecture/roadmap/tech-debt.md` | 重写 |
| `docs/architecture/roadmap/decoupling.md` | `docs/architecture/roadmap/migration_phases.md` | 重写（迁移阶段化） |
| `docs/troubleshooting/known-issues.md` | `docs/troubleshooting/known-issues.md` | 直接迁移 + 新分区 |
| `src/modules/[module]/README.md` | `services/[service]/README.md` | 重写 |
| `docs/standards/coding-standards.md` §A11y | `docs/standards/accessibility.md` | 拆分独立 |
---
@@ -283,14 +284,14 @@ gantt
### 6.2 各阶段目标
| 阶段 | 名称 | 目标 | 关键交付物 | 验收信号 |
|------|------|------|-----------|---------|
| P1 | 地基 | 仓库骨架、契约工具链、CI、可观测平台 | monorepo 结构、buf 配置、Kafka 集群、OpenTelemetry | 契约生成 + 一次端到端 trace |
| P2 | 身份 | identity + auth + notification 三服务打通 | JWT 颁发、RBAC、邮件/短信/站内通知 | 用户注册→登录→收到通知 |
| P3 | 核心教学 | org + teaching + content | 班级/课表/作业/题库/考试 | 教师创建作业→学生提交→批改闭环 |
| P4 | 内容分析 | insight + CQRS 读模型 + ES 全文检索 | ClickHouse 报表、ES 搜索、Neo4j 知识图谱 | 多维分析报表 + 全文搜索可用 |
| P5 | 沟通AI | comm + AI 辅助 | 站内信/通知中心、AI 备课/出题/答疑 | 教师用 AI 出题并发布到班级 |
| P6 | 硬化 | 安全加固、灾备、性能、混沌工程 | WAF、定期备份、压测报告、混沌演练 | RPO≤15min、RTO≤30min、P99≤500ms |
| 阶段 | 名称 | 目标 | 关键交付物 | 验收信号 |
| ---- | -------- | ----------------------------------------- | -------------------------------------------------- | ------------------------------- |
| P1 | 地基 | 仓库骨架、契约工具链、CI、可观测平台 | monorepo 结构、buf 配置、Kafka 集群、OpenTelemetry | 契约生成 + 一次端到端 trace |
| P2 | 身份 | identity + auth + notification 三服务打通 | JWT 颁发、RBAC、邮件/短信/站内通知 | 用户注册→登录→收到通知 |
| P3 | 核心教学 | org + teaching + content | 班级/课表/作业/题库/考试 | 教师创建作业→学生提交→批改闭环 |
| P4 | 内容分析 | insight + CQRS 读模型 + ES 全文检索 | ClickHouse 报表、ES 搜索、Neo4j 知识图谱 | 多维分析报表 + 全文搜索可用 |
| P5 | 沟通AI | comm + AI 辅助 | 站内信/通知中心、AI 备课/出题/答疑 | 教师用 AI 出题并发布到班级 |
| P6 | 硬化 | 安全加固、灾备、性能、混沌工程 | WAF、定期备份、压测报告、混沌演练 | RPO≤15min、RTO≤30min、P99≤500ms |
### 6.3 阶段交付门槛
@@ -310,15 +311,16 @@ gantt
**复用方式**：将 CICD 的 `src/app/styles/tokens/` 五层分层模型平移至微前端共享包。
| CICD 位置 | Edu 位置 | 调整 |
|-----------|---------|------|
| `src/app/styles/tokens/primitive.css` | `packages/ui-tokens/primitive.css` | 直接平移 |
| `src/app/styles/tokens/semantic-light.css` | `packages/ui-tokens/semantic-light.css` | 直接平移 |
| `src/app/styles/tokens/semantic-dark.css` | `packages/ui-tokens/semantic-dark.css` | 直接平移 |
| CICD 位置 | Edu 位置 | 调整 |
| ---------------------------------------------- | ------------------------------------------- | -------- |
| `src/app/styles/tokens/primitive.css` | `packages/ui-tokens/primitive.css` | 直接平移 |
| `src/app/styles/tokens/semantic-light.css` | `packages/ui-tokens/semantic-light.css` | 直接平移 |
| `src/app/styles/tokens/semantic-dark.css` | `packages/ui-tokens/semantic-dark.css` | 直接平移 |
| `src/app/styles/tokens/lesson-preparation.css` | `packages/ui-tokens/lesson-preparation.css` | 直接平移 |
| `src/app/styles/tokens/tailwind-theme.css` | `packages/ui-tokens/tailwind-theme.css` | 直接平移 |
| `src/app/styles/tokens/tailwind-theme.css` | `packages/ui-tokens/tailwind-theme.css` | 直接平移 |
**强制规则保持不变**：
- 禁止硬编码颜色（`#hex`）
- 禁止硬编码字体（`'Inter'`/`'Fraunces'`/`'JetBrains Mono'`）
- 禁止硬编码字号（`font-size: Npx`）
@@ -329,14 +331,15 @@ gantt
**复用方式**：将 CICD 的 `src/shared/components/ui/` 平移至 `packages/ui-components/`，作为 Module Federation 共享依赖。
| 组件类别 | CICD 路径 | Edu 路径 | 复用要点 |
|---------|----------|---------|---------|
| 基础组件（Button/Input/Dialog） | `shared/components/ui/` | `packages/ui-components/` | 全部平移，保持 PascalCase 命名 |
| A11y 组件 | `shared/components/a11y/` | `packages/ui-components/a11y/` | skip-link、visually-hidden、focus-trap、aria-status 全部平移 |
| 图表组件 | 各模块内 | `packages/ui-components/charts/` | 收集 recharts 封装，统一暴露 |
| 表单组件 | react-hook-form 封装 | `packages/ui-components/form/` | 与 zod resolver 一同平移 |
| 组件类别 | CICD 路径 | Edu 路径 | 复用要点 |
| ------------------------------- | ------------------------- | -------------------------------- | ------------------------------------------------------------ |
| 基础组件（Button/Input/Dialog） | `shared/components/ui/` | `packages/ui-components/` | 全部平移，保持 PascalCase 命名 |
| A11y 组件 | `shared/components/a11y/` | `packages/ui-components/a11y/` | skip-link、visually-hidden、focus-trap、aria-status 全部平移 |
| 图表组件 | 各模块内 | `packages/ui-components/charts/` | 收集 recharts 封装，统一暴露 |
| 表单组件 | react-hook-form 封装 | `packages/ui-components/form/` | 与 zod resolver 一同平移 |
**复用规则**：
- 组件必须为纯函数，使用 `function` 声明
- 不使用 `React.FC`，直接用函数声明 + 显式标注 props 类型
- 默认服务端组件（微前端 host），需要交互时才添加 `"use client"`
@@ -346,14 +349,15 @@ gantt
**复用方式**：将 CICD 的 `requirePermission()` + `usePermission().hasPermission()` 模式平移至 identity 服务 + auth 基础设施服务。
| CICD 资产 | Edu 位置 | 调整 |
|-----------|---------|------|
| `shared/lib/auth-guard.ts`（requirePermission） | `services/auth/src/guards/permission.guard.ts`（NestJS Guard） | 改为 NestJS Guard 装饰器 |
| `shared/types/permissions.ts`（权限点常量） | `packages/contracts/src/permissions.ts` | 集中到 contracts 包，多服务共享 |
| `usePermission` Hook | `packages/ui-components/hooks/use-permission.ts` | 通过 BFF 拉取权限，Hook 接口不变 |
| 角色权限矩阵（008） | `docs/architecture/role_mapping.md` | 直接平移 |
| CICD 资产 | Edu 位置 | 调整 |
| ----------------------------------------------- | -------------------------------------------------------------- | -------------------------------- |
| `shared/lib/auth-guard.ts`（requirePermission） | `services/auth/src/guards/permission.guard.ts`（NestJS Guard） | 改为 NestJS Guard 装饰器 |
| `shared/types/permissions.ts`（权限点常量） | `packages/contracts/src/permissions.ts` | 集中到 contracts 包，多服务共享 |
| `usePermission` Hook | `packages/ui-components/hooks/use-permission.ts` | 通过 BFF 拉取权限，Hook 接口不变 |
| 角色权限矩阵（008） | `docs/architecture/role_mapping.md` | 直接平移 |
**强制规则保持不变**：
- 每个 Controller/Action 必须调用 `requirePermission()` 等价物
- 前端组件禁止使用 `role === "xxx"` 硬编码，统一使用 `usePermission().hasPermission()`
@@ -361,36 +365,36 @@ gantt
**复用方式**：CICD 的 `cacheFn`（React `cache()` + 自定义缓存层）改为 NestJS Cache 模块 + Redis，**权限数据不跨请求缓存**的规则沿用。
| CICD 模式 | Edu 模式 | 备注 |
|-----------|---------|------|
| CICD 模式 | Edu 模式 | 备注 |
| ------------------------ | --------------------------------------------------- | ------------------------------------- |
| `cacheFn`（React cache） | NestJS `@UseInterceptors(CacheInterceptor)` + Redis | 单请求内缓存改为 NestJS REQUEST scope |
| `unstable_cache` | 禁用 | CICD 已禁用，Edu 沿用禁用决策 |
| 权限数据缓存 | 仅在 auth 服务内部缓存，TTL ≤ 60s | 跨服务不缓存权限 |
| 静态资源缓存 | CDN + 短缓存 | 配置不变 |
| `unstable_cache` | 禁用 | CICD 已禁用，Edu 沿用禁用决策 |
| 权限数据缓存 | 仅在 auth 服务内部缓存，TTL ≤ 60s | 跨服务不缓存权限 |
| 静态资源缓存 | CDN + 短缓存 | 配置不变 |
### 7.5 Server Action 模式 → Application Service 模式
**复用方式**：CICD 的 Server Action 编排模式（权限 + Zod 验证 + 调用 data-access + revalidate）平移为 NestJS Application Service 编排模式。
| CICD Server Action 步骤 | NestJS Application Service 对应 |
|------------------------|-------------------------------|
| `requirePermission(perm)` | `@RequirePermission(perm)` 装饰器 + Guard |
| Zod `safeParse` | `ValidationPipe` + DTO class-validator |
| 调用 `data-access` | 调用 Domain Service / Repository |
| `revalidatePath` | 发布领域事件触发读模型更新 |
| 返回 `ActionState<T>` | 返回 protobuf message（结构同 ActionState） |
| CICD Server Action 步骤 | NestJS Application Service 对应 |
| ------------------------- | ------------------------------------------- |
| `requirePermission(perm)` | `@RequirePermission(perm)` 装饰器 + Guard |
| Zod `safeParse` | `ValidationPipe` + DTO class-validator |
| 调用 `data-access` | 调用 Domain Service / Repository |
| `revalidatePath` | 发布领域事件触发读模型更新 |
| 返回 `ActionState<T>` | 返回 protobuf message（结构同 ActionState） |
### 7.6 状态管理 5 层模型
**复用方式**：CICD 的 5 层状态模型平移至微前端 host 应用。
| 层级 | CICD 方案 | Edu 方案 | 备注 |
|------|----------|---------|------|
| L1 URL | nuqs | nuqs | 直接平移 |
| L2 Server | TanStack Query | TanStack Query | 直接平移 |
| L3 Client Business | Zustand slice | Zustand slice | 直接平移 |
| L4 Global UI | Zustand ui-store + ModalRoot | Zustand ui-store + ModalRoot | 直接平移 |
| L5 Form | react-hook-form + zodResolver | react-hook-form + zodResolver | 直接平移 |
| 层级 | CICD 方案 | Edu 方案 | 备注 |
| ------------------ | ----------------------------- | ----------------------------- | -------- |
| L1 URL | nuqs | nuqs | 直接平移 |
| L2 Server | TanStack Query | TanStack Query | 直接平移 |
| L3 Client Business | Zustand slice | Zustand slice | 直接平移 |
| L4 Global UI | Zustand ui-store + ModalRoot | Zustand ui-store + ModalRoot | 直接平移 |
| L5 Form | react-hook-form + zodResolver | react-hook-form + zodResolver | 直接平移 |
### 7.7 A11y 工具集
@@ -409,23 +413,24 @@ gantt
**复用方式**：平移至 notification 服务，日志结构保持。
| CICD 资产 | Edu 位置 | 备注 |
|-----------|---------|------|
| `shared/lib/login-logger.ts` | `services/notification/src/loggers/login-logger.ts` | 登录尝试日志 |
| CICD 资产 | Edu 位置 | 备注 |
| ----------------------------- | ---------------------------------------------------- | ---------------------------- |
| `shared/lib/login-logger.ts` | `services/notification/src/loggers/login-logger.ts` | 登录尝试日志 |
| `shared/lib/change-logger.ts` | `services/notification/src/loggers/change-logger.ts` | 数据变更日志（监听领域事件） |
| `shared/lib/audit-logger.ts` | `services/notification/src/loggers/audit-logger.ts` | 关键业务操作日志 |
| `shared/lib/audit-logger.ts` | `services/notification/src/loggers/audit-logger.ts` | 关键业务操作日志 |
### 7.9 CI/CD 流水线模式
**复用方式**：三套工作流模式沿用（CI + 安全扫描 + 灾备演练），但执行方式改为多服务并行。
| CICD 工作流 | Edu 工作流 | 调整 |
|------------|-----------|------|
| `ci.yml` | `.gitea/workflows/ci.yml` | 单体改为矩阵并行（每个服务一个 job） |
| `security.yml` | `.gitea/workflows/security.yml` | 新增 Trivy 扫描 Docker 镜像 |
| `dr-drill.yml` | `.gitea/workflows/dr-drill.yml` | 灾备演练改为多服务恢复顺序演练 |
| CICD 工作流 | Edu 工作流 | 调整 |
| -------------- | ------------------------------- | ------------------------------------ |
| `ci.yml` | `.gitea/workflows/ci.yml` | 单体改为矩阵并行（每个服务一个 job） |
| `security.yml` | `.gitea/workflows/security.yml` | 新增 Trivy 扫描 Docker 镜像 |
| `dr-drill.yml` | `.gitea/workflows/dr-drill.yml` | 灾备演练改为多服务恢复顺序演练 |
**CI 必须包含**（沿用 CICD 规则）：
1. 安装依赖（多语言：pnpm install / go mod download / uv sync）
2. Lint 检查（ESLint + golangci-lint + ruff）
3. 类型检查（tsc --noEmit + go vet + mypy）
@@ -478,15 +483,15 @@ gantt
## 附录：迁移过程中的关键决策点
| 决策点 | 选择 | 理由 |
|--------|------|------|
| 服务拆分粒度 | 6 业务 + 2 基础设施 | 平衡团队规模与拆分收益，避免过细导致 RPC 开销 |
| 通信协议 | gRPC（内部）+ REST（BFF 对外） | 内部高性能，外部兼容性 |
| 事件总线 | Kafka + Debezium CDC | CDC 减少业务代码侵入，Outbox 模式保证一致性 |
| 契约工具 | protobuf + buf | 多语言代码生成，breaking change 检测 |
| 前端架构 | Module Federation | 微前端独立部署，运行时共享依赖 |
| 状态管理 | 沿用 5 层模型 | 团队熟悉度高，迁移成本低 |
| 数据库拆分 | 每服务独占库 | 杜绝跨服务联表，强制契约化通信 |
| 缓存策略 | NestJS Cache + Redis | 替代 React cache()，规则（权限不跨请求缓存）沿用 |
| 迁移方式 | strangler fig | 风险可控，渐进式切换 |
| arch.db | 多语言扫描扩展 | 复用 CICD 元数据库思路，扩展 Go/Python 扫描器 |
| 决策点 | 选择 | 理由 |
| ------------ | ------------------------------ | ------------------------------------------------ |
| 服务拆分粒度 | 6 业务 + 2 基础设施 | 平衡团队规模与拆分收益，避免过细导致 RPC 开销 |
| 通信协议 | gRPC（内部）+ REST（BFF 对外） | 内部高性能，外部兼容性 |
| 事件总线 | Kafka + Debezium CDC | CDC 减少业务代码侵入，Outbox 模式保证一致性 |
| 契约工具 | protobuf + buf | 多语言代码生成，breaking change 检测 |
| 前端架构 | Module Federation | 微前端独立部署，运行时共享依赖 |
| 状态管理 | 沿用 5 层模型 | 团队熟悉度高，迁移成本低 |
| 数据库拆分 | 每服务独占库 | 杜绝跨服务联表，强制契约化通信 |
| 缓存策略 | NestJS Cache + Redis | 替代 React cache()，规则（权限不跨请求缓存）沿用 |
| 迁移方式 | strangler fig | 风险可控，渐进式切换 |
| arch.db | 多语言扫描扩展 | 复用 CICD 元数据库思路，扩展 Go/Python 扫描器 |