xiaoqu_mcp_service/xiaoqu-agent-service/doc/crm-sync-integration-progress.md

SaaS MCP → 小趣 AI 经营系统对接进度

MCP 系统独立进度入口。最后核对：2026-09-15；当前字段扩展位于codex/mcp-source-domain-identity分支。

本文只记录 xiaoqu_mcp_service 的责任和状态。小趣 AI / CRM 的规则、事项、AI、页面与推送进度，以其仓库 PROJECT.md 为准。

1. 两个系统的边界

系统	必须负责	明确不负责
SaaS MCP	服务身份、源租户/数据域、工具授权、源系统行级权限、用户/物业/合同标准变化流、稳定游标、审计与标准错误	到期规则、经营优先级、AI决策、经营事项状态机、销售页面、APNs推送
小趣 AI / CRM	租户连接、数据镜像、身份与客户映射、确定性规则、仅把命中数据交给AI、事项生成/流转、展示、操作、反馈、推送前复核	猜测源租户、绕过MCP权限、兼容不符合冻结Schema的错误字段

双方唯一连接面是版本化接口契约：integration.context.get、三条 *.changes.list、contracts.current.batch_get、统一错误信封，以及真实端到端验收。任何一侧内部实现都不能成为另一侧的隐式依赖。

2. 当前结论

当前状态：协议可连接，基础公开字段Schema已部署；合同展示上下文字段已完成代码和回归、待合并部署；可靠同步与服务身份仍未通过，不能用于真实销售合同到期推送。

交付状态：三条变化流和发送前复核代码已经合入主线并部署；生产sync作用域尚未绑定contracts.current.batch_get。本轮新增的property_name/customer_no/customer_name/owner_name仍待合并部署。

已经具备：

• MCP Streamable HTTP 会话、SSE响应和Schema v2信封。
• X-Open-Key 管理、服务Token签发、Token作用域、工具白名单、审计和限流。
• integration.context.get。
• users.changes.list、properties.changes.list、contracts.changes.list及统一分页框架。
• contracts.current.batch_get发送前批量回源复核已在本地实现；沿用SYNC身份、权限、限流和审计边界。
• 基于 (modify_time, id) 的分页、软删标记、错误码和基础单元测试。

尚未通过的不是“小趣AI页面问题”，而是MCP公开数据契约与可靠同步语义。小趣AI侧不得通过放宽校验来掩盖这些问题。

3. 已确认问题与处理顺序

P0-1 服务身份与源数据域语义混淆

代码核对结论：当前SaaS业务库没有统一的tenant_id字段。人员、物业、合同处于同一个业务数据域，在线行权限由代理商、物业和销售关系计算；合同负责人由contract_new.sale_id表达。不能为了对接新增一个虚假的行级租户字段。

现状仍有两个独立问题：integration.context.get.tenant_id由作用域编码拼接得到，sync被误当成数据域；服务Token又按serviceName + scope全局复用，创建它的Open Client身份没有进入Token。作用域只代表“能用什么工具”，不是数据来源或调用方身份。

影响：消费者无法稳定识别数据来自哪套SaaS实例；不同Open Client使用相同serviceName时可能复用服务Token。它不会替代合同负责人分发，但会影响连接隔离、吊销和审计。

标准改造：

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；吊销其中一个不影响另一个；上下文返回稳定源数据域；小趣AI连接错配源数据域时在同步前失败关闭。

P0-2 三条变化流公开字段Schema（本地已修正，待部署联调）

原实现与冻结契约的差异：

流	当前输出	必须输出
users	mobile；数值型user_id/organization_ids	verified_mobile；字符串型稳定ID；状态使用公开枚举
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、布尔提醒标记、实际提醒天数，以及property_name/customer_no/customer_name/owner_name展示字段

已完成：新增独立公开DTO，将三类稳定ID统一为字符串；mobile改为verified_mobile；合同状态转换为公开枚举；expire_remind转换为布尔值；补齐remind_days；变化页使用统一stream字段。合同DTO继续补齐property_name/customer_no/customer_name/owner_name，这些字段只用于展示、AI解释和人工核对，身份关联与权限仍只认稳定ID。未知合同状态按DATA_INTEGRITY_ERROR失败关闭，不伪造业务语义。

验证：合并最新主分支后，Java编译、管理前端构建及MCP服务全量229项测试通过，0失败、0错误。尚需部署后的真实数据样例和小趣Gateway严格消费者契约联调，完成前仍不算生产通过。

验收：用真实样例对三条流执行消费者契约测试；Gateway无需兼容代码即可全部通过，未知字段、未知状态和错误类型必须失败。

P0-3 当前“快照”不能保证重放稳定

现状：令牌只保存cutoff，每页仍直接查询持续变化的业务表。分页期间，cutoff之前的记录被修改、删除或权限变化时，相同sync_token + cursor + limit可能得到不同结果；秒级modify_time也可能漏掉同一行在边界秒内的再次修改。

