docs: git-workflow v1.1 与 CODEOWNERS 规范

- git-workflow.md v1.1: scope-enum 对齐实际服务名（identity→iam 等） - git-workflow.md: 新增 §4.7 模块 Owner 与 CODEOWNERS 章节 - git-workflow.md: husky hooks 与实际文件对齐，新增 pre-push 说明 - .github/CODEOWNERS: 定义各模块 owner team 与 PR 合并职责 - .github/pull_request_template.md: PR 模板
2026-07-08 12:53:18 +08:00
parent beedbaf686
commit b39095cbdd
3 changed files with 398 additions and 197 deletions
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -0,0 +1,80 @@
+# Edu 平台 CODEOWNERS
+# 格式：路径  @owner
+# 作用：GitHub/Gitea 自动为 PR 分配 reviewer
+# 维护规则：
+#   1. 新增服务/包时，必须同步更新本文件
+#   2. owner 变更需开独立 PR，由架构组审批
+#   3. 与 docs/standards/git-workflow.md §4.7 保持同步
+# Team handle 占位符：@edu-platform/* 需在 Organization 中创建对应 team 后替换
+
+# ===== 架构与规则（架构组，2 人 review）=====
+/.trae/                    @edu-platform/arch
+/docs/architecture/        @edu-platform/arch
+/docs/standards/           @edu-platform/arch
+/scripts/arch-scan/        @edu-platform/arch
+
+# ===== 根配置（架构组，2 人 review，影响全局）=====
+/.commitlintrc.js          @edu-platform/arch
+/lint-staged.config.js     @edu-platform/arch
+/package.json              @edu-platform/arch
+/pnpm-workspace.yaml       @edu-platform/arch
+/go.work                   @edu-platform/arch
+/pyproject.toml            @edu-platform/arch
+/tsconfig.base.json        @edu-platform/arch
+
+# ===== 共享包（架构组，2 人 review，契约变更影响所有服务）=====
+/packages/shared-proto/    @edu-platform/arch
+/packages/shared-ts/       @edu-platform/arch
+/packages/shared-go/       @edu-platform/arch
+/packages/shared-py/       @edu-platform/arch
+/packages/shared-tokens/   @edu-platform/arch
+
+# ===== 网关层（Go）=====
+/services/api-gateway/     @edu-platform/gateway
+/services/push-gateway/    @edu-platform/gateway
+
+# ===== 业务微服务 =====
+# IAM（核心模块，2 人 review）
+/services/iam/             @edu-platform/iam
+# 教学核心
+/services/core-edu/        @edu-platform/edu-core
+/services/classes/         @edu-platform/edu-core
+# 内容资源
+/services/content/         @edu-platform/content
+# 消息通知
+/services/msg/             @edu-platform/messaging
+# 数据分析（Python）
+/services/data-ana/        @edu-platform/data
+# AI 网关（Python）
+/services/ai/              @edu-platform/ai
+
+# ===== BFF 聚合层（NestJS）=====
+/services/teacher-bff/     @edu-platform/edu-core
+/services/student-bff/     @edu-platform/edu-core
+/services/parent-bff/      @edu-platform/edu-core
+
+# ===== 微前端（Next.js）=====
+/apps/teacher-portal/      @edu-platform/frontend
+/apps/student-portal/      @edu-platform/frontend
+/apps/parent-portal/       @edu-platform/frontend
+/apps/admin-portal/        @edu-platform/frontend
+
+# ===== 基础设施（SRE，2 人 review，生产环境变更强制）=====
+/infra/k8s/                @edu-platform/sre
+/infra/backup/             @edu-platform/sre
+/infra/security/           @edu-platform/sre
+/infra/monitoring/         @edu-platform/sre
+/infra/docker-compose*.yml @edu-platform/sre
+
+# ===== CI/CD（SRE）=====
+/.github/                  @edu-platform/sre
+/.husky/                   @edu-platform/sre
+
+# ===== 文档（架构组）=====
+/docs/troubleshooting/     @edu-platform/arch
+/MIGRATION_GUIDE.md        @edu-platform/arch
+/README.md                 @edu-platform/arch
+/CHANGELOG.md              @edu-platform/arch
+
+# ===== 兜底（未匹配的文件由架构组 review）=====
+*                          @edu-platform/arch
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -0,0 +1,55 @@
+## 变更说明
+
+<!-- 简述本次变更的目的和实现方式 -->
+
+## 变更类型
+
+- [ ] feat: 新功能
+- [ ] fix: Bug 修复
+- [ ] perf: 性能优化
+- [ ] refactor: 重构
+- [ ] test: 测试
+- [ ] docs: 文档
+- [ ] build/ci: 构建/CI
+- [ ] chore: 杂项
+
+## 影响范围
+
+<!-- 列出受影响的服务/包 -->
+
+- 服务：
+- 包：
+- 数据库迁移：是 / 否
+- protobuf 契约变更：是 / 否（如变更是否向后兼容）
+- Kafka topic 变更：是 / 否
+- 架构文档变更：是 / 否
+
+## 测试情况
+
+- [ ] 单元测试通过
+- [ ] 集成测试通过
+- [ ] 本地手动测试通过
+- [ ] 新增测试覆盖新功能
+
+### 按语言的校验结果
+
+- TS 服务：`pnpm run lint` + `pnpm run typecheck`（如缺失脚本请说明）
+- Go 服务：`go vet ./...` + `go build ./...`
+- Python 服务：`ruff check src/`
+
+## 文档同步
+
+- [ ] 已更新服务 README（如涉及服务结构变更）
+- [ ] 已更新架构文档（如涉及架构变更）
+- [ ] 已运行 `pnpm run arch:scan` 更新 arch.db（arch.db 不入库，但本地验证必须通过）
+- [ ] 已更新 `docs/troubleshooting/known-issues.md`（如遇到新问题/经验）
+- [ ] 已更新 `.github/CODEOWNERS`（如新增服务/包）
+
+## Breaking Change
+
+- [ ] 否
+- [ ] 是（请在下方说明影响和迁移路径）
+
+## 关联 Issue
+
+Closes #
--- a/docs/standards/git-workflow.md
+++ b/docs/standards/git-workflow.md
@@ -1,11 +1,12 @@
 # Edu Git 工作流规范

