# V1 页面、API 与文件追踪表

本文档把 [30-v1-p0-page-matrix.md](30-v1-p0-page-matrix) 的 108 个页面对象逐一映射到前端文件、API 模块、后端 Controller、领域 Service 和主要数据。它是拆分开发任务、估工、评审 MR 和回归测试的入口，不替代页面字段规格或接口契约。

## 一、使用规则

- `E` 表示扩展现有文件，`N` 表示新增文件，`R` 表示直接复用。
- 同一页面对象可以由列表页、详情页或标签页多个文件实现；“108 个页面对象”不是“只能有 108 个 `.vue` 文件”。
- 隐藏详情路由、抽屉、标签和共用组件不另计页面编号，但仍在本表列出。
- API 路径以 `19` 为准，写命令细节以 `31` 为准。
- Controller 只编排请求；最终状态、金额、库存和分配由列出的 Service/Repository 执行。
- 路由、页面、API、Controller、权限码任一项缺失，该页面任务不能标记完成。

### 后端路径缩写

| 缩写 | 路径 |
| --- | --- |
| `AC` | `app/controller/admin/farm/cloud/` |
| `AA` | `app/controller/admin/farm/` |
| `MC` | `app/controller/merchant/farm/` |
| `UC` | `app/controller/api/farm/` |
| `SC` | `app/controller/service/farm/` |
| `CS-C` | `crmeb/services/farm/cloud/` |
| `CS-A` | `crmeb/services/farm/agriculture/` |
| `CS-S` | `crmeb/services/farm/support/` |

## 二、平台管理端 55 个页面

### 1. 商品与农业资产

| 页面 | 前端文件 | API/路由 | Controller | Service/主要表 |
| --- | --- | --- | --- | --- |
| `ADM-CM-001` 平台商品扩展 | `E src/views/product/productExamine/index.vue` 自营筛选；`E info.vue/proDetails.vue` | `E src/api/product.js` + `N src/api/farm/agriculture.js`；现有 `systemStoreProduct*` + product profile detail/save/submit | 现有商品 Controller + `AA/catalog/ProductAgriculture.php` | 商品 Repository + ProductAgriculture Repository；profile/material/audit/trace link |
| `ADM-CM-002` 商户商品审核扩展 | 同上，商户商品筛选与审核抽屉 | 同上；`POST farm/agriculture/product_profile/review/:product_id` | 现有商品审核 Controller + `AA/catalog/ProductAgriculture.php` | ProductAgriculture/Material/Audit；审核不创建供货库存 |
| `ADM-AG-001` 农业工作台 | `N src/views/farm/dashboard/index.vue` | `src/api/farm/agriculture.js`；`GET farm/agriculture/dashboard` | `AA/asset/FarmDashboard.php` | Dashboard query services；订单/任务/履约/异常只读投影 |
| `ADM-AG-002` 农场列表 | `N src/views/farm/asset/farm/index.vue` | `agriculture.js`；`farm/agriculture/farm/*` | `AA/asset/Farm.php` | Farm master service；farm/admin scope |
| `ADM-AG-003` 农场详情 | `N asset/farm/edit.vue`；`N components/WarehouseTab.vue`、`WarehouseLocationDrawer.vue` | farm/zone/warehouse/location detail 与 CRUD | `AA/asset/Farm.php`、`Zone.php`、`Warehouse.php` | Farm/Zone/Warehouse repositories；四张主数据表 |
| `ADM-AG-004` 区域列表 | `N src/views/farm/asset/zone/index.vue` | `farm/agriculture/zone/*` | `AA/asset/Zone.php` | Zone repository；farm/zone |
| `ADM-AG-005` 地块列表 | `N src/views/farm/asset/plot/index.vue` | `farm/agriculture/plot/*` | `AA/asset/Plot.php` | Plot repository；plot/occupancy |
| `ADM-AG-006` 地块详情 | `N src/views/farm/asset/plot/edit.vue` | plot detail/update/status、occupancy history | `AA/asset/Plot.php` | Plot/PlotOccupancy repositories |
| `ADM-AG-007` 地块占用日历 | `N src/views/farm/asset/plot/map.vue` | `GET farm/agriculture/plot/occupancy_calendar`、`GET farm/agriculture/plot/occupancy_detail/:id` | `AA/asset/Plot.php` | PlotAllocation query；plot occupancy |
| `ADM-AG-008` 栏舍/蜂场列表 | `N src/views/farm/asset/enclosure/index.vue` | `farm/agriculture/enclosure/*` | `AA/asset/Enclosure.php` | Enclosure repository；enclosure/breeding batch |
| `ADM-AG-009` 养殖资产列表 | `N src/views/farm/asset/animal/index.vue` | `farm/agriculture/animal/*` + 三段导入 | `AA/asset/AnimalAsset.php` | AnimalAsset/AsyncOperation；animal/allocation/replacement |
| `ADM-AG-010` 养殖批次列表 | `N src/views/farm/asset/breedingBatch/index.vue` | `farm/agriculture/breeding_batch/*` | `AA/asset/BreedingBatch.php` | BreedingBatch repository；breeding batch/adoption allocation |
| `ADM-AG-011` 自提点列表 | `N src/views/farm/asset/pickupPoint/index.vue` | `farm/agriculture/pickup_point/*` | `AA/asset/PickupPoint.php` | PickupPoint repository；pickup point/cloud pickup |
| `ADM-AG-012` 自提点编辑 | `N asset/pickupPoint/edit.vue`；`N components/farm/FarmMapPicker.vue` | pickup point detail/create/update/status + map helper | `AA/asset/PickupPoint.php`、`AA/support/FarmMap.php` | PickupPoint/FarmMapService |

