19 v1 api contract draft

V1 API 契约草案

本文档把 V1 页面、状态机和数据模型转换为可评审的接口边界。文中路径、路由名、请求和响应均为拟定契约，不表示接口已经存在，也不要求当前阶段编写代码。

一、设计结论

1. 接口分域

使用端	部署前缀	V1 业务前缀	鉴权方式
平台管理端	CRMEB `api_admin_prefix`	`farm/*`	`AdminTokenMiddleware` + `AdminAuthMiddleware`
商户中心	CRMEB `api_merchant_prefix`	`farm/*`	`MerchantTokenMiddleware` + `MerchantAuthMiddleware`
用户端	`/api/`	`farm/*`	公开查询可选登录；订单、持仓和账本强制登录
服务/现场端	CRMEB `api_service_prefix`	`farm/*`	`ServiceTokenMiddleware` + 业务范围校验

文档表格只写业务相对路径。例如用户端 farm/cloud/activity/current 的完整访问路径为 /api/farm/cloud/activity/current。

2. 与 CRMEB 的边界

复用 CRMEB 用户、商户、商品、支付、退款、物流、余额和普通零售订单。
云仓活动、活动 SKU、批次、去向、持仓、二次分配、回购和业务账本使用独立接口与业务表。
云仓只参考普通秒杀的场次、倒计时、限购和支付超时交互，不复用普通秒杀的 product_type=1 数据语义。
云仓首次购买、租地和认养均可生成 CRMEB 交易主单，但必须由独立业务创建服务编排并写入一对一业务扩展记录。
不为云仓直接新增现有 product_type 或 activity_type 枚举，也不在核心订单表增加农业专用类型；统一通过 eb_farm_order_binding 声明业务、财务、库存和履约策略。
普通二次零售仍走 CRMEB 原订单接口；云仓通过内部库存分配和订单事件建立二次零售关联。

3. V1 下单粒度

云仓抢购接口一次只接受一个活动 SKU，可购买多件同一 SKU。这样能够：

保持秒杀链路短，避免跨商户、跨批次和不同规则混单。
保证一条 CRMEB 订单明细对应一条云仓首次明细。
让去向、首次退款、持仓和商户货款都能以整条明细处理。
用户需要不同去向时，天然通过不同订单完成。

该粒度已冻结：云仓一单一活动 SKU，租地和认养一单一套餐。普通商城订单不受影响。

二、统一协议

1. 响应包

保持 CRMEB 当前 ApiResponseService 结构：

{
  "status": 200,
  "message": "success",
  "data": {}
}

失败仍使用 CRMEB 失败状态，并在 data 中增加稳定业务错误码：

{
  "status": 400,
  "message": "该订单明细已自动转为平台代销",
  "data": {
    "error_code": "CW_CHOICE_ALREADY_FINAL",
    "retryable": false,
    "current_state": "consigning",
    "resource_version": 8
  }
}

前端展示 message，业务分支判断使用 error_code，不得解析中文文案。

2. 分页、排序与筛选

项目	契约
页码	`page`，从 1 开始
每页数量	`limit`，默认 20，最大 100
返回列表	`data.list`
返回总数	`data.count`
排序	只接受接口白名单中的 `sort_field`、`sort_order=asc\|desc`
时间范围	`date_start`、`date_end`，闭区间
状态筛选	使用稳定状态码，不传中文
导出	异步生成导出任务，不在列表请求中直接返回大文件

3. 数据格式

类型	API 规则
主键/业务 ID	统一以字符串返回，防止 JavaScript 大整数精度丢失
业务编号	字符串，例如 `CWB202608010001`
金额	两位小数字符串，例如 `"128.50"`，前端不得使用浮点数自行结算
云仓实体库存/件数	非负整数字符串，例如 `"12"`；活动、供货、分配、核销和实物回购不得产生碎件
一般农业数量	最多三位小数字符串，例如 `"12.500"`，具体精度以 `34` 字段类型为准
用户持仓经济等价数量	六位小数字符串，例如 `"10.500000"`，用于比例销售和回购，不直接代表可拆分实物
比例	使用基点整数，`10000=100%`、`6500=65%`
日期时间	`YYYY-MM-DD HH:mm:ss`，统一按 `Asia/Shanghai`
布尔值	JSON `true/false`
状态	小写英文稳定码
媒体	返回文件 ID、URL、类型和缩略图，不只返回逗号分隔字符串

4. 列表摘要与详情

列表只返回检索、比较和操作按钮判断所需字段。
详情接口返回规则快照、状态时间线、关联对象和允许操作 allowed_actions。
前端按钮显示以 allowed_actions 为准，同时保留后端二次鉴权。
历史订单详情返回下单时快照，不拼接当前已修改配置。

5. 乐观锁

修改活动、套餐、批次人工操作和异常处理时必须提交 version：

{
  "version": 6,
  "name": "八月云仓专场"
}

版本不一致返回 COMMON_VERSION_CONFLICT，并携带当前版本。前端提示刷新后比较，不静默覆盖。

6. 幂等

CRMEB 当前 RequestLockMiddleware 只提供短时请求锁，不能替代业务幂等。V1 按调用来源拆分三类契约。

6.1 HTTP 写接口

用户、商户、平台和服务端主动提交的 P0 写接口必须同时提交：

Header：Idempotency-Key
Body：request_id

两者必须是同一 UUID；multipart/form-data 也在表单字段中提交 request_id。服务端以“operation_code + actor_type + actor_id + request_id”建立唯一约束，并保存规范化请求摘要、目标业务对象和首次响应。重复请求摘要相同则返回第一次结果，摘要不同返回 COMMON_IDEMPOTENCY_CONFLICT。

HTTP 必须幂等的命令包括：

创建抢购订单、租地订单、认养订单。
用户确认去向、创建/取消补运费单、申请退款。
平台或商户的审核、验收、发布、分配、回购、结算、异常和溯源命令。
现场记录、附件上传后的业务提交、核销和履约命令。

6.2 支付与退款回调

渠道回调不要求 HTTP Idempotency-Key。幂等事实键按业务载体固定：

CRMEB 普通订单继续使用现有订单号、支付单和渠道交易号约束。
云仓补运费使用 freight_order_no + channel_transaction_id + normalized_amount；同订单同交易号重复返回成功，同订单出现不同交易号或金额进入人工复核。
在线退款使用本地唯一退款单号和渠道退款号；重试必须复用原退款单号。
每次回调保存验签结果和规范化摘要；同一事实键摘要不同不得覆盖首次成功事实。

6.3 事件与定时任务

内部消费者和定时任务不伪造客户端 request_id：

事件消费使用 event_id + consumer_name，业务写入另有确定性结果键。
定时任务批次使用 job_name + run_key，单条处理使用“任务名 + 业务对象 + 目标状态/版本”的结果键。
自动转代销、创建持仓、启动批次、二次分配、生效/退款、节点账本、正式入账、商户货款、回购、产出分配和履约创建均依赖业务唯一键兜底。
相同结果键输入摘要不一致时停止重试并进入冲突告警，不能以后到请求覆盖先到事实。

7. 统一异步操作查询

导入、导出、批量生成、重算、对账和修复命令统一返回 operation_no。四端都注册相同相对路径，但分别经过各自 Token、中间件和 Controller：

终端	方法与相对路径	Controller 方法	约束
平台管理端	`GET farm/operation/detail/:operation_no`	`admin/farm/support/FarmOperation::detail`	发起人本人或拥有目标对象范围及操作查看权限
商户端	`GET farm/operation/detail/:operation_no`	`merchant/farm/support/FarmOperation::detail`	当前 `mer_id` 发起或归属本商户
用户端	`GET farm/operation/detail/:operation_no`	`api/farm/support/FarmOperation::detail`	当前 `uid` 发起且结果属于本人
服务/现场端	`GET farm/operation/detail/:operation_no`	`service/farm/FarmOperation::detail`	当前 `service_id` 发起或目标仍在当前职责范围

响应至少包含 operation_no、operation_type、status、progress_total、progress_done、success_count、failure_count、result_summary、result_file、error_code、started_at、finished_at 和 allowed_actions。列表页面以低频轮询或用户主动刷新更新，不为 V1 引入 WebSocket；终态后停止轮询。结果文件使用短时签名地址，不能返回服务器物理路径。

三、通用请求对象

1. `PageQuery`

{
  "page": 1,
  "limit": 20,
  "keyword": "",
  "status": "",
  "date_start": "",
  "date_end": "",
  "sort_field": "created_at",
  "sort_order": "desc"
}

2. `RuleSnapshot`

云仓、租地和认养订单的详情至少返回：

{
  "rule_version": 3,
  "snapshot_at": "2026-08-01 10:00:00",
  "settlement_mode": "principal_profit_periodic",
  "milestones": [2500, 5000, 7500, 10000],
  "choice_deadline_at": "2026-08-08 23:59:59",
  "pickup_days": 7,
  "expected_sale_days": 30,
  "maturity_resolution_days": 30,
  "user_profit_rate_bp": 6500,
  "platform_profit_rate_bp": 3500,
  "platform_cost_policy": "warehouse_logistics_marketing_costs_borne_by_platform",
  "buyback_rate_bp": 10000,
  "primary_after_sale_days": 7,
  "secondary_after_sale_days": 7
}

3. `AllowedActions`

{
  "allowed_actions": [
    "view",
    "choose_shipping",
    "choose_pickup",
    "choose_consign",
    "apply_primary_refund"
  ]
}

4. `FinancialPostingCommand`

正式入账接口只接受来源记录，不接受金额和目标账户：

{
  "source_ids": ["12001", "12002"],
  "version_map": {
    "12001": 3,
    "12002": 1
  },
  "request_id": "018fcaea-5d79-7c7f-a823-0de1c09c9401",
  "review_remark": "自动校验通过"
}

后端逐条返回 source_id、posting_id、status、crm_bill_id 和错误码。批量接口允许部分记录因状态变化而失败，但每条记录各自保持原子；响应必须清楚区分首次成功、幂等命中、待人工、可重试失败和永久失败。

5. `CloudFreightPaySuccessCommand`

支付渠道监听器只向领域服务传递已验签并规范化的支付事实：

{
  "freight_order_no": "CF20260730000001",
  "attach": "farm_cloud_freight",
  "pay_driver": "weixin",
  "provider_transaction_id": "4200000000000000000",
  "paid_amount": "12.00",
  "currency": "CNY",
  "paid_at": "2026-07-30 21:03:20",
  "callback_hash": "sha256:72c1..."
}

该命令只由验签后的内部监听器构建，不开放给用户 API。支付宝金额从验签后的 total_amount 获取；微信分金额先转换为元。原始回调只保存脱敏摘要和哈希，完整敏感报文继续按 CRMEB 支付日志策略处理。

四、平台端 API 目录

1. 云仓活动与活动商品

