37 v1 api field contract registry

SmartFarm V1 API 字段契约登记表

本文档补足 19-v1-api-contract-draft.md 的字段级契约。19 是路由目录，31 是写操作事务契约，本文件固定请求 DTO、响应 DTO、字段来源和禁止由客户端提交的事实。三者共同构成开发基线。

一、统一字段规则

1. 请求信封

DTO	字段	规则
ListQuery	page, limit, keyword, status, date_start, date_end, sort_field, sort_order	page>=1，1<=limit<=100，排序字段白名单
CommandMeta	request_id	UUID；与 Idempotency-Key Header 相同
VersionedCommand	request_id, version	version 为当前聚合正整数
ReasonCommand	request_id, version, reason_code, remark	高风险操作必填稳定原因码；备注最多 1000 字
ReviewCommand	request_id, version, decision, reason_code, remark	decision=approve/reject；审核请求不得携带被审内容
AsyncCommand	request_id, version, filters, confirm_token	服务端重算对象集合；confirm_token 只引用短期预演

2. 响应信封

DTO	必含字段
ListResult<T>	list, count, page, limit, filter_counts, action_count
DetailResult<T>	聚合字段、status, version, allowed_actions, timeline, warnings, related
CommandResult	id, business_no, status, version, allowed_actions, next_action, completed_at
AsyncAccepted	operation_no, status=pending, detail_url, poll_after_ms
OperationDetail	operation_no, operation_type, status, progress_total, progress_done, success_count, failure_count, result_summary, result_file, error_code, started_at, finished_at, allowed_actions
PayResult	business_type, business_id, group_order_id, pay_status, paid_at, next_action, return_path

所有 ID 以字符串返回；金额返回两位小数字符串，数量返回定点小数字符串，比例返回基点整数，时间返回 Asia/Shanghai 的 YYYY-MM-DD HH:mm:ss。响应中的 allowed_actions 是当前可用动作集合，不是长期授权凭证。

OperationDetail 与 eb_farm_async_operation 物理列一一同名；result_file_id 逻辑引用现有 eb_system_attachment.attachment_id，result_file 经文件服务实时换取短时签名响应，数据库不保存 URL。progress_done 必须等于 success_count + failure_count 且不大于 progress_total。

附件 ID 域固定如下：平台端和商户端的商品/供货/溯源材料、导入源文件、导出/异步结果使用 system_attachment_id（物理列仍为 attachment_id/result_file_id，逻辑引用 eb_system_attachment.attachment_id）；服务/现场端离线证据使用 farm_evidence_attachment_id（逻辑引用 eb_farm_evidence_attachment.attachment_id）。单一来源 DTO 必须使用这两个语义名；平台与现场共用的动作使用 evidence_refs[{source_type(system/farm_service), attachment_id}]，并按当前端限制可选来源。Controller 再映射到物理列，禁止只提交含义不明的通用 attachment_id。

3. 客户端禁止提交

任何请求不得接受以下字段作为最终事实：

• status、paid_at、completed_at、settled_at 等最终状态和事实时间。
• 可用库存、已售数量、进度、应结本金、收益、商户货款和账户余额。
• supply_eligible、审核人、入账人、CRMEB 流水 ID 和渠道成功状态。
• 订单归属 uid/mer_id/admin_id/service_id；全部从登录态取得。
• allowed_actions、数据范围 SQL、目标账户、最终回购金额和最终退款金额。

二、商品农业资料与权限范围

1. DTO

DTO	请求字段	成功响应
ProductAgricultureDraftInput	CommandMeta + version? + source_type(platform_self/merchant_supplier/farm_output), farm_id?, supplier_name?, origin_province, origin_city, origin_district, origin_address, public_summary, trace_archive_id?, material_ids[]	product_id, profile_id, status=draft, version, completeness, material_status, allowed_actions
ProductAgricultureSubmitInput	VersionedCommand	product_id, status=pending_review, submitted_at, version
ProductAgricultureReviewInput	ReviewCommand	product_id, status=approved/rejected, material_status, supply_eligible, audit_at, version
AdminScopeSaveInput	CommandMeta + scope_set_version + reason_code + remark + scopes[]	admin_id, scope_set_version, scopes, added, reactivated, disabled, unchanged
AdminScopeItem	domain_code, scope_type, scope_object_id, valid_from, valid_to?	返回时增加 scope_id, object_name, status