### 2. 租地与认养

| 页面 | 前端文件 | API/路由 | Controller | Service/主要表 |
| --- | --- | --- | --- | --- |
| `ADM-LA-001` 作物列表 | `N src/views/farm/catalog/crop/index.vue` | `farm/agriculture/crop/*` | `AA/catalog/Crop.php` | Crop repository；crop/land plan crop |
| `ADM-LA-002` 租地套餐列表 | `N src/views/farm/land/plan/index.vue` | `GET farm/land/plan/lst` + detail/copy/status | `AA/land/LandPlan.php` | LandPlan repository；land plan/crop |
| `ADM-LA-003` 租地套餐编辑 | `N src/views/farm/land/plan/edit.vue` | plan create/update/precheck/publish | `AA/land/LandPlan.php` | LandPlan publish service；plan/capacity/snapshot |
| `ADM-LA-004` 租地订单列表 | `N src/views/farm/land/order/index.vue` | `GET farm/land/order/lst` | `AA/land/LandOrder.php` | LandOrder query；order/binding/occupancy |
| `ADM-LA-005` 租地订单详情 | `N src/views/farm/land/order/detail.vue` | `GET farm/land/order/detail/:id` | `AA/land/LandOrder.php` | LandOrder/production/output/fulfillment queries |
| `ADM-LA-006` 地块分配工作台 | `N src/views/farm/land/allocation/index.vue` | candidates/reserve/confirm/release | `AA/land/LandAllocation.php` | PlotAllocationService；land order/plot/occupancy |
| `ADM-AD-001` 认养分类与品种 | `N src/views/farm/catalog/breed/index.vue` | adoption category + `farm/agriculture/breed/*` | `AA/catalog/Breed.php` | AdoptionCategory/Breed repositories |
| `ADM-AD-002` 认养套餐列表 | `N src/views/farm/adoption/plan/index.vue` | `GET farm/adoption/plan/lst` + detail/copy/status | `AA/adoption/AdoptionPlan.php` | AdoptionPlan repository |
| `ADM-AD-003` 认养套餐编辑 | `N src/views/farm/adoption/plan/edit.vue` | plan create/update/precheck/publish | `AA/adoption/AdoptionPlan.php` | AdoptionPlan publish service；asset/share capacity |
| `ADM-AD-004` 认养订单列表 | `N src/views/farm/adoption/order/index.vue` | `GET farm/adoption/order/lst` | `AA/adoption/AdoptionOrder.php` | AdoptionOrder query |
| `ADM-AD-005` 认养订单详情 | `N src/views/farm/adoption/order/detail.vue` | `GET farm/adoption/order/detail/:id` | `AA/adoption/AdoptionOrder.php` | Order/allocation/replacement/production/output |
| `ADM-AD-006` 资产/份额分配工作台 | `N src/views/farm/adoption/allocation/index.vue` | candidates/reserve/confirm/release | `AA/adoption/AdoptionAllocation.php` | AdoptionAllocationService；asset/batch/allocation |

### 3. 生产、产出、履约与溯源

