# V1 五项目代码改造蓝图

本文档把已确认的业务、页面、数据和 API 草案映射到五个现有项目的文件级改造范围。它用于 G4 评审和任务拆分，不代表已经创建文件、接口或数据表。

## 一、使用说明

### 1. 项目边界

| 项目 | 目录 | 主要职责 |
| --- | --- | --- |
| 后端 | `smartfarm` | API、领域规则、事务、事件、任务、权限和数据访问 |
| 平台管理端 | `smartfarm_admin` | 平台运营、农业运营、仓储、财务和审核 |
| 商户端 | `smartfarm_mer` | 云仓供货申请、供货履约、货款和数据 |
| 服务端 | `smartfarm_service` | 客服协同、现场作业、仓库和异常处理 |
| 用户端 | `smartfarm_user` | 集市云仓、租地、认养、溯源和用户权益 |

### 2. 变更类型

| 标记 | 含义 |
| --- | --- |
| `N` | 新建文件或目录 |
| `M` | 修改现有文件，必须做普通商城回归 |
| `R` | 直接复用，不应复制一套同类实现 |
| `C` | 配置、菜单、数据脚本或文档变更 |
| `D` | G3/G4 评审后才能定稿的设计项 |

### 3. 文件清单的解释

- 本文中的新文件名是推荐命名，开发前可按实际命名规范微调，但职责不能重新混在一起。
- “修改现有文件”是风险最高的清单。未列出的 CRMEB 核心文件原则上不改。
- Controller 只负责鉴权后的参数接收、调用和响应，不承载金额、库存或状态迁移公式。
- Repository 保持现有 CRMEB 数据访问习惯；跨多个聚合、需要统一事务的流程放入 `crmeb/services/farm`。
- DAO 和 Model 只表达查询、关联和持久化，不负责发通知、调用支付或决定结算。
- 所有文件任务最终都要关联页面编号、API 编号、数据表、验收用例和负责人。

## 二、现有工程事实与架构决定

### 1. 已核对的工程事实

- 后端当前主链路是 `Controller -> Repository -> DAO/Model`。
- `app/common` 下现有 `dao`、`model`、`repositories`，没有独立业务 `services` 目录。
- 跨模块服务、监听器和任务位于 `crmeb/services`、`crmeb/listens`、`crmeb/jobs`。
- `route/admin.php`、`route/merchant.php`、`route/api.php`会加载对应子目录路由文件。
- `route/service.php` 当前是单文件路由，V1 先局部追加，不同时重构整个服务端路由加载方式。
- 平台端和商户端使用 Vue 2、Element UI、静态路由文件和后端 `system_menu` 菜单权限。
- 用户端是 uni-app，页面需要登记到 `pages.json`。
- 服务端只有较轻的桌面客服工作台和静态路由，现有三栏页面最小宽度约 `1000px`，不是移动农业作业壳，也没有完整的动态菜单与细粒度业务权限。
- 后端没有正式数据库迁移框架，也没有现成 PHPUnit 测试依赖；不能假定已有迁移和自动化测试体系。
- 用户端页面、DIY、普通秒杀、订单和公共组件仍在进行组件级复用审计；本文件中的用户端新增组件清单必须在该审计后复核。

### 2. 架构建议基线

下表是当前蓝图采用的建议基线，不代表已经完成 G3/G4 签字。最终状态统一以 [24-g3-g4-decision-register.md](24-g3-g4-decision-register) 为准。

| 编号 | 决定 | 原因 |
| --- | --- | --- |
| `ADR-001` | 新农业领域统一使用 `farm` 命名空间 | 与 CRMEB 商城域隔离，便于识别影响范围 |
| `ADR-002` | 云仓活动、批次、持仓和账本使用独立表 | 不扩大原 `product_type`、`activity_type` 的全局分支 |
| `ADR-003` | 云仓首次购买使用独立编排入口，以 CRMEB 订单/支付/退款作为交易载体，以 `farm` 扩展表保存云仓语义 | 避免新造平行支付订单引擎，也避免把云仓字段直接塞进普通订单 |
| `ADR-004` | 跨聚合事务服务放在 `crmeb/services/farm` | 符合现有目录结构，避免先重构全项目 |
| `ADR-005` | 普通订单只通过窄适配点接入云仓二次库存 | 降低对普通商品、普通秒杀和其他营销活动的回归范围 |
| `ADR-006` | 活动 SKU 与批次使用自己的稳定主键 | CRMEB 商品编辑会重建规格值，不能只依赖可变 `value_id` |
| `ADR-007` | 事件采用事务事实表和幂等消费者 | 支付、退款、定时任务可能重复，业务不能依赖单次内存事件 |
| `ADR-008` | V1 云仓二次销售 SKU 必须是 `cloud_only` 库存来源 | 避免同一订单明细混合普通库存与云仓库存后无法退款分摊 |
| `ADR-009` | 业务账本/结单先冻结计算事实，再经统一入账桥接映射 CRMEB 余额和商户财务 | 保留计算依据、数据库幂等、审核、冻结和冲正能力 |
| `ADR-010` | 农业生产记录发布后版本化 | 用户看到的溯源事实不能被静默覆盖 |
| `ADR-011` | 地图统一腾讯供应商和 GCJ02，业务代码依赖地图 Provider 抽象 | 兼容现有管理端与 uni-app，同时隔离客户端 Key、服务端 Key/SK 和旧坐标字段 |

`ADR-008` 已冻结为由平台运营建立“二次代销商品映射 SKU”：前台仍是普通商城商品页面和普通订单，但该 SKU 的可售库存完全来自云仓桥接池。V1 不允许一个 SKU 同时消耗商户普通库存和云仓库存。

## 三、后端 `smartfarm` 改造

### 1. 路由文件

| 类型 | 文件 | 处理内容 |
| --- | --- | --- |
| `N` | `route/admin/farm_cloud.php` | 平台云仓活动、供货、订单、批次、二次零售、回购、账本和异常 |
| `N` | `route/admin/farm_agriculture.php` | 地图辅助、农场、地块、自提点、租地、认养、生产、产出、履约和溯源 |
| `N` | `route/merchant/farm_cloud.php` | 商户供货申请、验收结果、履约、数据和货款 |
| `N` | `route/api/farm.php` | 用户云仓、租地、认养、履约和溯源接口 |
| `M` | `route/service.php` | 追加客服/现场端云仓异常、生产记录、产出和履约接口 |
| `R` | `route/admin/marketing.php` | 只参考普通秒杀路由风格，不把云仓接口塞入普通秒杀控制器 |
| `R` | `route/merchant/marketing.php` | 只参考商户参加活动的路由和权限写法 |
| `R` | `route/api/login.php` | 复用登录/可选登录中间件分组方式，不新增失效的 v3 订单入口 |

路由要求：

- 每个后台写接口必须有唯一 route name，并在 `system_menu.route` 建立操作权限。
- 用户公开列表与详情可选登录；下单、选去向、补运费、持仓和账本必须强制登录。
- 所有命令接口使用 `POST`，不使用 `GET` 改状态。
- 路径与 [19-v1-api-contract-draft.md](19-v1-api-contract-draft) 一致。
- 普通请求锁中间件只能防短时间重复点击，金额和库存接口仍需业务幂等键。

四端均注册相对路径 `GET farm/operation/detail/:operation_no`，分别路由到平台、商户、用户、服务端的 `FarmOperation::detail()`；Controller 只注入当前身份与范围，统一调用 `FarmAsyncOperationService::detailForActor()`。不得把任一端的 Token 交给另一端 Controller 复用。

### 2. 平台端 Controller

#### 云仓

| 类型 | 推荐文件 | 对应职责 |
| --- | --- | --- |
| `N` | `app/controller/admin/farm/cloud/CloudActivity.php` | 活动草稿、发布、关闭、统计 |
| `N` | `app/controller/admin/farm/cloud/CloudActivityProduct.php` | 活动商品与 SKU 规则 |
| `N` | `app/controller/admin/farm/cloud/CloudSupply.php` | 平台自营供货创建、商户供货审核、冻结、验收、退回和平台承接 |
| `N` | `app/controller/admin/farm/cloud/CloudOrder.php` | 首次订单、待选去向和退款查询 |
| `N` | `app/controller/admin/farm/cloud/CloudPickup.php` | 自提核销、逾期处理 |
| `N` | `app/controller/admin/farm/cloud/CloudBatch.php` | 批次、库存池、冻结、恢复、对账预览 |
| `N` | `app/controller/admin/farm/cloud/CloudResale.php` | 二次零售分配与订单关联查询 |
| `N` | `app/controller/admin/farm/cloud/CloudUserLedger.php` | 用户账本、入账、冲正申请 |
| `N` | `app/controller/admin/farm/cloud/CloudMerchantLedger.php` | 商户供货货款和对账 |
| `N` | `app/controller/admin/farm/cloud/CloudMerchantStatement.php` | 商户日结单预览、生成、复核入账 |
| `N` | `app/controller/admin/farm/cloud/FarmFinancialPosting.php` | 正式入账详情、失败重试和反向记录查询 |
| `N` | `app/controller/admin/farm/cloud/CloudReconciliation.php` | 五段对账、差异详情、修复预览和审核执行 |
| `N` | `app/controller/admin/farm/cloud/CloudBuyback.php` | 回购预览、审核与执行 |
| `N` | `app/controller/admin/farm/cloud/CloudException.php` | 云仓异常处理 |

#### 农业经营

| 类型 | 推荐目录/文件 | 对应职责 |
| --- | --- | --- |
| `N` | `app/controller/admin/farm/asset/Farm.php` | 农场主数据 |
| `N` | `app/controller/admin/farm/asset/Zone.php` | 区域主数据 |
| `N` | `app/controller/admin/farm/asset/Plot.php` | 地块、容量与地图信息 |
| `N` | `app/controller/admin/farm/asset/PickupPoint.php` | 云仓自提点；租地/认养产出 V1 仍只邮寄 |
| `N` | `app/controller/admin/farm/asset/Warehouse.php` | 农场详情内仓库和库位主数据 |
| `N` | `app/controller/admin/farm/asset/FarmDashboard.php` | 农业工作台按权限聚合 |
| `N` | `app/controller/admin/farm/asset/Enclosure.php` | 栏舍/蜂场 |
| `N` | `app/controller/admin/farm/asset/AnimalAsset.php` | 单体动物资产及 `validate/preview/confirm` 三段导入 |
| `N` | `app/controller/admin/farm/asset/BreedingBatch.php` | 养殖批次、容量和可分配份额 |
| `N` | `app/controller/admin/farm/catalog/Crop.php` | 作物与品种目录 |
| `N` | `app/controller/admin/farm/catalog/Breed.php` | 养殖品种目录 |
| `N` | `app/controller/admin/farm/catalog/ProductAgriculture.php` | 平台商品审核/详情中的农业资料与材料 |
| `N` | `app/controller/admin/farm/land/LandPlan.php` | 租地套餐和版本 |
| `N` | `app/controller/admin/farm/land/LandOrder.php` | 租地订单与权益 |
| `N` | `app/controller/admin/farm/land/LandAllocation.php` | 地块候选和确认分配 |
| `N` | `app/controller/admin/farm/adoption/AdoptionPlan.php` | 认养套餐和版本 |
| `N` | `app/controller/admin/farm/adoption/AdoptionOrder.php` | 认养订单与权益 |
| `N` | `app/controller/admin/farm/adoption/AdoptionAllocation.php` | 个体/批次份额分配 |
| `N` | `app/controller/admin/farm/production/ProductionBatch.php` | 种植/养殖生产批次 |
| `N` | `app/controller/admin/farm/production/FarmTask.php` | 批次详情内任务创建、分派、转派、取消和历史 |
| `N` | `app/controller/admin/farm/production/ProductionEvent.php` | 过程记录审核与发布 |
| `N` | `app/controller/admin/farm/production/OutputBatch.php` | 产出、质量和库存 |
| `N` | `app/controller/admin/farm/fulfillment/FarmFulfillment.php` | 农业和云仓履约 |
| `N` | `app/controller/admin/farm/exception/FarmException.php` | 农业异常审核和处理 |
| `N` | `app/controller/admin/farm/trace/TraceArchive.php` | 溯源档案与版本 |
| `N` | `app/controller/admin/farm/trace/TraceMaterial.php` | 报告/证书、有效期和状态 |
| `N` | `app/controller/admin/farm/trace/TraceLink.php` | 商品、订单、生产/产出批次关联和解除 |
| `N` | `app/controller/admin/farm/support/FarmMap.php` | 地址编码、逆地址和地点建议，只返回规范化结果 |
| `N` | `app/controller/admin/farm/support/FarmAdminScope.php` | 现有管理员页农业数据范围的选项、详情和全量保存 |
| `N` | `app/controller/admin/farm/support/FarmOperation.php` | 当前管理员范围内异步操作进度和结果 |

### 3. 商户、用户和服务端 Controller

#### 商户

| 类型 | 推荐文件 | 对应职责 |
| --- | --- | --- |
| `N` | `app/controller/merchant/farm/cloud/CloudSupply.php` | 供货草稿、提交、材料和审核结果 |
| `N` | `app/controller/merchant/farm/cloud/CloudSupplyRecord.php` | 验收、活动占用和首次销售数据 |
| `N` | `app/controller/merchant/farm/cloud/CloudFulfillment.php` | 约定由商户处理的履约/售后 |
| `N` | `app/controller/merchant/farm/cloud/CloudSupplyLedger.php` | 货款账本和对账异议 |
| `N` | `app/controller/merchant/farm/cloud/CloudSupplyStatement.php` | 日结单列表、详情和导出 |
| `N` | `app/controller/merchant/farm/catalog/ProductAgriculture.php` | 商户商品农业资料、材料和供货资格 |
| `N` | `app/controller/merchant/farm/support/FarmOperation.php` | 当前商户异步操作进度和结果 |