source_type=platform_self/farm_output 时 farm_id 必填；merchant_supplier 时商户由商品归属反查。supply_eligible 由审核、材料有效性和商品状态共同计算。

2. 路由映射

路由	请求 DTO	响应 DTO
GET farm/agriculture/product_profile/detail/:product_id、GET farm/catalog/product_agriculture/detail/:product_id	Path product_id	商品基本摘要 + profile + materials + audit history + allowed_actions
POST farm/agriculture/product_profile/save/:product_id、POST farm/catalog/product_agriculture/save/:product_id	ProductAgricultureDraftInput	CommandResult + completeness
POST farm/agriculture/product_profile/submit/:product_id、POST farm/catalog/product_agriculture/submit/:product_id	ProductAgricultureSubmitInput	CommandResult
POST farm/agriculture/product_profile/review/:product_id	ProductAgricultureReviewInput	CommandResult + supply_eligible
GET farm/support/admin_scope/options	keyword?, domain_code?	业务域、农场、仓库树和操作者可授予上限
GET farm/support/admin_scope/detail/:admin_id	Path admin_id	admin_id, admin_name, scope_set_version, scopes, warnings
POST farm/support/admin_scope/save/:admin_id	AdminScopeSaveInput	范围差异和新集合版本

三、农业主数据

1. 主数据输入

资源	创建/修改字段	列表/详情响应核心字段
farm	farm_no, name, short_name, address, longitude?, latitude?, coordinate_system=GCJ02, contact_name?, contact_phone?, description?, cover_image?, gallery[], sort, enabled	ID/编号/名称、地址点位、区域/地块/仓库/在产批次数量、状态、版本
zone	farm_id, zone_no, name, zone_type, description?, schematic_image?, sort, enabled	农场、区域编号/名称/类型、地块/栏舍数、状态
plot	zone_id, plot_no, name, area, area_unit, capacity, capacity_unit, soil_type?, schematic_image?, sort, enabled	农场/区域、面积容量、当前占用、未来冲突、状态
warehouse	farm_id, warehouse_no, name, warehouse_type, address?, manager_name?, manager_phone?, enabled	农场、库位数、当前库存摘要、状态
warehouse_location	warehouse_id, location_no, name, location_type, capacity?, capacity_unit?, enabled	仓库、库位、占用/可用摘要、状态
pickup_point	farm_id, name, address, longitude, latitude, coordinate_system=GCJ02, contact_name, contact_phone, opening_hours, pickup_days, enabled	点位、营业时间、待核销量、状态
crop	crop_no, name, variety?, category, growth_days, output_unit, cover_image?, description?, enabled	作物/品种、周期、单位、套餐引用数
enclosure	zone_id, enclosure_no, name, enclosure_type, capacity, capacity_unit, schematic_image?, enabled	农场/区域、容量、当前个体/批次、状态
breed	category_id, breed_no, name, species, cycle_days, output_type, output_unit, cover_image?, enabled	分类/品种、周期、个体/批次和套餐引用
animal	farm_id, enclosure_id, breed_id, asset_no, ear_tag?, born_at?, sex?, source, health_status, weight?, weight_unit?, enabled	个体身份、位置、健康、当前认养占用、版本
breeding_batch	farm_id, enclosure_id, breed_id, batch_no, started_at, planned_end_at?, total_share, available_share, unit_name, enabled	批次、容量/可用份额、周期、当前分配

2. 通用主数据路由

farm/agriculture/{farm|zone|plot|warehouse|warehouse_location|pickup_point|crop|enclosure|breed|animal|breeding_batch} 使用：

后缀	请求	响应
GET lst	ListQuery + farm_id?, zone_id?, warehouse_id?, enabled?	ListResult<ResourceSummary>
GET detail/:id	Path ID	DetailResult<ResourceDetail>
POST create	CommandMeta + 对应资源字段	CommandResult
POST update/:id	VersionedCommand + 可编辑资源字段	CommandResult
POST status/:id	ReasonCommand + enabled	CommandResult + reference_warnings