| 页面 | 前端文件 | API/路由 | Controller | Service/主要表 |
| --- | --- | --- | --- | --- |
| `ADM-PD-001` 生产批次列表 | `N src/views/farm/production/batch/index.vue` | `GET farm/production/batch/lst` | `AA/production/ProductionBatch.php` | ProductionBatch repository |
| `ADM-PD-002` 生产批次详情 | `N src/views/farm/production/batch/detail.vue` | batch detail/create/update/start/pause/resume/complete；task list/detail/create/assign/reassign/cancel | `AA/production/ProductionBatch.php`、`AA/production/FarmTask.php` | ProductionBatchService、FarmTaskService；type detail/right link/task/assignment/event |
| `ADM-PD-003` 过程记录审核 | `N src/views/farm/production/event/review.vue` | review list/review/publish/withdraw | `AA/production/ProductionEvent.php` | ProductionEventPublishService；event/version |
| `ADM-PD-004` 采收/产出批次列表 | `N src/views/farm/output/batch/index.vue` | `GET farm/output/batch/lst` | `AA/production/OutputBatch.php` | OutputBatch repository |
| `ADM-PD-005` 采收/产出批次详情 | `N src/views/farm/output/batch/detail.vue` | detail/quality/allocation preview/confirm/reconcile | `AA/production/OutputBatch.php` | OutputAllocationService；output/flow/allocation |
| `ADM-PD-006` 邮寄履约列表 | `N src/views/farm/fulfillment/index.vue`；隐藏详情 `detail.vue` | fulfillment list/detail/create/package/ship/cancel | `AA/fulfillment/FarmFulfillment.php` | FarmFulfillmentService；fulfillment/items/packages/freight |
| `ADM-PD-007` 农业异常列表 | `N src/views/farm/exception/index.vue` | `GET farm/exception/lst` | `AA/exception/FarmException.php` | FarmException query；exception/impact |
| `ADM-PD-008` 农业异常详情 | `N src/views/farm/exception/detail.vue` | detail/impact/plan/precheck/review/execute/retry/close | `AA/exception/FarmException.php` | FarmExceptionService/ExecutionService；四张异常表 |
| `ADM-TR-001` 溯源档案列表 | `N src/views/farm/trace/archive/index.vue` | `GET farm/trace/archive/lst` | `AA/trace/TraceArchive.php` | TraceArchive repository |
| `ADM-TR-002` 溯源编辑/预览 | `N src/views/farm/trace/archive/edit.vue`；审核抽屉 `trace/review/index.vue` | archive detail/create、version save/submit/review/publish/withdraw | `AA/trace/TraceArchive.php` | TracePublishService；archive/version/material/link |
| `ADM-TR-003` 报告与证书 | `N src/views/farm/trace/material/index.vue` | material list/create/update/status | `AA/trace/TraceMaterial.php` | TraceMaterial repository；material/attachment |
| `ADM-TR-004` 溯源关联 | `N src/views/farm/trace/link/index.vue` | link list/create/unlink | `AA/trace/TraceLink.php` | TraceLink repository；trace link + target snapshots |

### 4. 云仓营销与财务

| 页面 | 前端文件 | API/路由 | Controller | Service/主要表 |
| --- | --- | --- | --- | --- |
| `ADM-CW-001` 云仓活动列表 | `N src/views/marketing/cloud/activity/index.vue` | `src/api/farm/cloud.js` activity list/filter/copy | `AC/CloudActivity.php` | CloudActivity repository |
| `ADM-CW-002` 云仓活动编辑 | `N activity/edit.vue` + `ActivityBaseForm.vue` | activity detail/create/update/precheck/publish/close | `AC/CloudActivity.php` | CloudActivityPublishService；activity/snapshot |
| `ADM-CW-003` 活动商品编辑 | `N ActivitySkuRuleTable.vue`，嵌入 activity/edit | activity_product 与 activity_sku 全部接口 | `AC/CloudActivityProduct.php` | Publish/Supply/ResaleStock services；product/sku/supply/batch |
| `ADM-CW-004` 活动数据详情 | `N activity/detail.vue` | activity chart + 指标下钻 | `AC/CloudActivity.php` | 活动/订单/批次/账本只读聚合 |
| `ADM-CW-005` 云仓供货列表 | `N src/views/marketing/cloud/supply/index.vue` | supply list/filter；platform supply create | `AC/CloudSupply.php` | CloudSupply repository/lifecycle |
| `ADM-CW-006` 供货详情 | `N supply/detail.vue` | platform/create、audit、receive、inspection、release、return、platform_acquire/prepare、platform_acquire/review、platform_acquire/execute、freeze | `AC/CloudSupply.php` | CloudSupplyLifecycle/Responsibility；供货、交付、验收、材料、退回、承接六表和库存流 |
| `ADM-CW-007` 订单与去向工作台 | `N order/index.vue`、隐藏 `order/detail.vue`、`pendingChoice/index.vue`、`pickup/index.vue` | order list/detail/pending/remind + pickup list/verify/resolve | `AC/CloudOrder.php`、`CloudPickup.php` | Order/Disposition/Freight/Pickup services；pickup/verification |
| `ADM-CW-008` 云仓批次列表 | `N src/views/marketing/cloud/batch/index.vue` | batch list | `AC/CloudBatch.php` | CloudBatch repository |
| `ADM-CW-009` 云仓批次详情 | `N batch/detail.vue` | detail/flows/freeze/resume/reconcile preview/apply | `AC/CloudBatch.php` | Batch/Progress/Reconciliation；batch/pools/flows |
| `ADM-CW-010` 二次零售分配 | `N resale/index.vue`、隐藏 `resale/detail.vue` | resale list/detail | `AC/CloudResale.php` | CloudResaleAllocationService；stock/allocation/refund |
| `ADM-CW-011` 到期回购 | `N buyback/index.vue`、隐藏 `buyback/detail.vue` | buyback list/preview/prepare/review/execute/retry | `AC/CloudBuyback.php` | CloudBuyback/MaturityFinalize；buyback/holding/ledger/posting |
| `ADM-CW-012` 云仓异常 | `N exception/index.vue`、隐藏 `exception/detail.vue` | cloud exception list/detail/impact/plan/execute | `AC/CloudException.php` | 统一异常服务；exception 四表 |
| `ADM-FN-001` 商户云仓货款 | `N src/views/accounts/farm/merchantLedger/index.vue`、隐藏 `detail.vue` | `src/api/farm/finance.js` merchant ledger list/detail | `AC/CloudMerchantLedger.php` | MerchantSupplySettlement；merchant ledger |
| `ADM-FN-002` 用户云仓账本 | `N accounts/farm/userLedger/index.vue`、隐藏 `detail.vue` | user ledger list/detail/review/execute/adjust | `AC/CloudUserLedger.php` | CloudUserSettlement/Posting/Reversal；user ledger |
| `ADM-FN-003` 商户供货结单 | `N accounts/farm/merchantStatement/index.vue`、隐藏 `detail.vue` | statement preview/generate/review/execute/retry | `AC/CloudMerchantStatement.php` | Statement/Posting；statement/items/posting |
| `ADM-FN-004` 云仓对账 | `N accounts/farm/reconciliation/index.vue` | reconciliation list/detail/preview/review/execute/retry | `AC/CloudReconciliation.php` | CloudReconciliationService/AsyncOperation |
| `ADM-FN-005` 账本/入账详情 | `N accounts/farm/financialPosting/detail.vue`；复用两类 ledger detail | posting detail/retry + source detail | `AC/FarmFinancialPosting.php` | Posting/Reversal；posting/audit/outbox/source ledger |

