中央供货 API 接入文档

协议选择

旧站使用第一种协议。原生接口的 nodeId、幂等请求头和节点内部凭据不能混入 GAMEBEAST 请求。三种凭据不通用。

公网连接与备案后迁移

自 2026-09-17 起已核验公网 HTTPS 可达。旧站货源、工作台和第三方接口统一填写 https://jllyx.cn，直接通过公网连接，不需要 SSH 通道、服务器登录密码或本机域名映射。

HTTP 和 www 入口只用于浏览器访问时转到主地址。API 客户端必须直接请求上述 HTTPS 主地址，不依赖跳转，不使用服务器 IP、localhost、19443 端口或 /healthz 作为接口根地址。工作台会拒绝接口重定向。

协议是否变化

接口仍为 v1：五个 GAMEBEAST 路径、签名及结果协议不变。0.3.13 修正目录数量表达与受理前执行条件检查，详见商品与数量章节。已有节点身份和接入密钥可继续使用。回调仍发往旧站 https://www.jllyx.com/api/supply/v1/callbacks/gamebeast/{vendorId}，不改为新站域名。

既有工作台迁移

1. 暂停接新单并确认空闲，备份原加密连接配置。
2. 本机原 SSH 模式仅将 transport 改为 direct，保留身份与账本；正常重启工作台，验证新心跳。
3. 关闭专用 SSH 通道后再次确认持续在线，再清理旧通道自启动。新安装首次绑定默认使用公网直连。
4. 办公室旧 hosts 转发方案在原解压目录运行 STOP.cmd，撤销专用映射后验证公网访问。不要重新绑定或重跑历史待核实订单。

联调验收顺序

先从旧站实际生产服务器访问 GET /healthz，再按本章签名规则读取 customer、list、product；有原订单时使用原编号 get。核对货源账号、额度、价格、节点状态及回调配置后再安排受控真实单。健康检查正常不代表已完成充值、回调和结算验收；备案通过不会自动启用接入账号。

接入现有聚琳琅供应平台（GAMEBEAST兼容协议）

店铺／下游 → www.jllyx.com 接单 → jllyx.cn 中央订单及节点执行 → 新站确认结果并回调旧站 → 旧站通知下游。只新增新站兼容层；旧站不改代码、数据库或协议，通过已有管理界面配置货源。GAMEBEAST 是协议名称，实际服务及充值由本系统提供。

本章与下方原生 API 独立。协议根地址 https://jllyx.cn，不要添加 /api/supply/v1。五个接口均为 POST application/json，UTF-8，无跳转登录页。兼容接口使用 JSON 内的 dealer_no、timestamp、sign；无需附加签名请求头、nonce 或 nodeId。

旧站现有管理界面配置

结算与供货条件

上游余额来自新站接入账户的内部结算账本，不是支付宝余额。初建接入账号为暂停、结算待确认、资金 0；供货价在共用商品目录管理，自动同步的新商品默认使用采购价，不再按接入账号配置。结算待配置时 customer 返回 code=999，目录中已定价且能力验证通过的商品显示 status=0，buy 不受理。未定价、尚无执行能力、参数无法由旧站表达或数量无法准确表示的商品不进入 GAMEBEAST 供货目录。结算模式、额度及供货价由管理员按实际约定确认。新站不会因代码升级自动增加生产额度、启用账号或更换密钥。

• 内部授信：可用额 = 授信上限 + 已登记结算 − 成功订单应收 − 在途占用。登记结算不得超过已成功且尚未结算的应收。
• 预存款：可用额 = 已核实到账 − 成功订单扣费 − 在途占用；不允许虚增授信。实际资金移动由管理员在外部完成，页面仅登记凭据。
• 下单事务占用金额，成功转记账，明确失败释放。UNKNOWN 保留占用；查询及回调失败不改账、不重新充值。凭据号重复提交幂等，所有配置和资金登记留审计及流水。
• 商品是否可供货以目录模式或明确配置的手工模式以及管理端执行条件为准，不固定于某个编号、品类或面额。供货价、充值面额及采购成本分别保存；修改供货价不改历史订单。

商品与数量：目录必须能真实执行

旧站只读取 buy_min_num 和 buy_max_num，把它们作为连续整数范围；不解析商品名中的金额清单，也不读取新加的 quantitySet、supportedAmounts 或参数模板。因此，新站目录只发布能够用原协议准确表达的范围。

price 是供货单价（元，四位小数）；payment_amount = price × quantity，也保留四位小数。价格不是账号余额、淘宝付款额或充值面额。商品数量不能直接当采购金额使用。

不连续面额的推荐目录（全部为虚构示例）

{"code":0,"msg":"ok","data":[
  {"id":61001,"name":"示例甲 · 六元规格","price":"5.8123","status":1,"supply":{"status":1},"type":1,"buy_min_num":1,"buy_max_num":1},
  {"id":61002,"name":"示例甲 · 十元规格","price":"9.7500","status":1,"supply":{"status":1},"type":1,"buy_min_num":1,"buy_max_num":1},
  {"id":62001,"name":"示例乙 · 十五元规格","price":"14.1234","status":1,"supply":{"status":1},"type":1,"buy_min_num":1,"buy_max_num":1}
]}

六元规格请求 product_id=61001, quantity=1, payment_amount="5.8123"；十元规格使用 61002 和 9.7500。没有五元规格时，目录不创建五元商品，也不把这两个规格表示成连续 1～10000。各编号保持各自商品、价格、参数和节点映射。

既有按元入口与迁移

既有按元编号保留原身份和 quantity=整数元面额 含义，不改造成固定面额编号。迁移可选择直接使用已关联固定规格（quantity 通常为 1），或按下方单编号手工绑定步骤启用统一入口（quantity 为元数）；独立单面额分组仍可继续使用。统一入口复用原固定执行商品，不复制采购规格、不改变旧编号的元数语义。历史订单查单、幂等重放和回调继续使用原编号与受理快照。

若有效主用规格恰为 6、7 元，则按元入口公布 buy_min_num=6, buy_max_num=7；每个数都必须存在合法规格。入口每元供货价 1.0050 时，quantity=6 的结算总价为 6.0300，真实六元规格只采购一份，采购成本取该规格快照。

未配置单编号手工模式时，若只有 6、10 元等不连续面额，该按元入口不进入 GAMEBEAST list，product 返回 104，新 buy 在确认未受理后持久化明确拒绝。后台显示“需迁移”及对应固定规格编号；数据库中的原入口身份、原生接口路由和历史记录保留，不把目录遗漏当作删除历史订单。旧拒单编号补上规格后也不会重新执行。

发布代码与开放供货分别验收。对正在使用的不连续按元入口，应先核查在途订单、旧站映射与管理员迁移计划，不能无评估直接撤下。若已核实全部 GAMEBEAST 接入账号暂停、没有既有兼容订单、执行中或待核验任务，可保持暂停发布本版；无法读取旧站映射时，应明确列为启用前待核验项，不能据零订单推断没有映射。旧站目录同步不会替管理员把旧 SKU 转为新规格，已核对旧站一键同步上架和自动调价的目录消失检查会停用相关绑定；迁移前须处理同步策略。

1. 在新站商品管理查看按元入口的主用固定规格编号，核对面额、价格及参数；记录旧编号与替代编号对照。
2. 管理员在旧站已有商品中心建立或同步独立规格 SKU，固定规格通常设置购买数量 1～1，绑定对应新站固定编号和供货单价。不能只改旧 SKU 的编号而沿用“数量=元”规则。
3. 只把新业务切到独立规格 SKU；原订单继续按原外部编号查询、等待回调。核实后通过旧站已有界面停用旧映射，保留历史关联。
4. 完成参数模板核对后才开放新业务；旧站、新站的暂停开关和额度均由管理员分别确认。

单编号按元充值：旧站只绑定一个上游编号

