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 枚举。是否需要核心订单增加通用业务标识，须在代码蓝图评审时以最小影响方案确认。
普通二次零售仍走 CRMEB 原订单接口；云仓通过内部库存分配和订单事件建立二次零售关联。

3. V1 下单粒度建议

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

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

这是技术设计建议，正式冻结前应作为 G3 评审项确认。租地和认养也建议一单一套餐，普通商城订单不受影响。

二、统一协议

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.500"`
比例	使用基点整数，`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 只提供短时请求锁，不能替代业务幂等。下列命令必须同时提交：

Header：Idempotency-Key
Body：request_id

两者可使用同一 UUID。服务端以“操作类型 + 操作主体 + 业务对象 + request_id”建立唯一约束，重复请求返回第一次成功结果。

必须幂等的命令包括：

创建抢购订单、租地订单、认养订单。
支付成功回调和支付结果补偿。
用户确认去向、创建补运费单、补运费成功。
自动转代销、创建持仓、启动批次。
二次零售分配、生效、退款释放和冲减。
进度节点账本、用户入账、商户货款、回购和冲正。
地块/资产分配、产出分配和履约创建。

三、通用请求对象

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",
  "expected_sale_days": 30,
  "user_profit_rate_bp": 6500,
  "platform_profit_rate_bp": 3500,
  "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"
  ]
}

四、平台端 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/publish/:id`	`adminFarmCloudActivityPublish`	校验并发布
`ADM-CW-002`	`POST farm/cloud/activity/close/:id`	`adminFarmCloudActivityClose`	关闭未开始/异常活动
`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/resale_map/:id`	`adminFarmCloudActivitySkuResaleMap`	绑定 `cloud_only` 二次销售 SKU
`ADM-CW-004`	`GET farm/cloud/activity/chart/:id`	`adminFarmCloudActivityChart`	活动数据面板

活动发布前必须校验：

每个 SKU 对应唯一云仓批次草稿。
每个活动 SKU 有独立稳定 ID，并保存来源规格值和 unique 快照。
活动库存不超过已验收可用量。
抢购价、供货价、预计周期、分成、结算模式和回购规则完整。
用户与平台利润分成基点合计等于 10000。
回购比例在 (0,10000]。
代销固定开启；邮寄和自提所需配置完整。
活动开始、结束、选择截止和代销到期时间顺序正确。
二次销售映射 SKU 的库存来源为 cloud_only，不得与普通库存混合。
发布后影响历史订单的规则字段不可直接覆盖，只能关闭或创建新活动。

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

页面	方法与路径	拟定路由名	用途
`ADM-CW-005`	`GET farm/cloud/supply/lst`	`adminFarmCloudSupplyLst`	供货申请列表
`ADM-CW-005`	`GET farm/cloud/supply/detail/:id`	`adminFarmCloudSupplyDetail`	商品、SKU、价格和材料
`ADM-CW-005`	`POST farm/cloud/supply/audit/:id`	`adminFarmCloudSupplyAudit`	审核通过/驳回
`ADM-CW-005`	`POST farm/cloud/supply/accept/:id`	`adminFarmCloudSupplyAccept`	入库/等价验收
`ADM-CW-005`	`POST farm/cloud/supply/freeze/:id`	`adminFarmCloudSupplyFreeze`	质量或库存冻结
`ADM-FN-003`	`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_ledger/settle`	`adminFarmCloudMerchantLedgerSettle`	批量生成结算
`ADM-FN-004`	`GET farm/cloud/reconciliation/lst`	`adminFarmCloudReconciliationLst`	对账差异

验收命令必须提交 accepted_qty、仓位/等价验收说明、证据文件、验收时间和版本。已分配活动数量不得超过验收可用数量。

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

