docs: ai 协作文档体系重构与多 ai 仲裁结果落地
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
229
docs/architecture/issues/matrix.md
Normal file
229
docs/architecture/issues/matrix.md
Normal 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 推送到前端
|
||||
Reference in New Issue
Block a user