页面	方法与路径	拟定路由名	用途
`ADM-CW-001`	`GET farm/cloud/activity/lst`	`adminFarmCloudActivityLst`	活动列表与汇总
`ADM-CW-001`	`GET farm/cloud/activity/filter`	`adminFarmCloudActivityFilter`	状态数量
`ADM-CW-002`	`GET farm/cloud/activity/detail/:id`	`adminFarmCloudActivityDetail`	活动详情
`ADM-CW-002`	`POST farm/cloud/activity/create`	`adminFarmCloudActivityCreate`	创建草稿
`ADM-CW-002`	`POST farm/cloud/activity/update/:id`	`adminFarmCloudActivityUpdate`	编辑草稿
`ADM-CW-002`	`POST farm/cloud/activity/precheck/:id`	`adminFarmCloudActivityPrecheck`	发布前完整校验，不改变状态
`ADM-CW-002`	`POST farm/cloud/activity/publish/:id`	`adminFarmCloudActivityPublish`	校验并发布
`ADM-CW-002`	`POST farm/cloud/activity/close/:id`	`adminFarmCloudActivityClose`	关闭未开始/异常活动
`ADM-CW-001`	`POST farm/cloud/activity/copy/:id`	`adminFarmCloudActivityCopy`	按历史快照复制为新草稿
`ADM-CW-003`	`GET farm/cloud/activity_product/lst`	`adminFarmCloudActivityProductLst`	活动商品列表
`ADM-CW-003`	`GET farm/cloud/activity_product/detail/:id`	`adminFarmCloudActivityProductDetail`	商品及 SKU 规则
`ADM-CW-003`	`POST farm/cloud/activity_product/create`	`adminFarmCloudActivityProductCreate`	添加活动商品
`ADM-CW-003`	`POST farm/cloud/activity_product/update/:id`	`adminFarmCloudActivityProductUpdate`	编辑未发布规则
`ADM-CW-003`	`POST farm/cloud/activity_product/remove/:id`	`adminFarmCloudActivityProductRemove`	移除未开始商品
`ADM-CW-003`	`GET farm/cloud/activity_sku/lst`	`adminFarmCloudActivitySkuLst`	活动 SKU、库存和规则
`ADM-CW-003`	`POST farm/cloud/activity_sku/update/:id`	`adminFarmCloudActivitySkuUpdate`	编辑未发布 SKU 价格、周期、分成和回购
`ADM-CW-003`	`POST farm/cloud/activity_sku/source_check/:id`	`adminFarmCloudActivitySkuSourceCheck`	重新核验单个草稿 SKU 来源，不改已发布快照
`ADM-CW-003`	`POST farm/cloud/activity/source_check/:id`	`adminFarmCloudActivitySourceCheck`	批量核验活动草稿的来源 SKU
`ADM-CW-003`	`POST farm/cloud/activity_sku/resale_map/:id`	`adminFarmCloudActivitySkuResaleMap`	绑定 `cloud_only` 二次销售 SKU
`ADM-CW-004`	`GET farm/cloud/activity/chart/:id`	`adminFarmCloudActivityChart`	活动数据面板

活动发布前必须校验：

每个 SKU 对应唯一云仓批次草稿。
每个活动 SKU 有独立稳定 activity_sku_id，并保存来源商品、当前规格值、unique、规范化规格文本和发布快照。
每个来源同步状态为 matched；changed 可由运营确认更新草稿，missing、ambiguous、unresolved 禁止发布。
活动库存不超过已验收可用量。
抢购价、供货价、预计周期、分成、结算模式和回购规则完整。
用户与平台利润分成基点合计等于 10000。
平台成本承担策略固定为“仓储、物流、营销等运营成本不从用户本金或收益账本扣减”，并进入发布快照。
回购比例在 (0,10000]。
代销固定开启；邮寄和自提所需配置完整。
活动开始、结束、选择截止和代销到期时间顺序正确。
二次销售映射 SKU 的库存来源为 cloud_only，不得与普通库存混合。
发布后影响历史订单的规则字段不可直接覆盖，只能关闭或创建新活动。

活动 SKU 详情必须同时返回 source_sync_status、source_checked_at、来源诊断标识和活动发布快照。草稿页面可提示并执行来源重检；已发布页面只显示告警，任何接口都不得用 CRMEB 当前商品数据覆盖已发布快照。

2. 供货、验收与商户货款

页面	方法与路径	拟定路由名	用途
`ADM-CW-005`	`GET farm/cloud/supply/lst`	`adminFarmCloudSupplyLst`	供货申请列表
`ADM-CW-006`	`GET farm/cloud/supply/detail/:id`	`adminFarmCloudSupplyDetail`	商品、SKU、价格、材料和责任快照
`ADM-CW-006`	`POST farm/cloud/supply/platform/create`	`adminFarmCloudPlatformSupplyCreate`	创建平台自营供货并原子预占自营来源 SKU 库存
`ADM-CW-006`	`POST farm/cloud/supply/audit/:id`	`adminFarmCloudSupplyAudit`	审核通过/驳回并建立来源库存预留
`ADM-CW-006`	`POST farm/cloud/supply/delivery/receive/:delivery_id`	`adminFarmCloudSupplyDeliveryReceive`	平台仓确认实际收货和短少
`ADM-CW-006`	`POST farm/cloud/supply/inspection/create/:delivery_id`	`adminFarmCloudSupplyInspectionCreate`	建立待检批次
`ADM-CW-006`	`POST farm/cloud/supply/inspection/complete/:inspection_id`	`adminFarmCloudSupplyInspectionComplete`	固化合格、待检、拒收和库位
`ADM-CW-006`	`POST farm/cloud/supply/release/:id`	`adminFarmCloudSupplyRelease`	释放未交付或已取消的来源库存预留
`ADM-CW-006`	`POST farm/cloud/supply/return/complete/:return_id`	`adminFarmCloudSupplyReturnComplete`	确认实物已退回并恢复来源库存
`ADM-CW-006`	`POST farm/cloud/supply/platform_acquire/prepare/:supply_id`	`adminFarmCloudSupplyAcquirePrepare`	固化平台承接数量、价格、目标自营 SKU 和证据预案
`ADM-CW-006`	`POST farm/cloud/supply/platform_acquire/review/:acquisition_id`	`adminFarmCloudSupplyAcquireReview`	独立复核通过或驳回承接预案
`ADM-CW-006`	`POST farm/cloud/supply/platform_acquire/execute/:acquisition_id`	`adminFarmCloudSupplyAcquireExecute`	原子转入平台库存并闭合供货数量
`ADM-CW-006`	`POST farm/cloud/supply/freeze/:supply_id`	`adminFarmCloudSupplyFreeze`	质量或库存冻结
`ADM-FN-001`	`GET farm/cloud/merchant_ledger/lst`	`adminFarmCloudMerchantLedgerLst`	商户供货账本
`ADM-FN-005`	`GET farm/cloud/merchant_ledger/detail/:id`	`adminFarmCloudMerchantLedgerDetail`	货款公式和来源
`ADM-FN-003`	`POST farm/cloud/merchant_statement/preview`	`adminFarmCloudMerchantStatementPreview`	预览待入单账本和金额
`ADM-FN-003`	`POST farm/cloud/merchant_statement/generate`	`adminFarmCloudMerchantStatementGenerate`	按商户和自然日生成结单
`ADM-FN-003`	`POST farm/cloud/merchant_statement/review/:id`	`adminFarmCloudMerchantStatementReview`	审核或驳回结单
`ADM-FN-003`	`POST farm/cloud/merchant_statement/execute/:id`	`adminFarmCloudMerchantStatementExecute`	执行已审核或自动阈值内结单入账
`ADM-FN-003`	`POST farm/cloud/merchant_statement/retry/:id`	`adminFarmCloudMerchantStatementRetry`	重试可恢复的执行失败
`ADM-FN-004`	`GET farm/cloud/reconciliation/lst`	`adminFarmCloudReconciliationLst`	对账差异
`ADM-FN-004`	`GET farm/cloud/reconciliation/detail/:id`	`adminFarmCloudReconciliationDetail`	订单、库存、账本和资金证据链
`ADM-FN-004`	`POST farm/cloud/reconciliation/preview/:id`	`adminFarmCloudReconciliationPreview`	生成修复或冲正预览
`ADM-FN-004`	`POST farm/cloud/reconciliation/review/:id`	`adminFarmCloudReconciliationReview`	审核或驳回修复方案
`ADM-FN-004`	`POST farm/cloud/reconciliation/execute/:id`	`adminFarmCloudReconciliationExecute`	执行已审核修复
`ADM-FN-004`	`POST farm/cloud/reconciliation/retry/:id`	`adminFarmCloudReconciliationRetry`	从失败步骤幂等重试

一张供货申请只允许一个来源 SKU；商户批量勾选时由前端分别建立草稿，后端仍逐张校验和提交。提交申请不修改来源商品库存；平台审核通过才建立 source_reserved_qty，验收后按真实数量转换为云仓库存，短缺、拒收、取消和退回必须走独立状态及数量流水。

送达、收货和质量验收不得合并成一个可任意改数的命令。商户先建立交付/发货事实，平台按 delivery_id 记录实际收货，再由验收单提交 accepted_qty、pending_inspection_qty、rejected_qty、仓位、证据、验收时间、version 和 request_id。已分配活动数量不得超过验收可用数量。响应至少返回完整数量链及三类责任方快照；页面按钮由 allowed_actions 决定，后端仍重新鉴权和验状态。

3. 首次订单、去向和批次

页面	方法与路径	拟定路由名	用途
`ADM-CW-007`	`GET farm/cloud/order/lst`	`adminFarmCloudOrderLst`	云仓首次订单
`ADM-CW-007`	`GET farm/cloud/order/detail/:id`	`adminFarmCloudOrderDetail`	首次交易、去向、补运费、履约和退款
`ADM-CW-007`	`GET farm/cloud/order/pending_choice`	`adminFarmCloudPendingChoiceLst`	待选择与超时预警
`ADM-CW-007`	`POST farm/cloud/order/remind_choice/:id`	`adminFarmCloudOrderRemindChoice`	幂等发送待选去向提醒
`ADM-CW-007`	`GET farm/cloud/pickup/lst`	`adminFarmCloudPickupLst`	待核销、自提逾期
`ADM-CW-007`	`POST farm/cloud/pickup/verify/:id`	`adminFarmCloudPickupVerify`	按 `verify_qty` 分次核销并返回累计/剩余量
`ADM-CW-007`	`POST farm/cloud/pickup/resolve/:id`	`adminFarmCloudPickupResolve`	逾期协商处理
`ADM-CW-008`	`GET farm/cloud/batch/lst`	`adminFarmCloudBatchLst`	批次列表
`ADM-CW-009`	`GET farm/cloud/batch/detail/:id`	`adminFarmCloudBatchDetail`	库存池、进度、持仓
`ADM-CW-009`	`GET farm/cloud/batch/flows/:id`	`adminFarmCloudBatchFlows`	库存与状态流水
`ADM-CW-009`	`POST farm/cloud/batch/freeze/:id`	`adminFarmCloudBatchFreeze`	异常冻结
`ADM-CW-009`	`POST farm/cloud/batch/resume/:id`	`adminFarmCloudBatchResume`	审核后恢复
`ADM-CW-010`	`GET farm/cloud/resale/lst`	`adminFarmCloudResaleLst`	二次零售分配
`ADM-CW-010`	`GET farm/cloud/resale/detail/:id`	`adminFarmCloudResaleDetail`	普通订单及批次拆分

批次页面的人工“重算”只能生成差异预览：

POST farm/cloud/batch/reconcile_preview/:id

确认修复必须使用独立权限：

POST farm/cloud/batch/reconcile_apply/:id

不得提供直接编辑 paid_qty、effective_sold_qty、remaining_qty 或用户余额的接口。

4. 用户账本、回购与异常

