# 上下游对接总矩阵

> 维护者：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
    PBFF --> DATA
    PBFF --> MSG

    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      | 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）       | 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                           | ✅      | ⏳   |
| 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/v1/* | 反向代理 teacher-bff | teacher-portal                                                 | JWT              | ⏳   |
| api-gateway (ai01)  | *      | /api/v1/student/v1/* | 反向代理 student-bff | student-portal                                                 | JWT              | ⏳   |
| api-gateway (ai01)  | *      | /api/v1/parent/v1/*  | 反向代理 parent-bff  | parent-portal                                                  | JWT              | ⏳   |
| api-gateway (ai01)  | *      | /api/v1/iam/v1/*     | 反向代理 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 错误码前缀矩阵

> 详见 [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           |

---

## §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 推送到前端
