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>
127 lines
5.8 KiB
Markdown
127 lines
5.8 KiB
Markdown
# 厂商数据中台与校园平台对接说明
|
||
|
||
## 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. 状态边界
|
||
|
||
### 厂商发布和学校接收必须分开
|
||
|
||
```text
|
||
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` 条有效分析快照，不能互相覆盖。
|
||
|
||
### 校园业务流程
|
||
|
||
```text
|
||
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 只用于人工核对业务链，不等于网络同步。
|
||
|
||
需要展示两个页面之间的数据交接时，使用可下载、可导入的文件：
|
||
|
||
1. 厂商导出 Manifest 和交付信封 JSON；
|
||
2. 学校导入后校验文件哈希与租户授权；
|
||
3. 学校导出接收回执或脱敏反馈 JSON；
|
||
4. 厂商导入回执/反馈后更新对应交付或处置状态。
|
||
|
||
正式系统由 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. 验收顺序
|
||
|
||
1. 厂商完成质量处置并创建 `REL-20260823-01`；
|
||
2. 独立审批人批准后发布 `EDU-PKG-20260823-01`；
|
||
3. 为三所学校创建彼此隔离的租户交付，重点核对 `TENANT-HZVTC` 的 `DELIVERY-HZVTC-20260823-01`；
|
||
4. 学校校验租户、包号、版本、Manifest、记录数与完整 SHA-256，生成 `RCT-HZVTC-20260823-01`；
|
||
5. 学校激活版本并生成 `SNP-HZVTC-20260824-01`；
|
||
6. 企业需求进入专业诊断，建议被采纳并产生关联任务和项目；
|
||
7. 执行人员提交证据，企业导师评价，校级管理者完成验收；
|
||
8. 报告由不同于提交人的校级管理者审批并发布，所有结论反查同一快照和证据；
|
||
9. 就业或业务部门记录使用反馈和下一周期指标；
|
||
10. 两端以共享 ID 核对发布、交付、接收、使用和反馈链，正式环境再通过 API 自动同步。
|