## 三、商户端 10 个页面

| 页面 | 前端文件 | API/路由 | Controller | Service/主要表 |
| --- | --- | --- | --- | --- |
| `MER-HM-001` 智慧经营工作台扩展 | `E src/views/dashboard/index.vue`，农业待办使用独立子组件 | `N src/api/farm/cloud.js` dashboard summary | `MC/cloud/CloudSupplyRecord.php` + 现有首页 Controller | 当前商户供货、履约、异议和货款只读聚合 |
| `MER-CM-001` 商品列表扩展 | `E src/views/product/productList/index.vue` | `E src/api/product.js` + `N src/api/farm/cloud.js`；product agriculture summary/detail | `MC/catalog/ProductAgriculture.php` + 现有商品 Controller | ProductAgriculture/Material；当前 merchant scope |
| `MER-CM-002` 商品编辑扩展 | `E src/views/product/addProduct/index.vue` | 商品保存 + `farm/catalog/product_agriculture/save/submit/:product_id` | `MC/catalog/ProductAgriculture.php` + 现有商品 Controller | Profile/Material/Audit repositories；历史供货只读快照 |
| `MER-CW-001` 供货申请列表 | `N src/views/marketing/cloudSupply/application/index.vue` | cloud.js supply list/candidates | `MC/cloud/CloudSupply.php` | CloudSupply repository，强制当前商户 |
| `MER-CW-002` 供货申请编辑 | `N application/edit.vue` | supply detail/create/update/submit | `MC/cloud/CloudSupply.php` | CloudSupplyLifecycleService；supply/material |
| `MER-CW-003` 供货记录 | `N cloudSupply/record/index.vue` | supply records + 数量下钻 | `MC/cloud/CloudSupplyRecord.php` | Supply/delivery/inspection/inventory/merchant ledger query |
| `MER-CW-004` 供货详情 | `N cloudSupply/record/detail.vue` | data、delivery CRUD/dispatch、inspection、return/ack | `MC/cloud/CloudSupplyRecord.php`、`CloudSupply.php` | SupplyLifecycle/Responsibility；供货数量链 |
| `MER-CW-005` 云仓履约/售后 | `N cloudSupply/fulfillment/index.vue`、隐藏 `detail.vue` | fulfillment list/detail/ship/logistics/evidence/return/exception | `MC/cloud/CloudFulfillment.php` | Cloud fulfillment responsibility adapter；履约/包裹/异常 |
| `MER-FN-001` 云仓供货货款 | `N src/views/accounts/farm/supplyLedger/index.vue`、隐藏 `detail.vue` | `src/api/farm/finance.js` ledger list/detail/dispute | `MC/cloud/CloudSupplyLedger.php` | MerchantSupplyLedger/Dispute；ledger/posting |
| `MER-FN-002` 云仓供货结单 | `N accounts/farm/supplyStatement/index.vue`、隐藏 `detail.vue`；`E capitalFlow/index.vue` | statement list/detail/export/dispute/adjustment | `MC/cloud/CloudSupplyStatement.php` | Statement/item/posting/adjustment；复用原转账提现入口 |