页面	方法与路径	拟定路由名	用途
`ADM-FN-002`	`GET farm/cloud/user_ledger/lst`	`adminFarmCloudUserLedgerLst`	用户本金/收益/回购账本
`ADM-FN-005`	`GET farm/cloud/user_ledger/detail/:id`	`adminFarmCloudUserLedgerDetail`	公式、快照和入账记录
`ADM-FN-002`	`POST farm/cloud/user_ledger/review`	`adminFarmCloudUserLedgerReview`	批量审核/驳回超阈值或异常账本
`ADM-FN-002`	`POST farm/cloud/user_ledger/execute`	`adminFarmCloudUserLedgerExecute`	触发已审核或自动阈值内账本入账
`ADM-FN-005`	`GET farm/cloud/financial_posting/detail/:id`	`adminFarmFinancialPostingDetail`	入账前后余额、CRMEB 流水和失败记录
`ADM-FN-002`	`POST farm/cloud/financial_posting/retry/:id`	`adminFarmFinancialPostingRetry`	重试可恢复的失败入账
`ADM-FN-002`	`POST farm/cloud/user_ledger/adjust/request`	`adminFarmCloudLedgerAdjustRequest`	发起冲正申请
`ADM-FN-002`	`POST farm/cloud/user_ledger/adjust/audit/:id`	`adminFarmCloudLedgerAdjustAudit`	财务审核冲正
`ADM-CW-011`	`GET farm/cloud/buyback/lst`	`adminFarmCloudBuybackLst`	到期回购列表
`ADM-CW-011`	`GET farm/cloud/buyback/preview/:batch_id`	`adminFarmCloudBuybackPreview`	回购计算预览
`ADM-CW-011`	`POST farm/cloud/buyback/prepare/:batch_id`	`adminFarmCloudBuybackPrepare`	固化回购预案和待回购库存
`ADM-CW-011`	`POST farm/cloud/buyback/review/:batch_id`	`adminFarmCloudBuybackReview`	审核或驳回预案
`ADM-CW-011`	`POST farm/cloud/buyback/execute/:batch_id`	`adminFarmCloudBuybackExecute`	原子执行已审核回购
`ADM-CW-011`	`POST farm/cloud/buyback/retry/:batch_id`	`adminFarmCloudBuybackRetry`	重试事务外可恢复步骤
`ADM-CW-012`	`GET farm/cloud/exception/lst`	`adminFarmCloudExceptionLst`	云仓异常
`ADM-CW-012`	`GET farm/cloud/exception/detail/:id`	`adminFarmCloudExceptionDetail`	事实、影响、处理历史和审计
`ADM-CW-012`	`POST farm/cloud/exception/create`	`adminFarmCloudExceptionCreate`	由平台基于云仓订单、履约、供货或批次事实创建异常
`ADM-CW-012`	`POST farm/cloud/exception/impact/recalculate/:id`	`adminFarmCloudExceptionImpactRecalculate`	重算订单、库存、持仓和账本影响
`ADM-CW-012`	`POST farm/cloud/exception/plan/create/:id`	`adminFarmCloudExceptionPlanCreate`	创建处理方案版本
`ADM-CW-012`	`POST farm/cloud/exception/plan/precheck/:plan_id`	`adminFarmCloudExceptionPlanPrecheck`	预检资金、库存和对象版本
`ADM-CW-012`	`POST farm/cloud/exception/plan/review/:plan_id`	`adminFarmCloudExceptionPlanReview`	审核或驳回方案
`ADM-CW-012`	`POST farm/cloud/exception/plan/execute/:plan_id`	`adminFarmCloudExceptionPlanExecute`	启动已审核方案
`ADM-CW-012`	`POST farm/cloud/exception/step/retry/:step_id`	`adminFarmCloudExceptionStepRetry`	重试失败步骤
`ADM-CW-012`	`POST farm/cloud/exception/close/:id`	`adminFarmCloudExceptionClose`	全部步骤和恒等式通过后关闭

账本异常入账、回购、结单和修复统一使用 prepared → pending_review → approved/rejected → executing → succeeded/partial_failed 语义。执行接口不得接受前端传入最终金额，只接受待执行记录 ID、版本和请求幂等键；正式金额、目标账户和 posting_key 均由后端从业务账本重算。V1 回购一律人工审核；普通用户账本和商户结单只有在规则零差异、无冻结/退款/争议且未超过自动阈值时才可跳过人工审核。

自动规则内账本/结单由任务调用同一个 Application Service；后台按钮不是另一套入账逻辑。已成功记录再次请求返回首次 posting_id、CRMEB 流水 ID 和完成时间，不能重复增加余额。

5. 商品农业资料与管理员农业范围

商品农业资料不建立第二套商品主档。平台和商户编辑的都是 CRMEB 商品的一对一扩展，商品名称、规格、售价和上下架仍由原商品接口负责。

页面/载体	方法与路径	用途
`ADM-CM-001/002`	`GET farm/agriculture/product_profile/detail/:product_id`	查看农业来源、产地、材料、溯源和审核历史
`ADM-CM-001`	`POST farm/agriculture/product_profile/save/:product_id`	保存平台自营商品农业资料草稿
`ADM-CM-001`	`POST farm/agriculture/product_profile/submit/:product_id`	提交平台自营商品资料审核
`ADM-CM-002`	`POST farm/agriculture/product_profile/review/:product_id`	通过或驳回平台/商户提交版本；审核人不得修改提交内容
现有管理员列表抽屉	`GET farm/support/admin_scope/options`	返回当前操作者可授权的业务域、农场和仓库树
现有管理员列表抽屉	`GET farm/support/admin_scope/detail/:admin_id`	查询目标管理员的显式农业范围和版本
现有管理员列表抽屉	`POST farm/support/admin_scope/save/:admin_id`	全量替换该管理员的农业范围，记录前后差异与审计

平台自营与商户商品资料都采用 draft → pending_review → approved/rejected → disabled；只有 approved 且材料有效的资料可以令 supply_eligible=true。重新提交递增当前资料版本，并在不可变审计日志保存提交前后快照；已产生订单和供货的历史快照不随当前资料变化。材料上传先走统一上传接口，保存草稿时只绑定附件 ID。

农业范围不写入现有管理员 region_ids 字符串。保存接口提交 version 和完整目标集合，事务内锁定该管理员当前有效范围，新增/停用差异行并写审计；不能把操作者自己无权授予的范围交给他人。超级管理员也保存显式 scope_type=all，避免业务查询散落特殊判断。

6. 农业资产、租地与认养

平台地图辅助接口：

方法与路径	用途	权限与约束
`GET farm/map/geocode`	按地址返回候选点位	平台登录 + `farm.map.geocode`，地址长度、频率和区域范围受限
`GET farm/map/reverse_geocode`	按点位返回结构化地址	平台登录 + `farm.map.reverse_geocode`，只接受 `GCJ02`
`GET farm/map/suggest`	地址关键词建议	平台登录 + `farm.map.suggest`，不作为无认证腾讯代理

统一响应示例：

{
  "provider": "tencent",
  "coordinate_system": "GCJ02",
  "items": [
    {
      "title": "示例农场",
      "address": "重庆市示例区示例路 1 号",
      "province_code": "500000",
      "city_code": "500100",
      "district_code": "500101",
      "longitude": "106.5500000",
      "latitude": "29.5600000"
    }
  ]
}

接口不透传供应商完整原始响应、Key、SK 或计费字段。农场和自提点写接口必须再次校验经纬度成对存在、范围合法、coordinate_system=GCJ02，不能信任地图辅助接口的旧结果。

通用主数据固定使用下列完整接口；不得在代码、测试或权限种子中使用省略后缀：

资源	列表	详情	创建	修改	状态
农场	`GET farm/agriculture/farm/lst`	`GET farm/agriculture/farm/detail/:id`	`POST farm/agriculture/farm/create`	`POST farm/agriculture/farm/update/:id`	`POST farm/agriculture/farm/status/:id`
区域	`GET farm/agriculture/zone/lst`	`GET farm/agriculture/zone/detail/:id`	`POST farm/agriculture/zone/create`	`POST farm/agriculture/zone/update/:id`	`POST farm/agriculture/zone/status/:id`
地块	`GET farm/agriculture/plot/lst`	`GET farm/agriculture/plot/detail/:id`	`POST farm/agriculture/plot/create`	`POST farm/agriculture/plot/update/:id`	`POST farm/agriculture/plot/status/:id`
自提点	`GET farm/agriculture/pickup_point/lst`	`GET farm/agriculture/pickup_point/detail/:id`	`POST farm/agriculture/pickup_point/create`	`POST farm/agriculture/pickup_point/update/:id`	`POST farm/agriculture/pickup_point/status/:id`
作物	`GET farm/agriculture/crop/lst`	`GET farm/agriculture/crop/detail/:id`	`POST farm/agriculture/crop/create`	`POST farm/agriculture/crop/update/:id`	`POST farm/agriculture/crop/status/:id`
栏舍/蜂场	`GET farm/agriculture/enclosure/lst`	`GET farm/agriculture/enclosure/detail/:id`	`POST farm/agriculture/enclosure/create`	`POST farm/agriculture/enclosure/update/:id`	`POST farm/agriculture/enclosure/status/:id`
仓库	`GET farm/agriculture/warehouse/lst`	`GET farm/agriculture/warehouse/detail/:id`	`POST farm/agriculture/warehouse/create`	`POST farm/agriculture/warehouse/update/:id`	`POST farm/agriculture/warehouse/status/:id`
库位	`GET farm/agriculture/warehouse_location/lst`	`GET farm/agriculture/warehouse_location/detail/:id`	`POST farm/agriculture/warehouse_location/create`	`POST farm/agriculture/warehouse_location/update/:id`	`POST farm/agriculture/warehouse_location/status/:id`
品种	`GET farm/agriculture/breed/lst`	`GET farm/agriculture/breed/detail/:id`	`POST farm/agriculture/breed/create`	`POST farm/agriculture/breed/update/:id`	`POST farm/agriculture/breed/status/:id`
动物资产	`GET farm/agriculture/animal/lst`	`GET farm/agriculture/animal/detail/:id`	`POST farm/agriculture/animal/create`	`POST farm/agriculture/animal/update/:id`	`POST farm/agriculture/animal/status/:id`
养殖批次	`GET farm/agriculture/breeding_batch/lst`	`GET farm/agriculture/breeding_batch/detail/:id`	`POST farm/agriculture/breeding_batch/create`	`POST farm/agriculture/breeding_batch/update/:id`	`POST farm/agriculture/breeding_batch/status/:id`

每条平台路由都必须设置唯一名称并在 system_menu 建立操作权限。批量导入使用“上传校验 → 错误预览 → 确认导入”三段式接口，禁止上传后直接落库。

动物资产导入接口固定为：

页面	方法与路径	用途
`ADM-AG-009`	`POST farm/agriculture/animal/import/validate`	提交已上传的 `system_attachment_id`、文件哈希和 `request_id`，创建校验异步操作；最多 1000 行，不写动物资产
`ADM-AG-009`	`GET farm/agriculture/animal/import/preview/:operation_no`	返回字段映射、通过/错误数、前 100 行脱敏预览和受控错误文件
`ADM-AG-009`	`POST farm/agriculture/animal/import/confirm/:operation_no`	校验操作已成功、零错误、文件哈希及目标农场版本未变后，创建确认异步操作并全批次原子导入

校验任务把附件绑定到校验操作并延长至终态后 7 天；确认任务重新读取同一文件并核对哈希，不能信任浏览器回传的预览行。任一行失败时整批不落动物资产，结果通过 GET farm/operation/detail/:operation_no 查询。

农业工作台和占用日历补充只读聚合接口：

页面	方法与路径	用途
`ADM-AG-001`	`GET farm/agriculture/dashboard`	当前角色可见的订单、生产、异常、履约和今日待办
`ADM-AG-007`	`GET farm/agriculture/plot/occupancy_calendar`	按农场、区域、地块和日期范围查询占用
`ADM-AG-007`	`GET farm/agriculture/plot/occupancy_detail/:id`	占用来源、订单、生产批次和冲突证据