#### 用户

| 类型 | 推荐文件 | 对应职责 |
| --- | --- | --- |
| `N` | `app/controller/api/farm/cloud/CloudActivity.php` | 云仓活动、场次和商品详情 |
| `N` | `app/controller/api/farm/cloud/CloudOrder.php` | 校验、创建、支付后状态和首次退款 |
| `N` | `app/controller/api/farm/cloud/CloudDisposition.php` | 去向预览和最终确认 |
| `N` | `app/controller/api/farm/cloud/CloudFreight.php` | 运费单详情、支付、结果、取消和退款结果 |
| `N` | `app/controller/api/farm/cloud/CloudPickup.php` | 自提码和核销状态 |
| `N` | `app/controller/api/farm/cloud/CloudHolding.php` | 我的持仓、进度和回购 |
| `N` | `app/controller/api/farm/cloud/CloudLedger.php` | 用户本金、收益和回购账本 |
| `N` | `app/controller/api/farm/agriculture/Farm.php` | 农场专区、公开详情和公开位置 |
| `N` | `app/controller/api/farm/land/LandPlan.php` | 租地套餐公开目录 |
| `N` | `app/controller/api/farm/land/LandOrder.php` | 租地下单、详情和产出邮寄 |
| `N` | `app/controller/api/farm/adoption/AdoptionPlan.php` | 认养套餐公开目录 |
| `N` | `app/controller/api/farm/adoption/AdoptionOrder.php` | 认养下单、详情和产出邮寄 |
| `N` | `app/controller/api/farm/fulfillment/FarmFulfillment.php` | 租地/认养产出地址、运费、包裹、收货和售后 |
| `N` | `app/controller/api/farm/exception/FarmException.php` | 本人异常方案详情、接受或拒绝 |
| `N` | `app/controller/api/farm/trace/Trace.php` | 用户可见溯源档案 |
| `N` | `app/controller/api/farm/support/FarmOperation.php` | 当前用户异步操作进度和结果 |

#### 服务/现场端

| 类型 | 推荐文件 | 对应职责 |
| --- | --- | --- |
| `N` | `app/controller/service/farm/Common.php` | 工作区上下文和本人授权摘要 |
| `N` | `app/controller/service/farm/FarmOrder.php` | 租地/认养订单搜索和综合详情 |
| `N` | `app/controller/service/farm/CloudOrder.php` | 云仓订单、去向、持仓、批次和账本只读 |
| `N` | `app/controller/service/farm/CloudException.php` | 客服查询、详情和提交处理建议 |
| `N` | `app/controller/service/farm/FarmTask.php` | 本人任务列表、详情和版本 |
| `N` | `app/controller/service/farm/FarmScan.php` | 二维码解析、验签和可执行动作 |
| `N` | `app/controller/service/farm/ProductionEvent.php` | 现场过程记录草稿与提交 |
| `N` | `app/controller/service/farm/OutputBatch.php` | 采收/产出录入 |
| `N` | `app/controller/service/farm/AssetHealth.php` | 健康、防疫和养殖记录 |
| `N` | `app/controller/service/farm/Warehouse.php` | 入库验收、拣货、打包和出库 |
| `N` | `app/controller/service/farm/CloudPickup.php` | 云仓自提核销、剩余数量处理和逾期协同 |
| `N` | `app/controller/service/farm/FarmFulfillment.php` | 租地/认养产出物流和履约异常 |
| `N` | `app/controller/service/farm/FarmException.php` | 现场异常上报和补充证据 |
| `N` | `app/controller/service/farm/FarmReview.php` | 被授权记录的审核或驳回 |
| `N` | `app/controller/service/farm/FarmAttachment.php` | 复用 `UploadService` 存储，创建受范围约束的临时证据附件并返回 ID |
| `N` | `app/controller/service/farm/FarmOperation.php` | 当前服务人员异步操作进度和结果 |

### 4. Validate

现有项目使用 `app/validate/admin`、`app/validate/merchant`、`app/validate/api`。V1 延续该方式，不另造 Request DTO 框架。

| 类型 | 目录 | 首批验证器 |
| --- | --- | --- |
| `N` | `app/validate/admin/farm/cloud` | `CloudActivityValidate`、`CloudActivityProductValidate`、`CloudSupplyValidate`、`CloudPlatformSupplyValidate`、`CloudPickupValidate`、`CloudBuybackValidate`、`CloudLedgerAdjustValidate`、`CloudMerchantStatementValidate`、`FarmFinancialPostingValidate` |
| `N` | `app/validate/admin/farm/agriculture` | `FarmAssetValidate`、`WarehouseValidate`、`PickupPointValidate`、`AnimalImportValidate`、`BreedingBatchValidate`、`LandPlanValidate`、`AdoptionPlanValidate`、`AllocationValidate`、`ProductionBatchValidate`、`ProductionEventValidate`、`FarmTaskValidate`、`OutputBatchValidate`、`OutputAllocationValidate`、`FarmExceptionPlanValidate`、`TraceVersionValidate`、`TraceMaterialValidate`、`TraceLinkValidate` |
| `N` | `app/validate/admin/farm/catalog` | `ProductAgricultureValidate`、`ProductMaterialValidate` |
| `N` | `app/validate/admin/farm/support` | `FarmMapQueryValidate`、`GeoPointValidate`、`FarmAdminScopeValidate` |
| `N` | `app/validate/merchant/farm/cloud` | `CloudSupplyValidate`、`CloudSupplySubmitValidate`、`CloudSupplyDeliveryValidate`、`CloudSupplyReturnValidate`、`CloudFulfillmentValidate`、`CloudLedgerExceptionValidate` |
| `N` | `app/validate/merchant/farm/catalog` | `ProductAgricultureValidate`、`ProductMaterialValidate` |
| `N` | `app/validate/api/farm/cloud` | `CloudOrderValidate`、`CloudDispositionValidate`、`CloudFreightValidate`、`CloudRefundValidate` |
| `N` | `app/validate/api/farm/agriculture` | `LandOrderValidate`、`AdoptionOrderValidate`、`FarmFulfillmentAddressValidate`、`FarmFulfillmentFreightValidate`、`FarmFulfillmentRefundValidate`、`FarmExceptionConfirmValidate` |
| `N` | `app/validate/service/farm` | `FarmScanValidate`、`CloudPickupVerifyValidate`、`ProductionEventValidate`、`OutputBatchValidate`、`WarehouseReceiveValidate`、`FarmFulfillmentValidate`、`FarmExceptionValidate`、`FarmReviewValidate`、`FarmAttachmentValidate` |

验证器除字段格式外，还要调用领域查询验证当前状态；Controller 不得只依赖前端按钮是否显示。

### 5. Model、DAO 与 Repository

#### 商品农业扩展

普通商品仍以 CRMEB 商品/SKU 为主对象，农业资料和证书报告使用薄扩展表：

```text
app/common/model/farm/catalog/<Entity>.php
app/common/dao/farm/catalog/<Entity>Dao.php
app/common/repositories/farm/catalog/<Entity>Repository.php
```

| 实体 | 主表/职责 |
| --- | --- |
| `ProductAgricultureProfile` | `eb_farm_product_agriculture_profile`，商品农业来源、产地和公开摘要 |
| `ProductMaterial` | `eb_farm_product_material`，商品报告/证书/溯源材料关联 |

平台商品审核、商户商品编辑和用户商品详情均通过 Repository/读取适配器访问扩展资料，不把农业字段继续塞入商品描述 JSON。

#### 云仓聚合

以下实体按同名方式建立：

```text
app/common/model/farm/cloud/<Entity>.php
app/common/dao/farm/cloud/<Entity>Dao.php
app/common/repositories/farm/cloud/<Entity>Repository.php
```

| 实体 | 主表/职责 |
| --- | --- |
| `CloudActivity` | `eb_farm_cloud_activity` |
| `CloudSupply` | `eb_farm_cloud_supply` |
| `CloudSupplyDelivery` | `eb_farm_cloud_supply_delivery` |
| `CloudSupplyInspection` | `eb_farm_cloud_supply_inspection` |
| `CloudSupplyMaterial` | `eb_farm_cloud_supply_material` |
| `CloudSupplyReturn` | `eb_farm_cloud_supply_return` |
| `CloudSupplyAcquisition` | `eb_farm_cloud_supply_acquisition` |
| `CloudActivityProduct` | `eb_farm_cloud_activity_product` |
| `CloudActivitySku` | `eb_farm_cloud_activity_sku` |
| `CloudUserQuota` | `eb_farm_cloud_user_quota` |
| `CloudBatch` | `eb_farm_cloud_batch` |
| `CloudBatchPoolBalance` | `eb_farm_cloud_batch_pool_balance` |
| `CloudInventoryFlow` | `eb_farm_cloud_inventory_flow` |
| `CloudOrderItem` | `eb_farm_cloud_order_item` |
| `CloudFreightOrder` | `eb_farm_cloud_freight_order` |
| `CloudFreightRefund` | `eb_farm_cloud_freight_refund` |
| `CloudPickup` | `eb_farm_cloud_pickup` |
| `CloudPickupVerification` | `eb_farm_cloud_pickup_verification` |
| `CloudPrimaryRefundImpact` | `eb_farm_cloud_primary_refund_impact` |
| `CloudHolding` | `eb_farm_cloud_holding` |
| `CloudResaleStock` | `eb_farm_cloud_resale_stock` |
| `CloudResaleAllocation` | `eb_farm_cloud_resale_allocation` |
| `CloudResaleRefundAllocation` | `eb_farm_cloud_resale_refund_allocation` |
| `CloudBatchProgress` | `eb_farm_cloud_batch_progress` |
| `CloudUserLedger` | `eb_farm_cloud_user_ledger` |
| `CloudBuyback` | `eb_farm_cloud_buyback` |
| `CloudLedgerAdjustment` | `eb_farm_cloud_ledger_adjustment` |
| `MerchantSupplyLedger` | `eb_farm_merchant_supply_ledger` |
| `MerchantSupplyStatement` | `eb_farm_merchant_supply_statement` |
| `MerchantSupplyStatementItem` | `eb_farm_merchant_supply_statement_item` |

Repository 职责约束：

- `CloudActivityRepository` 负责列表、详情和配置持久化，不直接执行批次结算。
- `CloudActivitySkuRepository` 负责稳定 `activity_sku_id`、来源诊断字段和发布快照；只允许在草稿状态确认更新来源引用。
- `CloudSupplyReturnRepository` 与 `CloudSupplyAcquisitionRepository` 只保存独立生命周期事实和条件状态迁移；供货汇总与 CRMEB/平台库存必须由 `CloudSupplyLifecycleService` 在同一事务更新。
- `CloudBatchRepository` 提供带行锁的候选批次查询、汇总重算和状态条件更新。
- `CloudInventoryFlowRepository` 只追加流水，并用 `idempotency_key` 防重。
- `CloudFreightOrderRepository` 提供带行锁的当前运费单查询、订单号/交易号防重和条件状态迁移；不直接调用支付渠道。
- `CloudFreightRefundRepository` 以运费单和退款单号防重，失败重试不得创建新退款单号。
- `CloudResaleStockRepository` 负责二次可售桥接汇总，不代替批次流水。
- `CloudUserLedgerRepository` 保存计算结果和状态，不在 Model 事件中直接改余额。
- `MerchantSupplyStatementRepository` 只归集已具资格且未入单的供货账本，结单生成后不替换明细。
- `FarmFinancialPostingRepository` 负责唯一 `posting_key`、处理租约、成功结果和反向入账关联，不自行计算业务应结金额。
- 所有 `*_Repository` 查询都必须显式接受平台、商户、用户或数据范围条件。

#### 农业经营聚合

```text
app/common/model/farm/agriculture/<Entity>.php
app/common/dao/farm/agriculture/<Entity>Dao.php
app/common/repositories/farm/agriculture/<Entity>Repository.php
```

首批实体：

