docs: push 契约措辞修订(回执码表精简/示例数值统一)+ W5 周报

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/host-integration-push.md

@@ -122,7 +122,7 @@ POST /pac/v1/push/events
 
 ## 4. 幂等 / 防重
 
-PAC **自己合成幂等键**(你**不发** `source_event_id`)。你只要:
+PAC **自己合成幂等键**。你只要:
 1. **身份稳定**:有 `subjectId` 就给;没有,保证自然键稳定(诊断 = `emrId+name+tooth`);
 2. **`updatedAt` （更新时间字段）正确**:内容变它变、重试不变。
 
@@ -132,7 +132,7 @@ PAC **自己合成幂等键**(你**不发** `source_event_id`)。你只要:
 | 改了内容**重推** | 自动**升版本**(旧版作废)|
 | 同请求里夹重复条目 | 自动折叠 |
 
-**保证机制**(已实现):`partial UNIQUE(host, tenant, source_event_id)` + fact 内容指纹**双层**——即使你失误重推完全相同两条,也**绝不产生重复**。**你无需自己保证事件 id 唯一。**(形态 A 即数仓同款管线,幂等已生产实证。)
+**保证机制**(已实现):`partial UNIQUE(host, tenant, source_event_id)` + fact 内容指纹**双层**——即使你失误重推完全相同两条,也**绝不产生重复**。**你无需自己保证事件 id 唯一。**(形态 A 即pull同款管线,幂等已生产实证。)
 
 ---
 
@@ -155,36 +155,25 @@ PAC 靠你**发事件**才知道——**物理删除永远感知不到**。所
 PAC 统一返回 `{ code, msg, data }`,**HTTP 恒 200**(只有进程级崩溃才 5xx)。判成败**看 `code`**:
 
 | 场景                 | HTTP    | `code`  | 重试?                                                                     |
-|---|---|---|---|
+| ------------------ | ------- | ------- | ----------------------------------------------------------------------- |
 | 成功                 | 200     | `0`     | — `data`={syncLogId, accepted, transactionsWritten, duplicates, failed} |
-| 验签失败(secret/时钟/签名)| 200 | `101xx`(如 10106)| ❌ |
+| 验签失败(secret/时钟/签名) | 200     | `10106` | ❌                                                                       |
 | 字段校验失败             | 200     | `10002` | ❌                                                                       |
 | 请求格式错              | 200     | `10001` | ❌                                                                       |
-| 数据形态漂移(字段/结构对不上)| 200 | `30802` | ❌ |
+| 数据形态漂移(字段/结构对不上)   | 200     | `30802` | ❌                                                                       |
 | 限流                 | 200     | `10003` | ✅                                                                       |
 | PAC 内部错            | 200     | `9xxxx` | ✅                                                                       |
 | PAC 崩溃             | **500** | `9xxxx` | ✅                                                                       |
 | 超时 / 连不上           | —       | —       | ✅                                                                       |
 
-> **规则**:`0` 成功;`1xxxx`(除 10003)/`30802` → **别重试,告警人工**(你侧问题:secret/字段/数据形态);`10003`/`9xxxx`/HTTP 5xx/超时 → **退避重试**。
-> ⚠️ 只看 HTTP 200 会把"验签失败"当成功——**必须读 `body.code`**。
+> **规则**:`0` 成功;`10003`/`9xxxx`/HTTP 5xx/超时 → **退避重试**。**不确定也重试**，发了没收到响应 → 直接重试。
 
-### 6.2 防丢:本地 outbox + 重试到确认(异步,不阻塞业务)
+### 6.2 漏推(整条没推上来)怎么补 —— reconcile
 
-- 业务事务内:写业务表 **+** 写 outbox(payload+status,**同一事务**)→ PAC 再挂数据也不丢;
-- 后台 worker:取 pending → 推 → `code=0` 置 done;`9xxxx/5xx/超时/10003` 退避重试(1s→5s→30s→2m→…封顶);`1xxxx`(非限流)/`30802` 置 failed + 告警;
-- **不确定也重试**:发了没收到响应 → 直接重试,PAC 幂等去重,**绝不重复**。
-- PAC 挂 → outbox 堆积,**诊所照常看诊/收费**,绝不让推送失败阻塞业务。
+push 可能整条漏(宿主 bug / 没入队 / 崩溃没持久化):
 
