变更日志

兼容承诺

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

• 变更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 两个逃生口仍能调到，权限完全一样。

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

• 新增代发新增「预配 → 提交」两步：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 直接报错），渠道号 + 口令登录的照旧。

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

• 变更接口面整体迁到 /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。