| 实体 | 主表 |
| --- | --- |
| `Farm` | `eb_farm_farm` |
| `Zone` | `eb_farm_zone` |
| `Plot` | `eb_farm_plot` |
| `Warehouse` | `eb_farm_warehouse` |
| `WarehouseLocation` | `eb_farm_warehouse_location` |
| `PickupPoint` | `eb_farm_pickup_point` |
| `PlotOccupancy` | `eb_farm_plot_occupancy` |
| `Crop` | `eb_farm_crop` |
| `LandPlan` | `eb_farm_land_plan` |
| `LandPlanCrop` | `eb_farm_land_plan_crop` |
| `LandOrder` | `eb_farm_land_order` |
| `AdoptionCategory` | `eb_farm_adoption_category` |
| `Breed` | `eb_farm_breed` |
| `Enclosure` | `eb_farm_enclosure` |
| `AnimalAsset` | `eb_farm_animal_asset` |
| `BreedingBatch` | `eb_farm_breeding_batch` |
| `AdoptionPlan` | `eb_farm_adoption_plan` |
| `AdoptionOrder` | `eb_farm_adoption_order` |
| `AdoptionAllocation` | `eb_farm_adoption_allocation` |
| `AssetReplacement` | `eb_farm_asset_replacement` |
| `ProductionBatch` | `eb_farm_production_batch` |
| `ProductionPlantDetail` | `eb_farm_production_plant_detail` |
| `ProductionLivestockDetail` | `eb_farm_production_livestock_detail` |
| `ProductionRightLink` | `eb_farm_production_right_link` |
| `ProductionEvent` | `eb_farm_production_event` |
| `ProductionEventVersion` | `eb_farm_production_event_version` |
| `FarmTask` | `eb_farm_task` |
| `FarmTaskAssignment` | `eb_farm_task_assignment` |
| `OutputBatch` | `eb_farm_output_batch` |
| `OutputInventoryFlow` | `eb_farm_output_inventory_flow` |
| `OutputAllocation` | `eb_farm_output_allocation` |
| `FarmFulfillment` | `eb_farm_fulfillment` |
| `FarmFulfillmentItem` | `eb_farm_fulfillment_item` |
| `FarmFulfillmentPackage` | `eb_farm_fulfillment_package` |
| `FarmFulfillmentPackageItem` | `eb_farm_fulfillment_package_item` |
| `FarmFulfillmentFreightOrder` | `eb_farm_fulfillment_freight_order` |
| `FarmExceptionEvent` | `eb_farm_exception_event` |
| `FarmExceptionImpact` | `eb_farm_exception_impact` |
| `FarmExceptionPlanVersion` | `eb_farm_exception_plan_version` |
| `FarmExceptionExecutionStep` | `eb_farm_exception_execution_step` |
| `TraceArchive` | `eb_farm_trace_archive` |
| `TraceVersion` | `eb_farm_trace_version` |
| `TraceMaterial` | `eb_farm_trace_material` |
| `TraceLink` | `eb_farm_trace_link` |

容量类 DAO 必须提供可加锁查询：

- 地块剩余面积。
- 栏舍/批次剩余份额。
- 产出批次合格可分配数量。
- 批次二次可售数量。

### 6. 跨聚合 Service

推荐新建：

```text
crmeb/services/farm/cloud
crmeb/services/farm/agriculture
crmeb/services/farm/support
crmeb/services/farm/support/map
```

#### 云仓 Service

| 类型 | 推荐文件 | 事务职责 |
| --- | --- | --- |
| `N` | `CloudActivityPublishService.php` | 发布校验、规则快照、批次草稿和供货占用 |
| `N` | `CloudActivityInventoryCloseService.php` | 活动结束后等待未支付释放，按供货归属关闭未抢库存 |
| `N` | `CloudSupplyLifecycleService.php` | 商户/平台单 SKU 申请、审核预留、送达、验收/拒收、释放、退回和平台承接；平台来源锁 `eb_store_product`、`eb_store_product_attr_value` 并写农业库存流水 |
| `N` | `CloudSupplyResponsibilityService.php` | 固化运费、质量和售后三类责任快照，并计算履约 `allowed_actions` |
| `N` | `CloudOrderCreateService.php` | 抢购校验、CRMEB 订单三层记录、订单绑定、首次库存锁定和幂等 |
| `N` | `CloudOrderPaidService.php` | 支付成功后首次库存确认和选择截止 |
| `N` | `CloudDispositionService.php` | 单一去向冻结、履约/持仓创建 |
| `N` | `CloudFreightQuoteService.php` | 复用 CRMEB 运费模板、区域、重量/体积并生成报价快照与哈希 |
| `N` | `CloudFreightPaymentService.php` | 创建/切换运费单、在线/余额支付、成功事务、迟到支付 |
| `N` | `CloudFreightRefundService.php` | 在线/余额全额退款、同退款单号重试和人工复核 |
| `N` | `CloudPickupService.php` | 分次核销、不可变核销流水、逾期剩余量与数量级首次完成事实 |
| `N` | `CloudBatchStartService.php` | 选择冻结、持仓入批次和二次库存发布 |
| `N` | `CloudResaleStockService.php` | 普通 SKU 与云仓库存桥接 |
| `N` | `CloudResaleAllocationService.php` | FEFO 分配、释放、生效和冲减 |
| `N` | `CloudProgressService.php` | 整数实物进度、经济等价数量、节点跨越和计算版本 |
| `N` | `CloudUserSettlementService.php` | 三种模式累计应结、最大余数分钱、正常退款抵扣与平台风险承担 |
| `N` | `CloudBuybackService.php` | 到期宽限、所有权切换、预案审核和原子回购库存转移 |
| `N` | `MerchantSupplySettlementService.php` | 首次购买、验收、观察期和商户货款 |
| `N` | `MerchantSupplyStatementService.php` | 按商户和自然日归集货款账本、冻结结单明细 |
| `N` | `CloudReconciliationService.php` | 只读重算、差异预览和审核修复 |

补运费支付实现边界：

- `CloudFreightOrder::getPayParams()` 只输出 `order_sn`、`pay_price`、`attach=farm_cloud_freight`、`body` 和可选 `return_url`。
- `CloudFreightPaymentService` 直接调用 CRMEB `Pay` 驱动，不调用 `StoreOrderRepository::paySuccess()`，不创建普通商城订单。
- V1 只开放当前用户终端已启用的微信、支付宝和余额支付；明确拒绝线下、扫码枪、组合支付和商户子账户支付。
- 支付超时后本地状态先收敛，渠道关单放入 Outbox；迟到成功回调只创建全额退款，不反向修改已生效的代销/待选择结果。

平台自营供货创建固定使用 `source_type=platform`、`merchant_id=NULL`。来源商品必须属于 CRMEB 自营商户（`eb_store_product.mer_id → eb_merchant.is_trader=1`），并同时满足商品可用和农业资料已批准。预占事务按主键顺序锁 `eb_store_product`、`eb_store_product_attr_value` 和供货聚合，校验 SKU 仍属于该商品及 `stock - 已有农业预占 >= proposed_qty`；成功后扣减/预占现有 SKU 可售库存、同步 SPU 汇总库存，并写 `eb_farm_cloud_inventory_flow`。任何一项失败整笔回滚，不能只写供货草稿。

#### 农业 Service

| 类型 | 推荐文件 | 事务职责 |
| --- | --- | --- |
| `N` | `ProductAgricultureService.php` | 平台/商户商品农业资料保存、提交、审核、材料集合校验和供货资格重算 |
| `N` | `ProductMaterialExpiryService.php` | 锁商品农业资料及当前必需材料集合，整体重算 `material_status/supply_eligible`，同事务写审计、状态历史和 Outbox |
| `N` | `LandOrderCreateService.php` | 套餐快照、交易扩展和支付后权益 |
| `N` | `PlotAllocationService.php` | 真实地块容量锁和占用 |
| `N` | `AdoptionOrderCreateService.php` | 套餐快照、单体/份额权益 |
| `N` | `AdoptionAllocationService.php` | 个体排他或批次份额分配 |
| `N` | `ProductionBatchService.php` | 权益、资产与生产批次关联 |
| `N` | `FarmTaskService.php` | 任务创建、分派、转派、取消、完成和历史 |
| `N` | `ProductionEventPublishService.php` | 审核、发布版本和用户可见性 |
| `N` | `OutputAllocationService.php` | 合格产出按权益分配 |
| `N` | `FarmFulfillmentService.php` | 分批邮寄、运费承担快照、物流、签收和售后 |
| `N` | `FarmFulfillmentFreightService.php` | 农业独立运费单、支付确认、超时和迟到退款 |
| `N` | `FarmDeliveryRefundService.php` | 服务/交付退款基数、累计未履约退款公式和分钱尾差 |
| `N` | `TracePublishService.php` | 溯源版本、材料和二维码关联 |
| `N` | `FarmExceptionService.php` | 异常事实、等价校验、用户确认/超时、比例分配、影响重算和方案版本 |
| `N` | `FarmExceptionExecutionService.php` | 预检、审核后分步执行、重试和闭合 |

#### 支撑 Service

| 类型 | 推荐文件 | 作用 |
| --- | --- | --- |
| `N` | `FarmIdempotencyService.php` | 命令幂等记录 |
| `N` | `FarmOutboxService.php` | 事务内写事件事实 |
| `N` | `FarmOrderPolicyResolver.php` | 批量读取订单绑定，返回财务、库存和履约策略 |
| `N` | `FarmOrderPaymentAdapter.php` | 支付事务内确认农业付款事实和 Outbox |
| `N` | `FarmOrderCancelAdapter.php` | 未支付关闭时按库存策略释放 |
| `N` | `FarmOrderRefundAdapter.php` | 退款申请、拒绝、取消和完成的统一薄适配 |
| `N` | `FarmAuditService.php` | 高风险操作审计 |
| `N` | `FarmNotificationService.php` | 通知模板、发送和去重 |
| `N` | `FarmMoneyService.php` | 金额、基点、累计差额和尾差规则 |
| `N` | `FarmUserBalancePostingService.php` | 锁定用户账本和账户，原子写余额、`UserBill`、入账记录和 Outbox |
| `N` | `FarmMerchantBalancePostingService.php` | 锁定商户结单和账户，原子写余额、`FinancialRecord`、入账记录和 Outbox |
| `N` | `FarmFinancialReversalService.php` | 审核后创建借方入账；余额不足转待追偿 |
| `N` | `FarmStateMachineService.php` | 统一校验状态迁移 |
| `N` | `FarmAsyncOperationService.php` | 导入、导出、重算、修复和批量命令的对外状态 |
| `N` | `FarmAdminScopeService.php` | 平台管理员业务域和对象范围解析 |
| `N` | `FarmEvidenceAttachmentService.php` | 调用现有 `UploadService`、检测文件、创建临时附件、业务提交时原子绑定 |
| `N` | `map/GeoPoint.php` | 规范化经纬度、成对空值、范围和 `GCJ02` 校验 |
| `N` | `map/MapProviderInterface.php` | 地理编码、逆地址和地点建议供应商契约 |
| `N` | `map/TencentMapProvider.php` | 腾讯 WebService 请求、签名、TLS、超时和错误映射 |
| `N` | `map/FarmMapService.php` | Provider 选择、缓存、限流、结果裁剪和统一错误 |

支撑表按同样的 Model/DAO/Repository 规范建立，推荐目录为：

```text
app/common/model/farm/support
app/common/dao/farm/support
app/common/repositories/farm/support
```

| 实体 | 主表 |
| --- | --- |
| `FarmOrderBinding` | `eb_farm_order_binding` |
| `FarmIdempotencyRecord` | `eb_farm_idempotency_record` |
| `FarmDomainOutbox` | `eb_farm_domain_outbox` |
| `FarmEventConsumeLog` | `eb_farm_event_consume_log` |
| `FarmJobRun` | `eb_farm_job_run` |
| `FarmNotificationLog` | `eb_farm_notification_log` |
| `FarmAuditLog` | `eb_farm_audit_log` |
| `FarmStateTransition` | `eb_farm_state_transition` |
| `FarmAsyncOperation` | `eb_farm_async_operation` |
| `FarmAdminScope` | `eb_farm_admin_scope` |
| `FarmServiceProfile` | `eb_farm_service_profile` |
| `FarmServiceScope` | `eb_farm_service_scope` |
| `FarmEvidenceAttachment` | `eb_farm_evidence_attachment` |
| `FarmFinancialPosting` | `eb_farm_financial_posting` |

### 7. CRMEB 核心适配点

