# 第 14 章 · 消息内卡片协议（对话即大厅的落地格式）

> 老板要求：**不要点进去，要在聊天对话里直接显示作战大厅那样的卡片。**
> 本章定两套渲染：**① Markdown 版（今天就能用）** ② **原生版（改本体后渲染成真卡片）**。

---

## 14.1 卡片清单（一条消息里最多 5 张卡）

| 卡 | 用途 | 必含元素 |
|---|---|---|
| **指挥条** | 一眼看全局 | 今日战果 / 待发货 / 在线部队 / 弹药 |
| **此刻该干** | 动态引导，只推一条 | 一句结论 + 一句理由 + **1 主按钮 + 1 次按钮** |
| **态势格** | 分区数字（履约 / 侦察哨 / 账本） | 3–5 格，红色=要处理，绿色=好 |
| **风险卡** | 阻断级/观察级/机会级 | 依据（可解释）+ 代价 + 处置按钮 |
| **流水卡** | 全自动在干什么 | 时间 · 平台 · 动作 · 依据 · 花费 · **〔我不同意〕** |
| **控制卡** | 三根杆 | 档位 / 油门 / 红线，各自可点 |

## 14.2 Markdown 版（当前可用，零改造）

| 元素 | 用什么表达 |
|---|---|
| 卡片 | `>` 引用块（左侧竖线，像卡边） |
| 态势格 | Markdown 表格（自带边框线） |
| 进度 / 仪表 / 收据 | 围栏代码块（等宽对齐）+ `▰▰▰░░░` |
| **按钮** | Markdown 链接（可点）→ 本机动作口 / 原生 scheme |
| 强调 | 加粗（结论）+ emoji（图标，颜色语义由 emoji 承担：🔴🟡🟢） |

**约束**：一屏最多 1 个主按钮；数字必须大（用表格单列 + 加粗）；小字只做解释。

## 14.3 原生版（改本体后，M1–M5）

````
```a9ui
{"kind":"hall",
 "bar":{"战果":"8.6万","待发货":"68","部队":"3支"},
 "guide":{"tag":"履约第一优先","t":"面单打不出来","s":"…",
          "primary":{"id":"setup_printer","label":"接打印机"},
          "secondary":{"id":"view_orders","label":"先看订单"}},
 "grid":[{"k":"高危买家","v":3,"level":"red"},{"k":"可疑订单","v":5}],
 "log":[{"t":"19:44:11","w":"物流","a":"追踪36单·0异常","cost":"6.3k"}],
 "levers":{"mode":"auto","throttle":"steady","cap":1800}}
```
````
→ 渲染成真卡片：真按钮（点击零跳转）、真颜色、真进度条。
**动作 id 与 Markdown 版链接里的 `do=` 完全一致**（同一套动作表，两端行为一致）。

## 14.4 动作 id 总表（唯一口径，三端共用）

| id | 含义 | 闸门 |
|---|---|---|
| `setup_printer` | 接打印机（三步陪跑） | 无 |
| `print_urgent` / `print_all` | 打超时单 / 打全部 | >50 张二次确认 |
| `call_courier` | 呼叫快递上门 | 无 |
| `chase_express` | 自动催单 | 无 |
| `block_high` | 发货前拦高危单 | 确认（挡生意） |
| `clear_high` | 放行但加防 | 无 |
| `vip_recall` | 老客召回券 | **必须确认（花钱）** |
| `approve_job` | 放行不可逆作业 | **必须确认** |
| `reject_log` | 〔我不同意〕撤销某条自动动作 | 无 |
| `set_mode` / `set_throttle` / `set_cap` | 三根杆 | 无 |

## 14.5 验收判据

- **C1** 对话内一次回复即包含指挥条 + 引导 + 至少一张态势/风险卡（无需跳页）
- **C2** 每条引导卡恰好 1 主 1 次按钮；主按钮 ≥ 视觉最重
- **C3** 流水卡每条含依据与花费，且能〔我不同意〕
- **C4** Markdown 版与原生版动作 id 一致，点击后行为一致
- **C5** 数字可读性：数值字号 ≥ 正文 1.5 倍，小字不承载关键信息

---

## 14.6 首屏布局顺序（作战指挥心理 · 2026-09-29 老板纠正后定稿）

> 老板原话：「首页首先看到是接入打印机很莫名其妙，应该直观看到全渠道经营情况，布局要符合作战指挥心理。」
> 病根：**把"装备"当成了"战况"**，把工具卡放在了首屏第一视线。

**布局铁律（顺序即心理学）**