页面	方法与路径	拟定路由名	用途
`ADM-CW-006`	`GET farm/cloud/order/lst`	`adminFarmCloudOrderLst`	云仓首次订单
`ADM-CW-006`	`GET farm/cloud/order/detail/:id`	`adminFarmCloudOrderDetail`	首次交易、去向、退款
`ADM-CW-007`	`GET farm/cloud/order/pending_choice`	`adminFarmCloudPendingChoiceLst`	待选择与超时预警
`ADM-CW-008`	`GET farm/cloud/pickup/lst`	`adminFarmCloudPickupLst`	待核销、自提逾期
`ADM-CW-008`	`POST farm/cloud/pickup/verify/:id`	`adminFarmCloudPickupVerify`	平台核销
`ADM-CW-008`	`POST farm/cloud/pickup/resolve/:id`	`adminFarmCloudPickupResolve`	逾期协商处理
`ADM-CW-009`	`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/settle`	`adminFarmCloudUserLedgerSettle`	自动校验通过或人工审核后的批量入账
`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/execute/:batch_id`	`adminFarmCloudBuybackExecute`	回购、转库存、生成账本
`ADM-CW-012`	`GET farm/cloud/exception/lst`	`adminFarmCloudExceptionLst`	云仓异常
`ADM-CW-012`	`POST farm/cloud/exception/resolve/:id`	`adminFarmCloudExceptionResolve`	处理并留痕

账本入账和回购执行必须支持“预览 → 审核 → 执行”，执行接口不得接受前端传入最终金额，只接受待执行记录 ID 和版本。

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

通用主数据使用下列接口形态：

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

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

页面	方法与路径	用途
`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/confirm/: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/confirm/:order_id`	确认分配

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

页面	方法与路径	用途
`ADM-PD-001`	`GET farm/production/batch/lst`	生产批次
`ADM-PD-002`	`GET farm/production/batch/detail/:id`	周期、事件、产出、关联订单
`ADM-PD-003`	`GET farm/production/event/review_lst`	待审核过程记录
`ADM-PD-003`	`POST farm/production/event/audit/: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-006`	`GET farm/fulfillment/lst`	农业履约
`ADM-PD-006`	`POST farm/fulfillment/create`	从产出分配生成履约
`ADM-PD-006`	`POST farm/fulfillment/delivery/:id`	复用物流能力发货
`ADM-PD-007`	`GET farm/exception/lst`	农业异常
`ADM-PD-007`	`POST farm/exception/audit/:id`	审核处理方案
`ADM-PD-007`	`POST farm/exception/resolve/:id`	执行并关闭
`ADM-TR-001`	`GET farm/trace/archive/lst`	溯源档案
`ADM-TR-002`	`GET farm/trace/archive/detail/:id`	当前版本与材料
`ADM-TR-002`	`POST farm/trace/version/save/:archive_id`	保存草稿版本
`ADM-TR-003`	`POST farm/trace/version/audit/:id`	审核
`ADM-TR-003`	`POST farm/trace/version/publish/:id`	发布
`ADM-TR-003`	`POST farm/trace/version/withdraw/:id`	撤回
`ADM-TR-004`	`POST farm/trace/link`	关联商品/SKU/订单/批次

五、商户端 API 目录

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-005`	`GET farm/cloud/fulfillment/lst`	`merchantFarmCloudFulfillmentLst`	约定由商户处理的履约/售后

商户创建供货申请时不得修改商品所有权、商品当前库存或活动规则。提交字段包括来源商品、SKU、供货价、拟供数量、交付方式、预计验收时间和证明材料。

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/export/:id`	`merchantFarmCloudStatementExport`	导出已生成结算单
`MER-FN-001`	`POST farm/cloud/merchant_ledger/exception/:id`	`merchantFarmCloudLedgerException`	提交对账异议

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

六、用户端云仓 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_cloud_order_item，状态为待付款。
保存价格、规则、协议和来源快照。
写入业务幂等结果。

创建成功后使用 CRMEB 现有 POST order/pay/:group_order_id 发起支付。支付成功通过内部事件把首次明细转为“已付款待选择”，不在支付回调里直接执行复杂结算。

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：批次开始时间、预计到期、结算模式、分成和回购规则。

预览不改变最终去向。

6. 确认去向

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

{
  "disposition": "consign",
  "address_id": "",
  "pickup_point_id": "",
  "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`	选择期内取消未支付运费单

补运费成功事务：

幂等确认支付事实。
固化地址和运费快照。
将首次明细最终去向设为邮寄。
创建履约单。
写状态和库存流水。

运费支付超时但仍在选择期，取消临时邮寄并返回待选择；超过选择截止时间，自动转代销。

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/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。

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

1. 公开目录

方法与路径	用途
`GET farm/agriculture/home`	农场专区聚合
`GET farm/agriculture/farm/lst`	可展示农场
`GET farm/agriculture/farm/detail/: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`	稳定二维码内容

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

2. 租地下单

方法与路径	用途
`POST farm/land/order/check`	校验套餐、作物、容量和金额
`POST farm/land/order/create`	创建 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",
  "protocol_version": "LAND-2026-08-01",
  "request_id": "8ef348ca-18fa-48ad-a42b-ef0e0fc69538"
}

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