| 类型 | 现有文件 | 计划改动 | 风险与限制 |
| --- | --- | --- | --- |
| `M` | `app/event.php` | 注册 `pay_success_farm_cloud_freight`、农业监听器和定时任务 | 不改变现有监听顺序 |
| `M` | `app/controller/api/Common.php`、`route/api/notLogin.php` | 旧 `/api/lbs/*` 响应兼容地收口到 `FarmMapService`，补参数验证与统一错误 | 独立基线整改；先回归首页定位、地址和附近门店 |
| `X` | `vendor/joypack/tencent-map` 请求实现 | 新农业地图不直接调用当前关闭 TLS 校验的请求层 | 不直接修改 vendor；使用项目 HTTP 客户端实现 Provider |
| `M` | `crmeb/services/AlipayService.php` | 验签后规范化 `out_trade_no`、`trade_no`、`total_amount`、`gmt_payment`、`trade_status`、`attach` | 不改变验签、响应文本或现有 `attach` 分发 |
| `M` | `app/common/repositories/store/order/StoreOrderCreateRepository.php` | 订单明细落库后调用云仓二次库存适配器 | 仅 `cloud_only` SKU 进入，失败与整单回滚 |
| `M` | `app/common/repositories/store/order/StoreOrderRepository.php` | `paySuccess` 事务内和提交后所有副作用先读取订单组策略矩阵 | 普通订单必须保持原逻辑和查询成本 |
| `M` | `app/common/repositories/store/order/StoreRefundOrderRepository.php` | 在三个申请入口、`refuse()`、`cancel()`、`executeRefund()` 扣商户锁定款前和 `refundAfter()` 分阶段调用适配器 | 云仓策略必须在错误普通财务副作用发生前生效 |
| `M` | `crmeb/jobs/CancelGroupOrderJob.php` | 在任何普通库存/活动库存/优惠券恢复前取得农业取消决策，再按布尔策略执行 | 首次与二次库存策略不同，必须幂等 |
| `M` | `app/common/repositories/store/order/MerchantOrderCreateRepository.php` | 拒绝 `cloud_only` SKU 代客下单 | V1 防止绕过 FEFO 分配 |
| `M` | `app/common/repositories/store/order/PointsOrderCreateRepository.php` | 拒绝 `cloud_only` SKU 积分兑换 | V1 不允许叠加活动 |
| `R` | `app/common/repositories/system/attachment/AttachmentRepository.php` | 平台/商户材料、导入源文件和异步结果复用 `eb_system_attachment.attachment_id` 及原租户归属校验 | 不把服务端农业证据 ID 当成系统附件 ID，不保存永久 URL |
| `R` | `app/common/repositories/store/product/ProductRepository.php` | 复用商品查询和普通销售能力 | 不新增云仓 `product_type` |
| `R` | `app/common/repositories/store/product/ProductAttrValueRepository.php` | 查询来源 SKU | 不把其自增主键当云仓永久业务主键 |
| `R` | `app/common/repositories/store/order/StoreOrderProductRepository.php` | 关联普通订单明细 | 云仓分配表保留独立快照 |
| `R` | `app/common/repositories/user/UserRepository.php` | 在专用事务中带行锁读取并保存用户余额 | 不调用后台人工调账接口 |
| `M` | `app/common/repositories/user/UserBillRepository.php` | 增加 `farm_cloud_settlement`、`farm_cloud_freight_pay`、`farm_cloud_freight_refund` 类型和展示文案 | `UserBill` 不承担业务幂等 |
| `R` | `app/common/repositories/system/merchant/MerchantRepository.php` | 账户行已锁定后复用 `addMoney` 和核心写入许可 | 商户货款不进入全局冻结款 |
| `M` | `app/common/repositories/system/merchant/FinancialRecordRepository.php` | 增加 `farm_supply_settlement` 常量、商户收入统计和查询识别 | 平台云仓对账仍读独立供货账本 |
| `M` | `app/controller/api/store/product/StoreProduct.php` | 商品详情追加已发布农业资料、材料和溯源摘要 | 不改变普通商品主结构和未配置商品响应 |
| `M` | `app/controller/api/store/order/StoreOrder.php` | 普通订单详情追加农业资料/溯源入口和 `farm_order_binding` 摘要 | 不在普通页面复制云仓完整状态机 |

正式入账的文件级事务边界：

1. `FarmUserBalancePostingService` 锁定 `CloudUserLedger`、`FarmFinancialPosting` 和 `User`，在同一事务写 `now_money`、`UserBill`、账本状态和 Outbox。
2. `FarmMerchantBalancePostingService` 锁定 `MerchantSupplyStatement`、`FarmFinancialPosting` 和 `Merchant`，在同一事务调用 `addMoney`、写 `FinancialRecord`、回写结单明细和 Outbox。
3. `CloudFreightPaymentService` 按运费单、云仓明细、用户账户顺序加锁；余额支付在同一事务扣余额、写 `UserBill`、确认邮寄、创建履约和 Outbox，在线支付回调事务执行除扣余额外的相同业务确认。
4. `CloudFreightRefundService` 以 `freight_refund_no` 幂等；余额退款在同一事务回款并写用户账单，在线渠道提交成功后再按渠道结果更新退款状态。
3. 两个服务都先检查目标字段容量和自动审核阈值；成功记录再次调用直接返回首次结果。
4. 不修改 `UserRepository::changeNowMoney`、充值回调或 `AutoUnlockMerchantMoneyListen` 承担云仓入账。
5. `FinancialRecord` 使用 `financial_type=farm_supply_settlement`、`type=0`；结单主键和结单号分别写入其 `order_id/order_sn`。
6. 反向调整只能调用 `FarmFinancialReversalService` 生成新记录，不更新原成功流水。

来源 SKU 适配必须经过独立 `CloudSourceSkuMatcher` 服务：按来源商品、当前标识和规范化规格文本生成 `matched`、`changed`、`missing`、`ambiguous` 或 `unresolved` 结果。发布服务只接受 `matched`；已发布活动只记录告警，不触发自动重匹配或快照覆盖。

`StoreOrderCreateRepository.php` 的适配调用必须满足：

1. 只对明确映射到 `eb_farm_cloud_resale_stock` 且状态可售的 SKU 执行。
2. 在 `StoreOrderProductRepository::insertAll()` 后、`order.create` 前，按新建 `order_id` 回查明细并完成 FEFO 批次锁定和分配；批量插入只返回影响行数，不能假设获得了明细 ID。
3. 核心订单创建失败时，云仓分配和库存流水一起回滚。
4. 普通 SKU 未映射时不额外查询全部云仓表，避免拖慢普通订单。
5. 不在支付成功后重新挑选批次；支付只推进已锁定分配状态。
6. 同一 `group_order_id` 出现 `normal` 与 `farm_managed` 两种策略时拒绝创建或拆成不同订单组，并由确认订单接口提示分别结算；只保证单个子订单一致仍不足以隔离按订单组执行的副作用。

`StoreOrderRepository::paySuccess()` 的适配必须满足：

1. 先由 `FarmOrderPolicyResolver` 一次性读取整个订单组的绑定；未命中时沿原分支执行，不给普通订单逐明细查询农业表。
2. 订单组内策略必须一致；混合策略立即回滚并告警，不能在付款后猜测哪些副作用该执行。
3. 同一 `group_order_id + event_type` 有业务唯一键；重复支付回调不得重复写农业事实。
4. 事务内和提交后副作用都读取同一策略对象，不能只跳过商户财务却继续发送普通赠券、积分或打印。
5. 提交后的 `order.paySuccess` 监听器只负责唤醒与补投递，不作为唯一事实来源。

支付成功副作用矩阵冻结如下：

| CRMEB 副作用 | `normal` | `cloud_primary` | `cloud_resale` |
| --- | --- | --- | --- |
| 核心订单支付状态、渠道事实 | 原逻辑 | 保留 | 保留 |
| 普通商品销量/普通活动状态 | 原逻辑 | 跳过，由云仓首次销量维护 | 仅保留普通商品销量；禁止普通营销活动 |
| 普通商品配送、同城配送、卡密 | 原逻辑 | 全部跳过，等待用户选去向 | 跳过自动普通履约，改由云仓分配后的履约任务接管 |
| 商户锁定款、普通净收入、普通财务 | 原逻辑 | 跳过 | 跳过 |
| 分销佣金、推广资格、用户-商户关系 | 原逻辑 | 跳过 | 跳过 |
| 积分、会员值、赠券、会员升级奖励 | 原逻辑 | 跳过 | 跳过 |
| 普通商户通知、短信、打印 | 原逻辑 | 跳过，发送云仓供货通知 | 跳过，发送云仓履约通知 |
| 普通用户支付统计/商城数据大屏 | 原逻辑 | 不计普通商城口径，进入农业报表 | 不计普通商城口径，进入农业报表 |
| 农业付款事实、状态迁移、Outbox | 无 | 写入 | 写入 |

“跳过普通副作用”不是丢弃事实：农业订单、支付金额和渠道仍可从 CRMEB 核心订单查询，业务统计由农业报表单独聚合。矩阵每一行都必须有普通订单、首次云仓和二次代销三组回归用例。

`StoreRefundOrderRepository.php` 的适配必须覆盖：

1. 三个退款申请创建入口在保存申请事实的同一事务调用 `applied()`，冻结首次去向或二次分配。
2. `refuse()` 和 `cancel()` 分别调用 `rejected()`、`cancelled()`，只解冻尚未被其他退款/异常占用的对象。
3. `executeRefund()` 在调用 `subLockMoney()` 前读取策略：`normal` 保持原逻辑，两类 `farm_managed` 均禁止扣减不存在的普通商户锁定款。
4. `refundAfter()` 负责库存、优惠和农业反向事实：`cloud_primary` 不恢复 CRMEB 来源库存；`cloud_resale` 恢复 CRMEB 镜像库存并反向 FEFO 分配，平台券按原 CRMEB 规则恢复。
5. 两类云仓订单跳过普通佣金、积分和普通商户退款财务，改写农业反向流水与 Outbox。
6. 所有入口先按 `order_product_id` 读取订单绑定，未绑定订单完全保持 CRMEB 原行为。

未支付取消决策由 `FarmOrderCancelAdapter` 在任何恢复动作前返回：

| 策略 | `restore_product_stock` | `restore_activity_stock` | `restore_coupon` | 农业动作 |
| --- | --- | --- | --- | --- |
| `normal` | 是 | 按原活动类型 | 是 | 无 |
| `cloud_primary` | 否 | 否 | 否 | 释放活动 SKU/批次抢购锁定 |
| `cloud_resale` | 是，仅镜像 SKU | 否 | 是，仅实际使用的平台券 | 释放原 FEFO 批次分配 |

取消 Job 只能按该决策调用现有恢复方法；适配器和原逻辑不得各恢复一次。

### 8. 事件、监听器与任务文件

#### 监听器

推荐目录：`crmeb/listens/farm`。

| 类型 | 推荐文件 | 消费事实 |
| --- | --- | --- |
| `N` | `crmeb/listens/pay/CloudFreightPaySuccessListen.php` | 接收 `pay_success_farm_cloud_freight`，规范化已验签金额/交易号并调用支付成功服务 |
| `N` | `CloudOrderPaidListener.php` | 消费事务 Outbox，异步推进首次云仓订单 |
| `N` | `CloudOrderClosedListener.php` | 未支付关闭、库存释放 |
| `N` | `CloudOrderCompletedListener.php` | 邮寄签收、自提核销 |
| `N` | `CloudRefundCompletedListener.php` | 消费统一退款完成 Outbox，推进首次/二次冲正 |
| `N` | `CloudResaleOrderPaidListener.php` | 消费二次订单付款 Outbox |
| `N` | `CloudResaleOrderCompletedListener.php` | 二次订单进入观察期 |
| `N` | `LandOrderPaidListener.php` | 租地订单支付 |
| `N` | `AdoptionOrderPaidListener.php` | 认养订单支付 |
| `N` | `FarmNotificationListener.php` | 领域事件转通知任务 |

这些监听器不得替代 `FarmOrderPaymentAdapter`、`FarmOrderCancelAdapter` 和 `FarmOrderRefundAdapter` 的事务内事实写入。

Outbox 分发后的领域消费组放在 `crmeb/listens/farm/domain/`，一个消费组可以分派同领域内多个事件，但每个处理分支仍按 `event_id + consumer_name` 幂等：

| 类型 | 推荐文件 | 消费范围 |
| --- | --- | --- |
| `N` | `CloudActivityDomainListen.php` | 活动状态、库存闭合和批次准备 |
| `N` | `CloudSupplyDomainListen.php` | 供货、交付、验收、退回和平台承接 |
| `N` | `CloudPrimaryOrderDomainListen.php` | 首次支付、去向、运费、自提、完成和退款 |
| `N` | `CloudResaleDomainListen.php` | FEFO 分配、观察期、有效销售和退款冲正 |
| `N` | `CloudBatchDomainListen.php` | 启动、进度节点、到期、回购和关闭 |
| `N` | `FarmFinanceDomainListen.php` | 用户账本、商户货款、正式入账和冲正 |
| `N` | `FarmRightsDomainListen.php` | 租地/认养付款、预留、分配和替换 |
| `N` | `FarmProductionDomainListen.php` | 生产批次、任务、过程记录和产出 |
| `N` | `FarmFulfillmentDomainListen.php` | 地址、运费、包裹、发货和完成 |
| `N` | `FarmExceptionDomainListen.php` | 异常影响、方案、步骤和闭合 |
| `N` | `FarmTraceDomainListen.php` | 溯源审核、发布、撤回和公开缓存 |
| `N` | `FarmAuditProjectionListen.php` | 非关键列表摘要、统计和审计投影 |

#### 队列任务

推荐目录：`crmeb/jobs/farm`。

| 类型 | 推荐文件 | 说明 |
| --- | --- | --- |
| `N` | `PublishFarmDomainEventJob.php` | 投递一条已抢占的领域事件 |
| `N` | `SendFarmNotificationJob.php` | 发送并记录站内/模板消息 |
| `N` | `PostFarmUserLedgerJob.php` | 用户业务账本映射余额 |
| `N` | `GenerateMerchantSupplyStatementJob.php` | 每日生成商户供货结单 |
| `N` | `PostMerchantSupplyStatementJob.php` | 商户结单映射可用余额和财务流水 |
| `N` | `FarmFinancialPostingRepairJob.php` | 回收超时处理租约并重试可恢复失败 |
| `N` | `RefundCloudFreightJob.php` | 使用原渠道和固定退款单号提交运费全额退款 |
| `N` | `ExecuteCloudBuybackJob.php` | 只执行已人工审核且预检仍有效的回购 |
| `N` | `CloudMaturityFinalizeJob.php` | 在途处置宽限截止后固化所有权切换和回购预案 |
| `N` | `ExecuteFarmExceptionStepJob.php` | 顺序执行异常方案步骤并记录部分失败 |
| `N` | `FarmExceptionConfirmationExpireJob.php` | 按等价校验与超时策略推进待用户确认方案 |
| `N` | `RepairFarmFulfillmentFreightJob.php` | 修复农业运费支付、迟到回调和退款 |
| `N` | `ProductMaterialExpiryJob.php` | 预警商品农业材料到期，并关闭新供货资格 |
| `N` | `ValidateAnimalImportJob.php` | 解析并校验动物资产导入文件，生成脱敏预览和错误文件，不写动物资产 |
| `N` | `ConfirmAnimalImportJob.php` | 校验文件哈希和预览结果未变化后，全批次原子导入动物资产 |
| `N` | `GenerateTraceQrCodeJob.php` | 溯源二维码与静态材料 |
| `N` | `CleanupFarmUnboundAttachmentJob.php` | 清理超期未绑定现场附件，保留已引用业务证据 |

