You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

98 lines
4.9 KiB

feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
package common.ecommerce.yqn;
/**
* 运去哪(YQN)协议常量。
*
* <p>端点与路径是<b>协议的一部分</b>,写在代码里,不做成配置表。
* 运行时不使用 {@link #PRODUCTION_BASE_URL}:端点由调用方每次经
* {@code WarehouseConnection} 传入。</p>
*
* <p>端点与路径来自 Spec W0 §2.3 / §8.1(《得力系统对接.xlsx》整理)。</p>
*/
public final class YqnConstants {
public static final String ADAPTER_ID = "yqn";
/** PR(联调)环境。 */
public static final String PR_BASE_URL = "https://pr-hwc-open-api.yqn.com";
/** 生产环境。 */
public static final String PRODUCTION_BASE_URL = "https://open-hwc.yqn.com";
/**
* 组织级 Token 的请求头名。API 115 文档确认:{@code x-api-key},固定值放请求头,无签名。
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
*/
public static final String TOKEN_HEADER = "x-api-key";
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
/** 商品创建 / 编辑(V1 推荐版)。 */
public static final String PATH_PRODUCT_SAVE = "/v1/product/save";
/** 创建销售订单(API 123)。 */
public static final String PATH_ORDER_CREATE = "/v1/saleOrder/create";
/** 订单详情(API 128):按来源单号查完整订单。 */
public static final String PATH_ORDER_FIND_ONE = "/v1/saleOrder/findOne";
/** 取消销售订单(API 122)。 */
public static final String PATH_ORDER_CANCEL = "/v1/saleOrder/cancel";
/** 批量查询库存(API 107),GET + 分页。 */
public static final String PATH_INVENTORY_PAGE = "/v2/inventory/get_inventory_by_page";
/** 创建调拨单(API 139)。 */
public static final String PATH_TRANSFER_CREATE = "/v2/transferOutboundPlan/create";
/** 创建入库计划单(API 97)。 */
public static final String PATH_INBOUND_CREATE = "/v1/inbound/createInboundPlan";
/** 打印入库计划单箱标(API 99):异步生成,只回任务编号。 */
public static final String PATH_INBOUND_BOX_LABEL = "/v1/inbound/generateBoxLabel";
/** 打印入库计划单 SKU 标(API 100):异步生成,只回任务编号。 */
public static final String PATH_INBOUND_SKU_LABEL = "/v1/inbound/generateItemLabel";
/** 查询入库计划(API 101)。 */
public static final String PATH_INBOUND_GET = "/v1/inbound/getInboundPlanInfo";
/** 创建销售退货(API 81)。 */
public static final String PATH_RETURN_CREATE = "/v3/saleReturn/createSaleReturnPlan";
/** 退货条目处理(API 77):按明细行设置检验后处理方式。 */
public static final String PATH_RETURN_PROCESS = "/v3/saleReturn/addProcessMode";
/** 创建销毁计划(API 88)。 */
public static final String PATH_DESTRUCTION_CREATE = "/v1/destroyPlan/createDestroyPlan";
/**
* 物流轨迹(API 189):{@code GET /api/v2/orderShipment/track/{trackingNo}}。
*
* <p><b>注意主机不同</b>:这个接口在 {@code pr-ship-api.yqn.com},不是仓接口的
* {@code pr-hwc-open-api.yqn.com}。调用方需通过
* {@code WarehouseConnection.of(主基址, 辅助基址, 凭据)} 传辅助基址,
* 未传时适配器显式拒绝而不是打到主基址上。</p>
*/
public static final String PATH_TRACKING = "/api/v2/orderShipment/track/";
/** 轨迹接口的 PR 环境基址;与仓接口不同主机,供调用方填 {@code auxEndpointBaseUrl}。 */
public static final String AUX_BASE_URL_PR = "https://pr-ship-api.yqn.com";
/**
* 轨迹接口的成功码——<b>待联调核对</b>。
*
* <p>该接口在另一个主机(ship-api),文档响应示例里 {@code code} 是 {@code 1},
* 但同站的其它接口都是 {@code 200},且该文档的示例值是自动生成的占位符
* ({@code message: "example"}),不能据此断定。因此两者都按成功处理,
* 联调确认后再收紧为单一值。</p>
*/
public static final int[] TRACK_SUCCESS_CODES = {1, 200};
/** 轨迹接口某次返回的业务码是否按成功处理。 */
public static boolean isTrackSuccess(int code) {
for (int ok : TRACK_SUCCESS_CODES) {
if (ok == code) {
return true;
}
}
return false;
}
/** 结算明细(API 133):作业费 / 仓储费 / 增值服务费 / 尾程费。 */
public static final String PATH_FEE_DETAIL = "/v1/warehouse/operation/costs/detail";
/** 订单测算 / 运费试算(API 121):发货前按包裹 + 地址 + 渠道询价。 */
public static final String PATH_FEE_ESTIMATE = "/v1/saleOrder/calculate";
/** 物流产品服务清单(API 135):按仓查询可用承运商渠道。 */
public static final String PATH_LOGISTICS_PRODUCTS = "/v2/sysCarrierGroup/getCarrierGroupList";
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
/** Spec §7.5:三家仓均未公开限流值,保守默认 2 req/s/仓。 */
public static final int PERMITS_PER_SECOND = 2;
private YqnConstants() {
}
}