| 序 | 分区 | 回答的问题 | 允许出现的卡 |
|---|---|---|---|
| ① | 今日战果 | 今天赚了多少、有没有火 | `bar`（2×2 大数字，红格=要处理） |
| ② | 全渠道战线 | 哪个渠道在涨、哪个在掉 | `channels` |
| ③ | 此刻该干这一件 | 我现在动手干什么 | `guide`（全页**仅一张**，带时限） |
| ④ | 风险与拍板 | 火在哪、等谁点头 | `risk`（`alert` / `approval`） |
| ⑤ | 执行与账本 | 钱和货走到哪了 | `progress` + `receipt` |
| ⑥ | 自动驾驶流水 | 它自己干了什么 | `log` |
| ⑦ | 控制杆 | 方向盘还在我手上吗 | `levers` |
| ⑧ | 战备检查 | 装备缺什么（**折叠、置底、虚线卡**） | `equipment` |

**四条硬约束**

1. **装备不上战场**：`setup_printer` 这类"接打印机/连平台/补资料"只允许出现在 ⑧ 战备检查 或 ⑤ 履约卡内的黄色提示 —— **不得占据首屏第一视线、不得当作 ③ 行动卡（除非它此刻真的阻断出单）**。
2. **一件事原则**：③ 只推一件、带时限（如「40 分钟内」），其余候选进 ④。
3. **先态势后动作**：没有任何行动卡可以排在 ①② 之上；数字先于建议。
4. **一屏两分区**：手机首屏必须完整呈现 ①+② 开头（实测 430×932 满足）。

分区标题由服务端 `cards[].sec` 下发，渲染器只在 `sec` 变化时插一次标题（前端不写业务顺序）。

## 14.7 协议增补 v1.1 · 两个新结构卡型

| 结构卡型 | 业务名 | 用途 | 关键字段 |
|---|---|---|---|
| `channels` | `frontline` | 全渠道战线（一行一渠道） | `title` `note` `rows[]{name,tag,gmv,orders,cvr,level,delta,w}`（`w`=占比%） |
| `equipment` | `binding` | 战备检查（链路/装备，置底折叠） | `title` `note` `items[]{k,v,level,fix,fixId}` |

`rows[].w` 直接决定占比条宽度；占比条色阶由渲染器给（5 段蓝阶），服务端不下发颜色。

## 14.8 演示 / 实操 双模式（老板令 2026-09-29）

> 老板原话：「演示数字可以接入我的所有真实店铺数据，但用户操作不要触发任何真实操作，只给演示操作。我登录后可以实际操作。」

**两条互不冲突的轴**（关键：数据与操作分开管）

| 轴 | 允许 | 由谁决定 |
|---|---|---|
| **数据** | 可接**真实店铺数据（只读）**——演示态也能看真数字 | 契约 `dataSource.kind = demo \| real` |
| **操作** | **演示态一律不落地**（不 POST、不写后端、不打单/拦单/改价/花钱）；只有**店主凭据**在场才是实操 | 客户端判定 `localStorage.a9_owner`（服务端签发，前端不伪造） |

**契约字段**

```json
{"dataSource":{"kind":"demo","label":"演示数据","note":"…"},
 "opMode":{"mode":"demo","label":"演示操作","note":"点击不产生任何真实后果"}}
```

**客户端行为（已实现，两端同口径）**

| 状态 | 头部标识 | 点击 `data-act` | 网络 |
|---|---|---|---|
| 演示（无店主凭据） | `操作 · 演示（不落真单）` | 记入本地演示流水（`a9_demo_ops`，上限 50 条）+ toast 明示「不会真的执行」+ 按钮回显「演示 ✓（未执行）」 | **不发 `/act`** |
| 实操（店主凭据在场） | `操作 · 实操（真实生效）` | POST `/act`，成功/失败都回显真实返回码 | 真请求 |

**硬约束**：体验登录（任意手机号）**不等于**店主身份 —— 仍是演示态；实操凭据必须由服务端签发（`a9-owner` 角色），不得由前端自造。

## 14.9 可验证性与主体信息（回应"幽灵平台"质疑）

被质疑"只有界面没有证据"时，**用可校验的东西回话，不用形容词**。首页底部固定一块「这是什么 · 可验证的部分」：

| 项 | 内容要求 |
|---|---|
| 定位 | 自用系统，不是招商平台（明说：不收加盟费 / 不拉人头 / 不代收代付 / 不承诺收益） |
| 主体 | 真实经营者与所在地；**不公示个人手机号**；主体信息以正式公示为准（不得编造备案号/执照号） |
| 数据 | 当前是演示还是真实只读接入，一句话说清 |
| 操作 | 演示不落地 / 实操需凭据 |
| 协议 · 契约 | 直链协议文档与 `a9ui.json`（外部可独立取用） |
| 自证 | 给出 `curl … | md5sum` 命令，任何交付可逐位复验 |
| 澄清 | 与其它同名「A9」项目无关（切成"我们是什么"，不复述对方名字） |

配套：页面必须有**真语义标题**（`h1` 站名 / `h2` 分区 / `h3` 卡标题）+ **JSON-LD**（`WebApplication` + `disambiguatingDescription` 主体澄清），否则爬虫读到的是"无标题无结构"的空壳。