#### 定时任务

CRMEB 当前 `create_timer` 注册的是实现 `ListenerInterface`、继承 `TimerService` 的监听器，不是队列 Job。V1 固定为：

```text
app/event.php create_timer
→ crmeb/listens/farm/timer/*Listen.php 仅按间隔抢占运行并投递
→ crmeb/jobs/farm/*Job.php 实现 JobInterface::fire()/failed()
→ crmeb/services/farm/* 领域服务
```

调度监听器和工作 Job 的文件映射：

| 调度监听器 `crmeb/listens/farm/timer` | 队列 Job `crmeb/jobs/farm` | 领域动作 |
| --- | --- | --- |
| `CloudActivityStatusListen.php` | `CloudActivityStatusJob.php` | 预热、开始、结束活动 |
| `CloudActivityInventoryCloseListen.php` | `CloudActivityInventoryCloseJob.php` | 等未支付释放后关闭未抢库存 |
| `CloudUnpaidReleaseListen.php` | `CloudUnpaidReleaseJob.php` | 修复未支付库存释放 |
| `CloudPaidRepairListen.php` | `CloudPaidRepairJob.php` | 修复付款事实差异 |
| `CloudChoiceReminderListen.php` | `CloudChoiceReminderJob.php` | 去向截止提醒 |
| `CloudChoiceExpireListen.php` | `CloudChoiceExpireJob.php` | 超时自动代销 |
| `CloudFreightExpireListen.php` | `CloudFreightExpireJob.php` | 云仓运费单超时 |
| `CloudFreightPaymentRepairListen.php` | `CloudFreightPaymentRepairJob.php` | 云仓运费支付/退款修复 |
| `CloudBatchStartListen.php` | `CloudBatchStartJob.php` | 冻结选择并启动批次 |
| `CloudPickupOverdueListen.php` | `CloudPickupOverdueJob.php` | 自提逾期协同 |
| `CloudResaleAllocationRepairListen.php` | `CloudResaleAllocationRepairJob.php` | 修复普通订单分配 |
| `CloudResaleReleaseListen.php` | `CloudResaleReleaseJob.php` | 释放未支付二次分配 |
| `CloudResaleEffectiveListen.php` | `CloudResaleEffectiveJob.php` | 观察期后确认有效销售 |
| `CloudRefundSyncListen.php` | `CloudRefundSyncJob.php` | 首次/二次退款差异修复 |
| `CloudMilestoneListen.php` | `CloudMilestoneJob.php` | 最高新节点及真实累计差额 |
| `CloudUserSettlementListen.php` | `CloudUserSettlementJob.php` | 用户账本校验和入账投递 |
| `CloudMerchantEligibilityListen.php` | `CloudMerchantEligibilityJob.php` | 商户货款资格 |
| `CloudMerchantStatementListen.php` | `CloudMerchantStatementJob.php` | 生成自然日结单 |
| `CloudMerchantPostingListen.php` | `CloudMerchantPostingJob.php` | 商户结单入账 |
| `FarmFinancialPostingRepairListen.php` | `FarmFinancialPostingRepairJob.php` | 回收租约和重试 |
| `CloudMaturityListen.php` | `CloudMaturityJob.php` | 到期停止新分配并开始在途处置宽限 |
| `CloudMaturityFinalizeListen.php` | `CloudMaturityFinalizeJob.php` | 宽限截止固化所有权和待审预案 |
| `CloudBuybackListen.php` | `ExecuteCloudBuybackJob.php` | 只执行已审核回购 |
| `CloudReconciliationListen.php` | `CloudReconciliationJob.php` | 订单、库存、账本、资金对账 |
| `CloudSupplyInventoryReconcileListen.php` | `CloudSupplyInventoryReconcileJob.php` | 供货数量守恒 |
| `FarmAllocationRepairListen.php` | `FarmAllocationRepairJob.php` | 已支付未分配修复 |
| `FarmAllocationReservationExpireListen.php` | `FarmAllocationReservationExpireJob.php` | 释放 5 分钟预留 |
| `FarmTaskReminderListen.php` | `FarmTaskReminderJob.php` | 现场任务提醒 |
| `FarmOutputAllocationListen.php` | `FarmOutputAllocationJob.php` | 合格产出分配 |
| `FarmExceptionExecutionListen.php` | `ExecuteFarmExceptionStepJob.php` | 异常方案步骤补偿 |
| `FarmExceptionConfirmationExpireListen.php` | `FarmExceptionConfirmationExpireJob.php` | 异常方案用户确认超时 |
| `FarmExceptionSlaListen.php` | `FarmExceptionSlaJob.php` | 异常 SLA 告警 |
| `FarmFulfillmentReminderListen.php` | `FarmFulfillmentReminderJob.php` | 地址、发货和收货提醒 |
| `FarmFulfillmentFreightRepairListen.php` | `RepairFarmFulfillmentFreightJob.php` | 农业运费差异修复 |
| `ProductMaterialExpiryListen.php` | `ProductMaterialExpiryJob.php` | 商品农业材料到期预警和供货资格收敛 |
| `TraceMaterialExpiryListen.php` | `TraceMaterialExpiryJob.php` | 材料到期预警 |
| `TracePublicCacheRepairListen.php` | `TracePublicCacheRepairJob.php` | 公开指针/缓存修复 |
| `FarmUnboundAttachmentCleanupListen.php` | `CleanupFarmUnboundAttachmentJob.php` | 清理未绑定临时附件 |
| `FarmOutboxDispatchListen.php` | `PublishFarmDomainEventJob.php` | 抢占并投递 Outbox |
| `FarmFailedJobAlertListen.php` | `FarmFailedJobAlertJob.php` | 失败任务告警 |

每个 Listen 只负责固定间隔、队列名、`job_name + run_key` 抢占和任务投递；每个 Job 使用游标、单批上限、租约、超时、重试和业务结果键。`failed()` 必须保留错误并进入告警，不能捕获异常后删除关键任务。频率、分片和修复策略以 `20` 和事件任务操作登记表为准。

### 9. 稳定状态码与常量

现有工程没有统一 `app/common/enums` 目录，V1 不强行引入 PHP 8.1 Enum。推荐使用：

```text
crmeb/services/farm/constants
```

首批文件：

- `CloudActivityStatus.php`
- `CloudBatchStatus.php`
- `CloudDisposition.php`
- `CloudInventoryPool.php`
- `CloudSettlementMode.php`
- `CloudLedgerStatus.php`
- `FarmOrderStatus.php`
- `ProductionStatus.php`
- `TracePublishStatus.php`
- `FarmCoordinateSystem.php`
- `FarmErrorCode.php`

常量值一经发布不得随展示文案变化；前端使用同一份接口字典或人工同步的常量映射。

### 10. 数据升级、菜单与配置

后端目前只有安装 SQL，没有正式迁移目录。G3 需先确认并建立以下约定，再写任何业务建表 SQL：

```text
install/upgrade/farm_v1/
  000_preflight_normalize.sql
  001_schema_up.sql
  001_schema_down.sql
  002_indexes_up.sql
  002_indexes_down.sql
  003_menu_seed.sql
  004_config_seed.sql
  verify_before.sql
  verify_after.sql
  README.md
  process/
    supervisor-farm.conf.example
```

| 类型 | 文件/数据 | 内容 |
| --- | --- | --- |
| `C` | `000_preflight_normalize.sql` | 先输出客服账号空白/重复报告；经发布步骤确认后把 `TRIM(account)=''` 规范化为 `NULL`，不自动合并非空重复账号 |
| `C` | `001_schema_up.sql` | 新增业务表，并只扩容现有余额/流水金额字段，不改历史金额 |
| `C` | `001_schema_down.sql` | 仅供未产生生产数据时回滚 |
| `C` | `002_indexes_up.sql` | 唯一键、状态扫描、FEFO 和数据范围索引 |
| `C` | `003_menu_seed.sql` | 平台、商户页面菜单与按钮权限 |
| `C` | `004_config_seed.sql` | 售后期、超时、批次任务、通知开关、地图服务端密钥占位和三项自动入账阈值 |
| `C` | `verify_before.sql` | 表前缀、字符集、版本、SQL 模式、金额字段容量、旧坐标字段和冲突检查 |
| `C` | `verify_after.sql` | 表、索引、扩容字段、菜单 route name、坐标规范和初始配置检查 |
| `M` | `config/queue.php` | 登记 `farm-critical`、`farm-business`、`farm-notification`、`farm-maintenance` 四条逻辑队列及连接参数 |
| `N` | `config/farm.php` | 农业功能开关、队列名、批量上限、提醒周期和第三方 Provider 选择；不保存真实密钥 |
| `M` | `.example.env` | 只增加农业队列、地图和开关的环境变量占位，不写生产值 |
| `C` | `process/supervisor-farm.conf.example` | 四队列 worker、重启/日志/停止超时示例；进程数由发布环境覆写 |
| `M` | `Dockerfile` | Docker 发布模板增加四队列消费者；仍保留现有 Swoole 与默认队列进程 |
| `M` | `config/swoole.php` | 仅部署决定使用 Swoole task 消费农业队列时登记对应队列；默认独立 worker 时不改 |

`004_config_seed.sql` 至少建立：

| 配置键 | 默认值 | 用途 |
| --- | --- | --- |
| `farm_user_auto_post_single_limit` | `10000.00` | 用户单条自动入账上限 |
| `farm_user_auto_post_daily_limit` | `50000.00` | 单用户自然日自动入账累计上限 |
| `farm_merchant_auto_post_statement_limit` | `100000.00` | 商户单张结单自动入账上限 |
| `farm_merchant_statement_time` | `02:00` | 归集上一自然日供货账本 |
| `farm_financial_posting_lease_seconds` | `300` | 入账处理中租约和故障抢占时间 |
| `farm_tencent_map_server_key` | 空 | 腾讯 WebService 服务端 Key；后台掩码展示，不返回前端 |
| `farm_tencent_map_server_sk` | 空 | 腾讯 WebService 签名密钥；仅后端密钥配置读取 |

现有 `tx_map_key` 继续作为客户端腾讯 GL JS 展示 Key，并配置域名/小程序白名单；不得与服务端 Key/SK 共用明文展示。两个服务端配置保持空默认值，联调与发布时由环境配置注入，迁移文件不写真实密钥。

回滚不得删除已发生交易、持仓或账本的数据。生产环境回滚采用“停用新入口 + 回退应用版本 + 保留扩展表”的方式。

`uk_service_account(account)` 只在空白账号已规范化、非空重复已人工处理后创建；任何启用 PC/移动登录的服务账号必须有非空唯一账号。预检发现重复时升级停止，不自行选择保留哪一条。

## 四、平台管理端 `smartfarm_admin` 改造

### 1. 路由与菜单

| 类型 | 文件 | 改动 |
| --- | --- | --- |
| `M` | `src/router/modules/marketing.js` | 增加“云仓秒杀”页面路由，位置在营销内、与普通秒杀并列 |
| `M` | `src/router/modules/accounts.js` | 增加用户云仓账本、商户供货货款、对账页面 |
| `N` | `src/router/modules/agriculture.js` | 农业资产、租地、认养、生产、履约和溯源路由 |
| `M` | `src/router/index.js` | 导入 `agriculture.js`，具体方式遵循现有模块注册方式 |
| `C` | 后端 `system_menu` | 页面菜单、按钮权限、父子层级和 route name |

菜单显示来自后端权限，但本地 Vue 路由仍需存在；只写菜单数据不能产生页面。

### 2. API 模块

推荐按业务域拆分，避免继续扩大现有 `src/api/marketing.js` 和 `src/api/accounts.js`：

```text
src/api/farm/cloud.js
src/api/farm/agriculture.js
src/api/farm/production.js
src/api/farm/trace.js
src/api/farm/finance.js
src/api/farm/map.js
src/api/farm/support.js
```

| 类型 | 现有文件 | 用法 |
| --- | --- | --- |
| `R` | `src/api/marketing.js` | 参考普通秒杀请求命名和列表格式 |
| `M` | `src/api/product.js` | 商品/SKU 候选选择，并读取平台商品农业资料审核字段 |
| `R` | `src/api/accounts.js` | 参考财务列表、导出和详情交互 |
| `R` | 现有 request 封装 | Token、错误包和下载能力 |

### 3. 云仓页面

```text
src/views/marketing/cloud/
  activity/index.vue
  activity/edit.vue
  activity/detail.vue
  activity/components/ActivityBaseForm.vue
  activity/components/ActivitySkuRuleTable.vue
  supply/index.vue
  supply/detail.vue
  order/index.vue
  order/detail.vue
  pendingChoice/index.vue
  pickup/index.vue
  batch/index.vue
  batch/detail.vue
  resale/index.vue
  resale/detail.vue
  buyback/index.vue
  buyback/detail.vue
  exception/index.vue
  exception/detail.vue
```

复用参考：

- `src/views/marketing/seckill/store_seckill`：活动、场次、统计和活动商品交互。
- `src/views/marketing/seckill/seckillGoods`：商品详情和 SKU 选择。
- 现有商品选择器、上传组件、富文本、表格筛选和分页。

