# 工具契约与失败检查

给即将接入模型的业务能力使用。先确定身份、作用与完成语义，再写工具描述。解释见[工具与集成](/methods/tools-integration)。

## 填写内容

工具用途及禁止用途；读／写性质；身份来源与权限；输入类型与前置条件；返回字段及完成证据；幂等与并发；错误分类及恢复；敏感数据；测试样例。字段不适用时解释原因，不为了完整而编造。

## 填好样例：合成商品调价

`apply_price_proposal`只执行已确认的永久售价提案，不生成提案、不处理折扣、不扣款。身份来自会话。调用者需具备该商店价格管理权限；后台检查对象范围。

输入：`proposal_id`、`confirmation_ref`、稳定`request_id`、`expected_version`。提案保存商品ID、原价、新价、币种；确认绑定提案内容与用户。参数不包含任意角色或账户凭据。

成功返回：`status=applied`、`operation_id`、商品新版本与实际价格。重复同一请求返回既有结果。相同请求ID不同载荷拒绝；价格版本改变返回`conflict`。超时后查询`operation_id/request_id`，不能直接重发新ID。

```json
{
  "proposal_id": "demo-p7",
  "confirmation_ref": "demo-confirm-7",
  "request_id": "demo-task-42-price-p7",
  "expected_version": 8
}
```

| 合成测试 | 应观察的结果 |
| --- | --- |
| 100→105，版本8，有效确认 | 目录105、版本9、业务记录关联请求 |
| 同请求重放 | 没有第二次修改，返回同一操作 |
| 原价已变102 | 冲突，不覆盖；重新预览确认 |
| 无管理权限 | 拒绝，目录与业务记录无修改 |
| 写入成功但返回超时 | 核对取得已成功结果，不新建请求 |
| 审计与目录不一致 | 不宣称完成，进入核对与人工恢复 |

试填结果：正常、重放、并发变化、权限和未知结果均能从契约推出处置；外部API是否支持按请求查询仍需接口验证，若不支持，应先补适配日志和对账能力。此为文档试填，尚未调用真实API。

## 商品任务怎样接到本表

参见[CAT-017发现与产物接续](/downloads/examples/product-catalog-workshop/discovery-to-design.md)，用于对应商品保存与后台版本条件。本表原有配送、调价等样例保留为不同条件的对照；不要把它们的字段、动作或数字直接当成CAT-017配置。填写后标明输入依据、产物版本、接收者与尚缺证据。