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

docs(docs): coord 完成 15 模块 issue 仲裁与基础设施同步

Browse Source 
coord.md 新增 ARB-019/020/021 三章仲裁章节，修正 ARB-001。

- coord.md: 新增 ARB-019/020/021（student/parent/admin-portal 24 项）
- coord.md: 修正 ARB-001（admin P2 预留/schema 文件名/classes 数据源）
- 004 §4: 依赖图加 PBFF→DataAna+Msg
- 004 §7.2: push-gateway→Redis 软失败标注
- 004 §11.4: 错误码前缀矩阵（11 服务+i18n key）
- 004 §11.5: ActionState 信封规范（降级模式方案 B）
- matrix §1: 依赖矩阵加 PBFF 边
- matrix §2: 移除 api-gateway 为 iam gRPC 消费方
- matrix §4: admin-portal→teacher-bff
- matrix §5: 移除 /sse+鉴权头统一
- matrix §6: 错误码表补 i18n key 列
- 15 个 issue.md: 仲裁结论回写
- push-gateway_contract: 移除 /sse+鉴权头改 X-Internal-Token
- packages/contracts: 新建包 ADMIN_* 权限点常量

AI: coord
This commit is contained in:
SpecialX
2026-07-10 16:30:51 +08:00
parent df62ffc176
commit c179af64a6
22 changed files with 2320 additions and 382 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
docs/architecture/issues/matrix.md
View File

@@ -63,6 +63,8 @@ graph TB
PBFF --> IAM
PBFF --> CORE
PBFF --> DATA
PBFF --> MSG
PGW --> MSG
@@ -81,14 +83,14 @@ graph TB
## §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 | ⏳ |
| 提供方 | gRPC 端口 | Service | RPC 数 | 消费方 | 就绪信号 | 状态 |
| --------------- | --------- | --------------------------------------------------------------------------------- | ------ | ------------------------------------------- | ----------------------------- | ---- |
| iam (ai06) | 50052 | IamService | 12 | teacher-bff / student-bff / parent-bff | 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 | ⏳ |
---
@@ -108,7 +110,7 @@ graph TB
| --------------- | --------------------------- | ----------------------------------------------------- | --------------------------------------------------------- | ------- | ---- |
| 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 | ✅ | ⏳ |
| iam (ai06) | edu.iam.audit.created | AuditEvent（create/update/delete/login/logout） | teacher-bff | ✅ | ⏳ |
| 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 | ✅ | ⏳ |
@@ -123,36 +125,37 @@ graph TB
## §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 | 无 | ⏳ |
| 提供方 | 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 / admin-portal | JWT | ⏳ |
| push-gateway (ai02) | POST | /internal/push | 内部推送入口 | msg | X-Internal-Token | ⏳ |
| 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 |
> 详见 [004 §11.4](../004_architecture_impact_map.md) 错误码前缀矩阵 + i18n key 映射规则
| 模块 | 前缀 | i18n key 模式 | 示例 |
| ------------ | ------------ | ------------------------------- | -------------------------------------------------- |
| api-gateway | GW_ | error.gateway.\<code_snake\> | GW_UNAUTHORIZED / GW_RATE_LIMITED |
| push-gateway | PUSH_ | error.push.\<code_snake\> | PUSH_DEVICE_NOT_FOUND / PUSH_CHANNEL_FAILED |
| teacher-bff | BFF_TEACHER_ | error.bffTeacher.\<code_snake\> | BFF_TEACHER_UNAUTHORIZED / BFF_TEACHER_BAD_GATEWAY |
| student-bff | BFF_STUDENT_ | error.bffStudent.\<code_snake\> | BFF_STUDENT_UNAUTHORIZED |
| parent-bff | BFF_PARENT_ | error.bffParent.\<code_snake\> | BFF_PARENT_CHILD_NOT_BOUND |
| iam | IAM_ | error.iam.\<code_snake\> | IAM_USER_NOT_FOUND / IAM_INVALID_CREDENTIALS |
| core-edu | CORE_EDU_ | error.core_edu.\<code_snake\> | CORE_EDU_EXAM_NOT_FOUND |
| content | CONTENT_ | error.content.\<code_snake\> | CONTENT_QUESTION_NOT_FOUND |
| msg | MSG_ | error.msg.\<code_snake\> | MSG_NOTIFICATION_NOT_FOUND |
| data-ana | DATA_ANA_ | error.data_ana.\<code_snake\> | DATA_ANA_DASHBOARD_UNAVAILABLE |
| ai | AI_ | error.ai.\<code_snake\> | AI_GENERATION_FAILED / AI_QUOTA_EXCEEDED |
---