不得直接复制普通秒杀页面后只改标题。云仓页面必须展示批次、去向、预计周期、结算模式、分成、回购和规则快照。

### 4. 农业页面

```text
src/views/farm/
  dashboard/index.vue
  asset/farm/index.vue
  asset/farm/edit.vue
  asset/farm/components/WarehouseTab.vue
  asset/farm/components/WarehouseLocationDrawer.vue
  asset/zone/index.vue
  asset/plot/index.vue
  asset/plot/edit.vue
  asset/plot/map.vue
  asset/pickupPoint/index.vue
  asset/pickupPoint/edit.vue
  asset/enclosure/index.vue
  asset/animal/index.vue
  asset/breedingBatch/index.vue
  catalog/crop/index.vue
  catalog/breed/index.vue
  land/plan/index.vue
  land/plan/edit.vue
  land/order/index.vue
  land/order/detail.vue
  land/allocation/index.vue
  adoption/plan/index.vue
  adoption/plan/edit.vue
  adoption/order/index.vue
  adoption/order/detail.vue
  adoption/allocation/index.vue
  production/batch/index.vue
  production/batch/detail.vue
  production/event/review.vue
  output/batch/index.vue
  output/batch/detail.vue
  fulfillment/index.vue
  fulfillment/detail.vue
  exception/index.vue
  exception/detail.vue
  trace/archive/index.vue
  trace/archive/edit.vue
  trace/review/index.vue
  trace/material/index.vue
  trace/link/index.vue
```

普通商品农业资料不另建一套商品列表，直接落入现有商品审核/详情：

| 类型 | 现有文件 | 改动 |
| --- | --- | --- |
| `M` | `src/views/product/productExamine/index.vue` | 增加农业资料完整性、材料状态和溯源筛选/列 |
| `M` | `src/views/product/productExamine/info.vue` | 审核农业来源和材料，不直接覆盖商户提交事实 |
| `M` | `src/views/product/productExamine/proDetails.vue` | 展示农业资料、证书报告和历史版本 |
| `M` | `src/views/setting/systemAdmin/index.vue` | 在现有管理员操作列增加“农业范围”，打开独立抽屉；不改动态新增/编辑表单 |
| `N` | `src/components/farm/FarmAdminScopeDrawer.vue` | 选择业务域、农场、仓库或显式全部范围，显示版本和授权差异 |

CRMEB 当前平台商品与商户商品审核都落在 `src/views/product/productExamine/`。`ADM-CM-001` 使用自营商品筛选，`ADM-CM-002` 使用商户商品筛选和审核动作；二者是同一页面实现的两个业务视图，不再虚构第二套平台自营商品页面。

管理员农业范围调用 `src/api/farm/support.js`，不把范围字段塞入现有 `system/admin/create/form` 和 `system/admin/update/form/:id`。独立抽屉负责层级选择、全量替换和版本冲突，同时保持 CRMEB 原管理员表单、区域代理和角色权限语义不变。

地图文件边界：

| 类型 | 文件 | 改动 |
| --- | --- | --- |
| `M` | `src/components/map/Map.vue`、`src/components/map/index.js` | 保持旧调用兼容，新增规范化 `longitude/latitude` 输出、加载失败状态和服务端地理编码模式 |
| `N` | `src/components/farm/FarmMapPicker.vue` | 组合地址建议、点选、坐标只读/手工输入、重新定位和失败降级 |
| `N` | `src/api/farm/map.js` | 调用后端地理编码、逆地址和地点建议，不在浏览器直接消耗 WebService Key |
| `R` | 腾讯 GL JS 动态加载能力 | 继续用于地图显示和点选，客户端只使用 `tx_map_key` |

地图只定位农场和自提点；区域、地块、栏舍以继承农场点位和上传示意图为主。V1 不创建 GIS 多边形编辑器、空间面积计算、路线规划或实时轨迹。

### 5. 财务页面

```text
src/views/accounts/farm/
  userLedger/index.vue
  userLedger/detail.vue
  merchantLedger/index.vue
  merchantLedger/detail.vue
  merchantStatement/index.vue
  merchantStatement/detail.vue
  financialPosting/detail.vue
  reconciliation/index.vue
  adjustment/index.vue
```

同时修改：

| 类型 | 现有文件 | 改动 |
| --- | --- | --- |
| `M` | `src/filters/commFilter.js` | 增加“云仓供货结算”财务类型文案 |
| `M` | `src/views/accounts/capitalFlow/index.vue` | 云仓供货流水跳转结单详情，不误判为退款单 |

页面不得提供直接改最终金额的输入框。高风险操作统一采用：

```text
差异/计算预览 -> 填写原因 -> 有权限人员审核 -> 后端按待执行记录重算并执行
```

### 6. 公共组件、状态和工具

| 类型 | 推荐文件 | 作用 |
| --- | --- | --- |
| `N` | `src/components/farm/StatusTag.vue` | 稳定状态码到标签 |
| `N` | `src/components/farm/RuleSnapshot.vue` | 历史规则只读展示 |
| `N` | `src/components/farm/BatchProgress.vue` | 批次数量与里程碑 |
| `N` | `src/components/farm/InventoryPoolTable.vue` | 库存池闭合展示 |
| `N` | `src/components/farm/LedgerFormula.vue` | 公式输入、结果和尾差 |
| `N` | `src/components/farm/TraceTimeline.vue` | 生产/溯源时间线 |
| `N` | `src/components/farm/VersionHistory.vue` | 发布版本和差异 |
| `N` | `src/components/farm/FarmMapPicker.vue` | 地址检索、GCJ02 点位、地图状态和手工降级 |
| `N` | `src/utils/farm/format.js` | 数量、金额、基点和周期格式化 |
| `N` | `src/utils/farm/constants.js` | 前端状态文案和颜色 |
| `N` | `src/utils/farm/actionGuard.js` | 二次确认和版本冲突提示 |

不建议为表单草稿建立全局 Vuex。列表筛选和编辑草稿先保留在页面；只有跨页面未完成流程确有需求时再新增 `src/store/modules/farm.js`。

## 五、商户端 `smartfarm_mer` 改造

### 1. 路由、API 和页面

| 类型 | 文件 | 改动 |
| --- | --- | --- |
| `M` | `src/router/modules/marketing.js` | 增加“云仓供货”入口，与普通秒杀参加活动区分 |
| `M` | `src/router/modules/accounts.js` | 增加“云仓供货货款”和对账 |
| `N` | `src/api/farm/cloud.js` | 供货、验收、履约和数据接口 |
| `N` | `src/api/farm/finance.js` | 货款、结算单和对账接口 |
| `M` | 商户首页实际工作台组件 | `MER-HM-001` 增加供货审核、待交付、履约售后和待入账待办 |
| `M` | `src/views/product/productList/index.vue` | `MER-CM-001` 增加农业资料、材料完整性、溯源和供货资格列/筛选 |
| `M` | `src/views/product/addProduct/index.vue` | `MER-CM-002` 增加农产品来源、报告/证书和溯源资料编辑 |
| `M` | `src/filters/commFilter.js` | 增加“云仓供货结算”财务流水类型 |
| `M` | `src/views/accounts/capitalFlow/index.vue` | 云仓供货流水跳转结单详情，不误跳退款单 |

```text
src/views/marketing/cloudSupply/
  application/index.vue
  application/edit.vue
  record/index.vue
  record/detail.vue
  fulfillment/index.vue
  fulfillment/detail.vue

src/views/accounts/farm/
  supplyLedger/index.vue
  supplyLedger/detail.vue
  supplyStatement/index.vue
  supplyStatement/detail.vue
  reconciliation/index.vue
```

### 2. 复用与隔离

- `src/views/marketing/seckill/store_seckill/join_activity.vue` 只参考信息架构和交互，不复制实现；当前参考页存在未定义变量风险，云仓代码必须独立通过 lint、构建和用例。
- 复用 `src/api/product.js` 和现有商品/SKU 选择器。
- 一张供货申请只绑定一个来源 SKU；多选商品/SKU 时前端创建多张草稿，不提交含多个 SKU 的申请。
- 商户只提交来源商品、SKU、供货价、拟供数量、交付方式、材料和责任方建议；平台审核后固化运费、质量和售后三类责任快照。
- 供货详情展示 `proposed/approved/source_reserved/delivered/pending_inspection/accepted/rejected/shortage/allocated_activity/cloud_available/return_pending/returned/platform_acquired` 数量链和守恒校验，不使用含义不清的单一 `available_qty`。
- 预计代销周期、用户分成、结算模式、回购比例由平台活动配置，不允许商户覆盖。
- 商户页面只展示本商户数据，后端必须再次限定 `merchant_id`，不能只靠前端筛选。
- 商户货款展示首次有效购买、验收、首次售后观察期和扣减，不展示为用户二次代销收益。
- 履约页覆盖详情、发货、物流更正、证据、退回验收和异常上报；只显示后端 `allowed_actions` 允许的动作。
- 结单详情继续展示 `farm_supply_settlement` 入账状态、CRMEB 可用余额流水和原有转账/提现入口；异议、冲正和调整记录不能被导出页省略。

### 3. 商户地图基线整改

当前业务口径不要求商户维护农场、地块或自提点，因此不新增商户农业地图页面。现有商户资料地图缺陷单列为 CRMEB 基线任务：

| 类型 | 文件 | 问题与处理 |
| --- | --- | --- |
| `M` | `src/components/map/map.vue` | 保持旧组件调用兼容，明确内部 `latitude/longitude` 语义和地图失败状态 |
| `M` | `src/views/systemForm/setSystem/modifyStoreInfo.vue` | 修正 `lat/long` 的经纬度标签与赋值方向，提交字段不得误写为 `log` |
| 回归 | `eb_merchant.long/lat` 旧字段适配 | `long` 仍映射经度、`lat` 映射纬度，不迁移成新农业字段 |

该整改不得顺带把商户旧字段改名或改表，以免扩大 CRMEB 店铺资料回归范围。

## 六、用户端 `smartfarm_user` 改造

### 1. API 文件

| 类型 | 文件 | 作用 |
| --- | --- | --- |
| `N` | `api/farmAgriculture.js` | 农场专区、农场公开详情和位置 |
| `N` | `api/farmCloud.js` | 云仓活动、下单、去向、持仓、账本、自提 |
| `N` | `api/farmLand.js` | 租地目录、订单、进度和产出邮寄 |
| `N` | `api/farmAdoption.js` | 认养目录、订单、进度和产出邮寄 |
| `N` | `api/farmException.js` | 本人农业异常方案详情、接受或拒绝 |
| `N` | `api/farmTrace.js` | 溯源查询 |
| `R` | `api/order.js` | 普通订单详情、退款和物流查询 |
| `R` | `api/activity.js` | 仅参考普通秒杀，不在其中混入云仓状态 |

### 2. 集市云仓页面

按用户端复用审计和已确认的 `G4-UI-008`，云仓使用独立 `pages/cloudWarehouse` 分包，不与租地/认养共同塞入 `pages/farm`。

```text
pages/cloudWarehouse/
  index.vue
  detail.vue
  order_confirm.vue
  pay_result.vue
  order_list.vue
  disposition.vue
  freight_pay.vue
  pickup.vue
  holding_list.vue
  holding_detail.vue
  ledger.vue
  ledger_detail.vue
```

页面职责：

- `index.vue`：场次、倒计时、库存、限购和活动状态。
- `detail.vue`：SKU、价格、预计周期、结算模式、回购和三种去向。
- `order_confirm.vue`：云仓专用确认页，一单一活动 SKU，不出现普通券、积分、会员价和分销开关。
- `pay_result.vue`：支付成功后突出“立即选择”和“稍后选择”；稍后选择可继续抢购。
- `order_list.vue`：`USR-CW-005` 专属订单中心，覆盖待支付、待选择、邮寄、自提、代销、售后/退款、关闭和异常，不把云仓完整状态塞入普通订单列表。
- `disposition.vue`：整条明细只能选邮寄、自提或代销；不可拆数量。
- `freight_pay.vue`：复用 CRMEB 地址选择与支付弹层，展示报价、倒计时和支付方式；处理中轮询本地结果，超时回待选择/代销，迟到支付展示原路退款，不允许重复支付。
- `holding_detail.vue`：批次进度、节点、已返本金、收益、未售数量和到期规则。
- `ledger_detail.vue`：`USR-CW-012` 展示来源订单、持仓、批次节点、公式快照、入账/冻结/冲正记录；回购结果作为账本类型和持仓到期区块呈现，不另建 `buyback_detail.vue`。

### 3. 租地、认养和溯源页面

```text
pages/farm/
  index.vue
  farm_detail.vue
  farm_location.vue

pages/farm/land/
  index.vue
  detail.vue
  order_confirm.vue
  my_list.vue
  order_detail.vue

pages/farm/adoption/
  index.vue
  detail.vue
  order_confirm.vue
  my_list.vue
  order_detail.vue

pages/farm/fulfillment/
  detail.vue

pages/farm/trace/
  detail.vue
```

`index.vue` 是公开套餐目录，`my_list.vue` 是登录后的 `USR-LA-004`/`USR-AD-004` 权益列表；两者不得通过页面参数混用权限和空状态。租地/认养产出只提供邮寄到家相关操作，不显示云仓代销按钮。

`USR-LA-005` 与 `USR-AD-005` 的生产时间线、产出和溯源均为权益详情内标签/组件，不再拆成额外路由；两端共用 `pages/farm/fulfillment/detail.vue` 对应唯一 `USR-PD-001`。报告和证书作为 `pages/farm/trace/detail.vue` 内区块。这样文件与冻结的 29 个用户页面对象保持一一对应。