停用操作不接受前端传“引用数”；后端返回套餐、活动、生产、任务或库存引用阻断明细。动物三段导入额外使用 upload_token → validation_operation_no → confirm_token，最终返回 AsyncAccepted。

动物导入字段契约：

DTO/路由	请求字段	响应
AnimalImportValidateInput / POST farm/agriculture/animal/import/validate	CommandMeta + system_attachment_id, content_hash, farm_id, default_enclosure_id?, column_mapping?	AsyncAccepted，operation_type=animal_import_validate
GET farm/agriculture/animal/import/preview/:operation_no	Path operation_no	status, content_hash, row_count, valid_count, error_count, columns, preview_rows<=100, error_file?, confirm_token?, target_versions
AnimalImportConfirmInput / POST farm/agriculture/animal/import/confirm/:operation_no	CommandMeta + confirm_token	AsyncAccepted，operation_type=animal_import_confirm

confirm_token 绑定校验操作、文件哈希、字段映射、目标农场/栏舍版本和有效期；确认请求不携带动物行数据。

四、租地与认养

1. 套餐和订单 DTO

DTO	请求字段	响应核心字段
LandPlanInput	CommandMeta/version? + farm_id, name, cover_image, gallery[], area, area_unit, service_days, price, service_value_amount, delivery_value_amount, delay_tolerance_days, allocation_mode, selectable_crop, crop_ids[], planting_service, output_rule, fulfillment_rule, sale_start_at, sale_end_at, stock, per_user_limit, description	plan ID/no、价值拆分校验、发布状态、容量预检、版本
AdoptionPlanInput	CommandMeta/version? + farm_id, category_id, breed_id, allocation_mode(individual/share), share_qty?, service_days, price, service_value_amount, delivery_value_amount, delay_tolerance_days, output_rule, replacement_rule, fulfillment_rule, sale_start_at, sale_end_at, stock, per_user_limit, description	plan ID/no、价值拆分/个体或份额容量预检、版本
FarmOrderCheckInput	plan_id, quantity=1, crop_id?, address_id?, request_id	check_key, plan_snapshot, amount_breakdown, capacity_summary, expires_at
FarmOrderCreateInput	check_key, request_id, user_remark?	CRMEB group_order_id, order_id, order_product_id, pay_price, pay_options, business_order_no
AllocationReserveInput	request_id, order_id, candidate_id, version	reservation_no, expires_at, candidate_snapshot
AllocationConfirmInput	request_id, order_id, reservation_no, version	allocation/occupancy ID、真实资产摘要、状态

2. 路由映射