中央 0.3.18 新增单编号手工绑定模式。同一业务使用一个稳定上游编号，quantity=充值元数：传 6 精确选择六元规格，传 10 选择十元规格，实际均采购一份。缺少面额时明确拒单，不四舍五入、不拆单、不跨业务找商品。客户端无需改回分组。0.2.27 将分组工具收进“高级供货设置”；自动分组原设置保留。中控默认收起已配置统一业务下的兼容面额入口，勾选“显示兼容面额入口”可查看；只影响管理页显示，目录、接口、映射和历史订单不变。

手工入口不出现在 GAMEBEAST list，product 返回 104；这是目录排除，不表示已配置的手工入口不能 buy。旧站原始适配器可直接按手工绑定编号发 buy，不依赖 product 预查。此例外只对管理员明确设置为手工绑定的入口生效；未配置入口仍按原规则拒绝。不得把隐藏入口描述成支持连续 1～10000。

一、新站配置一次

1. 客户端确认商品已验证、启用并参与按元供货，同一业务的真实“充值类型”相同。现有按面额分组可保持；不同业务必须使用不同充值类型，不按商品名称或编号猜测。
2. 中控“商品管理 → 单编号按元绑定”选择该业务，核对预览编号、每元价格、面额和旧站维护要求后确认。已有业务总入口复用原编号及元数语义；没有总入口时分配新编号，默认暂停供货。不会修改既有供货价、接入账号、节点状态或额度。
3. 中控按真实业务类型汇集现有分组的固定执行映射。同一面额首次存在多个候选时，在“按元供货规格”指定主用；旧主用保留，失效时阻止新单，不擅自切换。固定规格商品仍可单独按 quantity=1 购买。
4. 入口“详情”查看真实面额、采购成本及硬性额度条件；编辑每元供货价和供货开关。每个面额使用同一每元单价，总价=单价×quantity。若各面额需要不同折扣，请继续使用独立规格/面额编号，不能在同一编号内悄悄换结算公式。

二、管理员在旧站已有界面配置

1. 该 GAMEBEAST 货源使用 https://jllyx.cn 及已有凭据。关闭该货源的自动调价策略，不运行手动调价同步，不执行“一键同步上架”。手工入口不进入目录；旧站同步发现目录商品消失会停用绑定。仅暂停单条映射的调价不能阻止“目录消失”保护。若其他商品必须自动同步，可通过已有界面另建专门手工维护的货源记录，管理员核对凭据和回调配置。
2. 旧站“商品中心 → 编辑商品 → 购买数量规则”选“固定数量档位”，填写新站已具备执行条件的元数，如 6,10,20。账号参数沿用 account，按真实格式填写模板。面额清单不会自动同步；新增或停供规格后须维护。
3. “货源绑定”只添加一条映射：上游商品编号填新站统一入口编号，上游成本填新站每元供货单价；购买数量约束允许所选档位通过，“固定数量（选填）”留空。核对其他启用路由，避免同一数量仍命中过去的逐面额绑定。只由管理员在旧站界面调整，不直接修改数据库。
4. 新站、旧站账号启用和额度独立核对。改价时同步手工修改旧站每元成本；价格不匹配会拒单，不能靠重复发旧订单号重试。没有对应规格的请求在确认未受理后持久化拒绝，原编号以后补规格也不复活。

三、日后新增商品和面额

新业务配置一次自己的统一入口；既有业务新增面额只需客户端完成真实规格、参与供货、验证及启用，等中控自动同步。符合该业务的新增面额自动加入统一入口，不新增旧站绑定；管理员仍须更新旧站固定数量档位。重复面额存在多个候选需选择主用，额度不足需管理员另行评估，系统不自动增额。

{"product_id":"71000","quantity":6,"payment_amount":"5.8800",
"outer_order_id":"DEMO-MANUAL-006-R1","account":"DemoAccount06",
"notify_url":"https://www.jllyx.com/api/supply/v1/callbacks/gamebeast/DEMO_VENDOR"}

示例编号和账号均虚构；发送时由旧站原适配器添加 dealer_no、timestamp 和 MD5 sign。无需 nodeId、金额分组或新增必填字段。供货总价四位小数；执行份数与采购金额取真实规格。参数按命中规格校验，缺失或非法参数不猜默认值。需要旧站无法表达的字段时仍不能供货。

迁移只影响以后新请求的路由，不改变历史受理快照、原外部订单号、价格、数量和采购映射；UNKNOWN 或可能已经发生交易只核验原单。晚到终态仍使用持久化回调，回调失败不再充值。本模式的模拟测试不代表真实充值联调完成。

数量、采购金额与额度

GAMEBEAST 新单受理前必须至少存在一个已批准、未撤销、已关联且执行指纹／配置版本／能力匹配的合法节点，其单笔额度能够覆盖真实采购成本。没有规格、没有合法映射或所有单笔上限均不足时，不创建任务、不占款，保存可查询的拒单记录。增加面额需要更高额度时，应先由管理员评估并配置；系统不自动提高生产额度。

节点暂离线、暂停、忙碌、冷却或当日剩余额度不足，不等于永久缺少规格；具有合法能力及单笔额度的请求可按原队列等待。采购时限、许可、防重、原单核验和 UNKNOWN 保持不变。已受理订单沿用冻结映射与金额，新限制不会改写其快照、将可能已发生交易的原单判失败或重新充值。

额度边界示例

虚构固定规格面额 1200 元、供货价 1188.5000 元、采购成本 999.99 元，quantity=1：采购单笔额度至少 999.99 元且账号可用额至少 1188.5000 元才满足相应条件。采购成本若为 1000.01 元，而节点实际单笔额度仍为 1000 元，应拒绝新单；管理员可在暂停、空闲时将单笔额度提高到不超过 10000 元。可配置上限不等于当前生效额度，本机额度仍独立检查；不能把 quantity=1 当作采购 1 元。

充值参数与旧站模板

参数规则支持 identifier（字母、数字、下划线、点、连字符）、digits（纯数字）、text（符合长度及安全字符要求的文字），并可约束合法选项。以商品详情中保存的必填性、最大长度和枚举为准。当前生产通用执行器只处理一个 account；区服等多参数商品只有新增执行能力已实现并验证、且必需参数完全可由上述旧站字段表达时才可供货。仅在页面添加字段不会获得执行能力。

新站不会静默填入账号、区服或参数默认值；缺失或非法参数在未受理时明确拒绝。必需参数若为 role_id、token 等旧站不转发字段，该商品保持不可供货并显示具体字段原因。不得把新目录中的扩展字段当作旧站已经自动读取的参数模板。

未来多参数商品示例（仅隔离测试，非现有生产能力）

{"product_id":"62001","quantity":1,"payment_amount":"14.1234",
 "outer_order_id":"EXAMPLE-REGION-R1","account":"DemoAccount01",
 "area_name":"示例一区","server_name":"示例服","game_id":"DEMO_GAME",
 "notify_url":"https://www.jllyx.com/api/supply/v1/callbacks/gamebeast/EXAMPLE"}

该示例要求 account 为 identifier，最长 64；area_name 只允许“示例一区”，server_name 只允许“示例服”，game_id 只允许“DEMO_GAME”，四项均必填。缺少 area_name 或传入其他区服应拒单。这里只演示旧协议能表达的边界，不声明真实节点已支持该商品。

管理员通过旧站已有界面配置

以下自动目录配置仅适用于固定规格或连续目录入口；单编号手工入口请使用上方专用步骤，不运行目录同步。