3. 认养下单

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

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

4. 产出邮寄

方法与路径	用途
`GET farm/fulfillment/lst`	本人租地/认养履约
`GET farm/fulfillment/detail/:id`	本次产出、地址和物流
`POST farm/fulfillment/address/:id`	发货前确认地址
`POST farm/fulfillment/freight/check/:id`	如需运费则计算
`POST farm/fulfillment/freight/pay/:id`	支付本次运费
`POST farm/fulfillment/take/:id`	确认收货
`POST farm/fulfillment/refund/check/:id`	未履约部分售后校验

下单时地址作为默认联系信息。每次分批产出发货前允许用户重新确认地址，避免长期项目使用过期地址。

八、服务/现场端 API

现有服务端没有平台/商户式菜单权限，V1 需在 token 身份之外增加 service_scope 校验。客服只能查看被授权商户或平台范围，现场人员只能操作分配给自己的农场、批次或任务。

1. 客服协同

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

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

2. 现场作业

页面	方法与路径	用途
`SVC-PD-001`	`GET farm/task/lst`	我的今日/逾期任务
`SVC-PD-001`	`GET farm/task/detail/:id`	对象、时间和要求
`SVC-PD-002`	`GET farm/scan/resolve`	解析地块/资产/批次二维码
`SVC-PD-003`	`POST farm/production/event/create`	保存过程记录草稿
`SVC-PD-003`	`POST farm/production/event/submit/:id`	提交审核
`SVC-PD-004`	`POST farm/output/batch/create`	录入采收/产出
`SVC-PD-004`	`POST farm/output/batch/submit/:id`	提交质量验收
`SVC-PD-005`	`POST farm/asset/health/create`	健康/防疫记录
`SVC-PD-006`	`POST farm/exception/create`	异常上报
`SVC-PD-006`	`POST farm/exception/evidence/:id`	补充证据

现场新增记录允许离线草稿，但服务端最终提交仍以 request_id 幂等；媒体先上传取得文件 ID，再提交业务记录。

九、内部接口与事件边界

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

内部命令	触发来源	结果
`cloud.order.paid`	CRMEB `order.paySuccess` 适配器	首次明细转已付款待选择
`cloud.order.primary_refunded`	退款完成适配器	释放首次库存并冲减货款
`cloud.order.primary_completed`	收货/核销/入批次	计算商户结算资格时间
`cloud.batch.freeze_choices`	选择截止任务	自动代销、冻结批次数量
`cloud.resale.allocate`	普通订单锁库存	按最早到期批次分配
`cloud.resale.effective`	普通订单完成且过观察期	计有效销售与进度
`cloud.resale.reverse`	二次退款	释放或冲减分配
`cloud.ledger.generate`	节点/到期任务	生成差额账本
`cloud.buyback.execute`	到期审核命令	转平台库存并生成回购款
`land.order.paid`	支付成功适配器	建立租地业务单并分配
`adoption.order.paid`	支付成功适配器	建立认养业务单并分配