商户路由分别写入 `src/router/modules/marketing.js` 和 `accounts.js`。所有查询必须在 Repository 加当前 `merchant_id`；页面参数中的商户 ID 不参与授权。

## 四、用户端 29 个页面

### 1. 农场、租地、认养和履约

| 页面 | 前端文件 | API | Controller | Service/主要表 |
| --- | --- | --- | --- | --- |
| `USR-AG-001` 农场专区 | `N pages/farm/index.vue` | `api/farmAgriculture.js`；`GET farm/agriculture/home` | `UC/agriculture/Farm.php` | 公开 Farm/Plan/Trace 聚合 |
| `USR-AG-002` 农场详情 | `N pages/farm/farm_detail.vue` | farm detail | `UC/agriculture/Farm.php` | Farm/Zone + 已发布套餐/材料 |
| `USR-AG-003` 农场位置与导航 | `N pages/farm/farm_location.vue` | farm detail/公开位置 | `UC/agriculture/Farm.php` | 公开 GCJ02 点位；客户端 `uni.openLocation` |
| `USR-LA-001` 租地列表 | `N pages/farm/land/index.vue` | `api/farmLand.js` plan list | `UC/land/LandPlan.php` | 已发布 LandPlan/Crop/容量摘要 |
| `USR-LA-002` 租地详情 | `N pages/farm/land/detail.vue` | plan detail/rule | `UC/land/LandPlan.php` | 发布版本和规则快照 |
| `USR-LA-003` 租地下单确认 | `N pages/farm/land/order_confirm.vue` | order check/create + CRMEB pay | `UC/land/LandOrder.php` | LandOrderCreateService；order/binding/land order |
| `USR-LA-004` 我的土地 | `N pages/farm/land/my_list.vue` | land order list/action count | `UC/land/LandOrder.php` | 本人 LandOrder/Occupancy 摘要 |
| `USR-LA-005` 我的土地详情 | `N pages/farm/land/order_detail.vue` | land order detail + exception plan detail/confirm | `UC/land/LandOrder.php`、`UC/exception/FarmException.php` | Order/occupancy/production/output/fulfillment/exception/trace |
| `USR-AD-001` 认养列表 | `N pages/farm/adoption/index.vue` | `api/farmAdoption.js` plan list | `UC/adoption/AdoptionPlan.php` | 已发布 AdoptionPlan/Breed |
| `USR-AD-002` 认养详情 | `N pages/farm/adoption/detail.vue` | plan detail/rule | `UC/adoption/AdoptionPlan.php` | 发布版本、模式和替换规则 |
| `USR-AD-003` 认养下单确认 | `N pages/farm/adoption/order_confirm.vue` | order check/create + CRMEB pay | `UC/adoption/AdoptionOrder.php` | AdoptionOrderCreateService |
| `USR-AD-004` 我的认养 | `N pages/farm/adoption/my_list.vue` | adoption order list/action count | `UC/adoption/AdoptionOrder.php` | 本人 AdoptionOrder/Allocation 摘要 |
| `USR-AD-005` 我的认养详情 | `N pages/farm/adoption/order_detail.vue` | adoption order detail + exception plan detail/confirm | `UC/adoption/AdoptionOrder.php`、`UC/exception/FarmException.php` | Order/allocation/replacement/production/output/exception/trace |
| `USR-PD-001` 产出履约详情 | `N pages/farm/fulfillment/detail.vue` | land/adoption API 入口统一调 fulfillment address/freight/package/take/refund | `UC/fulfillment/FarmFulfillment.php` | FarmFulfillment/Freight services；fulfillment/items/packages |

### 2. 集市云仓

