docs(selfop): freeze historical reconstruction contract and local verification
This commit is contained in:
@@ -21,8 +21,35 @@
|
||||
|
||||
当前 Java 已有五个内部 POST 入口，共用 `/internal/integrations/lingxing/wms` 前缀并要求内部服务令牌：`/warehouses/query`、`/outbound-orders/query`、`/outbound-orders/locate`、`/outbound-orders/detail`、`/product-inventory/query`。出库发现与按单定位接口同时传递 `productList[].productSku/productName/qty`；列表字段完整时直接用于统计，缺项时才补该单详情，数量为零不属于缺项。接口职责和字段见[一期方案的接口约定](领星一件代发数据统计一期方案.md#平台查询接口和权限建议)。外部直接 HTTP 联调或源码核对不代表 Java 入口已运行验收。[本地启动说明](../../baiyue-firstleg/integration-service/README.md)
|
||||
|
||||
## 库存流水有界诊断（2026-10-15）
|
||||
|
||||
官方 OMP [库存流水分页接口](https://apidoc-omp.xlwms.com/reference/post_openapi-v2-stock-stockcellbook-page-1.md) 为 `POST /openapi/v2/stock/stockCellBook/page`，支持 `whCode`、`customerCode`、精确 SKU `barcodeAccurate`、`startTime/endTime`、`sortName=createTime`、`sortOrder=asc`。返回库位、批次、业务类型、`bookQty`、字符串 `bookChangQty`、`closeQty` 和时间。文档品质为1正品/2次品、ID为数字，但2026-10-15授权本地样本实际为字符串ID、品质0正品／1次品；其他品质仍未确认，不照搬文档枚举。另有批次流水接口 `/openapi/v2/stock/batch/flow/page`，本轮不混采两套流水。
|
||||
|
||||
实测字段合同：分页为 `records,total,size,current,pages`；流水ID保持字符串，禁止经JS Number再转回而丢精度。样本中 `bookQty` 是有符号增减量，与字符串 `bookChangQty` 一致，不是期初库存；`closeQty` 是同库位／内部批次／品质链的结存，不是SKU全仓总库存。三锚点及逐日销量可在原单SKU样本范围内对齐；本轮扩大字段核验并不表示新增SKU已完成独立锚点对账。原始响应仅存私有诊断目录，业务设计见[库存周转历史还原方案](库存周转视图设计.md#历史库存还原与周转率修正方案2026-10-15实施合同)。
|
||||
|
||||
### 本地扩展核验后的接口约束
|
||||
|
||||
| 核验项 | 已观察到的合同 | 实现边界 |
|
||||
| --- | --- | --- |
|
||||
| 时间端点 | 同一已知流水放在startTime、endTime均返回；严格前后相邻秒窗口均不返回 | 来源窗口两端含，平台按ID去重并按北京时间半开区间归属。午夜归属需离线测试，不宣称已取得恰在午夜的真实事件。 |
|
||||
| 仓范围与分页 | 不传货主／SKU可返回多个货主；一个完整小时间片10条，size100／20／6两页的ID与载荷一致；原单SKU32条以size20两页重读也一致 | 支持按仓时间片计划，不等于已核验两仓全量或永久稳定排序。每次正式片仍做覆盖、数量、身份、重复和漂移校验。 |
|
||||
| 合法空流水页 | 实测返回 `current=1,size=10,total=0,pages=0,records=[]`，请求页大小可能为20或100 | 只有首个空页且全部条件吻合才归一化，保留sourceSize；非空页、页码错误、pages非0和其他size不放宽。现有库存接口策略不随流水修复一起改变。 |
|
||||
| 数量／品质 | 234条去重流水中，bookQty均与bookChangQty一致；出现DO／PA／IMO／IAT／RI，品质0正品／1次品 | 不再按业务类型二次取负；不把未见BO／OBIAT自动映射为其他类型。 |
|
||||
| 调整与退件 | 完整窗口IAT35条：7正、28负；RI12条均为正 | 符号来自实际delta；退件和调整不自动成为销量分子。单独的链段仍需完整窗口及锚点校验。 |
|
||||
| 移库与品质转换 | 10组同品质移出／移入净额0；另一个完整单12条、6个SKU，正品合计−17、次品+17，总量0，业务类型同为IMO | 不能按IMO忽略全部行，也不能按单号去重掉一端。分品质记账后合计总实物；一个品质过滤结果不能用于全品质历史还原。 |
|
||||
| 同链同秒 | 观察到同一链同一秒两笔−1，结存分别38、37 | 此样本可由数量关系区分顺序，不证明ID或接口同秒排序有永久顺序合同；存在多种可行链序时保持未知。 |
|
||||
| 零库存 | 一条定向产品库存，isHideInventory=0明确返回stkQty=0，改为1则空页 | 明确零行可作为零锚点；缺行仍不能推定0，不能由该样本证明所有历史售空SKU都会返回。 |
|
||||
|
||||
源数据保留期限、历史更正／删除通知、跨页一致性保证和不可见历史主体无法由有限只读请求证明；这些仍需供应商契约或独立业务对账。当前实现准入为“已观察字段可开发，逐SKU／日期证据合格才发布”，不是“整个仓库历史完整已证明”。请求次数、实际时段、账号状态及本地测试结果统一见[TEST主契约](../测试环境单机部署与配置契约.md#自营库存周转-test-发布与验收2026-10-15)。
|
||||
|
||||
最小诊断源码入口为平台 `POST /api/platform/v1/last-leg/self-operated-analytics/inventory-flow-probe` → Integration `/inventory-flow/query`。只允许 TEST BUSINESS、配置仓库、平台非代登录且有 sync 权限；一次限定一个货主/SKU、最多31日、第一页最多1000行、最多一次供应商请求。同键成功回读结果，异参拒绝，失败/未知不自动重试；完整分页只证明这次返回完整，不证明供应商历史无缺失。请求共用原账号 lease/fence、短 permit、间隔、冷却和计数，独立任务类型 `INVENTORY_FLOW_PROBE` 不进入自动调度，SAMPLE_DONE/DEAD 只作为诊断终态。源11008“无接口权限”仅终止这个可选接口，其他凭据错误、429及未知结果仍按原账号保护处理。
|
||||
|
||||
诊断记录保存在现有任务/尝试中，不新建业务表，不写库存日代表，不发布经营结果。实施顺序：验证受控入口及失败隔离 → 经授权部署诊断版本 → 单SKU真实流水与已保存观测时点对账 → 决定是否具备全量历史重建条件。当前 key 权限、历史完整性和重建可行性不能由离线测试或文档推定；部署事实仍只维护在测试环境主契约。
|
||||
|
||||
## 认证和请求格式
|
||||
|
||||
历史库存自动采集使用独立内部入口 `POST /internal/integrations/lingxing/wms/inventory-flow-page/query`，保持服务令牌及单次出口许可验证，不暴露为平台可任意调用的接口。冻结仓库、北京时间起止（最长一天）、排序和每页1000条；`current`必须匹配任务持久化下一页。Integration 的 Long 类型 `total` 按统一Jackson合同输出十进制字符串，Lastleg 严格解析整数并验证页数及累计条数。来源ID、货主、SKU和仓库按字符串保存；只持久化数量还原所需白名单。该内部路径与仅单SKU的诊断入口并存，各自有独立权限／任务边界；真实部署与覆盖状态见TEST主契约。
|
||||
|
||||
基础地址为 `https://api.xlwms.com`；所有请求使用 HTTPS POST，`Content-Type: application/json; charset=UTF-8`，响应按 JSON 解析。认证参数放在请求体中，不需要 OAuth 获取 Token 的前置调用。
|
||||
|
||||
| 包络字段 | 类型 | 约束 |
|
||||
|
||||
Reference in New Issue
Block a user