Skip to content

21 v1 code change blueprint

Jump to bottom
技术老胡 edited this page Jul 29, 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。
  • 服务端只有较轻的客服工作台和静态路由，没有完整的动态菜单与细粒度业务权限。
  • 后端没有正式数据库迁移框架，也没有现成 PHPUnit 测试依赖；不能假定已有迁移和自动化测试体系。

2. 架构决定

编号 决定 原因
ADR-001 新农业领域统一使用 farm 命名空间 与 CRMEB 商城域隔离，便于识别影响范围
ADR-002 云仓活动、批次、持仓和账本使用独立表 不扩大原 product_type、activity_type 的全局分支
ADR-003 云仓首次购买使用独立编排入口，复用支付、订单、退款基础能力 首次购买存在延后选去向、独立库存和业务账本
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-008 的推荐落地是由平台运营建立“二次代销商品映射 SKU”：前台仍是普通商城商品页面和普通订单，但该 SKU 的可售库存完全来自云仓桥接池。V1 不允许一个 SKU 同时消耗商户普通库存和云仓库存。该决定需要在 G3 评审中正式签字。

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

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/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/Enclosure.php 栏舍/蜂场
N app/controller/admin/farm/asset/AnimalAsset.php 单体动物资产
N app/controller/admin/farm/catalog/Crop.php 作物与品种目录
N app/controller/admin/farm/catalog/Breed.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/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 溯源档案、版本和关联

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/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/CloudPickup.php 自提码和核销状态
N app/controller/api/farm/cloud/CloudHolding.php 我的持仓、进度和回购
N app/controller/api/farm/cloud/CloudLedger.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/trace/Trace.php 用户可见溯源档案

服务/现场端

类型 推荐文件 对应职责
N app/controller/service/farm/CloudException.php 客服查询和提交处理建议
N app/controller/service/farm/ProductionEvent.php 现场过程记录草稿与提交
N app/controller/service/farm/OutputBatch.php 采收/产出录入
N app/controller/service/farm/FarmFulfillment.php 拣货、发货、核销和异常

4. Validate

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

类型 目录 首批验证器
N app/validate/admin/farm/cloud CloudActivityValidate、CloudActivityProductValidate、CloudSupplyValidate、CloudBuybackValidate、CloudLedgerAdjustValidate
N app/validate/admin/farm/agriculture FarmAssetValidate、LandPlanValidate、AdoptionPlanValidate、ProductionEventValidate、OutputBatchValidate、TraceVersionValidate
N app/validate/merchant/farm/cloud CloudSupplyValidate、CloudSupplySubmitValidate、CloudFulfillmentValidate
N app/validate/api/farm/cloud CloudOrderValidate、CloudDispositionValidate、CloudFreightValidate、CloudRefundValidate
N app/validate/api/farm/agriculture LandOrderValidate、AdoptionOrderValidate、OutputShipmentValidate

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

5. Model、DAO 与 Repository

云仓聚合

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

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
CloudActivityProduct eb_farm_cloud_activity_product
CloudActivitySku eb_farm_cloud_activity_sku
CloudBatch eb_farm_cloud_batch
CloudInventoryFlow eb_farm_cloud_inventory_flow
CloudOrderItem eb_farm_cloud_order_item
CloudFreightOrder eb_farm_cloud_freight_order
CloudHolding eb_farm_cloud_holding
CloudResaleStock eb_farm_cloud_resale_stock
CloudResaleAllocation eb_farm_cloud_resale_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

Repository 职责约束：

  • CloudActivityRepository 负责列表、详情和配置持久化，不直接执行批次结算。
  • CloudBatchRepository 提供带行锁的候选批次查询、汇总重算和状态条件更新。
  • CloudInventoryFlowRepository 只追加流水，并用 idempotency_key 防重。
  • CloudResaleStockRepository 负责二次可售桥接汇总，不代替批次流水。
  • CloudUserLedgerRepository 保存计算结果和状态，不在 Model 事件中直接改余额。
  • 所有 *_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
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
ProductionBatch eb_farm_production_batch
ProductionEvent eb_farm_production_event
OutputBatch eb_farm_output_batch
OutputAllocation eb_farm_output_allocation
FarmFulfillment eb_farm_fulfillment
FarmExceptionEvent eb_farm_exception_event
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

云仓 Service

类型 推荐文件 事务职责
N CloudActivityPublishService.php 发布校验、规则快照、批次草稿和供货占用
N CloudOrderCreateService.php 抢购校验、首次订单、库存锁定和幂等
N CloudOrderPaidService.php 支付成功后首次库存确认和选择截止
N CloudDispositionService.php 单一去向冻结、履约/持仓创建
N CloudFreightService.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 CloudReconciliationService.php 只读重算、差异预览和审核修复