1. “货源管理”选择 GAMEBEAST／游戏兽，填写接口根地址 https://jllyx.cn、对应 dealer_no 和 SecretKey。保存并测试连接；测试连接不等于充值验收。
2. “同步／映射”拉取目录；核对新站编号、名称、四位供货价及数量范围，再使用“一键同步上架”或已有商品的“货源绑定”。既有货源映射的切换由管理员明确执行，代码更新不修改旧站配置。
3. 固定规格 SKU 设置购买数量 1～1，货源绑定填写对应稳定 product_id 和成本单价。旧站会用货源成本单价 × 数量生成四位 payment_amount；不能填写充值面额代替供货价。
4. 单账号商品在“商品中心 → 编辑商品 → 充值信息类型”选实际账号类型并核对 account；需要多参数时选“自定义”，进入“高级字段设置”。逐项填写 API 字段名、显示名称、TEXT／NUMBER／SELECT、必填、格式校验、合法选项和敏感标记。字段名仅用 account、area_name、server_name、game_id；账号保留字符串，避免前导零丢失。
5. 下游提交旧站的 parameters，旧站把这些指定字段转到 GAMEBEAST 顶层。下游不能直接提交节点参数绕过旧站商品规则。
6. 每次再次“一键同步上架”后重新核对。已核实的旧站导入会覆盖商品数量规则，并把 GAMEBEAST 自定义参数模板重置为空；不会自动生成区服模板。多参数商品应在暂停对外供应的窗口同步，复核／恢复模板后再开放，不能将这一步当作永久自动同步。
7. 核对节点审批与限额、商品开放、接入账号额度及回调地址，按独立批准的测试计划完成真实闭环后才投入供货。

商品扩展与执行能力

list、product、buy 使用同一 products 配置：稳定编号、名称、充值类型、规格、面额、供货单价、上架开关、供货开关、允许数量、参数规则和执行能力。节点映射复用现有 mappings。供货单价与面额、采购成本分开；payment_amount 始终是供货单价 × quantity，不能当充值面额。

原 1 元抖币能力继续保留；工作台 0.2.3 新增 taobao-recharge-v1 标准单账号充值方案，支持按商品配置并验证。每种规格数量固定 1，不拆成多次充值。当前开放范围以实际目录为准，模拟商品未发布。

自助新增商品／规格

1. 暂停目标节点，等原单结束；保持工作台在线、淘宝登录。
2. 工作台“商品管理 → 新增商品”，选“淘宝接口 · 通用单账号直充（可配置）”。粘贴详情链接，读取商品信息并选择 SKU，核对标题、店铺和采购价。
3. 填写充值类型、规格、面额、账号字段标识（常见 cdvAccount）、账号字符规则和订单账号标签（常见“充值号码”）。保存为停用草稿。
4. 点“验证接口配置”，输入该规格已有淘宝订单的充值账号和订单号。执行试算/账号回读与原单查询，不下单、不付款。没有历史订单时，先由管理员完成一笔受控人工测试。验证结构通过不等于软件已完成新商品真实充值验收。
5. 确认商品可开放后编辑启用，等待节点上报。在中控“商品映射 → 商品自动同步”开启持续同步；已验证并启用的新商品会自动分配中央编号、建立映射，按采购价上架供货。也可点“立即同步全部新商品”只执行一次；不必逐个选择。
6. 开启自动同步前应完成逐商品验收并核对节点额度；节点接单开关不会被同步改变。旧站仍在已有界面同步并映射中央商品编号，无需增加请求字段。若需先人工定价，可关闭自动同步，使用“手动导入单个商品”（默认下架、停供）。

本机独立接口使用工作台对接编号；GAMEBEAST 和原生中央接口使用中央编号，不能混用。修改接口身份、价格、规格、账号规则会要求重新验证；历史订单仍使用原快照。

中央 0.3.8：自动导入并上架

持续同步开关保存在中央数据库，重启后保留。开启时立即扫描，后续随节点心跳处理；商品必须已验证、已启用并被在线节点上报。自检失败、原单执行中或更新未结束时等待，恢复后再同步。未上报的草稿不会发布；新增记录不能替代执行能力验证。

按执行配置完整指纹去重：相同规格跨节点关联已有商品；新规格自动分配未用过的递增中央编号。已有商品的价格、下架、停供及手动解除映射不会被覆盖。同一本地商品编号的规格、采购价或账号规则变化时提示人工核对，不静默改旧商品。多个相同中央规格无法确定归属时跳过并说明原因。关闭同步不删除已有商品，也不停止原单核验。

同步窗口逐项展示中央编号及导入、已存在、跳过或等待原因。新商品供货单价默认等于采购价，之后可单独修改；充值面额仍独立保存。已受理订单沿用原商品和映射快照。管理接口 GET /api/admin/catalog/sync 查看状态；POST 同路径传 {"enabled":true/false} 修改开关，传 {} 执行一次全量同步；均须管理员登录，修改须 CSRF 校验。旧站协议不变。

已验证方案与自动匹配（工作台 0.2.3）

商品编辑窗口增加“复用接口方案”下拉列表。内置标准采集和必填账号输入两种结构；完整验证成功后，账号字段、输入结构、字符规则和查询标签会保存到本机账本，升级不会覆盖。方案只保存结构规则，不保存测试充值账号、历史单号、Cookie 或支付密码。重复方案按配置指纹去重。

验证窗口默认勾选“自动识别并匹配接口方案”。程序从当前商品的唯一账号字段读取实际标识和采集/必填属性，执行一次账号回读，再从已有原单识别账号标签，核对双账号、商品、规格、金额、店铺及标题。全部通过才原子替换当前商品配置、登记验证并保存方案。更换结构后商品保持停用，需核对后启用。

自动匹配不改变商品或金额来迎合返回值，不扩大账号字符规则，不循环尝试未知参数。多个输入框、未知结构、额外必填参数、价格/账号/SKU 不符、登录/验证码或超时都会停止；失败不保存猜测方案。下拉复用方案也必须重新验证当前商品。实际采购使用已保存的方案，不在已下单或付款后试错。

支持边界与故障处理

标准单账号方案要求唯一可见的 orderLineCusExtInputItem / orderLineExt，支持配置 collectorKey；原单须有 skuText 和 logisticsAddress 两处一致账号。独立 SKU 须返回对应编号，额外必填参数、复合提交或不同结果结构会明确停止。仅增加他趣、YY 等名称不能证明已适配；相同接口结构可按配置验证，不同能力仍需开发。充值终态使用平台明确状态，不把普通交易成功当作充值成功。

失败时核对界面显示的字段/标签、SKU、金额和账号，保持停用。已发起交易后的 UNKNOWN 继续核验原单，不能因改商品或恢复服务重充。暂不使用的商品可下架、暂停供货或删除节点映射，保留账本。原 1 元批量压测入口本次未扩展。两种新测试商品仅在隔离测试数据中运行，没有真实充值。

受理事务保存商品定义、修订号、规格、单价、数量、执行参数及映射快照。改价、下架、修改映射不会改原单。映射删改后，原单只会使用受理时相同且当前仍有效的映射；不会自动使用新加入的映射。如没有原映射可用，尚无执行许可的订单等待到采购期限后安全失败。已有交易可能则保留 UNKNOWN。已被订单引用的编号不能改成另一种类型／规格，不能删除后回收复用。

公共请求字段及签名

排除 sign、cards 及 undefined、null、空字符串；保留 0 和 false。字段名按 JavaScript 默认 UTF-16 字符串顺序排序，普通值 String(value)，数组／对象 JSON.stringify(value)。拼成 key=value，以 & 连接；前后各加 SecretKey，对完整文本 toLowerCase()，再 UTF-8 MD5 小写输出。签名前不改变金额字符串、字段类型和对象键序；签名的小写计算不改变实际充值账号。

下载可直接运行的离线示例：Node.js 示例；Python 示例＋Python 签名实现（两份 Python 文件放同一目录）。示例只打印签名，不联网、不下单。

node gamebeast-example.mjs
python gamebeast-example.py

虚构 SecretKey 均为 FakeSecret#A
向量 1：{"dealer_no":"DEMO001","timestamp":1800000000,"pageNum":1,"pageSize":100}
预期：603aa9d9dda5f5d23d9ae213c93b71e1
向量 2：{"z":0,"a":false,"empty":"","nil":null,"account":"CaseSensitive","payment_amount":"1.0000","cards":["ignored"],"sign":"ignored"}
预期：77e02fc60121e360316f4839928b2050

