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

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

Browse Source 
- 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 模板
This commit is contained in:
SpecialX
2026-07-08 12:53:18 +08:00
parent beedbaf686
commit b39095cbdd
3 changed files with 398 additions and 197 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
.github/CODEOWNERS vendored Normal file
View File

@@ -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

55
.github/pull_request_template.md vendored Normal file
View File

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

302
docs/standards/git-workflow.md
View File

@@ -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`
@@ -67,7 +69,7 @@ gitGraph
### 1.3 分支命名规范
| 分支类型 | 前缀 | 示例 | 生命周期 |
|---------|------|------|---------|
| -------- | ----------- | ---------------------------- | ---------- |
| 主干 | `main` | `main` | 永久 |
| 特性 | `feat/` | `feat/identity-service` | ≤ 3 天 |
| 修复 | `fix/` | `fix/jwt-expiry` | ≤ 1 天 |
@@ -78,6 +80,7 @@ gitGraph
| 热修复 | `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 并归档
@@ -115,7 +120,7 @@ gitGraph
### 2.2 类型（type）
| 类型 | 含义 | 是否触发发布 |
|------|------|-------------|
| ---------- | -------------------------- | ------------ |
| `feat` | 新功能 | 是（MINOR） |
| `fix` | Bug 修复 | 是（PATCH） |
| `perf` | 性能优化 | 是（PATCH） |
@@ -133,6 +138,7 @@ gitGraph
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): 实现用户注册接口
## 影响范围
<!-- 列出受影响的服务/包 -->
- 服务：
- 包：
- 数据库迁移：是 / 否
@@ -468,7 +463,7 @@ Closes #
### 4.4 Reviewer 要求
| 变更类型 | 最少 Reviewer | 备注 |
|---------|--------------|------|
| ------------------------- | ------------- | ------------------- |
| 普通业务变更 | 1 | 默认 |
| 跨服务变更 | 2 | 涉及 ≥ 2 个服务 |
| protobuf 契约变更 | 2 | 需包含架构组成员 |
@@ -479,6 +474,7 @@ Closes #
### 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,18 +505,61 @@ 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` 文件
---
## 五、文档同步规则
@@ -525,7 +567,7 @@ Closes #
### 5.1 文档同步矩阵
| 代码变更类型 | 需同步的文档 | 同步时机 |
|-------------|-------------|---------|
| --------------------- | -------------------------------------------- | --------- |
| 新增/删除服务 | `001_architecture_overview.md` + 服务 README | PR 内同步 |
| 新增/删除模块 | 服务 README + `arch:scan` | PR 内同步 |
| 新增/删除导出函数 | `pnpm run arch:scan` | 提交前 |
@@ -551,6 +593,7 @@ git commit -m "feat(identity): 实现用户注册接口"
```
**违规检查**：
- 长文件（> 1000 行）
- 未校验权限的 Handler
- 循环依赖
@@ -568,26 +611,33 @@ git commit -m "feat(identity): 实现用户注册接口"
> 技术栈：[语言 + 框架]
## 职责
[一段话描述]
## 架构
[mermaid 架构图]
## 核心流程
[mermaid 时序图]
## 目录结构
[树形结构 + 说明]
## 依赖
- 上游服务：[列表]
- 下游服务：[列表]
- 共享包：[列表]
## 约束
[业务规则、技术约束]
## 架构决策
[关键设计决策记录]
```
@@ -599,11 +649,12 @@ git commit -m "feat(identity): 实现用户注册接口"
### 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
@@ -692,14 +746,14 @@ git commit -m "feat(notification): 适配 UserRegistered v2 事件"
本项目采用**双层版本号**：
| 层级 | 格式 | 说明 |
|------|------|------|
| -------- | ------------------------ | ----------------------------------------- |
| 平台版本 | `v{阶段}.{迭代}.{patch}` | 如 `v0.3.1`（P3 阶段第 1 次迭代 patch 1） |
| 服务版本 | `{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 |
@@ -712,7 +766,7 @@ git commit -m "feat(notification): 适配 UserRegistered v2 事件"
**格式**：`{registry}/edu/{service}:{tag}`
| tag 类型 | 格式 | 示例 | 用途 |
|---------|------|------|------|
| -------- | -------------------- | ----------------- | ------------ |
| 版本号 | `v{version}` | `v0.3.1` | 正式发布 |
| 服务版本 | `{service}-{semver}` | `identity-1.2.0` | 服务独立版本 |
| Git SHA | `sha-{short}` | `sha-a1b2c3d` | 精确追溯 |
@@ -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 修复，向后兼容
@@ -789,7 +848,7 @@ flowchart TD
### 8.1 回滚策略
| 场景 | 回滚方式 | 耗时 |
|------|---------|------|
| -------------- | ----------------------- | ---------- |
| 代码缺陷 | `git revert` + 重新部署 | 5-10 分钟 |
| 镜像问题 | `kubectl rollout undo` | 1-2 分钟 |
| 数据库迁移问题 | 执行迁移 down 脚本 | 5-30 分钟 |
@@ -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 服务恢复
## 影响分析
[受影响的功能、用户数、业务损失]
## 根本原因
[技术原因 + 流程原因]
## 回滚过程
[执行的操作]
## 改进措施
- [ ] 短期：[立即修复项]
- [ ] 中期：[流程改进项]
- [ ] 长期：[架构改进项]
@@ -891,12 +956,12 @@ 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 个服务/包 |
| 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（沿用） |
| 版本号 | 单一应用版本 | 双层（平台版本 + 服务独立版本） |
@@ -914,5 +979,6 @@ pnpm --filter identity run migrate:down -- --to <version>
## 变更记录
| 版本 | 日期 | 变更内容 |
|------|------|---------|
| ---- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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 说明 |