农业 Service

类型 推荐文件 事务职责
N LandOrderCreateService.php 套餐快照、交易扩展和支付后权益
N PlotAllocationService.php 真实地块容量锁和占用
N AdoptionOrderCreateService.php 套餐快照、单体/份额权益
N AdoptionAllocationService.php 个体排他或批次份额分配
N ProductionBatchService.php 权益、资产与生产批次关联
N ProductionEventPublishService.php 审核、发布版本和用户可见性
N OutputAllocationService.php 合格产出按权益分配
N FarmFulfillmentService.php 分批邮寄、物流、签收和售后
N TracePublishService.php 溯源版本、材料和二维码关联
N FarmExceptionService.php 减产、替换、延期、补发和退款方案

支撑 Service

类型 推荐文件 作用
N FarmIdempotencyService.php 命令幂等记录
N FarmOutboxService.php 事务内写事件事实
N FarmAuditService.php 高风险操作审计
N FarmNotificationService.php 通知模板、发送和去重
N FarmMoneyService.php 金额、基点、累计差额和尾差规则
N FarmStateMachineService.php 统一校验状态迁移

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

app/common/model/farm/support
app/common/dao/farm/support
app/common/repositories/farm/support
实体 主表
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
FarmServiceScope eb_farm_service_scope

7. CRMEB 核心适配点

类型 现有文件 计划改动 风险与限制
M app/event.php 注册农业监听器和定时任务 不改变现有监听顺序
M app/common/repositories/store/order/StoreOrderCreateRepository.php 普通订单明细创建事务中调用云仓二次库存适配器 仅映射为 cloud_only 的 SKU 进入逻辑
M app/common/repositories/store/order/StoreRefundOrderRepository.php 在真实退款完成后产生统一适配事件 必须覆盖用户、商户和平台各退款入口
R app/common/repositories/store/order/StoreOrderRepository.php 复用支付成功、收货/核销等既有事件 先由监听器重查数据，非必要不修改
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 用户余额和 UserBillRepository 最终入账映射 业务账本先成功，再按幂等键入余额
R 商户财务、结算单和 FinancialRecordRepository 商户货款映射 不用二次零售进度拖延商户货款

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

  1. 只对明确映射到 eb_farm_cloud_resale_stock 且状态可售的 SKU 执行。
  2. 在普通订单核心事务内完成 FEFO 批次锁定和分配。
  3. 核心订单创建失败时，云仓分配和库存流水一起回滚。
  4. 普通 SKU 未映射时不额外查询全部云仓表，避免拖慢普通订单。
  5. 不在支付成功后重新挑选批次；支付只推进已锁定分配状态。

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

监听器

推荐目录：crmeb/listens/farm。

类型 推荐文件 消费事实
N CloudOrderPaidListener.php 首次云仓订单支付成功
N CloudOrderClosedListener.php 未支付关闭、库存释放
N CloudOrderCompletedListener.php 邮寄签收、自提核销
N CloudRefundCompletedListener.php 首次/二次退款完成
N CloudResaleOrderPaidListener.php 二次订单支付
N CloudResaleOrderCompletedListener.php 二次订单进入观察期
N LandOrderPaidListener.php 租地订单支付
N AdoptionOrderPaidListener.php 认养订单支付
N FarmNotificationListener.php 领域事件转通知任务

队列任务

推荐目录：crmeb/jobs/farm。

类型 推荐文件 说明
N PublishFarmDomainEventJob.php 投递一条已抢占的领域事件
N SendFarmNotificationJob.php 发送并记录站内/模板消息
N SyncFarmBalanceLedgerJob.php 用户业务账本映射余额
N SyncMerchantSupplyLedgerJob.php 商户货款映射结算
N GenerateTraceQrCodeJob.php 溯源二维码与静态材料

定时任务