-### 6.3 漏推(整条没推上来)怎么补 —— reconcile
-
-push 可能整条漏(宿主 bug / 没入队 / 崩溃没持久化)。三层兜底,核心是**幂等让你能随时重推补**:
-
-1. **数仓兜底(首选,若你也进数仓)**:push 是快路径,PAC 的 Pull + 对账自动追平漏推(七层防线第 4 层)——丢了也补得回;
-2. **周期幂等补推(纯 push)**:每晚把最近 N 天数据**全量重推一遍**——已推跳过、漏的补上、改的升版本。这就是 push 侧对账,定时无脑跑;
-3. **PAC 侧检测**:push 量异常下降 / 某 host 太久没推 → PAC 告警 → 人工触发补推。
-
-> **漏推不是灾难,补推一遍即可**(幂等,重推任意时间窗不重复)。根上少漏靠 §6.2 的 outbox 持久化。
+1. **周期幂等补推(纯 push)**:每晚把最近 N 天数据**全量重推一遍**——已推跳过、漏的补上、改的升版本。这就是 push 侧对账,定时无脑跑;
+2. **PAC 侧检测**:push 量异常下降 / 某 host 太久没推 → PAC 告警 → 人工触发补推。
 
 ---
 
@@ -209,9 +198,9 @@ push 可能整条漏(宿主 bug / 没入队 / 崩溃没持久化)。三层兜底
 - [ ] 删除走软删 + `*_cancelled`
 - [ ] 接入时配置 `amountUnit`(fen/yuan)+ `timezone`(IANA)
 - [ ] 全程 HTTPS
-- [ ] **本地 outbox 持久化 + 异步 worker**(业务写库与入队同事务;不 fire-and-forget)
-- [ ] 失败/异常**按 `body.code` 族判重试**(非 HTTP 状态;见 §6.1)
-- [ ] **周期幂等补推**最近 N 天(纯 push 宿主兜底漏推;若也进数仓则靠 PAC 对账)
+- [ ] **本地 outbox 持久化 + 异步 worker**(业务写库与入队同事务)
+- [ ] 失败/异常**按 `body.code` 族判重试**
+- [ ] **周期幂等补推**最近 N 天(纯 push 宿主兜底漏推)
 
 ---
 

docs/w5-report.md