影响：合同规模扩大或同步期间发生业务写入时，存在漏数、重复、记录消失和重放不一致风险，达不到文档声称的“不重不漏”。

标准改造：建立通用变更日志/Outbox（每次变更拥有单调递增change_seq，保存实体ID、操作类型、版本和必要投影），同步窗口按change_seq冻结；游标按change_seq推进。若使用CDC，也必须落成可保留、可重放的变化流，不能直接分页扫活表冒充快照。

验收：同步中并发更新、删除、负责人变更、权限变更以及相同请求重放时，旧快照结果不变，新变化只进入下一轮；压测覆盖成千上万合同。

P0-4 交接Token错误复用了24小时快照TTL

现状：轮内快照Token、页游标和已完成轮的next_sync_token统一执行24小时TTL。

影响：每日任务只要稍晚、停机或积压，就可能被迫全量重建；数据量增大后会形成周期性全量压力。

标准改造：只给轮内快照/游标设置短TTL；交接Token按变更日志保留期校验，或保存持久化消费位点。过期时返回可观测的最早可用位置及标准错误，消费者执行受控重建。

验收：间隔超过24小时仍可正常增量；只有位点早于服务端保留期才触发重建。

P0-5 数据权限版本不能覆盖真实权限变化

现状：data_scope_version仅取token_scope关系的修改时间；Open Client身份关联、scope-tool变化、源数据域ACL变化不会稳定反映。

影响：权限变化后旧同步位点可能继续使用，消费者无法判断需要重建或停止派发。

标准改造：维护数据域授权版本，任何调用方身份关联、工具授权、行级ACL语义变更都原子递增；上下文与同步Token使用同一个版本。

验收：修改任一影响可见数据的授权后，旧轮立即失败关闭，新轮在新数据域版本下重建。

P0-6 发送前权威复核（本地已实现，待部署联调）

已实现contracts.current.batch_get：一次读取1—200份合同当前事实，按输入顺序返回已找到记录，并明确返回not_found_ids；软删记录不会伪装成“查无数据”。该工具沿用SYNC服务身份，禁止调用方覆盖数据域，使用SYNC独立限流档并进入统一审计。

小趣AI侧已经按同一契约实现短时发送凭证：只有状态、到期日、负责人、客户归属、提醒字段及续约结果与本地候选一致才允许R04进入推送；缺失、删除、字段变化、响应不完整或MCP不可用均失败关闭，R03不受影响。

尚未完成：生产sync作用域还必须绑定该新工具；需要用真实合同验证负责人变更、删除、到期日修改和服务不可用四类反向场景。

4. 依赖顺序

1. 冻结服务端source_domain_id配置、单数据域范围和合同状态/提醒字段字典。
2. 完成Open Client与服务Token身份关联，补迁移、ensure和上下文测试。
3. 建立通用变更日志/Outbox与保留策略，再迁移三条变化流；不继续强化活表分页方案。
4. 使用独立公开DTO完成三条流字段映射和消费者契约测试。
5. 修正交接Token生命周期与统一数据权限版本。
6. 在测试环境用真实用户、物业、合同及变更/删除数据完成MCP侧验收。
7. 交付Open Client、稳定源数据域ID和凭证给小趣AI侧，联合验证“同步→映射→规则→事项→展示→推送前复核”。

5. 状态看板

工作项	状态	责任系统	下一步
MCP协议与工具发现	已完成	MCP	保持兼容并纳入回归
服务密钥与Token基础生命周期	已完成	MCP	在租户模型完成后升级幂等键
源数据域标识与服务主体隔离	未完成，P0阻塞	MCP	增加稳定部署数据域标识和Open Client关联
三流公开字段Schema	基础字段已部署；合同展示字段待合并部署	MCP	部署后用真实三流样例跑Gateway严格契约测试
发送前合同当前状态批量复核	代码已部署、生产scope未开放	MCP + 小趣AI	绑定sync作用域并完成四类真实反向用例
可靠变化日志与稳定快照	未完成，P0阻塞	MCP	设计Outbox/CDC及保留策略
权限版本与交接位点生命周期	未完成，P0阻塞	MCP	与租户/变化日志模型一起实现
小趣AI连接与消费代码	已完成，待部署联调	小趣AI	见小趣AI仓库PROJECT.md
真实销售合同到期推送	未开放	双方联合验收	所有P0通过后才允许从Shadow转Live

6. 发布门禁

以下条件全部满足前，不得把MCP同步标记为生产可用，也不得向真实销售发送合同提醒：

• 稳定源数据域、服务主体隔离和连接错配反向用例通过。
• 三条变化流通过冻结Schema及真实数据样例校验。
• 并发写入、删除、断点续传、超过24小时续传和权限变化测试通过。
• 凭证不入库明文、不入日志；轮换和吊销测试通过。
• 小趣AI侧完成负责人、客户双映射和发送前实时复核。
• 完整链路具有request_id/snapshot_id/source_domain_id审计证据，可定位每条事项和推送的数据来源。