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

.trae/rules/project_rules.md

@@ -28,7 +28,7 @@
 | `docs/architecture/0010_architecture.md`           | 理想蓝图（目标态）                                       |
 | `docs/architecture/roadmap/`                       | 长远规划（tech-debt / pending-features）                 |
 | `docs/architecture/runbooks/`                      | 运维手册（P6 硬化、post-p6-followup、incident-response） |
-| `docs/troubleshooting/known-issues.md`             | 已知问题速查（场景→技术映射 + 工作经验日志）             |
+| `docs/troubleshooting/known-issues.md`             | 已知问题速查（场景→技术映射，索引式，不写工作日志）      |
 
 ### 需要同步图的场景
 
@@ -246,11 +246,13 @@ services/[service]/src/
 
 ## 8. Git 工作流
 
-- **分支策略**：trunk-based（直接提交 main 分支，小项目）
-- **大型团队**：feature branch + PR，PR 至少 1 人 review
+- **分支策略**：trunk-based，直接提交到 `main` 分支（因 Gitea 问题，**不再使用特性分支/发布分支/hotfix 分支，不再使用 PR 流程**）
+- **提交方式**：所有变更直接 `git push origin main`；禁止 `git checkout -b` 创建任何分支
+- **提交前同步**：`git pull --rebase origin main` 拉取最新，解决冲突后再 push
 - **pre-commit hook**：`lint-staged` 自动修复 + 校验（见 `lint-staged.config.js`）
 - **commit-msg hook**：commitlint 校验格式
 - **禁止 force push**：除非显式要求并通知团队
+- **回滚**：`git revert <commit>` + `git push origin main`，不使用分支回滚
 
 ---
 
@@ -286,7 +288,8 @@ services/[service]/src/
 - **索引式**：场景→技术/规则映射，不写代码示例和错误示范列
 - **去重**：同类问题在原条目补充，不重复创建
 - **引用架构规则**：架构分层、模块结构等规则引用 004 和本规则文件，不重复
-- **工作经验日志**：在"工作经验日志"区按时间倒序追加（50 条上限），记录"做了什么/学到什么/下次注意"
+- **只读自己模块分区**：AI 查阅 known-issues 时只读自己负责模块的分区，禁止读其他 AI 模块的分区（避免被历史记录误导）
+- **禁止流水日志**：known-issues 不再设"工作经验日志"区，不写跨模块流水账；模块内的经验沉淀在各自模块的 README/文档中
 
 ---
 
@@ -294,14 +297,18 @@ services/[service]/src/
 
 **所有 AI 工作必须遵循此流程，违反即违规。**
 
-### 阶段 1：上下文加载
+### 阶段 1：上下文加载（按需阅读，严格模块边界）
+
+> **架构文档按需阅读**：模块开发只读自己模块的架构与服务 README；项目整体相关工作（跨模块契约、基础设施、文档体系、shared-proto）才读全局架构文档。功能开发/文档书写等强依赖场景必须读对应架构。
+>
+> **严格模块边界**：AI 只读自己负责模块的文档与源码，不越界阅读其他模块的内部实现细节（避免被历史记录或他人方案误导）。仅在需要确认跨模块契约时，才读对方的对外接口（proto/API/事件）。
 
 1. `pnpm run arch:scan` 更新 arch.db
 2. `pnpm run arch:query -- module-deps` 查目标模块依赖
 3. `pnpm run arch:query -- symbol-refs <目标函数>` 查调用链
-4. 阅读 `services/[service]/README.md` 读模块工作流程
-5. 查 `docs/troubleshooting/known-issues.md` "模块经验"分区读相关经验
-6. 查 `docs/architecture/004_architecture_impact_map.md` 对应章节
+4. 阅读 `services/[service]/README.md` 读**自己模块**的工作流程
+5. 查 `docs/troubleshooting/known-issues.md` **仅读自己模块的分区**，禁止读其他 AI 模块分区
+6. 模块开发：查 `docs/architecture/004_architecture_impact_map.md` **对应模块章节**；全局工作：查 004 全文
 
 ### 阶段 2：执行工作
 
@@ -314,13 +321,12 @@ services/[service]/src/
 
 ### 阶段 3：经验沉淀（强制，不可跳过）
 
-1. 在 `docs/troubleshooting/known-issues.md` "工作经验日志"区追加一条记录：
-   - 日期 + 时间
-   - 模块
-   - 做了什么 + 学到什么
-2. 若发现新的"场景→技术"映射 → 提炼到对应模块分区
-3. 若发现新的架构决策 → 更新 004
-4. 若代码结构变化 → `pnpm run arch:scan` 确认 arch.db 已更新
+1. 若发现新的"场景→技术"映射 → 提炼到 `docs/troubleshooting/known-issues.md` 对应**模块分区**（索引式一行，不写流水日志）
+2. 若发现新的架构决策 → 更新 004
+3. 若代码结构变化 → `pnpm run arch:scan` 确认 arch.db 已更新
+4. 模块内的经验沉淀到**自己模块的 README/文档**，不污染全局 known-issues
+
+> **禁止**在 known-issues.md 写跨模块"工作经验日志/流水账"。known-issues 是索引式速查手册，只保留场景→技术映射。新 AI 不应被前任同名 AI 的流水记录误导。
 
 ---
 