| 页面 | 前端文件 | API | Controller | Service/主要表 |
| --- | --- | --- | --- | --- |
| `USR-CW-001` 集市云仓 | `N pages/cloudWarehouse/index.vue` | `api/farmCloud.js` activity current/products | `UC/cloud/CloudActivity.php` | 公开活动/商品/库存投影 |
| `USR-CW-002` 云仓商品详情 | `N pages/cloudWarehouse/detail.vue` | cloud product/batch rule | `UC/cloud/CloudActivity.php` | Published SKU/batch/rule snapshot |
| `USR-CW-003` 云仓抢购确认 | `N pages/cloudWarehouse/order_confirm.vue` | order check/create + CRMEB pay | `UC/cloud/CloudOrder.php` | CloudOrderCreateService；quota/order/binding/inventory |
| `USR-CW-004` 云仓支付成功 | `N pages/cloudWarehouse/pay_result.vue`；`M components/payment/index.vue`、`pages/order_pay_back/index.vue` | pay_result 轮询 | `UC/cloud/CloudOrder.php` | Payment adapter 状态，只读 `next_action` |
| `USR-CW-005` 云仓订单中心 | `N pages/cloudWarehouse/order_list.vue` | order list/detail/action_count/refund | `UC/cloud/CloudOrder.php` | 本人首次明细/去向/运费/持仓/退款 |
| `USR-CW-006` 云仓去向选择 | `N pages/cloudWarehouse/disposition.vue` | disposition preview/confirm | `UC/cloud/CloudDisposition.php` | CloudDispositionService；item/freight/pickup/holding |
| `USR-CW-007` 邮寄地址与补运费 | `N pages/cloudWarehouse/freight_pay.vue` | freight detail/pay/pay_result/cancel/refund_result | `UC/cloud/CloudFreight.php` | FreightQuote/Payment/Refund services |
| `USR-CW-008` 自提凭证 | `N pages/cloudWarehouse/pickup.vue` | pickup voucher | `UC/cloud/CloudPickup.php` | CloudPickup；pickup point snapshot |
| `USR-CW-009` 我的云仓 | `N pages/cloudWarehouse/holding_list.vue` | holding list/summary | `UC/cloud/CloudHolding.php` | 本人 holdings/batches |
| `USR-CW-010` 云仓持仓详情 | `N pages/cloudWarehouse/holding_detail.vue` | holding detail/progress | `UC/cloud/CloudHolding.php` | Holding/BatchProgress/UserLedger/Buyback |
| `USR-CW-011` 云仓账本 | `N pages/cloudWarehouse/ledger.vue` | user ledger list | `UC/cloud/CloudLedger.php` | 本人 ledger/posting 摘要 |
| `USR-CW-012` 云仓账本详情 | `N pages/cloudWarehouse/ledger_detail.vue` | user ledger detail | `UC/cloud/CloudLedger.php` | 公式快照/posting/冲正；回购作为账本类型 |

### 3. 溯源和原商城扩展

| 页面 | 前端文件 | API | Controller | Service/主要表 |
| --- | --- | --- | --- | --- |
| `USR-TR-001` 溯源档案 | `N pages/farm/trace/detail.vue` | `api/farmTrace.js` public archive by code/target | `UC/trace/Trace.php` | Published trace version/material/link |
| `USR-CM-001` 普通商品详情扩展 | `E pages/goods_details/index.vue` | `E api/store.js` 或产品详情适配字段 + farmTrace | 现有商品 Controller + trace read adapter | Product agriculture profile + published trace |
| `USR-CM-002` 普通订单详情扩展 | `E pages/order_details/index.vue`；`E order_list` 仅跳转 | `R api/order.js` + trace target query | 现有订单 Controller + binding/trace read adapter | 普通订单不出现云仓去向/收益；只读批次溯源 |

`pages.json` 注册 `pages/cloudWarehouse` 和 `pages/farm` 分包；29 个页面对象与以上 29 行一一对应。生产时间线、产出和材料作为详情标签/区块，不额外增加页面编号。

## 五、服务端 14 个页面

