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

fix: code compliance audit and fix across all services
Some checks failed
CI / quality-ts (push) Failing after 48s
Details
CI / quality-go (push) Failing after 4s
Details
CI / quality-proto (push) Failing after 2s
Details
CI / deploy (push) Has been skipped
Details

Browse Source 
NestJS (6 services): implement @RequirePermission decorator with
SetMetadata+Reflector, register APP_GUARD globally, fix as assertions
to type guards, add explicit return types, fix import type for express,
fix /metrics implicit any, replace native Error with ApplicationError,
remove typeorm remnants, register LifecycleService.

teacher-bff: add logger, ApplicationError, GlobalErrorFilter, forward
real userId to downstream, log downstream failures, migrate health
controller to shared/health.

Go (2 services): interface to any, doc comments, CORS dev whitelist,
JWT secret fail-fast, push-gateway internal API auth, metrics and
readyz endpoints, remove dead code.

Python (2 services): lifespan return type, dev_mode to bool, data-ana
APIRouter, ai POST body model, ClickHouse async wrapping.
This commit is contained in:
SpecialX
2026-07-09 17:28:27 +08:00
parent b53a486c6e
commit 0a71b02e04
93 changed files with 5775 additions and 608 deletions
Download Patch File Download Diff File Expand all files Collapse all files

184
docs/standards/multi-ai-collaboration.md
View File

