犀见 ↔ 消息工作台 集成契约 v1（P0-6.2）

版本：v1.0 定稿 ｜ 2026-08-16 ｜ 作者：product-owner ｜ 终验：主会话（裁决见 §6 表） 上游：口径基线 v2.1（唯一口径源）｜ 总纲领 v1.3 §5 ｜ 盘点 docs/dev/message-api-notes.md（下称「盘点」，细节一律引其节号，本文不复述） 下游：P0-6.3（msgbridge 客户端）、P0-6.4（缺口处置）、P1-7/P1-8/P1-11 全部按本文开发。触达类功能的总闸：本文没写的触达场景不许开工。

---

1. 总则

定位澄清（用户确认 2026-08-16）：消息台深度融入统一运营台——对用户是一个产品（主工作面板即消息台形态，总纲领 §5），不是两个独立运行的系统；「集成契约」指的是代码层面的服务间接口（消息台作为企微执行层服务化部署），产品层面无缝一体。

1.1 分工边界（架构级，不可协商）

犀见 server 绝不自建企微发送通道（盘点 §3「推论对犀见的约束」）：消息台的发送限流是单 gunicorn 进程的内存状态，任何绕过它的发送路径都会让两边各限各的、合起来突破企微真实上限，代价是封号（封号=整条触达链全断）。犀见所有主动触达一律经消息台 API。

1.2 通道与身份

