docs: align sync catalog and checklists after Z14c

Document schema/fingerprint APIs, quote SMS Provider off, and refresh the联调意见 commit trail.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
whm
2026-08-05 18:33:13 +08:00
parent bb59bb5efd
commit 2a7da53769
4 changed files with 79 additions and 83 deletions

View File

@@ -52,7 +52,7 @@ postgres://user:pass@127.0.0.1:5432/app_online?sslmode=disable
同号硬约束:宇恒手机 = 公司成员手机(联调样例 **`13531041944`**)→ 必须询问「已有账号是否绑定」;**勿用**超管号 `13531041945` 同号硬约束:宇恒手机 = 公司成员手机(联调样例 **`13531041944`**)→ 必须询问「已有账号是否绑定」;**勿用**超管号 `13531041945`
**试运行**`SMS.RequireForBind=false`(或 `Provider=off`)关闭绑定短信;仍须确认。正式接短信后改为 `true`。宇恒可先 `GET /api/v1/auth/bind/policy``trial_mode` / `yuheng_ticket_enabled` **试运行**`SMS.RequireForBind=false``Provider: "off"`**须加引号**,裸 `off` 会被 YAML 当成布尔导致 platform 起不来)。正式接短信后改为 `RequireForBind: true` 且 Provider 非 `"off"`。宇恒可先 `GET /api/v1/auth/bind/policy``trial_mode` / `yuheng_ticket_enabled`
换票 / 自查: 换票 / 自查:

View File