@@ -375,44 +381,35 @@ services/[service]/src/
 
 ### 14.1 角色与权限
 
-| 角色                       | 职责                                     | push 特性分支 | 创建 PR | 合并 PR     | push main | force push main |
-| -------------------------- | ---------------------------------------- | ------------- | ------- | ----------- | --------- | --------------- |
-| **协调 AI（Coordinator）** | PR 审核、合并、冲突仲裁、发布            | ✅            | ✅      | ✅          | ❌        | ⚠️（仅事故）    |
-| **开发 AI（Dev）**         | 按模块分工写代码、提 PR                  | ✅            | ✅      | ❌          | ❌        | ❌              |
-| **SRE AI**                 | `infra/` 维护、部署                      | ✅（infra）   | ✅      | ✅（infra） | ❌        | ⚠️（仅事故）    |
-| **人类决策者**             | 架构决策、Breaking Change 审批、发布确认 | —             | —       | —           | —         | —               |
+| 角色                       | 职责                                     | 直接 push main | 修改他人模块                  | force push main |
+| -------------------------- | ---------------------------------------- | -------------- | ----------------------------- | --------------- |
+| **协调 AI（Coordinator）** | 契约管理、交叉审查、冲突仲裁、发布       | ✅             | ✅（shared-proto/infra/docs） | ⚠️（仅事故）    |
+| **开发 AI（Dev）**         | 按模块分工写代码、直接 push main         | ✅             | ❌                            | ❌              |
+| **SRE AI**                 | `infra/` 维护、部署                      | ✅（infra）    | ✅（仅 infra）                | ⚠️（仅事故）    |
+| **人类决策者**             | 架构决策、Breaking Change 审批、发布确认 | —              | —                             | —               |
 
-### 14.2 模块单一负责制
+> 不再使用特性分支与 PR。所有变更直接 `git push origin main`。代码审查改为事后追溯（通过 commit message + commit history），不在 push 前阻塞。
 
-- 每个模块（限界上下文）只有一个 AI 负责，禁止并行修改同一模块
+### 14.2 模块单一负责制与模块边界（强制）
+
+- **每个模块（限界上下文）只有一个 AI 负责，禁止并行修改同一模块**
+- **严格模块边界**：AI 只修改自己负责的目录（`services/<my-service>/` 或 `apps/<my-app>/`），禁止越界修改他人模块的源码
+- **只读自己模块文档**：AI 阅读文档时只读自己模块的 README/设计文档/known-issues 分区，**禁止阅读其他 AI 模块的内部文档和历史记录**（避免被前任同名 AI 的过时方案/审计结果误导）
+- **跨模块契约只读接口**：需要确认跨模块协同时，只读对方的对外接口（proto message / API 端点 / Kafka 事件 schema），不读对方内部实现
 - `shared-proto`、`shared-tokens`、`docs/` 由协调 AI 维护，开发 AI 只读引用
 - `infra/` 由 SRE AI 专门负责，业务 AI 不直接修改
 
-### 14.3 分支命名规范（强制）
+### 14.3 直接 push main 规则（强制）
 
-```
-<type>/<scope>-<task-id>-<ai-id>
-```
+1. **禁止创建分支**：不使用 `git checkout -b`、`git branch` 创建任何特性/发布/hotfix 分支
+2. **直接 push main**：所有变更 `git add` → `git commit` → `git pull --rebase origin main` → `git push origin main`
+3. **提交前校验**：push 前必须本地通过 `pnpm run lint` + `pnpm run typecheck`（TS）/ `go vet ./...`（Go）/ `ruff check src/`（Python）
+4. **提交信息规范**：遵循 Conventional Commits（见 §7），commit message 末尾标注 AI 身份（见 §14.6）
+5. **不阻塞审查**：push 不等待 review，问题通过事后 commit revert 或后续 commit 修正
 
-- `type`：feat / fix / refactor / docs / chore / test
-- `scope`：见 §7 提交规范 scope-enum（26 项）
-- `task-id`：任务简短描述（kebab-case）
-- `ai-id`：AI 唯一标识符（如 `ai01`、`ai02`、`coord`）
+### 14.4 跨模块变更顺序（强制）
 