这些固定时间戳只用于签名向量，联网请求须使用当前时间。相同业务重试更新 timestamp 和 sign，保留原 outer_order_id。

1. 经销商及余额

POST /open/dealer/v1/customer，只需要公共字段。

{"code":0,"msg":"ok","data":{"dealer_no":"DEMO001","name":"示例接入账号",
 "supply_list":[{"supply_id":1,"supply_name":"聚琳琅充值中心","balance":"0.0000"}]}}

balance 为元字符串，来自真实账本可用额。此处 0.0000 仅表示零资金示例；生产不预填测试资金。旧站将 supply_list.balance 求和显示为上游余额；当前核对的旧站代码未发现用 GAMEBEAST 余额直接拦截路由，新站仍实施实际额度校验。暂停接入后原单查询及回调继续可用。

2. 分页商品目录

POST /open/dealer/v1/list

{"code":0,"msg":"ok","data":[{"id":10001,"name":"抖币 · 1 元（10 钻石）",
 "price":"1.1600","status":1,"supply":{"status":1,"supply_id":1,"supply_name":"聚琳琅充值中心"},
 "type":1,"buy_min_num":1,"buy_max_num":1}]}

1.1600 是格式示例，不是已批准的生产售价。data 直接为数组；按稳定商品编号分页，超出末页返回 []。未定价商品不曝光，已暂停／下架商品 status 和 supply.status 为 0。type=1 是直充，不提供卡密商品。供货状态表示配置已开放，不保证此刻有空闲节点；节点可用性由中央调度判断。

3. 商品详情

POST /open/dealer/v1/product，额外必填 product_id（string 或 integer，例如 "10001"）。data 为上面单个商品对象。商品不存在或未定价 code=104。本接口已实现；旧站已核实的自动同步流程调用 list，并未确认旧站会调用 product。

4. 受理充值订单

POST /open/dealer/v1/buy

业务字段示例（加公共字段及按整份正文计算的 sign 后发送）：
{"product_id":"10001","quantity":1,"payment_amount":"1.1600","outer_order_id":"S202609140001-R1",
 "account":"CaseSensitiveAccount","notify_url":"https://www.jllyx.com/api/supply/v1/callbacks/gamebeast/123"}

受理响应：
{"code":0,"msg":"ok","data":{"dealer_no":"DEMO001","supply_id":1,"order_id":"AAA0000001",
 "outer_order_id":"S202609140001-R1","status":100,"status_info":"处理中","type":1,"cards":[]}}

code=0 表示接口返回正常，不代表充值成功。订单、幂等映射和额度占用在同一事务持久化；订单表就是现有调度器的可靠队列。HTTP 不等待真实充值，正常受理目标小于 2 秒；争用时尽早 code=999，让旧站保留原单核验。

5. 查询及丢失响应恢复

POST /open/dealer/v1/get，额外字段 outer_order_id（string）和 order_id（string），至少提供一个；两个均有时须属于同一订单。data 与 buy 相同，status 和 status_info 反映最新确认状态。严格限定 dealer_no 范围；查询不创建订单。

{"outer_order_id":"S202609140001-R1"}
或 {"order_id":"AAA0000001"}
或 {"outer_order_id":"S202609140001-R1","order_id":"AAA0000001"}
以上均需补全公共鉴权字段。

下单超时／响应丢失 → 使用原 outer_order_id 查询 → 取得同一中央 order_id → 继续查结果。不换编号重发，不凭“查不到”重新充值。UNIQUE(dealer_no, outer_order_id) 防并发重复；账号、商品、数量、供货金额或回调地址变更会返回 code=999，保留原记录。幂等指纹排除 timestamp、sign 和不影响执行的 client_ip；商品编号的整数／等价数字字符串及等额金额表示规范化后比较。已受理订单的合法重试不受暂停、价格更新影响。明确拒单会保存拒单记录，后续改参数也不能重新启用这个编号。

三类订单的最终处理

A．已受理：返回原中央 order_id（例如 AAA0000001）和原样 outer_order_id，状态为 PROCESSING / UNKNOWN / SUCCESS / FAILED。即使接口响应丢失、下架、暂停、改价，合法原请求重试仍返回原单。只查询原交易，不重建任务；有下单／付款许可或外部订单号时，不能通过“确认未受理”结束。

B．已保存明确拒单：初次 buy 可以返回 102、103 或 104。即使此响应丢失，get 仅用 outer_order_id 即可取得稳定拒绝结果：

{"code":0,"msg":"ok","data":{
 "dealer_no":"DEMO001","supply_id":1,"order_id":"RJ0123456789ABCDEF01234567",
 "outer_order_id":"S202609140001-R1","status":300,
 "status_info":"供货总价不匹配，请重新同步商品。","type":1,"cards":[]}}

RJ 加 24 位十六进制字符是持久化拒单查询编号，不是充值任务号；重启、恢复服务及改价后保持不变。拒单不创建中央充值任务、不占用资金。同一 dealer_no＋outer_order_id 永久不再受理，重发 buy 返回原拒绝；get 返回 code=0、status=300。新订单业务必须使用合法的新外部编号，不能拿改编号作为 UNKNOWN 的重充手段。

C．完全查不到：返回 {"code":999,"msg":"暂未找到唯一原单，已登记可关联的待核验记录，请在中控核查。","data":null}。不伪造中央订单号或 FAILED。合法鉴权且带 outer_order_id 的未找到查询、账号／中央暂停请求会持久登记“旧站接入 → 待核验”。鉴权失败、解析失败或数据库无法取得锁时，可能未能登记；修复后由管理员使用“核验外部订单”按接入账号和原始外部编号查询／登记。只有 order_id 且无法查到时，没有足够外部编号建立禁受理记录，须补取旧站原 outer_order_id。

旧站自动查单最多 8 次后转人工，新站不依赖无限轮询。已受理订单继续核验；晚于第 8 次才确认的终态仍生成持久回调，发送至原 notify_url，直到取得 ok。待回调数、最后错误和手动补报入口在“回调记录”。原交易一直不明确时保持 UNKNOWN 和资金占用，人工查原交易；不能定时批量改成失败。

“核验未受理并结束”只作用于待核验记录：在与 buy／执行许可共用的 SQLite BEGIN IMMEDIATE 写事务内，检查本渠道原单、兼容映射和幂等记录均不存在，随后写永久拒单记录。先受理则人工结束拒绝；先结束则延迟 buy 永久拒绝，因此不会出现已判未受理后又执行。同编号没有中央订单就没有合法执行许可；出现底层孤立受理或其他交易线索时拒绝结束，保持人工核验。已受理且从未获得下单许可的原单，可使用“统一订单”的安全取消；已有外部交易可能的原单须保留核验。新版任务只有完成下文原单取消与安全确认后，才可结束本次尝试或继续改派。

人工确认未受理的记录如果已有合法 notify_url 和 product_id，会回调 status=300；只凭查单登记而缺少回调目标时，不猜测地址，需要旧站已有人工查单入口再次 get 取得最终拒绝。

旧站 EXAMPLE-OUTER-001 → 中央 AAA0000042（始终同一个中央订单）
尝试 1 / 节点 A：付款前异常 → 取消并核验未付款关闭 → 本次尝试已安全取消
尝试 2 / 节点 B：执行成功 → 接口核验成功 → 中央 SUCCESS → 回调 status=200
中间尝试不产生失败回调；若最终所有尝试安全结束仍未成功，才回调 status=300。

节点重新连接与故障提示

节点卡片新增“重新连接”。中控开启最长 20 秒的检查，等待节点自动重连后发来的新认证心跳；已有的旧心跳不作为成功依据。弹窗分别显示中控是否响应、心跳时间、连接结果及桌面、淘宝接口、密码、执行器、暂停状态等真实上报原因。失败后可再次尝试。检查不解除暂停、不改订单、不重试付款。