内部事件的生产者、消费者、重试和任务频率见 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`	支付、物流、存储等依赖失败	视返回而定

2. 云仓

错误码	含义
`CW_ACTIVITY_NOT_STARTED`	活动未开始
`CW_ACTIVITY_ENDED`	活动已结束
`CW_ACTIVITY_CLOSED`	活动已关闭
`CW_STOCK_INSUFFICIENT`	活动 SKU 库存不足
`CW_LIMIT_EXCEEDED`	超过用户限购
`CW_RULE_CHANGED`	校验后规则版本变化
`CW_ORDER_ALREADY_CREATED`	当前请求已生成订单
`CW_ORDER_NOT_PAID`	首次订单未支付
`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_PICKUP_OVERDUE`	自提已逾期
`CW_PRIMARY_REFUND_WINDOW_CLOSED`	已进入正式代销批次
`CW_BATCH_NOT_READY`	批次条件未满足
`CW_BATCH_FROZEN`	批次异常冻结
`CW_LEDGER_ALREADY_SETTLED`	账本已结算
`CW_RECONCILIATION_REQUIRED`	数据差异需人工复核

3. 租地、认养和生产

错误码	含义
`LA_PLAN_NOT_AVAILABLE`	租地套餐不可售
`LA_CAPACITY_INSUFFICIENT`	可分配面积不足
`LA_PLOT_CONFLICT`	地块周期冲突
`AD_PLAN_NOT_AVAILABLE`	认养套餐不可售
`AD_ASSET_UNAVAILABLE`	个体资产不可分配
`AD_SHARE_INSUFFICIENT`	批次份额不足
`PD_OUTPUT_INSUFFICIENT`	合格产出不足
`PD_EVENT_ALREADY_PUBLISHED`	已发布记录不可原地修改
`TR_VERSION_CONFLICT`	溯源发布版本冲突
`TR_ARCHIVE_NOT_PUBLISHED`	无公开发布版本

十一、权限与隐私约束

平台财务金额、用户账本和商户货款必须使用独立操作权限。
商户接口始终按当前 mer_id 限定，不能仅依赖前端隐藏。
用户订单、持仓、账本和履约必须同时校验 uid。
服务端搜索手机号时默认脱敏；查看完整信息需单独权限并记操作日志。
溯源公开接口不得返回内部备注、成本、联系人隐私和未发布材料。
导出接口记录申请人、筛选条件、文件、下载次数和失效时间。

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

能力	V1 处理
支付	复用 CRMEB 支付渠道与回调；为补运费增加独立业务支付类型适配
物流	复用 CRMEB 快递、电子面单和物流查询；农业分批履约通过业务履约单关联
地图	复用当前腾讯地图配置；地块精细边界 V1 可先使用后台上传示意图/坐标点
文件存储	复用 CRMEB 本地/对象存储适配，业务表保存附件 ID 与快照
二维码	复用小程序码/二维码能力，二维码只保存稳定档案号或短链
短信/微信消息	复用现有消息渠道，新增业务模板和发送记录
设备/传感器	不进入 V1 核心交易链；后续通过设备适配层接入，不直接写生产主表

十三、接口评审检查表

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

十四、待 G3 评审确认

以下问题已有建议，但在进入代码蓝图前仍需正式签字确认：

云仓、租地和认养 V1 是否固定“一次创建一个业务 SKU/套餐”。
云仓首次购买是否允许平台券、积分、会员价和分销佣金。建议 V1 全部关闭，只保留现有支付方式，避免首次本金快照被多套优惠规则改变。
用户云仓结算款进入现有可用余额，还是独立可提现余额。建议 V1 先进入独立业务账本，规则内无差异记录自动校验、异常记录人工审核，再映射现有余额流水。
补运费支付是复用 CRMEB 通用支付订单注册机制，还是增加最小独立支付单适配器。
服务端现场人员是复用现有客服账号增加范围，还是新增现场人员身份。建议 V1 复用账号体系并新增职责与数据范围。

19 v1 api contract draft

V1 API 契约草案

一、设计结论

1. 接口分域

2. 与 CRMEB 的边界

3. V1 下单粒度建议

二、统一协议

1. 响应包

2. 分页、排序与筛选

3. 数据格式

4. 列表摘要与详情

5. 乐观锁

6. 幂等

三、通用请求对象

1. PageQuery

2. RuleSnapshot

3. AllowedActions

四、平台端 API 目录

1. 云仓活动与活动商品

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

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

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

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

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

五、商户端 API 目录

1. 供货申请

2. 商户货款

六、用户端云仓 API

1. 公开查询

2. 抢购校验

3. 创建订单

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

5. 去向预览

6. 确认去向

7. 补运费

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

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

1. 公开目录

2. 租地下单

3. 认养下单

4. 产出邮寄

八、服务/现场端 API

1. 客服协同

2. 现场作业

九、内部接口与事件边界

十、业务错误码

1. 通用

2. 云仓

3. 租地、认养和生产

十一、权限与隐私约束

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

十三、接口评审检查表

十四、待 G3 评审确认

十五、关联文档

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!

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`