页面	方法与路径	用途
`ADM-LA-002`	`GET farm/land/plan/lst`	租地套餐列表
`ADM-LA-003`	`POST farm/land/plan/create`	创建套餐草稿
`ADM-LA-003`	`POST farm/land/plan/update/:id`	修改草稿
`ADM-LA-003`	`POST farm/land/plan/publish/:id`	发布版本
`ADM-LA-004`	`GET farm/land/order/lst`	租地订单
`ADM-LA-005`	`GET farm/land/order/detail/:id`	权益、地块、生产、履约
`ADM-LA-006`	`GET farm/land/allocation/candidates/:order_id`	可分配地块
`ADM-LA-006`	`POST farm/land/allocation/reserve/:order_id`	建立 5 分钟地块预留并返回令牌
`ADM-LA-006`	`POST farm/land/allocation/confirm/:order_id`	使用预留令牌原子确认真实地块
`ADM-LA-006`	`POST farm/land/allocation/release/:order_id`	主动释放未确认预留
`ADM-AD-002`	`GET farm/adoption/plan/lst`	认养套餐
`ADM-AD-003`	`POST farm/adoption/plan/create`	创建套餐草稿
`ADM-AD-003`	`POST farm/adoption/plan/update/:id`	修改草稿
`ADM-AD-003`	`POST farm/adoption/plan/publish/:id`	发布版本
`ADM-AD-004`	`GET farm/adoption/order/lst`	认养订单
`ADM-AD-005`	`GET farm/adoption/order/detail/:id`	个体/份额、生产、履约
`ADM-AD-006`	`GET farm/adoption/allocation/candidates/:order_id`	可分配个体或份额
`ADM-AD-006`	`POST farm/adoption/allocation/reserve/:order_id`	建立 5 分钟资产/份额预留
`ADM-AD-006`	`POST farm/adoption/allocation/confirm/:order_id`	使用预留令牌原子确认
`ADM-AD-006`	`POST farm/adoption/allocation/release/:order_id`	主动释放未确认预留

7. 生产、产出、履约、溯源和异常

页面	方法与路径	用途
`ADM-PD-001`	`GET farm/production/batch/lst`	生产批次
`ADM-PD-002`	`GET farm/production/batch/detail/:id`	周期、事件、产出、关联订单
`ADM-PD-002`	`POST farm/production/batch/create`	创建计划批次及类型扩展草稿
`ADM-PD-002`	`POST farm/production/batch/update/:id`	修改尚未开始的批次
`ADM-PD-002`	`POST farm/production/batch/start/:id`	校验权益、占用和任务后开始生产
`ADM-PD-002`	`POST farm/production/batch/pause/:id`	因明确原因暂停并冻结相关自动任务
`ADM-PD-002`	`POST farm/production/batch/resume/:id`	预检通过后恢复
`ADM-PD-002`	`POST farm/production/batch/complete/:id`	产出、任务和异常闭合后完成
`ADM-PD-002`	`GET farm/task/lst`	生产批次详情内的农事、养殖、仓储和履约任务
`ADM-PD-002`	`GET farm/task/detail/:id`	要求快照、对象、分派和执行历史
`ADM-PD-002`	`POST farm/task/create`	创建任务
`ADM-PD-002`	`POST farm/task/assign/:id`	首次分派
`ADM-PD-002`	`POST farm/task/reassign/:id`	保留历史并转派
`ADM-PD-002`	`POST farm/task/cancel/:id`	取消未完成任务并记录原因
`ADM-PD-003`	`GET farm/production/event/review_lst`	待审核过程记录
`ADM-PD-003`	`POST farm/production/event/review/:id`	审核通过或驳回提交版本
`ADM-PD-003`	`POST farm/production/event/publish/:id`	发布已审核版本
`ADM-PD-003`	`POST farm/production/event/withdraw/:id`	撤回公开版本，不删除历史
`ADM-PD-004`	`GET farm/output/batch/lst`	采收/产出批次
`ADM-PD-005`	`GET farm/output/batch/detail/:id`	质量、库存、分配
`ADM-PD-005`	`POST farm/output/batch/quality/:id`	质量验收
`ADM-PD-005`	`POST farm/output/allocation/preview/:id`	按权益和可用量预演分配
`ADM-PD-005`	`POST farm/output/allocation/confirm/:id`	原子固化分配、库存流水和履约
`ADM-PD-005`	`POST farm/output/allocation/reconcile/:id`	生成差异预览，不直接改汇总
`ADM-PD-006`	`GET farm/fulfillment/lst`	农业履约
`ADM-PD-006`	`GET farm/fulfillment/detail/:id`	地址版本、明细、包裹、运费和售后
`ADM-PD-006`	`POST farm/fulfillment/create`	从产出分配生成履约
`ADM-PD-006`	`POST farm/fulfillment/package/:id`	生成或更新未发货包裹
`ADM-PD-006`	`POST farm/fulfillment/ship/:id`	复用 CRMEB 物流能力发货
`ADM-PD-006`	`POST farm/fulfillment/cancel/:id`	取消未出库部分并回退产出库存
`ADM-PD-007`	`GET farm/exception/lst`	农业异常
`ADM-PD-008`	`GET farm/exception/detail/:id`	事实、证据、影响订单和处理历史
`ADM-PD-008`	`POST farm/exception/impact/recalculate/:id`	重算影响对象、数量和金额
`ADM-PD-008`	`POST farm/exception/plan/create/:id`	创建不可覆盖的方案版本
`ADM-PD-008`	`POST farm/exception/plan/precheck/:plan_id`	预检库存、资金、资产和对象版本
`ADM-PD-008`	`POST farm/exception/plan/review/:plan_id`	审核或驳回方案
`ADM-PD-008`	`POST farm/exception/plan/execute/:plan_id`	启动已审核方案的分步执行
`ADM-PD-008`	`POST farm/exception/step/retry/:step_id`	使用原结果键重试失败步骤
`ADM-PD-008`	`POST farm/exception/close/:id`	全部必需步骤和恒等式通过后关闭
`ADM-TR-001`	`GET farm/trace/archive/lst`	溯源档案
`ADM-TR-002`	`GET farm/trace/archive/detail/:id`	当前版本与材料
`ADM-TR-002`	`POST farm/trace/archive/create`	为生产/产出对象建立唯一档案
`ADM-TR-002`	`POST farm/trace/version/save/:archive_id`	保存草稿版本
`ADM-TR-002`	`POST farm/trace/version/submit/:id`	提交草稿版本审核
`ADM-TR-002`	`POST farm/trace/version/review/:id`	审核通过或驳回
`ADM-TR-002`	`POST farm/trace/version/publish/:id`	发布
`ADM-TR-002`	`POST farm/trace/version/withdraw/:id`	撤回
`ADM-TR-003`	`GET farm/trace/material/lst`	报告与证书列表、有效期预警
`ADM-TR-003`	`POST farm/trace/material/create`	上传报告/证书及结构化元数据
`ADM-TR-003`	`POST farm/trace/material/update/:id`	修改未发布材料元数据
`ADM-TR-003`	`POST farm/trace/material/status/:id`	作废或恢复材料
`ADM-TR-004`	`GET farm/trace/link/lst`	商品/SKU/订单/批次关联列表
`ADM-TR-004`	`POST farm/trace/link`	关联商品/SKU/订单/批次
`ADM-TR-004`	`POST farm/trace/unlink/:id`	在权限和引用校验后解除关联

五、商户端 API 目录

0. 商品农业资料

页面	方法与路径	用途
`MER-CM-001/002`	`GET farm/catalog/product_agriculture/detail/:product_id`	当前商户商品的农业资料、材料、审核结果和历史
`MER-CM-002`	`POST farm/catalog/product_agriculture/save/:product_id`	保存农业资料草稿和已上传材料 ID
`MER-CM-002`	`POST farm/catalog/product_agriculture/submit/:product_id`	完整性校验后提交平台审核

商品必须属于当前商户；商户不能自行设置 supply_eligible、审核状态或当前溯源发布状态。已通过资料被修改后回到草稿，原活动、供货和订单快照保持不变。

1. 供货申请

页面	方法与路径	拟定路由名	用途
`MER-CW-001`	`GET farm/cloud/supply/lst`	`merchantFarmCloudSupplyLst`	本商户申请记录
`MER-CW-002`	`GET farm/cloud/supply/product_candidates`	`merchantFarmCloudSupplyCandidates`	可申请商品/SKU
`MER-CW-002`	`GET farm/cloud/supply/detail/:id`	`merchantFarmCloudSupplyDetail`	草稿或审核详情
`MER-CW-002`	`POST farm/cloud/supply/create`	`merchantFarmCloudSupplyCreate`	创建草稿
`MER-CW-002`	`POST farm/cloud/supply/update/:id`	`merchantFarmCloudSupplyUpdate`	修改草稿/驳回单
`MER-CW-002`	`POST farm/cloud/supply/submit/:id`	`merchantFarmCloudSupplySubmit`	提交平台审核
`MER-CW-003`	`GET farm/cloud/supply/records`	`merchantFarmCloudSupplyRecords`	验收、占用和活动记录
`MER-CW-004`	`GET farm/cloud/supply/data/:id`	`merchantFarmCloudSupplyData`	数量生命周期、首次销售、退款和责任快照
`MER-CW-004`	`GET farm/cloud/supply/delivery/lst/:supply_id`	`merchantFarmCloudSupplyDeliveryLst`	分批交付和平台收货状态
`MER-CW-004`	`POST farm/cloud/supply/delivery/create/:supply_id`	`merchantFarmCloudSupplyDeliveryCreate`	按尚可交付数量创建交付草稿
`MER-CW-004`	`POST farm/cloud/supply/delivery/update/:delivery_id`	`merchantFarmCloudSupplyDeliveryUpdate`	修改未发运交付草稿
`MER-CW-004`	`POST farm/cloud/supply/delivery/dispatch/:delivery_id`	`merchantFarmCloudSupplyDeliveryDispatch`	固化交付数量、物流和发运证据
`MER-CW-004`	`POST farm/cloud/supply/delivery/cancel/:delivery_id`	`merchantFarmCloudSupplyDeliveryCancel`	取消未发运草稿，不释放供货申请本身
`MER-CW-004`	`GET farm/cloud/supply/inspection/lst/:supply_id`	`merchantFarmCloudSupplyInspectionLst`	查看平台收货、待检和验收证据
`MER-CW-004`	`GET farm/cloud/supply/return/lst/:supply_id`	`merchantFarmCloudSupplyReturnLst`	查看退回、平台承接和来源库存恢复
`MER-CW-004`	`POST farm/cloud/supply/return/acknowledge/:return_id`	`merchantFarmCloudSupplyReturnAcknowledge`	确认收到退回实物或提交差异
`MER-CW-005`	`GET farm/cloud/fulfillment/lst`	`merchantFarmCloudFulfillmentLst`	约定由商户处理的履约/售后
`MER-CW-005`	`GET farm/cloud/fulfillment/detail/:id`	`merchantFarmCloudFulfillmentDetail`	履约、地址脱敏、责任、物流和售后详情
`MER-CW-005`	`POST farm/cloud/fulfillment/ship/:id`	`merchantFarmCloudFulfillmentShip`	提交承运商、运单和发货证据
`MER-CW-005`	`POST farm/cloud/fulfillment/logistics/:id`	`merchantFarmCloudFulfillmentLogistics`	更正未锁定物流信息
`MER-CW-005`	`POST farm/cloud/fulfillment/evidence/:id`	`merchantFarmCloudFulfillmentEvidence`	补充质量、打包或交接证据
`MER-CW-005`	`POST farm/cloud/fulfillment/return_receive/:id`	`merchantFarmCloudFulfillmentReturnReceive`	确认退回实物及验收结果
`MER-CW-005`	`POST farm/cloud/fulfillment/exception/:id`	`merchantFarmCloudFulfillmentException`	上报无法履约、短缺或质量异常

商户创建供货申请时不得修改商品所有权、商品当前库存或活动规则。一张申请只允许一个来源 SKU；批量选择仅创建多张互相独立的草稿。提交字段包括来源商品、SKU、供货价、拟供数量、交付方式、预计验收时间、证明材料，以及商户建议的运费、质量和售后责任方。平台审核确认后的三类责任方以供货快照为准，历史订单不得随商品资料变化。

列表和详情必须显式展示“拟供 → 审批 → 来源预留 → 送达 → 待检 → 验收/拒收/短缺 → 活动占用/云仓可用 → 退回或平台承接”的数量链。所有可点击动作均由响应 allowed_actions 控制显示；前端隐藏按钮不能替代后端权限、商户边界、状态和版本校验。

