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

docs: 文档体系修正 - 模块边界强化与按需阅读架构

Browse Source
This commit is contained in:
SpecialX
2026-07-10 13:33:31 +08:00
parent faaaf29f67
commit f15912c7ee
5 changed files with 594 additions and 918 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,8 +1,8 @@
# Edu Git 工作流规范
> 版本：1.1
> 日期：2026-07-08
> 状态：基线发布（v1.1：scope-enum 对齐 + CODEOWNERS）
> 版本：1.2
> 日期：2026-07-10
> 状态：基线发布（v1.2：移除分支/PR 流程，改为直接 push main）
> 适用范围：Edu 多语言 monorepo（pnpm workspace + go.work + pyproject.toml）
> 关联文档：
>
@@ -15,91 +15,69 @@
## 目录
1. [分支策略](#一分支策略)
1. [主干开发（直接 push main）](#一主干开发直接-push-main)
2. [Conventional Commits 规范](#二conventional-commits-规范)
3. [commitlint + husky 配置](#三commitlint--husky-配置)
4. [PR 与 Code Review](#四pr-与-code-review)
4. [事后 Code Review](#四事后-code-review)
5. [文档同步规则](#五文档同步规则)
6. [多语言 monorepo 提交规则](#六多语言-monorepo-提交规则)
7. [版本与发布](#七版本与发布)
7. [版本管理](#七版本管理)
8. [紧急回滚](#八紧急回滚)
9. [附录：CICD 与 Edu Git 工作流差异](#九附录cicd-与-edu-git-工作流差异)
---
## 一、分支策略
## 一、主干开发（直接 push main）
### 1.1 主干开发（Trunk-Based Development）
### 1.1 模式
本项目采用**主干开发**模式，所有变更最终合并至 `main` 分支。
本项目采用**主干开发**模式，所有变更**直接提交到 `main` 分支**。
> 因 Gitea 问题，**不再使用特性分支、发布分支、hotfix 分支，不再使用 PR 流程**。所有变更通过 `git push origin main` 提交。
**核心原则**：
- `main` 分支始终保持可发布状态
- 短生命周期特性分支（通常 ≤ 3 天）
- 频繁集成，每天至少一次 rebase/merge 至最新 `main`
- 所有变更直接 push main，**禁止 `git checkout -b` 创建任何分支**
- push 前本地通过 lint + typecheck + test + build（见 §3.4 pre-push hook）
- push 前 `git pull --rebase origin main` 同步最新
- 通过特性开关（Feature Flag）控制未完成功能的暴露
- 代码审查改为事后追溯（见 §4），不在 push 前阻塞
### 1.2 分支模型
### 1.2 提交流程
```mermaid
gitGraph
commit id: "init"
commit id: "P1-foundation"
branch feat/identity-service
checkout feat/identity-service
commit id: "scaffold"
commit id: "implement-login"
commit id: "add-tests"
checkout main
merge feat/identity-service tag: "v0.2.0"
branch fix/jwt-expiry
checkout fix/jwt-expiry
commit id: "fix-token-refresh"
checkout main
merge fix/jwt-expiry tag: "v0.2.1"
branch release/v0.3
checkout release/v0.3
commit id: "freeze"
commit id: "hotfix"
checkout main
merge release/v0.3 tag: "v0.3.0"
```bash
# 1. 同步最新 main
git pull --rebase origin main
# 2. 本地校验（强制）
pnpm run lint # TS 服务
pnpm run typecheck # TS 服务
cd services/api-gateway && go vet ./... && go build ./... # Go 服务
ruff check src/ # Python 服务
# 3. 提交（遵循 Conventional Commits，见 §2）
git add <files>
git commit -m "feat(<scope>): <subject>"
# 4. push 前再次同步（避免冲突）
git pull --rebase origin main
# 5. 直接 push main
git push origin main
```
### 1.3 分支命名规范
### 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 天 |
- **push 被拒绝**（远端有新提交）：`git pull --rebase origin main` → 解决冲突 → `git add` → `git rebase --continue` → `git push origin main`
- **架构冲突**：由协调 AI 仲裁，通过 `git revert` + 新 commit 修正
- **禁止 `git push --force` 到 main**：仅协调 AI 在事故时可 `git push --force-with-lease origin main`
**规则**：
### 1.4 main 分支保护
- 分支名使用 kebab-case
- 一个分支只做一件事，禁止在一个分支内混合多个无关变更
- 特性分支命名包含服务/模块名（`feat/identity-service` 而非 `feat/login`）
### 1.4 分支保护规则
**`main` 分支保护**：
- 禁止直接 push，必须通过 PR
- 至少 1 名 Reviewer 审批通过（核心模块需 2 名）
- 所有 CI 检查通过（lint + typecheck + test + build）
- 分支必须与 `main` 保持最新（无冲突或已 rebase）
- 禁止 force push
**`release/*` 分支保护**：
- 禁止直接 push，仅接受 cherry-pick 或特定 hotfix PR
- 至少 2 名 Reviewer 审批
- 发布完成后打 tag 并归档
- 禁止 force push（仅协调 AI 在事故时操作）
- pre-commit / commit-msg / pre-push hook 强制校验（见 §3.4）
- 不再要求 PR review，代码质量由本地校验 + 事后 review（§4）+ CI（project_rules §15）保证
---
@@ -375,103 +353,33 @@ module.exports = {
---
## 四、PR 与 Code Review
## 四、事后 Code Review
### 4.1 PR 流程
> 不再使用 PR 流程，代码审查改为**事后追溯**：变更直接 push main 后，由模块 owner 或协调 AI 通过 commit history 进行 review。问题通过后续 commit 修正或 `git revert` 回滚。
### 4.1 事后 Review 流程
```mermaid
flowchart TD
A[开发者创建特性分支] --> B[提交代码]
B --> C[本地通过 lint + typecheck + test]
C --> D[rebase 至最新 main]
D --> E[推送至远程]
E --> F[创建 PR]
F --> G[CI 自动检查]
G --> H{CI 通过?}
H -->|否| I[修复问题]
I --> B
H -->|是| J[Reviewer 审查]
J --> K{审查通过?}
K -->|需修改| L[根据反馈修改]
L --> B
K -->|通过| M[Squash Merge]
M --> N[删除特性分支]
N --> O[CI 部署至 staging]
A[开发 AI 本地校验] --> B[直接 push main]
B --> C[CI 自动检查]
C --> D{CI 通过?}
D -->|否| E[git revert + 修复后重新 push]
D -->|是| F[模块 owner 事后审查 commit]
F --> G{审查通过?}
G -->|有问题| H[后续 commit 修正或 revert]
G -->|通过| I[review 完成]
```
### 4.2 PR 标题
**review 依据**：
PR 标题必须符合 Conventional Commits 规范（与最终 squash merge 的 commit message 一致）：
- commit message（Conventional Commits 格式，见 §2）
- commit diff（通过 `git log -p` 或平台 commit 视图）
- AI 身份标注（commit body 末尾的 `AI-Agent:` 字段，见 project_rules §14.6）
```
feat(identity): 实现用户注册接口
```
### 4.2 Code Review 清单
### 4.3 PR 模板
`.github/pull_request_template.md`（或 Gitea 等价路径）：
```markdown
## 变更说明
<!-- 简述本次变更的目的和实现方式 -->
## 变更类型
- [ ] feat: 新功能
- [ ] fix: Bug 修复
- [ ] perf: 性能优化
- [ ] refactor: 重构
- [ ] test: 测试
- [ ] docs: 文档
- [ ] build/ci: 构建/CI
## 影响范围
<!-- 列出受影响的服务/包 -->
- 服务：
- 包：
- 数据库迁移：是 / 否
- protobuf 契约变更：是 / 否
- Kafka topic 变更：是 / 否
## 测试情况
- [ ] 单元测试通过
- [ ] 集成测试通过
- [ ] 本地手动测试通过
- [ ] 新增测试覆盖新功能
## 文档同步
- [ ] 已更新服务 README（如涉及服务结构变更）
- [ ] 已更新架构文档（如涉及架构变更）
- [ ] 已运行 `pnpm run arch:scan` 更新 arch.db
- [ ] 已更新 known-issues.md（如遇到新问题）
## Breaking Change
- [ ] 否
- [ ] 是（请在下方说明影响和迁移路径）
## 关联 Issue
Closes #
```
### 4.4 Reviewer 要求
| 变更类型 | 最少 Reviewer | 备注 |
| ------------------------- | ------------- | ------------------- |
| 普通业务变更 | 1 | 默认 |
| 跨服务变更 | 2 | 涉及 ≥ 2 个服务 |
| protobuf 契约变更 | 2 | 需包含架构组成员 |
| 数据库 schema 变更 | 2 | 需包含 DBA 或架构组 |
| 安全相关变更 | 2 | 需包含安全负责人 |
| 核心模块（auth/identity） | 2 | 核心模块强制 2 人 |
### 4.5 Code Review 清单
事后 review 时检查：
**通用检查**：
@@ -502,62 +410,46 @@ Closes #
- [ ] SQL 是否使用参数化查询
- [ ] 是否有 SQL 注入、XSS、SSRF 风险
### 4.6 合并策略
### 4.3 模块 Owner 与 CODEOWNERS
**默认使用 Squash Merge**：
**实际生效文件**：仓库根 `.github/CODEOWNERS`。
- 保留 PR 的完整变更作为一个 commit
- commit message 使用 PR 标题
- 删除特性分支
**禁止使用 Merge Commit**（除非是发布分支合并回 main）：
- 避免历史中充斥 "Merge branch" 噪音
- 保持线性历史
**Rebase Merge**：
- 仅用于需要保留多个有意义 commit 的特性分支
- 需在 PR 中说明原因
### 4.7 模块 Owner 与 CODEOWNERS
**实际生效文件**：仓库根 `.github/CODEOWNERS`（GitHub/Gitea 原生支持，自动为 PR 分配 reviewer）。
> 不再用于自动分配 PR reviewer（无 PR 流程），CODEOWNERS 保留作为**模块归属追溯依据**：commit 涉及某路径时，对应 owner 负责事后 review。
**设计原则**：
- 每个模块至少 1 名 owner，核心模块 2 名
- 跨模块变更（如 proto 契约、arch.db、project_rules）由架构组 review
- 基础设施变更（K8s/Helm/backup）由 SRE review
- owner 名单变更需走 PR，由架构组审批
- 跨模块变更（如 proto 契约、arch.db、project_rules）由架构组事后 review
- 基础设施变更（K8s/Helm/backup）由 SRE 事后 review
- owner 名单变更通过直接 commit 更新，由架构组确认
**模块 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 更新 |
| 模块分类 | 路径 | Owner Team | 备注 |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | -------------------- |
| 架构与规则 | `.trae/rules/`、`docs/architecture/`、`docs/standards/` | `@edu-platform/arch` | 架构组强制 review |
| 架构工具 | `scripts/arch-scan/` | `@edu-platform/arch` | |
| 根配置 | `.commitlintrc.js`、`lint-staged.config.js`、`package.json`、`pnpm-workspace.yaml`、`go.work`、`pyproject.toml`、`tsconfig.base.json` | `@edu-platform/arch` | 影响全局 |
| 共享包 | `packages/shared-proto/` | `@edu-platform/arch` | 契约变更影响所有服务 |
| 网关层 | `services/api-gateway/`、`services/push-gateway/` | `@edu-platform/gateway` | |
| IAM 服务 | `services/iam/` | `@edu-platform/iam` | 核心模块 |
| 教学核心 | `services/core-edu/`、`services/classes/` | `@edu-platform/edu-core` | |
| 内容资源 | `services/content/` | `@edu-platform/content` | |
| 消息通知 | `services/msg/` | `@edu-platform/messaging` | |
| 数据分析 | `services/data-ana/` | `@edu-platform/data` | |
| AI 服务 | `services/ai/` | `@edu-platform/ai` | |
| BFF 层 | `services/teacher-bff/`、`services/student-bff/`、`services/parent-bff/` | `@edu-platform/edu-core` | |
| 微前端 | `apps/teacher-portal/`、`apps/student-portal/`、`apps/parent-portal/`、`apps/admin-portal/` | `@edu-platform/frontend` | |
| 基础设施 | `infra/k8s/`、`infra/backup/`、`infra/security/`、`infra/monitoring/` | `@edu-platform/sre` | 生产环境变更 |
| CI/CD | `.github/`、`.husky/` | `@edu-platform/sre` | |
| 文档 | `docs/troubleshooting/`、`docs/standards/` | `@edu-platform/arch` | known-issues 更新 |
> **Team handle 占位符**：上表 `@edu-platform/*` 为 team handle 模板。实际团队 handle 需在 GitHub/Gitea Organization 中创建对应 team 后，同步更新 `.github/CODEOWNERS`。
**CODEOWNERS 文件维护规则**：
1. 新增服务/包时，必须在同一 PR 中更新 `.github/CODEOWNERS`
2. owner 变更（人员调动）需开独立 PR，由架构组审批
1. 新增服务/包时，必须同步更新 `.github/CODEOWNERS`
2. owner 变更（人员调动）由架构组确认后直接 commit 更新
3. CODEOWNERS 与本节表格保持同步，单一事实源为 `.github/CODEOWNERS` 文件
---
@@ -658,7 +550,7 @@ git commit -m "feat(identity): 实现用户注册接口"
- 索引式：场景→技术/规则映射
- 不写代码示例和错误示范
- 同类问题在原条目补充，不重复创建
- 在"工作经验日志"区按时间倒序追加记录
- **不设"工作经验日志"区**：模块内经验沉淀在各自服务 README，known-issues 只保留索引式场景→技术映射（见 project_rules §9）
---
@@ -739,11 +631,13 @@ git commit -m "feat(notification): 适配 UserRegistered v2 事件"
---
## 七、版本与发布
## 七、版本管理
> 不再使用 tag 发布与 release 分支（见 project_rules §15.3 no-push 模式）。版本通过 commit SHA 追溯，发布由 push main 触发 CI 自动部署。
### 7.1 版本号体系
本项目采用**双层版本号**：
本项目采用**双层版本号**（仅作记录与沟通用，不通过 git tag 标记）：
| 层级 | 格式 | 说明 |
| -------- | ------------------------ | ----------------------------------------- |
@@ -763,44 +657,38 @@ git commit -m "feat(notification): 适配 UserRegistered v2 事件"
### 7.3 Docker 镜像标签
> no-push 模式下镜像不推 registry，本地构建本地使用（见 project_rules §15.4）。下表标签格式仅用于本地镜像管理。
**格式**：`{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 类型 | 格式 | 示例 | 用途 |
| -------- | -------------------- | ---------------- | ------------ |
| Git SHA | `sha-{short}` | `sha-a1b2c3d` | 精确追溯 |
| 最新 | `latest` | `latest` | 开发环境 |
| 服务版本 | `{service}-{semver}` | `identity-1.2.0` | 服务独立版本 |
### 7.4 发布流程
```mermaid
flowchart TD
A[main 分支达到发布标准] --> B[创建 release/v0.3.x 分支]
B --> C[运行完整测试套件]
C --> D{测试通过?}
D -->|否| E[修复问题]
E --> C
D -->|是| F[更新 CHANGELOG.md]
F --> G[打 tag v0.3.0]
G --> H[CI 自动构建镜像]
H --> I[部署至 staging]
I --> J[冒烟测试]
J --> K{冒烟通过?}
K -->|否| L[修复并重新发布]
L --> C
K -->|是| M[审批发布至 production]
M --> N[monitoring 观察指标]
N --> O{指标正常?}
O -->|否| P[紧急回滚]
O -->|是| Q[发布完成]
Q --> R[合并 release 分支回 main]
A[开发 AI 本地校验通过] --> B[直接 push main]
B --> C[CI 自动触发 quality + deploy]
C --> D{CI 通过?}
D -->|否| E[git revert + 修复后重新 push]
E --> B
D -->|是| F[部署至目标环境]
F --> G[健康检查轮询 /healthz]
G --> H{健康?}
H -->|否| I[输出容器日志 + 紧急回滚 §8]
H -->|是| J[发布完成]
J --> K[更新 CHANGELOG.md]
```
> 不再创建 release 分支、不再打 git tag。发布点通过 commit SHA 追溯，回滚通过 `git revert` 或 `workflow_dispatch` 指定 `commit_sha`（见 project_rules §15.4）。
### 7.5 CHANGELOG 格式
`CHANGELOG.md` 按 [Keep a Changelog](https://keepachangelog.com/zh-CN/) 格式维护：
`CHANGELOG.md` 按 [Keep a Changelog](https://keepachangelog.com/zh-CN/) 格式维护，版本号对应阶段迭代（不绑定 git tag）：
```markdown
## [v0.3.0] - 2026-08-15
@@ -847,30 +735,30 @@ 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` + push main 触发 CI 重新部署 | 5-10 分钟 |
| 镜像问题 | `kubectl rollout undo` | 1-2 分钟 |
| 数据库迁移问题 | 执行迁移 down 脚本 | 5-30 分钟 |
| 配置错误 | 回滚 ConfigMap/Secret | 1-2 分钟 |
| 全站故障 | `workflow_dispatch` 指定稳定 `commit_sha` | 10-30 分钟 |
### 8.2 代码回滚
> 不再创建 hotfix 分支。直接在 main 上 `git revert` 后 push，CI 自动重新部署。
```bash
# 1. 确认要回滚的 commit
git log --oneline -10
# 2. 创建回滚分支
git checkout -b hotfix/v0.3.1
# 2. 拉取最新 main
git pull --rebase origin main
# 3. 回滚指定 commit
# 3. 回滚指定 commit（生成反向 commit）
git revert <commit-sha>
# 4. 推送并创建 PR
git push origin hotfix/v0.3.1
# 5. 紧急审批合并后部署
# 4. 直接 push main（CI 自动触发重新部署）
git push origin main
```
### 8.3 K8s 部署回滚
@@ -955,30 +843,31 @@ 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`） | 服务/包名（如 `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/` 目录独立记录 |
| 维度 | CICD（Next.js 单应用） | Edu（微服务 monorepo） |
| --------------------- | -------------------------------- | ----------------------------------------------------------------- |
| 仓库结构 | 单一 Next.js 应用 | 多语言 monorepo（pnpm + go.work + uv） |
| 分支策略 | trunk-based | trunk-based，**直接 push main，无分支无 PR** |
| 提交规范 | Conventional Commits | Conventional Commits（沿用，scope 扩展至服务/包） |
| scope 范围 | 模块名（如 `exams`、`homework`） | 服务/包名（如 `iam`、`api-gateway`、`shared-proto`） |
| commitlint scope-enum | 35 个模块 | 26 个 scope（含服务/包/工具/平台级，与 `.commitlintrc.js` 同步） |
| 代码审查 | PR Reviewer 1 人 | **事后 review**（无 PR，通过 commit history 追溯） |
| 合并策略 | Squash Merge | **直接 push main**（无合并操作） |
| 版本号 | 单一应用版本 | 双层（平台版本 + 服务独立版本，仅记录不打 tag） |
| 发布粒度 | 整体发布 | 按服务独立发布 |
| Docker 镜像 | 单一镜像 | 每服务一镜像（no-push 本地构建，见 project_rules §15） |
| 回滚粒度 | 整体回滚 | 按服务回滚 |
| 数据库迁移 | Drizzle 单库 | 每服务独立库 + 独立迁移 |
| 文档同步 | `npm run arch:scan` | `pnpm run arch:scan`（多语言扫描） |
| CI 检查 | lint + tsc + test | lint + typecheck + test（按语言分别执行） |
| 紧急回滚 | `git revert` + 重新部署 | `git revert` + push main 触发 CI，或 `workflow_dispatch` 指定 SHA |
| 事故复盘 | known-issues.md | `incidents/` 目录独立记录 |
---
## 变更记录
| 版本 | 日期 | 变更内容 |
| ---- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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 说明 |
| 版本 | 日期 | 变更内容 |
| ---- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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 说明 |
| 1.2 | 2026-07-10 | 因 Gitea 问题移除分支/PR 流程：§1 改为直接 push main（移除特性/发布/hotfix 分支命名与保护）；§4 改为事后 Code Review（移除 PR 流程/标题/模板/合并策略，保留 Code Review 清单与 CODEOWNERS 追溯）；§7 改为版本管理（移除 release 分支与 tag 发布，用 commit SHA 追溯）；§8 移除 hotfix 分支回滚，改为直接 git revert + push main；§9 更新差异表 |