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

docs: ai 协作文档体系重构与多 ai 仲裁结果落地

Browse Source 
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.设计规格文档
This commit is contained in:
SpecialX
2026-07-10 12:58:22 +08:00
parent 2a2a56f541
commit faaaf29f67
120 changed files with 23201 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

129
docs/architecture/issues/contracts/admin-portal_contract.md Normal file
View File

@@ -0,0 +1,129 @@
# admin-portal 对接契约
> 负责人：ai16
> 关联：[matrix.md](./matrix.md)、[iam.proto](../../../packages/shared-proto/proto/iam.proto)、[events.proto](../../../packages/shared-proto/proto/events.proto)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
无。admin-portal 是前端微前端 Remote。
### 1.2 HTTP 端点（如有）
| Method | Path | 用途 | 认证 |
| ------ | ----------- | ---------------- | --------------------- |
| GET | / | 管理后台首页 | JWT 必需 + admin 角色 |
| GET | /users | 用户管理 | JWT 必需 + admin |
| GET | /roles | 角色权限管理 | JWT 必需 + admin |
| GET | /classes | 班级管理（全局） | JWT 必需 + admin |
| GET | /teachers | 教师管理 | JWT 必需 + admin |
| GET | /students | 学生管理 | JWT 必需 + admin |
| GET | /audit-logs | 审计日志 | JWT 必需 + admin |
| GET | /dashboard | 管理员仪表盘 | JWT 必需 + admin |
| GET | /system | 系统配置 | JWT 必需 + admin |
### 1.3 GraphQL schema（如 BFF）
不适用。admin-portal 消费 teacher-bff GraphQL admin namespace，自身不提供 schema。
### 1.4 Kafka 事件发布（如有）
无。
### 1.5 错误码前缀
无（前端不定义错误码前缀，透传 BFF 错误码）。
### 1.6 微前端架构（补充）
| 角色 | 说明 |
| ---------------------- | ----------------------------------------------- |
| MF Remote | 管理后台是微前端远程模块 |
| 暴露的 remote 模块 | AdminApp（管理后台完整应用）、shared 管理端组件 |
| module federation 配置 | `apps/admin-portal/module-federation.config.ts` |
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
无。前端不直接调 gRPC。
### 2.2 Kafka 事件订阅（异步）
无。前端不直接订阅 Kafka（审计日志通过 GraphQL 查询，非直接订阅）。
### 2.3 HTTP 调用（如有）
| 被调用方 | Method.Path | 用途 | mock 策略 |
| ------------------- | ----------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------- |
| api-gateway (ai01) | POST /api/admin/graphql | 管理 GraphQL 查询（经网关代理到 teacher-bff admin namespace） | api-gateway/teacher-bff 就绪前使用 MSW 拦截返回 mock GraphQL 响应 |
| api-gateway (ai01) | POST /api/auth/login | 管理员登录 | api-gateway 就绪前使用 MSW 返回固定 JWT（admin 角色） |
| push-gateway (ai02) | GET /ws | WebSocket 实时通知 | push-gateway 就绪前使用 mock-socket 模拟 WS 推送 |
### 2.4 GraphQL 查询域（经 api-gateway 代理到 teacher-bff admin namespace）
| Query/Mutation | 用途 | mock 策略 |
| ------------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------- |
| currentUser | 当前管理员信息 | MSW 返回固定管理员（admin 角色） |
| adminUsers / createUser / updateUser / deleteUser | 用户管理 | MSW 返回固定 50 个用户 + CRUD success |
| adminRoles / updateRolePermissions | 角色权限管理 | MSW 返回固定 5 个角色 + 权限矩阵 |
| adminClasses | 班级管理（全局） | MSW 返回固定 20 个班级 |
| adminTeachers | 教师管理 | MSW 返回固定 50 个教师 |
| adminStudents | 学生管理 | MSW 返回固定 1200 个学生 |
| auditLogs | 审计日志（聚合 iam AuditEvent） | MSW 返回固定 100 条审计日志 |
| adminDashboard | 管理员仪表盘 | MSW 返回固定仪表盘（total_teachers=50, total_students=1200, school_avg_score=80.0） |
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] api-gateway HTTP :8080 启用（ai01）—— 前端请求入口 + admin 角色校验
- [ ] teacher-bff GraphQL :3003 启用（ai03）—— admin namespace 可用
- [ ] iam gRPC 50052 启用（ai06）—— 用户/角色/审计日志数据来源
- [ ] edu.iam.audit.created topic 有事件发布（ai06）—— 审计日志来源
- [ ] data-ana gRPC 50055 启用（ai11）—— adminDashboard 数据来源
- [ ] push-gateway WebSocket :8081/ws 启用（ai02）—— 实时通知
### 3.2 我的就绪标志（供下游消费）
- [ ] admin-portal dev server :4003 启用
- [ ] MF Remote 可被 AppShell 加载（暴露 AdminApp 模块）
- [ ] 独立壳渲染（首页 + 导航 + 路由守卫 + admin 角色校验）
- [ ] 登录流程可用（POST /api/auth/login 获取 JWT，前端校验 admin 角色）
- [ ] GraphQL 查询可执行（currentUser / adminDashboard / auditLogs 返回数据）
- [ ] 用户/角色 CRUD 可执行（createUser / updateRolePermissions）
- [ ] WebSocket 通知可接收
---
## §4 Mock 策略
### 4.1 我提供的 mock
admin-portal 是前端，无下游消费方。但对开发体验提供：
- **Storybook**：各组件独立 story（含权限矩阵编辑器、审计日志表格等复杂组件）
- **MSW handlers**：`apps/admin-portal/src/mocks/handlers.ts`，拦截所有 GraphQL/HTTP 请求
### 4.2 我消费的 mock
在真实上游就绪前，admin-portal 使用以下 mock：
- **HTTP/GraphQL mock**：使用 MSW 拦截所有请求
- POST /api/auth/login → 返回固定 JWT + UserInfo（admin 角色，permissions=["*"]）
- POST /api/admin/graphql → 根据 operationName 返回对应 mock 响应（与 teacher-bff admin namespace mock 数据一致）
- auditLogs mock 返回固定 100 条审计日志（含 action: create/update/delete/login/logout/permission_change）
- adminDashboard mock 返回固定全校统计仪表盘
- 所有 mock 响应定义在 `apps/admin-portal/src/mocks/fixtures/*.json`
- **WebSocket mock**：使用 mock-socket 库
- 连接后每 30 秒推送 1 条 mock 系统通知
- **JWT mock**：使用固定 mock JWT（admin 角色），存入 httpOnly cookie
- **权限矩阵 mock**：内置固定 5 个角色 + 完整权限矩阵（teacher/student/parent/admin/super_admin）
- **环境切换**：通过 `NEXT_PUBLIC_API_MOCKING=enabled` 环境变量控制，上游就绪后设为 `disabled`

108
docs/architecture/issues/contracts/ai_contract.md Normal file
View File

@@ -0,0 +1,108 @@
# ai 对接契约
> 负责人：ai12
> 关联：[matrix.md](./matrix.md)、[ai.proto](../../../packages/shared-proto/proto/ai.proto)、[events.proto](../../../packages/shared-proto/proto/events.proto)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
| Service | RPC | 请求 | 响应 | 端口 |
| --------- | ---------------------- | ----------------------------- | ------------------------ | ----- |
| AiService | Chat | ChatRequest | ChatResponse | 50057 |
| AiService | StreamChat | ChatRequest | stream ChatChunk | 50057 |
| AiService | GenerateQuestion | GenerateQuestionRequest | GeneratedQuestion | 50057 |
| AiService | OptimizeExpression | OptimizeExpressionRequest | OptimizedExpression | 50057 |
| AiService | GenerateLessonPlan | GenerateLessonPlanRequest | LessonPlan | 50057 |
| AiService | StreamGenerateQuestion | StreamGenerateQuestionRequest | stream GeneratedQuestion | 50057 |
### 1.2 HTTP 端点（如有）
无对外 HTTP 端点，仅 gRPC（含 2 个 Server Streaming RPC：StreamChat / StreamGenerateQuestion）。
### 1.3 GraphQL schema（如 BFF）
不适用。
### 1.4 Kafka 事件发布（如有）
| Topic | Event | 消费方 |
| ------------------- | ---------------------------------------------------------------------------------------- | -------- |
| edu.ai.usage.events | AIUsageEvent（operation: chat/generate_question/optimize_expression/lesson_preparation） | data-ana |
> 注：AIUsageEvent 豁免 Outbox 模式（派生数据事件，见 004 §12.2 + §15.3 #6）。
### 1.5 错误码前缀
`AI_`（如 AI_PROVIDER_UNAVAILABLE、AI_TOKEN_LIMIT_EXCEEDED、AI_CONTENT_FILTERED）
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
| 被调用方 | Service.RPC | 用途 | mock 策略 |
| --------------- | -------------------------------------- | ---------------------------- | ----------------------------------------------------------- |
| content (ai09) | KnowledgeGraphService.GetPrerequisites | 生成题目时获取知识点前置依赖 | content 就绪前使用本地知识点 stub（固定 3 个前置知识点） |
| content (ai09) | QuestionService.SearchQuestions | 备课时检索同类题目参考 | content 就绪前返回空列表 |
| data-ana (ai11) | AnalyticsService.GetStudentWeakness | 个性化出题时获取学生薄弱点 | data-ana 就绪前使用本地薄弱点 stub（固定 2 个 weak_points） |
### 2.2 Kafka 事件订阅（异步）
| Topic | Event | 发布方 | mock 策略 |
| ---------------------------------- | ------------------- | -------------- | -------------------------------------- |
| edu.content.knowledge_point.events | KnowledgePointEvent | content (ai09) | content 就绪前不订阅，使用内置知识点表 |
| edu.content.question.events | QuestionEvent | content (ai09) | content 就绪前忽略 |
### 2.3 HTTP 调用（如有）
| 被调用方 | Method.Path | 用途 | mock 策略 |
| -------------------------------- | ------------------------- | ------------------ | ------------------------------------------------------------------ |
| LLM Provider（OpenAI/百川/本地） | POST /v1/chat/completions | 调用大模型生成内容 | 开发期使用本地 mock server 返回固定 ChatResponse，不消耗真实 token |
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] content gRPC 50054 启用（ai09）—— 知识点维度 + 题库检索
- [ ] edu.content.knowledge_point.events topic 有事件发布（ai09）
- [ ] data-ana gRPC 50055 启用（ai11）—— 学生薄弱点（可选，ai 可先独立运行）
### 3.2 我的就绪标志（供下游消费）
- [ ] ai gRPC 50057 启用（HealthService.Check 返回 SERVING）
- [ ] AiService.Chat / StreamChat 可调用（含流式响应）
- [ ] AiService.GenerateQuestion / StreamGenerateQuestion 可调用
- [ ] AiService.GenerateLessonPlan 可调用（P5 补全）
- [ ] AiService.OptimizeExpression 可调用
- [ ] edu.ai.usage.events topic 可发布（供 data-ana 统计 AI 用量）
---
## §4 Mock 策略
### 4.1 我提供的 mock
在 ai 真实服务就绪前，为下游（teacher-bff）提供以下 mock：
- **gRPC mock**：使用 grpc-mock 拦截 50057 端口
- AiService.Chat 返回固定 ChatResponse（content="这是 AI 助手的模拟回复"）
- AiService.StreamChat 返回固定流（3 个 ChatChunk，最后一个 done=true）
- AiService.GenerateQuestion 返回固定 GeneratedQuestion（question/answer/explanation）
- AiService.GenerateLessonPlan 返回固定 LessonPlan（3 个 LessonSection）
- AiService.StreamGenerateQuestion 返回固定流（2 个 GeneratedQuestion）
- **Kafka mock**：ai 就绪前不发布真实 AIUsageEvent，data-ana 仪表盘 AI 用量显示"暂无数据"
### 4.2 我消费的 mock
在真实上游就绪前，ai 使用以下 mock：
- **LLM Provider mock**：本地启动 mock server，POST /v1/chat/completions 返回固定 JSON（不消耗真实 token，不产生费用）
- **content 知识点**：内置固定知识点表（数学 20 个知识点 + 前置依赖关系），不依赖 content gRPC
- **data-ana 薄弱点**：内置固定学生薄弱点（2 个 weak_points），不依赖 data-ana gRPC
- **事件订阅**：不订阅 content 事件，知识点维度表静态

102
docs/architecture/issues/contracts/api-gateway_contract.md Normal file
View File