节点每 5 秒自动尝试公网连接。历史 SSH 配置须按上方迁移步骤切换，网页刷新不会自动修改客户端连接方式。机器关闭、工作台退出或网络完全断开时，中控无法远程启动程序；20 秒后会明确提示未收到新心跳，并给出节点电脑上的排查步骤，不伪装恢复成功。

暂停与恢复

999 请求的恢复路径：先修复鉴权、时间或服务状态 → 以原编号 get／中控“核验外部订单”核查 → 查到原单则只跟踪原单；查到拒单则结束；仍未找到且要终止，则使用具备互斥保护的人工未受理确认。不要仅凭 999 换编号或其他渠道重充。

状态及错误语义

不会以 HTTP 429 表示临时限流；5xx 与 code=999 均要求原单核验。网络超时、付款已发出、节点离线、服务重启、订单未知、回调异常均不能证明失败。兼容层共用现有原单核验及人工处理；已停止的未知订单保留人工查询入口，不自动恢复付款。

结果回调与补发

每笔兼容订单只使用它自己的 notify_url 与对应 SecretKey，发送一次类型的兼容报文。已受理订单只对最终 SUCCESS / FAILED 生成事务 outbox；明确拒单也在有合法回调目标和商品编号时生成同格式失败事件。UNKNOWN 不发送失败回调。

{"dealer_no":"DEMO001","order_id":"AAA0000001","outer_order_id":"S202609140001-R1",
 "product_id":10001,"status":200,"type":1,"cards":"","msg":"充值成功",
 "timestamp":1800000000,"sign":"按本文算法计算的32位MD5"}

status 成功 200、明确失败 300；msg 保存真实结果原因。回调 timestamp 为发送时 Unix 秒，每次重试重新计算 timestamp / sign。旧站允许 ±600 秒，按同一算法验签（排除 sign 和 cards），沿用既有订单号＋状态去重。确认响应为 HTTP 2xx 且正文 trim() 后精确为 ok；旧站当前返回 200 text/plain ok。

5 秒起指数退避，最多间隔 1 小时，失败重试记录、最后错误、下次时间均持久化；404、非 ok、网络错误也重试，重启继续。中控“回调记录”显示协议、接入账号、待送达数量及错误，支持“立即重试”安排原事件，不重新充值。回调失败不会更改充值终态。当前提供页面告警／待送达计数，没有新增短信告警。

回调地址固定允许 www.jllyx.com 及指定路径范围；投递前检查全部 DNS 结果均为公网地址，用所解析地址固定连接并按原主机验证 TLS，不跟随重定向，不请求内网。

旧站停止第 8 次自动查询后，回调入口仍可接收终态。若管理员已经在旧站切换渠道或将订单终止，旧站现有逻辑可能仅记录迟到成功并产生风险告警，不会自动覆盖终态；需在旧站已有人工处理界面核对。新站收到 ok 表示旧站确认接收，不保证旧站人工改过的订单会自动改写。本次不改变旧站的这些处理规则。

更换 SecretKey 与历史回调

1. 中控“旧站接入 → 更换密钥”。新站原子暂停此账号接新单及回调，生成并加密保存待生效密钥。若该账号有正在发送的回调，暂不进入更换，提示稍后操作；此步不会创建充值。
2. 管理员在旧站已有货源管理配置中，将当前 SecretKey 保存为这份待生效密钥。只改配置，不改旧站代码、字段或验签算法。切换窗口内新旧密钥不一致时查单可能返回 999，保留原编号。
3. 回到新站点“继续更换密钥”，确认旧站已保存后激活。新站将新密钥设为当前密钥，并安排所有历史未送达事件立即重试。接单保持暂停；确认签名和查询通信正常后，再在现有配置启用。
4. 每次回调重试读取账号当前生效密钥，生成当次 timestamp 和 sign；原订单号、product_id、业务内容与终态保持不变。旧站以它当前 SecretKey 验证，不需要 keyVersion。补回调不会再生成充值或重新占用资金。

关闭页面或服务重启后可继续同一份待生效密钥，不会自动生成另一份。密钥以服务器加密配置保护的主密钥加密保存，管理展示有鉴权、CSRF 和 60 秒清理；列表、操作日志和公开文档不输出密钥。不要在旧站先随意改成另一把密钥；两边不一致时按上述流程协调，再从回调记录安排原事件重试。

隔离联调与排错

1. 先运行离线签名示例并核对固定向量。源码中运行 python -m unittest discover -s tests -p 'test_*.py' -q；仅临时 SQLite 和模拟节点，无平台执行器。设置 GAMEBEAST_OLD_ADAPTER 可指定旧站原始 gamebeast.mjs；契约测试只导入它，并将 fetch 注入本地隔离服务。
2. 管理员配置真实结算、供货价和兼容账号后，旧站已有界面填写货源、测试连接、同步商品、映射真实规格。测试连接成功不代表节点付款可用。
3. 从旧站实际生产服务器核实公网 HTTPS、合法签名目录和查单接口可用；统一使用 https://jllyx.cn。旧 SSH 测试通过不能代替此项公网联调。
4. 余额 code=999：查结算是否待定、dealer_no / 密钥、系统时间；商品为空：查真实商品是否建立及是否设置供货价；商品暂停：查中央／接入／商品开关。
5. buy 价格错误：重新同步供货价，不能把金额当面额；在途返回 999：保留原订单号查 get 和中控；不要改 -R 后缀进行重复充值。
6. 回调未确认：查旧站真实 vendorId 配置、SecretKey、时间、DNS／证书和 ok 正文；原单结果不变，修复后补发。
7. 本版自动验收使用模拟结果，未完成真实充值闭环。真实小额联调需要另行明确账号、商品及金额，禁止把运行契约测试当作授权付款。

1. 接入方式

供应网站只对接中央服务，由中央分配节点、记录订单及回调结果。节点不直接向网站供货。接口地址：https://jllyx.cn/api/supply/v1。本机 SSH 隧道属于内部联调，不是网站可使用的公网入口。

接入前需由部署管理员在中央配置：渠道号 channel_no、供货密钥 supply_key、回调地址 callback_url、回调密钥 callback_key。管理员登录密码与供货密钥不同；本页不提供任何真实凭据。确认公网 HTTPS 可用、中央接单开启、商品已开放供货、节点获批准且上线、商品映射完成。

可供货商品以实时共用目录及已验证执行能力为准，固定规格通常 quantity=1；原生接口同样读取配置，参数及数量以目录为准。节点限额单位为分；API 同时返回元和分字段。

2. 请求签名

待签名字符串（各段之间为一个换行符，无末尾换行）：
HTTP_METHOD
/完整路径?原始查询字符串
X-Timestamp
X-Nonce
SHA256(实际发送的正文原始字节)

signature = HMAC-SHA256(供货密钥的 UTF-8 字节, 待签名字符串的 UTF-8 字节)

GET 正文为空字节。路径包含 /api/supply/v1 前缀，不含协议或域名；查询参数编码和顺序须与实际请求一致。JSON 无需固定字段顺序，但签名后必须原样发送，不能重新序列化。重试使用新的时间戳和 nonce，订单号、幂等键、订单内容保持不变。

Python 签名示例（只生成请求，不自动下单）

import hashlib, hmac, json, secrets, time

def make_request(method, target, channel_no, supply_key, body=None):
    raw = b'' if body is None else json.dumps(
        body, ensure_ascii=False, separators=(',', ':')).encode('utf-8')
    stamp, nonce = str(int(time.time())), secrets.token_urlsafe(24)
    text = '\n'.join((method.upper(), target, stamp, nonce,
                      hashlib.sha256(raw).hexdigest()))
    headers = {'Content-Type': 'application/json',
               'X-Channel-No': channel_no, 'X-Timestamp': stamp,
               'X-Nonce': nonce,
               'X-Signature': hmac.new(supply_key.encode(), text.encode(),
                                      hashlib.sha256).hexdigest()}
    return raw, headers  # 使用这份 raw 原样发送；真实下单前核对订单