• 通道：http://127.0.0.1:5040（同机部署，115）。不走 message.lynoxi.com（公网入口由 nginx Basic Auth 挡，非服务间通道）。
• 身份头（每个请求必带）：X-Auth-User: xijian-server、X-Auth-Oid: system-xijian。消息台 _operator() 直接信任这两个头；不带则 operator=unknown，定价等落库接口 403（盘点 §6 认证缺口）。
• 安全前提与风险边界：消息台生产 .env 未配置 FEISHU_APP_ID，/api/* 在内网无需任何凭证（已核实）。因此本方案的全部安全性来自「服务只监听回环 + 同机」这一网络边界，不来自凭证。跨机部署即失效——届时必须升级为真凭证（mTLS 或消息台侧加 API Key）。升级钩子：server 侧 MSGBRIDGE_AUTH_MODE=header（v1 唯一实现值），换值即换鉴权实现，现在不做。
• 反向（消息台→犀见）鉴权见 §3.5，v1 只定形状不实现。

1.3 限流继承声明（照录盘点 §3，犀见侧一律只继承不重设）

犀见侧不设本地限流副本：额度一律实时读 GET /api/send-quota（发送）与 GET /api/addfriend 返回的 quota/config（加人）。理由——把 20/300 抄进犀见 cfg 会制造两份真相且必然漂移；真闸在消息台，犀见只做「发之前先看余量、余量不够就排队」。

1.4 shadow-first 纪律

• 每个触达场景先 shadow 后 live，无例外。开关走犀见配置中心：全局 msgbridge.mode（off/shadow/live，默认 off）+ 场景级 msgbridge.scene_mode.<scene>（默认继承全局；取二者中更保守的一档）。
• shadow 语义（对齐消息台 aimode 三态，盘点 §3）：名单计算、文案组装、幂等占位、审计落库全跑；不发出任何写类 HTTP 请求（读类预检照常）。审计记 mode=shadow。
• off 语义：连请求都不构造，接口直接返回 {ok:false, reason:"msgbridge_off"}。
• 流程等级：本契约涉及的一切 live 触达 = 全评审链（总纲领 §6「对外发送（企微）」）；shadow 期实现走轻流程 + api-tester 的「shadow 模式零真实调用」断言（P0-6.5）。
• 场景枚举（scene，全局唯一，审计与开关都用它）：invite.addfriend / invite.message / invite.card / onboard.card / urge.underperform / urge.sla / order.visitor_invite（报名确认→入园信息邀请，基线 §6.4）/ order.group_pull（报名确认→拉群，基线 §6.5）——后两个 v1.1 追加（P0-5.1 设计 S13 裁决，2026-08-17）。

---

2. 方向一：server → 消息台

2.1 场景 ②A 一键定向邀约（基线 §3 ②A、§6.9、§6.11）

前置铁律：名单由人工反选拍板（基线 §5「反选永不自动化」）；server 只执行已确认名单。名单在发起时快照落库（invite_batch_member），运行期不允许扩名单——对应 §6.9 判据「名单外不发」。

A1 未建联/未加好友者 → 批量好友申请（基线 §6.11）

1. server 取名单手机号（基线 §0：企微只能搜手机号）；无手机号者明确列出并提示，不静默跳过（§6.11 判据 2）
2. POST /api/addfriend body {phones:[...], guids:[...], mode:"balance", verifyText, note:"xijian:<batch_no>"} → {ok,id,job}
3. POST /api/addfriend/<jid>/confirm body {count: len(phones)}（数量原样确认）
4. POST /api/addfriend/<jid>/start

5. 轮询 GET /api/addfriend/<jid> 取明细（策略见 §4.3）

6. 幂等：note 写 xijian:<batch_no> 作业务幂等标记；建 job 前先 GET /api/addfriend 按该前缀查重，命中则复用不重建（消息台无幂等键，缺口 4）。

7. 重试：仅 create 阶段失败可重试（有查重兜底）；start 之后不重试。
8. shadow：跑到步骤 1 + GET /api/addfriend 读余量为止。

A2 已是好友者 → 邀约消息 + 入驻/任务卡片

1. 身份翻译（§2.5）拿到 (guid,userId)
2. GET /api/conv-of?guid=&userId= → cid；无会话则 POST /api/conv/new {userId,guid}
3. 文案：POST /api/conv/<cid>/send {text}（模板 cfg，见 §5）
4. 卡片：POST /api/conv/<cid>/send-miniprogram {pageKey,title,desc,taskId} → {ok,wcid,path}

5. 人数 > msgbridge.urge_batch_threshold 时改走群发：POST /api/broadcast {guid,targets,msgs,sendType,note:"xijian:<batch_no>"} → POST /api/broadcast/<bid>/confirm {count} → POST /api/broadcast/<bid>/send

6. 批次归因（§6.9 判据 2「报名意向可关联回邀约批次」）：用步骤 4 返回的 wcid 作归因键，server 存 wcid ↔ (batch_id, influencer_id)；达人点卡片后 wcid 回流即完成漏斗闭环。不新增任何接口。

7. 审计：每人一条 msgbridge.invite.*，记 scene/batch_id/influencer_id/peer/mode/wcid/消息台返回。

2.2 场景 一键催发（基线 §6.10 人工触发；§4 时效自动触发）

口径红线（契约级断言，api-tester 必测）：请求必带 trigger ∈ {manual, auto}。 - scene=urge.underperform（数据不达标催发，§6.10/§7.2）只接受 trigger=manual——「系统绝不自动催发不达标达人，着急的是达人」。trigger=auto + 该 scene → 422。 - scene=urge.sla（时效超时催发，§4）可 auto，对全量达人统一标准（§4 v2.0 口径）。

调用序列（单发）：身份翻译（§2.5）→ GET /api/conv-of → POST /api/conv/<cid>/send {text}；需要挂在某条消息下时用 POST /api/conv/<cid>/reply {text,quoteUid}（拼不出结构会 degraded:true 降级成普通发送，server 按成功记但审计标 degraded）。 批量（> 阈值）：POST /api/broadcast → /confirm {count} → /send（≤500 人/次）。

• 幂等（缺口 4 的犀见侧解法）：touch_log(scene, influencer_id, biz_date) 唯一索引，先占后发（先 INSERT 抢占，再调发送）；同一 scene+同一人在 msgbridge.dedupe_window_hours 内只发一次。
• 重试策略：
• 网络错误/5xx：最多 msgbridge.retry_max 次指数退避；
• {ok:false, rateLimited:true}：不重试，转延后队列（msgbridge.rate_limited_backoff_minutes 后重排）；
• 4xx：不重试，标 failed；
• 超时无响应：不自动重试，标 unknown 转人工确认。理由：发送接口无幂等键，超时时「是否已发出」不可知，重发的代价（骚扰达人/触发风控）高于漏发。
• 审计：msgbridge.urge.*，必记 trigger、operator、文案摘要（≤200 字）。

2.3 场景 入驻卡片触达（基线 §6.1）

• 接口：POST /api/conv/<cid>/send-miniprogram {pageKey,title,desc,taskId}；pageKey 必须在 GET /api/miniprogram/pages 清单内（appId wx120205414255fb5b，与犀见 miniapp 同一小程序）。
• 三分支落地页判定归 server（§6.1）：已入驻→首页 / 配某次招募→任务详情页（带 taskId）/ 新达人→入驻页。判定依据在犀见达人域，编排位置正确。
• 与消息台自动欢迎卡片去重：消息台 XIJIAN_WELCOME_CARD=1 已在生产开启，新好友会自动收到一张卡。server 发卡前查 GET /api/conv/<cid>/binding 的 pendingCards，若存在未点开卡片且在 msgbridge.dedupe_window_hours 内，跳过并记审计 skipped，避免同一人被连轰两张卡。
• taskId 语义见待裁决 D6；v1 期未确认前只传犀见已知可对齐的值或留空，批次归因一律靠 wcid，不依赖 taskId。

2.4 场景 会话查看嵌入（P0 明确不做）

可用接口：GET /api/state、GET /api/conv/<cid>、GET /api/conv/<cid>/history、GET /api/search——均为整页人工界面设计的重接口（盘点 §6）。 P0 决策：不做嵌入。 北极星判据：只读会话不减少任何达运人工动作（运营已有消息台界面，且总纲领 §5 定调「主工作面板就是消息台」），为它做裁剪接口属镀金（三不原则第 3 条）。P0 只用轻接口 GET /api/conv-of、GET /api/conv/<cid>/binding。P1（随 P2-16 前端融合）再议是否要裁剪版只读接口。

2.5 「业务条件 → 企微身份」翻译链路（催发/邀约共用，唯一正解）

influencer_id →（达人域档案）→ 手机号/抖音号 →（绑定关系）→ peer(guid,userId) → GET /api/conv-of → cid。

关键：不要试图用手机号在企微侧搜人——企微不给外部联系人手机号/微信号（contactType 2057 实测全空，盘点 §7），GET /api/contacts?kw=<手机号> 对外部联系人基本搜不到。可靠的唯一桥是绑定关系（wcid 回流或人工绑定，盘点 §4）。因此：

• server 建本地镜像表 binding_mirror(influencer_id, guid, peer_user_id, conv_id, source, synced_at)；（实现表名定案 influencer_binding，归达人域、字段为本契约形状的超集——P0-2.3 设计 S6 裁决，2026-08-16）
• 写入源 ①：wcid 回流即时写（§3.1）；源 ②：定期对账 GET /api/contacts?bound=1&limit=5000（该接口带 bound 参数，返回含 influencerId）；
• 未命中绑定的达人 = 不可触达，一律进「无法触达清单」显式呈现，不静默跳过（与 §6.11 判据 2 同一纪律）。

---

3. 方向二：消息台 → server

3.1 wcid 绑定回流（归属决策，待裁决 D1）

PO 推荐方案：沿用消息台协议签发与兑现，犀见 server 只做镜像。 - 犀见新 miniapp 拿到 wcid 后仍调 POST /api/wcid/redeem（公网固定入口 api.lynoxi.com/qiwe/wcid/redeem，无鉴权、HMAC 自证、30 天 TTL）； - redeem 成功后 miniapp 再调犀见 POST /api/miniapp/binding/redeemed {wcid, influencerId, openId}，server 写 binding_mirror 并触发 P0-3.1 建联入档。 - 推荐理由：① WCID_SECRET 只在消息台，犀见自签需复制密钥跨服务，双签发一旦密钥不同步即全链断；② 绑定权威表 peer_binding 在消息台（人工绑定也写那里），双写会造出两份真相；③ 卡片由消息台发出，token 由发卡方签发天然内聚；④ 犀见真正需要的只是「绑定发生了」这一事实，镜像足够。 - 风险与缓解：miniapp 需连调两个后端 → 顺序固定「先 redeem（权威）后通知犀见」；通知犀见失败不阻塞达人流程，靠 §4.3 的绑定对账轮询兜底补齐。 - 备选（若主会话裁定犀见自签）：需下发 WCID_SECRET、复刻 bind.make_wcid（约 30 行，盘点 §5），消息台 verify 侧不变——代价是密钥同步与两处生成逻辑必须永远一致。

3.2 绑定状态查询

GET/POST/DELETE /api/conv/<cid>/binding（单会话 CRUD，POST body {influencerId,taskId,note}，source=manual 优先级高于 wcid 自动绑定，不被覆盖）；GET /api/binding/stats（总数+来源分布，看板用）；按 influencer_id 反查见 §2.5 镜像方案。

3.3 议价落库（基线 §6.2，实现排 P1-11.1，v1 只定形状）

• 消息台侧现状：GET/POST /api/conv/<cid>/price（存自己 SQLite，POST 需身份头且不选证据不能提交，金额以分、追加不覆盖）。
• v1 采用犀见轮询拉取（GET /api/conv/<cid>/price 读 {ok,latest,history}），不要求消息台改代码调犀见（用户定案：老代码不动不管）。轮询集合受控——只轮「活跃商单关联的 cid」，不全量扫（§4.3）。
• 犀见承接接口形状（P1 实现）：POST /api/msgbridge/price-quotes {convId, peerId, influencerId, orderId, priceFen, evidenceUid, note, operator, confirmed, confirmedAt}。红线：evidenceUid 缺失 → 422；confirmed != true → 零写入（§6.2 判据 3）；写入后挂 §7.5 三数一致校验与 R3 价差告警。资金相关 = 全评审链。

3.4 阶段状态与档案（犀见供给侧，实现排 P1，AI 回复 9-10 里程碑）

业务阶段（基线 §3 的 12+2）权威在犀见，消息台侧的 handling（auto/escalated/taken/done）是会话处理态，两者不是一回事，禁止互相映射。犀见对外只读接口形状： GET /api/msgbridge/stage?douyin_id=|phone=|influencer_id= → 当前阶段 + 关联商单；GET /api/msgbridge/influencer?douyin_id=|phone= → 档案（§6.8 判据）。

3.5 反向鉴权（待裁决 D7）

建议：同机回环 + 犀见侧固定 X-Msgbridge-Token（放 server .env，非业务 cfg）。v1 不实现。

---

4. 盘点 §6 五项缺口逐项处置

4.3 轮询三原则（缺口 3 的落地纪律，工程铁律 3：轮询按实体去重，防 binlog 洪水）

1. 受控集合：只轮与「运行中的 addfriend job / 活跃邀约批次 / 活跃商单」关联的实体，永不全量扫 GET /api/state。
2. 变更才写：每轮对 (scene, entity_id, fingerprint) 比对，值未变零写入、零事件（消息台 store.set_handling() 是同一纪律的先例，盘点 §3）。
3. 水位/游标：addfriend 用 job 状态 + 已处理明细序号；price 用 latest.ts 水位；binding 用 synced_at 对账时间戳。
4. 频率（全部 cfg）：addfriend job 30s（仅任务运行中，终态即停）；binding 对账 60 分钟；price 5 分钟（仅活跃商单）。任务无活跃实体时轮询器空转不发请求。

---

5. 配置项清单

A. 走犀见配置中心（cfg，判定/开关；键名规范 域.蛇形名，需补入基线 §12A —— 补入动作待主会话批准，本次未改基线）

B. 走 server 环境配置（.env，部署事实非业务口径，不进配置中心） MSGBRIDGE_BASE_URL=http://127.0.0.1:5040、MSGBRIDGE_AUTH_MODE=header、MSGBRIDGE_AUTH_USER=xijian-server、MSGBRIDGE_AUTH_OID=system-xijian、MSGBRIDGE_TIMEOUT_READ=10、MSGBRIDGE_TIMEOUT_WRITE=30。

C. 明确不设本地副本：发送限流 20/分·300/时、加人 20/号/天 —— 见 §1.3，实时读消息台接口，禁止抄进 cfg。

---

6. 待裁决事项表（主会话已裁决，2026-08-16）

---

7. 验收判据（P0-6.3/6.4/6.5 共用，qa-acceptor 逐项实证）

• [ ] msgbridge.mode=off 时任一触达接口返回 {ok:false, reason:"msgbridge_off"} 且抓包零出站请求
• [ ] msgbridge.mode=shadow 时触达接口返回 200、审计有 mode=shadow 记录、mock 服务端零写类请求（P0-6.5 断言）
• [ ] scene=urge.underperform + trigger=auto → 422（基线 §6.10/§7.2 红线）
• [ ] 同一 (scene, influencer_id, 当日) 第二次调用返回 deduped，不产生第二次发送
• [ ] 发送超时（mock 不响应）→ 记录标 unknown，不自动重发
• [ ] 名单外 peer 不出现在任何出站请求 payload 中（§6.9 判据）
• [ ] 无手机号达人出现在「无法发起」清单，非静默跳过（§6.11 判据）
• [ ] 未绑定达人出现在「无法触达」清单
• [ ] 所有出站请求带 X-Auth-User: xijian-server 与 X-Auth-Oid: system-xijian
• [ ] 轮询器在无活跃实体时零出站请求；值未变时零写库（铁律 3）

---

变更记录