农场位置页使用后端返回的 `longitude/latitude/coordinate_system=GCJ02`，通过现有 `uni.openLocation` 打开导航。页面不自动调用 `uni.getLocation`，用户拒绝当前位置权限时仍可查看公开地址、示意图和复制地址。

H5 和小程序共用页面状态与接口契约，但适配层分别处理支付回跳、地址授权、分享、分包加载和安全区。支付成功页始终重新查询后端本地状态；任何端都不以渠道前端回调直接认定订单成功。租地/认养下单地址只作为合同联系人，产出发货在共享履约详情重新确认地址快照。

### 4. 我的页面与现有订单页

| 类型 | 文件 | 改动 |
| --- | --- | --- |
| `M` | `pages.json` | 注册新页面或分包 |
| `M` | “我的”入口实际组件 | 增加我的云仓、我的租地、我的认养 |
| `M` | `components/payment/index.vue` | 增加安全白名单内的通用 `returnPath`，不写云仓状态机 |
| `M` | `pages/order_pay_back/index.vue` | 支持读取受控回跳目标，默认仍回普通订单 |
| `R` | `pages/users/order_payment/index.vue` | 保持普通订单支付流程，不承担云仓回跳 |
| `M` | `pages/users/order_list/index.vue` | 只增加业务标识和进入专属详情的跳转，不复制云仓全部状态 |
| `M` | `pages/goods_details/index.vue` | `USR-CM-001` 展示已发布产地、供应商、报告/证书和溯源入口 |
| `M` | `pages/order_details/index.vue` | 云仓/农业扩展摘要和专属入口 |
| `R` | 现有地址、物流、退款组件 | 复用基础交互和能力 |

支付组件仍只处理支付渠道，但现有 H5/支付宝路径硬编码普通订单结果页，因此必须以最小修改增加白名单 `returnPath`。云仓确认页传入 `pages/cloudWarehouse/pay_result.vue`；支付结果页再查询后端 `next_action`，支付组件本身不知道“选择去向”等业务语义。

### 5. 用户端公共组件

先复用下列现有组件，不建立第二套基础组件：

| 复用类型 | 现有文件 | 用途 |
| --- | --- | --- |
| `R` | `components/common/base_container.vue` | 安全区、胶囊尺寸、页面最小高度和 CSS 变量 |
| `R` | `components/common/base_nav_bar.vue` | 小程序/APP 自定义导航 |
| `R` | `components/priceFormat.vue` | 金额格式 |
| `R` | `components/easyLoadimage/easyLoadimage.vue` | 图片加载与占位 |
| `R` | `components/countDown/index.vue` | 倒计时 |
| `R` | `components/emptyPage.vue`、`components/Loading/index.vue`、skeleton | 空、加载和骨架状态 |
| `R` | `components/productConSwiper/index.vue`、`components/jyf-parser/jyf-parser.vue` | 轮播与富文本 |
| `R` | `uni_modules/uni-popup`、`uni_modules/uni-datetime-picker` | 弹层和日期时间选择 |
| `R` | `uni.openLocation` 与现有位置调用方式 | 使用保存的目标点位打开系统/腾讯导航，不新增地图插件 |
| `E` | `components/productWindow/index.vue` | 复用 SKU、数量和库存交互，不复用普通商品业务 |
| `E` | `components/addressWindow/index.vue`、`pages/users/order_confirm/components/AddressSelector.vue` | 邮寄提货地址 |
| `E` | `sub-packages/diy/diyPage/seckill.vue` | 只参考倒计时和商品展示，云仓使用独立 API |

只有现有组件无法表达的领域能力才考虑新增：

```text
components/farm/
  CloudRuleSummary.vue
  CloudDispositionSelector.vue
  CloudSettlementTimeline.vue
  CloudBatchProgress.vue
  ProductionTimeline.vue
  OutputShipmentCard.vue
  TraceArchive.vue
  FarmLocationCard.vue
```

上述清单仍是候选，不要求每个名称都落成独立组件。低保真评审时如果只是现有标签、列表或卡片的简单组合，应直接在页面中组合，不额外抽象。

### 6. 用户端现状缺陷前置任务

以下任务与智慧农业需求分开管理，但会影响复用和联调：

| 类型 | 文件/配置 | 问题 |
| --- | --- | --- |
| `M` | `libs/login.js` | 默认登录路径 `/page/users/login/index` 与实际 `pages` 目录不一致 |
| `M` | `libs/order.js`、`pages/activity/goods_seckill_details/index.vue` | 秒杀跳转使用 `time`，详情读取 `time_id` |
| `M` | `pages/users/order_confirm/index.vue` | 移除残留 `debugger` 并回归普通下单 |
| `M` | `store/modules/location.js`、`utils/util.js` | 现有 WGS84 定位与腾讯 GCJ02 使用存在错配风险，单独回归后收口，不在农业页面中静默改全站行为 |
| 配置修复 | `manifest.json` 及环境配置 | 地图 Key 当前存在客户端硬编码；迁移为环境绑定的客户端 Key，禁止写入服务端 Key/SK |
| 配置修复 | 当前平台 DIY 导航 | “种草社区”错误指向普通秒杀页面 |

不要在智慧农业页面任务中顺手扩展为用户端大范围重构。

当前 uni-app 版本不作为农场位置页的升级前置条件。若后续必须启用 H5 当前定位或距离计算，再单独评估升级到 DCloud 当前兼容版本，并回归登录、支付、分包、地图和小程序构建。

需完整设计骨架屏、空状态、活动结束、库存不足、重复支付结果、规则版本冲突、去向已冻结、批次暂停和账本冻结状态。

## 七、服务端 `smartfarm_service` 改造

`SPIKE-006` 已确认：复用现有客服身份和 `SerToken`，在同一前端项目保留原 PC 客服页并新增农业桌面、移动现场两个独立布局。以下文件清单不再等待身份方案选择。

### 1. 后端认证、授权与路由

| 类型 | 文件 | 改动 |
| --- | --- | --- |
| `M` | `app/common/middleware/ServiceTokenMiddleware.php` | 每请求增加 `status`、`is_del` 校验，修正无意义变量捕获，保持 `service` guard |
| `N` | `app/common/middleware/FarmServicePermissionMiddleware.php` | 读取路由权限码，校验农业档案、职责和动作权限 |
| `N` | `crmeb/services/farm/support/FarmServicePolicy.php` | 版本化职责到权限码映射和权限判定 |
| `N` | `app/common/model/farm/support/FarmServiceProfile.php` | 农业工作区一对一档案 |
| `N` | `app/common/dao/farm/support/FarmServiceProfileDao.php` | 档案查询与版本更新 |
| `N` | `app/common/repositories/farm/support/FarmServiceProfileRepository.php` | 上下文、启停和默认工作区 |
| `N` | `app/common/model/farm/support/FarmServiceScope.php` | 职责与对象范围模型 |
| `N` | `app/common/dao/farm/support/FarmServiceScopeDao.php` | 当前有效范围查询 |
| `N` | `app/common/repositories/farm/support/FarmServiceScopeRepository.php` | `scopeQuery()`、`assertScopedObject()` 和范围归属链 |
| `M` | `app/controller/admin/system/service/StoreService.php` | 修复账号、密码、登录开关等表单参数的接收、校验、加密和持久化，再增加 PC/移动入口与农业档案维护 |
| `M` | `app/common/repositories/store/service/StoreServiceRepository.php` | 平台账号唯一校验、农业上下文关联和状态变更失效 |
| `M` | `app/validate/merchant/StoreServiceValidate.php` | 账号、密码和登录开关校验规则统一 |
| `M` | `app/controller/service/Service.php` | 修复 `getOrderInfo`、`orderStatus`、`getRefundOder`、`orderExpress`、`refundOrderExpress`、`product` 六个按 ID 读取，统一使用当前商户/显式平台授权范围 Repository；越界按不存在 |
| `M` | `route/service.php` | 在原 `/ser` 组内增加 `farm/*` 静态路由和逐路由权限中间件 |

路由顺序固定为 `ServiceTokenMiddleware -> FarmServicePermissionMiddleware -> Controller`。权限中间件不拼接领域 SQL；列表、详情和写事务分别调用范围 Repository。商户服务人员的 `all` 只代表当前 `mer_id` 内全部。

数据库迁移任务：

| 类型 | 对象 | 内容 |
| --- | --- | --- |
| `N` | `eb_farm_service_profile` | 工作区启用、默认入口、移动开关、`scope_version` |
| `N` | `eb_farm_service_scope` | 职责、对象范围、有效期、授权与撤销 |
| `M` | `eb_store_service` | 先把 `TRIM(account)=''` 规范化为 `NULL`，再检查非空重复；启用登录的账号强制非空，最后新增 `uk_service_account(account)` |

### 2. 前端入口、路由和上下文

| 类型 | 文件 | 改动 |
| --- | --- | --- |
| `M` | `src/router/index.js` | 导入 `farm.js` 静态数组并在末尾通配路由之前展开，保留 `/kefu/dashboard` |
| `N` | `src/router/farm.js` | 导出 `/kefu/farm/desk/*`、`/kefu/farm/work/*` 静态路由与 `meta.permission` |
| `M` | `src/permission.js` | 作为实际生效守卫加载农业上下文；`adminInfo`/上下文失败不得继续放行，区分 401、无页面权限和范围变化 |
| `N` | `src/store/modules/farmContext.js` | 缓存工作区、职责、权限、范围摘要和 `scope_version` |
| `M` | `src/store/getters.js` | 暴露农业上下文与权限判断 |
| `N` | `src/api/farm.js` | 上下文、客服查询、任务、扫码、生产、产出、仓储、履约和异常 API |
| `N` | `src/api/farmReview.js` | 生产/产出审核队列、详情、通过和驳回 |
| `N` | `src/api/farmAttachment.js` | 证据上传、重试和附件绑定结果 |
| `M` | `src/api/request.js` | 保持 `X-Token`，识别稳定农业错误码并避免权限错误误清 Token |
| `M` | `src/views/login/index.vue` | `SVC-AU-001` 保持现有登录交互，修正固定宽度并补移动视口，不改变认证方式 |
| `N` | `src/views/entry/index.vue` | 多工作区选择；旧客服账号不经过此页 |
| `N` | `src/views/farm/profile/index.vue` | `SVC-AU-003` 账号、职责、范围摘要、能力、工作区切换和退出 |
| `R` | `src/utils/auth.js` | PC 与移动继续共用 `SerToken` |
| `R` | `src/views/kefu/pc/index.vue` | 原三栏客服工作台不改成响应式 |

登录后默认入口由 `farm/context` 与人员配置共同决定；本机记住的最近工作区仅用于跳转。没有农业档案的原账号仍进入 `/kefu/dashboard`，保证客服回归边界。

现有 `src/store/modules/permission.js` 引用了不存在的 `asyncRoutes`，V1 不依赖该模块生成农业路由。它作为独立基线缺陷修复或明确停用；农业权限展示由实际守卫、静态路由 `meta.permission` 和 `farmContext` 完成，后端权限/范围仍是最终边界。

### 3. 农业桌面工作区

| 类型 | 文件 | 页面 |
| --- | --- | --- |
| `N` | `src/layout/farmDesktop/index.vue` | 农业桌面壳、导航、人员和范围摘要 |
| `N` | `src/layout/farmDesktop/components/FarmSidebar.vue` | 按权限显示桌面菜单 |
| `N` | `src/layout/farmDesktop/components/FarmHeader.vue` | 工作区切换、账号和范围变化提示 |
| `N` | `src/views/farm/desk/order/index.vue` | `SVC-CM-001` 农业订单搜索 |
| `N` | `src/views/farm/desk/order/detail.vue` | 租地/认养关系详情 |
| `N` | `src/views/farm/desk/cloud/index.vue` | `SVC-CW-001` 云仓订单搜索 |
| `N` | `src/views/farm/desk/cloud/detail.vue` | 首次订单到持仓/账本关系图 |
| `N` | `src/views/farm/desk/exception/index.vue` | `SVC-CW-002` 异常列表 |
| `N` | `src/views/farm/desk/exception/detail.vue` | 事实、动作、通知、建议和审计 |
| `N` | `src/views/farm/desk/review/index.vue` | `SVC-PD-007` 被授权生产/产出审核队列 |
| `N` | `src/views/farm/desk/review/detail.vue` | 内容、数量方程、证据、历史版本和审核动作 |

桌面端直接复用 Element UI 表格、表单、抽屉、分页和消息反馈，不复制管理端组件源码。页面只引入农业对象摘要、关系时间线和范围提示等领域组件。

### 4. 移动作业工作区