交付请求只允许引用本供货申请尚未交付的数量，不接受客户端修改供货价和责任快照。dispatch 后数量不可直接覆盖；平台收货差异进入收货/验收记录。退回确认发生争议时只改变退回任务为异常状态，不得自动恢复来源商品可售库存。

2. 商户货款

页面	方法与路径	拟定路由名	用途
`MER-FN-001`	`GET farm/cloud/merchant_ledger/lst`	`merchantFarmCloudLedgerLst`	本商户供货货款
`MER-FN-001`	`GET farm/cloud/merchant_ledger/detail/:id`	`merchantFarmCloudLedgerDetail`	数量、单价、扣减与状态
`MER-FN-002`	`GET farm/cloud/merchant_statement/lst`	`merchantFarmCloudStatementLst`	结算单
`MER-FN-002`	`GET farm/cloud/merchant_statement/detail/:id`	`merchantFarmCloudStatementDetail`	结单汇总、明细和入账流水
`MER-FN-002`	`GET farm/cloud/merchant_statement/export/:id`	`merchantFarmCloudStatementExport`	导出已生成结算单
`MER-FN-001`	`POST farm/cloud/merchant_ledger/dispute/:id`	`merchantFarmCloudLedgerDispute`	对未入单货款提交异议
`MER-FN-002`	`POST farm/cloud/merchant_statement/dispute/:id`	`merchantFarmCloudStatementDispute`	对结单及其明细提交异议
`MER-FN-002`	`GET farm/cloud/merchant_statement/adjustment/lst`	`merchantFarmCloudStatementAdjustmentLst`	查看差异调整、冲正和再次入账结果

所有查询强制追加当前 mer_id，不得接受前端传入其他商户 ID 作为数据边界。

V1 商户结单由平台每日 02:00 自动生成，商户不能自行提前入账、拆单、合单或修改金额。对账异议只冻结尚未入账记录；已入账差异进入独立调整和反向入账流程。商户详情必须能追到 farm_supply_settlement 财务记录、CRMEB 可用余额变动和后续原有转账/提现能力，不能把“结单生成”误写成资金已到账。

六、用户端云仓 API

1. 公开查询

方法与路径	鉴权	用途
`GET farm/cloud/activity/current`	可选登录	当前、预热和最近结束活动
`GET farm/cloud/activity/:id/products`	可选登录	活动商品和 SKU 批次
`GET farm/cloud/product/:activity_product_id`	可选登录	商品详情和规则
`GET farm/cloud/batch/:batch_id/rule`	可选登录	下单前规则快照预览
`GET farm/cloud/config`	可选登录	开关、默认说明和协议版本

登录用户可额外返回本人限购已用数量；未登录用户不得返回任何持仓或订单数据。

2. 抢购校验

POST farm/cloud/order/check

{
  "batch_id": "82001",
  "quantity": "2.000",
  "request_id": "7b906c21-1e8b-43f8-91b1-523e377fd6b1"
}

响应：

{
  "check_key": "cw-check-opaque-token",
  "expires_at": "2026-08-01 10:10:00",
  "activity": {
    "activity_id": "301",
    "name": "八月云仓专场",
    "end_at": "2026-08-05 23:59:59"
  },
  "sku": {
    "batch_id": "82001",
    "title": "生态鸡蛋 30 枚",
    "quantity": "2.000",
    "purchase_unit_price": "59.90"
  },
  "amounts": {
    "goods_amount": "119.80",
    "freight_amount": "0.00",
    "pay_amount": "119.80"
  },
  "choice": {
    "supports_shipping": true,
    "supports_pickup": true,
    "supports_consign": true,
    "choice_deadline_at": "2026-08-08 23:59:59"
  },
  "rule_snapshot": {},
  "pay_modes": ["wechat", "alipay", "balance"]
}

校验时读取活动 SKU 独立库存，不直接扣减。返回的 check_key 有效期建议 10 分钟，并绑定用户、批次、数量、规则版本和价格。

3. 创建订单

POST farm/cloud/order/create

{
  "check_key": "cw-check-opaque-token",
  "pay_type": "wechat",
  "protocol_version": "CW-2026-08-01",
  "request_id": "a52a2e2e-2bf0-4b22-abfc-0ae2437ac25f"
}

响应：

{
  "group_order_id": "98621",
  "order_id": "98635",
  "order_product_id": "100812",
  "cloud_order_item_id": "42001",
  "pay_amount": "119.80",
  "pay_deadline_at": "2026-08-01 10:15:00",
  "next_action": "pay"
}

事务必须同时完成：

条件扣减云仓批次可抢购库存并写库存流水。
创建 CRMEB 订单组、订单和订单明细。
创建 eb_farm_order_binding，策略固定为 cloud_primary + farm_managed + deferred_choice。
创建 eb_farm_cloud_order_item，状态为待付款。
保存价格、规则、协议和来源快照。
写入业务幂等结果和 farm.cloud.order.created Outbox。

创建成功后使用 CRMEB 现有 POST order/pay/:group_order_id 发起支付。支付成功事务内只确认订单绑定、首次明细付款事实并写 Outbox；复杂状态推进、通知和结算由幂等消费者执行。

云仓首次订单不创建普通商户锁定款、普通订单净收入或分销佣金。供应商货款按供货价和首次有效购买规则进入云仓供货账本，不能按用户抢购实付金额走普通商户结算。

3.1 普通商城二次代销结算边界

用户购买 cloud_only 映射 SKU 时继续使用 CRMEB 普通购物车、确认订单和支付 API，但必须遵守：

普通订单创建事务在订单明细落库后执行 FEFO 云仓分配，失败时整张订单和普通 SKU 扣减一起回滚。
一个 group_order_id 不得混合普通库存商品与 farm_managed 云仓代销商品；确认接口必须拆成不同订单组，当前端不能可靠表达多组支付时返回 CW_CART_FINANCE_POLICY_MIXED 并提示分别结算。
二次代销订单付款后不创建普通商户锁定款；实付金额与平台券补贴分别写入云仓销售计算快照。
cloud_only SKU 在 V1 不允许进入代客下单、积分商城或其他营销活动入口。
支付、取消和退款接口响应保持 CRMEB 现有外壳，业务查询通过 farm_order_binding 判断并返回对应 next_action。

4. 支付成功页与订单中心

方法与路径	用途
`GET farm/cloud/order/pay_result/:group_order_id`	支付结果轮询及下一步
`GET farm/cloud/order/lst`	云仓订单中心
`GET farm/cloud/order/detail/:cloud_order_item_id`	一条首次明细详情
`GET farm/cloud/order/action_count`	待付款、待选择、补运费、自提、异常数量

支付成功页按 next_action 决定“继续抢购”“立即选择”或“查看订单”。不得仅根据前端支付 SDK 回调认定支付成功。

5. 去向预览

POST farm/cloud/order_item/:id/disposition/preview

{
  "disposition": "shipping",
  "address_id": "991",
  "pickup_point_id": "",
  "version": 4
}

响应根据去向返回：

shipping：地址快照、运费模板、运费金额、是否包邮和支付超时。
pickup：自提点、开放时间、最晚核销时间和联系方式。
consign：批次开始时间、预计到期、结算模式、分成和回购规则。

邮寄预览额外返回 quote_hash 和 quote_version。确认邮寄时必须原样提交；服务端仍会重新计算并验证，客户端不得提交或覆盖运费金额。预览不改变最终去向。

6. 确认去向

POST farm/cloud/order_item/:id/disposition/confirm

{
  "disposition": "consign",
  "address_id": "",
  "pickup_point_id": "",
  "quote_hash": "",
  "version": 4,
  "request_id": "f1335bc8-e32d-4f7b-9122-1907f9fe5586"
}

处理规则：

去向	结果
代销	全量创建待入批次持仓，最终去向立即生效
自提	全量生成自提履约和核销凭证，最终去向立即生效
邮寄且包邮	全量生成邮寄履约，最终去向立即生效
邮寄且需补运费	创建/复用补运费单，首次明细保持待选择，返回 `next_action=pay_freight`

禁止提交数量字段，服务端始终使用本明细全部有效数量。

7. 补运费

方法与路径	用途
`GET farm/cloud/freight/detail/:freight_order_id`	补运费单
`POST farm/cloud/freight/pay/:freight_order_id`	发起支付
`GET farm/cloud/freight/pay_result/:freight_order_id`	查询结果
`POST farm/cloud/freight/cancel/:freight_order_id`	选择期内取消未支付运费单
`GET farm/cloud/freight/refund_result/:freight_order_id`	迟到支付或关联首次退款的运费退款结果

发起支付请求：

{
  "pay_type": "routine",
  "return_url": "",
  "request_id": "fb074ef2-c3bf-4c62-967f-7cfba4fdb290"
}

服务端只接受当前终端和 CRMEB 配置已启用的 weixin、routine、h5、alipay、App 对应渠道及 balance。V1 拒绝线下支付、扫码枪、组合支付和商户子账户支付。金额、用户、订单号、attach 和地址快照一律从运费单读取，不接受客户端覆盖。

在线支付响应：

{
  "freight_order_id": 8021,
  "freight_order_no": "CF20260730000001",
  "pay_type": "routine",
  "pay_price": "12.00",
  "pay_status": "paying",
  "expires_at": "2026-07-30 21:30:00",
  "config": {},
  "next_action": "wait_pay_result"
}

余额支付成功时可直接返回 business_status=shipping_confirmed 和 next_action=view_fulfillment。在线支付后前端必须轮询 pay_result，不得用支付 SDK 返回值直接确认邮寄。

pay_result 的 next_action：

本地状态	`next_action`	用户端处理
未支付/支付中	`wait_pay_result`	继续短轮询，超时后允许返回订单中心
邮寄已确认	`view_fulfillment`	进入履约详情
已超时且仍可选择	`choose_again`	返回去向选择
已超时且已自动代销	`view_holding`	查看云仓持仓
迟到支付/退款处理中	`wait_refund`	展示原路退款处理中
已退款	`refund_completed`	展示退款金额和时间
异常	`contact_service`	展示异常编号，不重复发起支付

补运费成功事务：

幂等确认支付事实。
校验规范化回调金额、渠道交易号和订单明细选择版本。
固化地址和运费快照。
将首次明细最终去向设为邮寄。
创建履约单。
写状态、Outbox 和必要库存流水。

支付回调使用固定 attach=farm_cloud_freight。expired_at 固定为“运费单创建时间加活动支付超时”和“去向选择截止”的较早值；到点先取消未成功运费单，仍在选择期则返回待选择，否则自动转代销。截止后收到渠道成功回调时记录迟到支付，不改变去向，自动创建整单全额退款。

取消请求必须包含当前 version 和 request_id，且只允许本人取消未支付、未超时、未进入成功回调事务的当前运费单。切换支付渠道时由服务端取消旧单并生成新运费单号。

8. 首次退款、自提与持仓

方法与路径	用途
`POST farm/cloud/order_item/:id/refund/check`	判断整条首次明细能否退款
`POST farm/cloud/order_item/:id/refund/apply`	编排 CRMEB 全量退款申请
`GET farm/cloud/pickup/voucher/:id`	自提凭证
`GET farm/cloud/pickup/verification/lst/:id`	本人查看分次核销历史和剩余量
`GET farm/cloud/holding/lst`	我的云仓
`GET farm/cloud/holding/detail/:id`	持仓、进度和规则
`GET farm/cloud/holding/progress/:id`	25/50/75/100 节点
`GET farm/cloud/user_ledger/lst`	本人云仓账本
`GET farm/cloud/user_ledger/detail/:id`	本人账本详情

首次退款接口只允许全量，不接受 refund_qty。批次已开始时返回 CW_PRIMARY_REFUND_WINDOW_CLOSED。

GET farm/cloud/holding/progress/:id 必须区分真实销售进度和最近已结节点：

