# 2.3 新增功能：能力、审批与结果

核对日期：2026-10-23。代码与合成接口测试覆盖实际请求、审批、故障和回读；未在真实店铺执行新增业务写入。账户连接成功不等于拥有所有写权限，最终资格仍由指定区域、profile、品牌、ASIN/SKU 和官方响应决定。

## 六项能力

| 面板操作 | 已实现 | 限制与结果边界 |
|---|---|---|
| `ads.sp.campaign.create` | SP 活动→广告组→广告商品；也可在已有活动/组下补建 | 全部默认暂停；关键词投放另出提案。逐步回执、创建标签、完整分页查重；部分成功不自动续跑 |
| `ads.sp.placement` | 固定、只降低、提高/降低策略与广告位加价 | 不提供 RULE_BASED 规则竞价；未指定广告位和受众/创意加价保留；检查竞价倍数上限 |
| `listing.images` | 主图、附图公开 HTTPS URL；实时商品类型定义、验证预览、PATCH、贡献回读 | 不托管本机图片；贡献接受/回读不等于买家页面换图 |
| `ads.budgetRules` 与 `ads.portfolio` | SP 预算规则创建、编辑、活动关联/解除；投资组合创建、名称/预算编辑、SP 活动归属/移出 | 专用 SP/Portfolios v3 API。支持 DAILY 日期范围，日内时段限定站点；不处理 SB/SD 规则或归属，不归档。关联成功不等于规则已触发 |
| `aplus.content` | 内容创建/编辑、ASIN 集替换、内容和资格校验、提交审核；查询审核/发布记录 | 四步独立精确审批。图片需已有 Uploads 素材 ID；发布记录没有修订版本，不能证明本次内容已展示 |
| `promotions.coupon` | 优惠券/促销准备、格式校验、人工/GPT 浏览器交接；官方查询与回执关联 | 官方 Promotions v2025-12-01 目前仅三个 GET，无创建/修改端点。面板明确标“需网页提交”；本插件不会自动点击或伪造提交 |

详细 API 字段、区域、资格和例子：[广告创建/广告位](ads-create-api.md)、[预算规则/投资组合](ads-budget-api.md)、[图片/A+](content-api.md)。

## 操作顺序

1. `xander_status` 查看店铺与设置；`xander_switches` 查看参数、能力和限制。所有新增开关默认关闭，升级保留现有开关、审批模式、演练模式、配置、钥匙串、档案库和 S3 备份设置。
2. 内容操作可先用 `xander_content_check`：`imageRequirements`、`listAplus`、`validateAplus`、`aplusStatus`。查询不是资格保证；403 表示当前授权或资格未通过。
3. `xander_prepare_change` 生成带精确新旧值、目标和警告的提案；用户核对并批准该份提案，按需在面板自行打开对应开关。AI 没有拨开关工具。
4. `xander_execute_change` 只执行一次。演练只记录 `DRY_RUN`，不发送业务写入。创建或多步骤执行在每步请求前后把状态保存到本机。
5. 用 `xander_verify_change` 只读核验。超时、断网、缺回执、进程中断时不能重发，也不能换提案绕过同目标保护。明确部分失败后，只对未完成部分用已有父对象 ID 另出提案；不要重建已成功对象。

执行时还会重算提案哈希、再读原值，并以店铺执行锁阻止多进程并发写入。面板审批页完整显示各项警告。旧值暂未变化可能只是最终一致性延迟，不能据此认定失败。

## 优惠券/促销交接

`promotions.coupon` 的 `value` 是本地计划格式，不是假造的 Amazon 创建请求。支持 `COUPON`、`BASKET_BUILDING`、`DEAL`、`PRICE_DISCOUNT` 的人工交接；非优惠券还须填写 `conditions` 说明门槛、商品级条件与资格核验事项。

```json
{
  "store": "店铺别名",
  "marketplace": "US",
  "changes": [{
    "op": "promotions.coupon",
    "value": {
      "promotionType": "COUPON",
      "title": "示例优惠券",
      "items": [{"asin": "B000000001", "sku": "EXAMPLE-SKU"}],
      "discount": {"type": "PERCENTAGE_OFF", "value": 10},
      "budget": {"amount": 100, "currency": "USD"},
      "startDate": "2026-11-01T00:00:00-07:00",
      "endDate": "2026-11-07T23:59:59-08:00",
      "audience": "符合后台资格的全部买家",
      "stackingPolicy": "不与其他促销叠加"
    }
  }]
}
```