-> 版本：1.0
-> 日期：2026-07-07
-> 状态：基线发布
+> 版本：1.1
+> 日期：2026-07-08
+> 状态：基线发布（v1.1：scope-enum 对齐 + CODEOWNERS）
 > 适用范围：Edu 多语言 monorepo（pnpm workspace + go.work + pyproject.toml）
 > 关联文档：
-> - [项目规则](../../project_rules.md)
+>
+> - [项目规则](../../.trae/rules/project_rules.md)
 > - [编码规范](./coding-standards.md)
 > - [迁移指南](../../MIGRATION_GUIDE.md)
 > - [架构总览](../architecture/001_architecture_overview.md)
@@ -33,6 +34,7 @@
 本项目采用**主干开发**模式，所有变更最终合并至 `main` 分支。

 **核心原则**：
+
 - `main` 分支始终保持可发布状态
 - 短生命周期特性分支（通常 ≤ 3 天）
 - 频繁集成，每天至少一次 rebase/merge 至最新 `main`
@@ -66,18 +68,19 @@ gitGraph

 ### 1.3 分支命名规范

-| 分支类型 | 前缀 | 示例 | 生命周期 |
-|---------|------|------|---------|
-| 主干 | `main` | `main` | 永久 |
-| 特性 | `feat/` | `feat/identity-service` | ≤ 3 天 |
-| 修复 | `fix/` | `fix/jwt-expiry` | ≤ 1 天 |
-| 重构 | `refactor/` | `refactor/split-data-access` | ≤ 5 天 |
-| 性能 | `perf/` | `perf/query-optimization` | ≤ 3 天 |
-| 文档 | `docs/` | `docs/api-specification` | ≤ 2 天 |
-| 发布 | `release/v` | `release/v0.3.0` | 发布周期内 |
-| 热修复 | `hotfix/` | `hotfix/v0.3.1` | ≤ 1 天 |
+| 分支类型 | 前缀        | 示例                         | 生命周期   |
+| -------- | ----------- | ---------------------------- | ---------- |
+| 主干     | `main`      | `main`                       | 永久       |
+| 特性     | `feat/`     | `feat/identity-service`      | ≤ 3 天     |
+| 修复     | `fix/`      | `fix/jwt-expiry`             | ≤ 1 天     |
+| 重构     | `refactor/` | `refactor/split-data-access` | ≤ 5 天     |
+| 性能     | `perf/`     | `perf/query-optimization`    | ≤ 3 天     |
+| 文档     | `docs/`     | `docs/api-specification`     | ≤ 2 天     |
+| 发布     | `release/v` | `release/v0.3.0`             | 发布周期内 |
+| 热修复   | `hotfix/`   | `hotfix/v0.3.1`              | ≤ 1 天     |

 **规则**：
+
 - 分支名使用 kebab-case
 - 一个分支只做一件事，禁止在一个分支内混合多个无关变更
 - 特性分支命名包含服务/模块名（`feat/identity-service` 而非 `feat/login`）
@@ -85,6 +88,7 @@ gitGraph
 ### 1.4 分支保护规则

 **`main` 分支保护**：
+
 - 禁止直接 push，必须通过 PR
 - 至少 1 名 Reviewer 审批通过（核心模块需 2 名）
 - 所有 CI 检查通过（lint + typecheck + test + build）
@@ -92,6 +96,7 @@ gitGraph
 - 禁止 force push

 **`release/*` 分支保护**：
+
 - 禁止直接 push，仅接受 cherry-pick 或特定 hotfix PR
 - 至少 2 名 Reviewer 审批
 - 发布完成后打 tag 并归档
@@ -114,25 +119,26 @@ gitGraph

 ### 2.2 类型（type）