{
  "batch_effective_sold_qty": "80",
  "consign_qty": "100.000",
  "sold_equivalent_qty": "32.000000",
  "unsold_equivalent_qty": "8.000000",
  "progress_rate": "80.0000",
  "settlement_mode": "profit_and_principal_by_milestone",
  "last_settled_milestone": 75,
  "crossed_milestones": [25, 50, 75],
  "next_milestone": 100,
  "cumulative_principal_due": "320.00",
  "cumulative_profit_due": "89.60",
  "posted_amount": "409.60",
  "pending_amount": "0.00",
  "normal_refund_offset_amount": "0.00",
  "platform_risk_absorbed_amount": "0.00",
  "calculation_version": 3
}

一次从 20% 跳到 80% 时，后台只生成一组 milestone=75 的累计差额账本，金额按真实 80% 计算；接口不得把真实进度截断成 75%，也不得伪造三笔节点收益。

七、用户端租地、认养与溯源 API

1. 公开目录

方法与路径	用途
`GET farm/agriculture/home`	农场专区聚合
`GET farm/agriculture/farm/lst`	可展示农场
`GET farm/agriculture/farm/detail/:id`	农场、区域和公开内容
`GET farm/agriculture/farm/location/:id`	农场公开点位、地址、示意图和导航能力
`GET farm/land/plan/lst`	可租套餐
`GET farm/land/plan/detail/:id`	套餐、作物、承诺和规则
`GET farm/adoption/plan/lst`	可认养套餐
`GET farm/adoption/plan/detail/:id`	分配模式、产出和规则
`GET farm/trace/public/:archive_no`	公开溯源档案
`GET farm/trace/qrcode/:archive_no`	稳定二维码内容

公开接口只返回已发布版本、可售容量和对用户可见记录。

农场位置响应使用固定坐标契约：

{
  "farm_id": "1001",
  "farm_name": "示例农场",
  "public_address": "重庆市示例区示例路 1 号",
  "longitude": "106.5500000",
  "latitude": "29.5600000",
  "coordinate_system": "GCJ02",
  "schematic_image": {
    "url": "https://example.invalid/farm-map.jpg"
  },
  "navigation_enabled": true
}

公开接口不返回服务端地图 Key、详细内部地址、联系人原值或地块、栏舍、仓库的内部精确坐标。农场点位缺失时不应处于公开状态；历史数据异常时返回地址和示意图，并令 navigation_enabled=false。

2. 租地下单

方法与路径	用途
`POST farm/land/order/check`	校验套餐、作物、容量和金额
`POST farm/land/order/create`	使用 `check_key` 创建 CRMEB 交易及租地扩展单
`GET farm/land/order/pay_result/:group_order_id`	支付与分配状态
`GET farm/land/order/lst`	我的土地
`GET farm/land/order/detail/:id`	地块、生产、产出和履约

校验请求：

{
  "plan_id": "2201",
  "crop_id": "118",
  "quantity": "1.000",
  "contact_address_id": "991",
  "request_id": "8ef348ca-18fa-48ad-a42b-ef0e0fc69538"
}

check 返回绑定用户、套餐、作物、数量、价格、容量版本和协议版本的 check_key，默认有效 10 分钟；它只校验容量，不锁定具体地块。创建请求只提交 check_key、pay_type、protocol_version 和新的 request_id，成功后复用 CRMEB POST order/pay/:group_order_id。

支付成功后进入“待分配”，地块分配可以同步完成，也可异步进入工作台。接口不得在支付前承诺尚未锁定的具体坐标。

contact_address_id 仅生成合同联系信息快照和默认联系人，不代表未来产出已经确认寄往该地址。产出达到可履约状态后，用户在 USR-PD-001 再次确认当前邮寄地址；服务端重新生成地址快照和运费报价，避免长周期内地址变更造成误寄。

3. 认养下单

方法与路径	用途
`POST farm/adoption/order/check`	校验套餐和可分配容量
`POST farm/adoption/order/create`	使用 `check_key` 创建交易及认养扩展单
`GET farm/adoption/order/pay_result/:group_order_id`	支付与分配状态
`GET farm/adoption/order/lst`	我的认养
`GET farm/adoption/order/detail/:id`	个体/份额、生产、产出和履约

认养 check/create/pay_result 与租地使用同一协议：check_key 绑定用户、套餐、分配模式、数量、价格、容量版本和协议版本，创建成功后复用 CRMEB 支付入口。支付成功后只承诺按套餐分配；具体个体或批次份额由原子分配事务确认。

单体认养详情返回真实资产编号；批次份额详情返回批次和份额，不返回虚构个体编号。

4. 产出邮寄

方法与路径	用途
`GET farm/fulfillment/lst`	本人租地/认养履约
`GET farm/fulfillment/detail/:id`	本次产出、地址和物流
`POST farm/fulfillment/address/preview/:id`	预览地址快照、支持范围和运费规则
`POST farm/fulfillment/address/confirm/:id`	固化本次履约地址版本
`POST farm/fulfillment/freight/check/:id`	生成绑定地址版本的报价令牌
`POST farm/fulfillment/freight/create/:id`	以报价令牌创建独立农业运费单
`GET farm/fulfillment/freight/detail/:freight_order_id`	查看金额、有效期和支付状态
`POST farm/fulfillment/freight/pay/:freight_order_id`	支付本次运费
`GET farm/fulfillment/freight/pay_result/:freight_order_id`	查询支付、迟到退款和履约状态
`POST farm/fulfillment/freight/cancel/:freight_order_id`	取消未支付当前运费单
`GET farm/fulfillment/package/lst/:id`	查看分包数量和物流轨迹
`POST farm/fulfillment/take/:id`	确认收货
`POST farm/fulfillment/refund/check/:id`	未履约部分售后校验
`POST farm/fulfillment/refund/apply/:id`	按后端可退数量申请退款
`GET farm/fulfillment/refund/result/:id`	查询退款和权益闭合结果
`GET farm/exception/plan/detail/:plan_id`	本人查看关联租地/认养订单的异常方案、等价校验、确认截止和超时结果
`POST farm/exception/plan/confirm/:plan_id`	本人接受或拒绝待确认方案，不允许提交替代金额或修改步骤

下单时地址仅作为默认联系信息。每次分批产出发货前必须让用户确认或更换地址，形成该履约单独立地址快照。接口返回 split_reason 和 freight_payer：平台因生产节奏主动分批或包邮套餐不得向用户追加运费；用户主动拆包、升级配送或改变到套餐范围外地址时，才可在确认报价后创建补运费单。

未履约退款校验响应必须返回 promised_qty、delivered_qty、refunded_unfulfilled_qty、max_refundable_qty、service_refund_base_amount、delivery_refund_base_amount、cumulative_refund_due、historical_refund_amount、pending_refund_amount 和本次由后端计算的 current_refund_amount。客户端只提交申请数量、原因、证据和订单版本，不提交最终退款金额。

八、服务/现场端 API

所有路径都位于现有 /ser 服务端前缀下。现有 ServiceTokenMiddleware 负责身份；只有登录与本人 farm/context 只经过 Token 校验，其他农业业务路由再经过 FarmServicePermissionMiddleware。领域 Repository 必须使用 FarmServiceScopeRepository 限定查询或断言对象范围。客服只能查看被授权商户或平台范围，现场人员只能操作分配给自己的农场、区域、仓库、批次、履约或任务。

1. 工作区上下文

页面	方法与路径	权限	用途
`SVC-AU-001`	`POST login`	未登录 + 现有验证码规则	复用现有服务人员登录并签发 `service` Token
`SVC-AU-002/003`	`GET farm/context`	仅有效 `ServiceToken`	返回工作区、职责、权限、范围摘要、默认入口和 `scope_version`
`SVC-AU-003`	`GET farm/me`	仅有效 `ServiceToken`	返回当前人员资料、启用状态、联系方式脱敏值和工作区偏好

响应示例：

{
  "service": {
    "service_id": 12,
    "nickname": "现场人员",
    "merchant_id": 0
  },
  "workspaces": ["farm_work"],
  "default_workspace": "farm_work",
  "duties": ["crop_operator"],
  "permissions": [
    "farm.task.read",
    "farm.scan.resolve",
    "farm.production.event.write",
    "farm.exception.report"
  ],
  "scope_summary": {
    "farm_count": 1,
    "area_count": 2,
    "task_only": false
  },
  "scope_version": 7,
  "features": {
    "camera_scan": true,
    "image_scan": true,
    "local_draft": true,
    "embedded_map": true
  },
  "map": {
    "provider": "tencent",
    "client_key": "[runtime-client-key]",
    "coordinate_system": "GCJ02"
  }
}

client_key 仅为受域名白名单限制的浏览器展示 Key，不是服务端 WebService Key/SK；未配置时返回空值并令 embedded_map=false。上下文不返回可被客户端拿来扩大权限的 SQL 条件。前端发现 SERVICE_SCOPE_CHANGED 时重新加载上下文；后端不能因为客户端仍携带旧 scope_version 而接受越权请求。

2. 客服协同

页面	方法与路径	权限码	用途
`SVC-CM-001`	`GET farm/order/search`	`farm.order.read`	按用户、手机号、业务号检索
`SVC-CM-001`	`GET farm/order/detail/:type/:id`	`farm.order.read`	租地/认养综合详情
`SVC-CW-001`	`GET farm/cloud/order/search`	`farm.cloud.order.read`	云仓首次订单检索
`SVC-CW-001`	`GET farm/cloud/order/detail/:id`	`farm.cloud.order.read`	去向、持仓、批次和账本只读
`SVC-CW-002`	`GET farm/cloud/exception/lst`	`farm.exception.read`	待协同异常
`SVC-CW-002`	`GET farm/cloud/exception/detail/:id`	`farm.exception.read`	事实、动作、通知和审计
`SVC-CW-002`	`POST farm/cloud/exception/propose/:id`	`farm.exception.propose`	提交处理建议
`SVC-CW-002`	`POST farm/cloud/pickup/verify/:id`	`farm.pickup.verify`	有仓储/核销范围时核销
`SVC-CW-002`	`POST farm/cloud/pickup/overdue/:id`	`farm.exception.propose`	记录继续提货/改寄/回购建议

客服不得直接修改账本金额、批次进度或用户余额。

3. 现场作业

页面	方法与路径	权限码	用途
`SVC-PD-001`	`GET farm/task/lst`	`farm.task.read`	我的今日/逾期任务
`SVC-PD-001`	`GET farm/task/detail/:id`	`farm.task.read`	对象、时间、要求和版本
`SVC-PD-001`	`POST farm/task/start/:id`	`farm.task.execute`	本人接受并开始待执行任务
`SVC-PD-001`	`POST farm/task/complete/:id`	`farm.task.execute`	校验必需记录、数量和证据后完成任务
`SVC-PD-002`	`POST farm/scan/resolve`	`farm.scan.resolve`	解析并验签地块/资产/批次/履约二维码
`SVC-PD-003`	`POST farm/production/event/create`	`farm.production.event.write`	保存过程记录草稿
`SVC-PD-003`	`POST farm/production/event/submit/:id`	`farm.production.event.write`	提交本人记录审核
`SVC-PD-004`	`POST farm/output/batch/create`	`farm.output.write`	录入采收/产出
`SVC-PD-004`	`POST farm/output/batch/submit/:id`	`farm.output.write`	提交质量验收
`SVC-PD-003`	`POST farm/asset/health/create`	`farm.asset.health.write`	健康/防疫记录
`SVC-PD-005`	`POST farm/warehouse/receive/:task_id`	`farm.warehouse.receive`	入库验收
`SVC-PD-005`	`POST farm/fulfillment/pack/:task_id`	`farm.fulfillment.pack`	拣货与打包
`SVC-PD-005`	`POST farm/fulfillment/ship/:task_id`	`farm.fulfillment.ship`	出库与运单
`SVC-PD-005`	`POST farm/cloud/pickup/verify/:id`	`farm.pickup.verify`	从现场任务进入云仓自提核销；复用 `CW_PICKUP_VERIFY`，不另建农业产出自提接口
`SVC-PD-006`	`POST farm/exception/create`	`farm.exception.report`	异常上报
`SVC-PD-006`	`POST farm/exception/evidence/:id`	`farm.exception.report`	补充本人异常证据
`SVC-PD-003~006`	`POST farm/attachment/upload`	`farm.evidence.upload`	上传图片/文件并取得短期可绑定附件 ID
`SVC-PD-007`	`GET farm/review/lst`	`farm.production.review` 或 `farm.output.review`	按范围查询待审核、已审核和退回记录
`SVC-PD-007`	`GET farm/review/detail/:type/:id`	对应审核权限	内容、数量方程、证据和历史版本
`SVC-PD-007`	`POST farm/production/review/:id`	`farm.production.review`	审核或驳回过程记录
`SVC-PD-007`	`POST farm/output/review/:id`	`farm.output.review`	审核或驳回产出记录

