diff --git a/docs/数据同步-开通说明.md b/docs/数据同步-开通说明.md index 528a744..e834b28 100644 --- a/docs/数据同步-开通说明.md +++ b/docs/数据同步-开通说明.md @@ -52,7 +52,7 @@ postgres://user:pass@127.0.0.1:5432/app_online?sslmode=disable 同号硬约束：宇恒手机 = 公司成员手机（联调样例 **`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`。 换票 / 自查： diff --git a/platform/internal/apidef/catalog.go b/platform/internal/apidef/catalog.go index 01f9c4c..d03b1e8 100644 --- a/platform/internal/apidef/catalog.go +++ b/platform/internal/apidef/catalog.go @@ -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}/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}/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_hash（Z14）", Group: "agent"}, {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"}, diff --git a/宇恒-松离线数据同步使用文档.md b/宇恒-松离线数据同步使用文档.md index d12aba3..ae105b4 100644 --- a/宇恒-松离线数据同步使用文档.md +++ b/宇恒-松离线数据同步使用文档.md @@ -539,6 +539,8 @@ CREATE TABLE IF NOT EXISTS orders ( - [ ] agent 停：仍可本地保存；恢复后按序追上 - [ ] delete 保序，不换新 UUID - [ ] 空表：`schema/ensure` 后线上出现空表（Z10c） +- [ ] 缺列：ensure 后 push 含新列不再 503（Z10d） +- [ ] 指纹：`schema/fingerprint` 返回 content_hash；智能体带挂载 `online_db_id` 不 403（Z14/Z14c） ### 生产绑定（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}/bootstrap` | 全量灌库 | | 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 | `/api/v1/platform/dbsync/lww-overrides` | 仅超管 | | POST | `/api/v1/platform/dbsync/lww-overrides/{id}/rollback` | 仅超管 | diff --git a/联调后修改意见-宇恒松离线.md b/联调后修改意见-宇恒松离线.md index 1b143ef..f58255f 100644 --- a/联调后修改意见-宇恒松离线.md +++ b/联调后修改意见-宇恒松离线.md @@ -1,8 +1,8 @@ # 联调后修改意见 · 宇恒松离线（形态 B） -> 初稿：2026-08-01 · 持续修订至 **2026-08-05 晚** -> 本次整理：生产 platform 已恢复；**§0.3 双方配合**；默认同步通道**默认运行中**；Z10d/Z14 合入待生产 pull；凭票/SMS 引号踩坑回写 -> 来源：宇恒客户端 `yuhengyihao_client` ↔ 智建 gateway/platform（本机 `8180`/`8888` 或生产 `aisite.yuxindazhineng.com`） +> 初稿：2026-08-01 · 修订至 **2026-08-05 18:25** +> 焦点：**§0.2 / §0.3**；Z10d / Z14 / Z14c **代码已合入**，生产须 `bash ./restart.sh --pull`；已修项勿再挂「仍待办」 +> 来源：宇恒 `yuhengyihao_client` ↔ 智建（生产 `aisite.yuxindazhineng.com`） > 依据：`松离线-dbsync方案-最终版.md`、`宇恒-松离线数据同步使用文档.md` --- @@ -11,71 +11,66 @@ | 级别 | 状态 | 说明 | |------|------|------| -| **硬改（阻塞接口上线）** | **无** | Z1–Z14 代码侧大体齐；剩运维配置 + Z14c ACL | -| **生产栈** | **已恢复（2026-08-05）** | `SMS.Provider: "off"` 须加引号；health `platform/ai=true`；部署脚本 `chmod +x` | -| **用户自助 Z1–Z7** | **已落实** | Z7：宇恒 ensure 宜带 `database_name`（§0.2 A′） | -| **Z8–Z9** | **已落实** | 见 §5.5 / §5.6 | -| **Z10 / Z10d** | **双方已接 / 智建已合入** | ensure + 空表；**Z10d** 已存在表 `ADD COLUMN`（生产须 pull） | -| **Z11** | **智建已落实** | 发布自动补列 | -| **Z12** | **双方已接** | 默认同步通道；**默认 Enabled=运行中**（`cb76824`） | -| **Z13** | **双方代码已接** | 绑定码/手机/凭票/policy；生产配号+Secret 见 §0.2 B | -| **Z14** | **双方已接；生产 pull** | 指纹 API + Z10d；**Z14c** 智能体挂载 online 已放行；见 §5.11 | -| **仍建议关注** | 性能 | SQLite remote 串行 drain；高并发易锁 | +| **硬改（阻塞接口）** | **无** | Z1–Z14 代码侧齐；剩生产 pull + 配号/Secret/白名单 | +| **生产栈** | **已恢复** | `SMS.Provider: "off"` 须引号；health `platform/ai=true` | +| **Z1–Z9 / Z11–Z13** | **已落实** | 绑定/凭票/模块导入等；见 §5 | +| **Z10 + Z10d** | **代码齐；生产 pull** | 空表 ensure；已存在表 **ADD COLUMN**（§5.7） | +| **Z12 默认同步** | **已落实** | 启用即通道；**默认运行中**（`cb76824`） | +| **Z14 + Z14c** | **代码齐；生产 pull** | fingerprint API；智能体挂载 `online_db_id` 已放行（§5.11） | +| **仍关注** | 用法 | SQLite 按库串行 drain；历史数据靠 full-push，不是「点启动」 | -### 0.1 绑定产品冻结摘要（Z13 · 试运行） +### 0.1 绑定产品冻结（Z13 · 试运行） | 约定 | 内容 | |------|------| -| 联调号 | 生产「宇信达」用 **`13531041944`**；**禁止**超管号 `13531041945` | -| 换票 | **凭票免登录**：`ticket-exchange`（`YXD_YUHENG_TICKET_SECRET` + `YXD_HOST_KEY` + 手机）；**不要**手写登录密码 | -| 短信 | **试运行关闭**：`RequireForBind=false`；`Provider: "off"`（**必须加引号**，否则 platform 起不来） | -| 同号 / 确认 | 命中成员必须弹窗；`confirm=true` 才绑 | -| 通道状态 | 默认同步通道 **默认运行中**；勿依赖用户先点「启动」 | +| 联调号 | **`13531041944`**（宇信达）；**禁止**超管 `13531041945` | +| 换票 | 凭票：`YXD_YUHENG_TICKET_SECRET` + `YXD_HOST_KEY` + 手机；**勿**手写登录密码 | +| 短信 | 试运行关：`RequireForBind=false`；`Provider: "off"`（**YAML 必须加引号**） | +| 同号 | 命中成员 → 必须弹窗；`confirm=true` 才绑 | +| 通道 | 默认同步通道 **默认运行中**；开通不依赖用户先点「启动」 | ### 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` | -| **Z13b–e** | 绑定码 / 弹窗 / policy / 凭票 / 选同步 | 技能 + `/database/sync/bind/*` + `sync/mode` | -| **Z14a** | 表级指纹慢心跳 | `sync_fingerprint.py`；不一致 ensure+full_push | +| 编号 | 内容 | +|------|------| +| **Z10c** | `ensure_before_drain`（选同步 force + drain 前 TTL） | +| **Z13b–e** | 绑定码 / 同号确认 / policy / 凭票 / 选「同步」即 Binding+drain | +| **Z14a** | 表级指纹慢心跳；不一致 → ensure + full-push | -#### A′. 宇恒 · 仍建议（非阻塞） / **配合注意** +#### A′. 宇恒 · 配合注意（非新开发） -| 优先级 | 编号 | 内容 | -|--------|------|------| -| **P0 配合** | **数据怎么上云** | 见 **§0.3**：绑定 → 库选「同步」→ agent drain；智建「查看线上表」只反映已 push/ensure | -| **P0 配合** | **online_db_id** | 智能体 JWT 可带 `agents/me` / ticket 返回的 `{channel}_uN`（Z14c 已修）；人类自助 JWT 仍须本人 Binding | -| **P1** | **Z12e / Z7 / §2.6** | env 过渡；Binding 可读名；按库串行 drain | -| **P1** | **指纹** | 优先调智建 `schema/fingerprint`；未部署则回退 `schema.row_count` | +| 优先级 | 内容 | +|--------|------| +| **P0** | 端到端见 **§0.3**：绑定 → 库选「同步」→ drain；线上表只反映已 push/ensure | +| **P0** | **`online_db_id`**：生产 pull Z14c 后，智能体 JWT **用** ticket/`agents/me` 的 `{channel}_uN`；人类自助仍走本人 Binding | +| **P1** | Binding 带可读名；同库串行 drain；指纹优先 `schema/fingerprint`，404 回退 `row_count` | -#### B. 智建 · 已完成（生产已验证 / 代码已合入） +#### B. 智建 · 已完成（仓内） | 项 | 说明 | |----|------| -| gateway 公开 bind/ticket | 生产 health 已通 | +| gateway 公开 bind / ticket | 生产 health 已通 | | `SMS.Provider: "off"` | YAML 布尔踩坑已修 | -| 默认同步通道默认启动 | `IsSystemDefault` 创建即 Enabled；重启自动 Start | -| Podman DNS 别名 | compose hostname/aliases | -| 部署脚本可执行位 | `restart.sh` 等 100755 | +| 默认同步通道默认启动 | 创建即 enabled；重启自动 Start | +| **Z14c** ACL | 智能体 JWT 放行挂载 `online_db_id`（`agentOwnsOnlineDB`） | +| Podman DNS / 脚本可执行位 | compose aliases；`restart.sh` 100755 | -#### B′. 智建 · 仍待办 +#### B′. 智建 · 仍待办（仅运维） | 优先级 | 项 | 说明 | |--------|----|------| -| **P0** | 生产再 pull 本批 | Z10d ADD COLUMN + `schema/fingerprint` + 默认启动；`bash ./restart.sh --pull` | -| **P0** | 成员手机 | 「宇信达」绑 **`13531041944`**；勿超管 `13531041945` | +| **P0** | **生产 pull 本批** | Z10d + `schema/fingerprint` + Z14c；`bash ./restart.sh --pull` | +| **P0** | 成员手机 | 「宇信达」绑 **`13531041944`**；勿超管号 | | **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** | `DefaultRemoteDSN` | 生产 Postgres；空则 sqlite 文件（联调） | +| **P1** | 凭票 Secret | `YuhengTicket.Secret` ≡ `YXD_YUHENG_TICKET_SECRET` | +| **P1** | `DefaultRemoteDSN` | 生产 Postgres；空则 sqlite 联调文件 | | **P2** | 正式短信 | Provider≠`"off"` 且 `RequireForBind=true` | -#### C. 双方已否决 / 不改 +#### C. 双方已否决 | 项 | 说明 | |----|------| @@ -87,35 +82,30 @@ ```text 【智建运维】 - 1. bash ./restart.sh --pull（平台 Up，health platform=true） - 2. 成员管理绑 13531041944；通道勿测试表白名单；配凭票 Secret - 3. 启用智能体 → 自动默认同步通道（应显示「运行中」） - 4.（可选）生成绑定码发给终端 + 1. bash ./restart.sh --pull（health platform=true） + 2. 成员绑 13531041944；通道勿测试表白名单；配凭票 Secret + 3. 启用智能体 → 默认同步通道应「运行中」 + 4.（可选）生成绑定码 【宇恒终端】 - 5. sync_bound？否 → policy → lookup/confirm 或 redeem 或 ticket-exchange - 6. 本机库选「同步」→ Binding + ensure + agent drain/full_push（Z13e） - 7. 慢心跳指纹对账（Z14）；缺列依赖智建 Z10d + 5. 未绑定 → policy → lookup/confirm 或 redeem 或 ticket-exchange + 6. 本机库选「同步」→ Binding + ensure + drain/full_push（Z13e） + 7. 慢心跳指纹（Z14）；缺列依赖生产已 pull 的 Z10d 【智建验收】 - 8. 「查看线上表」刷新 → 应出现业务表（含曾 0 行空表） - 9. 仍空 = 终端未 push，不是「点启动」就能灌表 + 8. 「查看线上表」刷新 → 应有业务表（含曾 0 行空表） + 9. 仍空 = 终端尚未 push/ensure，不是再点一次「启动」就能灌表 ``` | 角色 | 负责 | 不负责 | |------|------|--------| -| **智建** | 落点/通道/鉴权/ensure/fingerprint API；控制台查看线上表 | 不替宇恒本机灌历史数据 | -| **宇恒** | 绑定 UX、选同步、outbox、drain、指纹修复、full-push | 不手填 DSN/通道当产品终态 | -| **共同** | 同号 `13531041944`；试运行免短信仍须确认；Secret 对齐 | 不用超管号联调 | +| **智建** | 落点/通道/鉴权/ensure/fingerprint；控制台看线上表 | 不替宇恒灌本机历史行 | +| **宇恒** | 绑定 UX、选同步、outbox、drain、指纹修复、full-push | 不以手填 DSN/通道为产品终态 | +| **共同** | 联调号 `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` -- `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 加重试可压满（锁冲突靠重试消化）。 +复测摘要：gateway 串行 60/60、`eof502=0`；同 version → `skipped`；并发 SQLite 须重试 / 客户端串行。 --- @@ -149,7 +139,7 @@ | **生产 · 宇信达** | 公司管理 / 同号绑定联调 | **`13531041944`**（密码由开通时设定） | **专用联调号**；智建须在「宇信达」成员/管理员中写入此手机；宇恒 `YXD_SYNC_LOGIN_PHONE` 与 Z13 同号确认均以此号为准 | | 平台超管（禁止联调） | 控制台「填入超管手机」 | `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` | **智建已落实** | | **Z12b** | **P0** | **智能体自查绑定** | `GET /api/v1/agents/me`：智能体 Bearer 可读自己的通道/线上库/状态 | **智建已落实** | | **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`；仅管理员可设 | **智建已落实** | | **Z12d** | **P1** | **SyncPage 展示通道 ID** | 运维可见 + copyable | **智建已落实** | | **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` | -| **Z14b** | **P1** | 智建返回 `content_hash` | **智建已合入待生产 pull**：`POST /api/v1/agent/sync/channels/{id}/schema/fingerprint` | -| **Z10d** | **P0** | ensure 对已存在表补列 | **智建已合入待生产 pull**；否则 `填土高度` 等缺 `id` 会 503 | -| **Z14c** | **P1** | ticket/`agents/me` 的 `online_db_id` 与 gateway ACL 一致 | **智建已落实**：智能体 JWT 校验挂载落点（`agentOwnsOnlineDB`）；Binding 仍按人类 user_id | +| **Z14a** | **P0** | 宇恒本机指纹 + 对比线上 + 自动修复 | **宇恒已接**：`sync_fingerprint.py`；TTL **600s**；`POST /database/sync/fingerprint` | +| **Z14b** | **P1** | 智建 `content_hash` | **已合入，生产 pull**：`POST .../schema/fingerprint` | +| **Z10d** | **P0** | ensure 已存在表补列 | **已合入，生产 pull**；未 pull 时 `填土高度` 缺 `id` 仍 503 | +| **Z14c** | **P0** | 智能体 `online_db_id` ACL | **已合入，生产 pull**：`agentOwnsOnlineDB`；人类 Binding 规则不变 | **契约摘要（Z14b）** @@ -649,27 +639,27 @@ POST /api/v1/agent/sync/channels/{id}/schema/fingerprint → 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 API；404 则回退 `schema.row_count`；不一致自动 ensure+`enqueue_full_push`；heartbeat 写入 `fingerprint_*` | -| 智建 | 部署 fingerprint + Z10d；**Z14c 已修**（智能体挂载 online） | +| 宇恒 | 本机指纹；优先 fingerprint API，404 回退 `row_count`；不一致 ensure+full_push | +| 智建 | 生产 pull：fingerprint + Z10d + Z14c | -**联调踩坑（2026-08-05 · 宇信达生产）** +**联调踩坑（宇信达 · 已回写）** -1. **数据量对不上**：历史行不会因开通同步自动上云 → 须 full-push；指纹对账可检出差表。 -2. **`填土高度(6标一工区)`**：本机列 `_row_id`，线上曾无 `id`；push 默认 pk=`id` 并注入该列 → `has no column named id`；整队曾因 `mark_error` 未改 status 卡住（宇恒已修）。修复路径：删表重建 / 部署 Z10d 后 ensure 补 `id` 再推。 -3. **`online_db_id=_uN` 403（已修）**：智能体 JWT 的 `user_id=agent_id`，Binding 记在人类成员上；现 `authorizeUserOnlineDB` 额外放行智能体挂载的 `OnlineDBID`/`ChannelID`。 +1. **行数对不上**：开通同步不会自动灌历史 → full-push；指纹可检出。 +2. **`填土高度` 缺 `id`**：push 默认 pk=`id`；须 Z10d 补列或删表重建后再推（宇恒 `mark_error` 堵队已修）。 +3. **`_uN` 曾 403**：智能体 JWT `user_id=agent_id`，Binding 在人类成员上 → **Z14c** 放行挂载 online。 **验收** -1. 本机改行数后 ≤TTL 内指纹检出 mismatch，并排队 full-push。 -2. 未部署 fingerprint 时：仅 count 对账仍可用；`zhijian_fingerprint_api=false`。 -3. 部署后：同 count 不同内容 → `hash_mismatch` → 修复。 -4. Z10d 部署后：缺列 ensure 成功，`填土高度` 可推满。 +1. 改本机行数后 ≤TTL 检出 mismatch 并排队修复。 +2. 未 pull fingerprint：仅 count 对账仍可用。 +3. pull 后：同 count 不同内容 → `hash_mismatch`。 +4. Z10d pull 后：`填土高度` 可推满。 ---