3. 商品、节点、下单及查单

原生目录的离散数量

原生 GET /api/supply/v1/supplier/catalog 返回 products 数组，保留既有稀疏按元入口。quantitySet 是真实有效数量／元面额集合；minQuantity、maxQuantity 仅为该集合边界。客户端必须优先按 quantitySet 校验，不能将边界之间所有数视为可充。固定规格通常 quantitySet=[1]；按元入口可能为 [6,10]，其 quantity 含义仍为整数元面额。

{"products":[
  {"productNo":63001,"name":"虚构按元入口","offerPrice":1.005,
   "status":"ON_SALE","quantitySet":[6,10],"minQuantity":6,"maxQuantity":10},
  {"productNo":63002,"name":"虚构无有效规格入口","offerPrice":1,
   "status":"OFF_SALE","quantitySet":[],"minQuantity":null,"maxQuantity":null}
]}

以上只展示数量相关字段。第一项只能选择 6 或 10，不能选择 7；第二项不能下单。编号、原生路由和历史快照不会因 GAMEBEAST 目录修正被删除。现有旧站 GAMEBEAST 导入不读取 quantitySet 或原生 minQuantity/maxQuantity。不能让旧站误用本节 HMAC 接口，也不能把这些字段添加到 GAMEBEAST 目录后宣称自动兼容。

下单正文

{
  "merchantOrderNo": "WEB-20260914-0001",
  "idempotencyKey": "WEB-20260914-0001",
  "productNo": 10001,
  "quantity": 1,
  "account": "待充值账号",
  "nodeId": "node-03"
}

merchantOrderNo、idempotencyKey：1～80 位字母、数字、下划线、连字符或点。account：1～64 位同类字符。账号也兼容 parameters.account、params.account 或 recipient，多处出现时须一致。sourceType 可省略或设为 API。

nodeId 可省略，省略时自动调度；指定后只使用该节点。指定节点须已批准、上线、自检通过并关联商品；不满足时拒绝受理。受理后若节点忙、冷却或额度受限，会等待至采购时限，不会改用其他节点。节点限额和防重复机制不会因指定节点而失效。更换 nodeId 属于更改订单内容，不能使用同一订单号修改重试。

新中央订单号采用三位大写字母加七位数字：AAA0000001、AAA0000002，至 AAA9999999 后进入 AAB0000001。编号由服务器持久化分配；取消表单可能跳号，编号不回收。历史订单号及供应网站传入的 merchantOrderNo 保持原值。

返回示例（字段值仅为说明）

{
  "order": {
    "orderNo": "AAA0000001",
    "merchantOrderNo": "WEB-20260914-0001",
    "productNo": 10001, "quantity": 1,
    "requestedNodeId": "node-03",
    "status": "PROCESSING", "reason": "", "stateInfo": "",
    "amount": 1.0, "amountCents": 100,
    "total": 1.0, "platformCharge": 1.0,
    "attempts": []
  },
  "replayed": false
}

查单返回 order，不含 replayed。attempts 记录每次尝试的 sequence、nodeId、alias、alipayMode、phase、reason。requestedNodeId 为 null 表示自动调度；实际执行节点以 attempts 为准。接口受理不代表已扣款或充值成功。

采购时限为受理后 15 分钟。未取得下单许可而超时可判定失败；已取得许可或付款结果不明则保留 UNKNOWN，不能按超时推断未扣款。自动调度在下单前安全失败时可考虑其他节点；新版任务也可在原单已安全取消后继续改派，详见原单取消与安全改派。已授予许可但尚未安全确认原单结束时，只追踪原单。

4. 结果回调

中央向配置的公网 HTTPS 地址 POST。回调只发送 SUCCESS／FAILED 终态，至少一次投递；网站须按 eventId 去重。UNKNOWN 不发送失败回调。中控手工创建的订单不向供应网站回调。

{"eventId":"result-AAA0000001",
 "event":"order.success","occurredAt":"2026-09-14T12:00:00+08:00",
 "data":{"orderNo":"AAA0000001",
         "merchantOrderNo":"WEB-20260914-0001","status":"SUCCESS",
         "stateInfo":"充值成功","total":1.0,"platformCharge":1.0}}

请求头：X-JLL-Event、X-JLL-Timestamp、X-JLL-Signature。验签算法与请求签名不同：

HMAC-SHA256(回调密钥, X-JLL-Timestamp + "." + 原始请求正文)

按实际收到的原始字节验签，使用恒定时间比较；校验时间戳并按 eventId 幂等入账，持久化成功后返回任意 HTTP 2xx。非 2xx 或网络失败会重试，间隔从 5 秒指数增加，最大 1 小时，直到成功。不接受重定向到其他地址。失败回调的 event 为 order.failed。

5. 错误与重试

{"error":{"code":"NODE_NOT_READY","message":"指定节点未就绪或未上线；订单未创建。"}}

6. 中控节点管理

“可接单”要求新鲜心跳、桌面／淘宝／密码／配置就绪、已批准且上线。离线后不再沿用上次勾选显示为就绪。节点卡片显示最后心跳、故障原因、处理建议、当前执行原单；遇验证码或平台拒绝访问须人工处理，不能靠更改状态强制绕过。

删除节点采用停用并归档：凭据立即失效，历史订单和尝试记录保留，默认隐藏，可勾选“显示已删除节点”查看。存在执行中／待核实原单或未结束更新时拒绝删除；节点编号不复用。管理员可以在暂停状态下修改采购间隔、单笔额度、日额度。

统一订单页支持中控手工下单与指定节点；会二次核对账号并提示真实充值。供货网站应使用上面的签名 API，不应模拟管理页面。

管理 POST 均需要有效会话及 X-CSRF-Token；这些接口不能使用供货密钥代替管理身份。删除、下单和额度变化会保留审计记录。

额度及自动化诊断

采购间隔 10～3600 秒（整数）；单笔 1～10000 元；每日 1～100000 元（金额最多两位小数）。修改前须暂停节点，且不存在执行中或待核实原单。每日按中央服务器时区自然日统计，已发下单许可的尝试占用额度；节点本地额度仍独立检查。

中控显示独立收银台及淘宝内嵌页面的适配支持和各自最近执行记录。支持适配不代表当前页面已经通过核验；旧版未上报、未验证或离线时明确标示。异常保留原单和付款尝试，不重新发放付款许可。

后台管理查询与操作 · 0.3.13

本节仅供管理员页面使用，GET 需要有效登录 Cookie，写操作另需 X-CSRF-Token；不能用供货密钥替代。后台列表显式传入 page、page_size，服务端筛选后分页；以下查询参数为各路径的白名单，未知或重复参数会返回 INVALID_QUERY。所有分页页大小 1～100，默认 25；q 最多 80 字，页码从 1 开始。

订单日期与显示口径

date_from、date_to 为 YYYY-MM-DD，按 Asia/Shanghai 的开始日 00:00 至结束日次日 00:00（不含）过滤，即包含结束日全天。后台默认近 7 天，可选择今日、近 30 天、全部或自定义；“全部”只是省略两个日期参数，仍分页。缺失供货金额显示未记录，不用 0 冒充真实值。UNKNOWN 单独显示待核验，不归入失败。

GET /api/admin/orders?source=gamebeast&status=UNKNOWN&date_from=2026-09-12&date_to=2026-09-18&page=1&page_size=25
GET /api/admin/orders?source=gamebeast&page=1&page_size=25

商品规格与额度诊断