附件上传使用 multipart/form-data，除文件外必须提交 task_id、scope_object_type、scope_object_id 和 request_id。成功响应只返回可绑定的业务附件：

{
  "farm_evidence_attachment_id": "88101",
  "attachment_no": "FEA202608010001",
  "preview_url": "https://example.invalid/signed-preview",
  "mime_type": "image/jpeg",
  "file_size": 183024,
  "status": "temporary",
  "expires_at": "2026-08-03 12:00:00"
}

当前通用客服 Service::upload() 只返回 URL，不能满足业务绑定和清理契约；农业接口复用其底层 UploadService，但写入 eb_farm_evidence_attachment 并返回 farm_evidence_attachment_id。该字段不能作为 eb_system_attachment.attachment_id 使用；preview_url 只用于展示，不作为业务提交凭证。

扫码接口使用 POST，因为完整原始码可能包含签名且不应进入 URL、代理日志和浏览器历史。现场新增记录允许本机离线草稿，但 V1 不提供服务端草稿 CRUD：SVC-PD-008 使用 IndexedDB 按服务账号、业务对象和 schema 版本保存 JSON 与 Blob，登出只清当前账号敏感缓存，草稿恢复后仍需重新校验范围和对象版本；浏览器无法持久保存媒体时明确要求重新选择文件。服务端最终提交使用 request_id 幂等，媒体先上传取得附件 ID，再提交业务记录。上传接口校验文件类型、大小、当前账号和业务对象范围，未绑定附件定时清理。每个写请求同时提交当前对象 version，版本变化返回 COMMON_VERSION_CONFLICT。

4. 权限与范围执行顺序

Token 有效
→ `farm/context` 可读取本人工作区
→ 农业档案启用
→ route permission_code 命中
→ 商户上限未越界
→ 对象可见且沿归属链落入有效 scope
→ 对象状态、版本和任务分配允许
→ 执行业务事务

列表接口先套用范围再分页；详情越界统一返回 COMMON_NOT_FOUND，避免泄露对象存在性，内部审计可记录诊断码 SERVICE_SCOPE_DENIED，但不得把它返回给客户端。明确登录且对象可见、但缺少动作权限时返回 SERVICE_PERMISSION_DENIED。只有请求携带的 scope_version 已过期且尚未进入具体对象解析时才返回 SERVICE_SCOPE_CHANGED；一旦按 ID 解析对象，越界仍返回 COMMON_NOT_FOUND。所有详情响应返回 allowed_actions；前端只按它展示按钮，提交时后端仍按“Token → 权限 → 商户上限 → 对象范围 → 状态/版本/任务 → 事务”全链路复核。

九、内部接口与事件边界

以下能力不暴露给普通前端：

内部命令	触发来源	结果
`cloud.order.paid`	CRMEB `paySuccess` 事务内 `FarmOrderPaymentAdapter`	首次明细转已付款待选择
`cloud.order.primary_refunded`	退款完成适配器	释放首次库存并冲减货款
`cloud.order.primary_completed`	收货/核销/入批次	计算商户结算资格时间
`cloud.supply.approve`	平台供货审核	锁定单一来源 SKU 库存并建立责任快照
`cloud.activity.inventory_close`	活动结束且未支付订单已关闭	释放未抢数量，按来源生成平台退回、商户退回待办或平台承接
`cloud.supply.dispatch`	商户确认发运	固化交付事实和证据，不修改验收数量
`cloud.supply.receive`	平台实际收货	记录收货、短少并生成待检数量
`cloud.supply.inspect`	质量验收完成	转换合格、拒收和云仓库存
`cloud.supply.release_or_return`	取消、未交付、活动退回或平台承接	按实物状态释放来源预留、退回或转平台库存
`cloud.batch.freeze_choices`	选择截止任务	自动代销、冻结批次数量
`cloud.resale.allocate`	普通订单锁库存	按最早到期批次分配
`cloud.resale.effective`	普通订单完成且过观察期	计有效销售与进度
`cloud.resale.reverse`	二次退款	释放或冲减分配
`cloud.ledger.generate`	节点/到期任务	生成差额账本
`cloud.batch.maturity_finalize`	在途处置宽限截止	停止新分配后固化所有权切割、整数未售量和平台承接在途量
`cloud.user_ledger.post`	用户账本校验通过	锁定用户账户，写余额、余额流水和统一入账记录
`cloud.merchant_statement.generate`	每日结单任务	按商户归集上一自然日已具资格的供货账本
`cloud.merchant_statement.post`	结单自动校验或人工复核通过	锁定商户账户，写可用余额、财务流水和统一入账记录
`cloud.financial_posting.reverse`	调整单审核通过	生成独立借方入账；余额不足转待追偿
`cloud.buyback.execute`	到期审核命令	转平台库存并生成回购款
`land.order.paid`	支付成功适配器	建立租地业务单并分配
`adoption.order.paid`	支付成功适配器	建立认养业务单并分配
`farm.allocation.reserve`	平台分配页锁定候选	建立 5 分钟地块或认养资产预留
`farm.allocation.confirm`	使用有效预留令牌确认	原子占用容量、保留历史并写 Outbox
`farm.output.allocate`	合格产出确认或修复任务	按权益顺序分配产出并创建履约
`farm.exception.user_confirm`	受影响用户接受、拒绝或确认超时	写不可变确认事实并选择执行或未履约退款分支
`farm.exception.execute_step`	已审核异常方案	逐步执行替换、补发、延期、退款或恢复
`farm.delivery_refund.calculate`	生产开始后的未履约退款预检/执行	按交付退款基数和累计未履约数量计算本次退款差额
`farm.trace.publish`	已审核溯源版本	原子发布版本、更新公开指针并写 Outbox

内部事件的生产者、消费者、重试和任务频率见 20-v1-events-jobs-permissions-notifications.md。

十、业务错误码

1. 通用

错误码	含义	是否可重试
`COMMON_VALIDATION_FAILED`	参数校验失败	否
`COMMON_NOT_FOUND`	数据不存在或不可见	否
`COMMON_FORBIDDEN`	无权限	否
`COMMON_VERSION_CONFLICT`	数据版本已变化	刷新后可
`COMMON_IDEMPOTENCY_CONFLICT`	同一幂等键请求内容不同	否
`COMMON_BUSY`	资源正在处理	稍后可
`COMMON_DEPENDENCY_FAILED`	支付、物流、存储等依赖失败	视返回而定
`COMMON_ATTACHMENT_INVALID`	附件不存在、已删除、用途不符或 ID 域错误	否
`COMMON_ATTACHMENT_SCOPE_DENIED`	附件不属于当前平台/商户/服务人员或目标对象范围	否
`COMMON_ASYNC_NOT_READY`	异步操作尚未产生当前动作需要的预览、令牌或结果	轮询后可

2. 云仓

错误码	含义
`CW_ACTIVITY_NOT_STARTED`	活动未开始
`CW_ACTIVITY_ENDED`	活动已结束
`CW_ACTIVITY_CLOSED`	活动已关闭
`CW_STOCK_INSUFFICIENT`	活动 SKU 库存不足
`CW_SUPPLY_SINGLE_SKU_REQUIRED`	一张供货申请只能绑定一个来源 SKU
`CW_PLATFORM_SOURCE_NOT_SELF_OPERATED`	平台供货所选商品不属于 `is_trader=1` 的平台自营商户
`CW_SUPPLY_SOURCE_STOCK_INSUFFICIENT`	审核时来源可预留库存不足
`CW_SUPPLY_QUANTITY_CONFLICT`	送达、验收、拒收、短缺、占用或退回数量不闭合
`CW_SUPPLY_ALREADY_ALLOCATED`	数量已被活动占用，不能直接释放或退回
`CW_SUPPLY_DISPOSITION_CONFLICT`	同一剩余供货数量已被退回、承接或其他处置占用
`CW_SUPPLY_ACQUISITION_REVIEW_REQUIRED`	平台承接尚未由独立复核人批准或预检已失效
`CW_SUPPLY_RESPONSIBILITY_DENIED`	当前商户不是该履约/售后动作的责任方
`CW_FULFILLMENT_LOGISTICS_LOCKED`	包裹已签收、进入售后或物流事实已锁定，不能直接更正
`CW_FULFILLMENT_RETURN_QTY_CONFLICT`	退回实收、短少、待检或已恢复数量不闭合
`CW_LIMIT_EXCEEDED`	超过用户限购
`CW_RULE_CHANGED`	校验后规则版本变化
`CW_ORDER_ALREADY_CREATED`	当前请求已生成订单
`CW_ORDER_NOT_PAID`	首次订单未支付
`CW_CART_FINANCE_POLICY_MIXED`	普通商品与云仓代销商品需分别结算
`CW_CHOICE_NOT_AVAILABLE`	当前状态不可选择去向
`CW_CHOICE_ALREADY_FINAL`	去向已最终确定
`CW_CHOICE_DEADLINE_PASSED`	已过选择截止时间
`CW_SHIPPING_NOT_SUPPORTED`	商品不支持邮寄
`CW_PICKUP_NOT_SUPPORTED`	商品不支持自提
`CW_FREIGHT_PAYMENT_PENDING`	补运费未完成
`CW_FREIGHT_PAY_TYPE_UNSUPPORTED`	当前终端或系统未启用该支付方式
`CW_FREIGHT_ORDER_EXPIRED`	运费单已超时，需重新选择或已自动代销
`CW_FREIGHT_AMOUNT_MISMATCH`	渠道回调金额与本地应付金额不一致
`CW_FREIGHT_PAYMENT_CONFLICT`	同一运费单出现冲突渠道交易事实
`CW_FREIGHT_LATE_PAYMENT_REFUNDING`	迟到支付已进入全额退款
`CW_FREIGHT_REFUND_PENDING`	运费退款仍在处理
`CW_PICKUP_OVERDUE`	自提已逾期
`CW_PICKUP_VERIFY_QTY_INVALID`	本次核销量不大于零或超过剩余可提数量
`CW_PICKUP_REMAINDER_ACTION_REQUIRED`	部分核销后的剩余数量需要继续保留、改寄、退款或异常回购
`CW_PRIMARY_REFUND_WINDOW_CLOSED`	已进入正式代销批次
`CW_BATCH_NOT_READY`	批次条件未满足
`CW_BATCH_FROZEN`	批次异常冻结
`CW_MATURITY_GRACE_ACTIVE`	批次已到期但在途处置宽限尚未结束
`CW_OWNERSHIP_CUTOVER_COMPLETED`	所有权切割已完成，当前动作不能再改变用户未售数量
`CW_EQUIVALENT_QTY_INVARIANT_FAILED`	批次实物数量与持仓等价数量恒等式不成立
`CW_LEDGER_ALREADY_SETTLED`	账本已结算
`CW_LEDGER_NOT_ELIGIBLE`	账本尚未达到正式入账条件
`CW_POSTING_IN_PROGRESS`	相同入账正在处理中，可稍后查询
`CW_POSTING_FAILED_RETRYABLE`	入账失败且可使用原幂等键重试
`CW_POSTING_AMOUNT_OVER_LIMIT`	超过自动入账阈值，需人工复核
`CW_POSTING_BALANCE_CAPACITY`	目标余额字段容量或应用上限不足
`CW_REVERSAL_RECOVERY_PENDING`	冲正余额不足，已进入待追偿
`CW_RECONCILIATION_REQUIRED`	数据差异需人工复核
`CW_BUYBACK_REVIEW_REQUIRED`	回购预案尚未人工审核
`CW_BUYBACK_PRECHECK_CHANGED`	审核后批次、持仓或库存事实已变化，需重新计算
`CW_ACTIVITY_INVENTORY_NOT_CLOSED`	未支付释放或活动未抢库存尚未闭合