@@ -84,6 +84,9 @@ var Catalog = []Entry{
{Method: "POST", Path: "/api/v1/agent/sync/channels/{id}/push/batch", OperationID: "agentSyncPushBatch", Summary: "批量推送(同上鉴权)", Group: "agent"}, {Method: "POST", Path: "/api/v1/agent/sync/channels/{id}/push/batch", OperationID: "agentSyncPushBatch", Summary: "批量推送(同上鉴权)", Group: "agent"},
{Method: "POST", Path: "/api/v1/agent/sync/channels/{id}/pull", OperationID: "agentSyncPull", Summary: "从线上 A 下行bootstrap/rows/pks", Group: "agent"}, {Method: "POST", Path: "/api/v1/agent/sync/channels/{id}/pull", OperationID: "agentSyncPull", Summary: "从线上 A 下行bootstrap/rows/pks", Group: "agent"},
{Method: "POST", Path: "/api/v1/agent/sync/channels/{id}/bootstrap", OperationID: "agentSyncBootstrap", Summary: "全量灌库别名mode=bootstrap", Group: "agent"}, {Method: "POST", Path: "/api/v1/agent/sync/channels/{id}/bootstrap", OperationID: "agentSyncBootstrap", Summary: "全量灌库别名mode=bootstrap", Group: "agent"},
{Method: "POST", Path: "/api/v1/agent/sync/channels/{id}/schema", OperationID: "agentSyncSchema", Summary: "拉线上表结构(含空表 columns", Group: "agent"},
{Method: "POST", Path: "/api/v1/agent/sync/channels/{id}/schema/ensure", OperationID: "agentSyncSchemaEnsure", Summary: "本机表结构推到线上Z10/Z10d 可补列)", Group: "agent"},
{Method: "POST", Path: "/api/v1/agent/sync/channels/{id}/schema/fingerprint", OperationID: "agentSyncSchemaFingerprint", Summary: "线上表级指纹 row_count+content_hashZ14", Group: "agent"},
{Method: "GET", Path: "/api/v1/platform/dbsync/lww-overrides", OperationID: "platformLwwOverrides", Summary: "超管查看 LWW 覆盖审计", Group: "platform"}, {Method: "GET", Path: "/api/v1/platform/dbsync/lww-overrides", OperationID: "platformLwwOverrides", Summary: "超管查看 LWW 覆盖审计", Group: "platform"},
{Method: "POST", Path: "/api/v1/platform/dbsync/lww-overrides/{id}/rollback", OperationID: "platformLwwRollback", Summary: "超管按落败快照回滚线上单行", Group: "platform"}, {Method: "POST", Path: "/api/v1/platform/dbsync/lww-overrides/{id}/rollback", OperationID: "platformLwwRollback", Summary: "超管按落败快照回滚线上单行", Group: "platform"},

View File

@@ -539,6 +539,8 @@ CREATE TABLE IF NOT EXISTS orders (
- [ ] agent 停:仍可本地保存;恢复后按序追上 - [ ] agent 停:仍可本地保存;恢复后按序追上
- [ ] delete 保序,不换新 UUID - [ ] delete 保序,不换新 UUID
- [ ] 空表:`schema/ensure` 后线上出现空表Z10c - [ ] 空表:`schema/ensure` 后线上出现空表Z10c
- [ ] 缺列ensure 后 push 含新列不再 503Z10d
- [ ] 指纹:`schema/fingerprint` 返回 content_hash智能体带挂载 `online_db_id` 不 403Z14/Z14c
### 生产绑定Z12/Z13 ### 生产绑定Z12/Z13
@@ -579,7 +581,8 @@ CREATE TABLE IF NOT EXISTS orders (
| POST | `/api/v1/agent/sync/channels/{id}/pull` | agent / 用户 JWT下行 | | POST | `/api/v1/agent/sync/channels/{id}/pull` | agent / 用户 JWT下行 |
| POST | `/api/v1/agent/sync/channels/{id}/bootstrap` | 全量灌库 | | POST | `/api/v1/agent/sync/channels/{id}/bootstrap` | 全量灌库 |
| POST | `/api/v1/agent/sync/channels/{id}/schema` | 拉线上表结构(含空表) | | POST | `/api/v1/agent/sync/channels/{id}/schema` | 拉线上表结构(含空表) |
| POST | `/api/v1/agent/sync/channels/{id}/schema/ensure` | 本机空表建到线上Z10 | | POST | `/api/v1/agent/sync/channels/{id}/schema/ensure` | 本机空表建到线上已存在可补列Z10/Z10d |
| POST | `/api/v1/agent/sync/channels/{id}/schema/fingerprint` | 线上表指纹 `row_count`+`content_hash`Z14智能体可用挂载 online_db_id |
| GET/POST | `/api/v1/admin/sync/bindings` | 管理员或用户自助 | | GET/POST | `/api/v1/admin/sync/bindings` | 管理员或用户自助 |
| GET | `/api/v1/platform/dbsync/lww-overrides` | 仅超管 | | GET | `/api/v1/platform/dbsync/lww-overrides` | 仅超管 |
| POST | `/api/v1/platform/dbsync/lww-overrides/{id}/rollback` | 仅超管 | | POST | `/api/v1/platform/dbsync/lww-overrides/{id}/rollback` | 仅超管 |

View File

@@ -1,8 +1,8 @@
# 联调后修改意见 · 宇恒松离线(形态 B # 联调后修改意见 · 宇恒松离线(形态 B
> 初稿2026-08-01 · 持续修订至 **2026-08-05 ** > 初稿2026-08-01 · 修订至 **2026-08-05 18:25**
> 本次整理:生产 platform 已恢复;**§0.3 双方配合**;默认同步通道**默认运行中**Z10d/Z14 合入待生产 pull凭票/SMS 引号踩坑回写 > 焦点:**§0.2 / §0.3**Z10d / Z14 / Z14c **代码已合入**,生产须 `bash ./restart.sh --pull`;已修项勿再挂「仍待办」
> 来源:宇恒客户端 `yuhengyihao_client` ↔ 智建 gateway/platform本机 `8180`/`8888` 或生产 `aisite.yuxindazhineng.com` > 来源:宇恒 `yuhengyihao_client` ↔ 智建生产 `aisite.yuxindazhineng.com`
> 依据:`松离线-dbsync方案-最终版.md`、`宇恒-松离线数据同步使用文档.md` > 依据:`松离线-dbsync方案-最终版.md`、`宇恒-松离线数据同步使用文档.md`
--- ---
@@ -11,71 +11,66 @@
| 级别 | 状态 | 说明 | | 级别 | 状态 | 说明 |
|------|------|------| |------|------|------|
| **硬改(阻塞接口上线** | **无** | Z1Z14 代码侧大体齐;剩运维配置 + Z14c ACL | | **硬改(阻塞接口)** | **无** | Z1Z14 代码侧齐;剩生产 pull + 配号/Secret/白名单 |
| **生产栈** | **已恢复2026-08-05** | `SMS.Provider: "off"`引号health `platform/ai=true`;部署脚本 `chmod +x` | | **生产栈** | **已恢复** | `SMS.Provider: "off"` 须引号health `platform/ai=true` |
| **用户自助 Z1Z7** | **已落实** | Z7宇恒 ensure 宜带 `database_name`§0.2 A | | **Z1Z9 / Z11Z13** | **已落实** | 绑定/凭票/模块导入等;见 §5 |
| **Z8Z9** | **已落实** | 见 §5.5 / §5.6 | | **Z10 + Z10d** | **代码齐;生产 pull** | 空表 ensure已存在表 **ADD COLUMN**§5.7 |
| **Z10 / Z10d** | **双方已接 / 智建已合入** | ensure + 空表;**Z10d** 已存在表 `ADD COLUMN`(生产须 pull | | **Z12 默认同步** | **已落实** | 启用即通道;**默认运行中**`cb76824` |
| **Z11** | **智建已落实** | 发布自动补列 | | **Z14 + Z14c** | **代码齐;生产 pull** | fingerprint API智能体挂载 `online_db_id` 已放行§5.11 |
| **Z12** | **双方已接** | 默认同步通道;**默认 Enabled=运行中**`cb76824` | | **仍关注** | 用法 | SQLite 按库串行 drain历史数据靠 full-push不是「点启动」 |
| **Z13** | **双方代码已接** | 绑定码/手机/凭票/policy生产配号+Secret 见 §0.2 B |
| **Z14** | **双方已接;生产 pull** | 指纹 API + Z10d**Z14c** 智能体挂载 online 已放行;见 §5.11 |
| **仍建议关注** | 性能 | SQLite remote 串行 drain高并发易锁 |
### 0.1 绑定产品冻结摘要Z13 · 试运行) ### 0.1 绑定产品冻结Z13 · 试运行)
| 约定 | 内容 | | 约定 | 内容 |
|------|------| |------|------|
| 联调号 | 生产「宇信达」用 **`13531041944`****禁止**超管 `13531041945` | | 联调号 | **`13531041944`**(宇信达)**禁止**超管 `13531041945` |
| 换票 | **凭票免登录**`ticket-exchange``YXD_YUHENG_TICKET_SECRET` + `YXD_HOST_KEY` + 手机**不要**手写登录密码 | | 换票 | 凭票:`YXD_YUHENG_TICKET_SECRET` + `YXD_HOST_KEY` + 手机;****手写登录密码 |
| 短信 | **试运行关**`RequireForBind=false``Provider: "off"`**必须加引号**,否则 platform 起不来 | | 短信 | 试运行关:`RequireForBind=false``Provider: "off"`**YAML 必须加引号** |
| 同号 / 确认 | 命中成员必须弹窗;`confirm=true` 才绑 | | 同号 | 命中成员必须弹窗;`confirm=true` 才绑 |
| 通道状态 | 默认同步通道 **默认运行中**依赖用户先点「启动」 | | 通道 | 默认同步通道 **默认运行中**开通不依赖用户先点「启动」 |
### 0.2 待改清单(按负责方) ### 0.2 待改清单(按负责方)
> 智建近期提交`d195aa4` 凭票 → `4222667` SMS 引号 → `cb76824` 默认启动 → (本批)Z10d + fingerprint。生产`bash ./restart.sh --pull`。 > 智建轨迹`d195aa4` 凭票 → `4222667` SMS 引号 → `cb76824` 默认启动 → `4fae7ae` Z10d+fingerprint → **`bb59bb5` Z14c**。生产:`bash ./restart.sh --pull`。
#### A. 宇恒 · 已完成2026-08-05 #### A. 宇恒 · 已完成
| 编号 | 内容 | 落地 | | 编号 | 内容 |
|------|------|------| |------|------|
| **Z10c** | 空表 ensure | `sync_schema.ensure_before_drain` | | **Z10c** | `ensure_before_drain`(选同步 force + drain 前 TTL |
| **Z13be** | 绑定码 / 弹窗 / policy / 凭票 / 选同步 | 技能 + `/database/sync/bind/*` + `sync/mode` | | **Z13be** | 绑定码 / 同号确认 / policy / 凭票 / 选同步」即 Binding+drain |
| **Z14a** | 表级指纹慢心跳 | `sync_fingerprint.py`;不一致 ensure+full_push | | **Z14a** | 表级指纹慢心跳;不一致 ensure + full-push |
#### A. 宇恒 · 仍建议(非阻塞) / **配合注意** #### A. 宇恒 · 配合注意(非新开发)
| 优先级 | 编号 | 内容 | | 优先级 | 内容 |
|--------|------|------| |--------|------|
| **P0 配合** | **数据怎么上云** | **§0.3**:绑定 → 库选「同步」→ agent drain智建「查看线上表只反映已 push/ensure | | **P0** | 端到端**§0.3**:绑定 → 库选「同步」→ drain线上表只反映已 push/ensure |
| **P0 配合** | **online_db_id** | 智能体 JWT 可带 `agents/me` / ticket 返回`{channel}_uN`Z14c 已修);人类自助 JWT 仍须本人 Binding | | **P0** | **`online_db_id`**:生产 pull Z14c 后,智能体 JWT **用** ticket/`agents/me``{channel}_uN`;人类自助仍走本人 Binding |
| **P1** | **Z12e / Z7 / §2.6** | env 过渡;Binding 可读名;库串行 drain | | **P1** | Binding 可读名;库串行 drain;指纹优先 `schema/fingerprint`404 回退 `row_count` |
| **P1** | **指纹** | 优先调智建 `schema/fingerprint`;未部署则回退 `schema.row_count` |
#### B. 智建 · 已完成(生产已验证 / 代码已合入 #### B. 智建 · 已完成(仓内
| 项 | 说明 | | 项 | 说明 |
|----|------| |----|------|
| gateway 公开 bind/ticket | 生产 health 已通 | | gateway 公开 bind / ticket | 生产 health 已通 |
| `SMS.Provider: "off"` | YAML 布尔踩坑已修 | | `SMS.Provider: "off"` | YAML 布尔踩坑已修 |
| 默认同步通道默认启动 | `IsSystemDefault` 创建即 Enabled重启自动 Start | | 默认同步通道默认启动 | 创建即 enabled重启自动 Start |
| Podman DNS 别名 | compose hostname/aliases | | **Z14c** ACL | 智能体 JWT 放行挂载 `online_db_id``agentOwnsOnlineDB` |
| 部署脚本可执行位 | `restart.sh` 100755 | | Podman DNS / 脚本可执行位 | compose aliases`restart.sh` 100755 |
#### B. 智建 · 仍待办 #### B. 智建 · 仍待办(仅运维)
| 优先级 | 项 | 说明 | | 优先级 | 项 | 说明 |
|--------|----|------| |--------|----|------|
| **P0** | 生产 pull 本批 | Z10d ADD COLUMN + `schema/fingerprint` + 默认启动`bash ./restart.sh --pull` | | **P0** | **生产 pull 本批** | Z10d + `schema/fingerprint` + Z14c`bash ./restart.sh --pull` |
| **P0** | 成员手机 | 「宇信达」绑 **`13531041944`**;勿超管 `13531041945` | | **P0** | 成员手机 | 「宇信达」绑 **`13531041944`**;勿超管 |
| **P0** | 通道表白名单 | **勿**「填入测试默认」;形态 B 可空 | | **P0** | 通道表白名单 | **勿**「填入测试默认」;形态 B 可空 |
| **P0** | **Z14c** `online_db_id` ACL | ~~ticket/`agents/me` 的 `{channel}_uN` 403~~**已修**:智能体 JWT 放行其挂载的 `online_db_id``4fae7ae` 后续) | | **P1** | 凭票 Secret | `YuhengTicket.Secret``YXD_YUHENG_TICKET_SECRET` |
| **P1** | 凭票 Secret | `YuhengTicket.Secret``YXD_YUHENG_TICKET_SECRET` 同值 | | **P1** | `DefaultRemoteDSN` | 生产 Postgres空则 sqlite 联调文件 |
| **P1** | `DefaultRemoteDSN` | 生产 Postgres空则 sqlite 文件(联调) |
| **P2** | 正式短信 | Provider≠`"off"``RequireForBind=true` | | **P2** | 正式短信 | Provider≠`"off"``RequireForBind=true` |
#### C. 双方已否决 / 不改 #### C. 双方已否决
| 项 | 说明 | | 项 | 说明 |
|----|------| |----|------|
@@ -87,35 +82,30 @@
```text ```text
【智建运维】 【智建运维】
1. bash ./restart.sh --pull平台 Uphealth platform=true 1. bash ./restart.sh --pullhealth platform=true
2. 成员管理绑 13531041944通道勿测试表白名单配凭票 Secret 2. 成员绑 13531041944通道勿测试表白名单配凭票 Secret
3. 启用智能体 → 自动默认同步通道(应显示「运行中」 3. 启用智能体 → 默认同步通道「运行中」
4.(可选)生成绑定码发给终端 4.(可选)生成绑定码
【宇恒终端】 【宇恒终端】
5. sync_bound → policy → lookup/confirm 或 redeem 或 ticket-exchange 5. 未绑定 → policy → lookup/confirm 或 redeem 或 ticket-exchange
6. 本机库选「同步」→ Binding + ensure + agent drain/full_pushZ13e 6. 本机库选「同步」→ Binding + ensure + drain/full_pushZ13e
7. 慢心跳指纹对账Z14缺列依赖智建 Z10d 7. 慢心跳指纹Z14缺列依赖生产已 pull 的 Z10d
【智建验收】 【智建验收】
8. 「查看线上表」刷新 → 应出现业务表(含曾 0 行空表) 8. 「查看线上表」刷新 → 应业务表(含曾 0 行空表)
9. 仍空 = 终端未 push,不是「点启动」就能灌表 9. 仍空 = 终端未 push/ensure不是再点一次「启动」就能灌表
``` ```
| 角色 | 负责 | 不负责 | | 角色 | 负责 | 不负责 |
|------|------|--------| |------|------|--------|
| **智建** | 落点/通道/鉴权/ensure/fingerprint API;控制台看线上表 | 不替宇恒本机历史数据 | | **智建** | 落点/通道/鉴权/ensure/fingerprint控制台看线上表 | 不替宇恒本机历史 |
| **宇恒** | 绑定 UX、选同步、outbox、drain、指纹修复、full-push | 不手填 DSN/通道产品终态 | | **宇恒** | 绑定 UX、选同步、outbox、drain、指纹修复、full-push | 不手填 DSN/通道产品终态 |
| **共同** | `13531041944`;试运行免短信仍须确认Secret 对齐 | 不用超管号联调 | | **共同** | 联调`13531041944`Secret 对齐;试运行免短信仍须确认 | 不用超管号 |
宇恒对照脚本: 宇恒对照脚本:`smoke_zhijian_e2e.py` / `smoke_offline_concurrent.py` / `smoke_zhijian_gateway_burst.py` / `smoke_stress_sync.py`
- `yxd/app_fastapi/smoke_zhijian_e2e.py` 复测摘要gateway 串行 60/60、`eof502=0`;同 version → `skipped`;并发 SQLite 须重试 / 客户端串行。
- `yxd/app_fastapi/smoke_offline_concurrent.py`
- `yxd/app_fastapi/smoke_zhijian_gateway_burst.py`(连续 push / stats
- `yxd/app_fastapi/smoke_stress_sync.py`(高并发 + gateway 压测)
复测摘要改后gateway 串行 60/60、`eof502=0`;同 version → `skipped``pushed_applied` / `pushed_skipped` 有值;并发 push 加重试可压满(锁冲突靠重试消化)。
--- ---
@@ -149,7 +139,7 @@
| **生产 · 宇信达** | 公司管理 / 同号绑定联调 | **`13531041944`**(密码由开通时设定) | **专用联调号**;智建须在「宇信达」成员/管理员中写入此手机;宇恒 `YXD_SYNC_LOGIN_PHONE` 与 Z13 同号确认均以此号为准 | | **生产 · 宇信达** | 公司管理 / 同号绑定联调 | **`13531041944`**(密码由开通时设定) | **专用联调号**;智建须在「宇信达」成员/管理员中写入此手机;宇恒 `YXD_SYNC_LOGIN_PHONE` 与 Z13 同号确认均以此号为准 |
| 平台超管(禁止联调) | 控制台「填入超管手机」 | `13531041945` / `ljk_admin` | **最顶级管理员**seed `ensureDevPhone(ljk_admin)`**禁止**用作同步登录 / 绑定联调,会与公司账号冲突 | | 平台超管(禁止联调) | 控制台「填入超管手机」 | `13531041945` / `ljk_admin` | **最顶级管理员**seed `ensureDevPhone(ljk_admin)`**禁止**用作同步登录 / 绑定联调,会与公司账号冲突 |
> **智建待办(运维)**:见 **§0.2 B**成员手机 `13531041944`、`./restart.sh --pull`、凭票 Secret、通道勿测试表白名单)。 > **智建待办(运维)**:见 **§0.2 B**生产 pull、成员手机、Secret、通道勿测试表白名单Z14c/Z10d/fingerprint 属「已合入待 pull」不在待开发。
--- ---
@@ -536,7 +526,7 @@ POST .../schema
| **Z12a** | **P0** | **换票带回绑定** | `POST /api/v1/auth/token`(及登录)响应含 `channel_id` / `online_db_id` / `database_name` / `sync_bound` | **智建已落实** | | **Z12a** | **P0** | **换票带回绑定** | `POST /api/v1/auth/token`(及登录)响应含 `channel_id` / `online_db_id` / `database_name` / `sync_bound` | **智建已落实** |
| **Z12b** | **P0** | **智能体自查绑定** | `GET /api/v1/agents/me`:智能体 Bearer 可读自己的通道/线上库/状态 | **智建已落实** | | **Z12b** | **P0** | **智能体自查绑定** | `GET /api/v1/agents/me`:智能体 Bearer 可读自己的通道/线上库/状态 | **智建已落实** |
| **Z12c** | **P0** | **启用即自动绑通道** | 创建/启用智能体 → `EnsureAndStartSystemDefaultChannel``IsSystemDefault`,表白名单可空,**默认运行中**);写回 `channel_id`+`online_db_id`DSN 见 `DBSync.DefaultRemoteDSN` | **智建已落实**(含默认启动 `cb76824` | | **Z12c** | **P0** | **启用即自动绑通道** | 创建/启用智能体 → `EnsureAndStartSystemDefaultChannel``IsSystemDefault`,表白名单可空,**默认运行中**);写回 `channel_id`+`online_db_id`DSN 见 `DBSync.DefaultRemoteDSN` | **智建已落实**(含默认启动 `cb76824` |
| **Z12c-1** | **P0** | **账号级隔离** | Binding / push 校验:用户 JWT 只能写本人 `online_db_id` | **智建已有**(自助 Binding**Z14c** 仍有 `_uN` 与 JWT 不一致问题 | | **Z12c-1** | **P0** | **账号级隔离** | Binding / push用户 JWT 只能写本人 Binding**智能体 JWT** 另按挂载落点(**Z14c 已修** | **智建已落实** |
| **Z12c-2** | **P1** | **公司共享库** | Binding `shared=true`:同租户成员可访问该 `online_db_id`;仅管理员可设 | **智建已落实** | | **Z12c-2** | **P1** | **公司共享库** | Binding `shared=true`:同租户成员可访问该 `online_db_id`;仅管理员可设 | **智建已落实** |
| **Z12d** | **P1** | **SyncPage 展示通道 ID** | 运维可见 + copyable | **智建已落实** | | **Z12d** | **P1** | **SyncPage 展示通道 ID** | 运维可见 + copyable | **智建已落实** |
| **Z12e** | **P1** | **唯一默认通道** | 每公司至多 1 条 `is_system_default`;复用已有默认 | **智建已落实** + 宇恒「仅 1 条则写入 env」 | | **Z12e** | **P1** | **唯一默认通道** | 每公司至多 1 条 `is_system_default`;复用已有默认 | **智建已落实** + 宇恒「仅 1 条则写入 env」 |
@@ -636,10 +626,10 @@ POST .../schema
| 编号 | 优先级 | 诉求 | 现状 | | 编号 | 优先级 | 诉求 | 现状 |
|------|--------|------|------| |------|--------|------|------|
| **Z14a** | **P0** | 宇恒本机指纹 + 对比线上 row_count + 自动修复 | **宇恒已接**`yxd/app_fastapi/sync_fingerprint.py`agent 默认 TTL **600s**`POST /database/sync/fingerprint` | | **Z14a** | **P0** | 宇恒本机指纹 + 对比线上 + 自动修复 | **宇恒已接**`sync_fingerprint.py`TTL **600s**`POST /database/sync/fingerprint` |
| **Z14b** | **P1** | 智建返回 `content_hash` | **智建已合入生产 pull**`POST /api/v1/agent/sync/channels/{id}/schema/fingerprint` | | **Z14b** | **P1** | 智建 `content_hash` | **已合入生产 pull**`POST .../schema/fingerprint` |
| **Z10d** | **P0** | ensure 已存在表补列 | **智建已合入生产 pull**否则 `填土高度` `id` 503 | | **Z10d** | **P0** | ensure 已存在表补列 | **已合入生产 pull**未 pull 时 `填土高度``id` 503 |
| **Z14c** | **P1** | ticket/`agents/me``online_db_id` 与 gateway ACL 一致 | **智建已落实**:智能体 JWT 校验挂载落点(`agentOwnsOnlineDB`Binding 仍按人类 user_id | | **Z14c** | **P0** | 智能体 `online_db_id` ACL | **已合入,生产 pull**`agentOwnsOnlineDB`人类 Binding 规则不变 |
**契约摘要Z14b** **契约摘要Z14b**
@@ -649,27 +639,27 @@ POST /api/v1/agent/sync/channels/{id}/schema/fingerprint
result.tables[]: { name, pk_column, row_count, content_hash } result.tables[]: { name, pk_column, row_count, content_hash }
``` ```
哈希约定(双方对齐)`sha256( table+"|"+pk+"|" + Σ json(row, sort_keys=True)+"\n" )` 前 32 hex。 哈希:`sha256( table+"|"+pk+"|" + Σ json(row, sort_keys=True)+"\n" )` 前 32 hex。
**分工** **分工**
| 方 | 做什么 | | 方 | 做什么 |
|----|--------| |----|--------|
| 宇恒 | 本机指纹;优先 fingerprint API404 回退 `schema.row_count`;不一致自动 ensure+`enqueue_full_push`heartbeat 写入 `fingerprint_*` | | 宇恒 | 本机指纹;优先 fingerprint API404 回退 `row_count`;不一致 ensure+full_push |
| 智建 | 部署 fingerprint + Z10d**Z14c 已修**(智能体挂载 online | | 智建 | 生产 pullfingerprint + Z10d + Z14c |
**联调踩坑(2026-08-05 · 宇信达生产** **联调踩坑(宇信达 · 已回写**
1. **数据量对不上**历史行不会因开通同步自动上云 → 须 full-push指纹对账可检出差表 1. **数对不上**开通同步不会自动灌历史 → full-push指纹可检出。
2. **`填土高度(6标一工区)`**:本机列 `_row_id`,线上曾无 `id`push 默认 pk=`id` 并注入该列 → `has no column named id`;整队曾因 `mark_error` 未改 status 卡住(宇恒已修)。修复路径:删表重建 / 部署 Z10d 后 ensure 补 `id` 再推 2. **`填土高度` `id`**push 默认 pk=`id`;须 Z10d 补列或删表重建后再推(宇恒 `mark_error` 堵队已修)
3. **`online_db_id=_uN` 403(已修)**:智能体 JWT `user_id=agent_id`Binding 在人类成员上;现 `authorizeUserOnlineDB` 额外放行智能体挂载的 `OnlineDBID`/`ChannelID` 3. **`_uN` 403**:智能体 JWT `user_id=agent_id`Binding 在人类成员上**Z14c** 放行挂载 online
**验收** **验收**
1. 本机行数后 ≤TTL 内指纹检出 mismatch并排队 full-push 1. 本机行数后 ≤TTL 检出 mismatch 并排队修复
2.部署 fingerprint:仅 count 对账仍可用`zhijian_fingerprint_api=false` 2. pull fingerprint仅 count 对账仍可用。
3. 部署后:同 count 不同内容 → `hash_mismatch` → 修复 3. pull 后:同 count 不同内容 → `hash_mismatch`
4. Z10d 部署后:缺列 ensure 成功,`填土高度` 可推满。 4. Z10d pull 后:`填土高度` 可推满。
--- ---