feat(mcp): 增量同步框架与 users/properties/contracts changes 工具 (REQ-20260911-0013) #12

2026-09-14T12:19:56+08:00

wangheng commented

2026-09-14 12:19:56 +08:00

范围

通用 changes 引擎：快照 data_cutoff_at 钉住、(modify_time,id) 复合游标、仅末页签发 next_sync_token、软删 tombstone、注册式实体扩展
三个 changes 工具：users/properties/contracts.changes.list（m0/m2 只读，sync scope）
硬约束：禁止 tenant_id/scope 入参（PERMISSION_DENIED），数据域仅从 Token 推导
隔离：SYNC 独立限流档 + limit≤200 截断 + 慢查询超时
contract.list.query 补 12 字段、detail.query 补 version（ACL 不变）
Flyway V5 + rollback

验证

194 单测全绿
test-up.sh 冒烟通过；tools/list 恰 4 工具；翻页续传/增量轮/篡改 token→SYNC_CURSOR_EXPIRED 实测通过

## 范围 - 通用 changes 引擎：快照 data_cutoff_at 钉住、(modify_time,id) 复合游标、仅末页签发 next_sync_token、软删 tombstone、注册式实体扩展 - 三个 changes 工具：users/properties/contracts.changes.list（m0/m2 只读，sync scope） - 硬约束：禁止 tenant_id/scope 入参（PERMISSION_DENIED），数据域仅从 Token 推导 - 隔离：SYNC 独立限流档 + limit≤200 截断 + 慢查询超时 - contract.list.query 补 12 字段、detail.query 补 version（ACL 不变） - Flyway V5 + rollback ## 验证 - 194 单测全绿 - test-up.sh 冒烟通过；tools/list 恰 4 工具；翻页续传/增量轮/篡改 token→SYNC_CURSOR_EXPIRED 实测通过

wangheng added 1 commit 2026-09-14 12:19:56 +08:00

feat(mcp): 增量同步框架与 users/properties/contracts changes 工具 (REQ-20260911-0013) 6639b93c45

- 通用 ChangesEngine：snapshot 钉住 data_cutoff_at、(modify_time,id) 复合游标、
  仅最后一页签发 next_sync_token、软删 tombstone；sync_token/cursor 为
  HMAC-SHA256 无状态令牌（SyncTokenCodec），过期/篡改/跨快照/数据域变更
  统一 SYNC_CURSOR_EXPIRED
- 注册式实体扩展：SyncEntity/Registry + users(m0.user)/properties(m0.properyt)/
  contracts(m2.contract_new) 三个实现；生效修改时间 COALESCE(modify_time, create_time)
- 硬约束：GuardedToolCallback 对 *.changes.list 拒绝 tenant_id/scope 入参，
  数据域只从 Token 推导；行级权限复用 PermissionService 与 QUERY 工具同一 ACL
- 资源隔离：RateLimitService SYNC/QUERY 分档限流（Redis 固定分钟窗）、
  limit≤200 截断、SyncQueryTimeoutInterceptor 慢查询超时（三套 SqlSessionFactory 接入）
- contract.list.query 补齐 12 字段、contract.detail.query 补 version（ACL 不变）
- V5 migration：tool.description 512→1024（含 sql/rollback 回滚文件）
- seed-dev.sql：三个 changes 工具绑定进 sync 作用域
- 修复：properyt.customerId 为 NULL 时 Collectors.toMap NPE（冒烟命中），
  改为 put 逐条装填（ContractsSyncEntity/ContractTools）

wangheng merged commit e408768fe5 into main

2026-09-14 12:20:05 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangheng/xiaoqu_mcp_service#12