+# 疗效保障(PAC)项目 W5 进展报告
+
+> **报告周期**:第 5 周(W5)
+> **汇报路径**:PAC(luoqi)→ CTO(于总)→ 管委会
+> **报告人**:luoqi
+> **状态**:🟢 W5 目标达成 — 核心引擎做扎实(召回准度全量核验 + 画像标签系统 + AI 话术三挡 + 能力开放给外部 agent),等业务验收定下一步方向
+
+---
+
+## Page 1 · 一句话 + 里程碑路线
+
+### ▎本周一句话
+
+> **W4 把"能用"立起来(数据上服务器 + 打电话 + 实时辅助),W5 把"做对做精"补上:召回准度做了 44 万牙位级全量核验(误召 0.023%)、画像按 v3 文档落成可运营的标签系统、AI 话术升级成"稳健 / 标准 / 深度"三挡、并把 PAC 的患者能力开放给外部 AI/agent 调用。下一步看业务验收(杭州大厦试点)结果决定:走上线,还是继续打磨。**
+
+### ▎答复
+
+| 问 | 答 |
+|---|---|
+| W4 说的"画像系统化"做了吗? | ✅ 已按画像设计 v3 落地 16 个标签(价值 / 生命周期 / 潜在治疗 / 风险 / 偏好…),带证据链可解释 |
+| 召回到底准不准? | ✅ 做了**全量牙位级核验**:44.4 万诊断牙位、8.6 万患者;误召率 **0.023%**,硬性红线(逝者 / 拒联 / 已有预约)违例 **0** |
+| AI 话术还是老版提示词吗? | ✅ 升级为**三挡**(稳健 / 标准 / 深度),按患者价值与复杂度自动选挡,统一安全闸兜底 |
+| DW 数据补充进展? | 🟡 摄入链路侧补全(推送通道 + 表结构变更检测 + 字典重导);保险 / 专属客服等**字段仍待 DW 侧补齐** |
+| 还有什么新能力? | ✅ **PAC 能力开放给外部 agent**:外部系统的 AI 助手可经标准协议(MCP)安全调用患者画像 / 事实 / 召回工具 |
+
+### ▎走向终态(按当前节奏)
+
+```
+下一步 ⭐ 正式上线(真实客服日常使用 + 召回成效对照)
+   ↑ 需要: 业务验收(杭州大厦试点)结果 + 上线标准(GO/NO-GO)拍定
+W5 ✅ 核心引擎做扎实:DW 摄入补充 + 召回准度全量核验(44万牙位/误召0.023%)+ 画像 v3 标签系统 + AI 话术三挡(稳健/标准/深度)+ 能力开放给外部 agent(MCP)(本次报告)
+W4 ✅ 5 家试点全量数据上测试服务器 + 网络电话 + 实时 AI 辅助
+W3 ✅ 本地真实数据 demo + 潜在新链召回 + AI 话术 + 治疗链 5 阶段可视化
+W2 ✅ 数据接入文档 + 演示能力提前到位 + 召回算法策略落地
+W1 ✅ 框架定稿 + 数据库结构评审 closure
+```
+
+### ▎本周必须推动(求 CTO / 管委会协调)
+
+```
+🆘 1. 业务验收 + 上线标准(GO/NO-GO)
+       - 引擎已做扎实(召回准度有数 / 画像成系统 / 话术分挡),需业务实际验收来定方向
+       - 不验收 = 不知道"够好了可以上"还是"哪还要改",打磨没有终点
+
+🆘 2. DW 字段补齐(沿用 W4 未结项)
+       - 保险(商保保司名)/ 专属客服 等字段 DW 侧仍待补
+       - 影响:补齐后这些画像才能在页面真正显示
+```
+
+---
+
+## Page 2 · 本周做精的四件事(业务语言)
+
+### ▎① 召回"准不准" — 从"感觉准"到"有数可查"
+
+> 用独立的核对程序,对全量数据做**牙位级**正反校验(该召的召了没 / 不该召的有没有误召)。
+
+| 指标 | 结果 |
+|---|---|
+| 核验规模 | 44.4 万诊断牙位 · 8.6 万患者(全量,非抽样) |
+| 应治未治 → 正确召回 | 20.9 万 |
+| 已治疗 → 正确不召回 | 18.5 万 |
+| **误召**(已治却召回) | 104 例 = **0.023%**(且多为复发后的合理再召) |
+| 真正无法解释 | 2 例 = 0.0005% |
+| **硬红线违例**(逝者 / 拒联 / 已有预约仍召) | **0** ✅ |
+
+**本周修的两类典型偏差**:全口复发病(牙周 / 正畸)修复后又复发的,现在能正确"再入召回池"(找回 1,312 位被误排除的患者);缺失牙场景排除了智齿 / 正畸拔牙等噪声(降噪 663 颗牙,精度更高)。正畸漏召也从 5,554 例降到 1 例。
+
+### ▎② 画像 — 按 v3 文档落成"可运营的标签系统"
+
+> 不再是零散字段,而是一套**标签字典**:每个标签有结构化取值 + 证据(来自哪些事实)+ 人话描述。
+
+| 标签类 | 代表标签 |
+|---|---|
+| 人口属性 | 年龄段 / 性别 / 获客渠道 / 家庭结构 |
+| 价值与生命周期 | **RFM 价值分群(8 段)** / 生命周期阶段 / 权益状态 / 转介绍达人 |
+| 临床 | **潜在治疗(应治未治)** / 治疗史 / 紧迫度 / 禁忌 |
+| 行为偏好 | 就诊时间偏好 / 折扣锚点 / 特殊关注 / 治疗敏感 |
+
+**意义**:支撑"分层召回 + 精细化运营"——比如"高价值 + 应治未治 + 断口久"的患者可优先触达;每个标签都能点开看"为什么这么判"。
+
+### ▎③ AI 话术 — 升级"稳健 / 标准 / 深度"三挡
+
+> 客服看到的只是一个"挡位"旋钮,系统按患者价值与复杂度自动选挡。
+
+| 挡位 | 适用 | 特点 |
+|---|---|---|
+| **稳健** | 量大 / 标准场景 | 固定 4 段模板,稳定可控、近乎填空 |
+| **标准**(默认) | 常规 | 4 段自由结构,自然流畅 |
+| **深度** | 高价值 / 复杂 | 规划 → 撰写 → 自校验三步,质量更高 |
+
+三挡共用同一套**安全闸**(禁承诺疗效 / 禁报价 / 禁写死时间 / 禁不当医疗声明)+ 失败自动回退安全模板,客服永远不会"没话术可用"。知识库(诊断话术 × 人群 × 异议应对 × 安全规则)统一为单一真理源。
+
+### ▎④ 把 PAC 能力开放给外部 agent(新方向)
+
+> 让**外部系统的 AI 助手**(如宿主牙科系统里的客服 AI)能安全调用 PAC 的患者画像 / 事实 / 召回能力。
+
+- 用 2026 年业界标准协议 **MCP** 封装了 6 个**只读**工具(查患者 / 全景画像 / 患者事实 / 召回计划 / 召回队列);
+- **安全**:Bearer 令牌鉴权 + 租户硬隔离(外部 agent 只能看到授权租户的数据)+ 全只读(不改患者事实)+ 手机号掩码;
+- 本项目内做了一个**"外部 agent 模拟"助手页**(类 ChatGPT/Claude):模型自主决定调哪个工具,过程透明可见,结果还能用**卡片 / 图表(HTML)**可视化呈现。
+
+**意义**:PAC 不只服务自己的工作台,还能作为"患者智能中台"被宿主系统 / 外部 AI 复用——多一条对外赋能与商业化的路。
+
+---
+
+## Page 3 · W5 交付清单(说结果)
+
+| 方向 | 状态 | 实际成果 |
+|---|---|---|
+| **数仓数据摄入补充** | ✅ | 推送通道(延用拉取管线,宿主原生表结构直推)+ 宿主表结构 / 枚举变更检测 + 字典变更离线重导(不重连 DW)+ 增量游标防漂移 |
+| **召回算法提准** | ✅ | 全量牙位级核验(44万/8.6万);误召 0.023%、硬红线违例 0;修全口复发误排(找回 1,312 人)、缺失牙降噪、正畸漏召 5554→1 |
+| **画像 v3 标签** | ✅ | 16 个标签落地(4 类),结构化取值 + 证据链 + 人话描述,版本化幂等重算 |
+| **AI 话术三挡** | ✅ | 稳健 / 标准 / 深度三挡 + 统一安全闸 + 模板兜底 + 知识库单一真理源 |
+| **开放给外部 agent** | ✅ | MCP 只读服务(6 工具)+ 鉴权 / 租户隔离;外部 agent 模拟助手页(透明调用 + 卡片/图表可视化);已部署测试服务器 |
+
+### ▎W5 期间业务能力提升要点(管委会角度)
+
+| 能力 | W4 末 → W5 末 |
+|---|---|
+| 召回准度 | 补两处缺口 → **全量牙位级核验有数(误召 0.023% / 红线违例 0)** |
+| 画像 | 零散特征 → **可运营的 16 标签系统(可解释)** |
+| AI 话术 | 单一老版提示词 → **稳健 / 标准 / 深度三挡自动选** |
+| 数据摄入 | DW 直连拉取 → **+ 推送通道 + 表结构变更检测 + 字典重导** |
+| 对外能力 | 仅自有工作台 → **开放给外部 AI/agent 调用(MCP)** |
+
+---
+
+## Page 4 · 里程碑预告(等验收 → 上线)
+
+### ▎进行中(本阶段收口)
+
+```
+🎯 给管委会看
+  1. 召回准度 / 画像标签 / 话术三挡 — 拿到测试服务器上,等业务实际验收
+  2. DW 补充字段到齐后,保险 / 专属客服 等画像在页面真实显示
+  3. 部署流程固化(本周暴露的 dev/prod 配置脆弱点已修复,需脚本化避免再踩)
+```
+
+### ▎下一步 ⭐ · 看业务验收情况决定
+
+```
+🎯 业务验收(杭州大厦试点为主)
+  - 引擎已做扎实,接下来用真实业务验收来定方向:
+      验收通过 → 走上线标准(GO/NO-GO)+ 客服培训 + 灰度
+      验收有意见 → 按业务反馈继续打磨(画像优先标签 / 话术口径 / 召回阈值)
+
+🎯 上线标准讨论(需管委会拍定)
+  - GO/NO-GO 口径:召回准度达到什么线 / 试点验收看哪几个指标 / 灰度范围与节奏
+```
+
+---
+
+## Page 5 · 风险 + 依赖
+
+### ▎本周风险
+
+| # | 风险 | 等级 | 现状 | 求协调 |
+|---|---|---|---|---|
+| 1 | **业务验收未启动** | 🟡 中 | 引擎已扎实,但缺业务实际验收来定方向 | 安排杭州大厦试点业务验收 |
+| 2 | **上线标准未定** | 🟡 中 | 打磨没有明确终点判据 | 管委会拍定 GO/NO-GO 指标 |
+| 3 | **DW 字段补充**(沿用) | 🟡 中 | 保险保司名 / 专属客服等字段待补 | DW 团队补齐 + 重摄入 |
+| 4 | **召回准度业务校准** | 🟢 收敛中 | 技术核验 0.023% 误召,但"算法对" ≠ "业务认可",需场景化抽样 | W6 业务抽样审查 |
+| 5 | **部署流程脆弱 / 安全** | 🟡 中 | 见下"不报喜不报忧",本周已修复,需固化 | 列入 W6 工程化 |
+
+### ▎不报喜不报忧(W5 实际遇到的问题 + 怎么解的)
+
+| 问题 | 现象 | 处理 |
+|---|---|---|
+| 部署混了 dev/prod 模式 | 误用开发模式部署 + 库密码源不统一,一度服务异常 | 已恢复为标准生产模式(独立 prod 配置)、密码对齐;**需 W6 固化部署脚本 / CI 避免人工踩坑** |
+| mock 登录端口在生产未关 | 测试用的"一键登录"在生产仍可用 = 安全隐患 | 已定位,列入 W6 优先修(生产环境禁用) |
+| 外部 agent 模型适配 | 不同大模型对工具调用 / 输出格式要求不一 | 统一适配层(provider 可切换),已通 DeepSeek / 通义千问 / Gemini |
+| 可视化卡片首屏空白 | 流式生成时渲染容器空白 | 改"持久容器 + 增量注入",卡片实时"长出"不再空白 |
+
+### ▎资源依赖矩阵
+
+```
+W5 ✅:PAC 1 人 + AI 完成算法核验 / 画像 / 话术 / 开放 agent / 部署(轻借力)
+进行中:PAC 1 人 + DW 1 人(补字段)+ 业务(验收)(中借力)
+下一步:PAC 1 人 + 管委会(上线标准)+ 业务(验收 + 画像优先级)+ 客服培训(重借力)
+```
+
+---
+
+## ▎下一份报告预告
+
+**承诺给管委会看**:
+1. 业务验收(杭州大厦试点)结果 + 据此定的方向(上线 / 继续打磨)
+2. 上线标准(GO/NO-GO)讨论结论
+3. DW 字段补齐后画像在页面的真实显示
+4. 部署流程固化 + 生产安全收口(mock 登录关闭等)
+
+**汇报形式**:沿用"一页 Demo + 业务语言"风格,继续 Demo over Memo。
+
+---
+
+## ▎附件(留参考)
+
+| 附件 | 内容 |
+|---|---|
+| algorithm/recall-verification.md | 召回准度核验方法 + 全量结果 |
+| algorithm/persona-design-v2.md | 画像标签系统设计(16 标签 / 取数模式 / 证据链) |
+| algorithm/ai-script-generation.md | AI 话术三挡(稳健/标准/深度)+ 安全闸 + 知识库 |
+| algorithm/canonical-fact-layer.md | 事实层归一 + 字典 / 枚举 + 摄入可靠性 |
+| host-integration-push.md | 推送通道契约(宿主侧)+ 表结构变更检测 |
+| (开放能力)MCP 只读服务 + 外部 agent 模拟助手 | PAC 患者能力对外开放 |
+
+---
+
+> **核心信号**:W5 把引擎做扎实 — 召回准度有数(误召 0.023%)、画像成 16 标签系统、话术分稳健/标准/深度三挡、能力开放给外部 agent;下一步看业务验收结果定"上线 or 继续打磨"。