Skip to content

21 v1 code change blueprint

Jump to bottom
技术老胡 edited this page Jul 30, 2026 · 2 revisions

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 为准。

编号 决定 原因
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 一致。
  • 普通请求锁中间件只能防短时间重复点击，金额和库存接口仍需业务幂等键。

四端均注册相对路径 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 为主对象，农业资料和证书报告使用薄扩展表：

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。

云仓聚合

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

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 查询都必须显式接受平台、商户、用户或数据范围条件。

农业经营聚合

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

推荐新建：

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 规范建立，推荐目录为：

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 幂等；余额退款在同一事务回款并写用户账单，在线渠道提交成功后再按渠道结果更新退款状态。
  5. 两个服务都先检查目标字段容量和自动审核阈值；成功记录再次调用直接返回首次结果。
  6. 不修改 UserRepository::changeNowMoney、充值回调或 AutoUnlockMerchantMoneyListen 承担云仓入账。
  7. FinancialRecord 使用 financial_type=farm_supply_settlement、type=0；结单主键和结单号分别写入其 order_id/order_sn。
  8. 反向调整只能调用 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 固定为：

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。推荐使用：

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：

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：

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. 云仓页面

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. 农业页面

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. 财务页面

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 云仓供货流水跳转结单详情，不误判为退款单

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

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

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 云仓供货流水跳转结单详情，不误跳退款单 
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。

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. 租地、认养和溯源页面

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

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

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
金额字段扩容 普通充值、余额支付、普通商户结算、提现和财务报表保持原行为

九、实施任务依赖顺序

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
Loading

建议开发包：

包 内容 前置
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-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 一一对应。
  • 平台、商户、用户、服务端的数据范围均有后端校验位置。
  • 所有金额、库存和状态变更都有幂等键与重算方法。
  • 数据升级、验证和生产回滚方式已确认。
  • 普通商城回归清单已转成测试用例。
  • 文件任务已分配负责人、前置依赖和评审人。

十三、关联文档

SmartFarm 文档

Clone this wiki locally