路由族	请求	响应
平台 farm/land/plan/*	LandPlanInput；publish 使用 VersionedCommand	列表/详情、发布预检、CommandResult
平台 farm/adoption/plan/*	AdoptionPlanInput；publish 使用 VersionedCommand	列表/详情、发布预检、CommandResult
平台 `farm/{land	adoption}/order/lst	detail`
平台 `farm/{land	adoption}/allocation/candidates/:order_id`	farm_id?, date_range?
reserve/confirm/release/:order_id	AllocationReserveInput、AllocationConfirmInput、ReasonCommand	预留/分配结果
用户 `farm/{land	adoption}/plan/lst	detail`
用户 `farm/{land	adoption}/order/check	create`
用户 `farm/{land	adoption}/order/pay_result/:group_order_id`	Path ID
用户 `farm/{land	adoption}/order/lst	detail/:id`

租地和认养每次下单只允许一个套餐且数量为 1；具体地块、动物或份额在付款后分配，不在下单请求中承诺。

五、云仓活动、供货与库存

1. 活动和 SKU

DTO	请求字段	成功响应
CloudActivityInput	CommandMeta/version? + name, preview_at?, start_at, end_at, payment_timeout_minutes, choice_days_default, cover_image?, description?, sort	activity ID/no、状态、版本、预检摘要
CloudActivityProductInput	CommandMeta/version? + activity_id, product_id, display_title, cover_image?, supports_shipping, supports_pickup, supports_consign=true, choice_days?, pickup_days?	activity product ID、SKU 数、完整性
CloudActivitySkuRuleInput	VersionedCommand + supply_id, activity_unit_price, activity_qty, per_user_limit, expected_sale_days, maturity_resolution_days, settlement_mode, milestones[], user_profit_rate, buyback_rate, primary_after_sale_days, secondary_after_sale_days, shipping_rule, pickup_point_ids[], resale_product_id, resale_sku_value_id	SKU 规则校验、来源诊断、预计金额示例
CloudActivityPublishInput	VersionedCommand + precheck_hash	发布版本、批次草稿、库存占用摘要

平台成本比例和最终可售量不由客户端提交。settlement_mode 三选一；milestones 只对分期模式有效，严格递增且最后为 10000。

2. 供货生命周期

DTO	请求字段	成功响应
CloudSupplyDraftInput	CommandMeta/version? + product_id, source_sku_value_id, supply_price, proposed_qty, fulfillment_type, proposed_shipping_party, proposed_quality_party, proposed_after_sale_party, expected_delivery_at?, material_ids[], remark?	supply ID/no、来源 SKU 快照、完整性、版本
CloudPlatformSupplyCreateInput	CommandMeta + product_id, source_sku_value_id, proposed_qty, fulfillment_type, shipping_responsible_party, quality_responsible_party, after_sale_responsible_party, after_sale_days, material_ids[], remark?	source_type=platform, merchant_id=null 的 supply ID/no、来源预占和农业库存流水摘要
CloudSupplyAuditInput	ReviewCommand + approved_qty?, shipping_responsible_party?, quality_responsible_party?, after_sale_responsible_party?, after_sale_days?	审核状态、批准/预留数量、责任快照
SupplyDeliveryInput	CommandMeta/version? + dispatch_qty, handover_method, carrier_code?, tracking_no?, system_attachment_ids[]	delivery ID/no、累计发运和剩余可交付量
SupplyReceiveInput	VersionedCommand + received_qty, shortage_qty, system_attachment_ids[]	实收、短少和待检数量
SupplyInspectionInput	VersionedCommand + accepted_qty, rejected_qty, pending_inspection_qty, warehouse_id, location_id, quality_result, system_attachment_ids[]	验收方程、云仓可用量、拒收待办
SupplyReturnInput	ReasonCommand + qty, handover_method?, carrier_code?, tracking_no?, system_attachment_ids[]	退回/争议/完成状态和来源恢复量
SupplyAcquisitionPrepareInput	ReasonCommand + acquisition_qty, acquisition_unit_price, target_product_id, target_sku_value_id, system_attachment_ids[]	承接编号、待复核金额、目标平台库存和版本
SupplyAcquisitionReviewInput	ReviewCommand	approved/rejected、复核人和版本；不得修改数量、价格或目标 SKU
SupplyAcquisitionExecuteInput	VersionedCommand + precheck_hash	完成承接、平台库存流水、供货汇总和版本
CloudFulfillmentShipInput	VersionedCommand + package_id, carrier_code, tracking_no, system_attachment_ids[]?	包裹、出库数量、物流版本和履约状态
CloudFulfillmentLogisticsInput	ReasonCommand + package_id, carrier_code, tracking_no	变更前后物流快照、包裹版本和风险提示
CloudFulfillmentEvidenceInput	VersionedCommand + evidence_type, system_attachment_ids[], remark?	新增证据关联、证据版本和完整性
CloudFulfillmentReturnReceiveInput	VersionedCommand + after_sale_id, received_qty, shortage_qty, quality_result, system_attachment_ids[]	退回实收/差异、待检或异常 ID、下一动作
CloudFulfillmentExceptionInput	ReasonCommand + exception_type, severity, fact_description, system_attachment_ids[]	统一异常 ID/no、冻结建议和状态

供货审核 decision=reject 时不接受批准量和责任方；approve 时三类责任方、批准量和观察期必填。所有数量由后端以当前累计值重新校验。

3. 路由映射

路由族	请求/响应
`farm/cloud/activity/lst	filter
activity `create	update
activity product/SKU `lst	detail
商户 supply `product_candidates	lst
商户 delivery `lst	create
商户 fulfillment `lst	detail
平台 supply `lst	detail
`farm/cloud/batch/lst	detail
batch `freeze	resume

六、用户云仓订单与去向

1. DTO

DTO	请求字段	成功响应
CloudOrderCheckInput	activity_sku_id, purchase_qty, request_id	check_key, sku_snapshot, rule_snapshot, principal_amount, quota, stock, expires_at
CloudOrderCreateInput	check_key, request_id, user_remark?	CRMEB 订单三层 ID、云仓明细 ID、支付选项
CloudDispositionPreviewInput	cloud_order_item_id, disposition, address_id?, pickup_point_id?	可行性、运费承担、报价/自提点/代销规则、截止时间
CloudDispositionConfirmInput	request_id, cloud_order_item_id, choice_version, disposition, preview_token, address_id?, pickup_point_id?	最终去向；需补运费时返回运费单而不提前生效邮寄
CloudFreightPayInput	request_id, freight_order_id, version, pay_type, return_path?	支付参数或余额支付最终状态
CloudPrimaryRefundInput	request_id, cloud_order_item_id, version, reason_code, reason, pics[]?	退款申请 ID、冻结范围、状态；pics 沿用 CRMEB 用户售后图片格式和上传白名单
CloudPickupVerifyInput	request_id, pickup_id, version, voucher_code, verify_qty	核销流水 ID/no、累计核销量、剩余量、明细完成状态
CloudPickupResolveInput	CommandMeta + pickup_id, version, remaining_qty, resolution_type(extend/ship/refund/buyback), plan_version, user_confirmation_id?	异常方案/运费单/退款/回购结果，不接受客户端金额

2. 查询响应

接口	核心响应字段
activity current/config/product	活动/场次、SKU、倒计时、限购、可抢库存、三种去向、预计周期、分成、回购和风险提示
order list/detail/action_count	首次本金、支付、选择截止、去向、运费、自提、持仓、退款、规则快照、allowed_actions
freight detail/pay_result/refund_result	金额、报价快照、支付渠道、渠道事实摘要、超时/迟到退款状态
pickup voucher/verification list	点位快照、有效期、脱敏凭证展示值、应提/已核销/退款/改寄/回购/剩余数量和不可变核销历史
holding list/detail/progress	本金、实体批次数量、已售/未售经济等价数量、真实累计进度、节点、预计到期、所有权切换、回购和账本摘要
user ledger list/detail	本金/收益/回购类型、累计公式输入、分钱尾差、正常退款抵扣、平台风险承担、审核、入账、冲正和 CRMEB 流水摘要

去向确认一次只处理完整订单明细；purchase_qty 不允许拆分为多种去向。用户可以支付后继续抢购，订单中心通过 action_count.pending_choice 找回待选明细。

七、二次销售、账本、结单与对账

命令 DTO	请求字段	响应
LedgerReviewInput	ReviewCommand + source_calculation_version	审核状态、重算差异和下一动作
LedgerExecuteInput	CommandMeta + source_ids[], version_map, review_remark?	逐条 source_id, posting_id, status, crm_bill_id, error_code
LedgerAdjustmentInput	CommandMeta + source_ledger_id, direction, reason_code, reason, evidence_ids[]	调整申请 ID、影响预览；不得提交最终账户余额
StatementGenerateInput	CommandMeta + merchant_id, period_start, period_end, currency=CNY	statement ID/no、明细数和金额
ReconciliationExecuteInput	CommandMeta + reconciliation_id, version, approved_action_ids[], reason_code, remark	AsyncAccepted；每项按原结果键修复
BuybackReviewInput	ReviewCommand + calculation_version	审核状态和执行前置；金额、比例、平台目标库存均从快照读取

列表与详情必须返回公式快照，至少包括 source_qty, batch_effective_qty, sold_equivalent_qty, unsold_equivalent_qty, unit_price, principal, recognized_sales, distributable_profit, cumulative_due, historical_settled, current_due, normal_refund_offset_amount, platform_risk_absorbed_amount, rounding_adjustment。执行接口只接收来源 ID，不接收最终金额、目标账号或 CRMEB 流水 ID。

八、生产、产出、履约、异常与溯源

1. 生产与现场记录

DTO	请求字段	成功响应
ProductionBatchInput	CommandMeta/version? + production_type, farm_id, zone_id?, plot_id?, enclosure_id?, animal_asset_id?, breeding_batch_id?, planned_start_at, planned_end_at, expected_output_qty?, output_unit, right_links[]	batch ID/no、占用/权益预检、状态
FarmTaskInput	CommandMeta/version? + task_type, target_type, target_id, requirement_snapshot, planned_start_at, due_at, priority, assignee_ids[]?	task ID/no、分派和版本
ProductionEventInput	CommandMeta/version? + task_id?, production_batch_id, event_type, occurred_at, content, metric_items[], farm_evidence_attachment_ids[], visibility	event/version ID、审核状态
AssetHealthInput	CommandMeta + task_id?, animal_asset_id?, breeding_batch_id?, health_type, occurred_at, result, treatment?, farm_evidence_attachment_ids[]	健康记录 ID、是否触发异常
OutputBatchInput	CommandMeta/version? + production_batch_id, harvested_at, gross_qty, unit_code, warehouse_id?, location_id?, quality_note?, farm_evidence_attachment_ids[]	output ID/no、待检数量和状态

metric_items 使用白名单 {metric_code, value_decimal|string, unit_code}；现场提交人不能在审核接口修改原内容。生产类型扩展字段按 plant/livestock 二选一。

2. 产出分配与履约

DTO	请求字段	成功响应
OutputQualityInput	VersionedCommand + accepted_qty, loss_qty, pending_qty, warehouse_id, location_id, quality_result, system_attachment_ids[]	数量方程、可分配量、状态
OutputAllocationConfirmInput	CommandMeta + output_batch_id, calculation_version, preview_token	分配列表、库存流水和履约草稿
FulfillmentAddressInput	VersionedCommand + address_id	不可变地址版本、是否需运费
FarmFreightCreateInput	CommandMeta + fulfillment_id, address_version, quote_token	农业运费单、金额、支付期限
FulfillmentPackageInput	VersionedCommand + items[{fulfillment_item_id, qty}], warehouse_id, location_id	包裹 ID/no、待出库数量
FulfillmentShipInput	VersionedCommand + package_id, carrier_code, tracking_no, shipped_at?, evidence_refs[]?	包裹、物流和履约状态；平台入口只收 system，现场入口只收 farm_service
FulfillmentRefundInput	CommandMeta + fulfillment_id, refund_qty, reason_code, reason, evidence_ids[]?	承诺/已履约/已退数量、服务/交付退款基数、累计应退、历史/在途退款、本次后端计算金额和售后编号

租地/认养产出 V1 只允许邮寄。地址、运费、包裹和售后均按履约单，不修改原租地/认养交易金额。

3. 异常和溯源

DTO	请求字段	成功响应
ExceptionCreateInput	CommandMeta + business_domain, event_type, severity, target_type, target_id, occurred_at, reason, fact_items, evidence_refs[]	exception ID/no、SLA、初始影响；按平台/商户/现场端限制证据来源
ExceptionPlanInput	CommandMeta + exception_id, impact_version, plan_type, affected_qty, replacement_target_id?, proposed_delay_days?, steps[{step_order, step_code, input}], expected_result	后端等价校验、短缺分配、退款计算、是否需用户确认、确认截止、超时策略、plan version ID
ExceptionReviewInput	ReviewCommand + precheck_hash	审核状态
ExceptionUserConfirmInput	request_id, plan_version_id, decision(accept/reject), version	确认事实、下一动作；不得提交替代金额或直接改方案
TraceVersionInput	CommandMeta/version? + archive_id?, target_type, target_id, title, public_summary, sections[], material_ids[], link_targets[]	archive/version ID、完整性、审核状态
TraceMaterialInput	CommandMeta/version? + material_type, material_no?, system_attachment_id, issuer?, effective_at?, expire_at?, applicable_targets[]	material ID、有效性和引用数
TraceLinkInput	CommandMeta + archive_id, version_id, target_type, target_id, relation_type, valid_from?, valid_to?	link ID 和公开影响

异常执行接口只接受 plan_id/step_id + version + request_id，不接受任意类名、SQL、URL、脚本、最终退款金额或回购金额。完全等价且未超延期容忍期的方案可在 3 个自然日后按快照自动接受；降级、减量、超期或补款方案超时默认拒绝并转未履约退款。溯源审核、发布、撤回是三个独立权限；公开接口只返回当前发布版本。

九、服务/现场端字段契约

接口族	请求字段	响应字段
GET farm/context, GET farm/me	无业务对象参数	service ID、职责、能力码、scope 摘要/版本、默认入口、地图/扫码能力
`GET farm/order/search	detail/:type/:id`	keyword/type/status/page/limit
`GET farm/cloud/order/search	detail/:id`	同上
POST farm/scan/resolve	request_id, code, expected_types[]?, task_id?	object_type, object_id, display_no, summary, context, allowed_actions
task `lst	detail	start
cloud pickup verify	CloudPickupVerifyInput，并额外强制当前网点/仓库 scope	核销流水、累计/剩余数量和明细状态
event/health/output/warehouse/fulfillment	使用第八节对应 DTO，并额外强制当前 task/scope	业务结果和任务进度
POST farm/attachment/upload	multipart：file, task_id?, scope_object_type, scope_object_id, request_id	farm_evidence_attachment_id, attachment_no, mime_type, size, content_hash, expires_at, bind_status=unbound
review `lst	detail	approve
exception `create	evidence	propose`

服务端对象越界统一返回 COMMON_NOT_FOUND；只有对象已确认可见但动作不允许时返回 SERVICE_PERMISSION_DENIED。离线草稿只存在 IndexedDB，正式提交仍使用上述 DTO 和原 request_id。

十、公开查询、地图与文件

接口	请求	响应/限制
`farm/agriculture/home	farm/lst	farm/detail/:id`
farm/trace/public/:archive_no	稳定随机公开码	当前发布版本、公开材料、过程时间线和撤回状态
farm/trace/qrcode/:archive_no	公开码	二维码图片或稳定跳转；不编码内部主键
`farm/map/geocode	reverse_geocode	suggest`
GET farm/operation/detail/:operation_no	业务号	OperationDetail；四端各自鉴权，只限发起人或有权范围

文件响应按来源返回 system_attachment_id、farm_evidence_attachment_id 或只读 file_id，并附 url, thumbnail_url?, mime_type, size, expires_at?。存储物理路径、对象存储密钥和永久私有 URL 不得进入客户端。

十一、列表与详情投影最低字段

每个 19 中的 lst/search 接口必须至少返回：

id, business_no/code, display_name/title, status, status_text, primary_summary, warning_codes[], updated_at, allowed_actions

并补齐 30-v1-p0-page-matrix.md 对应页面“信息字段”列。每个详情接口必须至少返回：

id, business_no, status, version, base, rule_snapshot?, quantity_summary?, money_summary?, ownership, related, timeline, audit_summary, warnings, allowed_actions

Serializer 按终端裁剪：

• 平台：再按管理员业务域和对象范围。
• 商户：强制当前 mer_id，隐藏平台成本、其他商户和用户完整隐私。
• 用户：强制本人资源，隐藏供货成本、内部备注和责任人员联系方式。
• 服务端：按职责、对象范围和 PII 权限脱敏。
• 公开端：只读发布版本和公开字段。

十二、实现验收

1. 19 的每个路由必须映射到本文件一个 DTO 或明确的通用资源模式。
2. 31 的每个操作码必须有请求字段、响应字段、幂等键和版本规则。
3. Controller 只把校验后的 DTO 交给 Application Service，不把原始 Request 数组传入 Repository。
4. Serializer/Presenter 负责金额字符串、ID 字符串、隐私裁剪和 allowed_actions。
5. OpenAPI 或接口管理平台的 schema 名称必须沿用本文件 DTO 名；变更时同步更新 19、31、35 和测试。
6. 契约测试逐路由校验必填、禁止字段、类型、空值、错误码和响应快照；不能只测 HTTP 200。

十三、关联文档

• 19-v1-api-contract-draft.md
• 30-v1-p0-page-matrix.md
• 31-v1-write-operation-contract-registry.md
• 33-v1-state-exception-transaction-matrix.md
• 34-v1-database-field-dictionary.md
• 35-v1-page-api-file-trace.md