fix(sync): align public change stream schema
This commit is contained in:
jiashumeng
@@ -15,7 +15,7 @@
|
||||
|
||||
## 2. 当前结论
|
||||
|
||||
当前状态：**协议可连接，业务契约未通过，不能用于真实销售合同到期推送。**
|
||||
当前状态：**协议可连接，公开字段Schema已在本地修正并通过回归；可靠同步与服务身份仍未通过，不能用于真实销售合同到期推送。**
|
||||
|
||||
已经具备：
|
||||
|
||||
@@ -29,24 +29,27 @@
|
||||
|
||||
## 3. 已确认问题与处理顺序
|
||||
|
||||
### P0-1 服务身份没有绑定真实源租户
|
||||
### P0-1 服务身份与源数据域语义混淆
|
||||
|
||||
现状：`integration.context.get.tenant_id`由作用域编码拼接得到，`sync`被当成租户；服务Token又按`serviceName + scope`全局复用，创建它的Open Client身份没有进入Token。作用域代表“能用什么工具”，不是“属于哪个租户/数据域”。
|
||||
代码核对结论：当前SaaS业务库没有统一的`tenant_id`字段。人员、物业、合同处于同一个业务数据域，在线行权限由代理商、物业和销售关系计算；合同负责人由`contract_new.sale_id`表达。不能为了对接新增一个虚假的行级租户字段。
|
||||
|
||||
影响：不能证明某个小趣租户连接的是哪个SaaS数据域，也不能可靠阻止不同接入方复用同一服务身份。
|
||||
现状仍有两个独立问题：`integration.context.get.tenant_id`由作用域编码拼接得到，`sync`被误当成数据域；服务Token又按`serviceName + scope`全局复用，创建它的Open Client身份没有进入Token。作用域只代表“能用什么工具”，不是数据来源或调用方身份。
|
||||
|
||||
影响：消费者无法稳定识别数据来自哪套SaaS实例；不同Open Client使用相同`serviceName`时可能复用服务Token。它不会替代合同负责人分发，但会影响连接隔离、吊销和审计。
|
||||
|
||||
标准改造：
|
||||
|
||||
1. 为Open Client建立不可变的`source_tenant_id`（或等价数据域ID）绑定，不从请求体、scope或名称推断。
|
||||
2. 服务Token持久化`open_client_id + source_tenant_id + subject_name`，ensure按该组合幂等签发。
|
||||
3. `integration.context.get.tenant_id`返回真实`source_tenant_id`；`subject_id`返回稳定服务主体ID。
|
||||
4. 每条SYNC查询都从鉴权上下文取得该数据域并强制过滤；若当前源库确实只有单一数据域，也必须以明确配置和测试证明，不能用“user为空即查全库”表达。
|
||||
1. 为每套MCP部署配置稳定的`source_domain_id`，例如生产SaaS数据域标识；它来自服务端配置，不由请求体、scope或名称推断。
|
||||
2. 服务Token持久化`open_client_id + subject_name`，ensure按调用方、服务主体和scope组合幂等签发；不同Open Client不共享Token。
|
||||
3. `integration.context.get`返回稳定`source_domain_id`。若为保持既有契约继续输出`tenant_id`，必须明确该字段在当前单数据域SaaS中表示“源数据域”，不能再返回`sync`。
|
||||
4. SYNC服务Token读取该单一数据域的完整变化流；记录按合同`owner_user_id`分发。在线个人查询继续使用现有人员ACL，两条通道不混用。
|
||||
5. 小趣AI的租户连接负责把自己的`tenant_id`显式绑定到该`source_domain_id`，禁止同一个源数据域被误配给多个目标租户。
|
||||
|
||||
验收：两个Open Client即使使用相同`serviceName=crm`也得到不同服务Token和租户上下文；跨租户数据为零；吊销其中一个不影响另一个。
|
||||
验收：两个Open Client即使使用相同`serviceName=crm`也得到不同服务Token；吊销其中一个不影响另一个；上下文返回稳定源数据域；小趣AI连接错配源数据域时在同步前失败关闭。
|
||||
|
||||
### P0-2 三条变化流不符合冻结字段Schema
|
||||
### P0-2 三条变化流公开字段Schema（本地已修正，待部署联调）
|
||||
|
||||
现状与冻结契约的差异：
|
||||
原实现与冻结契约的差异：
|
||||
|
||||
| 流 | 当前输出 | 必须输出 |
|
||||
|---|---|---|
|
||||
@@ -54,9 +57,9 @@
|
||||
| properties | 数值型`property_id` | 字符串型稳定ID；状态使用公开枚举 |
|
||||
| contracts | 数值型`contract_id/property_id/owner_user_id`、数值状态`0..4`、数值`expire_remind`，缺`remind_days` | 字符串型稳定ID、`PENDING/REJECTED/ACTIVE/EXPIRED/TERMINATED/VOID`、布尔提醒标记、实际提醒天数 |
|
||||
|
||||
影响：小趣Gateway的严格Schema校验会正确拒绝当前users和contracts数据；合同不会进入镜像、规则和推送链路。
|
||||
已完成：新增独立公开DTO，将三类稳定ID统一为字符串；`mobile`改为`verified_mobile`；合同状态转换为公开枚举；`expire_remind`转换为布尔值；补齐`remind_days`；变化页使用统一`stream`字段。未知合同状态按`DATA_INTEGRITY_ERROR`失败关闭，不伪造业务语义。
|
||||
|
||||
标准改造：在MCP边界使用独立DTO/枚举映射，将老库字段一次性转换成公开Schema；公开契约不得直接泄漏数据库整数状态和Java实体类型。没有权威来源的可选字段保持空，不伪造。
|
||||
验证：Java编译和MCP服务全量测试通过，`220`项测试、`0`失败、`0`错误。尚需部署后的真实数据样例和小趣Gateway严格消费者契约联调，完成前仍不算生产通过。
|
||||
|
||||
验收：用真实样例对三条流执行消费者契约测试；Gateway无需兼容代码即可全部通过，未知字段、未知状态和错误类型必须失败。
|
||||
|
||||
@@ -82,23 +85,23 @@
|
||||
|
||||
### P0-5 数据权限版本不能覆盖真实权限变化
|
||||
|
||||
现状：`data_scope_version`仅取`token_scope`关系的修改时间；Open Client租户绑定、scope-tool变化、源数据域ACL变化不会稳定反映。
|
||||
现状：`data_scope_version`仅取`token_scope`关系的修改时间；Open Client身份关联、scope-tool变化、源数据域ACL变化不会稳定反映。
|
||||
|
||||
影响：权限变化后旧同步位点可能继续使用，消费者无法判断需要重建或停止派发。
|
||||
|
||||
标准改造：维护数据域授权版本，任何租户绑定、工具授权、行级ACL语义变更都原子递增；上下文与同步Token使用同一个版本。
|
||||
标准改造：维护数据域授权版本，任何调用方身份关联、工具授权、行级ACL语义变更都原子递增；上下文与同步Token使用同一个版本。
|
||||
|
||||
验收：修改任一影响可见数据的授权后，旧轮立即失败关闭，新轮在新数据域版本下重建。
|
||||
|
||||
## 4. 依赖顺序
|
||||
|
||||
1. 冻结真实`source_tenant_id`来源、数据域范围和合同状态/提醒字段字典。
|
||||
2. 完成服务身份与源租户持久化模型，补迁移、后台配置、ensure和上下文测试。
|
||||
1. 冻结服务端`source_domain_id`配置、单数据域范围和合同状态/提醒字段字典。
|
||||
2. 完成Open Client与服务Token身份关联，补迁移、ensure和上下文测试。
|
||||
3. 建立通用变更日志/Outbox与保留策略，再迁移三条变化流；不继续强化活表分页方案。
|
||||
4. 使用独立公开DTO完成三条流字段映射和消费者契约测试。
|
||||
5. 修正交接Token生命周期与统一数据权限版本。
|
||||
6. 在测试环境用真实用户、物业、合同及变更/删除数据完成MCP侧验收。
|
||||
7. 交付Open Client、真实源租户ID和凭证给小趣AI侧，联合验证“同步→映射→规则→事项→展示→推送前复核”。
|
||||
7. 交付Open Client、稳定源数据域ID和凭证给小趣AI侧，联合验证“同步→映射→规则→事项→展示→推送前复核”。
|
||||
|
||||
## 5. 状态看板
|
||||
|
||||
@@ -106,8 +109,8 @@
|
||||
|---|---|---|---|
|
||||
| MCP协议与工具发现 | 已完成 | MCP | 保持兼容并纳入回归 |
|
||||
| 服务密钥与Token基础生命周期 | 已完成 | MCP | 在租户模型完成后升级幂等键 |
|
||||
| 真实源租户与服务主体隔离 | 未完成，P0阻塞 | MCP | 明确权威租户来源并设计迁移 |
|
||||
| 三流公开字段Schema | 未完成，P0阻塞 | MCP | 建立DTO和状态字典，跑消费者契约测试 |
|
||||
| 源数据域标识与服务主体隔离 | 未完成，P0阻塞 | MCP | 增加稳定部署数据域标识和Open Client关联 |
|
||||
| 三流公开字段Schema | 本地代码完成，待部署联调 | MCP | 部署后用真实三流样例跑Gateway严格契约测试 |
|
||||
| 可靠变化日志与稳定快照 | 未完成，P0阻塞 | MCP | 设计Outbox/CDC及保留策略 |
|
||||
| 权限版本与交接位点生命周期 | 未完成，P0阻塞 | MCP | 与租户/变化日志模型一起实现 |
|
||||
| 小趣AI连接与消费代码 | 已完成，待部署联调 | 小趣AI | 见小趣AI仓库`PROJECT.md` |
|
||||
@@ -117,9 +120,9 @@
|
||||
|
||||
以下条件全部满足前，不得把MCP同步标记为生产可用，也不得向真实销售发送合同提醒：
|
||||
|
||||
- 真实源租户隔离、服务主体隔离和跨租户反向用例通过。
|
||||
- 稳定源数据域、服务主体隔离和连接错配反向用例通过。
|
||||
- 三条变化流通过冻结Schema及真实数据样例校验。
|
||||
- 并发写入、删除、断点续传、超过24小时续传和权限变化测试通过。
|
||||
- 凭证不入库明文、不入日志；轮换和吊销测试通过。
|
||||
- 小趣AI侧完成负责人、客户双映射和发送前实时复核。
|
||||
- 完整链路具有`request_id/snapshot_id/source_tenant_id`审计证据，可定位每条事项和推送的数据来源。
|
||||
- 完整链路具有`request_id/snapshot_id/source_domain_id`审计证据，可定位每条事项和推送的数据来源。
|
||||
|
||||
Reference in New Issue
Block a user