推荐目录：crmeb/jobs/farm/timer，注册位置为 app/event.php。

  • CloudActivityStatusJob.php
  • CloudUnpaidReleaseJob.php
  • CloudPaidRepairJob.php
  • CloudChoiceReminderJob.php
  • CloudChoiceExpireJob.php
  • CloudFreightExpireJob.php
  • CloudBatchStartJob.php
  • CloudPickupOverdueJob.php
  • CloudResaleAllocationRepairJob.php
  • CloudResaleReleaseJob.php
  • CloudResaleEffectiveJob.php
  • CloudRefundSyncJob.php
  • CloudMilestoneJob.php
  • CloudUserSettlementJob.php
  • CloudMerchantEligibilityJob.php
  • CloudMerchantSettlementJob.php
  • CloudMaturityJob.php
  • CloudBuybackJob.php
  • CloudReconciliationJob.php
  • FarmAllocationRepairJob.php
  • FarmTaskReminderJob.php
  • FarmOutputAllocationJob.php
  • FarmFulfillmentReminderJob.php
  • TraceMaterialExpiryJob.php
  • FarmOutboxDispatchJob.php
  • FarmFailedJobAlertJob.php

任务必须使用游标、单批上限、租约锁、运行记录和幂等键，不能捕获异常后直接把关键任务标记成功。

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
  • FarmErrorCode.php

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

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

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

install/upgrade/farm_v1/
  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
类型 文件/数据 内容
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 表前缀、字符集、版本和冲突检查
C verify_after.sql 表、索引、菜单 route name 和初始配置检查

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

四、平台管理端 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
类型 现有文件 用法
R src/api/marketing.js 参考普通秒杀请求命名和列表格式
R 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/zone/index.vue
  asset/plot/index.vue
  asset/plot/edit.vue
  asset/plot/map.vue
  asset/enclosure/index.vue
  asset/animal/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

可复用 src/components/map/Map.vue 和腾讯地图现有加载能力。地图只作为地块定位与示意，V1 不把 GIS 多边形编辑器列为必做，除非原型评审明确需要。

5. 财务页面

src/views/accounts/farm/
  userLedger/index.vue
  userLedger/detail.vue
  merchantLedger/index.vue
  merchantLedger/detail.vue
  reconciliation/index.vue
  adjustment/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/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 货款、结算单和对账接口 
src/views/marketing/cloudSupply/
  index.vue
  edit.vue
  detail.vue
  records.vue
  data.vue
  fulfillment.vue

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

2. 复用与隔离

  • 复用 src/views/marketing/seckill/store_seckill/join_activity.vue 的参加活动交互经验，但云仓不是商户自行创建普通秒杀。
  • 复用 src/api/product.js 和现有商品/SKU 选择器。
  • 商户只提交来源商品、SKU、供货价、数量、交付方式和材料。
  • 预计代销周期、用户分成、结算模式、回购比例由平台活动配置，不允许商户覆盖。
  • 商户页面只展示本商户数据，后端必须再次限定 merchant_id，不能只靠前端筛选。
  • 商户货款展示首次有效购买、验收、首次售后观察期和扣减，不展示为用户二次代销收益。

六、用户端 smartfarm_user 改造

1. API 文件

类型 文件 作用
N api/farmCloud.js 云仓活动、下单、去向、持仓、账本、自提
N api/farmLand.js 租地目录、订单、进度和产出邮寄
N api/farmAdoption.js 认养目录、订单、进度和产出邮寄
N api/farmTrace.js 溯源查询
R api/order.js 普通订单详情、退款和物流查询
R api/activity.js 仅参考普通秒杀，不在其中混入云仓状态

2. 集市云仓页面

pages/farm/cloud/
  index.vue
  detail.vue
  order_confirm.vue
  pay_result.vue
  disposition.vue
  freight_pay.vue
  pickup.vue
  holding_list.vue
  holding_detail.vue
  ledger.vue
  buyback_detail.vue
  help.vue

页面职责：

  • index.vue：场次、倒计时、库存、限购和活动状态。
  • detail.vue：SKU、价格、预计周期、结算模式、回购和三种去向。
  • order_confirm.vue：云仓专用确认页，一单一活动 SKU，不出现普通券、积分、会员价和分销开关。
  • pay_result.vue：支付成功后突出“立即选择”和“稍后选择”；稍后选择可继续抢购。
  • disposition.vue：整条明细只能选邮寄、自提或代销；不可拆数量。
  • freight_pay.vue：邮寄试算、地址和补运费；未支付前不冻结最终邮寄去向。
  • holding_detail.vue：批次进度、节点、已返本金、收益、未售数量和到期规则。

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

pages/farm/land/
  index.vue
  detail.vue
  order_confirm.vue
  order_detail.vue
  production.vue
  output.vue
  shipment.vue

pages/farm/adoption/
  index.vue
  detail.vue
  order_confirm.vue
  order_detail.vue
  production.vue
  output.vue
  shipment.vue

pages/farm/trace/
  detail.vue
  material.vue

租地/认养产出只提供邮寄到家相关操作，不显示云仓代销按钮。

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