固定商品的 quantity_checks 按每个允许数量列真实采购分金额、能否执行及原因；executable_quantities 是满足当前合法映射和硬性单笔额度的数量集合。supply_status=ready|partial|blocked 用于后台区分完整、部分及不能供货。目录数量表示已实现的结构规格范围，节点硬性额度仍逐次校验；临时日额度、离线和冷却属于排队条件。管理员不能仅凭“已上架”判断全部额度已满足。

回调详情的实际证据

回调业务正文持久化后不变；timestamp/sign 在每次真实发送时重新生成。升级前未记录原始 HTTP 请求／响应的事件，request_recorded 和 response_recorded 为 false。升级后只记录真正获得响应的投递证据；网络异常没有响应时不编造 HTTP 状态。历史投递明细最多保留最近 20 次，不改变 outbox、总尝试次数、重试计划、去重或资金结算。

查询统计卡片只进入对应列表。恢复节点、查询原单、补发结果和停止执行是独立操作；前端按钮状态不是授权依据，服务器仍核对登录、CSRF、许可和未结束原单。

超时、停止与节点切换（0.2.8）

单节点下单前准备限时 120 秒，心跳不能延长准备时限；整单采购限时仍为 15 分钟。尚未发下单许可的异常尝试会结束并暂停该节点，自动调度订单可尝试其他有效节点。指定节点订单不自动改派，可在尚未下单时手动切换为自动调度。

采购超时且未发下单许可：终态 FAILED，并说明未发起扣款。已进入平台操作或付款结果不明：记录停止请求、停止后续执行与自动查询，保留 UNKNOWN；不得据超时判定未扣款或换节点重充。停止记录在重启后仍生效；手动查询原单仍可取得最终成功或失败。

POST /api/admin/orders/{orderNo}/stop   {}
POST /api/admin/orders/{orderNo}/switch {}
POST /api/node/attempts/{attemptId}/stop {}

管理接口使用现有登录 Cookie 和 CSRF；节点接口使用现有节点签名并校验尝试归属。stop 在尚未下单时取消采购，否则仅停止自动化。switch 仅允许尚未下单且未超时的采购订单；旧尝试许可撤回，原节点本单不再重试，无其他可用节点则等待采购截止。订单查询增加 stop_requested、stop_state、stoppable、remaining_seconds 和 dispatch_policy。停止请求不是平台取消或退款；节点确认后才显示已停止。

页面提示与订单结果

订单详情读取错误会单独注明，不改变已保存的充值结果。详情读取成功或切换栏目后清除旧错误，也可以点击关闭提示。管理快照包含 center_version，页面与中央版本不一致时会提示刷新；不会自动刷新正在填写的订单。

登录后下载安装包

中控“版本更新”显示最高已发布 build 的 Windows 工作台安装包。仅管理员登录后可查看下载按钮，元数据与文件接口均校验有效登录；退出或会话过期后，原链接返回 401。文件不通过公开静态目录提供。

GET /api/admin/downloads/latest 返回 release_id、version、build、published_at（工作台发布时间）、filename、size、sha256、kind、installer_id 和 url。该版本已发布完整 EXE 时，kind 为 windows-installer，下载地址 /api/admin/downloads/{release_id}/installer 返回 EXE；尚无完整 EXE 时，kind 为 zip-bundle，兼容提供原 ZIP 安装包。上传未完成不会切换当前下载文件；已发布文件缺失或校验失败会报错。

先按现有流程发布签名工作台 release，再上传关联安装程序。安装程序使用同一 Ed25519 公钥校验离线签名，私钥不上传中央；这属于发行完整性校验，不等同于 Windows Authenticode 签名。签名信封仅含 manifest 和 signature，signature 为 Ed25519 对 canonical(manifest) UTF-8 字节的签名十六进制；canonical 使用 JSON 键排序、紧凑分隔符与 ensure_ascii=False。

{"manifest":{"format":1,"kind":"windows-installer","platform":"windows-x64",
"version":"0.2.20","build":2026091515,"release_sha256":"对应已发布 release 的 SHA256",
"sha256":"完整安装 EXE 的 SHA256","size":123456789},"signature":"离线签名十六进制"}

manifest 字段必须完全匹配上例，SHA256 为 64 位小写十六进制，size 为 1～536870912 字节，build 为正整数。version、build、platform 必须与 release_sha256 对应的已发布签名 release 一致。

POST /api/admin/installers/begin   {manifest,signature}  → {id,chunk_size:1048576}
POST /api/admin/installers/chunk   {id,index,data}        → {ok:true}
POST /api/admin/installers/finish  {id}                   → {ok:true}

以上 POST 均需管理员 Cookie 与 X-CSRF-Token。data 为单个 1 MiB 分片的 Base64，index 从 0 开始，末片为剩余字节。只接受服务端生成的 SHA256 编号，不接受文件路径或文件名；不要整体编码安装文件。finish 完整验证长度、SHA256、签名和版本关联后原子发布；失败保留旧下载，允许重传未发布分片。相同信封 begin 与已发布 finish 可幂等重试，发布后分片不可修改。不同签名清单不能复用同一安装程序编号。

EXE 下载后双击，按向导安装。兼容 ZIP 须完整解压再运行 Install.cmd。安装包不含节点身份、账本、Cookie、支付密码或 SSH 凭据。已有工作台使用推送更新；新电脑需单独绑定、登录淘宝和配置连接。中控网页版本与工作台版本独立。

明确失败与节点恢复

异常或暂停节点卡片提供“已处理，恢复接单”按钮，点击后在居中窗口显示检查结果。检查通过则恢复；未通过会说明离线、桌面、登录、密码、配置、执行中、更新中或待核实原单等原因，可处理后重新检查。手动确认不能代替原单结果核验。

可直接上架／下架，保留供货开关、价格、规格、节点映射和已受理订单快照。

已核验充值失败结束原单，不隔离节点。原单交易关闭、退款成功、单商品数量 1、退款金额等于原单金额、付款证据齐全且未曾确认充值成功时，可按充值失败结束；本地保留退款记录。

部分退款、退款申请中、缺少金额证据、付款后仅交易关闭均保留待核实。已成功原单不因后续退款回退结果。结果重报不重新充值、不重复生成结果事件。

已明确结束后仅解除该原单造成的隔离；人工暂停、其他异常隔离和更新暂停不被覆盖。验证码或登录异常仍需处理后恢复。原单付款不明时不能切换重充。

节点余额与交易风险提示 · 0.3.14 / 工作台 0.2.23

节点卡片新增红底余额块。工作台进入已核验原单的收银台时，读取唯一的“账户余额”金额，包含余额不足时可读的金额；不读取或上报支付宝账号、支付密码。尚未采集显示“未采集”，真实零余额显示 0.00 元。

刷新中控只更新最近上报数据，不会主动打开收银台。外部补款、退款、同一支付宝账户在其他电脑发生的支出，不会立即得知。银行卡付款不扣减支付宝余额估算。余额是补款参考，不代替单笔／日额度、原单核验和付款许可，也不据此自动停供或提高额度。

交易风险确认

识别与原单页面关联的淘宝“风险下单确认”后，工作台显示“待人工确认交易风险”，最多等待 5 分钟。须由管理员在该节点阅读平台提示并自行决定是否继续；程序不代点“申请继续交易”或“我已阅读，确认不拦截订单”，不跳过倒计时、验证码或安全核验。人工完成后，仅在同一原单的收银台稳定且订单状态、商品、账号、金额重新核验通过时，续接原有一次付款流程。停止、超时或关联不明则保留原单待核实，不重新创建订单，也不再次付款。

{"account_balance":{"version":1,"currency":"CNY","mode":"business","cents":12252,"observed_cents":14252,"source":"estimated","observed_at":"2026-09-19T08:00:00+08:00","updated_at":"2026-09-19T08:00:05+08:00"},"attention":null}

节点内部接口

本节仅供已经绑定的工作台使用，不是旧站货源协议。节点身份、配置指纹、许可与状态上报由新站和工作台内部协调，旧站不得增加这些参数或使用节点密钥。