@@ -37,36 +37,171 @@
---
## 2. 模块分工矩阵
## 2. 两种协作模式
### 2.1 模块清单与 AI 分配
本项目支持两种 AI 协作模式，根据开发阶段灵活切换：
每个 AI 负责一个"限界上下文"，避免跨模块修改导致冲突。
### 2.0 模式选择
| 模块 | scope | 路径 | 负责阶段 | 建议 AI 数 |
| -------------- | ---------------- | ------------------------- | -------- | ------------ |
| api-gateway | `api-gateway` | `services/api-gateway/` | P1 | 1 |
| classes | `classes` | `services/classes/` | P1 | 1 |
| teacher-portal | `teacher-portal` | `apps/teacher-portal/` | P1-P2 | 1 |
| iam | `iam` | `services/iam/` | P2 | 1 |
| teacher-bff | `teacher-bff` | `services/teacher-bff/` | P2 | 1 |
| core-edu | `core-edu` | `services/core-edu/` | P3 | 1 |
| content | `content` | `services/content/` | P4 | 1 |
| data-ana | `data-ana` | `services/data-ana/` | P4 | 1 |
| msg | `msg` | `services/msg/` | P5 | 1 |
| ai | `ai` | `services/ai/` | P5 | 1 |
| push-gateway | `push-gateway` | `services/push-gateway/` | P5 | 1 |
| shared-proto | `shared-proto` | `packages/shared-proto/` | 跨阶段 | 协调 AI 维护 |
| shared-tokens | `shared-tokens` | `packages/shared-tokens/` | 跨阶段 | 协调 AI 维护 |
| infra | `infra` | `infra/` | 跨阶段 | 1 (SRE AI) |
| docs | `docs` | `docs/` | 跨阶段 | 协调 AI 维护 |
| 模式 | 适用阶段 | 特点 |
| ------------------ | ---------------------------------- | ----------------------------------------------------- |
| **单仓库并行模式** | 架构设计外包、各服务独立功能开发 | 无需 PR，直接 push main；路径级别物理隔离，几乎零冲突 |
| **PR 模式** | 共享文件修改、跨模块变更、代码审核 | 标准 PR 流程，coord 审核后 Squash Merge |
### 2.2 分工原则
> 当前架构设计外包阶段使用**单仓库并行模式**，详见 [AI 分配方案](../architecture/ai-allocation.md)。
---
### 2.1 单仓库并行模式
**适用场景**：各 AI 修改的文件路径物理隔离（不同 `services/<name>/` 目录），无需 PR 审核。
**核心规则**：
1. 每个 AI 只能修改自己负责的目录
2. `pnpm-lock.yaml` 是唯一可能冲突的共享文件，冲突时取远程版本后 `pnpm install` 重新生成
3. proto 变更由 coord 统一管理（其他 AI 只读引用 `packages/shared-proto/`）
**提交流程**：
```bash
# 每天开始
git pull origin main --rebase
# 在自己目录内工作后提交
git add services/<my-service>/...
git commit -m "feat(<scope>): <描述>"
# 直接 push
git pull origin main --rebase # 先拉最新
git push
```
**pnpm-lock.yaml 冲突处理**：
```bash
git pull origin main --rebase
# 若 pnpm-lock.yaml 冲突：
git checkout --theirs pnpm-lock.yaml
pnpm install
git add pnpm-lock.yaml
git rebase --continue
```
---
### 2.2 PR 模式（标准流程）
PR 模式见 §3-§6（分支策略、推送流程、PR 流程、审核合并）。
---
### 2.3 模块完整清单
| 类别 | 服务名 | scope | 路径 | 阶段 | 语言 |
| ---- | -------------- | ---------------- | ------------------------ | ------ | -------- |
| 网关 | api-gateway | `api-gateway` | `services/api-gateway/` | P1 | Go |
| 网关 | push-gateway | `push-gateway` | `services/push-gateway/` | P5 | Go |
| BFF | teacher-bff | `teacher-bff` | `services/teacher-bff/` | P2 | TS |
| BFF | student-bff | `student-bff` | `services/student-bff/` | P3 | TS |
| BFF | parent-bff | `parent-bff` | `services/parent-bff/` | P4 | TS |
| 业务 | iam | `iam` | `services/iam/` | P2 | TS |
| 业务 | core-edu | `core-edu` | `services/core-edu/` | P3 | TS |
| 业务 | content | `content` | `services/content/` | P4 | TS |
| 业务 | msg | `msg` | `services/msg/` | P5 | TS |
| 业务 | data-ana | `data-ana` | `services/data-ana/` | P4 | Python |
| 业务 | ai | `ai` | `services/ai/` | P5 | Python |
| 前端 | teacher-portal | `teacher-portal` | `apps/teacher-portal/` | P2 | TS |
| 前端 | student-portal | `student-portal` | `apps/student-portal/` | P3 | TS |
| 前端 | parent-portal | `parent-portal` | `apps/parent-portal/` | P4 | TS |
| 前端 | admin-portal | `admin-portal` | `apps/admin-portal/` | P6 | TS |
| 共享 | shared-proto | `shared-proto` | `packages/shared-proto/` | 跨阶段 | protobuf |
| 共享 | shared-ts | `shared-ts` | `packages/shared-ts/` | 跨阶段 | TS |
| 共享 | shared-go | `shared-go` | `packages/shared-go/` | 跨阶段 | Go |
| 共享 | shared-py | `shared-py` | `packages/shared-py/` | 跨阶段 | Python |
| 基础 | infra | `infra` | `infra/` | 跨阶段 | — |
### 2.4 当前阶段 AI 分配（7 AI + 1 coord）
详见 [AI 分配方案](../architecture/ai-allocation.md#3-ai-分配方案7-ai--1-coord)。摘要如下：
| AI | 服务 | 语言 |
| ----- | ----------------------------------------------------------- | ------ |
| ai01 | api-gateway、push-gateway | Go |
| ai02 | iam | TS |
| ai03 | teacher-bff、core-edu | TS |
| ai04 | student-bff、parent-bff | TS |
| ai05 | content、msg | TS |
| ai06 | data-ana、ai | Python |
| ai07 | teacher-portal、student-portal、parent-portal、admin-portal | TS |
| coord | shared-proto、shared-*、infra/、docs/、CI/CD | — |
### 2.5 分工原则
1. **单一负责制**：每个模块只有一个 AI 负责，避免并行修改同一文件
2. **契约集中管理**：`shared-proto` 由协调 AI 维护，开发 AI 只读引用
3. **跨模块变更拆分**：需要修改多个模块时，拆成多个 PR，按依赖顺序合并
4. **基础设施独立**：`infra/` 由 SRE AI 专门负责，业务 AI 不直接修改
2. **同语言内聚**：一个 AI 负责多个同语言服务，降低学习成本
3. **契约集中管理**：`shared-proto` 由 coord 维护，开发 AI 只读引用
4. **跨模块变更拆分**：需要修改多个模块时，按依赖顺序（proto → service → gateway → BFF → frontend）
5. **基础设施独立**：`infra/` 由 coord（或 SRE AI）专门负责
6. **物理路径隔离**：目录级别隔离，单仓库并行几乎零文件冲突
### 2.6 架构设计外包三阶段
当前项目处于**架构设计外包阶段**，所有 AI 需先完成设计再动手写代码。完整文档见 [AI 分配方案](../architecture/ai-allocation.md)。简述如下：
```
阶段 1：全局理解 → 交付"理解确认书"
阶段 2：模块架构设计 → 交付"模块架构设计文档"，coord 交叉审查
阶段 3：按图实施 → 按设计文档写代码，coord 定期巡检一致性
```
**阶段 1 交付物模板**：
```markdown
## 模块理解确认书 — [模块名]
### 1. 我在架构中的位置
- 层级 / 上下游 / 通信方式
### 2. 我的限界上下文
- 聚合/实体 / 业务领域（D1-D6）/ 边界外
### 3. 我与外部的契约
- proto message / API/事件 / 错误码前缀
### 4. 我的技术栈
### 5. 我的阶段归属（P1-P6）
### 6. 黄金模板对齐清单（对照 classes 服务）
```
**阶段 2 交付物模板**：
```markdown
## 模块架构设计文档 — [模块名]
### 1. 模块内部分层图
### 2. 领域模型（聚合根/实体/值对象）
### 3. 数据模型（表/schema/索引/读写分离）
### 4. API 设计（端点/权限/请求响应）
### 5. 事件设计（发布/消费/Topic）
### 6. 横切关注点（权限/错误/可观测/健康/优雅关闭）
### 7. 与其他模块的交互点（契约清单）
### 8. 风险与假设
```
**coord 交叉审查**：收到全部 7 份设计文档后，检查接口一致性、端口冲突、Topic 重复、错误码重叠、黄金模板对齐。
---
@@ -726,6 +861,7 @@ git tag -a v<version> -m "..." && git push origin v<version>
## 15. 相关文档
- [AI 分配方案](../architecture/ai-allocation.md) — 架构设计外包 AI 分配与三阶段流程
- [Git 工作流](./git-workflow.md) — 提交规范、分支策略、CODEOWNERS
- [本地启动手册](./local-dev-runbook.md) — 手动启动服务
- [项目规则](../../.trae/rules/project_rules.md) — 强制约束