3. 租地、认养和生产

错误码	含义
`LA_PLAN_NOT_AVAILABLE`	租地套餐不可售
`LA_CAPACITY_INSUFFICIENT`	可分配面积不足
`LA_PLOT_CONFLICT`	地块周期冲突
`AD_PLAN_NOT_AVAILABLE`	认养套餐不可售
`AD_ASSET_UNAVAILABLE`	个体资产不可分配
`AD_SHARE_INSUFFICIENT`	批次份额不足
`FARM_RESERVATION_EXPIRED`	地块、个体或份额预留已过期
`FARM_RESERVATION_TOKEN_INVALID`	预留令牌与订单或当前预留不匹配
`FARM_ALLOCATION_CONFLICT`	确认时容量、周期或对象版本已变化
`FARM_PLAN_VALUE_SPLIT_INVALID`	生产服务价值与交付价值之和不等于套餐价格
`FARM_IMPORT_ROW_LIMIT_EXCEEDED`	动物资产导入超过 1000 行
`FARM_IMPORT_VALIDATION_FAILED`	导入文件存在字段、编号、对象范围或业务校验错误
`FARM_IMPORT_SOURCE_CHANGED`	校验后的附件哈希、字段映射或目标农场/栏舍版本已变化
`FARM_MATERIAL_SET_INVALID`	商品当前必需材料缺失、未审核、未生效或已失效
`PD_OUTPUT_INSUFFICIENT`	合格产出不足
`PD_EVENT_ALREADY_PUBLISHED`	已发布记录不可原地修改
`PD_EXCEPTION_PLAN_STALE`	异常方案预检后受影响事实已变化
`PD_EXCEPTION_USER_CONFIRM_REQUIRED`	异常方案需受影响用户确认后才能执行
`PD_EXCEPTION_CONFIRM_EXPIRED`	用户确认截止已过并已按超时策略处理
`PD_REPLACEMENT_NOT_EQUIVALENT`	替换对象不满足规则快照中的完全等价条件
`PD_DELAY_TOLERANCE_EXCEEDED`	延期超过套餐快照允许的容忍天数
`PD_REFUND_QTY_EXCEEDED`	申请退款数量超过当前最大未履约可退数量
`PD_SHORTAGE_ALLOCATION_CHANGED`	减产/短缺分配预览依赖的订单或数量版本已变化
`PD_EXCEPTION_STEP_FAILED`	方案执行步骤失败，需按原结果键重试或重做方案
`TR_VERSION_CONFLICT`	溯源发布版本冲突
`TR_ARCHIVE_NOT_PUBLISHED`	无公开发布版本

4. 服务/现场端

错误码	含义	前端处理
`SERVICE_FARM_PROFILE_DISABLED`	农业工作区未启用或已停用	返回原客服入口或退出
`SERVICE_PERMISSION_DENIED`	当前职责不包含该动作	无权限页，不重试提交
`SERVICE_SCOPE_CHANGED`	职责或范围版本已变化	重新加载 `farm/context`
`SERVICE_TASK_REASSIGNED`	任务已转派给其他人员	刷新任务并保留未提交草稿
`SERVICE_SCAN_INVALID`	二维码格式、签名或对象无效	允许重新扫描/手工输入
`SERVICE_SCAN_UNSUPPORTED`	当前码类型不支持	提示联系管理员
`SERVICE_DRAFT_OWNER_MISMATCH`	本机草稿不属于当前账号	不展示草稿内容
`SERVICE_MEDIA_PENDING`	仍有证据文件未上传完成	保留草稿并继续上传
`SERVICE_ATTACHMENT_INVALID`	文件类型、大小、内容或摘要不合法	保留草稿并重新选择文件
`SERVICE_ATTACHMENT_SCOPE_DENIED`	上传对象或任务不在当前范围	停止上传并刷新任务/上下文
`SERVICE_ATTACHMENT_EXPIRED`	临时附件已过期或被清理	重新上传后提交
`SERVICE_ATTACHMENT_ALREADY_BOUND`	附件已绑定其他业务记录	不复用旧 ID，检查重复提交结果

对象越界对外统一使用 COMMON_NOT_FOUND；SERVICE_SCOPE_DENIED 只允许作为服务端审计和监控诊断码。这样既保留排错能力，也不会向无权账号泄露对象存在性。

5. 地图

错误码	含义	前端处理
`MAP_NOT_CONFIGURED`	当前环境未配置所需地图能力	保留地址/表单，提示配置；不显示默认假点位
`MAP_INVALID_COORDINATE`	坐标缺项、越界或格式错误	定位到经纬度字段，修正后重试
`MAP_COORDINATE_SYSTEM_UNSUPPORTED`	坐标系不是 `GCJ02`	拒绝保存，不在前端猜测转换
`MAP_PROVIDER_UNAVAILABLE`	地图供应商超时、5xx 或响应异常	显示重试、手工坐标和地址降级
`MAP_QUOTA_EXCEEDED`	当前 Key 额度或频率受限	停止自动重试，提示配置人员处理

十一、权限与隐私约束

平台财务金额、用户账本和商户货款必须使用独立操作权限。
平台管理端先校验 CRMEB 路由权限，再由 FarmAdminScopeRepository 按管理员、业务域和农场/仓库范围约束列表与对象；超级管理员的全平台访问也解析为显式 all 范围。
商户接口始终按当前 mer_id 限定，不能仅依赖前端隐藏。
用户订单、持仓、账本和履约必须同时校验 uid。
服务端搜索手机号时默认脱敏；查看完整信息需单独权限并记操作日志。
服务端路由权限与对象数据范围必须分别校验；前端 permissions 只控制显示，不能替代后端。
商户服务人员的最大范围固定为自身 mer_id，平台授权记录不能把商户账号提升为跨商户账号。
溯源公开接口不得返回内部备注、成本、联系人隐私和未发布材料。
导出接口记录申请人、筛选条件、文件、下载次数和失效时间。

平台数据范围与高风险权限相互独立：拥有某农场的数据范围不代表可以执行财务入账、回购审核、库存修复或溯源发布；拥有某操作路由但没有目标对象范围时，列表为空、详情按不存在处理。范围授权本身使用独立管理权限并写审计。

十二、第三方能力调用原则

能力	V1 处理
支付	复用 CRMEB 支付渠道与回调；为补运费增加独立业务支付类型适配
物流	复用 CRMEB 快递、电子面单和物流查询；农业分批履约通过业务履约单关联
地图	V1 统一腾讯地图和 GCJ02；复用客户端 `tx_map_key`，新增仅后端可见的 WebService Key/SK；地理编码走 `FarmMapService`，地块精细边界使用示意图而非 GIS 多边形
文件存储	复用 CRMEB `UploadService` 的本地/对象存储驱动；平台素材继续使用原附件库，现场证据写 `eb_farm_evidence_attachment` 后以附件 ID 原子绑定业务记录
二维码	生成端复用小程序码/二维码能力；现场 H5 使用开源 `@zxing/browser` 识别摄像头/图片，后端统一解析、验签和范围校验，手工输入为强制降级
短信/微信消息	复用现有消息渠道，新增业务模板和发送记录
设备/传感器	不进入 V1 核心交易链；后续通过设备适配层接入，不直接写生产主表

地图调用补充规则：

浏览器/小程序展示 Key 与服务端 WebService Key/SK 分离，真实值不进入文档、日志和接口响应。
服务端开启 TLS 校验，连接超时 2 秒、总超时 5 秒，仅对超时和 5xx 重试 1 次。
地理编码和逆地址可按规范化输入短期缓存；不得把失败转换为 0,0。
用户端农场导航使用已保存的目标点位，不以用户授权当前定位作为页面前置条件。
地图加载失败不能阻断订单、履约、扫码和现场记录；地址、示意图、复制与手工输入是必备降级。

十三、接口评审检查表

每个页面操作是否有唯一接口或明确复用入口。
每个写接口是否定义权限、状态前置条件、版本和幂等键。
每个金额是否由服务端计算，是否有规则快照。
每个库存变化是否有条件更新和不可变流水。
每个支付结果是否以后端回调/主动查询为准。
每个异步动作是否返回当前状态、任务号和查询入口。
每个错误是否有稳定错误码。
每个商户/用户/服务接口是否有数据归属校验。
每个列表是否有分页上限和索引支持。
每个导出、批量结算和重算是否采用异步任务。
API、数据表、状态机、页面编号和测试用例是否能一一追踪。

十四、当前冻结结论

云仓首次抢购固定一单一活动 SKU；租地/认养一次创建一个套餐业务明细。用户需要不同去向或套餐时分别下单。
云仓首次购买关闭平台券、商户券、积分、会员价和分销佣金，只复用现有支付方式，确保用户本金快照唯一；平台券仅可能出现在后续普通商城二次零售，并由平台承担。
用户云仓正式入账、补运费支付载体、服务端身份/双入口、地图和现场证据附件边界均已有源码或专项验证依据。
低保真评审可以调整页面组合和文案，但不得绕过上述交易、库存、权限和历史快照边界。

19 v1 api contract draft

V1 API 契约草案

一、设计结论

1. 接口分域

2. 与 CRMEB 的边界

3. V1 下单粒度

二、统一协议

1. 响应包

2. 分页、排序与筛选

3. 数据格式

4. 列表摘要与详情

5. 乐观锁

6. 幂等

6.1 HTTP 写接口

6.2 支付与退款回调

6.3 事件与定时任务

7. 统一异步操作查询

三、通用请求对象

1. PageQuery

2. RuleSnapshot

3. AllowedActions

4. FinancialPostingCommand

5. CloudFreightPaySuccessCommand

四、平台端 API 目录

1. 云仓活动与活动商品

2. 供货、验收与商户货款

3. 首次订单、去向和批次

4. 用户账本、回购与异常

5. 商品农业资料与管理员农业范围

6. 农业资产、租地与认养

7. 生产、产出、履约、溯源和异常

五、商户端 API 目录

0. 商品农业资料

1. 供货申请

2. 商户货款

六、用户端云仓 API

1. 公开查询

2. 抢购校验

3. 创建订单

3.1 普通商城二次代销结算边界

4. 支付成功页与订单中心

5. 去向预览

6. 确认去向

7. 补运费

8. 首次退款、自提与持仓

七、用户端租地、认养与溯源 API

1. 公开目录

2. 租地下单

3. 认养下单

4. 产出邮寄

八、服务/现场端 API

1. 工作区上下文

2. 客服协同

3. 现场作业

4. 权限与范围执行顺序

九、内部接口与事件边界

十、业务错误码

1. 通用

2. 云仓

3. 租地、认养和生产

4. 服务/现场端

5. 地图

十一、权限与隐私约束

十二、第三方能力调用原则

十三、接口评审检查表

十四、当前冻结结论

十五、关联文档

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

1. `PageQuery`

2. `RuleSnapshot`

3. `AllowedActions`

4. `FinancialPostingCommand`

5. `CloudFreightPaySuccessCommand`