商城与库存
Java 商城提供后台基础资料、商品/SKU、库存单据、订单、发货、支付与售后。它不包含独立消费者客户端，当前没有租户或部门级数据过滤。
接口前缀为 /api/v1/mall；金额以整数分保存和传输，时间按 UTC ISO 输出。精确方法、权限和请求结构以 OpenAPI、Controller 和 art-system/src/test/resources/mall/endpoints.json 为准。
首次使用顺序
- 配置品牌、分类、商品服务、属性与运费等实际所需资料。
- 创建并启用默认仓库。
- 创建商品与 SKU，配置分仓库存。
- 先验证人工付款下的订单、发货和售后，再按业务需要接入在线支付。
- 使用普通业务角色验证操作权限与拒绝场景。
交付库没有演示商品或仓库。缺少默认仓时，不能把非零初始库存写入当作可用前置条件；切换默认仓也不会搬迁历史订单的预占库存。
第一次跑通一笔订单
在验收环境用普通实物商品验证：创建启用的默认仓库 → 创建商品/SKU 并准备少量库存 → 后台代客下单 → 人工确认付款 → 发货。观察下单前后可用/锁定库存，再检查发货记录和库存流水。需要售后时继续验证申请、处理和退款结果。
先使用人工付款便于确认商品、库存和履约配置；接入真实在线支付后，还需单独验证渠道回调与退款。不要把人工标记付款用于替代未确认的在线支付结果。
商品为什么不能提交上架
按表单提示补齐当前商品类型要求的资料、图片、分类、价格、规格及配送信息。上传图片只是商品资料的一部分，仍需完成表单校验。库存相关错误先确认默认仓库已启用，以及 SKU/分仓库存设置是否满足本次操作。
金额接口使用整数分，例如 1990 表示 19.90 元；管理端通常负责显示转换，二次开发时避免重复乘除 100。
库存事实与单据
AVAILABLE、LOCKED、IN_TRANSIT 是分仓库存事实。共享写入核心在控制锁与稳定的 SKU 锁顺序下维护非负校验、不可变流水、SKU/商品聚合和单据状态。
| 动作 | 库存变化 |
|---|---|
| 入库/出库确认 | 整单增加/扣减 AVAILABLE，任一明细失败回滚 |
| 调拨审核 | 源仓 AVAILABLE 转 IN_TRANSIT |
| 调拨收货 | 扣减源仓在途，增加目标仓可用库存 |
| 盘点完成 | 根据完成时当前可用库存与实盘量调账，同时保留原账面差异 |
| 实物下单 | 固化预占仓库，AVAILABLE 转 LOCKED |
| 发货 | 消费订单原仓 LOCKED，生成履约、出库及流水 |
不能直接更新 SKU 汇总库存来绕过分仓流水。库存单据的重复状态动作不能二次扣加库存；订单释放也必须使用订单创建时的预占仓库。
订单与售后
订单固化商品、SKU、客户、地址、金额与仓库快照。纯虚拟订单不占库存；实物分批发货按剩余量校验，不能从另一仓消费不属于该订单的预占。
已付款、未履约订单取消后仍需完成退款。售后申请占用可售后数量与退款额度，驳回或取消释放占用。退货退款首次完成时按既定用例回补默认仓，重复回调不能重复退款或入库。
商品复制产生新草稿与新 SKU 编码，库存不复制。恢复商品为 OFF_SHELF；彻底删除仍检查历史交易和库存引用。
不确定的支付结果
在线渠道初始化失败时订单和预占可能已提交，payment.paymentInitFailed=true 不代表下单回滚，也不证明渠道未受理。
存在在线 PENDING 流水时，改价、取消、关闭或人工标记付款会被拒绝。先查询渠道明确结果，不直接清流水、释放库存或另建一笔支付。详见 支付接入。
后台任务与维护
商品排期默认每分钟、超时订单每 5 分钟、支付恢复每 10 分钟执行。任务有批量和时间预算，不承诺到点瞬间处理全部积压。
在线待支付不会因超过本地时间阈值就被假定失败；持续积压需核对渠道、错误和库存约束。关闭商城 scheduler 不等于停掉所有写入者，备份前按 备份与升级 完成停写。
修改入口与验证
从 mall/controller 找到请求，再沿 mall/service 到 mall/mapper 和 mapper/mall。数据结构在 V4__init_mall.sql，后续变更使用新增迁移；站点配置归 settings，商城通过公开端口访问。
修改订单或库存时覆盖同事务失败、并发/重复执行、跨仓预占、部分发货、取消退款及渠道延迟结果。使用隔离 MySQL 与 HTTP 集成验证，不能仅用返回固定结果的单元测试代替。随包规则见 docs/guides/mall-contracts.md。