-| 类型 | 含义 | 是否触发发布 |
-|------|------|-------------|
-| `feat` | 新功能 | 是（MINOR） |
-| `fix` | Bug 修复 | 是（PATCH） |
-| `perf` | 性能优化 | 是（PATCH） |
-| `refactor` | 重构（不改变行为） | 否 |
-| `style` | 代码风格（格式化、空白） | 否 |
-| `test` | 新增/修改测试 | 否 |
-| `docs` | 文档变更 | 否 |
-| `build` | 构建系统或依赖变更 | 否 |
-| `ci` | CI 配置变更 | 否 |
-| `chore` | 杂项（不修改 src 或 test） | 否 |
-| `revert` | 回滚某次提交 | 是 |
+| 类型       | 含义                       | 是否触发发布 |
+| ---------- | -------------------------- | ------------ |
+| `feat`     | 新功能                     | 是（MINOR）  |
+| `fix`      | Bug 修复                   | 是（PATCH）  |
+| `perf`     | 性能优化                   | 是（PATCH）  |
+| `refactor` | 重构（不改变行为）         | 否           |
+| `style`    | 代码风格（格式化、空白）   | 否           |
+| `test`     | 新增/修改测试              | 否           |
+| `docs`     | 文档变更                   | 否           |
+| `build`    | 构建系统或依赖变更         | 否           |
+| `ci`       | CI 配置变更                | 否           |
+| `chore`    | 杂项（不修改 src 或 test） | 否           |
+| `revert`   | 回滚某次提交               | 是           |

 ### 2.3 范围（scope）

 scope 必须是服务名或包名，详见 [§3.3 scope-enum](#33-scope-enum-完整清单)。

 **示例**：
+
 - `feat(identity): 实现用户注册接口`
 - `fix(gateway): 修复路由匹配优先级`
 - `perf(teaching): 优化课表查询 N+1 问题`
@@ -141,6 +147,7 @@ scope 必须是服务名或包名，详见 [§3.3 scope-enum](#33-scope-enum-完
 ### 2.4 主题（subject）

 **规则**：
+
 - 使用中文简短描述
 - 不超过 50 个字符
 - 不以句号结尾
@@ -150,12 +157,14 @@ scope 必须是服务名或包名，详见 [§3.3 scope-enum](#33-scope-enum-完
 ### 2.5 正文（body）

 **规则**：
+
 - 解释"为什么"而非"做了什么"（代码已说明做了什么）
 - 每行不超过 72 个字符
 - 使用无序列表列出关键变更点
 - 涉及 breaking change 必须在正文开头说明

 **示例**：
+
 ```
 feat(teaching): 作业提交支持附件上传

@@ -195,7 +204,7 @@ pnpm exec husky init

 ### 3.2 commitlint 配置

-创建 `commitlint.config.cjs`：
+实际生效配置文件：仓库根 `.commitlintrc.js`（CommonJS）。

 ```javascript
 /** @type {import('@commitlint/types').UserConfig} */
@@ -224,46 +233,42 @@ module.exports = {
    "type-case": [2, "always", "lower-case"],
    // type 不能为空
    "type-empty": [2, "never"],
-    // scope 枚举（见 3.3）
+    // scope 枚举（见 3.3，与 .commitlintrc.js 保持同步）
    "scope-enum": [
      2,
      "always",
      [
-        // 业务微服务
-        "identity",
-        "org",
-        "teaching",
+        // 网关层（Go）
+        "api-gateway",
+        "push-gateway",
+        // 业务微服务（NestJS / FastAPI）
+        "iam",
+        "core-edu",
+        "classes",
        "content",
-        "comm",
-        "insight",
-        // 基础设施服务
-        "auth",
-        "notification",
-        // AI 服务
-        "insight-ai",
-        // 网关
-        "gateway",
-        // BFF
-        "admin-bff",
+        "data-ana",
+        "msg",
+        "ai",
+        // BFF 聚合层（NestJS）
        "teacher-bff",
        "student-bff",
-        // 微前端
-        "admin-shell",
-        "teacher-shell",
-        "student-shell",
-        "parent-shell",
-        // 共享包
-        "contracts",
-        "ui-tokens",
-        "ui-components",
+        "parent-bff",
+        // 微前端（Next.js）
+        "teacher-portal",
+        "student-portal",
+        "parent-portal",
+        "admin-portal",
+        // 共享包（packages/）
+        "shared-proto",
        "shared-ts",
-        // protobuf 契约
-        "proto",
-        // 平台级
-        "deps",
+        "shared-go",
+        "shared-py",
+        "shared-tokens",
+        // 工具与平台级
+        "arch-scan",
+        "infra",
        "docs",
-        "ci",
-        "chore",
+        "deps",
        "release",
      ],
    ],
@@ -285,100 +290,89 @@ module.exports = {
 };
 ```

+> **单一事实源**：实际生效的配置在仓库根 `.commitlintrc.js`，本节示例仅作说明。修改 scope 必须同步更新 `.commitlintrc.js` 与本节，并在 PR 中说明原因。
+
 ### 3.3 scope-enum 完整清单

-| 分类 | scope | 说明 |
-|------|-------|------|
-| 业务微服务 | `identity` | 身份与权限服务 |
-| 业务微服务 | `org` | 教学组织服务 |
-| 业务微服务 | `teaching` | 教学核心服务 |
-| 业务微服务 | `content` | 内容分析服务 |
-| 业务微服务 | `comm` | 沟通服务 |
-| 业务微服务 | `insight` | 智能洞察服务 |
-| 基础设施 | `auth` | 认证授权服务 |
-| 基础设施 | `notification` | 通知服务 |
-| AI 服务 | `insight-ai` | AI 分析服务（Python） |
-| 网关 | `gateway` | API 网关（Go） |
-| BFF | `admin-bff` | 管理端 BFF |
-| BFF | `teacher-bff` | 教师端 BFF |
-| BFF | `student-bff` | 学生/家长端 BFF |
-| 微前端 | `admin-shell` | 管理端 Shell |
-| 微前端 | `teacher-shell` | 教师端 Shell |
-| 微前端 | `student-shell` | 学生端 Shell |
-| 微前端 | `parent-shell` | 家长端 Shell |
-| 共享包 | `contracts` | protobuf 生成契约包 |
-| 共享包 | `ui-tokens` | 设计令牌包 |
-| 共享包 | `ui-components` | UI 组件库 |
-| 共享包 | `shared-ts` | TS 共享工具包 |
-| 契约 | `proto` | protobuf 定义文件 |
-| 平台级 | `deps` | 依赖升级 |
-| 平台级 | `docs` | 平台级文档 |
-| 平台级 | `ci` | CI/CD 配置 |
-| 平台级 | `chore` | 杂项 |
-| 平台级 | `release` | 发布相关 |
+> 与仓库根 `.commitlintrc.js` 保持同步；修改 scope 必须同时更新此处与 `.commitlintrc.js`。
+
+| 分类       | scope            | 对应目录                  | 说明                                                   |
+| ---------- | ---------------- | ------------------------- | ------------------------------------------------------ |
+| 网关层     | `api-gateway`    | `services/api-gateway/`   | API 网关（Go + Gin）                                   |
+| 网关层     | `push-gateway`   | `services/push-gateway/`  | WebSocket 推送网关（Go）                               |
+| 业务微服务 | `iam`            | `services/iam/`           | 身份与访问管理（NestJS）                               |
+| 业务微服务 | `core-edu`       | `services/core-edu/`      | 教学核心服务（NestJS，Outbox + Kafka）                 |
+| 业务微服务 | `classes`        | `services/classes/`       | 班级服务（P1 黄金模板，P3 并入 core-edu）              |
+| 业务微服务 | `content`        | `services/content/`       | 内容资源服务（NestJS + Neo4j）                         |
+| 业务微服务 | `data-ana`       | `services/data-ana/`      | 数据分析服务（Python + FastAPI + ClickHouse）          |
+| 业务微服务 | `msg`            | `services/msg/`           | 消息通知服务（NestJS + ES）                            |
+| 业务微服务 | `ai`             | `services/ai/`            | AI 网关服务（Python + FastAPI + LLM）                  |
+| BFF 聚合层 | `teacher-bff`    | `services/teacher-bff/`   | 教师端 BFF（NestJS）                                   |
+| BFF 聚合层 | `student-bff`    | `services/student-bff/`   | 学生端 BFF（待建立）                                   |
+| BFF 聚合层 | `parent-bff`     | `services/parent-bff/`    | 家长端 BFF（待建立）                                   |
+| 微前端     | `teacher-portal` | `apps/teacher-portal/`    | 教师端 Portal（Next.js）                               |
+| 微前端     | `student-portal` | `apps/student-portal/`    | 学生端 Portal（待建立）                                |
+| 微前端     | `parent-portal`  | `apps/parent-portal/`     | 家长端 Portal（待建立）                                |
+| 微前端     | `admin-portal`   | `apps/admin-portal/`      | 管理端 Portal（待建立）                                |
+| 共享包     | `shared-proto`   | `packages/shared-proto/`  | protobuf 契约定义                                      |
+| 共享包     | `shared-ts`      | `packages/shared-ts/`     | TS 共享类型与工具（待建立）                            |
+| 共享包     | `shared-go`      | `packages/shared-go/`     | Go 共享工具（待建立）                                  |
+| 共享包     | `shared-py`      | `packages/shared-py/`     | Python 共享工具（待建立）                              |
+| 共享包     | `shared-tokens`  | `packages/shared-tokens/` | 设计令牌（待建立）                                     |
+| 工具       | `arch-scan`      | `scripts/arch-scan/`      | 架构元数据库扫描器                                     |
+| 平台级     | `infra`          | `infra/`                  | 基础设施（K8s / docker-compose / backup / monitoring） |
+| 平台级     | `docs`           | `docs/`                   | 平台级文档（跨多模块）                                 |
+| 平台级     | `deps`           | -                         | 依赖升级                                               |
+| 平台级     | `release`        | -                         | 发布相关                                               |
+
+> `chore` / `ci` / `build` 等 Conventional Commits 标准 type 不需要 scope，可直接使用 `chore: xxx`、`ci: xxx`。

 ### 3.4 husky hooks

+实际生效的 hook 文件在仓库根 `.husky/` 目录。使用 `npx --no-install` 确保使用本地依赖。
+
 `.husky/commit-msg`：

 ```bash
-#!/usr/bin/env sh
-pnpm exec commitlint --edit "$1"
+npx --no-install commitlint --edit $1
 ```

 `.husky/pre-commit`：

 ```bash
-#!/usr/bin/env sh
-pnpm exec lint-staged
+npx --no-install lint-staged
 ```

-`.husky/pre-push`：
+`.husky/pre-push`（推送前类型检查，TS 服务 typecheck 通过后才允许推送）：

 ```bash
 #!/usr/bin/env sh
-# 推送前运行类型检查
-pnpm -r run typecheck
+# 推送前运行类型检查（TS 服务）
+pnpm -r run typecheck 2>/dev/null || echo "[pre-push] typecheck 跳过或不可用"
+# Go 服务编译检查
+for d in services/api-gateway services/push-gateway; do
+  if [ -d "$d" ]; then (cd "$d" && go build ./... ) || exit 1; fi
+done
 ```

+> **注意**：`pre-push` 中的 typecheck 在 TS 服务 ESLint 9 flat config 迁移完成前为可选（当前 `pnpm -r run typecheck` 缺失脚本，会 fallback 到 echo 提示）。Go `go build` 检查必须通过。
+
 ### 3.5 lint-staged 配置

-`package.json`（根目录）：
+实际生效配置文件：仓库根 `lint-staged.config.js`（CommonJS）。

-```json
-{
-  "lint-staged": {
-    // TypeScript / NestJS / Next.js
-    "*.{ts,tsx}": [
-      "eslint --fix",
-      "prettier --write"
-    ],
-    // Go
-    "*.go": [
-      "gofmt -w",
-      "golangci-lint run --fix"
-    ],
-    // Python
-    "*.py": [
-      "ruff check --fix",
-      "ruff format"
-    ],
-    // protobuf
-    "*.proto": [
-      "buf format --write"
-    ],
-    // Markdown
-    "*.md": [
-      "prettier --write"
-    ],
-    // JSON / YAML
-    "*.{json,yaml,yml}": [
-      "prettier --write"
-    ]
-  }
-}
+```javascript
+module.exports = {
+  "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
+  "*.{go,mod,sum}": ["gofmt -w", "golangci-lint run --fix"],
+  "*.{py}": ["ruff check --fix", "ruff format"],
+  "*.proto": ["buf format --write"],
+  "*.md": ["prettier --write"],
+};
 ```

+> JSON / YAML 文件由 prettier 在 `*.md` 规则外按全局配置处理，如需显式规则可在 `lint-staged.config.js` 追加 `'*.{json,yaml,yml}': ['prettier --write']`。
+
 ---

 ## 四、PR 与 Code Review
@@ -435,6 +429,7 @@ feat(identity): 实现用户注册接口
 ## 影响范围

 <!-- 列出受影响的服务/包 -->
+
 - 服务：
 - 包：
 - 数据库迁移：是 / 否
@@ -467,18 +462,19 @@ Closes #

 ### 4.4 Reviewer 要求

-| 变更类型 | 最少 Reviewer | 备注 |
-|---------|--------------|------|
-| 普通业务变更 | 1 | 默认 |
-| 跨服务变更 | 2 | 涉及 ≥ 2 个服务 |
-| protobuf 契约变更 | 2 | 需包含架构组成员 |
-| 数据库 schema 变更 | 2 | 需包含 DBA 或架构组 |
-| 安全相关变更 | 2 | 需包含安全负责人 |
-| 核心模块（auth/identity） | 2 | 核心模块强制 2 人 |
+| 变更类型                  | 最少 Reviewer | 备注                |
+| ------------------------- | ------------- | ------------------- |
+| 普通业务变更              | 1             | 默认                |
+| 跨服务变更                | 2             | 涉及 ≥ 2 个服务     |
+| protobuf 契约变更         | 2             | 需包含架构组成员    |
+| 数据库 schema 变更        | 2             | 需包含 DBA 或架构组 |
+| 安全相关变更              | 2             | 需包含安全负责人    |
+| 核心模块（auth/identity） | 2             | 核心模块强制 2 人   |

 ### 4.5 Code Review 清单

 **通用检查**：
+
 - [ ] 代码是否符合 [编码规范](./coding-standards.md)
 - [ ] 是否有明显的逻辑错误
 - [ ] 错误处理是否完整（不忽略 error/err/exception）
@@ -486,18 +482,21 @@ Closes #
 - [ ] 是否存在硬编码的密钥、token、连接字符串

 **架构检查**：
+
 - [ ] 是否违反限界上下文边界（跨服务直接查 DB）
 - [ ] 是否违反依赖方向（shared 反向依赖 services）
 - [ ] protobuf 变更是否向后兼容
 - [ ] 事件 schema 变更是否向后兼容

 **性能检查**：
+
 - [ ] 是否有 N+1 查询
 - [ ] 是否有未加索引的查询
 - [ ] 是否有不必要的大对象拷贝
 - [ ] 是否有阻塞事件循环的同步操作（Python/Node）

 **安全检查**：
+
 - [ ] 所有入口是否经过权限校验
 - [ ] 用户输入是否经过验证
 - [ ] SQL 是否使用参数化查询
@@ -506,37 +505,80 @@ Closes #
 ### 4.6 合并策略

 **默认使用 Squash Merge**：
+
 - 保留 PR 的完整变更作为一个 commit
 - commit message 使用 PR 标题
 - 删除特性分支

 **禁止使用 Merge Commit**（除非是发布分支合并回 main）：
+
 - 避免历史中充斥 "Merge branch" 噪音
 - 保持线性历史

 **Rebase Merge**：
+
 - 仅用于需要保留多个有意义 commit 的特性分支
 - 需在 PR 中说明原因

+### 4.7 模块 Owner 与 CODEOWNERS
+
+**实际生效文件**：仓库根 `.github/CODEOWNERS`（GitHub/Gitea 原生支持，自动为 PR 分配 reviewer）。
+
+**设计原则**：
+
+- 每个模块至少 1 名 owner，核心模块 2 名
+- 跨模块变更（如 proto 契约、arch.db、project_rules）由架构组 review
+- 基础设施变更（K8s/Helm/backup）由 SRE review
+- owner 名单变更需走 PR，由架构组审批
+
+**模块 Owner 分配矩阵**：
+
+| 模块分类   | 路径                                                                                                                                  | Owner Team                | 最少 Reviewer | 备注                  |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------------- | --------------------- |
+| 架构与规则 | `.trae/rules/`、`docs/architecture/`、`docs/standards/`                                                                               | `@edu-platform/arch`      | 2             | 架构组强制 review     |
+| 架构工具   | `scripts/arch-scan/`                                                                                                                  | `@edu-platform/arch`      | 1             |                       |
+| 根配置     | `.commitlintrc.js`、`lint-staged.config.js`、`package.json`、`pnpm-workspace.yaml`、`go.work`、`pyproject.toml`、`tsconfig.base.json` | `@edu-platform/arch`      | 2             | 影响全局              |
+| 共享包     | `packages/shared-proto/`                                                                                                              | `@edu-platform/arch`      | 2             | 契约变更影响所有服务  |
+| 网关层     | `services/api-gateway/`、`services/push-gateway/`                                                                                     | `@edu-platform/gateway`   | 1             |                       |
+| IAM 服务   | `services/iam/`                                                                                                                       | `@edu-platform/iam`       | 2             | 核心模块强制 2 人     |
+| 教学核心   | `services/core-edu/`、`services/classes/`                                                                                             | `@edu-platform/edu-core`  | 1             |                       |
+| 内容资源   | `services/content/`                                                                                                                   | `@edu-platform/content`   | 1             |                       |
+| 消息通知   | `services/msg/`                                                                                                                       | `@edu-platform/messaging` | 1             |                       |
+| 数据分析   | `services/data-ana/`                                                                                                                  | `@edu-platform/data`      | 1             |                       |
+| AI 服务    | `services/ai/`                                                                                                                        | `@edu-platform/ai`        | 1             |                       |
+| BFF 层     | `services/teacher-bff/`、`services/student-bff/`、`services/parent-bff/`                                                              | `@edu-platform/edu-core`  | 1             |                       |
+| 微前端     | `apps/teacher-portal/`、`apps/student-portal/`、`apps/parent-portal/`、`apps/admin-portal/`                                           | `@edu-platform/frontend`  | 1             |                       |
+| 基础设施   | `infra/k8s/`、`infra/backup/`、`infra/security/`、`infra/monitoring/`                                                                 | `@edu-platform/sre`       | 2             | 生产环境变更强制 2 人 |
+| CI/CD      | `.github/`、`.husky/`                                                                                                                 | `@edu-platform/sre`       | 1             |                       |
+| 文档       | `docs/troubleshooting/`、`docs/standards/`                                                                                            | `@edu-platform/arch`      | 1             | known-issues 更新     |
+
+> **Team handle 占位符**：上表 `@edu-platform/*` 为 team handle 模板。实际团队 handle 需在 GitHub/Gitea Organization 中创建对应 team 后，同步更新 `.github/CODEOWNERS`。
+
+**CODEOWNERS 文件维护规则**：
+
+1. 新增服务/包时，必须在同一 PR 中更新 `.github/CODEOWNERS`
+2. owner 变更（人员调动）需开独立 PR，由架构组审批
+3. CODEOWNERS 与本节表格保持同步，单一事实源为 `.github/CODEOWNERS` 文件
+
 ---

 ## 五、文档同步规则

 ### 5.1 文档同步矩阵

-| 代码变更类型 | 需同步的文档 | 同步时机 |
-|-------------|-------------|---------|
-| 新增/删除服务 | `001_architecture_overview.md` + 服务 README | PR 内同步 |
-| 新增/删除模块 | 服务 README + `arch:scan` | PR 内同步 |
-| 新增/删除导出函数 | `pnpm run arch:scan` | 提交前 |
-| 修改函数签名 | `pnpm run arch:scan` | 提交前 |
-| 修改权限点 | `project_rules.md` + 权限文档 | PR 内同步 |
-| 新增/删除数据库表 | 架构文档 + 服务 README | PR 内同步 |
-| 新增/删除路由 | 服务 README + OpenAPI | PR 内同步 |
-| 修改模块间依赖 | `arch:scan` + 架构文档 | PR 内同步 |
-| 新增 protobuf message | `proto/` README + `arch:scan` | PR 内同步 |
-| 新增 Kafka topic | 架构文档 + 服务 README | PR 内同步 |
-| 遇到新问题/经验 | `known-issues.md` | PR 内同步 |
+| 代码变更类型          | 需同步的文档                                 | 同步时机  |
+| --------------------- | -------------------------------------------- | --------- |
+| 新增/删除服务         | `001_architecture_overview.md` + 服务 README | PR 内同步 |
+| 新增/删除模块         | 服务 README + `arch:scan`                    | PR 内同步 |
+| 新增/删除导出函数     | `pnpm run arch:scan`                         | 提交前    |
+| 修改函数签名          | `pnpm run arch:scan`                         | 提交前    |
+| 修改权限点            | `project_rules.md` + 权限文档                | PR 内同步 |
+| 新增/删除数据库表     | 架构文档 + 服务 README                       | PR 内同步 |
+| 新增/删除路由         | 服务 README + OpenAPI                        | PR 内同步 |
+| 修改模块间依赖        | `arch:scan` + 架构文档                       | PR 内同步 |
+| 新增 protobuf message | `proto/` README + `arch:scan`                | PR 内同步 |
+| 新增 Kafka topic      | 架构文档 + 服务 README                       | PR 内同步 |
+| 遇到新问题/经验       | `known-issues.md`                            | PR 内同步 |

 ### 5.2 arch.db 同步规则

@@ -551,6 +593,7 @@ git commit -m "feat(identity): 实现用户注册接口"
 ```

 **违规检查**：
+
 - 长文件（> 1000 行）
 - 未校验权限的 Handler
 - 循环依赖
@@ -568,26 +611,33 @@ git commit -m "feat(identity): 实现用户注册接口"
 > 技术栈：[语言 + 框架]

 ## 职责
+
 [一段话描述]

 ## 架构
+
 [mermaid 架构图]

 ## 核心流程
+
 [mermaid 时序图]

 ## 目录结构
+
 [树形结构 + 说明]

 ## 依赖
+
 - 上游服务：[列表]
 - 下游服务：[列表]
 - 共享包：[列表]

 ## 约束
+
 [业务规则、技术约束]

 ## 架构决策
+
 [关键设计决策记录]
 ```

@@ -598,12 +648,13 @@ git commit -m "feat(identity): 实现用户注册接口"
 ```markdown
 ### X.X 主题分区

-| 场景 | 技术/规则 |
-|------|----------|
+| 场景     | 技术/规则          |
+| -------- | ------------------ |
 | 简述场景 | 正确做法（一句话） |
 ```

 **规则**：
+
 - 索引式：场景→技术/规则映射
 - 不写代码示例和错误示范
 - 同类问题在原条目补充，不重复创建
@@ -618,6 +669,7 @@ git commit -m "feat(identity): 实现用户注册接口"
 **规则**：一个 commit 只涉及一个服务或一个包的变更。

 **原因**：
+
 - 便于回滚（按服务粒度回滚）
 - 便于追踪（changelog 清晰）
 - 便于 review（聚焦单一职责）
@@ -653,12 +705,14 @@ git commit -m "build(contracts): 重新生成 proto 代码"
 ### 6.4 依赖升级规则

 **规则**：
+
 - 依赖升级使用 `build(deps):` 类型
 - 必须说明升级原因（安全、功能、兼容性）
 - 安全漏洞修复必须包含 CVE 编号
 - 大版本升级需单独 PR 并完整测试

 **示例**：
+
 ```
 build(deps): 升级 nestjs 至 10.3.0

@@ -691,33 +745,33 @@ git commit -m "feat(notification): 适配 UserRegistered v2 事件"

 本项目采用**双层版本号**：

-| 层级 | 格式 | 说明 |
-|------|------|------|
+| 层级     | 格式                     | 说明                                      |
+| -------- | ------------------------ | ----------------------------------------- |
 | 平台版本 | `v{阶段}.{迭代}.{patch}` | 如 `v0.3.1`（P3 阶段第 1 次迭代 patch 1） |
-| 服务版本 | `{service}:{semver}` | 如 `identity:1.2.0` |
+| 服务版本 | `{service}:{semver}`     | 如 `identity:1.2.0`                       |

 ### 7.2 阶段版本范围

-| 阶段 | 平台版本范围 | 说明 |
-|------|-------------|------|
-| P1 地基 | `v0.1.x` | monorepo 初始化、CI/CD、arch.db |
-| P2 身份 | `v0.2.x` | identity + auth + notification |
-| P3 核心教学 | `v0.3.x` | org + teaching + content |
-| P4 内容分析 | `v0.4.x` | insight + CQRS 读模型 |
-| P5 沟通AI | `v0.5.x` | comm + AI 增强 |
-| P6 硬化 | `v1.0.x` | 正式发布版 |
+| 阶段        | 平台版本范围 | 说明                            |
+| ----------- | ------------ | ------------------------------- |
+| P1 地基     | `v0.1.x`     | monorepo 初始化、CI/CD、arch.db |
+| P2 身份     | `v0.2.x`     | identity + auth + notification  |
+| P3 核心教学 | `v0.3.x`     | org + teaching + content        |
+| P4 内容分析 | `v0.4.x`     | insight + CQRS 读模型           |
+| P5 沟通AI   | `v0.5.x`     | comm + AI 增强                  |
+| P6 硬化     | `v1.0.x`     | 正式发布版                      |

 ### 7.3 Docker 镜像标签

 **格式**：`{registry}/edu/{service}:{tag}`

-| tag 类型 | 格式 | 示例 | 用途 |
-|---------|------|------|------|
-| 版本号 | `v{version}` | `v0.3.1` | 正式发布 |
-| 服务版本 | `{service}-{semver}` | `identity-1.2.0` | 服务独立版本 |
-| Git SHA | `sha-{short}` | `sha-a1b2c3d` | 精确追溯 |
-| 最新 | `latest` | `latest` | 开发环境 |
-| 阶段 | `{stage}-{sha}` | `staging-a1b2c3d` | 阶段环境 |
+| tag 类型 | 格式                 | 示例              | 用途         |
+| -------- | -------------------- | ----------------- | ------------ |
+| 版本号   | `v{version}`         | `v0.3.1`          | 正式发布     |
+| 服务版本 | `{service}-{semver}` | `identity-1.2.0`  | 服务独立版本 |
+| Git SHA  | `sha-{short}`        | `sha-a1b2c3d`     | 精确追溯     |
+| 最新     | `latest`             | `latest`          | 开发环境     |
+| 阶段     | `{stage}-{sha}`      | `staging-a1b2c3d` | 阶段环境     |

 ### 7.4 发布流程

@@ -752,19 +806,23 @@ flowchart TD
 ## [v0.3.0] - 2026-08-15

 ### Added
+
 - 教学核心服务新增作业管理功能
 - 内容服务支持题库导入
 - 教师端 Shell 新增作业批改界面

 ### Changed
+
 - identity 服务升级至 NestJS 10.3
 - gateway 路由匹配算法优化

 ### Fixed
+
 - 修复 JWT 刷新 token 过期判断错误
 - 修复课表查询时区问题

 ### Breaking Changes
+
 - UserRegistered 事件 schema 变更至 v2，消费方需升级
 ```

@@ -778,6 +836,7 @@ flowchart TD
 ```

 **版本号升级规则**：
+
 - **MAJOR**：Breaking Change（protobuf 不兼容变更、API 破坏性修改）
 - **MINOR**：新增功能，向后兼容
 - **PATCH**：Bug 修复，向后兼容
@@ -788,13 +847,13 @@ flowchart TD

 ### 8.1 回滚策略

-| 场景 | 回滚方式 | 耗时 |
-|------|---------|------|
-| 代码缺陷 | `git revert` + 重新部署 | 5-10 分钟 |
-| 镜像问题 | `kubectl rollout undo` | 1-2 分钟 |
-| 数据库迁移问题 | 执行迁移 down 脚本 | 5-30 分钟 |
-| 配置错误 | 回滚 ConfigMap/Secret | 1-2 分钟 |
-| 全站故障 | 回滚至上一稳定 tag | 10-30 分钟 |
+| 场景           | 回滚方式                | 耗时       |
+| -------------- | ----------------------- | ---------- |
+| 代码缺陷       | `git revert` + 重新部署 | 5-10 分钟  |
+| 镜像问题       | `kubectl rollout undo`  | 1-2 分钟   |
+| 数据库迁移问题 | 执行迁移 down 脚本      | 5-30 分钟  |
+| 配置错误       | 回滚 ConfigMap/Secret   | 1-2 分钟   |
+| 全站故障       | 回滚至上一稳定 tag      | 10-30 分钟 |

 ### 8.2 代码回滚

@@ -833,6 +892,7 @@ kubectl rollout status deployment/identity -n edu-prod
 ### 8.4 数据库迁移回滚

 **规则**：
+
 - 所有迁移必须提供 `up` 和 `down` 脚本
 - `down` 脚本必须在 CI 中测试
 - 回滚前必须备份生产数据
@@ -865,6 +925,7 @@ pnpm --filter identity run migrate:down -- --to <version>
 > 严重等级：P0/P1/P2/P3

 ## 时间线
+
 - HH:MM 告警触发
 - HH:MM 确认问题
 - HH:MM 决定回滚
@@ -872,15 +933,19 @@ pnpm --filter identity run migrate:down -- --to <version>
 - HH:MM 服务恢复

 ## 影响分析
+
 [受影响的功能、用户数、业务损失]

 ## 根本原因
+
 [技术原因 + 流程原因]

 ## 回滚过程
+
 [执行的操作]

 ## 改进措施
+
 - [ ] 短期：[立即修复项]
 - [ ] 中期：[流程改进项]
 - [ ] 长期：[架构改进项]
@@ -890,29 +955,30 @@ pnpm --filter identity run migrate:down -- --to <version>

 ## 九、附录：CICD 与 Edu Git 工作流差异

-| 维度 | CICD（Next.js 单应用） | Edu（微服务 monorepo） |
-|------|----------------------|----------------------|
-| 仓库结构 | 单一 Next.js 应用 | 多语言 monorepo（pnpm + go.work + uv） |
-| 分支策略 | trunk-based | trunk-based（沿用） |
-| 提交规范 | Conventional Commits | Conventional Commits（沿用，scope 扩展至服务/包） |
-| scope 范围 | 模块名（如 `exams`、`homework`） | 服务/包名（如 `identity`、`contracts`） |
-| commitlint scope-enum | 35 个模块 | 27 个服务/包 |
-| PR Reviewer | 1 人 | 1-2 人（核心模块/跨服务 2 人） |
-| 合并策略 | Squash Merge | Squash Merge（沿用） |
-| 版本号 | 单一应用版本 | 双层（平台版本 + 服务独立版本） |
-| 发布粒度 | 整体发布 | 按服务独立发布 |
-| Docker 镜像 | 单一镜像 | 每服务一镜像 |
-| 回滚粒度 | 整体回滚 | 按服务回滚 |
-| 数据库迁移 | Drizzle 单库 | 每服务独立库 + 独立迁移 |
-| 文档同步 | `npm run arch:scan` | `pnpm run arch:scan`（多语言扫描） |
-| CI 检查 | lint + tsc + test | lint + typecheck + test（按语言分别执行） |
-| 紧急回滚 | `git revert` + 重新部署 | `git revert` + `kubectl rollout undo` |
-| 事故复盘 | known-issues.md | `incidents/` 目录独立记录 |
+| 维度                  | CICD（Next.js 单应用）           | Edu（微服务 monorepo）                                           |
+| --------------------- | -------------------------------- | ---------------------------------------------------------------- |
+| 仓库结构              | 单一 Next.js 应用                | 多语言 monorepo（pnpm + go.work + uv）                           |
+| 分支策略              | trunk-based                      | trunk-based（沿用）                                              |
+| 提交规范              | Conventional Commits             | Conventional Commits（沿用，scope 扩展至服务/包）                |
+| scope 范围            | 模块名（如 `exams`、`homework`） | 服务/包名（如 `iam`、`api-gateway`、`shared-proto`）             |
+| commitlint scope-enum | 35 个模块                        | 26 个 scope（含服务/包/工具/平台级，与 `.commitlintrc.js` 同步） |
+| PR Reviewer           | 1 人                             | 1-2 人（核心模块/跨服务 2 人）                                   |
+| 合并策略              | Squash Merge                     | Squash Merge（沿用）                                             |
+| 版本号                | 单一应用版本                     | 双层（平台版本 + 服务独立版本）                                  |
+| 发布粒度              | 整体发布                         | 按服务独立发布                                                   |
+| Docker 镜像           | 单一镜像                         | 每服务一镜像                                                     |
+| 回滚粒度              | 整体回滚                         | 按服务回滚                                                       |
+| 数据库迁移            | Drizzle 单库                     | 每服务独立库 + 独立迁移                                          |
+| 文档同步              | `npm run arch:scan`              | `pnpm run arch:scan`（多语言扫描）                               |
+| CI 检查               | lint + tsc + test                | lint + typecheck + test（按语言分别执行）                        |
+| 紧急回滚              | `git revert` + 重新部署          | `git revert` + `kubectl rollout undo`                            |
+| 事故复盘              | known-issues.md                  | `incidents/` 目录独立记录                                        |

 ---

 ## 变更记录

-| 版本 | 日期 | 变更内容 |
-|------|------|---------|
-| 1.0 | 2026-07-07 | 基线发布，从 CICD 单应用规范迁移至微服务多语言 monorepo |
+| 版本 | 日期       | 变更内容                                                                                                                                                 |
+| ---- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1.0  | 2026-07-07 | 基线发布，从 CICD 单应用规范迁移至微服务多语言 monorepo                                                                                                  |
+| 1.1  | 2026-07-08 | scope-enum 对齐实际服务名（identity→iam、teaching→core-edu 等）；新增 §4.7 模块 Owner 与 CODEOWNERS；husky hooks 与实际文件对齐；新增 pre-push hook 说明 |