| 页面 | 前端文件 | API | Controller | Service/主要表 |
| --- | --- | --- | --- | --- |
| `SVC-AU-001` 服务人员登录 | `E src/views/login/index.vue` | `R src/api/login.js`；现有登录、验证码、退出 | 现有服务端登录 Controller | 现有 `SerToken`、服务人员账号和登录日志；不新增农业登录体系 |
| `SVC-AU-002` 工作空间选择 | `N src/views/entry/index.vue` | `N src/api/farm/common.js`；`GET farm/context` | `SC/Common.php` | FarmServiceScopeQueryService；service farm/warehouse scope |
| `SVC-AU-003` 个人资料与授权范围 | `N src/views/farm/profile/index.vue`；工作台内复用 `work/profile/index.vue` | `GET farm/context`、`GET farm/me` | `SC/Common.php` | 当前人员、角色、农场、仓库、能力和待办摘要，只读 |
| `SVC-CM-001` 农业订单查询 | `N src/views/farm/desk/order/index.vue`、隐藏 `detail.vue` | `N src/api/farm/order.js`；order list/detail | `SC/FarmOrder.php` | Land/Adoption order query；Repository 强制服务范围 |
| `SVC-CW-001` 云仓订单查询 | `N src/views/farm/desk/cloud/index.vue`、隐藏 `detail.vue` | `N src/api/farm/cloud.js`；cloud order list/detail | `SC/CloudOrder.php` | Cloud order/disposition/freight/pickup query；仓库范围 |
| `SVC-CW-002` 云仓异常协同 | `N src/views/farm/desk/exception/index.vue`、隐藏 `detail.vue` | cloud exception list/detail/claim/comment/evidence + pickup verify/overdue propose | `SC/CloudException.php`、`SC/CloudPickup.php` | Unified exception/Pickup collaboration；pickup/verification/exception/attachment |
| `SVC-PD-001` 我的任务 | `N src/views/farm/work/task/index.vue`、隐藏 `detail.vue` | `N src/api/farm/production.js`；task list/detail/start/complete | `SC/FarmTask.php` | ProductionTaskService；task/assignee/event；仅当前执行人可开始/完成 |
| `SVC-PD-002` 扫码作业 | `N src/views/farm/work/scan/index.vue`；`N src/components/farm/FarmQrScanner.vue` | `N src/api/farm/scan.js`；scan resolve/context | `SC/FarmScan.php` | FarmScanService；解析地块、资产、生产批次、任务、履约和自提码 |
| `SVC-PD-003` 过程记录 | `N src/views/farm/work/production/event.vue`；`N FarmEvidenceUploader.vue` | event draft/detail/create/update/submit + attachment upload/bind | `SC/ProductionEvent.php`、`SC/AssetHealth.php`、`SC/FarmAttachment.php` | ProductionEvent/AssetHealth services；event/version/attachment |
| `SVC-PD-004` 采收/产出登记 | `N src/views/farm/work/output/edit.vue` | output draft/detail/create/update/submit | `SC/OutputBatch.php` | OutputBatchService；output batch/flow/attachment；提交后平台审核 |
| `SVC-PD-005` 入库、打包、发货与云仓核销 | `N src/views/farm/work/warehouse/index.vue`、`receive.vue`、`fulfillment/pack.vue`、`ship.vue`、`pickup/verify.vue` | warehouse receive、fulfillment detail/pack/ship；云仓 pickup verify/resolve 复用 `CW_PICKUP_VERIFY` | `SC/Warehouse.php`、`SC/FarmFulfillment.php`、`SC/CloudPickup.php` | Warehouse/FarmFulfillment/CloudPickup services；inventory flow/package/freight/pickup；农业产出只邮寄 |
| `SVC-PD-006` 异常上报 | `N src/views/farm/work/exception/edit.vue`；复用 `FarmEvidenceUploader.vue` | exception create/update/submit + attachment upload/bind | `SC/FarmException.php`、`SC/FarmAttachment.php` | FarmExceptionService；exception/impact/attachment/outbox |
| `SVC-PD-007` 审核待办 | `N src/views/farm/desk/review/index.vue`、隐藏 `detail.vue` | `N src/api/farm/review.js`；review list/detail/approve/reject | `SC/FarmReview.php` | 授权范围内过程、产出和异常审批聚合；调用各领域 Service |
| `SVC-PD-008` 离线草稿 | `N src/views/farm/work/draft/index.vue`；`N src/utils/farmDraft.js` | 无服务端草稿 CRUD；联网后重新读取 context/对象版本再提交正式命令 | 无独立 Controller | 本地 IndexedDB；`draft_id + object_type + object_id + base_version` 去重和冲突检测 |

服务端新增静态农业路由必须注册在现有 `/:pathMatch(.*)*` 或等价动态路由之前。路由 `meta` 同时声明菜单权限码和能力码，页面显示不能代替 Controller 与 Repository 的范围校验。现有普通订单、退款、物流和商品接口需要修复越权风险的方法，详见 `21` 的服务端安全改造清单。

## 六、四端共用实现要求

### 1. API 与请求基础设施

| 端 | 新增 API 文件 | 复用基础设施 |
| --- | --- | --- |
| 平台管理端 | `src/api/farm/agriculture.js`、`cloud.js`、`finance.js`、`support.js` | 现有 `request`、统一分页、权限指令、上传组件和表格导出 |
| 商户端 | `src/api/farm/cloud.js`、`finance.js` | 现有商品、物流、上传、表格和商户权限能力 |
| 用户端 | `api/farmAgriculture.js`、`farmLand.js`、`farmAdoption.js`、`farmCloud.js`、`farmTrace.js` | `request.get/post`、CRMEB 地址、支付、物流、上传、分享和登录拦截 |
| 服务端 | `src/api/farm/common.js`、`order.js`、`cloud.js`、`production.js`、`scan.js`、`review.js` | 现有登录 token、`src/permission.js`、上传、订单和物流能力 |

写命令统一携带 `Idempotency-Key`、对象 `version` 和操作原因；客户端不得生成金额、库存、收益或最终状态。接口失败后按错误码刷新对象，不以本地乐观状态覆盖服务端事实。

### 2. 共用组件与工具

