faaaf29f67
1.AI 协作文档体系重构(objections/worklines/contracts+matrix.md) 2.coord 仲裁文档(final-decisions/cross-review/final-rulings/orchestration) 3.各服务 01/02 文档补全 4.共享包初始化(shared-ts/shared-go/hooks/ui-components/ui-tokens) 5.Proto 契约补全 6.004 架构影响地图更新 7.端口分配表 8.设计规格文档
1241 lines
69 KiB
Markdown
1241 lines
69 KiB
Markdown
# 总裁最终裁决（President Final Rulings）
|
||
|
||
> 版本：1.0
|
||
> 日期：2026-07-09
|
||
> 决策者：总裁（用户）
|
||
> 执行者：coord（统一落实）
|
||
> 适用范围：Edu 微服务架构全部 16 个 AI（ai01-ai16）+ coord 维护的 shared-* 包与文档
|
||
> 关联文档：
|
||
>
|
||
> - [coord-final-decisions.md](./coord-final-decisions.md)（80+ 项强制裁决，本文件为其上层总裁裁决）
|
||
> - [ai-work-orchestration.md](./ai-work-orchestration.md)（6 批次并行规划，本文件调整其时间线）
|
||
> - [issues.md](../issues.md)（70+ 问题汇总，本文件逐个裁决）
|
||
> - [004 架构影响地图](./004_architecture_impact_map.md)
|
||
> - [port-allocation.md](../../infra/port-allocation.md)
|
||
> - [ai-allocation.md](./ai-allocation.md)
|
||
|
||
---
|
||
|
||
## 0. 裁决原则
|
||
|
||
### 0.1 总裁授权范围
|
||
|
||
本文件是用户作为总裁对全部已汇总问题（ISSUE-001 ~ ISSUE-066，含编号冲突）的**最终裁决**，覆盖：
|
||
|
||
1. **coord-final-decisions.md** 80+ 项裁决的最终确认（无推翻）
|
||
2. **ai-work-orchestration.md** 6 批次时间线的最终调整
|
||
3. **issues.md** 70+ 问题的逐个裁决（状态全部转为"总裁已裁决"）
|
||
4. 文档同步遗漏的修复指令
|
||
5. 编号冲突的整理规则
|
||
6. 各 AI 工作内容的最终边界
|
||
|
||
### 0.2 裁决优先级
|
||
|
||
裁决按以下优先级分组，AI 执行时按优先级处理：
|
||
|
||
- **P0 立即执行**：文档同步遗漏修复 + 编号冲突整理
|
||
- **P1 批次 0 启动前完成**：设计契约明确 + 工具包产出
|
||
- **P2 各批次启动前完成**：文档回写 + 工作量分级
|
||
- **P3 各阶段执行中持续**：跨阶段扩展例外执行
|
||
|
||
### 0.3 "不分阶段"与"批次"的最终澄清
|
||
|
||
针对 ISSUE-021（ai08）/ ISSUE-015 §0.1（ai15）表述歧义问题，总裁最终澄清：
|
||
|
||
| 概念 | 适用层级 | 含义 | 禁止事项 |
|
||
| ------------------ | ---------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
|
||
| **不分阶段** | 代码实现层面 | 服务首次落地即采用最终方案，禁止"前期简化版后期重构" | 禁止 P2 写 REST 后期切 GraphQL；禁止 P2 mock 数据后期接真实 gRPC |
|
||
| **批次** | 工作排序层面 | 因服务依赖需串行启动（下游未就绪时上游无法启动） | 批次时间线允许调整，但不得作为"先简化后重构"的借口 |
|
||
| **跨阶段扩展例外** | 唯一允许的"分阶段"场景 | BFF /readyz 探针列表 / Dashboard Resolver 字段填充 / AuthorizationGuard 内部实现允许按阶段扩展 | 见 §2.3 详细验收标准 |
|
||
|
||
**核心规则**：批次规划保证下游就绪后再启动上游；不分阶段保证每个服务首次实现即最终方案。两者不冲突。
|
||
|
||
### 0.4 编号冲突整理规则（ISSUE-031/035 处理）
|
||
|
||
针对 issues.md 严重的编号冲突（ISSUE-024/025 ai11 与 ai09 重复 / ISSUE-028~~030 ai04 与 ai11 重复 / ISSUE-031 ai04 与 ai15 重复 / ISSUE-032~~035 ai03 与 ai15 重复 / ISSUE-036 ai03 与 ai13 重复 / ISSUE-044~048 ai16 与 ai06 重复），总裁裁决：
|
||
|
||
1. **保留所有 issues 原始内容不删除**（避免信息丢失）
|
||
2. **不再重新编号**（重编号工作量大，且 AI 已在文档中引用现有编号）
|
||
3. **在本文件 §10 问题索引表中统一映射**，每个 issue 用 `ISSUE-XXX-<提请AI>` 格式唯一定位（如 ISSUE-024-ai11 / ISSUE-024-ai09）
|
||
4. **coord 在 issues.md §0.5 添加索引指针**指向本文件，AI 查询时先看本文件索引表
|
||
|
||
---
|
||
|
||
## 1. P0 立即修复：文档同步遗漏
|
||
|
||
### 1.1 port-allocation.md §5 iam 行修正（ISSUE-001/015）
|
||
|
||
**裁决**：修正 port-allocation.md §5（行 77 附近）iam 行：
|
||
|
||
- 修改前：`IamService（P3 启用） | P3`
|
||
- 修改后：`IamService（P2 启用，I1 裁决） | P2`
|
||
|
||
**理由**：对齐 coord-final-decisions.md I1 裁决（iam P2 即启用 gRPC server 50052）+ port-allocation.md §3 已修正的内容。
|
||
|
||
**执行者**：coord
|
||
**完成期限**：本裁决发布后立即
|
||
|
||
### 1.2 004 §4.2 gRPC 启用矩阵修正（ISSUE-003）
|
||
|
||
**裁决**：修正 004 §4.2 gRPC 启用阶段矩阵，iam 行从"P3 启用"改为"P2 启用"。
|
||
|
||
**理由**：对齐 I1 裁决。
|
||
|
||
**执行者**：coord
|
||
**完成期限**：本裁决发布后立即
|
||
|
||
### 1.3 004 §16.7.4 P4 清单补 QuestionService（ISSUE-016）
|
||
|
||
**裁决**：004 §16.7.4 P4 启动前整改清单补充 content QuestionService：
|
||
|
||
- 修改前：仅列"ChapterService / TextbookService.ListTextbooks"
|
||
- 修改后：补充"+ QuestionService（N3 裁决，P4 即补全，不等到 P5）"
|
||
|
||
**理由**：对齐 coord-final-decisions.md N3 裁决（QuestionService proto P4 即补全）。
|
||
|
||
**执行者**：coord
|
||
**完成期限**：本裁决发布后立即
|
||
|
||
### 1.4 004 §16.7.5 P5 清单删 QuestionService（ISSUE-016）
|
||
|
||
**裁决**：004 §16.7.5 P5 启动前整改清单删除"ai09 content 补 QuestionService RPC（阻塞 ai 出题）"项。
|
||
|
||
**理由**：QuestionService 已在 P4 补全，P5 不再重复。
|
||
|
||
**执行者**：coord
|
||
**完成期限**：本裁决发布后立即
|
||
|
||
### 1.5 004 §7.2 Kafka topic 表格修订（ISSUE-043/053）
|
||
|
||
**裁决**：修订 004 §7.2 Kafka topic 路由表：
|
||
|
||
- 删除：`| edu.notification.events | 通知事件 | Msg | push-gateway |`
|
||
- 新增 3 行：
|
||
|
||
```
|
||
| edu.notification.sent | 通知发送 | Msg | push-gateway、DataAna |
|
||
| edu.notification.read | 通知已读 | Msg | DataAna |
|
||
| edu.notification.recalled | 通知撤回 | Msg | DataAna |
|
||
| edu.notification.requested | 通知投递请求 | Msg | push-gateway |
|
||
```
|
||
|
||
- 在表格下方追加注释："本表已对齐 §16.3.2 + G16 裁决，禁止抽象名 `edu.*.events`"
|
||
|
||
**理由**：对齐 G16 裁决（topic 命名统一 `edu.<domain>.<aggregate>.<action>`，禁止抽象名）+ ai10 msg 02 §5 已设计的具体动作名 + ai02 push-gateway 消费 `edu.notification.requested`（ISSUE-053）。
|
||
|
||
**执行者**：coord
|
||
**完成期限**：本裁决发布后立即
|
||
|
||
### 1.6 coord-final-decisions.md + ai-work-orchestration.md 相对路径修正（ISSUE-031-ai15）
|
||
|
||
**裁决**：修正两份文档 L7 关联文档引用：
|
||
|
||
- `coord-final-decisions.md` L7：`[ai-allocation.md](./architecture/ai-allocation.md)` → `[ai-allocation.md](./ai-allocation.md)`
|
||
- `ai-work-orchestration.md` L7：`[ai-allocation.md](./architecture/ai-allocation.md)` → `[ai-allocation.md](./ai-allocation.md)`
|
||
|
||
**理由**：两份文档自身位于 `docs/architecture/` 目录下，引用 `./architecture/ai-allocation.md` 会多一层路径。
|
||
|
||
**执行者**：coord
|
||
**完成期限**：本裁决发布后立即
|
||
|
||
### 1.7 issues.md §0.5 添加总裁裁决索引指针
|
||
|
||
**裁决**：在 issues.md §0.4 之后新增 §0.5：
|
||
|
||
```markdown
|
||
### 0.5 总裁最终裁决索引
|
||
|
||
> 所有 ISSUE-001 ~ ISSUE-066 的"coord 裁决"字段已由总裁最终裁决覆盖。
|
||
> 查询裁决结果请先查阅 [president-final-rulings.md](./architecture/president-final-rulings.md)。
|
||
> 本文件保留所有 issues 原始内容作为问题追溯，编号冲突通过 `ISSUE-XXX-<提请AI>` 格式唯一定位（见 president-final-rulings.md §10）。
|
||
```
|
||
|
||
**执行者**：coord
|
||
**完成期限**：本裁决发布后立即
|
||
|
||
---
|
||
|
||
## 2. P1 批次 0 启动前完成：设计契约明确
|
||
|
||
### 2.1 shared-ts Outbox 工具包设计（ISSUE-018/050）
|
||
|
||
**裁决**：coord 在批次 0.4 完成 `packages/shared-ts/src/outbox/` 设计草案，包含：
|
||
|
||
1. **包名**：`@edu/shared-ts/outbox`
|
||
2. **导出 API**：
|
||
|
||
```typescript
|
||
// 1. OutboxModule（NestJS Module 注入）
|
||
export class OutboxModule {
|
||
static forRoot(config: OutboxConfig): DynamicModule;
|
||
}
|
||
|
||
// 2. OutboxService（发布接口）
|
||
export class OutboxService {
|
||
publish(
|
||
eventType: string,
|
||
payload: unknown,
|
||
options?: PublishOptions,
|
||
): Promise<string>;
|
||
// 返回 outbox record id
|
||
}
|
||
|
||
// 3. OutboxRelayWorker（内置 Relay Worker，可注入）
|
||
export class OutboxRelayWorker {
|
||
start(): void;
|
||
stop(): Promise<void>;
|
||
}
|
||
```
|
||
|
||
3. **配置项**：
|
||
|
||
```typescript
|
||
interface OutboxConfig {
|
||
tableName: string; // 各服务可配，默认 'outbox_events'
|
||
kafkaTopic: string; // 各服务可配
|
||
pollIntervalMs: number; // 默认 1000
|
||
batchSize: number; // 默认 100
|
||
maxRetryCount: number; // 默认 5
|
||
retryBackoffMs: number; // 默认 1000，指数退避
|
||
}
|
||
```
|
||
|
||
4. **表 schema**（Drizzle migration，各服务执行）：
|
||
|
||
```sql
|
||
CREATE TABLE outbox_events (
|
||
id VARCHAR(32) PRIMARY KEY, -- cuid2
|
||
event_type VARCHAR(64) NOT NULL,
|
||
payload JSON NOT NULL,
|
||
status VARCHAR(16) DEFAULT 'pending', -- pending / published / failed
|
||
retry_count INT DEFAULT 0,
|
||
last_error TEXT,
|
||
created_at TIMESTAMP DEFAULT NOW(),
|
||
published_at TIMESTAMP
|
||
);
|
||
CREATE INDEX idx_outbox_status_created ON outbox_events(status, created_at);
|
||
```
|
||
|
||
5. **集成方式**：NestJS Module 注入（`@Module({ imports: [OutboxModule.forRoot(config)] })`）
|
||
6. **是否含 Kafka producer**：内置（iam 仅配置 topic）
|
||
7. **ORM 支持**：仅支持 Drizzle ORM（对齐黄金模板）
|
||
8. **事务边界**：业务表 + outbox 表同事务（Drizzle 事务 API），示例：
|
||
|
||
```typescript
|
||
await db.transaction(async (tx) => {
|
||
await tx.insert(users).values(newUser);
|
||
await outboxService.publish("user.created", { userId: newUser.id }, { tx });
|
||
});
|
||
```
|
||
|
||
**理由**：iam 首次接入方需求迫切（I2 裁决），core-edu / content / msg 后续接入保持一致。
|
||
|
||
**执行者**：coord
|
||
**完成期限**：批次 0.4（批次 1 启动前）
|
||
|
||
### 2.2 GraphQL schema 仲裁机制（ISSUE-019/030/037）
|
||
|
||
**裁决**：建立 GraphQL schema 仲裁规范：
|
||
|
||
1. **存放位置**：`packages/shared-ts/contracts/graphql/`
|
||
- `teacher-bff.schema.graphql`（ai03 定义，coord 仲裁）
|
||
- `student-bff.schema.graphql`（ai04 定义，coord 仲裁）
|
||
- `parent-bff.schema.graphql`（ai05 定义，coord 仲裁）
|
||
- `admin.schema.graphql`（admin 命名空间，复用 teacher-bff schema，见 §5.1）
|
||
|
||
2. **起草方**：各 BFF 负责 AI 起草，coord 仲裁
|
||
- teacher-bff：ai03 起草，coord 在批次 1 启动前仲裁第一版
|
||
- student-bff：ai04 起草（批次 1 等待期），coord 在批次 2 启动前仲裁第一版
|
||
- parent-bff：ai05 起草（批次 2 等待期），coord 在批次 3 启动前仲裁第一版
|
||
|
||
3. **覆盖范围**：
|
||
- Query/Mutation 清单（含字段定义 + 类型 + 分页规范）
|
||
- 权限点标注（F7 规范，注释形式 `# @permission: DASHBOARD_VIEW`）
|
||
- DataScope 标注（注释形式 `# @dataScope: OWN/CHILD/CLASS`）
|
||
- 错误响应格式（GraphQL errors 数组扩展 ActionState 字段，`extensions.code = BFF_*`）
|
||
|
||
4. **版本管理**：SDL-first（schema.graphql 文件），配合 graphql-codegen 生成 TS 类型
|
||
|
||
5. **命名规范**：
|
||
- Query/Mutation：camelCase（如 `teacherDashboard` / `listClassesByTeacher`）
|
||
- 分页：Relay Cursor Connections 规范（`{ edges, pageInfo, totalCount }`）
|
||
- 错误：GraphQL errors 数组 + `extensions.code` + `extensions.traceId`
|
||
|
||
6. **协调流程**：
|
||
- BFF AI 起草 schema 草案 → coord 仲裁第一版 → 前端 AI 消费
|
||
- schema 变更需 PR + BFF AI + 前端 AI 双方 review
|
||
- 重大变更（删除字段 / 修改类型）需 coord 仲裁
|
||
|
||
**理由**：ai03 / ai04 / ai05 / ai13 / ai14 / ai15 均依赖 schema 仲裁，需统一机制。
|
||
|
||
**执行者**：coord（仲裁）+ 各 BFF AI（起草）+ 各前端 AI（消费）
|
||
**完成期限**：
|
||
|
||
- teacher-bff schema 第一版：批次 1 启动前
|
||
- student-bff schema 第一版：批次 2 启动前
|
||
- parent-bff schema 第一版：批次 3 启动前
|
||
|
||
### 2.3 BFF 跨阶段扩展例外验收标准（ISSUE-020）
|
||
|
||
**裁决**：明确"跨阶段扩展例外"的允许范围：
|
||
|
||
**允许扩展**：
|
||
|
||
1. 新增下游 gRPC 调用（新增 RPC 方法到 DownstreamClient）
|
||
2. 新增下游配置（gRPC endpoint 配置）
|
||
3. 新增 /readyz 探针（按阶段启用，见 §2.4）
|
||
4. Dashboard Query Resolver 内部数据源扩展（null 字段 → 真实数据）
|
||
5. AuthorizationGuard 内部实现替换（DEV_MODE 放行 → 真实 gRPC 校验）
|
||
|
||
**禁止变更**：
|
||
|
||
1. 修改已有 RPC 调用的签名或返回类型
|
||
2. 删除已实现的 RPC 调用（除非下游服务下线）
|
||
3. 修改 GraphQL schema 已有字段的类型（新增字段允许）
|
||
4. 修改 /readyz 已有探针的检查项（只能新增，不能修改）
|
||
|
||
**验收标准**：
|
||
|
||
1. 扩展时必须更新 BFF 的 02-architecture-design.md 下游调用矩阵
|
||
2. 扩展时必须更新 packages/shared-ts/contracts/graphql/ 下对应 schema 文件
|
||
3. 扩展时必须运行 `pnpm run arch:scan` 更新 arch.db
|
||
4. coord 在批次验收时检查上述 3 项
|
||
|
||
**理由**：ai03 / ai04 / ai05 跨阶段扩展时需统一标准。
|
||
|
||
**执行者**：各 BFF AI 执行，coord 验收
|
||
|
||
### 2.4 /readyz 探针按阶段扩展规则（ISSUE-023/034/042/055）
|
||
|
||
**裁决**：G2 裁决"首次实现即检查全部下游依赖"按以下规则执行：
|
||
|
||
1. **探针列表按阶段扩展**（属"跨阶段扩展例外"）：
|
||
- P2 teacher-bff /readyz：DB + Redis + iam gRPC 50052（3 项）
|
||
- P3 teacher-bff：+ core-edu gRPC 50053（4 项）
|
||
- P4 teacher-bff：+ content gRPC 50054 + data-ana gRPC 50055（6 项）
|
||
- P5 teacher-bff：+ ai gRPC 50058 + msg gRPC 50056（8 项）
|
||
|
||
2. **实现方式**：`DownstreamHealthCheck` 注册表模式，每个下游注册独立探针，按阶段启用
|
||
|
||
3. **可选依赖软失败规则**（针对 ISSUE-042/055）：
|
||
- **必需依赖**（DB / Redis / 已启用 gRPC 下游）：失败返回 503，触发 Pod 重启
|
||
- **可选依赖**（Kafka 消费 / PushGateway / 未启用 gRPC 下游）：失败仅告警，返回 200 + body `degraded: true`
|
||
- msg /readyz 对 PushGateway：软失败（ISSUE-042 采纳方案 A）
|
||
- push-gateway /readyz 对 Kafka：软失败（ISSUE-055）
|
||
|
||
4. **未引入依赖跳过**（ISSUE-023）：
|
||
- content P4 /readyz：检查 MySQL + Neo4j + Kafka（3 项，ES 未配置则跳过）
|
||
- content P5 /readyz：扩展 ES 检查（4 项，ES_URL 存在时才检查）
|
||
- 实现方式：检查项数组通过 ENV 过滤（`if (env.ES_URL) checks.push(checkES)`）
|
||
|
||
5. **分级检查**（ISSUE-029）：
|
||
- data-ana /readyz 对 iam gRPC：
|
||
- L1 ping iam 50052 端口可达（基础就绪，失败 ready=false）
|
||
- L2 调用 GetEffectiveDataScope 返回有效（深度就绪，失败 degraded=true）
|
||
|
||
**理由**：G2 原裁决"全部下游依赖"在 P2 不可行，需按阶段扩展 + 软失败策略。
|
||
|
||
**执行者**：各 AI 按规则实现
|
||
|
||
### 2.5 AttendanceService proto 责任方（ISSUE-022）
|
||
|
||
**裁决**：
|
||
|
||
1. **coord 负责 proto 契约定义**：core_edu.proto 补 AttendanceService + GetClassesByTeacher + BatchGetClasses 的 message + RPC 签名
|
||
2. **ai08 负责 proto 实现**：基于 coord 定义的 proto 生成 TS 代码 + 实现 AttendanceService 业务逻辑
|
||
3. **修正 coord-cross-review.md §6 #14**：责任方从 ai03 改为 coord（proto）+ ai08（实现）
|
||
4. **修正 004 §16.7.3**：保留 ai08 实现，但补注"proto 契约由 coord 定义"
|
||
|
||
**理由**：proto 契约是跨服务协作的接口，应由 coord 统一维护；业务实现由服务负责 AI 完成。
|
||
|
||
**执行者**：coord（proto）+ ai08（实现）
|
||
**完成期限**：proto 在批次 0.8 完成，实现 ai08 P3 完成
|
||
|
||
### 2.6 降级模式 ActionState 表达（ISSUE-030-ai11）
|
||
|
||
**裁决**：采纳方案 B（success=true + error=null + data 内 degraded 字段）：
|
||
|
||
```typescript
|
||
// 降级响应
|
||
{
|
||
success: true,
|
||
data: {
|
||
...actualData,
|
||
degraded: true, // 降级标记
|
||
degradedReason: "redis_unavailable" // 降级原因
|
||
},
|
||
error: null
|
||
}
|
||
```
|
||
|
||
**规则**：
|
||
|
||
1. 降级时 `success=true`，HTTP 200
|
||
2. `data` 内统一加 `degraded: boolean` + `degradedReason: string` 字段
|
||
3. BFF 消费端检查 `data.degraded` 判断降级
|
||
4. Python 服务（data-ana / ai）的 data 类型需统一加 degraded 字段
|
||
5. 修正 data-ana 02-architecture-design.md §4.3 ActionState.ok() 实现
|
||
|
||
**理由**：方案 B 最符合"成功返回数据但质量降级"的语义，避免"success=true 但 error 有值"的语义矛盾。
|
||
|
||
**执行者**：ai11（data-ana）+ ai12（ai）实现，coord 验收
|
||
|
||
### 2.7 BFF 错误码语义区分（ISSUE-059）
|
||
|
||
**裁决**：采纳 ai03 建议方案，明确 3 类 BFF 越权防御错误码：
|
||
|
||
| 错误码 | HTTP | 场景 | i18n key |
|
||
| -------------------------------- | ---- | ---------------------------------------------------- | ------------------------------------- |
|
||
| `BFF_TEACHER_UNAUTHORIZED` | 401 | x-user-id 缺失或无效 | `error.bffTeacher.unauthorized` |
|
||
| `BFF_TEACHER_FORBIDDEN_RESOURCE` | 403 | teacherId 与资源无归属关系（场景 A） | `error.bffTeacher.forbidden_resource` |
|
||
| `BFF_TEACHER_IDENTITY_MISMATCH` | 403 | JWT teacherId 与请求 body teacherId 不一致（场景 B） | `error.bffTeacher.identity_mismatch` |
|
||
|
||
**B3 裁决澄清**：BFF 豁免 @RequirePermission 指不做"功能权限决策"（如"能否查看仪表盘"），但必须做"数据权限防御"（如"只能看自己的班级"）。
|
||
|
||
**student-bff / parent-bff 同规则**：`BFF_STUDENT_*` / `BFF_PARENT_*` 前缀对应。
|
||
|
||
**执行者**：ai03 / ai04 / ai05 实现
|
||
|
||
### 2.8 Dashboard Query Resolver P2 实现方式（ISSUE-032）
|
||
|
||
**裁决**：采纳 ai03 建议方案：
|
||
|
||
1. **GraphQL schema 设计完整**（含全部 Query/Mutation 字段定义），P2 即定型，后续不重构
|
||
2. **Resolver 实现**：P2 阶段 Dashboard Query Resolver 内部仅调 iam gRPC（返回用户基础信息 + 角色），未启用的下游字段（班级数 / 作业数等）返回 `null` + `extensions.warning = "field_unavailable_in_p2"`
|
||
3. **P3-P5 扩展**：按"跨阶段扩展例外"原则，在 Resolver 内逐步补 gRPC 调用，将 null 字段替换为真实数据
|
||
4. **ai13 前端**：P2 联调时对 null 字段做 UI 降级展示（如"数据加载中"或隐藏模块）
|
||
5. **此方案不违反"不分阶段"**：schema 即最终方案，Resolver 内部数据源扩展属"跨阶段扩展例外"
|
||
|
||
**执行者**：ai03 实现 + ai13 前端配合
|
||
|
||
### 2.9 越权防御 P2 实现方式（ISSUE-033）
|
||
|
||
**裁决**：采纳 ai03 建议方案 D：
|
||
|
||
1. P2 抽象 `AuthorizationGuard` 接口（`canAccessClass(userId, classId): Promise<boolean>`）
|
||
2. P2 内部实现为"DEV_MODE 放行 + 生产拒绝"（保守策略）
|
||
3. **Redis 缓存**：P3 接入 core-edu gRPC 后，`GetClassesByTeacher` 结果缓存到 Redis（key: `authz:teacher:{teacherId}:classes`，TTL 5min），AuthorizationGuard 优先查缓存
|
||
4. **此方案不违反"不分阶段"**：Guard 接口即最终方案，P2→P3 仅替换内部实现（属"跨阶段扩展例外"）
|
||
|
||
**P2 阶段生产环境**：Guard 全部拒绝时，teacher-bff P2 端到端验证仅限 DEV_MODE。生产环境 P2 不接入流量（仅 dev 测试），P3 接入真实校验后正式上线。
|
||
|
||
**执行者**：ai03 实现
|
||
|
||
### 2.10 analytics.proto 补全时间（ISSUE-027）
|
||
|
||
**裁决**：
|
||
|
||
1. coord 在批次 0.11 完成 analytics.proto 扩展（4 端 Dashboard + Warning + MasteryDistribution + SubscribeMasteryUpdate Stream RPC）
|
||
2. ai11 在批次 3（P4）启动前确认 proto 已就绪
|
||
3. ai11 等待期间可先实现 HTTP 端点 + CDC 消费者 + ClickHouse DDL 等不依赖 proto 的工作
|
||
|
||
**执行者**：coord
|
||
**完成期限**：批次 0.11（批次 3 启动前）
|
||
|
||
### 2.11 warning.triggered topic 处理（ISSUE-028-ai11）
|
||
|
||
**裁决**：采纳方案 B（复用 topic）：
|
||
|
||
1. 维持现状，`warning.triggered` 复用 `edu.insight.mastery.updated` topic
|
||
2. events.proto MasteryEvent 用 `action` 字段区分 `mastery.updated` / `warning.triggered`
|
||
3. consumer 按 action 字段路由
|
||
4. D5 描述修正为"复用 mastery.updated topic，非独立登记"
|
||
5. 004 §7.2 表格补充注释："warning.triggered 复用 edu.insight.mastery.updated topic，通过 action 字段区分"
|
||
|
||
**理由**：避免拆分为两个 message 增加复杂度，复用 topic + action 字段路由是 Kafka 常见模式。
|
||
|
||
**执行者**：coord 修订 004 §7.2 + D5 描述
|
||
|
||
### 2.12 ClickHouse DDL 归属（ISSUE-026）
|
||
|
||
**裁决**：
|
||
|
||
1. **ai11 提供 DDL 内容**（已在 02 文档 §3 设计完毕）
|
||
2. **coord 授权 ai11 在 `infra/clickhouse/ddl/` 下创建纯 DDL .sql 文件**（不涉及部署脚本）
|
||
3. **SRE AI 负责部署执行脚本**（如 `init-clickhouse.sh`）
|
||
4. **修正 project_rules §14.2 解释**：业务 AI 可创建纯 DDL 文件（不涉及部署脚本），SRE AI 负责部署执行
|
||
|
||
**理由**：DDL 内容是业务特定的（5 张宽表设计），由 ai11 提供最合适；部署脚本属 infra 范畴。
|
||
|
||
**执行者**：ai11（DDL）+ SRE AI（部署）
|
||
|
||
### 2.13 Neo4j 知识图谱派生数据裁决（ISSUE-025-ai09）
|
||
|
||
**裁决**：Neo4j 知识图谱属于"派生数据读模型"：
|
||
|
||
1. Neo4j 节点数据完全从 MySQL 的 knowledge_points / kp_prerequisites 表派生
|
||
2. Neo4j 是读模型（图查询优化），MySQL 是写模型（权威源）
|
||
3. 符合 CQRS 读写分离原则
|
||
4. **实现方式**：content 主领域事件走 Outbox → Kafka，Neo4j Sync Worker 作为 Kafka consumer 消费这些事件并同步图谱（无需独立 Outbox）
|
||
|
||
**理由**：采纳 ai09 建议方案，符合 004 §12.2 派生数据事件豁免 Outbox 模式。
|
||
|
||
**执行者**：ai09 实现
|
||
|
||
### 2.14 ES Projector 实现位置（ISSUE-024-ai09）
|
||
|
||
**裁决**：采纳方案 A（content 内部实现）：
|
||
|
||
1. ES Projector 在 content 服务内部实现（`shared/sync/es-sync.worker.ts`）
|
||
2. 与 Neo4j Sync Worker 同构（一对 Sync Worker 模式）
|
||
3. shared-ts 仅承载通用的 Outbox Publisher（Kafka producer 通用能力），特定 Projector 由各服务自实现
|
||
4. ES mapping 是 content 特有的（questions/knowledge_points 索引结构、ik_max_word 分词、dense_vector embedding），通用 Projector 难以抽象
|
||
|
||
**执行者**：ai09 实现（P5 阶段）
|
||
|
||
### 2.15 API 版本化 /iam/v1/* 规则（ISSUE-048）
|
||
|
||
**裁决**：
|
||
|
||
1. **全服务统一加 `/v1` 前缀**（不只是 iam），各服务按自身节奏推进（iam P2 / core-edu P3 / content P4 / msg P5）
|
||
2. **前缀位置**：Controller 内加 `v1` 前缀（NestJS `@Controller('v1/iam/auth')`）
|
||
3. **Gateway 透传**：Gateway 路由 `/iam/v1/*` → iam 服务 `/v1/iam/*`（Gateway 不改路径，直接透传）
|
||
4. **避免双 v1**：Controller 加 `/v1`，Gateway 转发路径不含 `/v1`（Gateway 仅做路径匹配 + 代理）
|
||
5. **现有端点立即迁移**：不保留旧路径（遵循"不分阶段"原则，P1 链路由 ai01 + ai06 同步修复）
|
||
6. **gateway 路由配置同步更新**（ai01 P2 工作项）
|
||
|
||
**理由**：采纳 ai06 建议方案，统一规则避免各 AI 自行理解。
|
||
|
||
**执行者**：各服务 AI 实现 + ai01 Gateway 配置
|
||
|
||
### 2.16 gRPC 与 REST 双入口策略（ISSUE-049）
|
||
|
||
**裁决**：
|
||
|
||
1. **双入口策略**：REST 供 gateway 透传 + 前端直连（admin-portal），gRPC 供 BFF 聚合调用
|
||
2. **NestJS 复用**：同一 Application Service 同时被 REST Controller + gRPC Controller 调用，业务逻辑不重复
|
||
3. **gateway 保持 HTTP 透传**：gateway 不改为 gRPC 客户端（降低 P2 工作量），gateway → iam REST 路径不变
|
||
4. **BFF gRPC 调 iam**：teacher-bff / student-bff / parent-bff 用 gRPC 调 iam（B2 裁决）
|
||
5. **写入 coord-final-decisions.md I1 补充条款**
|
||
|
||
**理由**：采纳 ai06 建议方案，避免 gateway 改为 gRPC 客户端的额外工作量。
|
||
|
||
**执行者**：ai06 实现 + ai01 Gateway
|
||
|
||
### 2.17 MF AppShell GraphQL client 单例（ISSUE-038/047）
|
||
|
||
**裁决**：采纳方案 A（Shell 暴露 GraphQL client 单例）：
|
||
|
||
1. **Shell 暴露 GraphQLProvider**：ai13 P2 teacher-portal MF shell 的 AppShell 包含 `<GraphQLProvider client={sharedClient}>`
|
||
2. **统一缓存**：避免跨 Remote 数据不一致
|
||
3. **统一鉴权 header 注入**：Authorization: Bearer token
|
||
4. **统一错误处理**：401 跳转登录、5xx 降级
|
||
5. **MF shared 配置**：react / urql / apollo 设为 singleton，避免多实例
|
||
6. **admin-portal 复用**（ISSUE-047）：ai16 admin-portal 作为 MF Remote 接入 teacher-portal Shell，复用 Shell 暴露的 GraphQL client 单例
|
||
7. **ai16 回写 02 文档 §4.1**：将"复用 ApiClient (REST)"改为"复用 Shell 暴露的 GraphQL client 单例"
|
||
8. **coord 在批次 1 启动前仲裁 MF shell 暴露清单**（增加 GraphQL client 项）
|
||
|
||
**理由**：统一缓存 + 鉴权 + 错误处理，避免各 Remote 自行初始化导致数据不一致。
|
||
|
||
**执行者**：ai13 实现 + ai14/ai15/ai16 消费
|
||
|
||
### 2.18 ai13 packages 建立时机（ISSUE-039）
|
||
|
||
**裁决**：
|
||
|
||
1. **ai13 在 P2 启动前（批次 0 末或批次 1 初）建立 3 个 packages 骨架**：
|
||
- `packages/ui-tokens`（设计令牌，无依赖）
|
||
- `packages/ui-components`（依赖 ui-tokens）
|
||
- `packages/hooks`（依赖 ui-components）
|
||
2. **4 个 portal 统一消费**，版本通过 pnpm workspace 协议（`"workspace:*"`）
|
||
3. **ai13 完成后通知 ai14/ai15/ai16** 消费
|
||
4. **coord 在批次 1 验收 ai13 时检查 packages 已建立**
|
||
5. **批次 0 增加 0.15 任务**："ai13 建立 packages/ui-tokens + ui-components + hooks 骨架"
|
||
|
||
**执行者**：ai13
|
||
**完成期限**：批次 0.15（批次 1 启动前）
|
||
|
||
### 2.19 shared-go 包建立（ISSUE-054）
|
||
|
||
**裁决**：
|
||
|
||
1. **coord 在批次 0 增加 0.14 任务**："建立 `packages/shared-go` 包骨架（含 tracer/logger/jwks/env 4 个模块的接口定义 + 默认实现）"
|
||
2. **ai01 / ai02 在 P2/P5 启动时直接 import `packages/shared-go`**，禁止各自维护副本
|
||
3. **shared-go 包版本管理**：通过 go.workspace 引用，对齐 project_rules §11
|
||
4. **后续提取候选**：circuit-breaker.go / rate-limiter.go（若 ai01 P2 实现后 ai02 P5 复用）
|
||
|
||
**执行者**：coord
|
||
**完成期限**：批次 0.14（批次 1 启动前）
|
||
|
||
---
|
||
|
||
## 3. P2 各批次启动前完成：文档回写与工作量分级
|
||
|
||
### 3.1 ai03 P2 工作量分级（ISSUE-036）
|
||
|
||
**裁决**：采纳 ai03 建议方案，明确 P2 最小交付范围：
|
||
|
||
**Must Have（P2 必须完成）**：
|
||
|
||
1. GraphQL endpoint + schema 第一版（阻塞 ai13）
|
||
2. DownstreamClient 抽象 + iam gRPC（阻塞 ai04/ai05）
|
||
3. AuthMiddleware 越权防御抽象（B4 + ISSUE-033）
|
||
4. /readyz 探针注册表 + iam 探针（G2 + ISSUE-034）
|
||
5. /healthz liveness（G3）
|
||
6. pino 结构化日志（G4）
|
||
7. GlobalErrorFilter + ActionState 信封（G8）
|
||
8. BFF_TEACHER_ 错误码前缀（B5 + G14 + ISSUE-059）
|
||
9. 回写 02 文档（§7.2 + ISSUE-035）
|
||
10. ESM import .js 后缀（G12）
|
||
11. import type（G13）
|
||
12. getDb() 统一（G10）
|
||
13. cuid2 ID（G11）
|
||
|
||
**Should Have（P2 末期或 P3 初期补）**：14. OTel tracer（G6，P2 可降级为 logger-only）15. /metrics 业务指标（G5，P2 仅暴露 process metrics）16. DataLoader 集成（B1，P2 可先用普通 resolver）17. Redis 5-30s 短缓存（B6）
|
||
|
||
**Nice to Have（P3 持续补）**：18. Zod 全量验证（G7，P2 先校验核心 Query）19. 优雅关闭 SIGTERM（G9，P2 可简化为 HTTP close）
|
||
|
||
**理由**：批次 1 时间线 5-7 天内完成 19 项工作风险高，按 Must/Should/Nice 分级保证关键路径。
|
||
|
||
**执行者**：ai03
|
||
**完成期限**：Must Have 在批次 1 完成，Should Have 在 P3 初期补，Nice to Have 在 P3 持续补
|
||
|
||
### 3.2 ai06 iam P2 工作量分级（ISSUE-052）
|
||
|
||
**裁决**：采纳方案 A（拆分 P2 为 P2.1 核心 + P2.2 扩展）：
|
||
|
||
**P2.1（批次 1，5-7 天，阻塞批次 2）**：
|
||
|
||
1. gRPC server 50052 + 8 RPC 实现（GetViewports / GetEffectivePermissions / GetEffectiveAccess / Logout / GetPublicKey / BatchGetUsers / GetEffectiveDataScope / GetChildrenByParent）
|
||
2. AuthMiddleware 注册 + Controller 改用 @Req() 注入（I4 裁决）
|
||
3. JWT RS256 本地文件 + refresh token 轮换（I5 裁决）
|
||
4. iam_student_guardians 表 + GetChildrenByParent RPC + GET /iam/children REST（I6 裁决）
|
||
5. shared-ts Outbox 接入（I2 裁决）
|
||
6. /iam/v1/* 前缀迁移（I7 裁决）+ 端点路径统一（I8 裁决）
|
||
7. DB 驱动 PermissionGuard 基础（I3 裁决，废弃硬编码 ROLE_PERMISSIONS map）
|
||
8. 回写 02 文档（ISSUE-051）
|
||
|
||
**P2.2（P3 期间持续补，不阻塞批次 2/3）**：9. 三层角色模型（school_admin / teacher / student + 自定义角色）10. DataScope 6 级实现（ALL / SCHOOL / GRADE / CLASS / SUBJECT / SELF）11. 视口 4 层（admin / teacher / student / parent）+ getEffectivePermissions 12. 审计日志（user_audit_log 表 + 记录关键操作）13. 密码策略（强度 / 过期 / 重用限制）14. 单元测试 + 集成测试 15. Redis 缓存（I3 裁决完整实现）
|
||
|
||
**批次 2 启动条件**：仅依赖 P2.1 完成（gRPC 50052 + 8 RPC + GetChildrenByParent 已就绪），不依赖 P2.2。
|
||
|
||
**理由**：iam 实际工作量 26-27 天，批次 1 时间线 5-7 天严重不匹配。拆分 P2.1 / P2.2 保证关键路径不阻塞。
|
||
|
||
**执行者**：ai06
|
||
**完成期限**：P2.1 在批次 1 完成，P2.2 在 P3 期间持续补
|
||
|
||
### 3.3 ai10 P5 工作量分级（关联 ISSUE-052）
|
||
|
||
**裁决**：ai10 msg P5 实际工作量 14-15 天，批次 4 预估 7-10 天差距约 50%。采纳分级交付：
|
||
|
||
**P5 Must Have（批次 4，10-12 天）**：
|
||
|
||
1. proto 生成代码 + gRPC server 50056 框架搭建
|
||
2. DB schema 建立（6 表扩展/新增）+ ES mapping + Redis bitmap schema
|
||
3. 6 层架构骨架（Entry/Guard/App/Strategy/Domain/Data）+ getDb() + cuid2
|
||
4. 8 gRPC RPC 实现 + 16 REST 端点实现
|
||
5. 7 Kafka 消费方实现 + 3 发布事件 Outbox
|
||
6. 4 ChannelStrategy 基础实现（InApp/Email/SMS/Push）
|
||
7. /readyz + /healthz + /metrics + 优雅关闭 + OTel
|
||
|
||
**P5 Should Have（批次 4 末期或 P6 初期补）**：8. 模板渲染完整实现 9. 静默时段 10. DLQ 完整实现 11. 三层幂等完整实现 12. 集成测试 + 端到端验证（含 push-gateway 联调）
|
||
|
||
**理由**：与 ai06 iam P2 同类问题，分级交付保证关键路径。
|
||
|
||
**执行者**：ai10
|
||
**完成期限**：Must Have 在批次 4 完成，Should Have 在 P6 初期补
|
||
|
||
### 3.4 各 AI 文档回写义务（ISSUE-028/032-ai15/034-ai15/036-ai13/051-ai06/053-ai02/063-ai14）
|
||
|
||
**裁决**：各 AI 在 coord 仲裁后 3 个工作日内（或对应批次启动前）完成回写：
|
||
|
||
| AI | 文档 | 回写内容 | 完成期限 |
|
||
| ---- | ----------------- | ---------------------------------------------------------------------------------- | ------------- |
|
||
| ai03 | teacher-bff 02 | 4 处 GetTeacherDashboardStats → GetTeacherDashboard（ISSUE-035） | 批次 1 启动前 |
|
||
| ai04 | student-bff 02 | B1 GraphQL + B2 gRPC + B8 DownstreamClient 回写（ISSUE-028） | 批次 2 启动前 |
|
||
| ai05 | parent-bff 02 | B1 GraphQL + B2 gRPC 回写 | 批次 3 启动前 |
|
||
| ai06 | iam 02 | I1-I8 裁决对齐 4 处 + §9 标注前移（ISSUE-051） | 批次 1 启动前 |
|
||
| ai09 | content 02 | 移除已裁决项 + ES 启用时机标注 | 批次 3 启动前 |
|
||
| ai10 | msg 02 | M2 软失败 + ISSUE-043 验证 + ISSUE-012 契约更新 | 批次 4 启动前 |
|
||
| ai02 | push-gateway 02 | ISSUE-053 topic + ISSUE-055 /readyz + ISSUE-056 设计决策记录 + ISSUE-058 Redis SET | 批次 4 启动前 |
|
||
| ai13 | teacher-portal 03 | 删除 §6 REST→GraphQL 演进策略（ISSUE-036） | 批次 1 启动前 |
|
||
| ai14 | student-portal 02 | F9 GraphQL + F7 权限点命名回写（ISSUE-063/064） | 批次 2 启动前 |
|
||
| ai15 | parent-portal 02 | F9 GraphQL + 删除"P4 用 REST 后续切 GraphQL"（ISSUE-032/034） | 批次 3 启动前 |
|
||
| ai16 | admin-portal 02 | ISSUE-044~048 仲裁结果回写 | 批次 5 启动前 |
|
||
|
||
**回写验收**：
|
||
|
||
1. 回写完成后在 known-issues.md 工作经验日志追加记录
|
||
2. coord 在批次验收时检查 02 文档与裁决一致性
|
||
3. 不回写视为违反 coord-final-decisions §0.1 回写义务，coord 验收不通过
|
||
|
||
**执行者**：各 AI
|
||
|
||
### 3.5 ai03 P2 功能范围（关联 ISSUE-040）
|
||
|
||
**裁决**：明确 ai13 teacher-portal P2 功能范围：
|
||
|
||
**P2 实现**（依赖 iam + teacher-bff GraphQL schema）：
|
||
|
||
- 登录 + 权限上下文
|
||
- Dashboard 框架（null 字段降级展示）
|
||
- 个人设置
|
||
- 班级列表（iam 数据）
|
||
- 学生列表（iam 数据）
|
||
|
||
**P3 扩展**（跟随 teacher-bff 调 core-edu）：
|
||
|
||
- 课表 / 考勤 / 考试 / 作业
|
||
|
||
**P4 扩展**（跟随 teacher-bff 调 content/data-ana）：
|
||
|
||
- 教材 / 题库 / 分析仪表盘
|
||
|
||
**P5 扩展**（跟随 teacher-bff 调 ai/msg）：
|
||
|
||
- AI 助教 / 消息通知
|
||
|
||
**规则**：前端路由骨架 P2 一次性建立，但页面内容随 BFF 能力分阶段填充（属"跨阶段扩展例外"）。
|
||
|
||
**执行者**：ai13
|
||
|
||
### 3.6 ai14 student-portal P3 功能范围（ISSUE-065）
|
||
|
||
**裁决**：明确 ai14 student-portal P3 功能范围：
|
||
|
||
**P3 实现**（7 页，依赖 iam + core-edu）：
|
||
|
||
- dashboard / homework / exams / take / result / grades / my-schedule
|
||
|
||
**P4 扩展**（4 页，依赖 content + data-ana）：
|
||
|
||
- textbooks / questions / diagnostic / weakness
|
||
|
||
**P5 扩展**（2 页，依赖 msg + ai）：
|
||
|
||
- notifications / ai-chat
|
||
|
||
**P4/P5 页面**：设 `<FeatureFlag>` 占位（显示"功能开发中"提示页），避免用户访问 404。
|
||
|
||
**coord 验收 ai14 P3 时检查**：P3 范围 7 页全部可用 + P4/P5 页面有占位。
|
||
|
||
**执行者**：ai14
|
||
|
||
### 3.7 BFF 通知功能阶段归属（ISSUE-013/033/066）
|
||
|
||
**裁决**：BFF 通知功能统一推迟到 P5：
|
||
|
||
1. **P2-P4 阶段**：BFF 不订阅 Kafka（B7 裁决），通知功能不实现
|
||
2. **P5 阶段**：msg + push-gateway 就绪后，BFF 订阅 Kafka + 前端接入 push-gateway WebSocket/SSE
|
||
3. **parent-portal 通知偏好**（ISSUE-033）：
|
||
- P4 阶段：通知偏好设置页面 UI + 表单校验，偏好暂存前端 localStorage（降级方案），不调后端 API
|
||
- P5 阶段：parent-bff 接入 msg 服务 GraphQL mutation `updateNotificationPreferences`，偏好持久化到 msg DB
|
||
4. **student-portal 通知中心**（ISSUE-066）：
|
||
- P3-P4：notifications route 设 `<FeatureFlag>` 占位
|
||
- P5：实现通知中心页面 + WebSocket/SSE 接入 push-gateway
|
||
5. **P3-P4 降级方案**：学生端可提供"手动刷新"（轮询 core-edu 查询最近作业/考试），但不作为正式通知功能
|
||
|
||
**理由**：B7 裁决 P2-P4 BFF 不订阅 Kafka 简化实现，通知功能推迟到 P5 统一启用。
|
||
|
||
**执行者**：ai03/ai04/ai05（BFF）+ ai13/ai14/ai15（前端）
|
||
|
||
---
|
||
|
||
## 4. P2 各批次启动前完成：服务依赖与时序
|
||
|
||
### 4.1 批次 0 完成信号机制（ISSUE-047）
|
||
|
||
**裁决**：
|
||
|
||
1. **coord 在 ai-work-orchestration.md §3.1 标注每项任务完成状态**（✅ 已完成 / ⏳ 待办 / 🔄 进行中）
|
||
2. **批次 0 全部 15 项任务完成后，coord 发布批次 1 启动公告**（在 ai-work-orchestration.md §9 时间线末尾追加"批次 0 已完成，批次 1 启动"）
|
||
3. **建立"前置依赖就绪检查清单"**，coord 在批次 1/2/3/4/5 启动前逐项确认
|
||
4. **批次 0 任务清单**（最终 15 项）：
|
||
- 0.1 arch:scan 更新
|
||
- 0.2 修订 coord-cross-review.md
|
||
- 0.3 补全 iam.proto 8 RPC
|
||
- 0.4 建立 shared-ts Outbox 工具包（含设计草案 + 实现）
|
||
- 0.5 补全 content.proto（QuestionService 等）
|
||
- 0.6 补全 msg.proto
|
||
- 0.7 补全 analytics.proto 扩展
|
||
- 0.8 补全 core_edu.proto（AttendanceService / GetClassesByTeacher / BatchGetClasses）
|
||
- 0.9 buf.gen.yaml 补 gRPC 插件
|
||
- 0.10 补全 events.proto（7 message 已完成）
|
||
- 0.11 analytics.proto 扩展（4 端 Dashboard + Warning + MasteryDistribution + SubscribeMasteryUpdate）
|
||
- 0.12 补全 push-gateway 相关 proto（如有）
|
||
- 0.13 补全 msg.proto（5 RPC + NotificationPreferenceService + NotificationTemplateService + 3 message）
|
||
- 0.14 建立 shared-go 包骨架（tracer/logger/jwks/env 4 模块）
|
||
- 0.15 ai13 建立 packages/ui-tokens + ui-components + hooks 骨架
|
||
|
||
**执行者**：coord（0.1-0.14）+ ai13（0.15）
|
||
**完成期限**：批次 0 全部完成后再启动批次 1
|
||
|
||
### 4.2 /internal/push 契约采纳（ISSUE-057/012）
|
||
|
||
**裁决**：
|
||
|
||
1. **coord 直接采纳 ai02 02 §4.2 作为第一版 /internal/push 契约**（"as-is"采纳）
|
||
2. **仅在 ai10 提出异议时**（如 msg 调用方需要 batch 接口 / 异步回调机制），coord 才调整契约
|
||
3. **coord 在批次 4 启动前公布"采纳 ai02 02 §4.2 作为第一版契约"的决定**，避免重复仲裁
|
||
4. **若 coord 决定调整**，必须给出具体差异点（如新增字段、修改响应格式），ai02/ai10 按差异点调整
|
||
|
||
**执行者**：coord
|
||
**完成期限**：批次 4 启动前
|
||
|
||
### 4.3 Redis SET 心跳重建机制（ISSUE-058）
|
||
|
||
**裁决**：采纳 ai02 建议方案：
|
||
|
||
1. **ai02 02 §3.1 补充"Hub 启动时重建 Redis SET"机制**：
|
||
- Hub 启动时遍历内存连接（userID），SADD 自己 instanceID 到 `edu:push:online:<userID>` + EXPIRE 60s
|
||
- 启动时清空 Redis 中本 instanceID 的旧成员（避免幽灵成员）
|
||
2. **/readyz Redis 检查失败时仅告警不阻塞**（与 ISSUE-055 协调），避免雪崩
|
||
3. **metrics 暴露 `push_gateway_redis_set_rebuild_total`** 监控重建次数
|
||
4. **文档化"Redis 故障恢复后 60s 内在线状态可能短暂不一致"**，msg 服务调用方需容忍 `online: false` 误判（msg 应继续尝试 HTTP /internal/push，由 push-gateway 返回真实在线状态）
|
||
|
||
**执行者**：ai02
|
||
**完成期限**：P5 启动前回写 02 文档
|
||
|
||
### 4.4 设计决策记录章节保留规则（ISSUE-056）
|
||
|
||
**裁决**：
|
||
|
||
1. **coord-final-decisions.md §7.2 回写义务表补充澄清**："设计决策记录章节（已被 coord 采纳的仲裁请求）保留，但正文需标注'coord 已采纳，见 coord-final-decisions P1/P5/P6'，标题改为'设计决策记录：xxx'"
|
||
2. **ai02 02 §5.4 改名**为"设计决策记录：gRPC vs HTTP 协议选型（coord 已采纳 P1）"
|
||
3. **ai02 02 §14.2 改名**为"设计决策记录：SSE/断线重连范围（coord 已采纳 P5/P6）"
|
||
4. **章节内容保留作为决策追溯依据**，但删除"中间过渡方案"字样
|
||
5. **其他 AI 的同类"过渡方案描述"**（如 ai13 ISSUE-036、ai15 ISSUE-034）按此原则处理：删除过渡方案本身，保留设计决策记录
|
||
|
||
**执行者**：coord（§7.2 补充）+ ai02（02 文档回写）+ 其他 AI 同规则
|
||
|
||
### 4.5 iam /readyz 检查深度（ISSUE-029-ai11）
|
||
|
||
**裁决**：采纳 ai11 建议方案：
|
||
|
||
1. **coord 验收 iam P2 时强制检查 GetEffectiveDataScope RPC 已落地**（不仅仅是 gRPC server 启用）
|
||
2. **data-ana /readyz 分两级检查**：
|
||
- L1 ping iam 50052 端口可达（基础就绪，失败 ready=false）
|
||
- L2 调用 GetEffectiveDataScope 返回有效（深度就绪，失败 degraded=true）
|
||
|
||
**执行者**：ai11 实现 + coord 验收
|
||
|
||
---
|
||
|
||
## 5. P2 各批次启动前完成：工作归属裁决
|
||
|
||
### 5.1 admin-portal BFF 归属（ISSUE-044）
|
||
|
||
**裁决**：采纳方案 2（复用 teacher-bff）：
|
||
|
||
1. **admin-portal 复用 teacher-bff 的 GraphQL endpoint**，不新建 admin-bff 服务
|
||
2. **ai03 P2 预留 admin schema 命名空间**（如 `admin.*` Query/Mutation）
|
||
3. **coord 在批次 1 启动前仲裁 schema 第一版时纳入 admin 命名空间**
|
||
4. **004 §1.2 服务清单保持不变**（无 admin-bff）
|
||
5. **ai16 回写 02 文档 §4.1**：数据获取路径改为"复用 teacher-bff GraphQL endpoint"
|
||
|
||
**理由**：admin 操作低 QPS，无需独立 BFF 实例；减少 ai16 工作量。
|
||
|
||
**执行者**：ai03（预留 admin 命名空间）+ ai16（回写 02 文档）
|
||
|
||
### 5.2 admin-portal 错误码前缀（ISSUE-045）
|
||
|
||
**裁决**：
|
||
|
||
1. **G14 清单补充 `ADMIN_` 前缀**（合并 SCHOOL_ 入 ADMIN_，因学校设置属 admin 业务子域）
|
||
2. **ORG 管理也归入 ADMIN\_ 前缀**（统一 admin 域）
|
||
3. **错误码命名**：`ADMIN_<RESOURCE>_<ERROR>`（如 `ADMIN_SCHOOL_NOT_FOUND`、`ADMIN_ORG_DUPLICATE_NAME`）
|
||
4. **i18n key**：`error.admin.*`（对齐 F4 规范）
|
||
5. **写入 coord-final-decisions.md G14 补充条款**
|
||
|
||
**执行者**：coord（G14 补充）+ ai16（实现）
|
||
|
||
### 5.3 admin-portal 权限点命名（ISSUE-046）
|
||
|
||
**裁决**：
|
||
|
||
1. **F7 允许服务前缀作为命名空间**（避免不同域同名资源冲突，如 `CONTENT_QUESTION_READ` vs `CORE_EDU_QUESTION_READ`）
|
||
2. **命名规则**：`[<SERVICE>_]<RESOURCE>_<ACTION>[_<SCOPE>]`，SERVICE 可选
|
||
3. **admin-portal 权限点统一加 `ADMIN_` 前缀**（与错误码前缀对齐）
|
||
4. **跨服务资源**（如调 iam 用户管理）保留 iam 前缀（`IAM_USER_READ`），admin 自身资源用 `ADMIN_` 前缀
|
||
5. **admin-portal 调下游服务的权限点校验由下游服务负责**（B3 裁决 BFF 豁免 @RequirePermission，admin-portal 作为 client 不做权限决策）
|
||
6. **写入 coord-final-decisions.md F7 补充条款**
|
||
|
||
**执行者**：coord（F7 补充）+ ai16（实现）
|
||
|
||
### 5.4 admin-portal GraphQL 客户端（ISSUE-047）
|
||
|
||
**裁决**：已在 §2.17 裁决，admin-portal 复用 Shell 暴露的 GraphQL client 单例。
|
||
|
||
**执行者**：ai13（Shell 暴露）+ ai16（消费）
|
||
|
||
### 5.5 admin-portal 审计日志归属（ISSUE-048）
|
||
|
||
**裁决**：X3 审计日志归属前置到 P6 启动前裁决：
|
||
|
||
1. **审计日志归 iam**（iam 已掌握用户/角色数据，审计事件天然属 iam 域）
|
||
2. **events.proto 补 `AuditEvent` message**：
|
||
|
||
```protobuf
|
||
message AuditEvent {
|
||
string event_id = 1;
|
||
string aggregate_id = 2;
|
||
string event_type = 3;
|
||
int64 occurred_at = 4;
|
||
string actor_user_id = 5;
|
||
string action = 6; // create / update / delete / login / logout
|
||
string resource_type = 7; // user / role / class / exam ...
|
||
string resource_id = 8;
|
||
string before_state = 9; // JSON string
|
||
string after_state = 10; // JSON string
|
||
string ip = 11;
|
||
string user_agent = 12;
|
||
string trace_id = 13;
|
||
map<string, string> metadata = 14;
|
||
}
|
||
```
|
||
|
||
3. **新增 topic `edu.iam.audit.created`**（统一审计事件 topic，不按操作类型分）
|
||
4. **admin-portal 作为 consumer 订阅 `edu.iam.audit.created`**，写入 ClickHouse 审计表（或 MySQL 审计表）
|
||
5. **admin-portal 8 个新 Kafka topic 重新评估**：若审计归 iam，admin-portal 仅需 1 个 audit consumer topic，无需 8 个
|
||
6. **iam P2.2 扩展阶段补 AuditEvent 发布**（user_audit_log 表 + 事件发布）
|
||
7. **events.proto 补 AuditEvent 在批次 0.10 完成**
|
||
|
||
**执行者**：coord（proto + topic）+ ai06（iam 发布）+ ai16（admin-portal 消费）
|
||
|
||
---
|
||
|
||
## 6. 时间统筹总表（批次时间线最终调整）
|
||
|
||
### 6.1 批次时间线（最终版）
|
||
|
||
基于工作量分级裁决（§3.1-3.3），批次时间线最终调整如下：
|
||
|
||
| 批次 | 阶段 | AI 并行 | 时间线 | 关键交付 | 启动条件 |
|
||
| ---------- | ---------- | ---------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
|
||
| **批次 0** | coord 前置 | coord（0.1-0.14）+ ai13（0.15） | 3-5 天 | proto 契约 + shared-ts Outbox + shared-go + packages 骨架 | 本裁决发布后立即 |
|
||
| **批次 1** | P2 | ai01 + ai06 + ai03⟷ai13 | 7-10 天 | iam P2.1 + teacher-bff Must Have + teacher-portal P2 + Gateway 路由 | 批次 0 全部完成 |
|
||
| **批次 2** | P3 | ai08 + ai07 交接 + ai04⟷ai14 + ai03 扩展 | 7-10 天 | core-edu gRPC 50053 + student-bff + student-portal P3（7 页）+ teacher-bff P3 扩展 | 批次 1 P2.1 完成 + ai03 DownstreamClient 抽象就绪 |
|
||
| **批次 3** | P4 | ai09 + ai11 + ai05⟷ai15 + ai03/ai04 扩展 | 10-12 天 | content gRPC 50054 + data-ana gRPC 50055 + parent-bff + parent-portal P4 + teacher/student-bff P4 扩展 | 批次 2 完成 |
|
||
| **批次 4** | P5 | ai10⟷ai02 + ai12 + ai03 扩展 | 12-15 天 | msg gRPC 50056 + push-gateway + ai 服务 + teacher-bff P5 扩展 + 通知功能启用 | 批次 3 完成 |
|
||
| **批次 5** | P6 | ai16 + 持续优化 | 10-12 天 | admin-portal + 审计日志 + iam P2.2 补全 + 持续优化 | 批次 4 完成 |
|
||
|
||
**总时间线**：49-64 天（约 10-13 周）
|
||
|
||
### 6.2 批次 0 详细任务清单
|
||
|
||
| 任务 | 责任方 | 内容 | 完成信号 |
|
||
| ---- | ------ | ---------------------------------------------------------------------------------------------------------- | ------------------------------------- |
|
||
| 0.1 | coord | arch:scan 更新 | arch.db 已更新 |
|
||
| 0.2 | coord | 修订 coord-cross-review.md | 文档已更新 |
|
||
| 0.3 | coord | 补全 iam.proto 8 RPC | proto 文件已提交 |
|
||
| 0.4 | coord | 建立 shared-ts Outbox 工具包（含设计草案 + 实现） | packages/shared-ts/src/outbox/ 已建立 |
|
||
| 0.5 | coord | 补全 content.proto（QuestionService 等） | proto 文件已提交 |
|
||
| 0.6 | coord | 补全 msg.proto 基础 | proto 文件已提交 |
|
||
| 0.7 | coord | 补全 analytics.proto 基础 | proto 文件已提交 |
|
||
| 0.8 | coord | 补全 core_edu.proto（AttendanceService / GetClassesByTeacher / BatchGetClasses） | proto 文件已提交 |
|
||
| 0.9 | coord | buf.gen.yaml 补 gRPC 插件 | buf generate 可运行 |
|
||
| 0.10 | coord | 补全 events.proto（含 AuditEvent） | proto 文件已提交 |
|
||
| 0.11 | coord | analytics.proto 扩展（4 端 Dashboard + Warning + MasteryDistribution + SubscribeMasteryUpdate Stream RPC） | proto 文件已提交 |
|
||
| 0.12 | coord | 补全 push-gateway 相关 proto（如有） | proto 文件已提交 |
|
||
| 0.13 | coord | 补全 msg.proto（5 RPC + NotificationPreferenceService + NotificationTemplateService + 3 message） | proto 文件已提交 |
|
||
| 0.14 | coord | 建立 shared-go 包骨架（tracer/logger/jwks/env 4 模块） | packages/shared-go/ 已建立 |
|
||
| 0.15 | ai13 | 建立 packages/ui-tokens + ui-components + hooks 骨架 | 3 个 packages 已建立 |
|
||
|
||
### 6.3 批次 1 详细任务清单（P2）
|
||
|
||
| AI | 任务 | 时间线 | 关键交付 |
|
||
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | --------------------------------------------------------- |
|
||
| ai01 | Gateway 路由配置（/iam/v1/* + /teacher/* + /parent/* 前缀） | 3-5 天 | Gateway 路由就绪 |
|
||
| ai06 | iam P2.1（gRPC + 8 RPC + AuthMiddleware + JWT RS256 + iam_student_guardians + shared-ts Outbox + /iam/v1/* 前缀 + DB 驱动 PermissionGuard 基础） | 7-10 天 | iam gRPC 50052 + 8 RPC 就绪 |
|
||
| ai03 | teacher-bff P2 Must Have（GraphQL + DownstreamClient + AuthMiddleware + /readyz + /healthz + pino + GlobalErrorFilter + 错误码 + ESM + cuid2） | 7-10 天 | teacher-bff GraphQL schema 第一版 + DownstreamClient 抽象 |
|
||
| ai13 | teacher-portal P2（client 改造 + MF shell + 共享组件抽取 + GraphQL Provider + packages 完善） | 7-10 天 | teacher-portal P2 可联调 |
|
||
|
||
**批次 1 启动前 coord 仲裁**：
|
||
|
||
- teacher-bff GraphQL schema 第一版（含 admin 命名空间）
|
||
- MF shell 暴露清单（含 GraphQL client 单例）
|
||
- /internal/push 契约（如批次 4 提前需要，可延后）
|
||
|
||
### 6.4 批次 2-5 启动前 coord 仲裁
|
||
|
||
| 批次 | 仲裁内容 | 完成期限 |
|
||
| ------ | ------------------------------------------------ | ------------- |
|
||
| 批次 2 | student-bff GraphQL schema 第一版 | 批次 2 启动前 |
|
||
| 批次 3 | parent-bff GraphQL schema 第一版 | 批次 3 启动前 |
|
||
| 批次 4 | /internal/push 契约（采纳 ai02 02 §4.2） | 批次 4 启动前 |
|
||
| 批次 5 | admin-portal schema 命名空间（复用 teacher-bff） | 批次 5 启动前 |
|
||
|
||
---
|
||
|
||
## 7. 各 AI 工作内容最终清单
|
||
|
||
### 7.1 ai01（api-gateway）
|
||
|
||
- **批次 1（P2）**：Gateway 路由配置（/iam/v1/* + /teacher/* + /parent/* 前缀）+ 接入 shared-go 包
|
||
- **批次 2-5**：路由扩展（core-edu / content / data-ana / msg / ai 路由）+ 持续优化
|
||
|
||
### 7.2 ai02（push-gateway）
|
||
|
||
- **批次 0 等待期**：复审 02 文档 + 回写 ISSUE-053/055/056/058
|
||
- **批次 4（P5）**：/internal/push + WebSocket + Redis Pub/Sub + Kafka 消费（可选）+ /readyz + /metrics + OTel + 多阶段 Dockerfile + slog + X-Internal-Token 重命名 + 集成测试
|
||
|
||
### 7.3 ai03（teacher-bff）
|
||
|
||
- **批次 1（P2）**：Must Have 13 项（见 §3.1）+ DownstreamClient 抽象 + admin schema 命名空间预留
|
||
- **批次 2-5**：跨阶段扩展（core-edu / content / data-ana / msg / ai gRPC 调用）+ Should Have + Nice to Have 持续补
|
||
|
||
### 7.4 ai04（student-bff）
|
||
|
||
- **批次 0/1 等待期**：回写 02 文档（B1/B2/B8）+ 起草 student-bff GraphQL schema 草案
|
||
- **批次 2（P3）**：student-bff P3（GraphQL + DownstreamClient 复用 + iam + core-edu gRPC）
|
||
- **批次 3-4**：跨阶段扩展（content / data-ana gRPC）
|
||
- **批次 4**：跨阶段扩展（msg / ai gRPC）+ 通知功能启用
|
||
|
||
### 7.5 ai05（parent-bff）
|
||
|
||
- **批次 0-2 等待期**：回写 02 文档 + 起草 parent-bff GraphQL schema 草案
|
||
- **批次 3（P4）**：parent-bff P4（GraphQL + DownstreamClient 复用 + iam + core-edu gRPC）
|
||
- **批次 4**：跨阶段扩展（data-ana gRPC）+ 通知功能启用
|
||
|
||
### 7.6 ai06（iam）
|
||
|
||
- **批次 0 等待期**：回写 02 文档（I1-I8）+ 监控批次 0.3/0.4 完成
|
||
- **批次 1（P2.1）**：gRPC + 8 RPC + AuthMiddleware + JWT RS256 + iam_student_guardians + shared-ts Outbox + /iam/v1/* 前缀 + DB 驱动 PermissionGuard 基础
|
||
- **批次 2-5（P2.2 持续补）**：三层角色 + DataScope + 视口 + 审计日志 + 密码策略 + 测试
|
||
|
||
### 7.7 ai07（classes 交接）
|
||
|
||
- **批次 0**：classes 黄金模板代码交接给 ai08
|
||
- **后续**：无（ai07 已完成黄金模板工作）
|
||
|
||
### 7.8 ai08（core-edu）
|
||
|
||
- **批次 0 等待期**：复审 02 文档 + 监控批次 0.8 完成
|
||
- **批次 2（P3）**：core-edu gRPC 50053 + AttendanceService 实现 + classes 代码交接 + Outbox + TOPIC_MAP 修订（edu.teaching.*）
|
||
- **批次 3-5**：跨阶段扩展（如需）
|
||
|
||
### 7.9 ai09（content）
|
||
|
||
- **批次 0-2 等待期**：复审 02 文档 + 移除已裁决项
|
||
- **批次 3（P4）**：content gRPC 50054 + QuestionService 完整实现 + Outbox + Neo4j Sync Worker + /readyz（MySQL + Neo4j + Kafka）
|
||
- **批次 4（P5）**：ES Projector 实现 + /readyz 扩展 ES 检查
|
||
|
||
### 7.10 ai10（msg）
|
||
|
||
- **批次 0-3 等待期**：复审 02 文档 + 回写 ISSUE-042/043
|
||
- **批次 4（P5）**：msg gRPC 50056 + Must Have（gRPC + REST + Outbox + 基础 channel）+ Should Have（模板 + 静默 + DLQ + 完整幂等）
|
||
- **批次 5**：Should Have 补全 + 集成测试
|
||
|
||
### 7.11 ai11（data-ana）
|
||
|
||
- **批次 0-2 等待期**：复审 02 文档 + ClickHouse DDL 文件创建
|
||
- **批次 3（P4）**：data-ana gRPC 50055 + CDC 消费者 + ClickHouse 宽表 + /readyz（分两级检查 iam gRPC）
|
||
- **批次 4-5**：跨阶段扩展（如需）
|
||
|
||
### 7.12 ai12（ai）
|
||
|
||
- **批次 0-3 等待期**：复审 02 文档
|
||
- **批次 4（P5）**：ai 服务（ES 检索 + AI 备课 + 出题 + StreamChat）+ 接入 content/data-ana gRPC
|
||
|
||
### 7.13 ai13（teacher-portal）
|
||
|
||
- **批次 0（0.15）**：建立 packages/ui-tokens + ui-components + hooks 骨架
|
||
- **批次 1（P2）**：teacher-portal P2（client 改造 + MF shell + GraphQL Provider + 共享组件抽取）+ 03 文档回写
|
||
- **批次 2-5**：跟随 teacher-bff 扩展页面
|
||
|
||
### 7.14 ai14（student-portal）
|
||
|
||
- **批次 0/1 等待期**：回写 02 文档（F9 GraphQL + F7 权限点命名）+ 起草 client query 清单
|
||
- **批次 2（P3）**：student-portal P3（7 页：dashboard/homework/exams/take/result/grades/my-schedule）
|
||
- **批次 3**：P4 扩展（4 页：textbooks/questions/diagnostic/weakness）
|
||
- **批次 4**：P5 扩展（2 页：notifications/ai-chat）
|
||
|
||
### 7.15 ai15（parent-portal）
|
||
|
||
- **批次 0-2 等待期**：回写 02 文档（F9 GraphQL + 删除"P4 用 REST 后续切 GraphQL"）+ 起草 client query 清单
|
||
- **批次 3（P4）**：parent-portal P4（Dashboard + 孩子列表 + 考试/作业/成绩 + 通知偏好 UI 占位）
|
||
- **批次 4**：P5 扩展（通知偏好持久化 + 通知中心）
|
||
|
||
### 7.16 ai16（admin-portal）
|
||
|
||
- **批次 0-4 等待期**：回写 02 文档（ISSUE-044~048 仲裁结果）
|
||
- **批次 5（P6）**：admin-portal（用户/角色管理 + 学校设置 + 组织管理 + 审计日志消费）+ 复用 teacher-bff GraphQL endpoint
|
||
|
||
---
|
||
|
||
## 8. 总裁裁决执行检查清单
|
||
|
||
### 8.1 P0 立即执行（coord）
|
||
|
||
- [ ] 修正 port-allocation.md §5 iam 行（§1.1）
|
||
- [ ] 修正 004 §4.2 gRPC 启用矩阵（§1.2）
|
||
- [ ] 修正 004 §16.7.4 P4 清单补 QuestionService（§1.3）
|
||
- [ ] 修正 004 §16.7.5 P5 清单删 QuestionService（§1.4）
|
||
- [ ] 修订 004 §7.2 Kafka topic 表格（§1.5）
|
||
- [ ] 修正 coord-final-decisions.md + ai-work-orchestration.md 相对路径（§1.6）
|
||
- [ ] 在 issues.md §0.5 添加总裁裁决索引指针（§1.7）
|
||
|
||
### 8.2 P1 批次 0 启动前完成（coord + ai13）
|
||
|
||
- [ ] coord 完成 shared-ts Outbox 工具包设计 + 实现（§2.1，0.4）
|
||
- [ ] coord 建立 GraphQL schema 仲裁规范（§2.2）
|
||
- [ ] coord 补全 core_edu.proto AttendanceService（§2.5，0.8）
|
||
- [ ] coord 补全 analytics.proto 扩展（§2.10，0.11）
|
||
- [ ] coord 补全 events.proto AuditEvent（§5.5，0.10）
|
||
- [ ] coord 建立 shared-go 包骨架（§2.19，0.14）
|
||
- [ ] ai13 建立 packages 骨架（§2.18，0.15）
|
||
- [ ] coord 修订 004 §7.2 warning.triggered 注释（§2.11）
|
||
- [ ] coord 修正 coord-cross-review.md §6 #14 责任方（§2.5）
|
||
- [ ] coord 在 coord-final-decisions.md 补充 I1 双入口策略（§2.16）
|
||
- [ ] coord 在 coord-final-decisions.md 补充 F7 服务前缀规则（§5.3）
|
||
- [ ] coord 在 coord-final-decisions.md 补充 G14 ADMIN_ 前缀（§5.2）
|
||
- [ ] coord 在 coord-final-decisions.md §7.2 补充设计决策记录保留规则（§4.4）
|
||
|
||
### 8.3 P2 各批次启动前完成（各 AI）
|
||
|
||
- [ ] ai03 回写 teacher-bff 02（GetTeacherDashboard 命名，§3.4）
|
||
- [ ] ai04 回写 student-bff 02（B1/B2/B8，§3.4）
|
||
- [ ] ai06 回写 iam 02（I1-I8，§3.4）
|
||
- [ ] ai13 回写 teacher-portal 03（删除 REST→GraphQL，§3.4）
|
||
- [ ] ai14 回写 student-portal 02（F9/F7，§3.4）
|
||
- [ ] ai15 回写 parent-portal 02（F9/删除过渡方案，§3.4）
|
||
- [ ] ai02 回写 push-gateway 02（ISSUE-053/055/056/058，§3.4）
|
||
- [ ] ai10 回写 msg 02（ISSUE-042/043/012，§3.4）
|
||
- [ ] ai16 回写 admin-portal 02（ISSUE-044~048，§3.4）
|
||
|
||
### 8.4 P3 各阶段执行中持续（各 AI）
|
||
|
||
- [ ] 各 AI 按工作量分级执行（§3.1-3.3）
|
||
- [ ] 各 AI 按跨阶段扩展例外执行（§2.3）
|
||
- [ ] 各 AI 按回写义务执行（§3.4）
|
||
- [ ] coord 按批次验收检查（§8.1-8.3）
|
||
|
||
---
|
||
|
||
## 9. 未解决问题后续处理
|
||
|
||
### 9.1 待 P6 评估的问题（保留）
|
||
|
||
以下问题待 P6 阶段评估，不阻塞当前批次：
|
||
|
||
- **ISSUE-014**：admin-portal 8 个新 Kafka topic（若审计归 iam，仅需 1 个 audit consumer topic，见 §5.5）
|
||
- **X3 审计日志归属**：已前置裁决（§5.5），归 iam
|
||
- **X6 httpOnly Cookie 迁移**：P6 评估
|
||
- **X7 其他 P6+ 事项**：P6 评估
|
||
|
||
### 9.2 不再追溯的问题
|
||
|
||
以下问题已被本裁决覆盖，不再单独追溯：
|
||
|
||
- ISSUE-001 ~ ISSUE-014（coord 初始识别，已被 coord-final-decisions + 本裁决覆盖）
|
||
- ISSUE-015 ~ ISSUE-022（ai08 提请，已在 §1/§2 裁决）
|
||
- ISSUE-023 ~ ISSUE-025-ai09（ai09 提请，已在 §2.4/2.13/2.14 裁决）
|
||
- ISSUE-026 ~ ISSUE-030-ai11（ai11 提请，已在 §2.6/2.10/2.11/4.5 裁决）
|
||
- ISSUE-028 ~ ISSUE-031-ai04（ai04 提请，已在 §3.4 裁决）
|
||
- ISSUE-032 ~ ISSUE-036+059-ai03（ai03 提请，已在 §2.7/2.8/2.9/3.1 裁决）
|
||
- ISSUE-036 ~ ISSUE-041-ai13（ai13 提请，已在 §2.2/2.17/2.18/3.5 裁决）
|
||
- ISSUE-031 ~ ISSUE-035-ai15（ai15 提请，已在 §0.3/0.4/3.4 裁决）
|
||
- ISSUE-042 ~ ISSUE-043-ai10（ai10 提请，已在 §1.5/2.4 裁决）
|
||
- ISSUE-044 ~ ISSUE-048-ai16（ai16 提请，已在 §5.1-5.5 裁决）
|
||
- ISSUE-047 ~ ISSUE-052-ai06（ai06 提请，已在 §2.15/2.16/3.2/4.1 裁决）
|
||
- ISSUE-053 ~ ISSUE-058-ai02（ai02 提请，已在 §1.5/2.4/4.2/4.3/4.4 裁决）
|
||
- ISSUE-063 ~ ISSUE-066-ai14（ai14 提请，已在 §3.4/3.6/4.7 裁决）
|
||
|
||
---
|
||
|
||
## 10. 问题索引表（编号冲突映射）
|
||
|
||
> 由于 issues.md 存在严重编号冲突（见 §0.4），本表提供 `ISSUE-XXX-<提请AI>` 格式的唯一定位。
|
||
|
||
| ISSUE 编号 | 提请 AI | 主题 | 裁决章节 |
|
||
| -------------- | ------- | ------------------------------------------------------------------------------ | --------- |
|
||
| ISSUE-001 | coord | iam gRPC server 启用时机三处文档冲突 | §1.1/1.2 |
|
||
| ISSUE-002 | coord | shared-ts Outbox 工具包未列入 P2 整改清单 | §2.1 |
|
||
| ISSUE-003 | coord | 004 §4.2 gRPC 启用阶段矩阵与 B2 裁决冲突 | §1.2 |
|
||
| ISSUE-004 | coord | teacher-bff P2 "首次实现即 gRPC 调下游"与下游服务分阶段启用矛盾 | §2.3/2.8 |
|
||
| ISSUE-005 | coord | teacher-bff 跨阶段持续改造与"不分阶段"裁决原则矛盾 | §0.3/2.3 |
|
||
| ISSUE-006 | coord | student-bff P3 同样存在跨度过大问题 | §2.3 |
|
||
| ISSUE-007 | coord | BFF DownstreamClient 抽象回写 teacher-bff 的时间点 | §3.4 |
|
||
| ISSUE-008 | coord | teacher-portal P2 改造为 urql/apollo 的工作量 | §2.17/3.5 |
|
||
| ISSUE-009 | coord | parent-bff P4 依赖 iam.GetChildrenByParent | §3.2 |
|
||
| ISSUE-010 | coord | ai12 ai P5 调 content.QuestionService 的 proto 补全时机冲突 | §1.3/1.4 |
|
||
| ISSUE-011 | coord | ai12 ai P5 调 core-edu.ExamService.GetExam 的方向修正 | §7.12 |
|
||
| ISSUE-012 | coord | msg P5 调 push-gateway HTTP /internal/push 的时序协调 | §4.2 |
|
||
| ISSUE-013 | coord | BFF P2-P4 不订阅 Kafka，家长通知实时性如何保证 | §3.7 |
|
||
| ISSUE-014 | coord | admin-portal P6 + 8 个新 Kafka topic 时序 | §5.5/9.1 |
|
||
| ISSUE-015 | ai08 | port-allocation.md §3 与 §5 关于 iam gRPC 启用阶段冲突 | §1.1 |
|
||
| ISSUE-016 | ai08 | 004 §16.7.4 P4 清单未列 content QuestionService | §1.3/1.4 |
|
||
| ISSUE-017 | ai08 | 14 个 issues 状态字段未回填 coord 裁决 | §0.4/9.2 |
|
||
| ISSUE-018 | ai08 | shared-ts Outbox 工具包设计未明确 | §2.1 |
|
||
| ISSUE-019 | ai08 | GraphQL schema 第一版仲裁机制未明确 | §2.2 |
|
||
| ISSUE-020 | ai08 | BFF 跨阶段扩展例外的验收标准未明确 | §2.3 |
|
||
| ISSUE-021 | ai08 | "不分阶段"原则与"批次时间线"表述易混淆 | §0.3 |
|
||
| ISSUE-022 | ai08 | core-edu AttendanceService proto 补全责任方不明 | §2.5 |
|
||
| ISSUE-023-ai09 | ai09 | content /readyz 检查项与 P5 ES 引入的时序冲突 | §2.4 |
|
||
| ISSUE-024-ai09 | ai09 | content ES Projector 实现位置未明确 | §2.14 |
|
||
| ISSUE-025-ai09 | ai09 | Neo4j 知识图谱同步是否属于"派生数据事件"豁免 Outbox | §2.13 |
|
||
| ISSUE-026-ai11 | ai11 | ClickHouse DDL 目录归属不明 | §2.12 |
|
||
| ISSUE-027-ai11 | ai11 | analytics.proto 扩展交付时间不明确 | §2.10 |
|
||
| ISSUE-028-ai11 | ai11 | warning.triggered topic 登记状态不明确 | §2.11 |
|
||
| ISSUE-029-ai11 | ai11 | data-ana /readyz 检查 iam gRPC 依赖落地验证 | §4.5 |
|
||
| ISSUE-030-ai11 | ai11 | 降级模式在 ActionState 信封中的表达方式 | §2.6 |
|
||
| ISSUE-028-ai04 | ai04 | ai04 02 文档与 coord B1+B2 裁决冲突需回写 | §3.4 |
|
||
| ISSUE-029-ai04 | ai04 | ai04 P3 启动前置依赖确认 | §4.1/6.1 |
|
||
| ISSUE-030-ai04 | ai04 | ai04⟷ai14 student-bff GraphQL schema 第一版仲裁时机 | §2.2 |
|
||
| ISSUE-031-ai04 | ai04 | issues.md ISSUE-024/025 编号冲突 | §0.4 |
|
||
| ISSUE-031-ai15 | ai15 | coord-final-decisions.md + ai-work-orchestration.md 相对路径错误 | §1.6 |
|
||
| ISSUE-032-ai03 | ai03 | B2 裁决 P2 阶段 teacher-bff Dashboard Query Resolver 实现方式 | §2.8 |
|
||
| ISSUE-033-ai03 | ai03 | B4 越权防御校验 teacherId 与班级关系在 P2 阶段实现方式 | §2.9 |
|
||
| ISSUE-034-ai03 | ai03 | G2 /readyz 检查全部下游依赖在 P2 阶段不可行 | §2.4 |
|
||
| ISSUE-035-ai03 | ai03 | §5.2 接口命名 GetTeacherDashboard 需 ai03 回写 02 文档 | §3.4 |
|
||
| ISSUE-036-ai03 | ai03 | ai03 P2 工作量激增 | §3.1 |
|
||
| ISSUE-059 | ai03 | BFF_TEACHER_FORBIDDEN_RESOURCE vs BFF_TEACHER_PERMISSION_DENIED 错误码语义区分 | §2.7 |
|
||
| ISSUE-032-ai15 | ai15 | ai15 parent-portal API 契约 REST 假设与 F9 GraphQL 裁决冲突 | §3.4 |
|
||
| ISSUE-033-ai15 | ai15 | ai15 parent-portal 通知偏好 P4 落地与 B7 裁决冲突 | §3.7 |
|
||
| ISSUE-034-ai15 | ai15 | ai15 parent-portal §476 "P4 用 REST 后续切 GraphQL"违反"不分阶段"原则 | §3.4 |
|
||
| ISSUE-035-ai15 | ai15 | issues.md 文件结构严重混乱 | §0.4 |
|
||
| ISSUE-036-ai13 | ai13 | ai13 03-long-term-architecture.md §6 "REST→GraphQL 演进策略"与 F9 裁决冲突 | §3.4 |
|
||
| ISSUE-037-ai13 | ai13 | ai13 与 ai03 的 GraphQL schema 契约协调机制未明确 | §2.2 |
|
||
| ISSUE-038-ai13 | ai13 | MF 暴露 AppShell 整体是否包含 GraphQL client 单例未明确 | §2.17 |
|
||
| ISSUE-039-ai13 | ai13 | F8 ai13 维护 packages 的建立时机与依赖未明确 | §2.18 |
|
||
| ISSUE-040-ai13 | ai13 | ai13 teacher-portal P2 功能范围与下游服务启用阶段的关系未明确 | §3.5 |
|
||
| ISSUE-041-ai13 | ai13 | 仲裁评估总结 | §9.2 |
|
||
| ISSUE-042-ai10 | ai10 | M2 msg /readyz 强依赖 PushGateway 与 P5 同批次启动时序冲突 | §2.4 |
|
||
| ISSUE-043-ai10 | ai10 | 004 §7.2 表格 edu.notification.events 与 §16.3.2 + G16 裁决不同步 | §1.5 |
|
||
| ISSUE-044-ai16 | ai16 | admin-portal BFF 归属不明 | §5.1 |
|
||
| ISSUE-045-ai16 | ai16 | admin-portal 错误码前缀缺失 | §5.2 |
|
||
| ISSUE-046-ai16 | ai16 | admin-portal 权限点命名与 F7 规范的契合度 | §5.3 |
|
||
| ISSUE-047-ai16 | ai16 | admin-portal GraphQL 客户端复用 Shell 还是独立引入 | §2.17/5.4 |
|
||
| ISSUE-048-ai16 | ai16 | admin-portal 审计日志与 iam 审计事件归属耦合 | §5.5 |
|
||
| ISSUE-047-ai06 | ai06 | 批次 0 强阻塞 ai06 iam P2 启动 | §4.1 |
|
||
| ISSUE-048-ai06 | ai06 | I7 API 版本化 /iam/v1/* 破坏性变更跨服务协调 | §2.15 |
|
||
| ISSUE-049-ai06 | ai06 | gRPC 与 REST 双入口实现策略未明确 | §2.16 |
|
||
| ISSUE-050-ai06 | ai06 | shared-ts Outbox 工具包 API 契约未明确 | §2.1 |
|
||
| ISSUE-051-ai06 | ai06 | 02-architecture-design.md 与 I1-I8 裁决对齐回写义务 | §3.4 |
|
||
| ISSUE-052-ai06 | ai06 | iam P2 工作量评估与批次时间线不匹配 | §3.2 |
|
||
| ISSUE-053-ai02 | ai02 | G16 Kafka topic 命名规则与 push-gateway 02 §5.1 消费 topic 不一致 | §1.5 |
|
||
| ISSUE-054-ai02 | ai02 | shared-go 共享包建立时机与责任方未在批次规划中明确 | §2.19 |
|
||
| ISSUE-055-ai02 | ai02 | G2 /readyz "全部下游依赖"对 push-gateway Kafka 可选消费的适用性 | §2.4 |
|
||
| ISSUE-056-ai02 | ai02 | 02 文档 §5.4/§14.2 仲裁请求章节删除会丢失设计决策追溯 | §4.4 |
|
||
| ISSUE-057-ai02 | ai02 | ISSUE-012 /internal/push 契约仲裁前置与 02 §4.2 已有定义重复 | §4.2 |
|
||
| ISSUE-058-ai02 | ai02 | push-gateway 在线状态 Redis SET 心跳续期与 G2 /readyz 检查的耦合 | §4.3 |
|
||
| ISSUE-063-ai14 | ai14 | ai14 student-portal 02 REST 假设与 F9/B1 GraphQL 裁决冲突 | §3.4 |
|
||
| ISSUE-064-ai14 | ai14 | F7 权限点命名风格 ai14 文档与裁决不一致 | §3.4 |
|
||
| ISSUE-065-ai14 | ai14 | student-portal P3 功能范围受限 | §3.6 |
|
||
| ISSUE-066-ai14 | ai14 | student-portal 通知功能推迟到 P5 | §3.7 |
|
||
|
||
---
|
||
|
||
## 11. 裁决效力
|
||
|
||
### 11.1 裁决生效
|
||
|
||
本文件自发布之日起生效，覆盖以下文档的冲突条款：
|
||
|
||
- `coord-final-decisions.md`（80+ 项裁决保持有效，本文件为其补充 + 澄清）
|
||
- `ai-work-orchestration.md`（批次时间线以本文件 §6 为准）
|
||
- `issues.md`（所有问题状态转为"总裁已裁决"）
|
||
|
||
### 11.2 裁决变更
|
||
|
||
本文件的裁决变更需总裁（用户）再次确认。coord 无权单方面变更。
|
||
|
||
### 11.3 裁决执行
|
||
|
||
- **coord**：负责 P0 立即执行项（§8.1）+ P1 批次 0 启动前完成项（§8.2）+ 批次验收
|
||
- **各 AI**：负责 P2 各批次启动前完成项（§8.3）+ P3 各阶段执行中持续项（§8.4）
|
||
|
||
---
|
||
|
||
**本文件为总裁最终裁决，所有 AI 必须遵守。**
|