lofyerandfactory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
b9fbd4c6af
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
5.8 KiB
5.8 KiB
厂商数据中台与校园平台对接说明
1. 目标
两端产品使用同一组业务标识核对记录，但各自负责不同的工作和数据：
- 厂商端负责数据源、采集、质量、数据产品发布、学校交付和交付回执；
- 校园端负责学校接收、校内验收、分析快照、专业诊断、改进执行、报告审批和使用反馈；
- 厂商默认不能读取学校明文业务数据，学校反馈只提交明确授权的汇总影响和脱敏证据。
2. 共享样板场景
| 实体 | 样板标识 | 主责端 |
|---|---|---|
| 演示场景 | SCN-CLOSED-LOOP-001 |
两端 |
| 学校租户 | TENANT-HZVTC |
平台租户服务 |
| 数据产品版本 | V2026.08.23 |
厂商端 |
| 数据包 | EDU-PKG-20260823-01 |
厂商端 |
| 发布候选 | REL-20260823-01 |
厂商端 |
| 杭州租户数据文件 | 2,846,320 条 / SHA-256 4f8d91a47e2b6d82b2aaad136d344d61c83f9cd472185d2543725c91870e9e32 |
厂商端 |
| 学校交付 | DELIVERY-HZVTC-20260823-01 |
厂商端 |
| 学校接收回执 | RCT-HZVTC-20260823-01 |
校园端 |
| 分析快照 | SNP-HZVTC-20260824-01 |
校园端 |
| 企业需求 | DEM-HKVS-20260823-01 |
校园端/企业 |
| 专业建议 | REC-SOFTWARE-20260823-01 |
校园端 |
| 改进任务 | TSK-SOFTWARE-20260823-01 |
校园端 |
| 合作项目 | PRJ-HKVS-20260823-01 |
校园端 |
| 执行证据 | EVD-HKVS-01… |
校园端 |
| 企业评价 | EVL-HKVS-20260823-01 |
企业 |
| 报告版本 | RPT-HZVTC-20260823-01 |
校园端 |
| 使用反馈 | FBK-EMP-01 |
校园端 |
| 下一周期复核 | RVW-SOFTWARE-2027C1-01 |
校园端 |
每个共享对象必须携带 tenant_id、trace_id、状态、创建/更新时间、创建/修改人和关联对象标识。
3. 状态边界
厂商发布和学校接收必须分开
ReleaseCandidate
DRAFT → QUALITY_PASSED → AWAITING_APPROVAL
→ APPROVED → PUBLISHED → ROLLED_BACK
Delivery（每所学校独立）
PENDING → SENDING → DELIVERED
→ ACKNOWLEDGED | FAILED → RETRYING
ACKNOWLEDGED → ROLLED_BACK
“数据包已发布”只表示厂商稳定版本已生成，不能直接显示“学校已收到”。厂商端只有 FIX_REPLAY 的记录数、规则结果和独立复核签名全部通过检查后才可继续发布；WAIVE、DISCARD 仍不能发布。学校回执中的租户、包号、版本、记录数、完整 SHA-256 和授权范围全部通过后，交付才能进入 ACKNOWLEDGED。
交付记录数和学校分析快照样本量是不同口径：样板杭州租户文件为 2,846,320 条，校园端验收后生成 128,642 条有效分析快照，不能互相覆盖。
校园业务流程
DeliveryReceipt
PENDING → VERIFIED → ACCEPTED → ACTIVATED
EnterpriseDemand
SUBMITTED → RECEIVED → ANALYZED → RESPONDED → CLOSED
Recommendation
PENDING → ACCEPTED | DEFERRED | REJECTED
ImprovementTask
TODO → IN_PROGRESS → READY_FOR_REVIEW
→ ACCEPTED | RETURNED → CLOSED
ReportVersion
DRAFT → REVIEWING → APPROVED | RETURNED
APPROVED → PUBLISHED
UsageReview
BASELINE → FOLLOW_UP → IMPROVED | UNCHANGED | WORSENED
每次状态迁移都必须产生不可变审计事件，包含操作者、前后状态、时间、意见、证据和 trace_id。
4. 静态原型能做什么
两个静态页面分别使用自己的浏览器本地状态，只用于刷新后继续当前页面的演示：
- 厂商端本地状态不能让校园端自动变化；
- 校园端本地状态不能让厂商端自动变化；
- 页面必须明确“未连接后端，不代表另一端已实时收到”；
- 两端相同的固定 ID 只用于人工核对业务链，不等于网络同步。
需要展示两个页面之间的数据交接时，使用可下载、可导入的文件：
- 厂商导出 Manifest 和交付信封 JSON；
- 学校导入后校验文件哈希与租户授权；
- 学校导出接收回执或脱敏反馈 JSON；
- 厂商导入回执/反馈后更新对应交付或处置状态。
正式系统由 API、消息和 Outbox/Webhook 完成幂等交接，不使用浏览器本地存储同步业务状态。
5. 正式服务边界
| 服务 | 关键职责 |
|---|---|
| Data Product API | 数据包生成、质量检查、审批、发布和回滚 |
| Entitlement & Delivery API | 租户授权、逐学校交付、重试、撤回 |
| Receipt API | 幂等接收回执、记录数和哈希校验 |
| Campus Ingestion API | 学校暂存、质量校验、业务审批、激活和回滚 |
| Analysis API | 使用不可修改的数据版本生成分析快照 |
| Collaboration API | 需求、建议、项目、任务、证据、评价和验收 |
| Report API | 报告版本、审批、发布、下载和证据引用 |
| Feedback API | 学校反馈、厂商处置、学校复验和关闭 |
| Audit & Notification | 统一追踪、不可篡改审计、通知和超时升级 |
大文件只通过对象存储短期签名地址传递，业务 API 不直接传输数据包或附件正文。
6. 验收顺序
- 厂商完成质量处置并创建
REL-20260823-01； - 独立审批人批准后发布
EDU-PKG-20260823-01； - 为三所学校创建彼此隔离的租户交付，重点核对
TENANT-HZVTC的DELIVERY-HZVTC-20260823-01； - 学校校验租户、包号、版本、Manifest、记录数与完整 SHA-256，生成
RCT-HZVTC-20260823-01； - 学校激活版本并生成
SNP-HZVTC-20260824-01； - 企业需求进入专业诊断，建议被采纳并产生关联任务和项目；
- 执行人员提交证据，企业导师评价，校级管理者完成验收；
- 报告由不同于提交人的校级管理者审批并发布，所有结论反查同一快照和证据；
- 就业或业务部门记录使用反馈和下一周期指标；
- 两端以共享 ID 核对发布、交付、接收、使用和反馈链，正式环境再通过 API 自动同步。