Edu/docs/architecture/issues/matrix.md

上下游对接总矩阵

维护者：coord（协调 AI） 关联：coord.md、workline.md、各模块 contracts/ 模式：全并行开发（各 AI 一口气完成 P2-P6，开发期间用 mock，最后统一集成测试）

---

§1 服务依赖矩阵（谁调用谁）

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 错误码前缀矩阵 + 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 推送到前端