类型 文件 改动
M pages.json 注册新页面或分包
M “我的”入口实际组件 增加我的云仓、我的租地、我的认养
M pages/users/order_payment/index.vue 或实际支付回跳页 按后端 next_action 跳云仓支付结果页
M pages/users/order_list/index.vue 只增加业务标识和进入专属详情的跳转，不复制云仓全部状态
M pages/order_details/index.vue 云仓/农业扩展摘要和专属入口
R components/payment/index.vue 复用现有支付方式，不在组件内写云仓业务判断
R 现有地址、物流、退款组件 复用基础交互和能力

支付组件只返回支付结果；“下一步选择去向”由后端订单查询返回 next_action，避免支付组件与所有业务类型耦合。

5. 用户端公共组件

components/farm/
  CloudRuleSummary.vue
  CloudDispositionSelector.vue
  CloudSettlementTimeline.vue
  CloudBatchProgress.vue
  FarmOrderStatus.vue
  ProductionTimeline.vue
  OutputShipmentCard.vue
  TraceArchive.vue

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

七、服务端 smartfarm_service 改造

1. 账号与数据范围

V1 推荐复用现有客服登录和 Token，不新增一套账号表；新增服务职责与数据范围关联：

  • 平台客服：查看授权范围内云仓订单、持仓和异常。
  • 农场现场人员：仅能操作被分配农场/区域/生产批次。
  • 仓库人员：仅能操作被分配仓库、验收和履约单。
  • 审核、结算、回购和最终异常方案仍在平台管理端完成。

服务端写接口必须在每次请求中重新校验数据范围，不能只相信 Token 内缓存的农场 ID。

2. 前端文件

类型 文件 改动
M src/router/index.js 增加固定工作台路由；V1 不同时引入后台动态菜单体系
N src/api/farm.js 云仓异常、现场记录、产出和履约
N src/views/farm/dashboard.vue 待办汇总
N src/views/farm/cloudException/index.vue 云仓异常查询和建议
N src/views/farm/production/index.vue 我的生产批次
N src/views/farm/production/event.vue 农事/养殖记录
N src/views/farm/output/index.vue 产出录入
N src/views/farm/fulfillment/index.vue 履约、核销和异常
R src/api/request.js 复用 Token 和统一响应
R src/views/kefu/pc/index 保留客服主工作台，按原型决定嵌入入口或并列页面

八、普通商城回归边界

1. 必须保持不变

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

2. 必须新增回归

风险点 回归要求
普通订单创建适配点 未映射 SKU 的 SQL、库存和订单结果与改造前一致
映射 SKU 下单 云仓分配与普通订单同事务，失败无残留
未支付关闭 CRMEB 库存和云仓批次锁定同时释放
部分退款 分配数量、金额、优惠承担和批次流水一致
全额退款 不产生有效销售和用户收益
普通营销活动 cloud_only SKU 被禁止参加不支持的活动
商品编辑 已发布云仓映射不因来源规格重建而失联
财务映射 重复任务不重复入用户余额或商户账单

九、实施任务依赖顺序

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 原功能
依赖 前置任务、第三方配置和原型
负责人 后端、前端、测试和评审人

十一、开发前仍需冻结的文件级决定

编号 待确认项 推荐方案 不确认的影响
G3-CODE-001 云仓二次销售商品映射 建立平台二次代销映射 SKU，cloud_only，不混普通库存 无法确定普通订单库存改造点
G3-CODE-002 用户首次购买优惠 V1 关闭券、积分、会员价和分销，只保留支付方式 本金快照和退款分摊不稳定
G3-CODE-003 用户结算入账账户 业务账本审核/自动校验后映射现有可用余额，并标记来源 无法定最终入账 Repository
G3-CODE-004 补运费支付载体 使用独立云仓运费支付单，复用支付渠道和退款适配器 无法定支付回调与退款文件
G3-CODE-005 数据升级规范 建立 install/upgrade/farm_v1 的版本化 up/down/verify 脚本 建表与回滚无法分配任务
G3-CODE-006 服务端身份 复用客服账号，新增职责和数据范围关联 服务路由权限无法定稿
G3-CODE-007 自动账本入账阈值 规则内零差异自动入账，异常和人工调整必须审核 定时任务与后台按钮职责冲突
G3-CODE-008 GIS 深度 V1 使用点位、区域图和地块示意，不做专业 GIS 编辑器 页面、地图接口和第三方费用不确定

十二、G4 评审通过标准

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

十三、关联文档

SmartFarm 文档

Clone this wiki locally