@@ -0,0 +1,102 @@
# api-gateway 对接契约
> 负责人：ai01
> 关联：[matrix.md](./matrix.md)、[iam.proto](../../../packages/shared-proto/proto/iam.proto)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
无。api-gateway 是 HTTP 入口，不对外提供 gRPC。
### 1.2 HTTP 端点（如有）
| Method | Path | 用途 | 认证 |
| ------ | -------------- | ------------------------------------------- | ---------------------- |
| ANY | /api/auth/* | 代理到 iam 认证相关（登录/注册/刷新 token） | 公开（登录注册免认证） |
| ANY | /api/teacher/* | 代理到 teacher-bff GraphQL（:3003） | JWT 必需 |
| ANY | /api/student/* | 代理到 student-bff GraphQL（:3009） | JWT 必需 |
| ANY | /api/parent/* | 代理到 parent-bff GraphQL（:3010） | JWT 必需 |
| ANY | /api/admin/* | 代理到 teacher-bff GraphQL admin namespace | JWT 必需 + admin 角色 |
| GET | /healthz | 网关健康检查（liveness） | 公开 |
| GET | /readyz | 网关就绪检查（readiness，含 iam 连通性） | 公开 |
| GET | /metrics | Prometheus 指标端点 | 公开（内网） |
### 1.3 GraphQL schema（如 BFF）
不适用。api-gateway 仅做 HTTP 反向代理 + JWT 验签，不解析 GraphQL。
### 1.4 Kafka 事件发布（如有）
无。api-gateway 不发布事件。
### 1.5 错误码前缀
`GW_`（如 GW_UNAUTHORIZED、GW_RATE_LIMITED、GW_CIRCUIT_OPEN、GW_BACKEND_UNAVAILABLE）
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
| 被调用方 | Service.RPC | 用途 | mock 策略 |
| ---------- | ----------------------------- | ---------------------------------------- | ----------------------------------------------------------------- |
| iam (ai06) | IamService.GetPublicKey | 启动时拉取 RS256 公钥，用于 JWT 验签 | iam 就绪前使用本地固定 mock 公钥（与 mock 私钥配对签发 mock JWT） |
| iam (ai06) | IamService.GetEffectiveAccess | 权限校验（可选，部分路由需要细粒度权限） | iam 就绪前放行所有请求（仅校验 JWT 签名） |
### 2.2 Kafka 事件订阅（异步）
无。api-gateway 不订阅 Kafka 事件。
### 2.3 HTTP 调用（如有）
| 被调用方 | Method.Path | 用途 | mock 策略 |
| ------------------ | ------------- | --------------------------- | -------------------------------------------------- |
| teacher-bff (ai03) | POST /graphql | 反向代理教师端 GraphQL 请求 | teacher-bff 就绪前返回 502，前端使用本地 mock 数据 |
| student-bff (ai04) | POST /graphql | 反向代理学生端 GraphQL 请求 | student-bff 就绪前返回 502 |
| parent-bff (ai05) | POST /graphql | 反向代理家长端 GraphQL 请求 | parent-bff 就绪前返回 502 |
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] iam gRPC 50052 启用（ai06）—— GetPublicKey 拉取验签公钥
- [ ] teacher-bff GraphQL :3003 启用（ai03）
- [ ] student-bff GraphQL :3009 启用（ai04）
- [ ] parent-bff GraphQL :3010 启用（ai05）
### 3.2 我的就绪标志（供下游消费）
- [ ] api-gateway HTTP :8080 启用（/healthz 返回 200）
- [ ] /readyz 返回 200（含 iam 连通性检查通过）
- [ ] JWT 验签链路打通（使用 iam 公钥校验 access_token）
- [ ] /api/auth/* 代理到 iam 认证链路可用
- [ ] /api/teacher/* /api/student/* /api/parent/* 反向代理到各 BFF 可用
- [ ] 限流（IP 级令牌桶）+ 熔断（各后端独立熔断器）生效
---
## §4 Mock 策略
### 4.1 我提供的 mock
在 api-gateway 真实就绪前，为下游（各前端 portal）提供以下 mock：
- **HTTP mock**：使用 MSW（Mock Service Worker）或本地 nginx 拦截
- /api/auth/login 返回固定 JWT（mock 签发）+ UserInfo
- /api/teacher/* /api/student/* /api/parent/* 直接返回各 BFF 的 mock GraphQL 响应
- /healthz /readyz 返回 200
- **JWT mock**：前端开发期使用固定 mock JWT（api-gateway 就绪前不走真实验签）
### 4.2 我消费的 mock
在真实上游就绪前，api-gateway 使用以下 mock：
- **iam 公钥**：使用本地固定 mock RS256 公钥（与 mock 私钥配对），验签 mock JWT
- **iam 权限校验**：GetEffectiveAccess 返回 allowed=true，放行所有请求
- **各 BFF 代理**：BFF 就绪前返回 503 + Retry-After，前端降级到本地 mock 数据

123
docs/architecture/issues/contracts/classes_contract.md Normal file
View File

@@ -0,0 +1,123 @@
# classes 对接契约
> 负责人：ai07
> 关联：[matrix.md](../matrix.md)、[classes.proto](../../../packages/shared-proto/proto/classes.proto)、[events.proto](../../../packages/shared-proto/proto/events.proto)、[02-architecture-design.md](../../../services/classes/docs/02-architecture-design.md)
> 状态：黄金模板（P1 已实现），P3 合并入 core-edu
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
| Service | RPC | 请求 | 响应 | 端口 |
| ------------ | ----------- | ------------------ | ------------------- | ------------------------------- |
| ClassService | CreateClass | CreateClassRequest | Class | 50053（P3 启用，core-edu 承载） |
| ClassService | GetClass | GetClassRequest | Class | 50053 |
| ClassService | ListClasses | ListClassesRequest | ListClassesResponse | 50053 |
| ClassService | UpdateClass | UpdateClassRequest | Class | 50053 |
| ClassService | DeleteClass | DeleteClassRequest | Empty | 50053 |
> **注意**：classes 当前仅 REST（端口 3001），gRPC server 50053 在 P3 合并入 core-edu 后启用。proto 契约已就绪（classes.proto），由 core-edu 实现承载。
### 1.2 HTTP 端点（如有）
| Method | Path | 权限 | 说明 |
| ------ | -------------- | ---------------- | ----------------------------- |
| POST | `/classes` | `CLASSES_CREATE` | 创建班级 |
| GET | `/classes` | `CLASSES_READ` | 列表（可选 `?gradeId=` 过滤） |
| GET | `/classes/:id` | `CLASSES_READ` | 单条查询 |
| PUT | `/classes/:id` | `CLASSES_UPDATE` | 更新 |
| DELETE | `/classes/:id` | `CLASSES_DELETE` | 删除（先校验存在） |
| GET | `/healthz` | 无 | liveness |
| GET | `/readyz` | 无 | readiness（校验 DB） |
| GET | `/metrics` | 无 | Prometheus 指标 |
> **响应信封**：ActionState（`{success:true, data:T}` / `{success:false, error:{code,message,details?,traceId?}}`）
### 1.3 GraphQL schema（如 BFF）
不适用。classes 是业务服务，非 BFF。
### 1.4 Kafka 事件发布（如有）
| Topic | Event | 消费方 | 阶段 |
| --------------------------- | --------------------------------- | ------------------------------- | ------------------- |
| `edu.org.class.created` | ClassEvent（action: created） | data-ana（建宽表行） | P3（core-edu 承载） |
| `edu.org.class.updated` | ClassEvent（action: updated） | data-ana、msg（班主任变更通知） | P3 |
| `edu.org.class.deleted` | ClassEvent（action: deleted） | data-ana、core-edu（关联检查） | P3 |
| `edu.org.class.transferred` | ClassEvent（action: transferred） | msg（通知新/旧班主任） | P3 |
> **事件 message**：`events.proto` 的 `ClassEvent`（event_id / aggregate_id / event_type / occurred_at / class_id / name / action / metadata）
> **发布方式**：Outbox 模式（P3 补齐 `shared/outbox/`），保证事务与事件最终一致
### 1.5 错误码前缀
`CLASSES_`（004 §11.4 确认保留，P3 合并入 core-edu 后保留历史遗留前缀）
| 错误码 | HTTP | 触发条件 |
| --------------------------- | ---- | ----------------------------- |
| `CLASSES_VALIDATION_ERROR` | 400 | Zod 校验失败 / 空 update body |
| `CLASSES_NOT_FOUND` | 404 | 资源不存在 |
| `CLASSES_PERMISSION_DENIED` | 403 | PermissionGuard 校验失败 |
| `CLASSES_CONFLICT` | 409 | 并发冲突（预留） |
| `CLASSES_BUSINESS_ERROR` | 422 | 业务规则违反（预留） |
| `CLASSES_DATABASE_ERROR` | 500 | DB 操作失败 |
| `CLASSES_INTERNAL_ERROR` | 500 | 未预期异常 |
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
当前无。P3 合并入 core-edu 后，可能调用 iam 的 `BatchGetUsers`（班主任信息批量查询）。
### 2.2 Kafka 事件订阅（异步）
| Topic | Event | 消费动作 | 阶段 |
| --------------------------- | ---------------------------- | -------------------------------------------- | ---- |
| `edu.identity.user.deleted` | UserEvent（action: deleted） | 若 deleted user 是班主任，置空 headTeacherId | P3 |
### 2.3 HTTP 调用（如有）
无。classes 是基础数据源，不反向调用其他服务。
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] MySQL classes_db 可用（已就绪，P1）
- [ ] api-gateway `/classes/*` 路由已注册（已就绪，P1）
- [ ] P3：iam `BatchGetUsers` gRPC 可用（班主任信息查询）
- [ ] P3：Kafka `edu.identity.user.deleted` topic 可消费
### 3.2 我的就绪标志（供下游消费）
- [x] classes REST API 5 端点可用（P1 已实现）
- [x] `/healthz` + `/readyz` 可用（P1 已实现）
- [x] `/metrics` 可用（P1 已实现）
- [ ] P3：gRPC 50053 启用（由 core-edu 承载，`ClassService` 5 RPC 可调用）
- [ ] P3：`edu.org.class.created/updated/deleted/transferred` topic 可发布
- [ ] P3：Outbox 模式落地（`shared/outbox/` 目录补齐）
---
## §4 Mock 策略
### 4.1 我提供的 mock
classes 是 P1 黄金模板，REST API 已实现，**下游无需 mock，可直接调用真实服务**。
但为 P3 gRPC 迁移期间兼容，提供以下 mock 供下游在 gRPC 未启用时使用：
- **REST mock**（已可用）：直接调用 `http://classes:3001/classes/*`，返回真实数据
- **gRPC mock**（P3 过渡期）：grpc-mock 拦截 50053，ClassService 5 RPC 返回固定 Class 数据
- **Kafka mock**（P3 过渡期）：classes 事件未发布前，下游订阅方使用本地 stub（固定 ClassEvent JSON）
### 4.2 我消费的 mock
- P3 期间 iam `BatchGetUsers` 未就绪时，使用 grpc-mock 返回固定用户信息（班主任姓名）
- P3 期间 `edu.identity.user.deleted` topic 未就绪时，使用本地 Kafka mock consumer stub

110
docs/architecture/issues/contracts/content_contract.md Normal file
View File

@@ -0,0 +1,110 @@
# content 对接契约
> 负责人：ai09
> 关联：[matrix.md](./matrix.md)、[content.proto](../../../packages/shared-proto/proto/content.proto)、[events.proto](../../../packages/shared-proto/proto/events.proto)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
| Service | RPC | 请求 | 响应 | 端口 |
| --------------------- | ------------------ | ------------------------- | -------------------------- | ----- |
| TextbookService | CreateTextbook | CreateTextbookRequest | Textbook | 50054 |
| TextbookService | GetTextbook | GetTextbookRequest | Textbook | 50054 |
| TextbookService | ListTextbooks | ListTextbooksRequest | ListTextbooksResponse | 50054 |
| ChapterService | GetChapter | GetChapterRequest | Chapter | 50054 |
| ChapterService | ListChapters | ListChaptersRequest | ListChaptersResponse | 50054 |
| ChapterService | CreateChapter | CreateChapterRequest | Chapter | 50054 |
| ChapterService | UpdateChapter | UpdateChapterRequest | Chapter | 50054 |
| KnowledgeGraphService | GetPrerequisites | GetPrerequisitesRequest | KnowledgePointsResponse | 50054 |
| KnowledgeGraphService | GetLearningPath | GetLearningPathRequest | LearningPath | 50054 |
| KnowledgeGraphService | AddPrerequisite | AddPrerequisiteRequest | AddPrerequisiteResponse | 50054 |
| KnowledgeGraphService | RemovePrerequisite | RemovePrerequisiteRequest | RemovePrerequisiteResponse | 50054 |
| QuestionService | CreateQuestion | CreateQuestionRequest | Question | 50054 |
| QuestionService | GetQuestion | GetQuestionRequest | Question | 50054 |
| QuestionService | ListQuestions | ListQuestionsRequest | ListQuestionsResponse | 50054 |
| QuestionService | UpdateQuestion | UpdateQuestionRequest | Question | 50054 |
| QuestionService | DeleteQuestion | DeleteQuestionRequest | DeleteQuestionResponse | 50054 |
| QuestionService | PublishQuestion | PublishQuestionRequest | PublishQuestionResponse | 50054 |
| QuestionService | SearchQuestions | SearchQuestionsRequest | SearchQuestionsResponse | 50054 |
### 1.2 HTTP 端点（如有）
无对外 HTTP 端点，仅 gRPC。
### 1.3 GraphQL schema（如 BFF）
不适用。
### 1.4 Kafka 事件发布（如有）
| Topic | Event | 消费方 |
| ---------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------- |
| edu.content.knowledge_point.events | KnowledgePointEvent（action: created/updated/prerequisite_added/prerequisite_removed） | data-ana / ai / Neo4j Sync Worker / ES Sync Worker |
| edu.content.question.events | QuestionEvent（action: created/updated/published/deleted） | data-ana |
### 1.5 错误码前缀
`CONTENT_`（如 CONTENT_TEXTBOOK_NOT_FOUND、CONTENT_QUESTION_DUPLICATE）
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
无直接 gRPC 调用上游。content 通过 Kafka 事件接收 core-edu 班级/学生变更用于数据一致性。
### 2.2 Kafka 事件订阅（异步）
| Topic | Event | 发布方 | mock 策略 |
| ---------------- | --------------------------------- | --------------- | ----------------------------------------------------- |
| edu.class.events | ClassEvent（action: transferred） | core-edu (ai08) | core-edu 就绪前不订阅，content 内部不依赖班级实时数据 |
| edu.exam.events | ExamEvent | core-edu (ai08) | core-edu 就绪前忽略，题目关联知识点不依赖考试事件 |
### 2.3 HTTP 调用（如有）
无。
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] core-edu gRPC 50053 启用（ai08）—— 用于知识点与班级关联（可选，content 可先独立运行）
- [ ] edu.class.events / edu.exam.events topic 有事件发布（ai08）
### 3.2 我的就绪标志（供下游消费）
- [ ] content gRPC 50054 启用（HealthService.Check 返回 SERVING）
- [ ] TextbookService 3 RPC 可调用
- [ ] ChapterService 4 RPC 可调用
- [ ] KnowledgeGraphService 4 RPC 可调用（GetPrerequisites/GetLearningPath/AddPrerequisite/RemovePrerequisite）
- [ ] QuestionService 7 RPC 可调用（含 SearchQuestions 全文检索）
- [ ] edu.content.knowledge_point.events / edu.content.question.events topic 可发布
---
## §4 Mock 策略
### 4.1 我提供的 mock
在 content 真实服务就绪前，为下游（teacher-bff / student-bff / ai / data-ana）提供以下 mock：
- **gRPC mock**：使用 grpc-mock 拦截 50054 端口
- TextbookService.ListTextbooks 返回固定 5 个 Textbook（语数英理化）
- ChapterService.ListChapters 返回固定章节树（每教材 10 章）
- KnowledgeGraphService.GetLearningPath 返回固定 8 个 KnowledgePoint 推荐顺序
- KnowledgeGraphService.GetPrerequisites 返回固定 3 个前置知识点
- QuestionService.SearchQuestions 返回固定 20 个 Question（含 options）
- **Kafka mock**：content 就绪前不发布真实事件，下游使用本地 stub
### 4.2 我消费的 mock
在真实 core-edu 就绪前，content 使用以下 mock：
- 班级/学生数据：不依赖 core-edu 实时数据，知识点关联使用固定 subject_id/grade
- 事件订阅：不订阅 edu.class.events / edu.exam.events，内部数据自洽

118
docs/architecture/issues/contracts/core-edu_contract.md Normal file
View File

@@ -0,0 +1,118 @@
# core-edu 对接契约
> 负责人：ai08
> 关联：[matrix.md](./matrix.md)、[core_edu.proto](../../../packages/shared-proto/proto/core_edu.proto)、[events.proto](../../../packages/shared-proto/proto/events.proto)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
| Service | RPC | 请求 | 响应 | 端口 |
| ----------------- | ----------------------- | ------------------------------ | --------------------------- | ----- |
| ClassService | GetClass | GetClassRequest | ClassInfo | 50053 |
| ClassService | GetClassesByTeacher | GetClassesByTeacherRequest | GetClassesByTeacherResponse | 50053 |
| ClassService | BatchGetClasses | BatchGetClassesRequest | BatchGetClassesResponse | 50053 |
| ClassService | ListStudentsByClass | ListStudentsByClassRequest | ListStudentsByClassResponse | 50053 |
| ExamService | CreateExam | CreateExamRequest | CreateExamResponse | 50053 |
| ExamService | GetExam | GetExamRequest | Exam | 50053 |
| ExamService | ListExamsByClass | ListExamsByClassRequest | ListExamsResponse | 50053 |
| ExamService | UpdateExam | UpdateExamRequest | UpdateExamResponse | 50053 |
| ExamService | DeleteExam | DeleteExamRequest | DeleteExamResponse | 50053 |
| HomeworkService | AssignHomework | AssignHomeworkRequest | AssignHomeworkResponse | 50053 |
| HomeworkService | GetHomework | GetHomeworkRequest | Homework | 50053 |
| HomeworkService | ListHomeworkByClass | ListHomeworkByClassRequest | ListHomeworkResponse | 50053 |
| HomeworkService | SubmitHomework | SubmitHomeworkRequest | SubmitHomeworkResponse | 50053 |
| GradeService | RecordGrade | RecordGradeRequest | RecordGradeResponse | 50053 |
| GradeService | GetGrade | GetGradeRequest | Grade | 50053 |
| GradeService | ListGradesByStudent | ListGradesByStudentRequest | ListGradesResponse | 50053 |
| GradeService | ListGradesByExam | ListGradesByExamRequest | ListGradesResponse | 50053 |
| GradeService | ListGradesByHomework | ListGradesByHomeworkRequest | ListGradesResponse | 50053 |
| AttendanceService | RecordAttendance | RecordAttendanceRequest | RecordAttendanceResponse | 50053 |
| AttendanceService | GetAttendance | GetAttendanceRequest | Attendance | 50053 |
| AttendanceService | ListAttendanceByStudent | ListAttendanceByStudentRequest | ListAttendanceResponse | 50053 |
| AttendanceService | ListAttendanceByClass | ListAttendanceByClassRequest | ListAttendanceResponse | 50053 |
### 1.2 HTTP 端点（如有）
无对外 HTTP 端点，仅 gRPC。
### 1.3 GraphQL schema（如 BFF）
不适用。
### 1.4 Kafka 事件发布（如有）
| Topic | Event | 消费方 |
| ------------------- | -------------------------------------------------- | -------------- |
| edu.exam.events | ExamEvent（action: created/updated/deleted） | msg / data-ana |
| edu.homework.events | HomeworkEvent（action: assigned/submitted/graded） | msg / data-ana |
| edu.grade.events | GradeEvent（action: recorded/updated） | msg / data-ana |
| edu.class.events | ClassEvent（action: transferred） | msg / data-ana |
### 1.5 错误码前缀
`CORE_EDU_`（如 CORE_EDU_CLASS_NOT_FOUND、CORE_EDU_EXAM_CONFLICT）
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
无直接 gRPC 调用上游。core-edu 通过 Kafka 事件接收 iam 用户变更，不主动调 iam。
### 2.2 Kafka 事件订阅（异步）
| Topic | Event | 发布方 | mock 策略 |
| ------------------- | --------------------------------------------------------- | ---------- | -------------------------------------------------------------------- |
| edu.iam.user.events | UserEvent（action: created/updated/deleted/role_changed） | iam (ai06) | iam 就绪前不订阅，使用本地内置用户数据（teacher_id/student_id 固定） |
| edu.iam.role.events | RoleEvent（action: created/updated） | iam (ai06) | iam 就绪前忽略，权限校验在 core-edu 内部 mock |
### 2.3 HTTP 调用（如有）
无。
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] iam gRPC 50052 启用（ai06）—— 用于用户身份一致性校验（可选，core-edu 可先独立运行）
- [ ] edu.iam.user.events topic 有事件发布（ai06）—— 用于同步用户缓存
### 3.2 我的就绪标志（供下游消费）
- [ ] core-edu gRPC 50053 启用（HealthService.Check 返回 SERVING）
- [ ] ClassService 4 RPC 可调用（GetClass/GetClassesByTeacher/BatchGetClasses/ListStudentsByClass）
- [ ] ExamService 5 RPC 可调用
- [ ] HomeworkService 4 RPC 可调用
- [ ] GradeService 5 RPC 可调用
- [ ] AttendanceService 4 RPC 可调用
- [ ] edu.exam.events / edu.homework.events / edu.grade.events / edu.class.events topic 可发布
---
## §4 Mock 策略
### 4.1 我提供的 mock
在 core-edu 真实服务就绪前，为下游（teacher-bff / student-bff / parent-bff / content / msg / data-ana）提供以下 mock：
- **gRPC mock**：使用 grpc-mock 拦截 50053 端口
- ClassService.GetClassesByTeacher 返回固定 3 个 ClassInfo
- ClassService.ListStudentsByClass 返回固定 30 个 StudentInfo
- ExamService.ListExamsByClass 返回固定 2 个 Exam
- HomeworkService.ListHomeworkByClass 返回固定 3 个 Homework
- GradeService.ListGradesByStudent 返回固定 5 个 Grade
- AttendanceService.ListAttendanceByStudent 返回固定 10 条 Attendance
- **Kafka mock**：core-edu 就绪前不发布真实事件，下游 data-ana/msg 使用本地 stub 事件
### 4.2 我消费的 mock
在真实 iam 就绪前，core-edu 使用以下 mock：
- 用户数据：内置固定 teacher_id / student_id（不订阅 edu.iam.user.events）
- 权限校验：core-edu 内部不校验权限（由 Gateway/BFF 层负责），仅记录 created_by 字段

121
docs/architecture/issues/contracts/data-ana_contract.md Normal file
View File

@@ -0,0 +1,121 @@
# data-ana 对接契约
> 负责人：ai11
> 关联：[matrix.md](./matrix.md)、[analytics.proto](../../../packages/shared-proto/proto/analytics.proto)、[events.proto](../../../packages/shared-proto/proto/events.proto)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
| Service | RPC | 请求 | 响应 | 端口 |
| ---------------- | ---------------------- | ----------------------------- | ------------------------- | ----- |
| AnalyticsService | GetClassPerformance | GetClassPerformanceRequest | ClassPerformance | 50055 |
| AnalyticsService | GetStudentWeakness | GetStudentWeaknessRequest | StudentWeakness | 50055 |
| AnalyticsService | GetLearningTrend | GetLearningTrendRequest | LearningTrend | 50055 |
| AnalyticsService | GetTeacherDashboard | GetTeacherDashboardRequest | TeacherDashboard | 50055 |
| AnalyticsService | GetStudentDashboard | GetStudentDashboardRequest | StudentDashboard | 50055 |
| AnalyticsService | GetParentDashboard | GetParentDashboardRequest | ParentDashboard | 50055 |
| AnalyticsService | GetAdminDashboard | GetAdminDashboardRequest | AdminDashboard | 50055 |
| AnalyticsService | GetWarningList | GetWarningListRequest | WarningListResponse | 50055 |
| AnalyticsService | TriggerWarning | TriggerWarningRequest | TriggerWarningResponse | 50055 |
| AnalyticsService | GetMasteryDistribution | GetMasteryDistributionRequest | MasteryDistribution | 50055 |
| AnalyticsService | GetStudentMastery | GetStudentMasteryRequest | StudentMastery | 50055 |
| AnalyticsService | SubscribeMasteryUpdate | SubscribeMasteryUpdateRequest | stream MasteryUpdateEvent | 50055 |
### 1.2 HTTP 端点（如有）
无对外 HTTP 端点，仅 gRPC（含 1 个 Server Streaming RPC）。
### 1.3 GraphQL schema（如 BFF）
不适用。
### 1.4 Kafka 事件发布（如有）
| Topic | Event | 消费方 |
| --------------------------- | --------------------------------------------------------- | -------------- |
| edu.data_ana.mastery.events | MasteryEvent（action: mastery.updated/warning.triggered） | core-edu / msg |
> 注：MasteryEvent 豁免 Outbox 模式（派生数据事件，见 004 §12.2 + §15.3 #6）。
### 1.5 错误码前缀
`DATA_ANA_`（如 DATA_ANA_DASHBOARD_UNAVAILABLE、DATA_ANA_MASTERY_NOT_COMPUTED）
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
无主动 gRPC 调用上游。data-ana 通过 CDC + Kafka 事件接收数据，计算后发布 MasteryEvent。
### 2.2 Kafka 事件订阅（异步）
| Topic | Event | 发布方 | mock 策略 |
| ---------------------------------- | ------------------- | --------------- | ------------------------------------------------- |
| edu.exam.events | ExamEvent | core-edu (ai08) | core-edu 就绪前使用 CDC 模拟数据 + 本地 stub 事件 |
| edu.homework.events | HomeworkEvent | core-edu (ai08) | 同上 |
| edu.grade.events | GradeEvent | core-edu (ai08) | 同上 |
| edu.class.events | ClassEvent | core-edu (ai08) | 同上 |
| edu.content.knowledge_point.events | KnowledgePointEvent | content (ai09) | content 就绪前使用内置知识点维度表 |
| edu.content.question.events | QuestionEvent | content (ai09) | content 就绪前忽略 |
| edu.ai.usage.events | AIUsageEvent | ai (ai12) | ai 就绪前忽略，AI 用量统计为空 |
### 2.3 HTTP 调用（如有）
无。
### 2.4 CDC 数据源（补充）
| 数据源 | 用途 | mock 策略 |
| ----------------------------------------------------- | ------------------------------- | --------------------------------------------------------------------------- |
| core-edu MySQL（exams/homework/grades/attendance 表） | Debezium CDC → Kafka 同步读模型 | core-edu 就绪前使用 ClickHouse 内置模拟数据集（30 学生 × 5 考试 × 10 作业） |
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] core-edu gRPC 50053 启用（ai08）—— 业务事件 + CDC 数据源
- [ ] edu.exam.events / edu.homework.events / edu.grade.events / edu.class.events topic 有事件发布（ai08）
- [ ] content gRPC 50054 启用（ai09）—— 知识点维度
- [ ] edu.content.knowledge_point.events topic 有事件发布（ai09）
- [ ] ai gRPC 50057 启用（ai12）—— AI 用量统计（可选，仪表盘补全）
### 3.2 我的就绪标志（供下游消费）
- [ ] data-ana gRPC 50055 启用（HealthService.Check 返回 SERVING）
- [ ] AnalyticsService 12 RPC 可调用（含 4 端 Dashboard + Server Streaming SubscribeMasteryUpdate）
- [ ] GetTeacherDashboard / GetStudentDashboard / GetParentDashboard / GetAdminDashboard 返回结构化数据
- [ ] edu.data_ana.mastery.events topic 可发布（mastery.updated / warning.triggered）
---
## §4 Mock 策略
### 4.1 我提供的 mock
在 data-ana 真实服务就绪前，为下游（teacher-bff / student-bff / parent-bff / admin-portal / msg）提供以下 mock：
- **gRPC mock**：使用 grpc-mock 拦截 50055 端口
- GetTeacherDashboard 返回固定仪表盘（total_classes=3, class_avg_score=82.5, top_students 5 个, pending_homework_count=8）
- GetStudentDashboard 返回固定仪表盘（avg_score=85.0, class_rank=5, weak_points 3 个）
- GetParentDashboard 返回固定仪表盘（child_avg_score=85.0, child_class_rank=5）
- GetAdminDashboard 返回固定仪表盘（total_teachers=50, total_students=1200, school_avg_score=80.0）
- GetWarningList 返回固定 5 条预警（severity: warning/critical）
- GetMasteryDistribution 返回固定分布（mastered=20, progressing=7, weak=3）
- SubscribeMasteryUpdate 返回固定流（每 5 秒推 1 个 MasteryUpdateEvent）
- **Kafka mock**：data-ana 就绪前不发布真实 MasteryEvent，msg 使用本地 stub 预警
### 4.2 我消费的 mock
在真实上游就绪前，data-ana 使用以下 mock：
- 业务数据：ClickHouse 内置模拟数据集（30 学生 × 5 考试 × 10 作业 × 30 天出勤），不依赖 core-edu CDC
- 知识点维度：内置固定知识点表（数学 50 个知识点），不依赖 content 事件
- AI 用量：AIUsageEvent 为空，仪表盘 AI 用量区块显示"暂无数据"
- CDC 通道：core-edu 就绪前 Debezium 不启动，使用 ClickHouse 批量导入模拟数据

95
docs/architecture/issues/contracts/iam_contract.md Normal file
View File

@@ -0,0 +1,95 @@
# iam 对接契约
> 负责人：ai06
> 关联：[matrix.md](./matrix.md)、[iam.proto](../../../packages/shared-proto/proto/iam.proto)、[events.proto](../../../packages/shared-proto/proto/events.proto)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
| Service | RPC | 请求 | 响应 | 端口 |
| ---------- | ----------------------- | ------------------------------ | ---------------------------- | ----- |
| IamService | Register | RegisterRequest | AuthResponse | 50052 |
| IamService | Login | LoginRequest | AuthResponse | 50052 |
| IamService | RefreshToken | RefreshTokenRequest | TokenPair | 50052 |
| IamService | Logout | LogoutRequest | LogoutResponse | 50052 |
| IamService | GetUserInfo | GetUserInfoRequest | UserInfo | 50052 |
| IamService | BatchGetUsers | BatchGetUsersRequest | BatchGetUsersResponse | 50052 |
| IamService | GetEffectivePermissions | GetEffectivePermissionsRequest | EffectivePermissionsResponse | 50052 |
| IamService | GetEffectiveAccess | GetEffectiveAccessRequest | EffectiveAccessResponse | 50052 |
| IamService | GetEffectiveDataScope | GetEffectiveDataScopeRequest | DataScopeResponse | 50052 |
| IamService | GetViewports | GetViewportsRequest | ViewportsResponse | 50052 |
| IamService | GetPublicKey | GetPublicKeyRequest | PublicKeyResponse | 50052 |
| IamService | GetChildrenByParent | GetChildrenByParentRequest | ChildrenResponse | 50052 |
### 1.2 HTTP 端点（如有）
无对外 HTTP 端点，仅 gRPC。
### 1.3 GraphQL schema（如 BFF）
不适用。
### 1.4 Kafka 事件发布（如有）
| Topic | Event | 消费方 |
| --------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------- |
| edu.iam.user.events | UserEvent（action: created/updated/deleted/role_changed） | core-edu / msg / push-gateway / teacher-bff / student-bff |
| edu.iam.role.events | RoleEvent（action: created/updated） | core-edu / teacher-bff |
| edu.iam.audit.created | AuditEvent（action: create/update/delete/login/logout/permission_change） | admin-portal |
### 1.5 错误码前缀
`IAM_`（如 IAM_UNAUTHORIZED、IAM_USER_NOT_FOUND、IAM_PERMISSION_DENIED）
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
无。iam 是身份根服务，不依赖其他业务服务。
### 2.2 Kafka 事件订阅（异步）
无。
### 2.3 HTTP 调用（如有）
无。
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
无上游依赖。
### 3.2 我的就绪标志（供下游消费）
- [ ] iam gRPC 50052 启用（HealthService.Check 返回 SERVING）
- [ ] IamService.Register/Login/RefreshToken/Logout 可调用（返回 AuthResponse/TokenPair）
- [ ] IamService.GetPublicKey 可用（返回 RS256 PEM 公钥，供 api-gateway 验签）
- [ ] IamService.GetChildrenByParent 可用（供 parent-bff 查孩子列表）
- [ ] edu.iam.user.events / edu.iam.role.events / edu.iam.audit.created topic 可发布
- [ ] JWT RS256 签发链路打通（access_token + refresh_token）
---
## §4 Mock 策略
### 4.1 我提供的 mock
在 iam 真实服务就绪前，为下游（api-gateway / 各 BFF）提供以下 mock：
- **gRPC mock**：使用 grpc-mock 拦截 50052 端口，Register/Login 返回固定 AuthResponse（user.id="mock-user-001", tokens.access_token="mock-access-token"）
- **GetPublicKey mock**：返回固定 RS256 公钥 PEM（与 mock 私钥配对），供 api-gateway 验签 mock JWT
- **GetChildrenByParent mock**：返回固定 ChildInfo 列表（2 个孩子）
- **Kafka mock**：iam 服务就绪前不发布真实事件，下游订阅方使用本地 stub
### 4.2 我消费的 mock
不适用（无上游依赖）。

110
docs/architecture/issues/contracts/msg_contract.md Normal file
View File

@@ -0,0 +1,110 @@
# msg 对接契约
> 负责人：ai10
> 关联：[matrix.md](./matrix.md)、[msg.proto](../../../packages/shared-proto/proto/msg.proto)、[events.proto](../../../packages/shared-proto/proto/events.proto)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
| Service | RPC | 请求 | 响应 | 端口 |
| ----------------------------- | ---------------------- | ----------------------------- | --------------------------- | ----- |
| NotificationService | SendNotification | SendNotificationRequest | Notification | 50056 |
| NotificationService | ListNotifications | ListNotificationsRequest | ListNotificationsResponse | 50056 |
| NotificationService | MarkAsRead | MarkAsReadRequest | MarkAsReadResponse | 50056 |
| NotificationService | SearchNotifications | SearchNotificationsRequest | SearchNotificationsResponse | 50056 |
| NotificationService | RecallNotification | RecallNotificationRequest | RecallNotificationResponse | 50056 |
| NotificationPreferenceService | GetPreference | GetPreferenceRequest | NotificationPreference | 50056 |
| NotificationPreferenceService | UpdatePreference | UpdatePreferenceRequest | NotificationPreference | 50056 |
| NotificationPreferenceService | GetPreferenceByChannel | GetPreferenceByChannelRequest | ChannelPreference | 50056 |
| NotificationPreferenceService | ListPreferences | ListPreferencesRequest | ListPreferencesResponse | 50056 |
| NotificationTemplateService | CreateTemplate | CreateTemplateRequest | NotificationTemplate | 50056 |
| NotificationTemplateService | GetTemplate | GetTemplateRequest | NotificationTemplate | 50056 |
| NotificationTemplateService | ListTemplates | ListTemplatesRequest | ListTemplatesResponse | 50056 |
| NotificationTemplateService | RenderTemplate | RenderTemplateRequest | RenderedTemplate | 50056 |
### 1.2 HTTP 端点（如有）
无对外 HTTP 端点，仅 gRPC。
### 1.3 GraphQL schema（如 BFF）
不适用。
### 1.4 Kafka 事件发布（如有）
| Topic | Event | 消费方 |
| --------------------------- | ------------------------------------------------------ | ----------------------- |
| edu.msg.notification.events | NotificationEvent（action: sent/read/recalled/failed） | push-gateway / data-ana |
### 1.5 错误码前缀
`MSG_`（如 MSG_TEMPLATE_NOT_FOUND、MSG_CHANNEL_DISABLED、MSG_RATE_LIMITED）
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
无主动 gRPC 调用上游。msg 通过 Kafka 事件被动接收业务事件后触发通知。
### 2.2 Kafka 事件订阅（异步）
| Topic | Event | 发布方 | mock 策略 |
| --------------------------- | --------------------------------------------------------- | --------------- | ------------------------------------------------------- |
| edu.iam.user.events | UserEvent | iam (ai06) | iam 就绪前使用本地用户偏好默认值 |
| edu.exam.events | ExamEvent（action: created/updated/deleted） | core-edu (ai08) | core-edu 就绪前不订阅，使用本地 stub 事件触发 mock 通知 |
| edu.homework.events | HomeworkEvent（action: assigned/submitted/graded） | core-edu (ai08) | 同上 |
| edu.grade.events | GradeEvent（action: recorded/updated） | core-edu (ai08) | 同上 |
| edu.class.events | ClassEvent（action: transferred） | core-edu (ai08) | 同上 |
| edu.data_ana.mastery.events | MasteryEvent（action: mastery.updated/warning.triggered） | data-ana (ai11) | data-ana 就绪前不订阅，预警通知使用本地 stub |
### 2.3 HTTP 调用（如有）
无。
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] iam gRPC 50052 启用（ai06）—— 用于用户通知偏好查询（可选）
- [ ] core-edu gRPC 50053 启用（ai08）—— 业务事件来源
- [ ] edu.exam.events / edu.homework.events / edu.grade.events / edu.class.events topic 有事件发布（ai08）
- [ ] data-ana gRPC 50055 启用（ai11）—— 预警事件来源
- [ ] edu.data_ana.mastery.events topic 有事件发布（ai11）
### 3.2 我的就绪标志（供下游消费）
- [ ] msg gRPC 50056 启用（HealthService.Check 返回 SERVING）
- [ ] NotificationService 5 RPC 可调用
- [ ] NotificationPreferenceService 4 RPC 可调用
- [ ] NotificationTemplateService 4 RPC 可调用（含 RenderTemplate 模板渲染）
- [ ] edu.msg.notification.events topic 可发布（供 push-gateway 推送）
---
## §4 Mock 策略
### 4.1 我提供的 mock
在 msg 真实服务就绪前，为下游（teacher-bff / student-bff / parent-bff / push-gateway）提供以下 mock：
- **gRPC mock**：使用 grpc-mock 拦截 50056 端口
- NotificationService.ListNotifications 返回固定 10 条未读通知
- NotificationService.MarkAsRead 返回 success=true
- NotificationPreferenceService.GetPreference 返回默认偏好（in_app+email 开启，sms+push 关闭）
- NotificationTemplateService.RenderTemplate 返回固定 title+content
- **Kafka mock**：msg 就绪前不发布真实 NotificationEvent，push-gateway 使用本地 stub 推送
### 4.2 我消费的 mock
在真实上游就绪前，msg 使用以下 mock：
- 业务事件：core-edu/data-ana 就绪前，msg 内置定时器发布本地 stub 事件（ExamEvent/HomeworkEvent），触发 mock 通知流程
- 用户偏好：iam 就绪前使用默认偏好（所有用户 in_app 开启）
- 模板渲染：内置 5 个常用模板（exam.created / homework.assigned / grade.recorded / warning.triggered / system.notice）

121
docs/architecture/issues/contracts/parent-bff_contract.md Normal file
View File

@@ -0,0 +1,121 @@
# parent-bff 对接契约
> 负责人：ai05
> 关联：[matrix.md](./matrix.md)、[iam.proto](../../../packages/shared-proto/proto/iam.proto)、[core_edu.proto](../../../packages/shared-proto/proto/core_edu.proto)、[analytics.proto](../../../packages/shared-proto/proto/analytics.proto)、[msg.proto](../../../packages/shared-proto/proto/msg.proto)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
无对外 gRPC。parent-bff 是 GraphQL 聚合层。
### 1.2 HTTP 端点（如有）
| Method | Path | 用途 | 认证 |
| ------ | -------- | ----------------------------------------- | ---------------------- |
| POST | /graphql | 家长 BFF GraphQL 端点 | JWT 必需 + parent 角色 |
| GET | /graphql | GraphQL Playground（开发环境） | 开发环境公开 |
| GET | /healthz | 健康检查（liveness） | 公开 |
| GET | /readyz | 就绪检查（readiness，含下游 gRPC 连通性） | 公开 |
### 1.3 GraphQL schema（如 BFF）
GraphQL schema 文件路径：`apps/parent-bff/src/schema/*.graphql`（端口 :3010）
核心 Query / Mutation 域：
- **auth**：currentUser（聚合 iam.GetUserInfo + GetEffectivePermissions + GetViewports）
- **children**：myChildren（聚合 iam.GetChildrenByParent，核心依赖 I3 裁决）
- **childSummary**：childSummary（聚合 data-ana.AnalyticsService.GetParentDashboard）
- **childGrades**：childGrades（聚合 core-edu.GradeService.ListGradesByStudent）
- **childAttendance**：childAttendance（聚合 core-edu.AttendanceService.ListAttendanceByStudent）
- **childHomework**：childHomework（聚合 core-edu.HomeworkService.ListHomeworkByClass）
- **childWeakness**：childWeakness（聚合 data-ana.AnalyticsService.GetStudentWeakness）
- **childTrend**：childTrend（聚合 data-ana.AnalyticsService.GetLearningTrend）
- **notifications**：myNotifications / markAsRead（聚合 msg.NotificationService）
### 1.4 Kafka 事件发布（如有）
无。parent-bff 不发布事件，仅做 gRPC 聚合。
### 1.5 错误码前缀
`BFF_PARENT_`（如 BFF_PARENT_UPSTREAM_UNAVAILABLE、BFF_PARENT_AGGREGATION_FAILED、BFF_PARENT_NO_CHILDREN、BFF_PARENT_FORBIDDEN）
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
| 被调用方 | Service.RPC | 用途 | mock 策略 |
| --------------- | ----------------------------------------- | ------------------------ | ------------------------------------------------------ |
| iam (ai06) | IamService.GetUserInfo | 获取当前家长信息 | iam 就绪前返回固定 UserInfo（parent 角色） |
| iam (ai06) | IamService.GetEffectivePermissions | 权限校验 | iam 就绪前返回家长权限集 |
| iam (ai06) | IamService.GetViewports | 家长导航菜单 | iam 就绪前返回固定视口列表 |
| iam (ai06) | IamService.GetChildrenByParent | 查询关联孩子列表（核心） | iam 就绪前返回固定 2 个 ChildInfo（I3/ISSUE-047 裁决） |
| core-edu (ai08) | GradeService.ListGradesByStudent | 孩子成绩 | core-edu 就绪前返回固定 5 个 Grade |
| core-edu (ai08) | AttendanceService.ListAttendanceByStudent | 孩子考勤 | core-edu 就绪前返回固定 10 条 Attendance |
| core-edu (ai08) | HomeworkService.ListHomeworkByClass | 孩子作业 | core-edu 就绪前返回固定 3 个 Homework |
| data-ana (ai11) | AnalyticsService.GetParentDashboard | 家长仪表盘 | data-ana 就绪前返回固定仪表盘（child_avg_score=85.0） |
| data-ana (ai11) | AnalyticsService.GetStudentWeakness | 孩子薄弱点 | data-ana 就绪前返回固定 3 个 weak_points |
| data-ana (ai11) | AnalyticsService.GetLearningTrend | 孩子学习趋势 | data-ana 就绪前返回固定趋势数据 |
| msg (ai10) | NotificationService.ListNotifications | 家长通知 | msg 就绪前返回固定 10 条通知 |
| msg (ai10) | NotificationService.MarkAsRead | 标记已读 | msg 就绪前返回 success=true |
### 2.2 Kafka 事件订阅（异步）
无。parent-bff 不订阅 Kafka 事件，仅做同步 gRPC 聚合。
### 2.3 HTTP 调用（如有）
无。
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] iam gRPC 50052 启用（ai06）—— **核心依赖 GetChildrenByParent（I3/ISSUE-047 裁决）**
- [ ] core-edu gRPC 50053 启用（ai08）
- [ ] data-ana gRPC 50055 启用（ai11）
- [ ] msg gRPC 50056 启用（ai10）
### 3.2 我的就绪标志（供下游消费）
- [ ] parent-bff GraphQL :3010 启用（/healthz 返回 200）
- [ ] /readyz 返回 200（含 4 个下游 gRPC 连通性检查）
- [ ] GraphQL schema 可内省（POST /graphql 返回 schema）
- [ ] 核心 Query 可执行：currentUser / myChildren / childSummary / childGrades
- [ ] 核心 Mutation 可执行：markAsRead
- [ ] 数据范围校验生效（家长只能查自己孩子的数据，基于 iam.GetChildrenByParent 返回的 user_id 校验）
---
## §4 Mock 策略
### 4.1 我提供的 mock
在 parent-bff 真实就绪前，为下游（parent-portal）提供以下 mock：
- **GraphQL mock**：使用 Apollo Server mockProviders 或 MSW 拦截 POST /graphql
- currentUser 返回固定家长（id="parent-001", name="王家长", roles=["parent"]）
- myChildren 返回固定 2 个孩子（id="student-001" 李同学 + id="student-002" 李妹妹）
- childSummary 返回固定仪表盘（child_avg_score=85.0, child_class_rank=5）
- childGrades 返回固定 5 个成绩
- childAttendance 返回固定 10 条考勤
- myNotifications 返回固定 10 条通知
### 4.2 我消费的 mock
在真实上游就绪前，parent-bff 使用以下 mock（详见 §2.1 mock 策略列）：
- **iam mock**：固定 UserInfo + 家长权限 + 固定视口 + 固定 2 个 ChildInfo（家长-学生关联核心数据）
- **core-edu mock**：固定孩子成绩/考勤/作业
- **data-ana mock**：固定家长仪表盘/孩子薄弱点/趋势
- **msg mock**：固定通知列表 + MarkAsRead success
> 关键：iam.GetChildrenByParent 的 mock 必须返回与 core-edu mock 数据一致的 student_id，否则数据范围校验会失败。parent-bff 启动时校验 myChildren 返回的 user_id 与下游查询的 student_id 一致性。

124
docs/architecture/issues/contracts/parent-portal_contract.md Normal file
View File

@@ -0,0 +1,124 @@
# parent-portal 对接契约
> 负责人：ai15
> 关联：[matrix.md](./matrix.md)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
无。parent-portal 是前端微前端 Remote。
### 1.2 HTTP 端点（如有）
| Method | Path | 用途 | 认证 |
| ------ | --------------------- | ------------ | ------------------------------------- |
| GET | / | 家长门户首页 | JWT 必需（前端路由守卫） |
| GET | /children | 我的孩子列表 | JWT 必需 |
| GET | /child/:id/summary | 孩子概况 | JWT 必需 + 数据范围校验（仅自己孩子） |
| GET | /child/:id/grades | 孩子成绩 | JWT 必需 + 数据范围校验 |
| GET | /child/:id/attendance | 孩子考勤 | JWT 必需 + 数据范围校验 |
| GET | /child/:id/homework | 孩子作业 | JWT 必需 + 数据范围校验 |
| GET | /child/:id/weakness | 孩子薄弱点 | JWT 必需 + 数据范围校验 |
| GET | /notifications | 通知中心 | JWT 必需 |
### 1.3 GraphQL schema（如 BFF）
不适用。parent-portal 消费 parent-bff GraphQL，自身不提供 schema。
### 1.4 Kafka 事件发布（如有）
无。
### 1.5 错误码前缀
无（前端不定义错误码前缀，透传 BFF 错误码）。
### 1.6 微前端架构（补充）
| 角色 | 说明 |
| ---------------------- | ------------------------------------------------ |
| MF Remote | 家长门户是微前端远程模块 |
| 暴露的 remote 模块 | ParentApp（家长端完整应用）、shared 家长端组件 |
| module federation 配置 | `apps/parent-portal/module-federation.config.ts` |
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
无。前端不直接调 gRPC。
### 2.2 Kafka 事件订阅（异步）
无。前端不直接订阅 Kafka。
### 2.3 HTTP 调用（如有）
| 被调用方 | Method.Path | 用途 | mock 策略 |
| ------------------- | ------------------------ | -------------------------------------------- | ---------------------------------------------------------------- |
| api-gateway (ai01) | POST /api/parent/graphql | 家长 GraphQL 查询（经网关代理到 parent-bff） | api-gateway/parent-bff 就绪前使用 MSW 拦截返回 mock GraphQL 响应 |
| api-gateway (ai01) | POST /api/auth/login | 家长登录 | api-gateway 就绪前使用 MSW 返回固定 JWT |
| push-gateway (ai02) | GET /ws | WebSocket 实时通知 | push-gateway 就绪前使用 mock-socket 模拟 WS 推送 |
### 2.4 GraphQL 查询域（经 api-gateway 代理到 parent-bff）
| Query/Mutation | 用途 | mock 策略 |
| ---------------------------- | -------------------- | ----------------------------- |
| currentUser | 当前家长信息 | MSW 返回固定家长 |
| myChildren | 我的孩子列表（核心） | MSW 返回固定 2 个孩子 |
| childSummary | 孩子概况 | MSW 返回固定仪表盘 |
| childGrades | 孩子成绩 | MSW 返回固定 5 个成绩 |
| childAttendance | 孩子考勤 | MSW 返回固定 10 条考勤 |
| childHomework | 孩子作业 | MSW 返回固定 3 个作业 |
| childWeakness | 孩子薄弱点 | MSW 返回固定 3 个 weak_points |
| childTrend | 孩子学习趋势 | MSW 返回固定趋势数据 |
| myNotifications / markAsRead | 通知中心 | MSW 返回固定通知 |
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] api-gateway HTTP :8080 启用（ai01）—— 前端请求入口
- [ ] parent-bff GraphQL :3010 启用（ai05）—— 数据来源
- [ ] push-gateway WebSocket :8081/ws 启用（ai02）—— 实时通知
### 3.2 我的就绪标志（供下游消费）
- [ ] parent-portal dev server :4002 启用
- [ ] MF Remote 可被 AppShell 加载（暴露 ParentApp 模块）
- [ ] 独立壳渲染（首页 + 导航 + 路由守卫）
- [ ] 登录流程可用（POST /api/auth/login 获取 JWT 存入 cookie）
- [ ] GraphQL 查询可执行（currentUser / myChildren / childSummary 返回数据）
- [ ] 数据范围校验生效（前端路由守卫校验 child:id 是否在 myChildren 返回列表中）
- [ ] WebSocket 通知可接收
---
## §4 Mock 策略
### 4.1 我提供的 mock
parent-portal 是前端，无下游消费方。但对开发体验提供：
- **Storybook**：各组件独立 story
- **MSW handlers**：`apps/parent-portal/src/mocks/handlers.ts`，拦截所有 GraphQL/HTTP 请求
### 4.2 我消费的 mock
在真实上游就绪前，parent-portal 使用以下 mock：
- **HTTP/GraphQL mock**：使用 MSW 拦截所有请求
- POST /api/auth/login → 返回固定 JWT + UserInfo（parent 角色）
- POST /api/parent/graphql → 根据 operationName 返回对应 mock 响应（与 parent-bff mock 数据一致）
- myChildren mock 必须返回固定 2 个孩子（id="student-001" + "student-002"），与其他 child* 查询的 student_id 一致
- 所有 mock 响应定义在 `apps/parent-portal/src/mocks/fixtures/*.json`
- **WebSocket mock**：使用 mock-socket 库
- 连接后每 30 秒推送 1 条 mock 通知
- **JWT mock**：使用固定 mock JWT，存入 httpOnly cookie
- **环境切换**：通过 `NEXT_PUBLIC_API_MOCKING=enabled` 环境变量控制，上游就绪后设为 `disabled`

101
docs/architecture/issues/contracts/push-gateway_contract.md Normal file
View File

@@ -0,0 +1,101 @@
# push-gateway 对接契约
> 负责人：ai02
> 关联：[matrix.md](./matrix.md)、[msg.proto](../../../packages/shared-proto/proto/msg.proto)、[events.proto](../../../packages/shared-proto/proto/events.proto)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
无对外 gRPC。push-gateway 是 WebSocket/SSE 推送入口。
### 1.2 HTTP 端点（如有）
| Method | Path | 用途 | 认证 |
| ------ | ------------------- | -------------------------------------- | -------------------------------- |
| GET | /ws | WebSocket 升级端点（实时推送通知） | JWT 必需（query param 传 token） |
| GET | /sse | SSE 推送端点（备选实时通道） | JWT 必需 |
| POST | /internal/broadcast | 内部广播接口（msg 服务触发） | 内网 mTLS |
| POST | /internal/send | 内部单推接口（msg 服务触发） | 内网 mTLS |
| GET | /healthz | 健康检查（liveness） | 公开 |
| GET | /readyz | 就绪检查（readiness，含 Kafka 连通性） | 公开 |
| GET | /metrics | Prometheus 指标端点 | 公开（内网） |
### 1.3 GraphQL schema（如 BFF）
不适用。
### 1.4 Kafka 事件发布（如有）
无。push-gateway 不发布事件，仅消费事件触发推送。
### 1.5 错误码前缀
`PUSH_`（如 PUSH_CONNECTION_FAILED、PUSH_CHANNEL_CLOSED、PUSH_AUTH_INVALID）
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
无主动 gRPC 调用上游。
### 2.2 Kafka 事件订阅（异步）
| Topic | Event | 发布方 | mock 策略 |
| --------------------------- | --------------------------------- | ---------- | --------------------------------------------------------------------------- |
| edu.msg.notification.events | NotificationEvent（action: sent） | msg (ai10) | msg 就绪前不订阅，使用本地定时器每 30 秒推送 1 条 mock 通知到所有连接客户端 |
### 2.3 HTTP 调用（如有）
无。
### 2.4 内部接口（msg 调用 push-gateway）
| 被调用方 | Method.Path | 用途 | 说明 |
| ------------ | ------------------------ | ------------------ | ---------------------------------------- |
| push-gateway | POST /internal/broadcast | msg 服务批量推送 | msg 收到业务事件后渲染模板，调此接口广播 |
| push-gateway | POST /internal/send | msg 服务单用户推送 | msg 渲染后定向推送给目标用户 |
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] msg gRPC 50056 启用（ai10）—— 通知事件来源
- [ ] edu.msg.notification.events topic 有事件发布（ai10）
- [ ] iam gRPC 50052 启用（ai06）—— WebSocket 连接时 JWT 验签（可选，push-gateway 可独立验签）
### 3.2 我的就绪标志（供下游消费）
- [ ] push-gateway HTTP :8081 启用（/healthz 返回 200）
- [ ] /readyz 返回 200（含 Kafka 连通性检查通过）
- [ ] WebSocket /ws 端点可升级连接（JWT 鉴权后建立长连接）
- [ ] SSE /sse 端点可建立 EventStream
- [ ] /internal/broadcast + /internal/send 接收 msg 推送并下发到在线客户端
- [ ] Kafka consumer edu.msg.notification.events 订阅成功
---
## §4 Mock 策略
### 4.1 我提供的 mock
在 push-gateway 真实就绪前，为下游（各前端 portal）提供以下 mock：
- **WebSocket mock**：前端开发期使用 mock-socket 库模拟 WS 连接
- 连接成功后每 30 秒推送 1 条 mock 通知（type="system", title="测试通知"）
- **SSE mock**：前端使用 EventSource polyfill，本地定时推送 mock 事件
- **HTTP mock**：/internal/* 接口返回 200 success
### 4.2 我消费的 mock
在真实上游就绪前，push-gateway 使用以下 mock：
- **NotificationEvent mock**：msg 就绪前，push-gateway 内置定时器每 30 秒生成 1 条 mock NotificationEvent（action=sent），推送到所有在线客户端
- **JWT 验签**：iam 就绪前使用本地固定 mock RS256 公钥验签 WebSocket 连接的 token
- **Kafka 订阅**：msg 就绪前不启动 Kafka consumer，使用本地定时器替代

130
docs/architecture/issues/contracts/student-bff_contract.md Normal file
View File

@@ -0,0 +1,130 @@
# student-bff 对接契约
> 负责人：ai04
> 关联：[matrix.md](./matrix.md)、[iam.proto](../../../packages/shared-proto/proto/iam.proto)、[core_edu.proto](../../../packages/shared-proto/proto/core_edu.proto)、[content.proto](../../../packages/shared-proto/proto/content.proto)、[analytics.proto](../../../packages/shared-proto/proto/analytics.proto)、[msg.proto](../../../packages/shared-proto/proto/msg.proto)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
无对外 gRPC。student-bff 是 GraphQL 聚合层。
### 1.2 HTTP 端点（如有）
| Method | Path | 用途 | 认证 |
| ------ | -------- | ----------------------------------------- | ----------------------- |
| POST | /graphql | 学生 BFF GraphQL 端点 | JWT 必需 + student 角色 |
| GET | /graphql | GraphQL Playground（开发环境） | 开发环境公开 |
| GET | /healthz | 健康检查（liveness） | 公开 |
| GET | /readyz | 就绪检查（readiness，含下游 gRPC 连通性） | 公开 |
### 1.3 GraphQL schema（如 BFF）
GraphQL schema 文件路径：`apps/student-bff/src/schema/*.graphql`（端口 :3009）
核心 Query / Mutation 域：
- **auth**：currentUser（聚合 iam.GetUserInfo + GetEffectivePermissions + GetViewports）
- **myClasses**：我的班级（聚合 core-edu.ClassService.GetClass + ListStudentsByClass）
- **myExams**：我的考试列表（聚合 core-edu.ExamService.ListExamsByClass）
- **myHomework**：我的作业（聚合 core-edu.HomeworkService.ListHomeworkByClass + SubmitHomework）
- **myGrades**：我的成绩（聚合 core-edu.GradeService.ListGradesByStudent）
- **myAttendance**：我的考勤（聚合 core-edu.AttendanceService.ListAttendanceByStudent）
- **content**：textbooks / chapters / learningPath（聚合 content.KnowledgeGraphService.GetLearningPath）
- **dashboard**：studentDashboard（聚合 data-ana.AnalyticsService.GetStudentDashboard）
- **weakness**：myWeakness（聚合 data-ana.AnalyticsService.GetStudentWeakness）
- **trend**：myTrend（聚合 data-ana.AnalyticsService.GetLearningTrend）
- **notifications**：myNotifications / markAsRead（聚合 msg.NotificationService）
### 1.4 Kafka 事件发布（如有）
无。student-bff 不发布事件，仅做 gRPC 聚合。
### 1.5 错误码前缀
`BFF_STUDENT_`（如 BFF_STUDENT_UPSTREAM_UNAVAILABLE、BFF_STUDENT_AGGREGATION_FAILED、BFF_STUDENT_FORBIDDEN）
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
| 被调用方 | Service.RPC | 用途 | mock 策略 |
| --------------- | ----------------------------------------- | ---------------- | ------------------------------------------- |
| iam (ai06) | IamService.GetUserInfo | 获取当前学生信息 | iam 就绪前返回固定 UserInfo（student 角色） |
| iam (ai06) | IamService.GetEffectivePermissions | 权限校验 | iam 就绪前返回学生权限集 |
| iam (ai06) | IamService.GetViewports | 学生导航菜单 | iam 就绪前返回固定视口列表 |
| core-edu (ai08) | ClassService.GetClass | 我的班级详情 | core-edu 就绪前返回固定 ClassInfo |
| core-edu (ai08) | ClassService.ListStudentsByClass | 班级同学名单 | core-edu 就绪前返回固定 30 个 StudentInfo |
| core-edu (ai08) | ExamService.ListExamsByClass | 我的考试 | core-edu 就绪前返回固定 2 个 Exam |
| core-edu (ai08) | HomeworkService.ListHomeworkByClass | 我的作业 | core-edu 就绪前返回固定 3 个 Homework |
| core-edu (ai08) | HomeworkService.SubmitHomework | 提交作业 | core-edu 就绪前返回 success=true |
| core-edu (ai08) | GradeService.ListGradesByStudent | 我的成绩 | core-edu 就绪前返回固定 5 个 Grade |
| core-edu (ai08) | AttendanceService.ListAttendanceByStudent | 我的考勤 | core-edu 就绪前返回固定 10 条 Attendance |
| content (ai09) | TextbookService.ListTextbooks | 教材列表 | content 就绪前返回固定 5 个教材 |
| content (ai09) | ChapterService.ListChapters | 章节列表 | content 就绪前返回固定章节树 |
| content (ai09) | KnowledgeGraphService.GetLearningPath | 学习路径 | content 就绪前返回固定 8 个知识点推荐顺序 |
| data-ana (ai11) | AnalyticsService.GetStudentDashboard | 学生仪表盘 | data-ana 就绪前返回固定仪表盘 |
| data-ana (ai11) | AnalyticsService.GetStudentWeakness | 我的薄弱点 | data-ana 就绪前返回固定 3 个 weak_points |
| data-ana (ai11) | AnalyticsService.GetLearningTrend | 学习趋势 | data-ana 就绪前返回固定趋势数据 |
| msg (ai10) | NotificationService.ListNotifications | 学生通知 | msg 就绪前返回固定 10 条通知 |
| msg (ai10) | NotificationService.MarkAsRead | 标记已读 | msg 就绪前返回 success=true |
### 2.2 Kafka 事件订阅（异步）
无。student-bff 不订阅 Kafka 事件，仅做同步 gRPC 聚合。
### 2.3 HTTP 调用（如有）
无。
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] iam gRPC 50052 启用（ai06）
- [ ] core-edu gRPC 50053 启用（ai08）
- [ ] content gRPC 50054 启用（ai09）
- [ ] data-ana gRPC 50055 启用（ai11）
- [ ] msg gRPC 50056 启用（ai10）
### 3.2 我的就绪标志（供下游消费）
- [ ] student-bff GraphQL :3009 启用（/healthz 返回 200）
- [ ] /readyz 返回 200（含 5 个下游 gRPC 连通性检查）
- [ ] GraphQL schema 可内省（POST /graphql 返回 schema）
- [ ] 核心 Query 可执行：currentUser / myClasses / studentDashboard / myGrades
- [ ] 核心 Mutation 可执行：submitHomework / markAsRead
---
## §4 Mock 策略
### 4.1 我提供的 mock
在 student-bff 真实就绪前，为下游（student-portal）提供以下 mock：
- **GraphQL mock**：使用 Apollo Server mockProviders 或 MSW 拦截 POST /graphql
- currentUser 返回固定学生（id="student-001", name="李同学", roles=["student"]）
- myClasses 返回固定 1 个班级
- studentDashboard 返回固定仪表盘（avg_score=85.0, class_rank=5）
- myGrades 返回固定 5 个成绩
- myHomework 返回固定 3 个作业（1 个待提交）
- myNotifications 返回固定 10 条通知
### 4.2 我消费的 mock
在真实上游就绪前，student-bff 使用以下 mock（详见 §2.1 mock 策略列）：
- **iam mock**：固定 UserInfo + 学生权限 + 固定视口
- **core-edu mock**：固定班级/同学/考试/作业/成绩/考勤
- **content mock**：固定教材/章节/学习路径
- **data-ana mock**：固定仪表盘/薄弱点/趋势
- **msg mock**：固定通知列表 + MarkAsRead success
> 所有上游 mock 通过 gRPC client 拦截器实现，上游就绪后移除拦截器切换真实调用。

125
docs/architecture/issues/contracts/student-portal_contract.md Normal file
View File

@@ -0,0 +1,125 @@
# student-portal 对接契约
> 负责人：ai14
> 关联：[matrix.md](./matrix.md)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
无。student-portal 是前端微前端 Remote。
### 1.2 HTTP 端点（如有）
| Method | Path | 用途 | 认证 |
| ------ | -------------- | ------------ | ------------------------ |
| GET | / | 学生门户首页 | JWT 必需（前端路由守卫） |
| GET | /my-classes | 我的班级 | JWT 必需 |
| GET | /my-exams | 我的考试 | JWT 必需 |
| GET | /my-homework | 我的作业 | JWT 必需 |
| GET | /my-grades | 我的成绩 | JWT 必需 |
| GET | /my-attendance | 我的考勤 | JWT 必需 |
| GET | /learning-path | 学习路径 | JWT 必需 |
| GET | /dashboard | 学生仪表盘 | JWT 必需 |
| GET | /notifications | 通知中心 | JWT 必需 |
### 1.3 GraphQL schema（如 BFF）
不适用。student-portal 消费 student-bff GraphQL，自身不提供 schema。
### 1.4 Kafka 事件发布（如有）
无。
### 1.5 错误码前缀
无（前端不定义错误码前缀，透传 BFF 错误码）。
### 1.6 微前端架构（补充）
| 角色 | 说明 |
| ---------------------- | ----------------------------------------------------------------- |
| MF Remote | 学生门户是微前端远程模块，由 teacher-portal AppShell 或独立壳加载 |
| 暴露的 remote 模块 | StudentApp（学生端完整应用）、shared 学生端组件 |
| module federation 配置 | `apps/student-portal/module-federation.config.ts` |
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
无。前端不直接调 gRPC。
### 2.2 Kafka 事件订阅（异步）
无。前端不直接订阅 Kafka。
### 2.3 HTTP 调用（如有）
| 被调用方 | Method.Path | 用途 | mock 策略 |
| ------------------- | ------------------------- | --------------------------------------------- | ----------------------------------------------------------------- |
| api-gateway (ai01) | POST /api/student/graphql | 学生 GraphQL 查询（经网关代理到 student-bff） | api-gateway/student-bff 就绪前使用 MSW 拦截返回 mock GraphQL 响应 |
| api-gateway (ai01) | POST /api/auth/login | 学生登录 | api-gateway 就绪前使用 MSW 返回固定 JWT |
| push-gateway (ai02) | GET /ws | WebSocket 实时通知 | push-gateway 就绪前使用 mock-socket 模拟 WS 推送 |
### 2.4 GraphQL 查询域（经 api-gateway 代理到 student-bff）
| Query/Mutation | 用途 | mock 策略 |
| ----------------------------------- | --------------- | -------------------------------------------------- |
| currentUser | 当前学生信息 | MSW 返回固定学生 |
| myClasses | 我的班级 | MSW 返回固定 1 个班级 |
| myExams | 我的考试 | MSW 返回固定 2 个考试 |
| myHomework / submitHomework | 我的作业 + 提交 | MSW 返回固定作业 + submitHomework success |
| myGrades | 我的成绩 | MSW 返回固定 5 个成绩 |
| myAttendance | 我的考勤 | MSW 返回固定 10 条考勤 |
| textbooks / chapters / learningPath | 学习内容 | MSW 返回固定内容 + 学习路径 |
| studentDashboard | 学生仪表盘 | MSW 返回固定仪表盘（avg_score=85.0, class_rank=5） |
| myWeakness | 我的薄弱点 | MSW 返回固定 3 个 weak_points |
| myTrend | 学习趋势 | MSW 返回固定趋势数据 |
| myNotifications / markAsRead | 通知中心 | MSW 返回固定通知 |
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] api-gateway HTTP :8080 启用（ai01）—— 前端请求入口
- [ ] student-bff GraphQL :3009 启用（ai04）—— 数据来源
- [ ] push-gateway WebSocket :8081/ws 启用（ai02）—— 实时通知
### 3.2 我的就绪标志（供下游消费）
- [ ] student-portal dev server :4001 启用
- [ ] MF Remote 可被 AppShell 加载（暴露 StudentApp 模块）
- [ ] 独立壳渲染（首页 + 导航 + 路由守卫）
- [ ] 登录流程可用（POST /api/auth/login 获取 JWT 存入 cookie）
- [ ] GraphQL 查询可执行（currentUser / myClasses / studentDashboard 返回数据）
- [ ] WebSocket 通知可接收
---
## §4 Mock 策略
### 4.1 我提供的 mock
student-portal 是前端，无下游消费方。但对开发体验提供：
- **Storybook**：各组件独立 story
- **MSW handlers**：`apps/student-portal/src/mocks/handlers.ts`，拦截所有 GraphQL/HTTP 请求
### 4.2 我消费的 mock
在真实上游就绪前，student-portal 使用以下 mock：
- **HTTP/GraphQL mock**：使用 MSW 拦截所有请求
- POST /api/auth/login → 返回固定 JWT + UserInfo（student 角色）
- POST /api/student/graphql → 根据 operationName 返回对应 mock 响应（与 student-bff mock 数据一致）
- 所有 mock 响应定义在 `apps/student-portal/src/mocks/fixtures/*.json`
- **WebSocket mock**：使用 mock-socket 库
- 连接后每 30 秒推送 1 条 mock 通知
- **JWT mock**：使用固定 mock JWT，存入 httpOnly cookie
- **环境切换**：通过 `NEXT_PUBLIC_API_MOCKING=enabled` 环境变量控制，上游就绪后设为 `disabled`

136
docs/architecture/issues/contracts/teacher-bff_contract.md Normal file
View File

@@ -0,0 +1,136 @@
# teacher-bff 对接契约
> 负责人：ai03
> 关联：[matrix.md](./matrix.md)、[iam.proto](../../../packages/shared-proto/proto/iam.proto)、[core_edu.proto](../../../packages/shared-proto/proto/core_edu.proto)、[content.proto](../../../packages/shared-proto/proto/content.proto)、[analytics.proto](../../../packages/shared-proto/proto/analytics.proto)、[msg.proto](../../../packages/shared-proto/proto/msg.proto)、[ai.proto](../../../packages/shared-proto/proto/ai.proto)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
无对外 gRPC。teacher-bff 是 GraphQL 聚合层。
### 1.2 HTTP 端点（如有）
| Method | Path | 用途 | 认证 |
| ------ | -------- | ----------------------------------------- | ----------------------- |
| POST | /graphql | 教师 BFF GraphQL 端点 | JWT 必需 + teacher 角色 |
| GET | /graphql | GraphQL Playground（开发环境） | 开发环境公开 |
| GET | /healthz | 健康检查（liveness） | 公开 |
| GET | /readyz | 就绪检查（readiness，含下游 gRPC 连通性） | 公开 |
### 1.3 GraphQL schema（如 BFF）
GraphQL schema 文件路径：`apps/teacher-bff/src/schema/*.graphql`（端口 :3003）
核心 Query / Mutation 域：
- **auth**：currentUser（聚合 iam.GetUserInfo + GetEffectivePermissions + GetViewports）
- **classes**：myClasses（聚合 core-edu.ClassService.GetClassesByTeacher）
- **students**：classStudents（聚合 core-edu.ClassService.ListStudentsByClass + iam.BatchGetUsers 补用户名）
- **exams**：classExams / createExam / updateExam（聚合 core-edu.ExamService）
- **homework**：classHomework / assignHomework（聚合 core-edu.HomeworkService）
- **grades**：studentGrades / recordGrade（聚合 core-edu.GradeService）
- **attendance**：classAttendance / recordAttendance（聚合 core-edu.AttendanceService）
- **content**：textbooks / chapters / knowledgePoints / questions（聚合 content 4 个 Service）
- **dashboard**：teacherDashboard（聚合 data-ana.AnalyticsService.GetTeacherDashboard）
- **notifications**：myNotifications / markAsRead（聚合 msg.NotificationService）
- **ai**：aiChat / generateQuestion / generateLessonPlan（聚合 ai.AiService）
### 1.4 Kafka 事件发布（如有）
无。teacher-bff 不发布事件，仅做 gRPC 聚合。
### 1.5 错误码前缀
`BFF_TEACHER_`（如 BFF_TEACHER_UPSTREAM_UNAVAILABLE、BFF_TEACHER_AGGREGATION_FAILED、BFF_TEACHER_FORBIDDEN）
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
| 被调用方 | Service.RPC | 用途 | mock 策略 |
| --------------- | ------------------------------------- | ---------------- | ----------------------------------------------- |
| iam (ai06) | IamService.GetUserInfo | 获取当前教师信息 | iam 就绪前返回固定 UserInfo（teacher 角色） |
| iam (ai06) | IamService.BatchGetUsers | 批量补全学生姓名 | iam 就绪前返回固定用户名（"学生001"~"学生030"） |
| iam (ai06) | IamService.GetEffectivePermissions | 权限校验 | iam 就绪前返回全权限（放行） |
| iam (ai06) | IamService.GetViewports | 教师导航菜单 | iam 就绪前返回固定视口列表 |
| core-edu (ai08) | ClassService.GetClassesByTeacher | 教师班级列表 | core-edu 就绪前返回固定 3 个 ClassInfo |
| core-edu (ai08) | ClassService.ListStudentsByClass | 班级学生名单 | core-edu 就绪前返回固定 30 个 StudentInfo |
| core-edu (ai08) | ExamService.* | 考试管理 | core-edu 就绪前返回固定考试数据 |
| core-edu (ai08) | HomeworkService.* | 作业管理 | core-edu 就绪前返回固定作业数据 |
| core-edu (ai08) | GradeService.* | 成绩管理 | core-edu 就绪前返回固定成绩数据 |
| core-edu (ai08) | AttendanceService.* | 考勤管理 | core-edu 就绪前返回固定考勤数据 |
| content (ai09) | TextbookService.ListTextbooks | 教材列表 | content 就绪前返回固定 5 个教材 |
| content (ai09) | ChapterService.ListChapters | 章节列表 | content 就绪前返回固定章节树 |
| content (ai09) | KnowledgeGraphService.* | 知识图谱 | content 就绪前返回固定知识点 |
| content (ai09) | QuestionService.SearchQuestions | 题库检索 | content 就绪前返回固定 20 题 |
| data-ana (ai11) | AnalyticsService.GetTeacherDashboard | 教师仪表盘 | data-ana 就绪前返回固定仪表盘数据 |
| data-ana (ai11) | AnalyticsService.GetClassPerformance | 班级成绩分析 | data-ana 就绪前返回固定分析数据 |
| data-ana (ai11) | AnalyticsService.GetWarningList | 预警列表 | data-ana 就绪前返回固定 5 条预警 |
| msg (ai10) | NotificationService.ListNotifications | 教师通知列表 | msg 就绪前返回固定 10 条通知 |
| msg (ai10) | NotificationService.MarkAsRead | 标记已读 | msg 就绪前返回 success=true |
| ai (ai12) | AiService.Chat | AI 对话 | ai 就绪前返回固定回复 |
| ai (ai12) | AiService.GenerateQuestion | AI 出题 | ai 就绪前返回固定题目 |
| ai (ai12) | AiService.GenerateLessonPlan | AI 备课 | ai 就绪前返回固定教案 |
### 2.2 Kafka 事件订阅（异步）
无。teacher-bff 不订阅 Kafka 事件，仅做同步 gRPC 聚合。
### 2.3 HTTP 调用（如有）
无。
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] iam gRPC 50052 启用（ai06）
- [ ] core-edu gRPC 50053 启用（ai08）
- [ ] content gRPC 50054 启用（ai09）
- [ ] data-ana gRPC 50055 启用（ai11）
- [ ] msg gRPC 50056 启用（ai10）
- [ ] ai gRPC 50057 启用（ai12）
### 3.2 我的就绪标志（供下游消费）
- [ ] teacher-bff GraphQL :3003 启用（/healthz 返回 200）
- [ ] /readyz 返回 200（含 6 个下游 gRPC 连通性检查）
- [ ] GraphQL schema 可内省（POST /graphql 返回 schema）
- [ ] 核心 Query 可执行：currentUser / myClasses / teacherDashboard
- [ ] 核心 Mutation 可执行：createExam / assignHomework / recordGrade
- [ ] admin namespace 可用（供 admin-portal 消费）
---
## §4 Mock 策略
### 4.1 我提供的 mock
在 teacher-bff 真实就绪前，为下游（teacher-portal / admin-portal）提供以下 mock：
- **GraphQL mock**：使用 Apollo Server mockProviders 或 MSW 拦截 POST /graphql
- currentUser 返回固定教师（id="teacher-001", name="张老师", roles=["teacher"]）
- myClasses 返回固定 3 个班级
- teacherDashboard 返回固定仪表盘数据
- myNotifications 返回固定 10 条通知
- **admin namespace mock**：admin-portal 查询返回固定管理员视角数据（全校统计）
### 4.2 我消费的 mock
在真实上游就绪前，teacher-bff 使用以下 mock（详见 §2.1 mock 策略列）：
- **iam mock**：固定 UserInfo + 全权限 + 固定视口
- **core-edu mock**：固定班级/学生/考试/作业/成绩/考勤数据
- **content mock**：固定教材/章节/知识点/题目
- **data-ana mock**：固定仪表盘/分析/预警
- **msg mock**：固定通知列表 + MarkAsRead success
- **ai mock**：固定 AI 回复/题目/教案
> 所有上游 mock 通过 gRPC client 拦截器实现，上游就绪后移除拦截器切换真实调用。

126
docs/architecture/issues/contracts/teacher-portal_contract.md Normal file
View File

@@ -0,0 +1,126 @@
# teacher-portal 对接契约
> 负责人：ai13
> 关联：[matrix.md](./matrix.md)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
无。teacher-portal 是前端微前端 Shell。
### 1.2 HTTP 端点（如有）
| Method | Path | 用途 | 认证 |
| ------ | -------------- | ----------------------------- | ------------------------ |
| GET | / | 教师门户首页（MF Shell 容器） | JWT 必需（前端路由守卫） |
| GET | /classes/* | 班级管理子应用 | JWT 必需 |
| GET | /exams/* | 考试管理子应用 | JWT 必需 |
| GET | /homework/* | 作业管理子应用 | JWT 必需 |
| GET | /grades/* | 成绩管理子应用 | JWT 必需 |
| GET | /attendance/* | 考勤管理子应用 | JWT 必需 |
| GET | /content/* | 内容管理子应用 | JWT 必需 |
| GET | /dashboard | 教师仪表盘 | JWT 必需 |
| GET | /ai/* | AI 助手子应用 | JWT 必需 |
| GET | /notifications | 通知中心 | JWT 必需 |
### 1.3 GraphQL schema（如 BFF）
不适用。teacher-portal 消费 teacher-bff GraphQL，自身不提供 schema。
### 1.4 Kafka 事件发布（如有）
无。
### 1.5 错误码前缀
无（前端不定义错误码前缀，透传 BFF 错误码）。
### 1.6 微前端架构（补充）
| 角色 | 说明 |
| ---------------------- | --------------------------------------------------- |
| MF Shell（AppShell） | 教师门户是微前端宿主，加载其他子应用 |
| 暴露的 remote 模块 | AppShell（导航/布局/路由守卫）、shared 设计系统组件 |
| module federation 配置 | `apps/teacher-portal/module-federation.config.ts` |
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
无。前端不直接调 gRPC。
### 2.2 Kafka 事件订阅（异步）
无。前端不直接订阅 Kafka。
### 2.3 HTTP 调用（如有）
| 被调用方 | Method.Path | 用途 | mock 策略 |
| ------------------- | ------------------------- | --------------------------------------------- | ----------------------------------------------------------------- |
| api-gateway (ai01) | POST /api/teacher/graphql | 教师 GraphQL 查询（经网关代理到 teacher-bff） | api-gateway/teacher-bff 就绪前使用 MSW 拦截返回 mock GraphQL 响应 |
| api-gateway (ai01) | POST /api/auth/login | 教师登录 | api-gateway 就绪前使用 MSW 返回固定 JWT |
| push-gateway (ai02) | GET /ws | WebSocket 实时通知 | push-gateway 就绪前使用 mock-socket 模拟 WS 推送 |
### 2.4 GraphQL 查询域（经 api-gateway 代理到 teacher-bff）
| Query/Mutation | 用途 | mock 策略 |
| -------------------------------------------------- | ------------ | ---------------------- |
| currentUser | 当前教师信息 | MSW 返回固定教师 |
| myClasses | 我的班级 | MSW 返回固定 3 个班级 |
| classStudents | 班级学生名单 | MSW 返回固定 30 个学生 |
| classExams / createExam | 考试管理 | MSW 返回固定考试数据 |
| classHomework / assignHomework | 作业管理 | MSW 返回固定作业数据 |
| studentGrades / recordGrade | 成绩管理 | MSW 返回固定成绩数据 |
| classAttendance / recordAttendance | 考勤管理 | MSW 返回固定考勤数据 |
| textbooks / chapters / knowledgePoints / questions | 内容管理 | MSW 返回固定内容数据 |
| teacherDashboard | 教师仪表盘 | MSW 返回固定仪表盘 |
| myNotifications / markAsRead | 通知中心 | MSW 返回固定通知 |
| aiChat / generateQuestion / generateLessonPlan | AI 助手 | MSW 返回固定 AI 响应 |
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] api-gateway HTTP :8080 启用（ai01）—— 前端请求入口
- [ ] teacher-bff GraphQL :3003 启用（ai03）—— 数据来源
- [ ] push-gateway WebSocket :8081/ws 启用（ai02）—— 实时通知
### 3.2 我的就绪标志（供下游消费）
- [ ] teacher-portal dev server :4000 启用
- [ ] MF Shell 可加载（首页渲染 AppShell + 导航）
- [ ] 子应用路由可访问（/classes /exams /homework 等子页面渲染）
- [ ] 登录流程可用（POST /api/auth/login 获取 JWT 存入 cookie）
- [ ] GraphQL 查询可执行（currentUser / myClasses 返回数据）
- [ ] WebSocket 通知可接收（push-gateway 推送 → 前端通知中心更新）
---
## §4 Mock 策略
### 4.1 我提供的 mock
teacher-portal 是最前端，无下游消费方。但对开发体验提供：
- **Storybook**：各组件独立 story，供设计审查
- **MSW handlers**：`apps/teacher-portal/src/mocks/handlers.ts`，拦截所有 GraphQL/HTTP 请求返回 mock 数据
### 4.2 我消费的 mock
在真实上游就绪前，teacher-portal 使用以下 mock：
- **HTTP/GraphQL mock**：使用 MSW（Mock Service Worker）拦截所有请求
- POST /api/auth/login → 返回固定 JWT + UserInfo
- POST /api/teacher/graphql → 根据 operationName 返回对应 mock 响应（与 teacher-bff mock 数据一致）
- 所有 mock 响应定义在 `apps/teacher-portal/src/mocks/fixtures/*.json`
- **WebSocket mock**：使用 mock-socket 库
- 连接 ws://localhost:8081/ws 后每 30 秒推送 1 条 mock 通知
- **JWT mock**：使用固定 mock JWT（与 api-gateway mock 公钥配对），存入 httpOnly cookie
- **环境切换**：通过 `NEXT_PUBLIC_API_MOCKING=enabled` 环境变量控制是否启用 MSW，上游就绪后设为 `disabled`

292
docs/architecture/issues/coord.md Normal file
View File

@@ -0,0 +1,292 @@
# coord 仲裁结果汇总
> 维护者：coord（协调 AI）
> 维护规则：各 AI 在 `objections/[模块名]_issue.md` 提请异议 → coord 审阅 → 在本文件写入仲裁结果
> 关联文档：[president-final-rulings.md](../president-final-rulings.md)、[ai-work-orchestration.md](../ai-work-orchestration.md)、[workline.md](./workline.md)、[matrix.md](./matrix.md)
---
## 仲裁记录索引
| 编号 | 日期 | 提请方 | 主题 | 状态 | 仲裁章节 |
| ------- | ---------- | ---------------------- | --------------------------------- | --------- | -------- |
| ARB-001 | 2026-07-09 | coord（批次 1 启动前） | teacher-bff GraphQL schema 第一版 | ✅ 已裁决 | §1 |
| ARB-002 | 2026-07-09 | coord（批次 1 启动前） | MF Shell 暴露清单 | ✅ 已裁决 | §2 |
---
## §1 ARB-001：teacher-bff GraphQL schema 第一版
### 1.1 背景
批次 1（P2）启动前，需仲裁 teacher-bff GraphQL schema 第一版，作为 ai03（teacher-bff）和 ai13（teacher-portal）的共同契约。
数据源：ai03 的 [02-architecture-design.md §5](../../services/teacher-bff/docs/02-architecture-design.md#L503) 提供了目标态 schema（P4），但 P2 只需 Must Have 子集。
### 1.2 仲裁结论
**P2 第一版 schema 范围**（Must Have，对应 ai03 P2 工作量分级 Must Have 13 项）：
```graphql
# ============ P2 第一版 schema ============
# 存放位置：packages/shared-ts/contracts/graphql/teacher-bff.graphql
# 仲裁原则：仅包含 P2 可实现的 Query（iam + classes 已就绪），Mutation 延后到 P3
scalar DateTime
enum DataScope {
SELF
CLASS
GRADE
SCHOOL
DISTRICT
ALL
}
enum ExamStatus {
DRAFT
PUBLISHED
IN_PROGRESS
GRADING
SCORED
ARCHIVED
}
enum SubmissionStatus {
NOT_SUBMITTED
SUBMITTED
GRADED
}
type User {
id: ID!
email: String!
name: String!
roles: [String!]!
dataScope: DataScope!
}
type ViewportItem {
key: String!
label: String!
route: String!
icon: String
sortOrder: String!
requiredPermission: String
}
type Class {
id: ID!
name: String!
gradeId: String!
studentCount: Int!
}
type DashboardStats {
totalExams: Int!
pendingGrading: Int!
todayHomework: Int!
}
type DashboardData {
user: User!
classes: [Class!]!
viewports: [ViewportItem!]!
stats: DashboardStats!
}
# ============ Query（P2 仅读，无 Mutation） ============
type Query {
# 仪表盘聚合（并行：iam.me + iam.viewports + iam.permissions + classes.byTeacher）
dashboard: DashboardData!
# 视口配置（导航）
viewports: [ViewportItem!]!
# 当前用户信息
me: User!
# 班级列表（按教师 dataScope 过滤）
classes: [Class!]!
class(id: ID!): Class
}
# ============ P2 不包含（P3+ 扩展） ============
# - exams / homework / grades Query → P3（core-edu 就绪后）
# - classPerformance / studentWeakness / learningTrend → P4（data-ana 就绪后）
# - notifications → P5（msg 就绪后）
# - 所有 Mutation → P3+
# - Subscription → P6+ 评估
```
### 1.3 关键裁决
| 裁决点 | 结论 | 依据 |
| ---------------- | ---------------------------------------------------------- | ------------------------------------------------------------ |
| Schema 存放位置 | `packages/shared-ts/contracts/graphql/teacher-bff.graphql` | 总裁裁决 §2.17 SDL-first + 集中管理 |
| P2 Query 范围 | dashboard / viewports / me / classes / class（5 个） | 仅依赖 iam + classes（P2 就绪） |
| P2 Mutation 范围 | **无**（P2 纯读） | Mutation 依赖 core-edu（P3），P2 无下游可写 |
| DataLoader | dashboard 内 classes 列表用 DataLoader | N+1 防御（ai03 §5.1 第 4 条） |
| 复杂度限制 | depth ≤ 7，cost ≤ 1000 | ai03 §5.1 第 5 条 |
| admin 命名空间 | **P2 不包含**，P6 admin-portal 阶段新增 `admin` 命名空间 | 总裁裁决 §5.1 admin 复用 teacher-bff + admin schema 命名空间 |
| 错误响应 | ActionState 信封（success/errors/data） | coord-final-decisions F9 |
| 降级模式 | success=true + error=null + data 内 degraded 字段 | 总裁裁决 §3.4 方案 B |
### 1.4 ai03 执行项
1. 在 `packages/shared-ts/contracts/graphql/teacher-bff.graphql` 创建 P2 第一版 schema 文件
2. teacher-bff 实现 Yoga GraphQL endpoint（`POST /graphql`）
3. 实现 5 个 Query Resolver（dashboard / viewports / me / classes / class）
4. dashboard Resolver 并行调用 iam（3 RPC）+ classes（1 RPC），用 DataLoader 防御 N+1
5. 实现 ActionState 信封 + 降级模式（方案 B）
### 1.5 ai13 执行项
1. teacher-portal Shell 暴露 `GraphQLProvider`（urql client 单例）
2. 使用 `useGraphQLClient()` 从 packages/hooks 获取 client
3. P2 页面（dashboard / classes）通过 GraphQL query 拉取数据
4. **不调用 REST 端点**（除登录外，P2 起 all-in GraphQL）
---
## §2 ARB-002：MF Shell 暴露清单
### 2.1 背景
批次 1（P2）启动前，需仲裁 teacher-portal 作为 MF Shell 暴露哪些模块给 Remote（student/parent/admin），作为 ai13 的实现依据。
数据源：ai13 的 [03-long-term-architecture.md §1.4](../../apps/teacher-portal/docs/03-long-term-architecture.md) 提供了 GraphQL client 单例设计。
### 2.2 仲裁结论
**P2 第一版 MF Shell 暴露清单**：
```typescript
// teacher-portal/next.config.js — NextFederationPlugin exposes
exposes: {
// 1. AppShell（布局 + 导航 + 认证守卫）
'./AppShell': './src/components/AppShell.tsx',
// 2. GraphQLProvider（urql client 单例，总裁 §2.17 方案 A）
'./GraphQLProvider': './src/app/providers.tsx',
// 3. 共享 hooks
'./useAuth': './packages/hooks/src/use-auth.ts',
'./usePermission': './packages/hooks/src/use-permission.ts',
'./useGraphQLClient': './packages/hooks/src/use-graphql-client.ts',
// 4. 共享 UI 组件
'./ErrorBoundary': './packages/ui-components/src/error-boundary.tsx',
'./Loading': './packages/ui-components/src/loading.tsx',
'./Empty': './packages/ui-components/src/empty.tsx',
'./RequirePermission': './packages/ui-components/src/require-permission.tsx',
}
```
**MF shared（singleton）配置**：
```typescript
shared: {
react: { singleton: true, requiredVersion: '^18.3.0' },
'react-dom': { singleton: true, requiredVersion: '^18.3.0' },
urql: { singleton: true, requiredVersion: '^2.2.0' },
graphql: { singleton: true, requiredVersion: '^16.8.0' },
'@edu/ui-tokens': { singleton: true },
'@edu/ui-components': { singleton: true },
'@edu/hooks': { singleton: true },
}
```
### 2.3 关键裁决
| 裁决点 | 结论 | 依据 |
| ------------------- | ---------------------------------------------- | --------------------------- |
| Shell 身份 | teacher-portal 是 MF Shell（非 Remote） | 总裁裁决 §2.17 + ai13 §1.3 |
| P2 Remote 数量 | **0**（P2 暂无 Remote，仅配置 exposes/shared） | ai13 §1.3 绞杀者模式 step 3 |
| P3 首个 Remote | student-portal | ai13 §1.3 step 4 |
| GraphQL client 归属 | Shell 暴露 GraphQLProvider，Remote 复用 | 总裁 §2.17 方案 A |
| MF shared singleton | react / react-dom / urql / graphql / @edu/* | 避免多实例 + 缓存不一致 |
| AppShell 暴露 | 是（Remote 复用布局 + 导航 + 认证守卫） | ai13 §1.3 |
| feature flag | `NEXT_PUBLIC_MF_ENABLED=false`（P2 默认关） | ai13 §1.3 回退策略 |
| 登录页 | P2 不走 MF（Shell 独占 `/login`） | 登录是认证前提，MF 依赖认证 |
### 2.4 ai13 执行项
1. teacher-portal `next.config.js` 添加 NextFederationPlugin（exposes + shared，**无 remotes**）
2. 创建 `src/app/providers.tsx`（GraphQLProvider 包裹）
3. AppShell 改造：从 REST `/api/v1/teacher/viewports` 切换为 GraphQL query `viewports`
4. P2 页面（dashboard / classes）全部用 GraphQL
5. feature flag `NEXT_PUBLIC_MF_ENABLED=false`（P2 默认单体路由）
### 2.5 ai03 执行项（联动）
1. teacher-bff 暴露 `POST /graphql` endpoint
2. 提供GraphQL playground（仅开发环境）
---
## §3 仲裁流程说明
### 3.1 提请异议
各 AI 在自己模块的 `objections/[模块名]_issue.md` 中追加异议条目，格式：
```markdown
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
```
### 3.2 coord 仲裁
coord 审阅各 `objections/[模块名]_issue.md` 后，在本文件（coord.md）追加仲裁章节：
```markdown
## §N ARB-XXX：[主题]
### N.1 背景
### N.2 仲裁结论
### N.3 关键裁决（表格）
### N.4 相关 AI 执行项
```
### 3.3 状态同步
- 仲裁完成后，coord 在对应 `objections/[模块名]_issue.md` 中更新状态为"已裁决（见 coord.md §N）"
- coord 在 [workline.md](./workline.md) §8 就绪信号跟踪表中更新进度
### 3.4 目录结构
```
issues/
├── coord.md # 本文件（仲裁汇总）
├── workline.md # 总工作安排
├── matrix.md # 上下游对接总矩阵
├── objections/ # 各模块问题/异议
│ ├── [模块名]_issue.md
│ └── cross_issue.md # 跨模块问题
├── worklines/ # 各模块工作排期
│ └── [模块名]_workline.md
└── contracts/ # 各模块对接契约
└── [模块名]_contract.md
```
---
## §4 历史仲裁（已迁移）
以下仲裁已在此前完成，原始记录见 [coord-final-decisions.md](../coord-final-decisions.md) 和 [president-final-rulings.md](../president-final-rulings.md)：
- I1-I8：iam P2 契约（coord-final-decisions.md §1）
- F1-F9：BFF 设计裁决（coord-final-decisions.md §2）
- G1-G3：Gateway 裁决（coord-final-decisions.md §3）
- N1-N3：content 裁决（coord-final-decisions.md §4）
- 总裁裁决 70+ 项（president-final-rulings.md §1-§5）
本文件仅记录**新流程启动后**（2026-07-09 起）的仲裁。

229
docs/architecture/issues/matrix.md Normal file
View File

@@ -0,0 +1,229 @@
# 上下游对接总矩阵
> 维护者：coord（协调 AI）
> 关联：[coord.md](./coord.md)、[workline.md](./workline.md)、各模块 [contracts/](./contracts/)
> 模式：全并行开发（各 AI 一口气完成 P2-P6，开发期间用 mock，最后统一集成测试）
---
## §1 服务依赖矩阵（谁调用谁）
```mermaid
graph TB
subgraph Frontend["微前端层"]
TP[teacher-portal<br/>ai13 :4000]
SP[student-portal<br/>ai14 :4001]
PP[parent-portal<br/>ai15 :4002]
AP[admin-portal<br/>ai16 :4003]
end
subgraph Gateway["网关层"]
AGW[api-gateway<br/>ai01 :8080]
PGW[push-gateway<br/>ai02 :8081]
end
subgraph BFF["BFF 层"]
TBFF[teacher-bff<br/>ai03 :3003 GraphQL]
SBFF[student-bff<br/>ai04 :3009 GraphQL]
PBFF[parent-bff<br/>ai05 :3010 GraphQL]
end
subgraph Services["业务服务层"]
IAM[iam<br/>ai06 :50052]
CORE[core-edu<br/>ai08 :50053]
CONTENT[content<br/>ai09 :50054]
MSG[msg<br/>ai10 :50056]
DATA[data-ana<br/>ai11 :50055]
AISVC[ai<br/>ai12 :50057]
end
TP --> AGW
SP --> AGW
PP --> AGW
AP --> AGW
TP -.推送.-> PGW
SP -.推送.-> PGW
PP -.推送.-> PGW
AGW --> TBFF
AGW --> SBFF
AGW --> PBFF
TBFF --> IAM
TBFF --> CORE
TBFF --> CONTENT
TBFF --> DATA
TBFF --> MSG
TBFF --> AISVC
SBFF --> IAM
SBFF --> CORE
SBFF --> CONTENT
SBFF --> DATA
PBFF --> IAM
PBFF --> CORE
PGW --> MSG
AISVC --> CONTENT
AISVC --> DATA
CORE -.Kafka.-> CONTENT
CORE -.Kafka.-> DATA
CORE -.Kafka.-> MSG
CONTENT -.Kafka.-> DATA
IAM -.Kafka.-> CORE
IAM -.Kafka.-> MSG
```
---
## §2 gRPC 接口提供方矩阵
| 提供方 | gRPC 端口 | Service | RPC 数 | 消费方 | 就绪信号 | 状态 |
| --------------- | --------- | --------------------------------------------------------------------------------- | ------ | ---------------------------------------------------- | ----------------------------- | ---- |
| iam (ai06) | 50052 | IamService | 12 | teacher-bff / student-bff / parent-bff / api-gateway | HealthService.Check = SERVING | ⏳ |
| core-edu (ai08) | 50053 | ClassService + ExamService + HomeworkService + GradeService + AttendanceService | 22 | teacher-bff / student-bff / parent-bff | HealthService.Check = SERVING | ⏳ |
| content (ai09) | 50054 | TextbookService + ChapterService + KnowledgeGraphService + QuestionService | 18 | teacher-bff / student-bff / ai | HealthService.Check = SERVING | ⏳ |
| data-ana (ai11) | 50055 | AnalyticsService | 12 | teacher-bff / student-bff / parent-bff / ai | HealthService.Check = SERVING | ⏳ |
| msg (ai10) | 50056 | NotificationService + NotificationPreferenceService + NotificationTemplateService | 13 | teacher-bff / push-gateway | HealthService.Check = SERVING | ⏳ |
| ai (ai12) | 50057 | AiService | 6 | teacher-bff | HealthService.Check = SERVING | ⏳ |
---
## §3 GraphQL 接口提供方矩阵
| 提供方 | HTTP 端口 | Endpoint | 消费方 | schema 文件 | 状态 |
| ------------------ | --------- | ------------- | ----------------------------- | -------------------------------------------------------- | ---- |
| teacher-bff (ai03) | 3003 | POST /graphql | teacher-portal / admin-portal | packages/shared-ts/contracts/graphql/teacher-bff.graphql | ⏳ |
| student-bff (ai04) | 3009 | POST /graphql | student-portal | packages/shared-ts/contracts/graphql/student-bff.graphql | ⏳ |
| parent-bff (ai05) | 3010 | POST /graphql | parent-portal | packages/shared-ts/contracts/graphql/parent-bff.graphql | ⏳ |
---
## §4 Kafka 事件发布方矩阵
| 发布方 | Topic | Event | 消费方 | Outbox | 状态 |
| --------------- | --------------------------- | ----------------------------------------------------- | --------------------------------------------------------- | ------- | ---- |
| iam (ai06) | edu.iam.user.events | UserEvent（created/updated/deleted/role_changed） | core-edu / msg / push-gateway / teacher-bff / student-bff | ✅ | ⏳ |
| iam (ai06) | edu.iam.role.events | RoleEvent（created/updated） | core-edu / msg | ✅ | ⏳ |
| iam (ai06) | edu.iam.audit.created | AuditEvent（create/update/delete/login/logout） | admin-portal | ✅ | ⏳ |
| core-edu (ai08) | edu.exam.events | ExamEvent（created/updated/deleted） | msg / data-ana / push-gateway | ✅ | ⏳ |
| core-edu (ai08) | edu.homework.events | HomeworkEvent（assigned/submitted/graded） | msg / data-ana / push-gateway | ✅ | ⏳ |
| core-edu (ai08) | edu.grade.events | GradeEvent（recorded/updated） | msg / push-gateway / parent-bff | ✅ | ⏳ |
| core-edu (ai08) | edu.class.events | ClassEvent（transferred） | msg / data-ana | ✅ | ⏳ |
| content (ai09) | edu.content.kp.events | KnowledgePointEvent（created/updated/prerequisite_*） | data-ana / ai / Neo4j Sync / ES Sync | ✅ | ⏳ |
| content (ai09) | edu.content.question.events | QuestionEvent（created/updated/published/deleted） | data-ana / ai / ES Sync | ✅ | ⏳ |
| msg (ai10) | edu.notification.requested | NotificationEvent（sent） | push-gateway / data-ana | ✅ | ⏳ |
| data-ana (ai11) | edu.analytics.mastery | MasteryEvent（mastery.updated / warning.triggered） | core-edu / msg | ❌ 豁免 | ⏳ |
| ai (ai12) | edu.ai.usage | AIUsageEvent（chat/generate/lesson） | data-ana | ❌ 豁免 | ⏳ |
---
## §5 HTTP 接口矩阵（非 gRPC / 非 GraphQL）
| 提供方 | Method | Path | 用途 | 消费方 | 认证 | 状态 |
| ------------------- | ------ | ----------------- | -------------------- | ----------------------------------------------- | -------------- | ---- |
| api-gateway (ai01) | * | /api/v1/teacher/* | 反向代理 teacher-bff | teacher-portal | JWT | ⏳ |
| api-gateway (ai01) | * | /api/v1/student/* | 反向代理 student-bff | student-portal | JWT | ⏳ |
| api-gateway (ai01) | * | /api/v1/parent/* | 反向代理 parent-bff | parent-portal | JWT | ⏳ |
| api-gateway (ai01) | * | /api/v1/iam/* | 反向代理 iam | （内部） | JWT | ⏳ |
| push-gateway (ai02) | WS | /ws | WebSocket 推送通道 | teacher-portal / student-portal / parent-portal | JWT | ⏳ |
| push-gateway (ai02) | SSE | /sse | SSE 推送通道 | teacher-portal | JWT | ⏳ |
| push-gateway (ai02) | POST | /internal/push | 内部推送入口 | msg | X-Internal-Key | ⏳ |
| iam (ai06) | GET | /healthz | 存活检查 | k8s / 监控 | 无 | ⏳ |
| iam (ai06) | GET | /readyz | 就绪检查（5 依赖） | k8s / 监控 | 无 | ⏳ |
| 所有服务 | GET | /metrics | Prometheus 指标 | Prometheus | 无 | ⏳ |
---
## §6 错误码前缀矩阵
| 模块 | 前缀 | 示例 |
| ------------ | --------- | -------------------------------------------------- |
| api-gateway | GW_ | GW_UNAUTHORIZED / GW_RATE_LIMITED |
| push-gateway | PUSH_ | PUSH_DEVICE_NOT_FOUND / PUSH_CHANNEL_FAILED |
| teacher-bff | BFF_XXX_ | BFF_TEACHER_UNAUTHORIZED / BFF_TEACHER_BAD_GATEWAY |
| student-bff | BFF_XXX_ | BFF_STUDENT_UNAUTHORIZED |
| parent-bff | BFF_XXX_ | BFF_PARENT_CHILD_NOT_BOUND |
| iam | IAM_ | IAM_USER_NOT_FOUND / IAM_INVALID_CREDENTIALS |
| core-edu | CORE_EDU_ | CORE_EDU_EXAM_NOT_FOUND |
| content | CONTENT_ | CONTENT_QUESTION_NOT_FOUND |
| msg | MSG_ | MSG_NOTIFICATION_NOT_FOUND |
| data-ana | DATA_ANA_ | DATA_ANA_DASHBOARD_UNAVAILABLE |
| ai | AI_ | AI_GENERATION_FAILED / AI_QUOTA_EXCEEDED |
---
## §7 全并行开发 Mock 策略汇总
| 消费方 | 消费的接口 | Mock 方式 | 切换真实时机 |
| -------------- | ----------------------------------- | --------------------------------------- | ----------------------------------- |
| api-gateway | iam.GetPublicKey | 硬编码 RS256 公钥（DEV_MODE） | iam gRPC 50052 就绪 |
| teacher-bff | iam gRPC 12 RPC | grpc-mock 拦截 + 固定 JSON | iam 就绪信号 ✅ |
| teacher-bff | core-edu gRPC 22 RPC | grpc-mock 拦截 + 固定 JSON | core-edu 就绪信号 ✅ |
| student-bff | iam + core-edu + content + data-ana | grpc-mock 拦截 | 各服务就绪信号 ✅ |
| parent-bff | iam + core-edu | grpc-mock 拦截 | 各服务就绪信号 ✅ |
| teacher-portal | teacher-bff GraphQL | MSW 拦截 + 固定 response | teacher-bff GraphQL 就绪 ✅ |
| student-portal | student-bff GraphQL | MSW 拦截 | student-bff GraphQL 就绪 ✅ |
| parent-portal | parent-bff GraphQL | MSW 拦截 | parent-bff GraphQL 就绪 ✅ |
| admin-portal | teacher-bff GraphQL (admin) | MSW 拦截 | teacher-bff admin namespace 就绪 ✅ |
| push-gateway | msg Kafka 事件 | 本地 Kafka mock producer | msg 就绪信号 ✅ |
| ai | content + data-ana gRPC | grpc-mock 拦截 | 各服务就绪信号 ✅ |
| data-ana | core-edu/content/ai Kafka + CDC | 本地 Kafka mock + ClickHouse 模拟数据集 | 各服务就绪信号 ✅ |
---
## §8 就绪信号跟踪表
> 各 AI 完成模块后，在此表更新状态（⏳ 进行中 → ✅ 就绪）
| 模块 | AI | 就绪信号 | 状态 | 完成时间 |
| -------------- | ---- | ------------------------------------------- | ---- | -------- |
| iam | ai06 | gRPC 50052 + 12 RPC + HealthService SERVING | ⏳ | - |
| api-gateway | ai01 | :8080 可访问 + JWT 验签 | ⏳ | - |
| teacher-bff | ai03 | POST /graphql + 5 Query | ⏳ | - |
| teacher-portal | ai13 | :4000 可访问 + 登录→Dashboard | ⏳ | - |
| core-edu | ai08 | gRPC 50053 + 22 RPC + HealthService SERVING | ⏳ | - |
| content | ai09 | gRPC 50054 + 18 RPC + HealthService SERVING | ⏳ | - |
| msg | ai10 | gRPC 50056 + 13 RPC + HealthService SERVING | ⏳ | - |
| data-ana | ai11 | gRPC 50055 + 12 RPC + HealthService SERVING | ⏳ | - |
| ai | ai12 | gRPC 50057 + 6 RPC + HealthService SERVING | ⏳ | - |
| student-bff | ai04 | POST /graphql + Dashboard Query | ⏳ | - |
| parent-bff | ai05 | POST /graphql + Dashboard Query | ⏳ | - |
| push-gateway | ai02 | :8081 可访问 + /internal/push | ⏳ | - |
| student-portal | ai14 | :4001 可访问 + MF Remote | ⏳ | - |
| parent-portal | ai15 | :4002 可访问 + MF Remote | ⏳ | - |
| admin-portal | ai16 | :4003 可访问 + MF Remote + admin | ⏳ | - |
---
## §9 统一集成测试检查清单
> 所有模块就绪后，按此清单进行统一集成测试
### 9.1 认证链路
- [ ] teacher-portal 登录 → api-gateway → iam → JWT 签发
- [ ] JWT 验签 → x-user-id 注入 → teacher-bff 读取
### 9.2 GraphQL 链路
- [ ] teacher-portal → teacher-bff GraphQL dashboard Query
- [ ] teacher-bff → iam gRPC + core-edu gRPC 并行聚合
- [ ] ActionState 信封正确返回
### 9.3 事件链路
- [ ] core-edu 发布 GradeEvent → Kafka → msg 消费 → push-gateway 推送
- [ ] data-ana 消费 CDC 事件 → ClickHouse 写入
### 9.4 MF 链路
- [ ] teacher-portal Shell 加载 student-portal Remote
- [ ] GraphQL client 单例跨 Remote 共享
### 9.5 推送链路
- [ ] msg → push-gateway /internal/push → WebSocket 推送到前端

24
docs/architecture/issues/objections/admin-portal_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# admin-portal 问题记录
> 负责人：ai16
> 关联：[coord.md](../coord.md)、[contracts/admin-portal_contract.md](../contracts/admin-portal_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

24
docs/architecture/issues/objections/ai_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# ai 问题记录
> 负责人：ai12
> 关联：[coord.md](../coord.md)、[contracts/ai_contract.md](../contracts/ai_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

24
docs/architecture/issues/objections/api-gateway_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# api-gateway 问题记录
> 负责人：ai01
> 关联：[coord.md](../coord.md)、[contracts/api-gateway_contract.md](../contracts/api-gateway_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

58
docs/architecture/issues/objections/classes_issue.md Normal file
View File

@@ -0,0 +1,58 @@
# classes 问题记录
> 负责人：ai07
> 关联：[coord.md](../coord.md)、[contracts/classes_contract.md](../contracts/classes_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
### ISSUE-001-ai07：P3 合并后 classes 目录保留方式
- **提请方**：ai07
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：classes 是黄金模板，P3 合并入 core-edu 后，`services/classes/` 目录是否保留？若保留，是只读对照基准还是改为 shared-ts 模板？若删除，黄金模板对照基准丢失，其他 TS 服务无法对齐。
- **建议方案**：保留 `services/classes/` 作为只读对照基准（不删除），core-edu 复制其结构。黄金模板 checklist（02-architecture-design.md §10）由 ai07 持续维护。
- **状态**：待 coord 仲裁
### ISSUE-002-ai07：cuid2 迁移时机
- **提请方**：ai07
- **日期**：2026-07-10
- **类型**：前置依赖缺失
- **描述**：classes 当前用 uuid v4 生成 ID，project_rules 要求 cuid2。迁移时机有两种选择：(A) P1 黄金模板立即迁移；(B) P3 合并入 core-edu 时统一迁移。若选 A，黄金模板先行避免 ai08 继承 uuid 遗留；若选 B，减少一次迁移成本。
- **建议方案**：选 A（P1 立即迁移），黄金模板应先行，避免其他服务继承 uuid 遗留。迁移涉及 classes 表主键、proto message 字段类型。
- **状态**：待 coord 仲裁
### ISSUE-003-ai07：proto ClassService 合并后归属
- **提请方**：ai07
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：P3 合并入 core-edu 后，`classes.proto` 的 `ClassService` 是否迁移到 `core_edu.proto`？若迁移，破坏 proto 契约稳定性（下游需更新 import）；若保留，core_edu.proto 不会膨胀但需在 core-edu 实现中 import classes.proto。
- **建议方案**：保留 `classes.proto` 由 core-edu 实现（选项 B），保持契约稳定性，避免下游 import 路径变更。
- **状态**：待 coord 仲裁
### ISSUE-004-ai07：node:20-alpine → node:22-alpine 升级时机
- **提请方**：ai07
- **日期**：2026-07-10
- **类型**：其他
- **描述**：classes Dockerfile 用 `node:20-alpine`，project_rules §15.8 镜像预拉清单是 `node:22-alpine`。是 P1 立即升级还是等统一升级？
- **建议方案**：P1 立即升级，影响所有 TS 服务 Dockerfile 基准，黄金模板应先行。
- **状态**：待 coord 仲裁

24
docs/architecture/issues/objections/content_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# content 问题记录
> 负责人：ai09
> 关联：[coord.md](../coord.md)、[contracts/content_contract.md](../contracts/content_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

24
docs/architecture/issues/objections/core-edu_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# core-edu 问题记录
> 负责人：ai08
> 关联：[coord.md](../coord.md)、[contracts/core-edu_contract.md](../contracts/core-edu_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

13
docs/architecture/issues/objections/cross_issue.md Normal file
View File

@@ -0,0 +1,13 @@
# 跨模块问题记录
> 维护者：所有 AI（跨模块问题在此追加）
> 关联：[coord.md](../coord.md)
> 规则：涉及多个模块的问题在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!-- 追加条目格式同各模块 issue.md -->
（暂无问题）

24
docs/architecture/issues/objections/data-ana_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# data-ana 问题记录
> 负责人：ai11
> 关联：[coord.md](../coord.md)、[contracts/data-ana_contract.md](../contracts/data-ana_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

24
docs/architecture/issues/objections/iam_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# iam 问题记录
> 负责人：ai06
> 关联：[coord.md](../coord.md)、[contracts/iam_contract.md](../contracts/iam_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

24
docs/architecture/issues/objections/msg_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# msg 问题记录
> 负责人：ai10
> 关联：[coord.md](../coord.md)、[contracts/msg_contract.md](../contracts/msg_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

24
docs/architecture/issues/objections/parent-bff_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# parent-bff 问题记录
> 负责人：ai05
> 关联：[coord.md](../coord.md)、[contracts/parent-bff_contract.md](../contracts/parent-bff_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

24
docs/architecture/issues/objections/parent-portal_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# parent-portal 问题记录
> 负责人：ai15
> 关联：[coord.md](../coord.md)、[contracts/parent-portal_contract.md](../contracts/parent-portal_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

24
docs/architecture/issues/objections/push-gateway_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# push-gateway 问题记录
> 负责人：ai02
> 关联：[coord.md](../coord.md)、[contracts/push-gateway_contract.md](../contracts/push-gateway_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

24
docs/architecture/issues/objections/student-bff_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# student-bff 问题记录
> 负责人：ai04
> 关联：[coord.md](../coord.md)、[contracts/student-bff_contract.md](../contracts/student-bff_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

24
docs/architecture/issues/objections/student-portal_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# student-portal 问题记录
> 负责人：ai14
> 关联：[coord.md](../coord.md)、[contracts/student-portal_contract.md](../contracts/student-portal_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

24
docs/architecture/issues/objections/teacher-bff_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# teacher-bff 问题记录
> 负责人：ai03
> 关联：[coord.md](../coord.md)、[contracts/teacher-bff_contract.md](../contracts/teacher-bff_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

161
docs/architecture/issues/objections/teacher-portal_issue.md Normal file
View File

@@ -0,0 +1,161 @@
# teacher-portal 问题记录
> 负责人：ai13
> 关联：[coord.md](../coord.md)、[contracts/teacher-portal_contract.md](../contracts/teacher-portal_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
> 迁移说明：本文件 ISSUE-036~041 迁移自旧 `docs/issues.md` §2.7（已按总裁裁决 §0.4 编号冲突整理规则保留原始编号 + 追加 `<提请AI>` 后缀）
---
## 问题列表
### ISSUE-036-ai13：03-long-term-architecture.md "REST→GraphQL 演进策略"与 F9 裁决冲突
- **提请方**：ai13
- **日期**：2026-07-09
- **类型**：裁决冲突 + 文档同步遗漏
- **阶段**：P2
- **描述**：
- coord F9 裁决："P2 起 BFF 用 GraphQL，前端用 urql/apollo"，禁止"P2-P6 REST，未来切 GraphQL"
- ai13 `apps/teacher-portal/docs/03-long-term-architecture.md` §1.4（提请时误记为 §6，实际 §6 是 i18n）仍保留"REST→GraphQL 切换策略"过渡方案（P2-P4 REST + P5+ 迁移 + feature flag 灰度）
- 与 F9 裁决直接冲突，违反"不分阶段"原则
- **建议方案**：
1. 删除 §1.4 "REST → GraphQL 切换策略"整节
2. 替换为"GraphQL 客户端架构（P2 起最终方案）"
3. 同步更新 §1.1 P2 行 + §1.2 表格 + §12.3 #3 待裁决问题
- **状态**：✅ 已回写闭合（2026-07-09，批次 0.15 后）
- **coord 裁决**：总裁裁决 §3.4 + §4.4 第 5 条（删除过渡方案本身，保留设计决策记录）
- **回写执行**：详见 [03-long-term-architecture.md §14.1](../../../apps/teacher-portal/docs/03-long-term-architecture.md)
---
### ISSUE-037-ai13：ai13 与 ai03 的 GraphQL schema 契约协调机制未明确
- **提请方**：ai13
- **日期**：2026-07-09
- **类型**：契约不明确
- **阶段**：P2
- **描述**：
- F9 裁决：P2 起 BFF 用 GraphQL（teacher-bff ai03 实现 GraphQL Yoga server），前端用 urql（teacher-portal ai13 实现 GraphQL client）
- B1 裁决：GraphQL Yoga + DataLoader
- ai13 与 ai03 的 GraphQL schema 契约如何协调未明确：
- schema 定义权归属（ai03 定义 server schema，ai13 消费？还是 coord 仲裁第一版？）
- schema 版本管理（GraphQL schema 演进如何同步前后端？）
- 查询/变更/订阅的命名规范（camelCase vs snake_case？分页规范？）
- 错误响应格式（GraphQL errors 数组 vs ActionState 信封？）
- 与 ISSUE-019（ai08 core-edu 调用侧）/ ISSUE-030（ai04 student-bff 前端消费侧）同类但不同 BFF
- **建议方案**：
1. coord 在批次 1 启动前仲裁 teacher-bff GraphQL schema 第一版
2. 建立"schema-first"工作流：ai03 定义 → coord 仲裁 → ai13 消费 → 变更需 PR + 双方 review
3. 明确 GraphQL 规范：camelCase 命名、Relay Cursor Connections 分页、errors 数组扩展 ActionState 字段（extensions.code = BFF_TEACHER_*）
4. 建立 schema 注册表（packages/shared-ts/contracts/graphql/）
- **状态**：✅ 已裁决
- **coord 裁决**：总裁裁决 §2.2（GraphQL schema 仲裁机制）—— SDL-first，存放 `packages/shared-ts/contracts/graphql/`，各 BFF AI 起草 + coord 仲裁第一版
- **执行**：ai13 待 ai03 起草 teacher-bff schema 后消费，coord 批次 1 启动前仲裁
---
### ISSUE-038-ai13：MF 暴露 AppShell 整体是否包含 GraphQL client 单例未明确
- **提请方**：ai13
- **日期**：2026-07-09
- **类型**：契约不明确
- **阶段**：P2
- **描述**：
- F10 裁决："暴露 AppShell 整体，各 Remote 自行决定内部布局"
- 问题：AppShell 整体暴露是否包含 GraphQL client 单例（urql Client）？
- 方案 A（包含）：Shell 初始化 GraphQL client，通过 React Context 注入给所有 Remote，共享同一 client 实例 + 缓存
- 方案 B（不包含）：各 Remote 自行初始化，缓存隔离
- 方案 A 风险：MF 跨 React 实例时 Context 共享有坑（shared singleton 要求）
- 方案 B 风险：缓存隔离导致跨 Remote 数据不一致
- **建议方案**：建议方案 A（Shell 暴露 GraphQL client 单例）
- **状态**：✅ 已裁决
- **coord 裁决**：总裁裁决 §2.17（采纳方案 A：Shell 暴露 GraphQLProvider，student/parent/admin Remote 复用 Shell 单例）
- **执行**：ai13 P2 实现 Shell GraphQLProvider，ai14/ai15/ai16 消费；MF shared 配置 react/urql/graphql 设为 singleton
---
### ISSUE-039-ai13：F8 ai13 维护 packages 的建立时机与依赖未明确
- **提请方**：ai13
- **日期**：2026-07-09
- **类型**：前置依赖未就绪 + 工作归属不明
- **阶段**：P2
- **描述**：
- F8 裁决："ai13 维护 ui-tokens/ui-components/hooks，coord 仅维护 shared-ts/contracts"
- 问题：
- 这 3 个 packages 何时建立？P2 启动前？P2 启动时？
- ai13 P2 首次实现是否依赖这 3 个 packages 已就位？
- packages 的依赖关系：ui-components 依赖 ui-tokens，hooks 依赖 ui-components？还是平级？
- 4 个 portal 是否都消费？版本管理策略？
- ai-work-orchestration.md §3.1 批次 0 未列出这 3 个 packages 的建立任务
- **建议方案**：
1. ai13 在 P2 启动前（批次 0 末）建立 3 个 packages 骨架
2. 依赖关系：ui-tokens（无依赖）→ ui-components（依赖 ui-tokens）→ hooks（依赖 ui-components）
3. 4 个 portal 统一消费，版本通过 pnpm workspace 协议（"workspace:*"）
4. ai13 完成后通知 ai14/ai15/ai16 消费
- **状态**：✅ 已裁决 + 已执行
- **coord 裁决**：总裁裁决 §2.18（ai13 在 P2 启动前 = 批次 0.15 建立 3 个 packages 骨架，4 个 portal 统一消费）
- **执行**：ai13 已于批次 0.15 完成建立：
- `packages/ui-tokens/`（colors/typography/spacing/shadows + index.ts）
- `packages/ui-components/`（cn/error-boundary/loading/empty/require-permission + index.ts）
- `packages/hooks/`（use-auth/use-permission/use-a11y-id/use-toast/use-trace-id/use-aria-live/use-api/use-viewports + types + index.ts）
- 依赖方向：ui-tokens ← ui-components ← hooks（hooks 不依赖 iam，权限数据 props 注入）
- pnpm-workspace.yaml 已注册 packages/*
---
### ISSUE-040-ai13：ai13 teacher-portal P2 功能范围与下游服务启用阶段的关系未明确
- **提请方**：ai13
- **日期**：2026-07-09
- **类型**：跨度过大
- **阶段**：P2
- **描述**：
- ai-work-orchestration.md §4.3 明确 ai13 P2 范围：client 改造 + MF shell + 共享组件抽取
- 但 teacher-portal P2 阶段需对接 teacher-bff（ai03 P2 启动）的哪些 GraphQL 查询未明确：
- P2 仅实现登录 + Dashboard 框架？
- 还是包含班级列表 + 学生列表等基础教学功能？
- teacher-bff P2 只调 iam（gRPC），core-edu P3 / content P4 / data-ana P4 才启用
- 若 teacher-portal P2 实现班级/学生/作业等页面，但 teacher-bff P2 无法 gRPC 调 core-edu（P3 才启用），数据来源断裂
- ISSUE-004/005 已裁决"BFF 跨阶段扩展下游"是允许的例外，但前端是否也跟随？
- **建议方案**：
1. 明确 ai13 P2 功能范围：登录 + 权限上下文 + Dashboard 框架 + 个人设置 + 班级列表（iam 数据）+ 学生列表（iam 数据）
2. P3 起跟随 teacher-bff 扩展 core-edu 相关页面
3. 前端路由骨架 P2 一次性建立，但页面内容随 BFF 能力分阶段填充
- **状态**：✅ 已裁决
- **coord 裁决**：总裁裁决 §3.5（ai13 P2 功能范围：登录 + 权限上下文 + Dashboard 框架 + 个人设置 + 班级列表 + 学生列表；P3-P5 跟随 teacher-bff 扩展）
- **执行**：ai13 P2 按此范围实现，见 workline.md §3 P2 详细任务
---
### ISSUE-041-ai13：仲裁评估总结 - 关键裁决对 ai13 的可行性与影响评估
- **提请方**：ai13
- **日期**：2026-07-09
- **类型**：跨度过大（评估总结）
- **阶段**：P2-P6
- **描述**：ai13 完整阅读 coord-final-decisions.md（80+ 项裁决）+ ai-work-orchestration.md（批次 0-5 规划）+ issues.md（35 个已识别问题），对 ai13 的关键裁决影响评估：
| 裁决编号 | 裁决内容 | 对 ai13 影响 | 可行性 | 风险 |
| -------- | -------------------------------- | --------------------------------- | -------------------------------------- | -------------------------------------- |
| F9 | P2 起 GraphQL（urql） | 高：从 REST 改造为 GraphQL client | 中：schema 契约协调成本高（ISSUE-037） | schema 未及时仲裁阻塞 P2 |
| F12 | P2 localStorage token | 低：与原设计一致 | 高 | 无 |
| F8 | ai13 维护 3 个 packages | 中：新增 packages 建立任务 | 高：ai13 已设计完毕 | 时机不明确（ISSUE-039） |
| F10 | MF 暴露 AppShell 整体 | 中：Shell 设计需包含 Provider | 高 | GraphQL client 单例不明确（ISSUE-038） |
| F7 | 权限点命名 `<RESOURCE>_<ACTION>` | 低：命名规范调整 | 高 | 无 |
- **影响**：本评估总结供 coord 参考，不直接阻塞工作；具体阻塞问题已分别提请（ISSUE-036~040，均已裁决）
- **建议方案**：
1. coord 优先处理 ISSUE-037（schema 仲裁机制）+ ISSUE-039（packages 时机），二者是 ai13 P2 启动的关键前置 —— ✅ 均已裁决
2. ai13 在等待 coord 仲裁期间，先完成 03 文档回写（删除 REST→GraphQL）+ packages 骨架建立 —— ✅ 均已完成
3. ai13 与 ai03 建立 schema 协调通道（PR review + 双方签字）
- **状态**：✅ 仅供参考，无具体裁决需求（所有子问题 ISSUE-036~040 均已裁决）
- **coord 裁决**：总裁裁决 §10 问题索引表确认 ISSUE-036~041-ai13 映射到 §2.2/2.17/2.18/3.4/3.5
---
**AI Agent**: ai13（teacher-portal）
**Branch**: feat/teacher-portal-issues-migrate-ai13
**Coordinator**: coord-ai
**迁移说明**：本文件 ISSUE-036~041 迁移自旧 `docs/issues.md` §2.7，按总裁裁决 §0.4 保留原始编号 + 追加 `<提请AI>` 后缀，状态更新为已裁决

268
docs/architecture/issues/workline.md Normal file
View File

@@ -0,0 +1,268 @@
# 总工作安排（coord 汇总）
> 维护者：coord（协调 AI）
> 维护规则：各 AI 在 `worklines/[模块名]_workline.md` 写入甘特图工作排期 → coord 汇总到本文件
> 模式：**全并行**（各 AI 一口气完成 P2-P6 全部代码，开发期间用 mock，最后统一集成测试）
> 关联文档：[ai-work-orchestration.md](../ai-work-orchestration.md)、[coord.md](./coord.md)、[matrix.md](./matrix.md)、[president-final-rulings.md](../president-final-rulings.md)
---
## §1 16 AI 总时间线（甘特图）
```mermaid
gantt
title Edu 项目 16 AI 功能时间线（总裁裁决 §6.1 最终版）
dateFormat YYYY-MM-DD
axisFormat %m-%d
section 批次0 coord前置 3-5天
coord 0.1-0.14 proto+工具包 :crit, b0, 2026-07-09, 4d
ai13 0.15 packages骨架 :b0a, 2026-07-09, 3d
section 批次1 P2 7-10天
ai01 Gateway路由+shared-go :b1a, after b0, 8d
ai06 iam P2.1 gRPC+8RPC :crit, b1b, after b0, 8d
ai03 teacher-bff GraphQL Must :b1c, after b0, 8d
ai13 teacher-portal P2 MF Shell :b1d, after b0, 8d
section 批次2 P3 7-10天
ai07 classes代码交接 :b2a, after b1b, 2d
ai08 core-edu gRPC 50053 :crit, b2b, after b1b, 8d
ai04 student-bff GraphQL :b2c, after b1c, 8d
ai14 student-portal P3 :b2d, after b1d, 8d
ai03 teacher-bff P3扩展 :b2e, after b1c, 5d
section 批次3 P4 10-12天
ai09 content gRPC 50054+Question :crit, b3a, after b2b, 11d
ai11 data-ana gRPC 50055 :b3b, after b2b, 11d
ai05 parent-bff GraphQL :b3c, after b2c, 11d
ai15 parent-portal P4 :b3d, after b2d, 11d
section 批次4 P5 12-15天
ai10 msg gRPC 50056 :crit, b4a, after b3a, 13d
ai02 push-gateway HTTP :b4b, after b3a, 13d
ai12 ai服务 gRPC 50058 :b4c, after b3a, 13d
ai03 teacher-bff P5扩展 :b4d, after b3a, 8d
section 批次5 P6 10-12天
ai16 admin-portal MVP :crit, b5a, after b4a, 11d
iam P2.2补全 :b5b, after b4a, 11d
持续优化 /readyz硬化 :b5c, after b4a, 11d
```
**关键路径**（红色 crit）：批次0 → iam P2.1 → core-edu → content → msg → admin-portal
**总时间线**：49-64 天（约 10-13 周）
---
## §2 批次概览
| 批次 | 阶段 | 时间 | 参与AI | 完成信号 |
| ---- | ---------- | -------- | ------------------------------------ | ------------------ |
| 0 | coord 前置 | 3-5 天 | coord + ai13 | ✅ 2026-07-09 完成 |
| 1 | P2 | 7-10 天 | ai01 + ai06 + ai03 ⟷ ai13 | ⏳ 进行中 |
| 2 | P3 | 7-10 天 | ai07 + ai08 + ai04 ⟷ ai14 + ai03扩展 | ⏳ |
| 3 | P4 | 10-12 天 | ai09 + ai11 + ai05 ⟷ ai15 | ⏳ |
| 4 | P5 | 12-15 天 | ai10 ⟷ ai02 + ai12 + ai03扩展 | ⏳ |
| 5 | P6 | 10-12 天 | ai16 + 持续优化 | ⏳ |
---
## §3 批次 1（P2）详细排期
### 3.1 总甘特图
```mermaid
gantt
title 批次 1（P2）详细排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section ai01 api-gateway
1.1 路由表+双入口+shared-go接入 :a1a, 2026-07-10, 3d
1.2 JWT校验+JWKS fetcher :a1b, after a1a, 3d
1.3 限流+熔断+CORS :a1c, after a1b, 2d
section ai06 iam P2.1
6.1 gRPC server 50052启用 :crit, a6a, 2026-07-10, 2d
6.2 8 RPC实现(Register-GetChildrenByParent) :crit, a6b, after a6a, 4d
6.3 /readyz深度(5依赖检查) :a6c, after a6b, 1d
6.4 iam_student_guardians表+DataScope :a6d, after a6b, 1d
section ai03 teacher-bff
3.1 GraphQL schema第一版(ARB-001) :crit, a3a, 2026-07-10, 2d
3.2 Yoga endpoint+5 Query Resolver :crit, a3b, after a3a, 3d
3.3 DataLoader+N+1防御 :a3c, after a3b, 1d
3.4 ActionState信封+降级模式B :a3d, after a3b, 1d
3.5 /readyz探针列表 :a3e, after a3d, 1d
section ai13 teacher-portal
13.1 MF Shell配置(exposes+shared) :crit, a13a, 2026-07-10, 2d
13.2 GraphQLProvider+urql client单例 :crit, a13b, after a13a, 2d
13.3 AppShell改造(REST→GraphQL) :a13c, after a13b, 2d
13.4 登录页+Dashboard页+班级列表页 :a13d, after a13c, 2d
```
### 3.2 依赖关系
```
ai06.6.1 gRPC 启用 ──┬──> ai03.3.2 GraphQL Resolver（调用 iam gRPC）
└──> ai01.1.2 JWT 校验（调用 iam GetPublicKey）
ai03.3.1 schema 第一版 ──> ai13.13.2 GraphQLProvider（消费 schema）
ai03.3.2 Resolver ────────> ai13.13.3 AppShell 改造（viewports query）
ai01.1.1 路由表 ──> ai03.3.2 endpoint 对外可访问
└──> ai13.13.4 页面可访问
```
### 3.3 完成信号
批次 1 完成的 5 个标志：
1. ai06：iam gRPC 50052 启用 + 12 RPC 全部实现 + /readyz 返回 5 项依赖状态
2. ai01：api-gateway 路由 `/api/v1/teacher/*` → teacher-bff:3003 + JWKS 验签 + 限流
3. ai03：teacher-bff `POST /graphql` 可用 + 5 Query Resolver + DataLoader + ActionState
4. ai13：teacher-portal MF Shell 配置就绪 + 登录/Dashboard/班级列表页可用
5. 端到端：教师登录 → 看到 Dashboard（含班级列表 + 视口导航）
---
## §4 各 AI 工作清单（汇总）
> 详细排期见各模块 `_workline.md` 文件
### 4.1 ai01（api-gateway）
- P2：路由表 + JWT RS256 验签（JWKS） + 限流 + 熔断 + CORS + shared-go 接入
- 详见：[api-gateway_workline.md](./api-gateway_workline.md)
### 4.2 ai02（push-gateway）
- P5：HTTP /internal/* + Kafka 双通道 + 多设备会话隔离 + 审计表
- 详见：[push-gateway_workline.md](./push-gateway_workline.md)
### 4.3 ai03（teacher-bff）
- P2：GraphQL schema 第一版 + 5 Query Resolver + DataLoader + ActionState
- P3 扩展：exams/homework/grades Query + Mutation
- P5 扩展：notifications Query + SSE
- 详见：[teacher-bff_workline.md](./teacher-bff_workline.md)
### 4.4 ai04（student-bff）
- P3：GraphQL schema + Dashboard + 考试作答 + 作业提交
- 详见：[student-bff_workline.md](./student-bff_workline.md)
### 4.5 ai05（parent-bff）
- P4：GraphQL schema + Dashboard + 多子女切换 + 成绩趋势
- 详见：[parent-bff_workline.md](./parent-bff_workline.md)
### 4.6 ai06（iam）
- P2.1：gRPC 50052 + 12 RPC + /readyz 深度 + iam_student_guardians + DataScope
- P2.2：P3-P6 期间持续补充
- 详见：[iam_workline.md](./iam_workline.md)
### 4.7 ai07（classes → core-edu 交接）
- P3：classes 代码交接 + core-edu 服务骨架
- 详见：[core-edu_workline.md](./core-edu_workline.md)
### 4.8 ai08（core-edu）
- P3：gRPC 50053 + exams/homework/grades/attendance/class 全部 RPC + Outbox
- 详见：[core-edu_workline.md](./core-edu_workline.md)
### 4.9 ai09（content）
- P4：gRPC 50054 + textbook/chapter/knowledge-graph/question 4 service + Neo4j + ES
- 详见：[content_workline.md](./content_workline.md)
### 4.10 ai10（msg）
- P5：gRPC 50056 + notification/preference/template 3 service + Outbox
- 详见：[msg_workline.md](./msg_workline.md)
### 4.11 ai11（data-ana）
- P4：gRPC 50055 + 4 Dashboard + Warning + Mastery + ClickHouse + CDC 消费
- 详见：[data-ana_workline.md](./data-ana_workline.md)
### 4.12 ai12（ai 服务）
- P5：gRPC 50058 + Chat/GenerateQuestion/OptimizeExpression/LessonPlan + ES 检索
- 详见：[ai_workline.md](./ai_workline.md)
### 4.13 ai13（teacher-portal）
- P2：MF Shell + AppShell + GraphQL client + 登录/Dashboard/班级列表
- P3：考试/作业/成绩页面 + MF Remote 就绪
- 详见：[teacher-portal_workline.md](./teacher-portal_workline.md)
### 4.14 ai14（student-portal）
- P3：MF Remote + 考试作答 + 作业提交
- 详见：[student-portal_workline.md](./student-portal_workline.md)
### 4.15 ai15（parent-portal）
- P4：MF Remote + Dashboard + 多子女切换
- 详见：[parent-portal_workline.md](./parent-portal_workline.md)
### 4.16 ai16（admin-portal）
- P6：MVP + 用户管理 + 角色权限 + 审计日志
- 详见：[admin-portal_workline.md](./admin-portal_workline.md)
---
## §5 工作流说明
### 5.1 各 AI 写入 `_workline.md`
各 AI 在自己模块的 `[模块名]_workline.md` 中写入甘特图排期，格式：
````markdown
# [模块名] 工作排期
## §1 总览
[模块职责简述]
## §2 甘特图
```mermaid
gantt
title [模块名] 工作排期
dateFormat YYYY-MM-DD
...
```
````
## §3 详细任务
### [阶段] [任务编号]：[任务名]
- 负责人：aiXX
- 依赖：[前置任务]
- 交付物：[具体文件/功能]
- 验收标准：[验收点]
```
### 5.2 coord 汇总
coord 审阅各 `_workline.md` 后，在本文件（workline.md）汇总：
- §1 总时间线（16 AI 甘特图）
- §2 批次概览
- §3 当前批次详细排期
- §4 各 AI 工作清单（链接到各 `_workline.md`）
### 5.3 更新时机
- 批次启动前：coord 写入 §3 当前批次详细排期
- 批次进行中：各 AI 更新自己的 `_workline.md`（标记完成进度）
- 批次完成后：coord 更新 §2 完成信号 + §1 总进度
```

45
docs/architecture/issues/worklines/admin-portal_workline.md Normal file
View File

@@ -0,0 +1,45 @@
# admin-portal 工作排期
> 负责人：ai16
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/admin-portal_contract.md](../contracts/admin-portal_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
admin-portal 是管理端微前端，通过 MF Remote 接入主应用，覆盖用户管理、角色权限、审计日志等场景。全阶段目标：P2 MF Remote 骨架 → P3 用户管理+角色权限+审计日志 → P4-P6 持续优化。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai16 admin-portal 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2-P6
[阶段任务] :a16a, 2026-07-10, Xd
```
> **注意**：以上为 coord 初始规划，ai16 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### 全阶段任务
- **负责人**：ai16
- **交付物**：⚠️ 由 ai16 自行补充
- **依赖**：见 [contracts/admin-portal_contract.md](../contracts/admin-portal_contract.md)
- **验收标准**：⚠️ 由 ai16 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：⚠️ 由 ai16 自行补充（见 contract.md）
- **我的就绪信号**：⚠️ 由 ai16 自行补充

45
docs/architecture/issues/worklines/ai_workline.md Normal file
View File

@@ -0,0 +1,45 @@
# ai 工作排期
> 负责人：ai12
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/ai_contract.md](../contracts/ai_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
ai 是智能服务，提供 AiService（6 个 RPC），结合 Elasticsearch 检索与 LLM 网关实现智能问答与推荐。全阶段目标：P2 ES 接入+LLM 网关 → P3 AiService 6 RPC → P4-P6 持续优化。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai12 ai 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2-P6
[阶段任务] :a12a, 2026-07-10, Xd
```
> **注意**：以上为 coord 初始规划，ai12 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### 全阶段任务
- **负责人**：ai12
- **交付物**：⚠️ 由 ai12 自行补充
- **依赖**：见 [contracts/ai_contract.md](../contracts/ai_contract.md)
- **验收标准**：⚠️ 由 ai12 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：⚠️ 由 ai12 自行补充（见 contract.md）
- **我的就绪信号**：⚠️ 由 ai12 自行补充

57
docs/architecture/issues/worklines/api-gateway_workline.md Normal file
View File

@@ -0,0 +1,57 @@
# api-gateway 工作排期
> 负责人：ai01
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/api-gateway_contract.md](../contracts/api-gateway_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
api-gateway 是 Edu 系统统一入口，负责路由、JWT 验签、限流、熔断、CORS。全阶段目标：P2 路由+JWT → P3 限流加固 → P4-P6 持续优化。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai01 api-gateway 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2 基础
路由表+双入口+shared-go :a1a, 2026-07-10, 3d
JWT校验+JWKS fetcher :a1b, after a1a, 3d
限流+熔断+CORS :a1c, after a1b, 2d
section P3-P6 持续优化
路由扩展(student/parent/admin) :a1d, after a1c, 2d
指标+链路加固 :a1e, after a1d, 2d
```
> **注意**：以上为 coord 初始规划，ai01 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### P2：路由表 + JWT + 限流
- **负责人**：ai01
- **交付物**：
- `services/api-gateway/internal/routing/router.go` — 路由表
- `/api/v1/teacher/*` → teacher-bff:3003 代理
- `/api/v1/iam/*` → iam:3002 代理
- JWT RS256 验签（shared-go/jwks）
- 限流 + 熔断 + CORS
- **依赖**：shared-go 骨架（批次 0 已完成）+ iam GetPublicKey（ai06）
- **验收标准**：路由双入口 + JWT 验签 + 限流 + CORS 白名单
- **完整 P3-P6 任务**：⚠️ 由 ai01 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：iam GetPublicKey RPC（ai06）
- **我的就绪信号**：api-gateway :8080 可访问 + JWT 验签可用

107
docs/architecture/issues/worklines/classes_workline.md Normal file
View File

@@ -0,0 +1,107 @@
# classes 工作排期
> 负责人：ai07
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/classes_contract.md](../contracts/classes_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
> 特殊说明：classes 是黄金模板（P1 已实现），P3 合并入 core-edu（ai08 接管）
---
## §1 总览
classes 是 Edu 微服务的黄金模板，P1 阶段已实现班级 CRUD + 全横切关注点。P3 阶段合并入 core-edu 后，classes 模块代码由 ai08 接管维护，但黄金模板对照 checklist 由 ai07 持续维护。
**全阶段目标**：
- P1（已完成）：班级 CRUD + 黄金模板 + 6 项整改
- P3：合并入 core-edu + Outbox + gRPC + DataScope + Redis 缓存 + cuid2 迁移
- P6：黄金模板 checklist 持续维护 + 硬化
---
## §2 全阶段甘特图（P1-P6）
```mermaid
gantt
title ai07 classes 黄金模板全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P1 黄金模板整改
阶段1+2架构设计文档 :crit, a7a, 2026-07-10, 1d
typeorm移除+tracer修复+@Query替换 :crit, a7b, 2026-07-10, 1d
测试覆盖率60→80%+Dockerfile升级 :a7c, 2026-07-11, 1d
schema索引补齐 :a7d, 2026-07-11, 1d
section P3 合并入core-edu
shared/outbox目录补齐 :a7e, 2026-07-14, 2d
cuid2迁移+DataScope注入 :a7f, 2026-07-15, 2d
Redis缓存+软删除+分页 :a7g, 2026-07-17, 3d
gRPC 50053启用+核心edu合并 :a7h, 2026-07-20, 2d
section P6 硬化
黄金模板checklist持续维护 :a7i, 2026-07-25, 5d
可观测性增强+告警规则 :a7j, 2026-07-30, 3d
```
---
## §3 详细任务
### P1：黄金模板整改（立即）
| # | 任务 | 交付物 | 验收标准 | 状态 |
| --- | ----------------------------------- | ------------------------------------------------------------------------- | --------------------------------- | --------- |
| 1 | 阶段 1+2 架构设计文档 | `services/classes/docs/01-understanding.md` + `02-architecture-design.md` | coord 交叉审查通过 | ✅ 已完成 |
| 2 | 移除 typeorm 冗余依赖 | `package.json` 删除 typeorm 行 | `pnpm install` 零错误 | 待执行 |
| 3 | tracer.ts console.log → logger.info | `src/shared/observability/tracer.ts` L20 | grep `console.log` 返回 0 | 待执行 |
| 4 | controller list @Req → @Query | `src/classes/classes.controller.ts` L49-53 | list 方法用 `@Query('gradeId')` | 待执行 |
| 5 | 测试覆盖率阈值 60% → 80% | `vitest.config.ts` + 补测试用例 | `pnpm test:coverage` 达 80% | 待执行 |
| 6 | Dockerfile node:20 → node:22 | `Dockerfile` | 基础镜像 `node:22-alpine` | 待执行 |
| 7 | schema 补齐索引 | `classes.schema.ts` + 迁移脚本 | grade_id / head_teacher_id 有索引 | 待执行 |
### P3：合并入 core-edu（交接给 ai08）
| # | 任务 | 交付物 | 验收标准 | 状态 |
| --- | ------------------------- | ---------------------------------------------------------- | ------------------------------- | ------ |
| 1 | `shared/outbox/` 目录补齐 | outbox.repository / outbox.publisher / outbox.relay-worker | 事件可发布到 Kafka | 待执行 |
| 2 | cuid2 迁移 | id 字段 uuid v4 → cuid2 + 数据迁移脚本 | 双写过渡期完成 | 待执行 |
| 3 | DataScope 6 级 WHERE 注入 | Repository list 方法接收 dataScope 参数 | 6 级过滤生效 | 待执行 |
| 4 | Redis 班级列表缓存 | cachedList 方法 + TTL 5 分钟 + 事件失效 | 缓存命中率 > 80% | 待执行 |
| 5 | 软删除 + 审计字段 | deleted_at / created_by / updated_by | DELETE 改软删除 | 待执行 |
| 6 | 分页 + 批量查询 | 游标分页 + POST /classes/batch | proto page_size/page_token 落地 | 待执行 |
| 7 | gRPC server 50053 启用 | ClassService 5 RPC 实现 | gRPC health check SERVING | 待执行 |
| 8 | PermissionGuard 改调 iam | 动态权限查询 getEffectivePermissions | 角色变更无需改代码重启 | 待执行 |
### P6：硬化
| # | 任务 | 交付物 | 验收标准 | 状态 |
| --- | --------------------------- | ---------------------------------- | ---------------- | ------ |
| 1 | 黄金模板 checklist 持续维护 | 02-architecture-design.md §10 更新 | 覆盖全部新模式 | 待执行 |
| 2 | 可观测性增强 | 日志注入 traceId + Outbox 积压告警 | Grafana 面板可用 | 待执行 |
---
## §4 依赖与就绪信号
- **我依赖**：
- MySQL classes_db（P1 已就绪）
- api-gateway 路由注册（P1 已就绪）
- P3：iam `BatchGetUsers` + `getEffectivePermissions`
- P3：Kafka 基础设施（ai08 启用）
- **我的就绪信号**：
- P1：REST API 5 端点 + /healthz + /readyz + /metrics 可用（已就绪）
- P3：gRPC 50053 + Outbox 事件发布 + Redis 缓存可用
- **交接信号**：P3 合并时，ai07 向 ai08 交接 classes 模块，交接清单见 02-architecture-design.md §11
---
## §5 交接计划（ai07 → ai08）
| 交接项 | 内容 | 时间 |
| ------------------ | ------------------------------------------------------- | --------- |
| 源码交接 | `services/classes/src/` 全部源码 | P3 启动时 |
| 文档交接 | `services/classes/docs/` 2 份设计文档 | P3 启动时 |
| proto 交接 | `classes.proto` 由 core-edu 实现承载 | P3 启动时 |
| 黄金模板保留 | `services/classes/` 保留作只读对照基准（待 coord 仲裁） | P3 合并后 |
| checklist 持续维护 | ai07 持续维护 02-architecture-design.md §10 | 跨阶段 |

45
docs/architecture/issues/worklines/content_workline.md Normal file
View File

@@ -0,0 +1,45 @@
# content 工作排期
> 负责人：ai09
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/content_contract.md](../contracts/content_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
content 是内容服务，提供 TextbookService、ChapterService、KnowledgeGraphService、QuestionService，结合 Neo4j 知识图谱与 Elasticsearch 全文检索。全阶段目标：P2 服务骨架+Neo4j+ES → P3 四大 Service 实现 → P4-P6 持续优化。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai09 content 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2-P6
[阶段任务] :a9a, 2026-07-10, Xd
```
> **注意**：以上为 coord 初始规划，ai09 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### 全阶段任务
- **负责人**：ai09
- **交付物**：⚠️ 由 ai09 自行补充
- **依赖**：见 [contracts/content_contract.md](../contracts/content_contract.md)
- **验收标准**：⚠️ 由 ai09 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：⚠️ 由 ai09 自行补充（见 contract.md）
- **我的就绪信号**：⚠️ 由 ai09 自行补充

45
docs/architecture/issues/worklines/core-edu_workline.md Normal file
View File

@@ -0,0 +1,45 @@
# core-edu 工作排期
> 负责人：ai08
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/core-edu_contract.md](../contracts/core-edu_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
core-edu 是教学核心服务，提供 ClassService、ExamService、HomeworkService、GradeService、AttendanceService，并基于 Outbox 模式发布领域事件。全阶段目标：P2 服务骨架+Outbox → P3 五大 Service 实现 → P4-P6 持续优化。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai08 core-edu 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2-P6
[阶段任务] :a8a, 2026-07-10, Xd
```
> **注意**：以上为 coord 初始规划，ai08 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### 全阶段任务
- **负责人**：ai08
- **交付物**：⚠️ 由 ai08 自行补充
- **依赖**：见 [contracts/core-edu_contract.md](../contracts/core-edu_contract.md)
- **验收标准**：⚠️ 由 ai08 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：⚠️ 由 ai08 自行补充（见 contract.md）
- **我的就绪信号**：⚠️ 由 ai08 自行补充

45
docs/architecture/issues/worklines/data-ana_workline.md Normal file
View File

@@ -0,0 +1,45 @@
# data-ana 工作排期
> 负责人：ai11
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/data-ana_contract.md](../contracts/data-ana_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
data-ana 是数据分析服务，提供 AnalyticsService（12 个 RPC），基于 ClickHouse 列存查询与 CDC 消费实现实时分析。全阶段目标：P2 ClickHouse 接入+CDC 消费 → P3 AnalyticsService 12 RPC → P4-P6 持续优化。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai11 data-ana 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2-P6
[阶段任务] :a11a, 2026-07-10, Xd
```
> **注意**：以上为 coord 初始规划，ai11 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### 全阶段任务
- **负责人**：ai11
- **交付物**：⚠️ 由 ai11 自行补充
- **依赖**：见 [contracts/data-ana_contract.md](../contracts/data-ana_contract.md)
- **验收标准**：⚠️ 由 ai11 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：⚠️ 由 ai11 自行补充（见 contract.md）
- **我的就绪信号**：⚠️ 由 ai11 自行补充

56
docs/architecture/issues/worklines/iam_workline.md Normal file
View File

@@ -0,0 +1,56 @@
# iam 工作排期
> 负责人：ai06
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/iam_contract.md](../contracts/iam_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
iam 是身份认证服务，全阶段目标：gRPC 50052 + 12 RPC + /readyz 深度 + iam_student_guardians + DataScope + 审计日志 + Outbox。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai06 iam 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2.1 核心
gRPC server 50052启用 :crit, a6a, 2026-07-10, 2d
12 RPC实现 :crit, a6b, after a6a, 4d
/readyz深度(5依赖) :a6c, after a6b, 1d
iam_student_guardians+DataScope :a6d, after a6b, 1d
section P2.2-P6 扩展
审计日志+Outbox :a6e, after a6d, 3d
持续补全 :a6f, after a6e, 5d
```
> **注意**：以上为 coord 初始规划，ai06 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### P2.1：gRPC + 12 RPC + /readyz + DataScope
- **负责人**：ai06
- **交付物**：
- gRPC server 50052 + 12 RPC（见 iam.proto）
- /readyz 5 项依赖检查
- iam_student_guardians 表 + DataScope=CHILDREN
- **依赖**：iam.proto（批次 0 已完成）
- **验收标准**：12 RPC 全部可用 + /readyz 返回 5 项状态
- **完整 P2.2-P6 任务**：⚠️ 由 ai06 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：无（iam 是基础服务）
- **我的就绪信号**：gRPC 50052 启用 + GetPublicKey RPC 可用 + HealthService.Check 返回 SERVING

45
docs/architecture/issues/worklines/msg_workline.md Normal file
View File

@@ -0,0 +1,45 @@
# msg 工作排期
> 负责人：ai10
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/msg_contract.md](../contracts/msg_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
msg 是消息服务，提供 NotificationService、PreferenceService、TemplateService，并基于 Outbox 模式发布消息事件。全阶段目标：P2 服务骨架+Outbox → P3 三大 Service 实现 → P4-P6 持续优化。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai10 msg 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2-P6
[阶段任务] :a10a, 2026-07-10, Xd
```
> **注意**：以上为 coord 初始规划，ai10 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### 全阶段任务
- **负责人**：ai10
- **交付物**：⚠️ 由 ai10 自行补充
- **依赖**：见 [contracts/msg_contract.md](../contracts/msg_contract.md)
- **验收标准**：⚠️ 由 ai10 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：⚠️ 由 ai10 自行补充（见 contract.md）
- **我的就绪信号**：⚠️ 由 ai10 自行补充

45
docs/architecture/issues/worklines/parent-bff_workline.md Normal file
View File

@@ -0,0 +1,45 @@
# parent-bff 工作排期
> 负责人：ai05
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/parent-bff_contract.md](../contracts/parent-bff_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
parent-bff 为家长端提供 GraphQL 聚合 API，覆盖 Dashboard、多子女切换、成绩趋势等场景。全阶段目标：P2 GraphQL schema 骨架 → P3 Dashboard+多子女+成绩趋势 → P4-P6 持续优化。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai05 parent-bff 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2-P6
[阶段任务] :a5a, 2026-07-10, Xd
```
> **注意**：以上为 coord 初始规划，ai05 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### 全阶段任务
- **负责人**：ai05
- **交付物**：⚠️ 由 ai05 自行补充
- **依赖**：见 [contracts/parent-bff_contract.md](../contracts/parent-bff_contract.md)
- **验收标准**：⚠️ 由 ai05 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：⚠️ 由 ai05 自行补充（见 contract.md）
- **我的就绪信号**：⚠️ 由 ai05 自行补充

45
docs/architecture/issues/worklines/parent-portal_workline.md Normal file
View File

@@ -0,0 +1,45 @@
# parent-portal 工作排期
> 负责人：ai15
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/parent-portal_contract.md](../contracts/parent-portal_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
parent-portal 是家长端微前端，通过 MF Remote 接入主应用，覆盖 Dashboard、多子女切换等场景。全阶段目标：P2 MF Remote 骨架 → P3 Dashboard+多子女切换 → P4-P6 持续优化。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai15 parent-portal 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2-P6
[阶段任务] :a15a, 2026-07-10, Xd
```
> **注意**：以上为 coord 初始规划，ai15 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### 全阶段任务
- **负责人**：ai15
- **交付物**：⚠️ 由 ai15 自行补充
- **依赖**：见 [contracts/parent-portal_contract.md](../contracts/parent-portal_contract.md)
- **验收标准**：⚠️ 由 ai15 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：⚠️ 由 ai15 自行补充（见 contract.md）
- **我的就绪信号**：⚠️ 由 ai15 自行补充

45
docs/architecture/issues/worklines/push-gateway_workline.md Normal file
View File

@@ -0,0 +1,45 @@
# push-gateway 工作排期
> 负责人：ai02
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/push-gateway_contract.md](../contracts/push-gateway_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
push-gateway 负责长连接接入（HTTP /internal/* + WebSocket/SSE）与多设备会话管理，配合审计表实现消息推送可观测。全阶段目标：P2 HTTP+WS 接入 → P3 多设备会话 → P4-P6 审计与加固。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai02 push-gateway 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2-P6
[阶段任务] :a2a, 2026-07-10, Xd
```
> **注意**：以上为 coord 初始规划，ai02 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### 全阶段任务
- **负责人**：ai02
- **交付物**：⚠️ 由 ai02 自行补充
- **依赖**：见 [contracts/push-gateway_contract.md](../contracts/push-gateway_contract.md)
- **验收标准**：⚠️ 由 ai02 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：⚠️ 由 ai02 自行补充（见 contract.md）
- **我的就绪信号**：⚠️ 由 ai02 自行补充

45
docs/architecture/issues/worklines/student-bff_workline.md Normal file
View File

@@ -0,0 +1,45 @@
# student-bff 工作排期
> 负责人：ai04
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/student-bff_contract.md](../contracts/student-bff_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
student-bff 为学生端提供 GraphQL 聚合 API，覆盖 Dashboard、考试作答、作业提交等场景。全阶段目标：P2 GraphQL schema 骨架 → P3 Dashboard+考试+作业聚合 → P4-P6 持续优化。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai04 student-bff 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2-P6
[阶段任务] :a4a, 2026-07-10, Xd
```
> **注意**：以上为 coord 初始规划，ai04 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### 全阶段任务
- **负责人**：ai04
- **交付物**：⚠️ 由 ai04 自行补充
- **依赖**：见 [contracts/student-bff_contract.md](../contracts/student-bff_contract.md)
- **验收标准**：⚠️ 由 ai04 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：⚠️ 由 ai04 自行补充（见 contract.md）
- **我的就绪信号**：⚠️ 由 ai04 自行补充

45
docs/architecture/issues/worklines/student-portal_workline.md Normal file
View File

@@ -0,0 +1,45 @@
# student-portal 工作排期
> 负责人：ai14
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/student-portal_contract.md](../contracts/student-portal_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
student-portal 是学生端微前端，通过 MF Remote 接入主应用，覆盖考试作答、作业提交等场景。全阶段目标：P2 MF Remote 骨架 → P3 考试作答+作业提交 → P4-P6 持续优化。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai14 student-portal 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2-P6
[阶段任务] :a14a, 2026-07-10, Xd
```
> **注意**：以上为 coord 初始规划，ai14 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### 全阶段任务
- **负责人**：ai14
- **交付物**：⚠️ 由 ai14 自行补充
- **依赖**：见 [contracts/student-portal_contract.md](../contracts/student-portal_contract.md)
- **验收标准**：⚠️ 由 ai14 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：⚠️ 由 ai14 自行补充（见 contract.md）
- **我的就绪信号**：⚠️ 由 ai14 自行补充

58
docs/architecture/issues/worklines/teacher-bff_workline.md Normal file
View File

@@ -0,0 +1,58 @@
# teacher-bff 工作排期
> 负责人：ai03
> 关联：[workline.md](../workline.md)、[coord.md §1 ARB-001](../coord.md)、[contracts/teacher-bff_contract.md](../contracts/teacher-bff_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
teacher-bff 是教学场景域聚合层，全阶段目标：P2 GraphQL schema 第一版 → P3 扩展 exams/homework/grades → P4 学情分析 → P5 通知+SSE → P6 admin 命名空间。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai03 teacher-bff 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2 GraphQL 基础
schema第一版(ARB-001) :crit, a3a, 2026-07-10, 2d
Yoga endpoint+5 Query Resolver :crit, a3b, after a3a, 3d
DataLoader+N+1防御 :a3c, after a3b, 1d
ActionState信封+降级模式B :a3d, after a3b, 1d
section P3-P6 扩展
exams/homework/grades Query :a3e, after a3d, 3d
学情分析+通知+SSE :a3f, after a3e, 4d
admin命名空间 :a3g, after a3f, 2d
```
> **注意**：以上为 coord 初始规划，ai03 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### P2：GraphQL schema + 5 Query + DataLoader + ActionState
- **负责人**：ai03
- **交付物**：
- `packages/shared-ts/contracts/graphql/teacher-bff.graphql` — P2 schema
- Yoga endpoint `POST /graphql`
- 5 Query：dashboard / viewports / me / classes / class
- DataLoader + ActionState 信封 + 降级模式 B
- **依赖**：iam gRPC（ai06）+ coord 仲裁 ARB-001
- **验收标准**：5 Query 可用 + ActionState 信封 + depth ≤ 7
- **完整 P3-P6 任务**：⚠️ 由 ai03 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：iam gRPC 50052（ai06）+ core-edu gRPC 50053（ai08，P3+）
- **我的就绪信号**：POST /graphql 可用 + dashboard Query 返回正确数据

170
docs/architecture/issues/worklines/teacher-portal_workline.md Normal file
View File

@@ -0,0 +1,170 @@
# teacher-portal 工作排期
> 负责人：ai13
> 关联：[workline.md](../workline.md)、[coord.md §2 ARB-002](../coord.md)、[contracts/teacher-portal_contract.md](../contracts/teacher-portal_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，开发期间用 mock，最后统一集成测试）
> 依据：president-final-rulings.md §3.5（ai13 P2 功能范围）+ §7.13（ai13 工作内容最终清单）+ 03-long-term-architecture.md §1.1 阶段能力累积矩阵
---
## §1 总览
teacher-portal 是教学场景域微前端（MF Shell），全阶段目标：P2 MF Shell + GraphQL client + 基础页面 → P3 考试/作业/成绩 → P4 知识图谱/学情 → P5 推送/AI → P6 可观测性硬化。
**全并行模式**：ai13 一口气完成 P2-P6 全部代码，开发期间用 MSW mock 上游（teacher-bff GraphQL / api-gateway HTTP / push-gateway WebSocket），上游就绪后在 [matrix.md](../matrix.md) §8 更新就绪信号，最后统一集成测试。
---
## §2 全阶段甘特图（P2-P6）
```mermaid
gantt
title ai13 teacher-portal 全阶段排期（全并行）
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2 基础
packages骨架(ui-tokens/ui-components/hooks) :crit, a13p0, 2026-07-09, 1d
MF Shell配置(NextFederationPlugin) :crit, a13a, after a13p0, 2d
GraphQLProvider+urql client单例 :crit, a13b, after a13a, 2d
AppShell+路由骨架+设计令牌三层 :a13c, after a13b, 2d
登录页+权限上下文+Token存储 :a13d, after a13c, 2d
Dashboard框架+班级列表+学生列表+个人设置 :a13e, after a13d, 3d
section P3 教学核心
考试管理页面(列表/创建/详情) :a13f, after a13e, 3d
作业管理页面(布置/批改) :a13g, after a13f, 3d
成绩管理页面(录入/分析) :a13h, after a13g, 2d
乐观更新+多Tab会话同步 :a13i, after a13h, 2d
section P4 知识与学情
知识图谱可视化页面 :a13j, after a13i, 3d
学情分析仪表盘(宽表5s) :a13k, after a13j, 3d
parent-portal Remote接入 :a13l, after a13k, 1d
section P5 推送与AI
WebSocket通知中心 :a13m, after a13l, 2d
AI辅助出题(SSE流式) :a13n, after a13m, 3d
AI生成教案/学情报告 :a13o, after a13n, 2d
section P6 硬化
Sentry+RUM+OTel browser :a13p, after a13o, 2d
A11y审计(WCAG 2.2 AA) :a13q, after a13p, 2d
性能优化+bundle门禁 :a13r, after a13q, 2d
localStorage→httpOnly Cookie迁移 :a13s, after a13r, 1d
```
---
## §3 详细任务
### P2：MF Shell + GraphQL client + 基础页面
- **负责人**：ai13
- **裁决依据**：总裁裁决 §3.5（ai13 P2 功能范围）+ F9（GraphQL P2 起）+ F12（localStorage token）+ §2.17（MF GraphQL client 单例方案 A）+ §2.18（packages 批次 0.15）
- **交付物**：
- ✅ packages 骨架（ui-tokens/ui-components/hooks，批次 0.15 已完成）
- NextFederationPlugin 配置（exposes AppShell + shared react/urql/graphql singleton，无 remotes）
- GraphQLProvider + urql client 单例（Shell 暴露，Remote 复用，§2.17 方案 A）
- AppShell（Layout + 侧边栏 + 路由守卫 + ErrorBoundary + 设计令牌三层 primitive/semantic/tailwind-theme）
- 登录页（POST /api/auth/login → JWT 存 localStorage，F12）
- 权限上下文（usePermission + useViewports，权限点 `<RESOURCE>_<ACTION>` F7）
- Dashboard 框架（teacherDashboard GraphQL query）
- 班级列表页（myClasses GraphQL query，iam 数据）
- 学生列表页（classStudents GraphQL query，iam 数据）
- 个人设置页（currentUser + updateUser GraphQL query/mutation）
- **依赖**：teacher-bff GraphQL schema 第一版（ai03 + coord 仲裁 ISSUE-037）+ api-gateway 路由（ai01）
- **Mock 策略**：MSW 拦截 POST /api/teacher/graphql + POST /api/auth/login（见 contract.md §4.2）
- **验收标准**：MF 配置不破坏单体 + GraphQL 拉取数据 + 登录→Dashboard→班级列表→学生列表链路通
### P3：考试/作业/成绩 + 乐观更新 + 多 Tab 同步
- **负责人**：ai13
- **交付物**：
- 考试管理页面（classExams list / createExam mutation / examDetail）
- 作业管理页面（classHomework list / assignHomework mutation / homeworkDetail / 批改界面）
- 成绩管理页面（studentGrades list / recordGrade mutation / 成绩分析图表）
- 乐观更新（useMutation onMutate 回滚 + invalidateQueries，见 03 §10.1）
- 多 Tab 会话同步（BroadcastChannel('edu-session')，见 03 §2.5）
- **依赖**：teacher-bff 扩展 core-edu gRPC 调用（ai03 P3，core-edu ai08 P3 启用 gRPC）
- **Mock 策略**：MSW 返回固定考试/作业/成绩数据
- **验收标准**：教师创建考试→学生（student-portal Remote）作答→教师批改全链路（mock）+ 乐观更新回滚正确 + 多 Tab 登出同步
### P4：知识图谱 + 学情分析 + parent-portal Remote
- **负责人**：ai13
- **交付物**：
- 知识图谱可视化页面（recharts/d3 节点图，CSR + @next/dynamic 懒加载）
- 学情分析仪表盘（宽表 5s 返回，ISR revalidate 60s + CSR 交互）
- parent-portal Remote 接入（MF remotes 配置，feature flag NEXT_PUBLIC_MF_ENABLED）
- **依赖**：teacher-bff 扩展 content/data-ana gRPC 调用（ai03 P4，content ai09 P4 / data-ana ai11 P4 启用 gRPC）+ parent-portal（ai15 P4）
- **Mock 策略**：MSW 返回固定知识图谱 + 学情宽表数据
- **验收标准**：教师查看知识图谱 + 学情宽表 5s 返回（mock）+ parent-portal Remote 在 Shell 内渲染
### P5：WebSocket 推送 + AI 辅助 + 通知中心
- **负责人**：ai13
- **交付物**：
- WebSocket 通知中心（ws://push-gateway:8081/ws，实时通知 + BroadcastChannel 跨 Tab）
- AI 辅助出题（SSE 流式，generateQuestion subscription）
- AI 生成教案/学情报告（generateLessonPlan / generateReport mutation）
- **依赖**：push-gateway WebSocket（ai02 P5）+ ai 服务 gRPC（ai12 P5 启用 gRPC）+ msg 服务（ai10 P5）
- **Mock 策略**：mock-socket 模拟 WS 推送 + MSW 返回固定 AI 响应（SSE 用 ReadableStream mock）
- **验收标准**：全校广播实时到达（mock）+ AI 流式出题（mock）+ 通知中心实时更新
### P6：可观测性硬化 + A11y + 性能 + Token 迁移
- **负责人**：ai13
- **交付物**：
- Sentry 错误追踪 + Session Replay（NEXT_PUBLIC_SENTRY_DSN + beforeSend PII 过滤）
- Web Vitals RUM（LCP/INP/CLS/TTFB → /api/v1/admin/web-vitals）
- OTel browser SDK（自动埋点 fetch/XHR/document load → OTLP collector）
- A11y 审计（WCAG 2.2 AA：eslint-plugin-jsx-a11y + @axe-core/playwright + 对比度审计）
- 性能优化（bundle analyzer + size-limit CI 门禁：Shell <150KB / Remote <80KB / CSS <50KB）
- localStorage → httpOnly Cookie 迁移（iam refresh cookie 端点就绪后 + CSRF 防护）
- **依赖**：全链路可观测就绪（iam refresh cookie + Sentry DSN + OTel collector）
- **验收标准**：99.9% 可用 + WCAG 2.2 AA + LCP <2.5s / INP <200ms / CLS <0.1（P75）
---
## §4 依赖与就绪信号
### §4.1 我依赖的上游就绪标志
| 上游 | 就绪标志 | 阻塞阶段 | 状态 |
| --------------------------------------------------------- | ------------------------------------------------- | -------- | ---------------------- |
| packages 骨架（ai13 自建） | ui-tokens/ui-components/hooks 可 import | P2 启动 | ✅ 已就绪（批次 0.15） |
| teacher-bff GraphQL schema（ai03 + coord 仲裁 ISSUE-037） | packages/shared-ts/contracts/graphql/ 第一版 | P2 启动 | ⏳ 待 coord 仲裁 |
| api-gateway HTTP :8080（ai01） | /api/teacher/graphql + /api/auth/login 路由可用 | P2 启动 | ⏳ 待 ai01 |
| teacher-bff core-edu 扩展（ai03 P3） | classExams/classHomework/studentGrades query 可用 | P3 启动 | ⏳ 待 ai03 P3 |
| teacher-bff content/data-ana 扩展（ai03 P4） | knowledgeGraph/studentAnalytics query 可用 | P4 启动 | ⏳ 待 ai03 P4 |
| push-gateway WebSocket :8081/ws（ai02 P5） | WS 连接可建立 + 推送可接收 | P5 启动 | ⏳ 待 ai02 P5 |
| ai 服务 gRPC（ai12 P5） | generateQuestion/generateLessonPlan 可调 | P5 启动 | ⏳ 待 ai12 P5 |
| iam refresh cookie 端点（ai06 P6） | POST /iam/auth/refresh 返回 httpOnly cookie | P6 启动 | ⏳ 待 ai06 P6 |
### §4.2 我的就绪信号（供下游消费）
| 信号 | 就绪标志 | 消费方 |
| ------------------------------- | -------------------------------------- | ---------------------------------- |
| teacher-portal dev server :4000 | next dev -p 4000 可访问 | 无（最前端） |
| MF Shell 可加载 | 首页渲染 AppShell + 导航 | student/parent/admin Remote（P3+） |
| 登录流程可用 | POST /api/auth/login → JWT → Dashboard | 无（最前端） |
| GraphQL 查询可执行 | currentUser/myClasses 返回数据 | 无（最前端） |
| parent-portal Remote 接入点 | MF remotes 配置就绪 | parent-portal（ai15 P4） |
---
## §5 全并行开发说明
按 [matrix.md](../matrix.md) §全并行模式：
1. ai13 一口气完成 P2-P6 全部代码，开发期间用 MSW mock 上游
2. 上游就绪后在 matrix.md §8 更新就绪信号
3. 所有模块就绪后统一集成测试（matrix.md §9 检查清单）
4. Mock 切换：NEXT_PUBLIC_API_MOCKING=enabled → disabled
---
**AI Agent**: ai13（teacher-portal）
**Branch**: feat/teacher-portal-workline-ai13
**Coordinator**: coord-ai