食疗专家（Diet Therapy Expert）
Overview
依据个人健康档案（年龄、常驻地址、身高体重、既往病史、现有基础疾病、过敏忌口、饮食偏好、兴趣、运动习惯）生成个性化食疗方案：推荐食材清单、慎食/禁忌清单、一日三餐搭配、疾病与体质调理重点、运动作息建议。
本技能以 HTTP 接口 形式对外提供服务，采用 支付宝 AI 按量付费（Alipay AI Pay-per-Use） 计费模式：每次调用按次计费，未付费调用返回 402 账单，付费后携带支付凭证重试完成履约。
触发方式
当用户需要个性化食疗/膳食方案、慢病饮食管理、营养配餐，或需要构建/接入按量付费的食疗服务接口时，使用本技能。
技能能力
- 健康档案采集：九要素（年龄、常驻地址、身高体重、既往病史、基础疾病、过敏忌口、饮食偏好、兴趣、运动频率/强度），选填可跳过、必填做校验。
- 个性化方案生成：推荐食材、慎食/禁忌、一日三餐、调理重点、运动作息建议。
- 慢病营养管理：覆盖高血压、糖尿病、高血脂、痛风、胃病、失眠、贫血等常见疾病。
- 按量付费接口：402 账单下发、Payment-Proof 验付、履约确认（ack）、订单持久化与幂等。
技能接口（Interfaces）
本技能暴露以下 HTTP 接口，全部遵循支付宝 AI 按量付费协议：
| 接口 | 方法 | 说明 | 协议阶段 |
|---|---|---|---|
/shiliao/v1/probe |
POST | 预检/询价：返回是否需付费、账单预估 | probe |
/shiliao/v1/pay |
POST | 创建订单并返回支付宝支付参数 | pay |
/shiliao/v1/complete |
POST | 验付 + 履约：校验 Payment-Proof 后生成方案 | complete |
/shiliao/v1/ack |
POST | 履约确认：返回支付完成与结果回执（幂等） | ack |
probe（预检/询价）
调用方在正式请求前调用 probe，传入待生成的方案类型与参数，服务端返回 probe 结果：是否需要付费、账单预估金额、可用功能清单，供调用方决定是否发起支付。
pay（下单支付）
调用方调用付费业务接口（如 complete）但尚未支付时，服务端返回 HTTP 402 Payment Required，并在响应头与响应体下发账单（订单号 payment-order-id、金额、币种、支付链接/二维码、Payment-Needed 标记）。调用方凭账单跳转支付宝完成支付。
complete（验付 + 履约）
调用方完成支付后携带支付凭证重试：在请求头 Payment-Proof 中传入支付凭证，服务端调用支付宝验付接口校验凭证有效性（是否真实支付、金额是否匹配、订单是否匹配）。校验通过后执行实际业务逻辑（生成食疗方案），返回方案结果与支付完成信息。
ack（履约确认）
业务完成后返回 ack 回执（订单号、支付状态、履约结果）。ack 与业务结果幂等：同一订单重复请求只返回首次履约结果，不重复执行、不重复扣费。
支付宝 AI 按量付费协议（Alipay AI Pay-per-Use）
协议字段
| 字段 | 位置 | 说明 |
|---|---|---|
402 |
HTTP 状态码 | Payment Required，需要付费 |
Payment-Needed |
响应头 / 响应体 | 标记需要付费，值为 true 时需支付 |
Payment-Proof |
请求头 | 支付凭证，调用方支付后重试时携带 |
payment-order-id |
响应体 / 请求头 | 订单号，用于持久化与幂等 |
Idempotency-Key |
请求头 | 请求幂等键，防止重复扣款/重复履约 |
ack |
响应体 | 履约确认回执（订单号、支付状态、结果） |
支付流程（probe → pay → complete → ack）
- probe（预检）：调用方先
probe询价，确认是否需要付费与费用。 - pay（下单支付）：首次调用业务接口未付费 → 服务端返回
402+Payment-Needed账单 → 调用方跳转支付宝支付。 - complete（验付履约）：调用方携带
Payment-Proof重试 → 服务端验付 → 校验通过后执行业务逻辑。 - ack（履约确认）：服务端返回结果 +
ack回执，标记支付完成与履约完成。
1. 402 账单下发
需要付费时，服务端返回 HTTP 402 Payment Required，并在响应头 Payment-Needed: true 与响应体中下发账单：
{
"code": "PAYMENT_REQUIRED",
"payment-needed": true,
"payment-order-id": "ORD-20260919-0001",
"amount": "1.00",
"currency": "CNY",
"pay-url": "https://openapi.alipay.com/gateway.do?out_trade_no=ORD-20260919-0001",
"message": "请完成支付后携带 Payment-Proof 重试"
}
2. 携带凭证重试（Payment-Proof）
调用方收到 402 后完成支付宝支付，在重试请求的请求头携带支付凭证：
POST /shiliao/v1/complete HTTP/1.1
Payment-Proof: ALIPAY-PROOF-<交易号或凭证串>
payment-order-id: ORD-20260919-0001
Idempotency-Key: <调用方生成的幂等键>
3. 验付调用
服务端对 Payment-Proof 调用支付宝验付接口（alipay.trade.query 或异步通知验签）逐项校验：
- 凭证真实且未被使用；
- 支付金额与账单金额一致；
- 订单号与 payment-order-id 匹配；
- 支付状态为「已支付」。
验付失败返回 402（仍需支付）或明确错误码，不执行任何业务逻辑。
4. 履约确认（ack）
验付通过后执行实际业务逻辑（生成食疗方案），返回支付完成信息与 ack 回执：
{
"code": "OK",
"payment-order-id": "ORD-20260919-0001",
"paid": true,
"ack": { "status": "FULFILLED", "result": "<食疗方案结果>" }
}
5. 订单持久化与幂等
- 订单持久化：将订单号、支付状态（待支付 / 已支付 / 已履约 / 已退款）持久化到数据库或存储。
- 幂等去重：按
payment-order-id或Idempotency-Key去重——同一订单/幂等键的重复请求直接返回首次结果，避免重复扣款与重复履约。 - 状态机：
待支付 → 已支付 → 已履约；已履约订单再次请求直接返回ack，不重复执行。
支付依赖（Dependencies）
| 依赖包 | 环境 | 用途 |
|---|---|---|
alipay-sdk-python |
Python | 支付宝开放平台官方 SDK（下单、验付、验签） |
alipay-sdk |
Node.js | 支付宝开放平台 Node SDK |
cryptography |
Python | 支付回调验签（RSA2） |
requests |
Python | 调用支付宝网关 HTTP 接口 |
具体版本见 requirements.txt（Python）与 package.json（Node.js）。
Resources
references/payment-protocol.md：支付宝 AI 按量付费协议完整规范（402 / Payment-Needed / Payment-Proof、probe / pay / complete / ack、验付与幂等）。scripts/payment_gateway.py：支付网关示例实现（402 账单下发、验付、履约确认、订单持久化与幂等）。requirements.txt、package.json：支付相关依赖清单。