-**示例**：`feat/classes-add-pagination-ai01`
-
-### 14.4 PR 与合并规则（强制）
-
-1. **禁止直接 push 到 `main`**：所有变更通过 PR
-2. **PR 必须通过 CI**：lint / typecheck / build / test 全绿
-3. **PR 必须通过 CODEOWNERS review**：至少 1 人 approve
-4. **合并策略**：Squash Merge（默认），Rebase Merge（保留多 commit 历史），**禁止 Merge Commit**
-5. **特性分支寿命 ≤ 3 天**：超期需 rebase 最新 main
-6. **跨模块变更拆分**：按依赖顺序拆多个 PR（proto → service → gateway → frontend），协调 AI 按序合并
-
-### 14.5 跨模块变更顺序（强制）
-
-修改涉及多模块时，必须按以下顺序拆分 PR 并顺序合并：
+修改涉及多模块时，按依赖顺序**依次直接 push main**（不拆 PR，按顺序提交避免下游编译失败）：
 
 1. `shared-proto`（proto 契约）
 2. 业务服务（classes / iam / core-edu 等）
@@ -420,29 +417,28 @@ services/[service]/src/
 4. BFF（teacher-bff 等）
 5. 微前端（teacher-portal 等）
 
-> 每合并一个 PR，后续 PR 的开发 AI 必须 rebase 最新 main 并重新校验。
+> 每提交一层并 push 后，再开发下一层。协调 AI 负责监督顺序，避免越级提交导致下游构建失败。
 
-### 14.6 冲突处理规则
+### 14.5 冲突处理规则
 
-- **文件冲突**：后合并的 PR rebase 最新 main，`git push --force-with-lease`（仅自己的分支）
-- **架构冲突**：由协调 AI 仲裁保留方案
-- **禁止 `git push --force` 到 main 或他人分支**
+- **push 冲突**：`git pull --rebase origin main` 解决冲突后重新 `git push origin main`
+- **架构冲突**：由协调 AI 仲裁保留方案，通过 commit revert + 新 commit 修正
+- **禁止 `git push --force` 到 main**：仅协调 AI 在事故时可 `--force-with-lease`
 
-### 14.7 AI 身份标注（强制）
+### 14.6 AI 身份标注（强制）
 
-每个 PR 描述末尾必须追加：
+每个 commit message body 末尾必须追加（用于追溯，不再有 PR 描述）：
 
-```markdown
+```text
 ---
 
-**AI Agent**: <ai-id> (<负责模块>)
-**Branch**: <分支名>
-**Coordinator**: <协调 AI ai-id>
+AI-Agent: <ai-id> (<负责模块>)
+Coord: <协调 AI ai-id>
 ```
 
-每个 AI 完成任务后，在 `docs/troubleshooting/known-issues.md` "工作经验日志"区追加记录（见 §9.3）。
+> 不再有 Branch 字段（不使用分支）。每个 AI 的经验沉淀到自己模块的 README/文档，**禁止**在 known-issues.md 写跨模块工作日志。
 
-### 14.8 敏感文件保护
+### 14.7 敏感文件保护
 
 以下文件修改需人类决策者额外审批：
 
@@ -470,18 +466,17 @@ services/[service]/src/
 | ----------------- | ---- | ------------------------------------ | -------- |
 | **quality-ts**    | ✅   | pnpm lint + typecheck + test + build | 失败阻断 |
 | **quality-go**    | ✅   | go vet + build + test                | 失败阻断 |
-| **quality-proto** | ✅   | buf lint + buf breaking（仅 PR）     | 失败阻断 |
+| **quality-proto** | ✅   | buf lint + buf breaking              | 失败阻断 |
 | **deploy**        | 串行 | docker compose up --build + 健康检查 | 失败阻断 |
 
-> deploy job 仅在 `push main` 或 `workflow_dispatch` 时触发，PR 时不部署
+> 不再使用 PR。所有质量检查与部署在 push main 时触发。
 
 ### 15.3 触发条件
 
-| 事件              | 触发阶段                                        | 触发条件                         |
-| ----------------- | ----------------------------------------------- | -------------------------------- |
-| PR 创建/更新      | quality-ts + quality-go + quality-proto（并行） | 所有路径                         |
-| push 到 main      | 上述全部 + deploy                               | 合并后自动                       |
-| workflow_dispatch | 上述全部 + deploy                               | 手动触发，支持 `commit_sha` 回滚 |
+| 事件              | 触发阶段                                                | 触发条件                         |
+| ----------------- | ------------------------------------------------------- | -------------------------------- |
+| push 到 main      | quality-ts + quality-go + quality-proto（并行）+ deploy | 每次 push main 自动              |
+| workflow_dispatch | 上述全部 + deploy                                       | 手动触发，支持 `commit_sha` 回滚 |
 
 > **不再支持 tag 发布**：no-push 模式下不用 `git tag v*` 触发。版本管理通过 commit SHA 追溯。