| 类型 | 文件 | 页面/职责 |
| --- | --- | --- |
| `N` | `src/layout/farmMobile/index.vue` | 移动单列壳、安全区和离线横幅 |
| `N` | `src/layout/farmMobile/components/FarmMobileHeader.vue` | 当前任务/对象和返回 |
| `N` | `src/layout/farmMobile/components/FarmMobileTabbar.vue` | 任务、扫码、草稿、我的 |
| `N` | `src/layout/farmMobile/components/FarmStickyActions.vue` | 固定提交操作区 |
| `N` | `src/views/farm/work/task/index.vue` | `SVC-PD-001` 我的任务 |
| `N` | `src/views/farm/work/task/detail.vue` | 任务对象、要求和可执行动作 |
| `N` | `src/views/farm/work/scan/index.vue` | `SVC-PD-002` 摄像头、图片和手工扫码 |
| `N` | `src/views/farm/work/production/event.vue` | `SVC-PD-003` 过程记录 |
| `N` | `src/views/farm/work/output/edit.vue` | `SVC-PD-004` 采收/产出 |
| `N` | `src/views/farm/work/warehouse/index.vue` | `SVC-PD-005` 仓储任务 |
| `N` | `src/views/farm/work/warehouse/receive.vue` | 入库验收 |
| `N` | `src/views/farm/work/fulfillment/pack.vue` | 拣货与打包 |
| `N` | `src/views/farm/work/fulfillment/ship.vue` | 出库和运单 |
| `N` | `src/views/farm/work/pickup/verify.vue` | 云仓自提核销；复用 `CW_PICKUP_VERIFY` |
| `N` | `src/views/farm/work/exception/edit.vue` | `SVC-PD-006` 异常上报 |
| `N` | `src/views/farm/work/draft/index.vue` | `SVC-PD-008` 当前账号本机草稿、媒体状态、恢复和删除 |
| `N` | `src/views/farm/work/profile/index.vue` | `SVC-AU-003` 移动版我的与职责范围 |

移动端不增加整套 UI 框架。日期、时间、数量优先使用原生控件；复用请求、Token、上传、SVG/Iconfont 和格式化逻辑，新增以下小型领域组件：

| 类型 | 文件 | 说明 |
| --- | --- | --- |
| `N` | `src/components/farm/FarmObjectSummary.vue` | 对象编号、地点、状态和版本 |
| `N` | `src/components/farm/FarmTaskStatus.vue` | 图标 + 文字任务状态 |
| `N` | `src/components/farm/FarmEvidenceUploader.vue` | 压缩、重试、待上传和附件 ID |
| `N` | `src/components/farm/FarmQuantityEquation.vue` | 总量与合格/损耗/待检实时校验 |
| `N` | `src/components/farm/FarmQrScanner.vue` | `@zxing/browser@0.1.5` + `@zxing/library@0.21.3` 摄像头/图片识别与手工降级 |
| `N` | `src/components/farm/FarmLocationSummary.vue` | 地址、示意图、复制/导航和可选腾讯 GL 点位；加载失败不阻断作业 |
| `N` | `src/components/farm/FarmScopeChanged.vue` | 授权变化阻断与刷新 |
| `N` | `src/utils/tencentMapLoader.js` | 按需加载腾讯 GL JS、复用客户端 Key，并对重复加载和失败统一收口 |
| `N` | `src/utils/farmDraft.js` | IndexedDB 按账号、对象和 schema 版本隔离 JSON 与 Blob，含迁移、容量和清理策略 |
| `M` | `package.json`、`package-lock.json` | 精确锁定上述两版，不使用 `latest`，不引入整套移动 UI 框架 |

服务/现场端不获取人员实时位置，也不建设签到或轨迹。任务对象返回结构化地址与可公开 GCJ02 点位；没有 Key、地图加载失败或浏览器不支持时，仍提供地址、示意图、复制和外部导航，扫码、记录和提交不受影响。

依赖版本选择依据：`0.1.5` 使用 CommonJS/ESM/ES2015 构建并以 `@zxing/library ^0.21.0` 为 peer，较新的 `0.2.x` 已提高 peer 基线。真正写入依赖前必须在当前 Vue 2.6、Vue CLI 3.5、Webpack 4 项目完成一次隔离 Spike：生产构建、HTTPS 摄像头、后置摄像头选择、图片识别、拒权/无摄像头降级、组件卸载后释放视频流、包体积变化。任一项失败则保留图片上传和手工码，不让扫码依赖阻塞核心作业。

V1 本机草稿没有服务端 CRUD。草稿保存、恢复和删除都在 `farmDraft.js` 完成；恢复时重新请求对象详情并比对 `scope_version`、对象 `version` 和任务状态。附件先经 `FarmEvidenceUploader.vue` 上传取得临时附件 ID，再随业务提交绑定；未绑定附件由后端定时清理，前端不得把上传 URL 当成永久业务证据。

### 5. 明确不改

| 类型 | 文件/能力 | 原因 |
| --- | --- | --- |
| `X` | 新建服务人员账号表或第二套 JWT guard | 复用现有身份已满足 V1 |
| `X` | 把现场工作区放进 `smartfarm_user` | 消费者与工作人员安全边界不同 |
| `X` | 把三栏客服页压缩成移动布局 | 现有最小宽度约 `1000px` |
| `X` | 引入平台/商户动态菜单体系 | 服务端使用稳定权限码更小、更可测 |
| `X` | 现场端结算、回购和最终异常决策 | 高风险动作保留平台端 |

## 八、普通商城回归边界

### 1. 必须保持不变

- 普通商品创建、编辑、上下架和 SKU 库存。
- 普通秒杀、拼团、预售、助力、积分商品。
- 普通购物车、订单确认、支付、发货、收货和售后。
- 平台券、商户券、会员价、积分和分销在普通商城中的原行为。
- 商户普通订单结算、账单和提现。
- 客服现有聊天和订单查询。

### 2. 必须新增回归

| 风险点 | 回归要求 |
| --- | --- |
| 普通订单创建适配点 | 未映射 SKU 的 SQL、库存和订单结果与改造前一致 |
| 订单组策略 | 普通与 `farm_managed` 不得进入同一 `group_order_id`；普通多商户订单仍按原逻辑创建 |
| 映射 SKU 下单 | 云仓分配与普通订单同事务，失败无残留 |
| 支付事务内副作用 | 普通商户锁定款/净收入、商品/活动状态和订单支付事实与改造前一致 |
| 支付提交后副作用 | 普通订单打印、商户/用户短信、赠券、积分、会员值、推广资格、用户-商户关系、支付统计和数据大屏均保持原行为 |
| 普通履约类型 | 快递、同城配送、电子面单、卡密和自提不因策略解析改变 |
| 未支付关闭 | 普通商品库存、活动库存和优惠券按原逻辑恢复；云仓首次/二次各只恢复自己的库存源且不重复 |
| 退款申请/拒绝/取消 | 三个申请入口和拒绝/取消均冻结、解冻正确，普通订单保持原流程 |
| 退款执行前财务 | `normal` 仍扣应扣商户锁定款，`farm_managed` 在 `executeRefund()` 前跳过 |
| 部分退款 | 分配数量、金额、平台券承担和批次流水一致 |
| 全额退款 | 不产生有效销售和用户收益；普通库存、佣金、积分与券保持原逻辑 |
| 渠道退款重试 | 重复回调、渠道重试和 `refundAfter()` 重入不重复库存/财务副作用 |
| 普通营销活动 | `cloud_only` SKU 被禁止参加不支持的活动 |
| 商品编辑 | 已发布云仓映射不因来源规格重建而失联 |
| 用户财务映射 | 与充值、消费并发不丢更新；重复任务不重复入余额或 `UserBill` |
| 商户财务映射 | 与普通订单解冻并发不丢更新；重复结单不重复入余额或 `FinancialRecord` |
| 金额字段扩容 | 普通充值、余额支付、普通商户结算、提现和财务报表保持原行为 |

## 九、实施任务依赖顺序

```mermaid
flowchart TD
    A["G3 决策与字段字典冻结"] --> B["数据升级规范与基础表"]
    B --> C["Model / DAO / Repository"]
    C --> D["领域事务 Service"]
    D --> E["路由 / Controller / Validate"]
    D --> F["CRMEB 核心适配点"]
    E --> G["事件 / 队列 / 定时任务"]
    F --> G
    E --> H["平台端与商户端"]
    E --> I["用户端"]
    E --> J["服务端"]
    G --> K["联调、对账与故障演练"]
    H --> K
    I --> K
    J --> K
```

建议开发包：

| 包 | 内容 | 前置 |
| --- | --- | --- |
| `BE-00` | 基础表、幂等、Outbox、审计、状态常量 | G3 字段冻结 |
| `BE-CW-01` | 供货、活动和批次草稿 | `BE-00` |
| `BE-CW-02` | 首次抢购、支付后去向和持仓 | `BE-CW-01` |
| `BE-CW-03` | 二次库存桥接、普通订单分配和观察期 | `BE-CW-02` |
| `BE-CW-04` | 节点结算、回购和商户货款 | `BE-CW-03` |
| `BE-AG-01` | 农业资产、套餐和权益订单 | `BE-00` |
| `BE-AG-02` | 分配、生产、产出和履约 | `BE-AG-01` |
| `BE-AG-03` | 溯源、异常和通知 | `BE-AG-02` |
| `FE-ADM` | 平台管理端 | 对应后端接口稳定 |
| `FE-MER` | 商户端 | `BE-CW-01/04` |
| `FE-USER-CW` | 用户云仓 | `BE-CW-02/03/04` |
| `FE-USER-AG` | 用户租地认养 | `BE-AG-01/02/03` |
| `FE-SVC` | 服务/现场端 | `BE-AG-02`、异常接口 |

## 十、每个文件任务的标准卡片

后续写入任务管理工具时，每张卡必须包含：

| 字段 | 要求 |
| --- | --- |
| 任务编号 | 如 `BE-CW-02-API-03` |
| 业务规则 | 关联 `12` 的决策编号 |
| 页面/API | 关联页面编号和 `19` 的接口 |
| 数据对象 | 明确读写表和字段 |
| 文件范围 | 新增、修改、复用文件 |
| 事务边界 | 哪些写入必须一起成功 |
| 幂等键 | 重复请求/事件的预期结果 |
| 权限与范围 | 角色、route name、商户/农场范围 |
| 正常验收 | Given/When/Then |
| 异常验收 | 超时、退款、并发、冻结、冲正 |
| 回归范围 | 受影响 CRMEB 原功能 |
| 依赖 | 前置任务、第三方配置和原型 |
| 负责人 | 后端、前端、测试和评审人 |

## 十一、文件级决定状态摘要

本节是文件蓝图中的摘要。完整理由、状态、专项验证和签字位置统一见 [24-g3-g4-decision-register.md](24-g3-g4-decision-register)，两处冲突时以 `24` 为准。

| 编号 | 决定项 | 当前方案 | 状态 |
| --- | --- | --- | --- |
| `G3-CODE-001` | 云仓二次销售商品映射 | 建立平台二次代销映射 SKU，`cloud_only`，不混普通库存 | 已确认 |
| `G3-CODE-002` | 用户首次购买优惠 | V1 关闭券、积分、会员价和分销，只保留支付方式 | 已确认 |
| `G3-CODE-003` | 用户结算入账账户 | 业务账本经 `FarmFinancialPosting` 原子映射现有可用余额和 `UserBill` | 已确认 |
| `G3-CODE-004` | 补运费支付载体 | 独立运费单使用 `attach=farm_cloud_freight` 复用支付/退款驱动；超时迟到支付全额退款，不改原商品订单 | 已确认 |
| `G3-CODE-005` | 数据升级规范 | 建立 `install/upgrade/farm_v1` 的版本化 up/down/verify 脚本；业务事实产生后只关入口不删表 | 已确认 |
| `G3-CODE-006` | 服务端身份 | 复用客服账号，新增职责、权限码、对象范围和 PC/移动双入口 | 已由 `SPIKE-006` 确认 |
| `G3-CODE-007` | 自动账本入账阈值 | 零差异且在用户/商户默认阈值内自动入账，异常或超限必须审核 | 已确认 |
| `G3-CODE-008` | GIS 深度 | 腾讯地图 + GCJ02；农场/自提点真实点位，区域/地块示意；不做专业 GIS 编辑器 | 已由 `SPIKE-007` 确认 |

## 十二、G4 评审通过标准

- [ ] 每个 V1 页面都有对应 Controller、API 模块和页面文件。
- [ ] 每个写接口都能定位到 Validate、Service、Repository 和事务边界。
- [ ] 每张新增表都有 Model、DAO、Repository 或明确只写流水的访问方式。
- [ ] 普通订单、退款、支付和余额的修改点已限制在最小范围。
- [ ] 事件、任务、通知和审计文件与 `20` 一一对应。
- [ ] 平台、商户、用户、服务端的数据范围均有后端校验位置。
- [ ] 所有金额、库存和状态变更都有幂等键与重算方法。
- [ ] 数据升级、验证和生产回滚方式已确认。
- [ ] 普通商城回归清单已转成测试用例。
- [ ] 文件任务已分配负责人、前置依赖和评审人。

## 十三、关联文档

- [12-v1-business-decisions-and-glossary.md](12-v1-business-decisions-and-glossary)
- [15-v1-data-model-draft.md](15-v1-data-model-draft)
- [16-pre-development-design-plan.md](16-pre-development-design-plan)
- [17-v1-information-architecture.md](17-v1-information-architecture)
- [18-v1-page-and-prototype-spec.md](18-v1-page-and-prototype-spec)
- [19-v1-api-contract-draft.md](19-v1-api-contract-draft)
- [20-v1-events-jobs-permissions-notifications.md](20-v1-events-jobs-permissions-notifications)
- [22-v1-test-acceptance-release-manual-plan.md](22-v1-test-acceptance-release-manual-plan)
- [23-crmeb-visual-baseline-audit.md](23-crmeb-visual-baseline-audit)
- [24-g3-g4-decision-register.md](24-g3-g4-decision-register)
- [25-user-uniapp-reuse-audit.md](25-user-uniapp-reuse-audit)