日期与商品只是合成示例，必须替换成用户批准的实际内容。计划预算是审批时的投入上限，不保证平台自动止损。正式提交前必须在 Seller Central 核验账户/商品资格、参考价、促销费用、优惠叠加和最终字段；出现新费用或值变化须重新审批。

执行结果 `HANDOFF_READY` 仅表示本地交接包已准备，未向平台提交。本插件不会启动浏览器、抢前台或依赖紫鸟。用户可手动操作；只有宿主确实提供电脑操控工具且用户允许前台操作时，GPT 才能依批准内容辅助填写和提交。没有工具时继续走人工交接。

提交后用 `xander_record_promotion_receipt` 传 `proposalId`、`hash`、零起始 `itemIndex` 和平台 `promotionId`。这只记录操作者提供的回执并查询官方状态，不把手工输入当成功证明。`PLATFORM_STATUS_OBSERVED` 表示读到了平台状态，尚未核对整份批准计划。

`xander_promotions` 提供 `search/get/selection`。`search` 返回的 `nextToken` 传入 `query.paginationToken` 继续翻页；空页也可能有下一页。`selection` 必须传详情中的 `selectionId` 和 `query.revisionId`；可用 `includedData:["ISSUES"]`。`PROCESSING` 是处理中，`UPCOMING` 是排期，`RUNNING` 是平台标记正在运行，三者不能混用。

官方来源：[Promotions API 目录与角色](https://developer-docs.amazon/sp-api/docs/promotions-api)、[官方 OpenAPI 模型](https://github.com/amzn/selling-partner-api-models/blob/main/models/promotions-api-model/promotions_2025-12-01.json)。三个操作适用 NA/EU/FE，需 Pricing 或 Product Listing 角色至少其一；没有公开创建/修改端点。

## 关键状态

| 状态 | 含义 |
|---|---|
| `DRY_RUN` | 演练，没有业务提交 |
| `OUTCOME_UNKNOWN` | 请求结果未知，保留已知 ID，只核验不重发 |
| `PARTIALLY_SUCCEEDED` | 部分步骤完成，检查逐步回执和未完成部分 |
| `API_STATE_VERIFIED` | 批准的 API 字段回读一致，不保证买家页面或广告实际投放 |
| `IMAGE_CONTRIBUTION_VERIFIED` | 图片贡献回读一致，零售页面待核验 |
| `DRAFT_CREATED` / `CONTENT_UPDATED` / `ASINS_ASSOCIATED` | A+ 对应单步已核验，不表示已提交审核 |
| `SUBMITTED_FOR_REVIEW` | 已提交审核，不表示审核通过 |
| `APPROVED` | 审核通过，不证明当前修订在买家页面发布 |
| `HANDOFF_READY` | 资料已准备，需要网页操作；未提交 |
| `PLATFORM_STATUS_OBSERVED` | 已查询回执对应的平台状态；完整批准计划仍待核验 |

## 更新与回退

沿用仓库 `main` 的版本化插件发布方式；不把本机安装缓存当作源代码。Codex 用户可运行：

```sh
codex plugin marketplace upgrade xander-zaozao
codex plugin add xander-zaozao-xiaban@xander-zaozao
```

查看 `codex plugin list --marketplace xander-zaozao --json` 确认版本、安装和启用状态。已有进程可能继续运行旧代码，需要在当前任务结束后重新加载插件/面板；不必重新接入店铺。回退只能替换插件代码，不能删除 `~/.xander-zaozao` 或清除钥匙串。升级后的未决创建记录必须保留，避免回退后重复提交。

从 2.3.7 启动的面板会保留同版本页面快照，运行期间清理安装目录不会再让页面请求导致进程退出。启动时缺少页面会显示 503 提示，资源恢复后刷新可重试。正在审批或核验时仍应先完成当前操作，再升级和重新打开面板；该修复不能自动改变已经运行的旧版进程。