| 组件/工具 | 放置位置 | 使用页面 |
| --- | --- | --- |
| `FarmStatusTag`、`FarmAuditTimeline` | 各管理前端的 `src/components/farm/` | 状态、审核和操作轨迹 |
| `FarmMoneyFormula` | 平台、商户和用户端对应组件目录 | 活动规则、订单、持仓、账本和结单 |
| `FarmEvidenceUploader` | 平台/商户/服务端组件目录，基于现有上传组件包装 | 供货、质检、过程、异常和售后凭证 |
| `FarmMapPicker` | 平台端组件目录，基于现有地图选择能力 | 农场、自提点和地块点位 |
| `FarmAdminScopeDrawer` | 平台端 `src/components/farm/`，嵌入现有管理员列表 | 农业业务域、农场和仓库范围授权 |
| `FarmQrScanner` | 服务端组件目录 | 扫码作业和核销 |
| `CloudRuleSnapshot` | 平台、商户、用户端组件目录 | 活动 SKU、首次订单、持仓和账本详情 |
| `FarmOperationProgress` | 四端对应共用组件目录 | 导入、导出、重算、修复和批量任务进度 |
| `farmDraft.js` | 服务端 `src/utils/` | 离线草稿、重试、版本冲突提示 |
| `farmRoute.js` | 各端 `src/utils/` 或既有路由工具中扩展 | 统一对象类型到详情路由映射 |

以上组件只封装显示和交互，不封装业务状态迁移。已有 CRMEB 组件可直接满足时必须复用，具体复用依据见 `23`、`25`。

## 七、路由、菜单与权限落位

1. 平台端农业资产、租地认养、生产溯源注册到独立 `farm` 路由模块；云仓放入营销模块；账本与结单放入财务模块。
2. 商户端云仓供货放入营销模块，货款和结单放入财务模块，商品农业资料继续挂在现有商品页面。
3. 用户端使用 `pages/farm`、`pages/cloudWarehouse` 分包；“我的土地、我的认养、云仓订单、持仓、账本”从现有“我的”页面增加入口。
4. 服务端只显示授权范围内菜单；入口页根据能力引导至工作台或桌面查询，不把隐藏路由当作权限控制。
5. 平台、商户和服务端按钮权限码必须与 `20` 权限矩阵一致；用户端以资源归属、订单状态和服务端动作集控制。
6. 菜单 SQL、路由名、页面文件和 Controller 方法在同一开发任务包中交付，禁止只创建菜单或空页面。

## 八、计数与覆盖校验

| 端 | 页面对象数 | 本表行数 | 结论 |
| --- | ---: | ---: | --- |
| 平台管理端 | 55 | 55 | 一一对应 |
| 商户端 | 10 | 10 | 一一对应 |
| 用户端 | 29 | 29 | 一一对应 |
| 服务端 | 14 | 14 | 一一对应 |
| **合计** | **108** | **108** | 与 `18`、`30` 和 Figma 低保真一致 |

每行必须能反查到：

1. `30` 中的页面字段、筛选、动作和状态；
2. `19` 中的读写接口；
3. `31` 中对应写操作的事务、锁、幂等和返回；
4. `34` 中的实体、字段、索引和迁移批次；
5. `21` 中的新增/修改文件；
6. `22` 中的页面、接口、权限和异常测试；
7. `42` 中的开发任务包和验收责任。

## 九、开发准入规则

- 页面任务开始前，必须具备已冻结的页面编号、Figma 节点、API 契约、权限码、状态动作集和字段字典。
- 后端任务开始前，必须具备写操作码、事务边界、锁顺序、幂等键、事件/任务和冲正方案。
- 一个页面涉及多个领域时，选择一个聚合 Controller 负责查询，写命令仍进入对应领域 Service，不允许 Controller 跨表拼接写入。
- 列表查询不得加载完整领域对象后在内存分页；详情页不得直接返回 ORM 模型。
- 新增字段不得只在前端隐藏；敏感金额、证据、联系方式和授权范围必须由 Serializer/DTO 按角色裁剪。
- 任一行在代码、接口、权限、数据表或测试中无对应项，追踪检查失败，不能进入联调。

## 十、关联文档

- 页面定义与低保真：`18-v1-page-and-prototype-spec.md`
- API 契约：`19-v1-api-contract-draft.md`
- 事件、任务与权限：`20-v1-events-jobs-permissions-notifications.md`
- 代码文件蓝图：`21-v1-code-change-blueprint.md`
- 测试与发布：`22-v1-test-acceptance-release-manual-plan.md`
- 视觉与组件复用：`23-crmeb-visual-baseline-audit.md`、`25-user-uniapp-reuse-audit.md`
- 页面字段矩阵：`30-v1-p0-page-matrix.md`
- 写操作契约：`31-v1-write-operation-contract-registry.md`
- 事件任务登记：`32-v1-event-job-operation-registry.md`
- 状态与异常矩阵：`33-v1-state-exception-transaction-matrix.md`
- 数据库字段字典：`34-v1-database-field-dictionary.md`