取消许可与取消证据（仅节点内部）

工作台在认证心跳中上报 cancellation_v1:true，中控将能力冻结在新执行尝试中。没有该标记的旧尝试不会被追溯开启。以下请求只由对应节点使用原节点 HMAC 签名发送；管理员页面、GAMEBEAST 货源及原生供应商不得直接调用。

取消许可正文须与受理快照及已关联原单精确一致：cents 为采购金额（分）、qty 为实际采购份数；还包括 account、alias、mode、taobao_id、fingerprint、executor_stopped:true、payment_attempted:false 及最多 300 字的 reason。这些内部字段不是旧站新增必填字段。

{"granted":true,"frozen":true,"attempt_id":"A000000000000000000000001",
 "kind":"cancel","cancel_id":"C00000000000000000000000000000001"}

同一许可再次请求返回原 cancel_id，但 granted:false，不能据此再次向淘宝发取消请求。已发付款许可、已付款、尝试已结束或证据不符均拒绝自动取消。客户端也须在提交前持久化一次取消意图，响应丢失后只查原单。

处理中可上报 cancellation_state=verifying（取消／核验中）或 awaiting_manual（等待人工取消）。安全完成使用内部 status=CANCELLED_SAFE、paid=false、verified=true，并携带 cancellation_evidence：cancel_id、source、taobao_id、account、cents、qty、fingerprint、platform_status、paid_at、refund_status、refund_cents、payment_attempted、executor_stopped、checked_at。source 必须为“淘宝订单详情接口”，platform_status 为“交易关闭”，paid_at 为 null、refund_status 为空字符串、refund_cents 为 null；出现退款或扣款证据的关闭订单不能当作未付款。checked_at 为带时区的实际核验时间。中控仍核验原许可、归属、冻结状态与全部证据，不能仅靠状态名判定安全。

{
  "status": "CANCELLED_SAFE", "revision": 4,
  "paid": false, "verified": true,
  "reason": "原单定位异常；已独立核验未付款关闭",
  "cents": 2000, "account": "DEMO_ACCOUNT", "taobao_id": "900000000000000001",
  "cancellation_evidence": {
    "cancel_id": "C00000000000000000000000000000001",
    "source": "淘宝订单详情接口", "taobao_id": "900000000000000001",
    "account": "DEMO_ACCOUNT", "cents": 2000, "qty": 1,
    "fingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "platform_status": "交易关闭", "paid_at": null,
    "refund_status": "", "refund_cents": null,
    "payment_attempted": false, "executor_stopped": true,
    "checked_at": "2026-09-20T10:00:00+08:00"
  }
}

后台详情返回每次尝试的 cancel_state、cancel_reason、cancel_requested、cancel_verified，并以 cancellation_summary 汇总最近取消尝试（state、reason、requested_at、verified_at、attempt_id、node_id）。closed_safe 只表示那次原单已安全结束，整笔订单状态仍以 status 为准。此摘要不是新的 GAMEBEAST 查询字段。

新电脑从中控下载商品配置

POST /api/node/catalog 供已绑定工作台读取中央保存的商品配置；尚未批准接单的节点也可下载。沿用节点 HMAC-SHA256 鉴权请求头 X-Node-Id、X-Timestamp、X-Nonce、X-Signature，签名串为 method、完整 target、timestamp、nonce、原始正文 SHA256，以换行连接。时间允许 ±300 秒，nonce 不能重用。管理员 Cookie、供货渠道密钥和其他节点密钥均不能替代该节点凭据；凭据撤销或节点删除后拒绝下载。

首包：{"cursor":0,"revision":""}
后续：{"cursor":上一包的next_cursor,"revision":"首包返回的revision"}

正文须包含 cursor、revision，可增加 format=2，不接受其他字段或查询参数。不传 format 或传 1 时沿用原格式；传 2 时返回带配置验证结论的新格式。cursor 是上一包最后一个商品的中央编号，不是页码；首包为 0。每包最多 10 条，UTF-8 JSON 正文最多 60,000 字节；内容较大时会提前分页。next_cursor 为 null 时完成，异常过大的单条保留精简原因供跳过。

每条 items 固定包含 number、revision、definition、payload、fingerprint、category、amount_supply、enabled、transferable、reason。number 是中央商品编号，条目 revision 为商品修订整数。definition 只保留经校验的商品白名单字段及参数规则；配置损坏或过大时为空对象。category 为现有中央分类的 {id,name} 或 null；amount_supply 为 {group,name} 或 null，依据中央存储的同指纹、唯一分组成员关联，不修改主用规格或路由。

只有精确匹配内置一元抖币执行规格，或完整通过 taobao-recharge-v1 配置校验的固定商品，才可 transferable=true，并附执行 payload 及其 SHA256 fingerprint。transferable=false 时 payload=null、fingerprint 为空字符串，reason 说明原因。多个分组关联须先在中控核对。按元入口只是中央选择固定规格的路由，始终不可作为采购商品导入。

每次响应在同一只读事务内读取商品、分类和分组后统一计算摘要再分页。本次下发配置发生变化时，后续携带旧 revision 的请求返回 HTTP 409 / CATALOG_CHANGED，工作台须丢弃本轮未完成数据、从首包重读并完成整批校验后才允许导入。未使用分类和中央主用路由切换不属于本次下发配置摘要。

下载不依赖原电脑在线，也不携带登录 Cookie、支付密码、节点密钥、历史订单或原始验证 proof。enabled 仅说明中央供货状态；transferable 仅说明配置可导入。新商品始终默认停用。格式 1 或格式 2 没有有效结论时，仍须本机验证；格式 2 有匹配结论时可复用配置验证，无需在每台电脑逐商品重验，但平台登录、节点批准和用户主动启用仍分别执行。

格式 2：复用已确认的配置结论

首包：{"cursor":0,"revision":"","format":2}
每条商品新增 verification：
null
或 {"format":1,"fingerprint":"对应payload的64位SHA256","method":"direct","scope":"configuration"}

method 为 direct（原工作台直接验证）或 sample（原工作台按既有验证规则复用代表规格结论）。verification 只针对当前精确执行配置；不含来源节点、本机账号、测试订单、源验证时间或凭据。按元入口、不可导入项、无有效来源证据或商品指纹已变化时为 null。商品停售、下架及原节点暂时离线不会抹掉相同配置的历史结论，也不会因此自动上架或启用任何商品。

工作台心跳通过独立的 catalog_verifications 数组上报，不能混入可执行的 products 清单。已验证项须且仅包含 id、fingerprint、status="verified"、method="direct"|"sample"、scope="configuration"、configuration={definition,payload}；失败或待核实测试项须且仅包含 id、fingerprint、status="blocked"。前者由本地有效原始结论提炼，继承自中央的结论不再次上报为独立来源；后者只撤销同一节点、同一本地商品及同一指纹的既有来源。其他独立来源仍有效时，中央可继续给出结论。

中央只采集已绑定且已批准、未撤销节点的明确验证上报，核对当前配置版本、唯一既有映射、商品白名单、已实现执行能力及完整指纹；清单存在、上架、旧版 verified=true 或没有来源方法的历史心跳均不能单独建立结论。结论及来源审计保存在既有 metadata 的 catalog_validation:中央编号中，不另建商品系统。源节点离线或删除不自动否认已记录的配置验证；明确 blocked 上报会撤销对应来源。

部署先更新中控，再更新已有源工作台。源工作台的新心跳会从原来仍有效且没有未解决测试的本地证明提炼结论，无需重做已有验证；中央不从旧心跳猜测 direct/sample。新电脑再用格式 2 同步。每次下载仍在同一读事务中形成完整摘要，结论出现、方法变化或撤销会改变本格式 revision；重复心跳和内部审计时间不会导致分页版本抖动，旧格式 1 也不会因新增验证结论而改变结构或摘要。