# 变更日志

只记客户看得见的变化：端点、参数、响应形状、错误码、限流、认证。版本号在每个响应的 `X-API-Version` 头里。

> **兼容承诺** 1.x 内只加不减：不删端点、不改必填、不改现有字段含义。要做这三件事之一就升到 2.0，并且 1.x 再保留 12 个月。

## 1.4.0 · 2026-09-04 — 给 AI 的是业务动作

- **变更** MCP 现在给 AI 的是**业务动作**而不是 43 条端点的镜像：`check_stock`（一次问一批货）、`find_products`、`get_statement`（对账）、`quote_order` / `place_order` / `cancel_order`、`quote_dropship` / `place_dropship` / `release_dropship`。一个动作内部可能连着打好几条端点，返回的是答案（缺什么、多少钱、单号是什么）。端点面一条没少：`list_endpoints` / `call_endpoint` 两个逃生口仍能调到，权限完全一样。

## 1.3.0 · 2026-09-04 — 对账

- **新增** 补上一直缺的对账：`GET /api/v1/balances` 账户余额、`/transactions` 交易流水（每笔带之后的余额）、`/bills` 月度账单、`/refunds` 退款单、`/freight-bills` 运费单。以前这些只能在 OMS 网页上看，月底得人工核。

## 1.2.0 · 2026-09-04 — 下单前先看配货

- **新增** 代发新增「预配 → 提交」两步：`POST /api/v1/dropship-orders/allocation-preview` 逐条告诉你能不能配齐、缺多少、几时到货、要付多少，确认后再 `POST /api/v1/dropship-orders/submit`。⚠️ 预配会占住库存，决定不提交时用 `DELETE /api/v1/dropship-orders/{dropship_order_id}/allocation` 释放。
- **新增** 批发订单同样有配货预览与提交：`POST /api/v1/orders/{order_id}/allocation-preview` 与 `/submit`。付款方式可选 balance / invoice / wechat / alipay，默认按发票付款。
- **新增** 新增作废：`DELETE /api/v1/orders/{order_id}` 与 `DELETE /api/v1/dropship-orders/{dropship_order_id}`，连同占住的配货一起释放（已发货的作废不了）。
- **变更** 用 OMS 账号登录时，建批发单 / 建代发单走 OMS 前台那条链（明细按你的可售目录校验，禁售的 SKU 直接报错），渠道号 + 口令登录的照旧。

## 1.1.0 · 2026-09-04 — 用 OMS 账号登录

- **新增** 换 token 新增 `grant_type=password`：用 OMS 网站的登录账号和密码（`{username, password}`）换 token，权限跟着 OMS 账号走；上游登录态由网关加密代持，不出网关。渠道号 + 口令那条路不变。
- **新增** 新增 `GET /api/v1/me`：这张 token 是谁——账号、渠道、能用的仓、权限、业务开关。

## 1.0.0 · 2026-09-03 — 首个稳定契约（/api/v1）

- **变更** 接口面整体迁到 `/api/v1/*`，27 条端点按一套命名规范重定：路径小写连字符名词复数、从属关系进路径（`/warehouses/{warehouse_code}/stock`）、参数与字段一律 snake_case、同一概念只有一个名字（术语字典）。上一代 `/Api/*` 全部回 410 并在 error.hint 里给新地址。
- **变更** 响应信封改为 `{data, …}` / `{error: {code, message, hint, request_id, doc_url}}`：成功失败只看 HTTP 状态码，没有 `code / result / msg`，没有 "sucesss"。
- **变更** 换 token 改为 `POST /api/v1/auth/token`，渠道号和口令走请求体（`{client_id, client_secret}`），不再出现在 URL 和访问日志里；`?token=` 查询串在 `/api/v1/*` 不再接受，只认 `Authorization: Bearer`。
- **新增** 仓库主数据 `GET /api/v1/warehouses`：仓码用 ERP 真实编码（AUSYD2 / AUSYD1 / CHNZJ1）加两个公司级合计视图（AU / CN）；不再有 AuStock / SydrhStock 这类网关自造的别名。仓白名单对所有带 warehouse_code 的请求生效。
- **变更** 库存字段重命名：`sku` / `product_code` / `quantity_on_hand` / `quantity_available` / `price_wholesale` / `price_retail` / `currency`，每行自带 `warehouse_code`；整仓、按款（`?product_code=`）、按 SKU（`?sku=`）合并为一条 `GET /api/v1/warehouses/{warehouse_code}/stock`。
- **变更** 下单、锁单、购物车统一用 `lines[{sku, quantity}]`（购物车叫 `items`）；代发单一单一个 SKU（`sku` + `quantity`），收件人是一个对象 `recipient{name, phone, address, country_code, state, city, postal_code}`，运输方式 `shipping_method: normal / express`；请求和响应同形。
- **变更** 查询一律 GET：订单 / 代发 / 发货单 / 锁单列表用 `?start_date=&end_date=` 日期区间；分页统一 `page` / `page_size`，响应带 `has_more`；代发「按客户单号 / 按流水号」并入 `GET /api/v1/dropship-orders?client_order_number=` / `?serial_number=`。
- **变更** 状态改为可读枚举（对真实 ERP 数据核对后定）：批发订单 `draft / confirmed / cancelled`，锁单 `reserved / cancelled / confirmed`，发货单 `shipped`，代发 `pending / shipped / intercepted / cancelled`；原值仍在 `status_raw`；代发付款是 `paid` 布尔。查询串的 `status` 也用这些词。
- **新增** 库存增量同步 `GET /api/v1/warehouses/{warehouse_code}/stock/changes`：只返回 since 之后变了的行，响应 `{data, version, since, latest, has_more, needs_full_sync}`，头 `X-Stock-Version` 给游标。
- **新增** Webhook 推送 `stock.changed` / `order.created`：载荷 `{event_id, type, channel_code, occurred_at, data}`，`X-Ever-Signature` 签名；失败按 30 秒→2 分→10 分→1 小时→6 小时重试，6 次进死信。
- **新增** 写接口支持 `Idempotency-Key` 头，重复提交不会重复下单；响应统一带 `X-API-Version` / `X-Request-Id`。
- **新增** 远程 MCP `POST /mcp`、命令行 `ever`（`ever login --sandbox`、`ever stock changes AU --since 0`）、给 AI 读的 `/llms.txt` 与每页 Markdown；工具名 = 资源_动作（stock_list、order_create…），三处一致。
- **变更** 限流按点计：默认 600 点/分；整仓拉取 60 点（分页 5 点），产品列表 30 点，增量同步按实际返回条数计（跟上进度时 1 点），写操作 2 点。
- **弃用** 旧网关签发的 token 兼容至 2026-11-30；之后只认用本站口令换出的 token。

---
Markdown 源: https://connect.everugg.net.au/changelog.md?lang=zh · 网页版: https://connect.everugg.net.au/changelog?lang=zh