38 v1 platform admin manual

SmartFarm V1 平台管理员操作手册

状态：设计态操作手册，功能尚未开发和发布

本文档依据 SmartFarm V1 已确认业务规则、页面信息架构和接口契约编写。页面编号用于设计、开发和验收追踪；对应功能完成开发、测试和发布后，本文才能升级为正式操作手册。当前未上线页面不得描述为现有可操作能力。

每次补充正式截图时必须记录适用系统版本、页面编号、截图时间和脱敏结果，禁止在手册中保存账号密码、Token 或第三方密钥。

一、适用角色与职责分离

角色	主要页面	可以做	不应默认拥有
超级管理员	全部平台页面	配置角色、范围和最终应急处置	日常业务全部由同一人操作
农业运营	ADM-AG/LA/AD/PD-*	农业主数据、套餐、分配、生产和履约协调	资金入账、回购执行、冲正审核
云仓运营	ADM-CW-*	供货审核、活动、订单去向、批次和异常	直接改用户余额或商户余额
仓储履约	ADM-AG-003/011/012、ADM-PD-004~006、ADM-CW-005~007	收货、质检、库存、打包、发货和云仓自提	结算规则、异常最终金额
内容/溯源审核	ADM-CM-*、ADM-PD-003、ADM-TR-*	农业资料、过程记录和溯源版本审核	修改提交人的原始事实
财务	ADM-FN-*、ADM-CW-011	账本复核、结单、回购审核、对账和冲正	绕过业务来源直接改余额
客服主管	ADM-PD-007/008、ADM-CW-007/012	异常协同、联系记录和方案建议	最终资金、库存或规则决定
数据只读	授权列表/详情	查询、筛选和脱敏导出	任意写操作

最小权限原则：

1. 路由权限决定能否进入页面。
2. eb_farm_admin_scope 决定可见农场、仓库和农业对象。
3. allowed_actions 决定当前对象和状态可显示哪些操作。
4. 后端每次提交重新校验权限、范围、状态、版本、数量和金额。
5. 活动编辑与发布、供货审核与验收、账本审核与入账、回购审核与执行、冲正申请与审核应由不同权限控制。

二、每日工作顺序

建议按以下顺序处理，不按红点数量直接执行资金动作：

1. 进入 ADM-AG-001 查看授权范围内的租地、认养、生产、履约和农业异常。
2. 检查 ADM-PD-003/007 的待审核记录、严重异常和 SLA。
3. 检查 ADM-CW-005 待审核/待验收供货。
4. 检查 ADM-CW-004/007 活动状态、未支付释放、待选去向和补运费异常。
5. 检查 ADM-CW-008/009/011/012 批次、在途宽限、回购预案和冻结项。
6. 检查 ADM-FN-003/004 日结单、五段对账和正式入账失败。
7. 对每个异常保留事实、方案版本、审核、执行和复核证据，再交班。

三、商品农业资料

ADM-CM-001 平台商品管理扩展

适用角色：平台商品运营、农业资料审核。

前置条件：

• 普通 CRMEB 商品和 SKU 已存在。
• 农产品来源、产地和材料使用稳定对象 ID。

操作：

1. 在原商品编辑页进入农业资料区域。
2. 选择商品来源、农场/供应来源、公开产地信息和溯源档案。
3. 上传报告、证书或生产材料引用，不把临时 URL 当正式材料。
4. 平台自营商品需要进入云仓时，建立平台供货来源，不直接把普通库存视为云仓活动库存。
5. 保存后查看资料完整性和发布影响。

成功结果：商品农业资料保存版本和审计，普通商品原价格、库存和营销规则不被农业字段覆盖。

常见阻断：材料已过期、来源对象停用、溯源未发布、SKU 来源诊断失配、无对象范围。

ADM-CM-002 商户商品审核扩展

审核产地、材料、溯源和供货资格。审核通过只表示商品资料可用，不等于供货申请已批准，也不预留来源库存。

证据：商品/SKU、材料版本、审核意见、审核人、时间和供货资格状态。

四、农业资产与仓储主数据

农场、区域和地块

页面：ADM-AG-002~007。

推荐顺序：

1. 新建农场并配置名称、地址、GCJ02 点位、公开说明和状态。
2. 在 ADM-AG-003 建立区域、仓库和库位。
3. 建立地块，记录面积、单位、用途、容量和状态。
4. 在地块详情核对占用历史、生产批次和异常。
5. 在占用日历检查周期重叠。
6. 只有真实点位、容量和必需材料完整时启用农场。

禁止：

• 用地图多边形面积替代业务面积。
• 保存 0,0 作为默认坐标。
• 删除已被订单、生产或溯源引用的资产。

栏舍、养殖资产和批次

页面：ADM-AG-008~010。

• 栏舍/蜂场是空间和容量主数据。
• 单体资产需有稳定编号、品种、性别/阶段、健康和当前位置。
• 批次资产需有可分配份额、已分配份额和预留份额。
• 单体有效分配只能有一条；批次已分配加有效预留不得超过总份额。

仓库、库位与自提点

页面：ADM-AG-003、ADM-AG-011/012。

• 仓库/库位用于供货验收、农业产出和履约库存。
• 自提点只用于云仓自提，不用于租地/认养产出。
• 自提点启用前必须有名称、地址、GCJ02 点位、营业时间、联系方式和可服务范围。
• 地图不可用时允许保存草稿，不能启用缺少真实点位的自提点。

五、租地业务

套餐发布

页面：ADM-LA-001~003。

发布前必须确认：

• 农场和可分配地块有效。
• 作物、服务天数、承诺产出数量和单位明确。
• 套餐价格等于生产服务价值加交付价值。
• 延期容忍天数必填，默认 7 天，可选 0/3/7/15/30。
• 产出履约只配置邮寄规则。
• 库存、限购、销售时间和公开说明完整。

发布后规则形成版本。历史订单继续读取下单快照，不因套餐后改而变化。

订单与地块分配

页面：ADM-LA-004~006。

流程：

1. 用户支付后订单进入待分配。
2. 候选查询不占容量。
3. 平台选择地块后建立默认 5 分钟预留。
4. 确认时锁定地块并重查周期、容量、订单版本和预留令牌。
5. 成功后建立占用历史和订单关系；冲突时刷新候选，不手工覆盖占用。

成功结果：订单详情能追到真实地块、占用周期、生产批次、产出、邮寄履约和异常。

六、认养业务

页面：ADM-AD-001~006。

套餐发布必须选择单体或批次份额模式：

• 单体：确认时锁定真实动物/蜂箱等资产，保证唯一有效分配。
• 批次份额：确认时锁定批次并重查剩余份额。

分配同样使用“候选不占用、5 分钟预留、原子确认、显式/超时释放”。资产替换不得删除原关系，必须建立替换链。

租地和认养共同边界：用户产出只能邮寄，不出现云仓代销、店铺上架或自提。

七、生产、产出与邮寄履约

生产批次与过程审核

页面：ADM-PD-001~003。

1. 建立种植/养殖生产批次并关联真实资产和权益订单。
2. 分派现场任务。
3. 现场提交过程记录后，审核人查看原始内容、附件、对象版本和历史。
4. 通过后生成可发布版本；驳回必须填写结构化原因。
5. 审核人不得直接修改提交人事实。

产出与分配

页面：ADM-PD-004/005。

验收恒等式：

总数量 = 合格数量 + 损耗数量 + 待检数量

合格产出按订单未履约数量分配。发生短缺时按未履约量比例计算，整数余量使用最大余数法，余数相同按支付时间、订单 ID。

邮寄履约

页面：ADM-PD-006。

• 用户在每次发货前确认地址。
• 平台按生产节奏主动分批产生的额外运费由平台承担。
• 包邮套餐正常分批不得再次收费。
• 只有用户主动要求额外拆包或升级配送时，才可经确认报价生成补运费单。
• 已出库包裹保留原地址快照；改地址只影响未出库部分。

八、溯源

页面：ADM-TR-001~004。

流程：

1. 以生产/产出批次建立档案草稿。
2. 关联过程记录、检测报告、证书和商品/订单对象。
3. 内容审核通过后发布不可变公开版本。
4. 新修改建立新版本，不覆盖用户历史查看依据。
5. 撤回只改变公开指针和撤回说明，历史版本保留。
6. 二维码使用稳定公开码，不暴露内部主键。

材料过期时阻止新发布或触发告警，不静默删除已引用历史证据。

九、云仓供货

页面：ADM-CW-005/006。

数量生命周期：

拟供
→ 审核批准并预留来源库存
→ 发运
→ 平台收货
→ 待检
→ 验收合格/拒收/短缺
→ 云仓可用
→ 活动占用
→ 退回或平台承接

审核步骤：

1. 平台自营供货只能选择所属商户 is_trader=1 的商品/SKU；创建时直接锁定并预占来源库存，供货归属保存为平台来源。
2. 商户申请核对一张申请只关联一个来源 SKU。
3. 核对商品资料、供货价、拟供量和来源可预留库存。
4. 确认邮寄、质量和售后责任快照。
5. 商户申请审核通过后才预留来源库存。
6. 收货、质检和短缺分别记录，不覆盖商户发运事实。
7. 验收合格量才可进入活动发布预检。

商户实物仍在平台仓时，活动未抢完数量先进入退回待办，完成实物退回/等价移交后才恢复来源可售库存。

商户同意由平台承接剩余实物时必须分三步：

1. prepare：锁供货剩余量，生成数量、单价、目标平台商品/SKU 和证据快照；不改平台库存。
2. review：由非制单人独立批准或驳回，不得在复核时改数量、价格或目标 SKU。
3. execute：重新预检并在一个事务内增加平台库存、供货承接汇总和库存流水；重复执行返回同一结果。

同一数量不能同时退回和承接；发生并发或守恒差异时停止处置并进入异常/对账，不直接改汇总数。

十、云仓活动

页面：ADM-CW-001~004。

活动商品编辑 ADM-CW-003 每个 SKU 必须配置：

• 稳定活动 SKU 与供货来源。
• 抢购价、活动数量、限购和时间。
• 预计销售周期正整数天。
• 到期在途处置宽限，默认 30 天，可配置 7 至 60 天。
• 结算模式三选一。
• 用户收益分成率、平台分成率合计 100%。
• 回购比例，默认 100%。
• 首次/二次售后观察期。
• 支持的邮寄、自提点和代销规则。

发布预检至少验证：

1. 来源 SKU 当前仍匹配。
2. 实际验收云仓库存充足。
3. 普通二次代销 SKU 映射有效且库存来源为 cloud_only。
4. 结算、周期、比例、去向、运费和责任字段完整。
5. 活动时间、限购和材料有效。

发布后保存规则快照，不能用后续编辑改写历史订单或持仓。

十一、云仓订单、去向与批次

首次订单和去向

页面：ADM-CW-007。

• 用户先付款，可继续抢购，之后在截止前选择。
• 一条订单明细全部数量只能选择邮寄、自提或代销之一。
• 邮寄补运费期限不晚于去向截止；超时迟到支付不得改变去向，只进入幂等全额退款。
• 云仓自提可以分次核销，每次形成不可变核销事实。
• 部分核销剩余量只能进入继续保留、改寄、退款或异常回购中的一种。
• 超过选择截止未处理时自动代销。

批次和真实二次销售

页面：ADM-CW-008~010。

• 每场活动的每个活动 SKU 对应一个批次。
• 活动库存、未支付订单和未抢库存闭合后才能启动批次。
• 二次销售来自普通商城真实订单，经完成和二次售后观察期后才计有效销售。
• 分配按最早到期批次和整数实物库存执行；持仓用六位小数记录经济等价量。
• 25/50/75/100% 是结算触发节点，金额按真实累计销售进度计算。
• 二次正常退款不直接追扣用户余额，先抵扣未入账/未来应付，不足由平台承担。

到期和回购

页面：ADM-CW-011。

1. 到期停止新分配。
2. 等待在途处置宽限。
3. 宽限截止固化所有权切割。
4. 系统计算回购预案。
5. 财务/运营核对数量、快照、金额和平台目标库存。
6. 审核通过后原子执行用户账本、平台库存、所有权和 Outbox。
7. 驳回只能修正事实关联或计算版本，不能修改历史单价/比例快照。

十二、财务、结单与五段对账

页面：ADM-FN-001~005。

商户供货货款

云仓商户货款按固定供货价计算。资格需要同时满足：

• 对应数量已验收。
• 首次购买按邮寄收货、云仓自提核销或代销进入正式批次完成。
• 首次售后观察期结束。
• 无争议、退款或冻结。

每日 02:00 归集上一自然日合格记录生成不可变结单。“已生成结单”不等于“资金已到账”；正式入账成功并产生 CRMEB 商户资金流水后才进入可用余额。

用户账本

本金、收益、回购分开显示。待结算、待审核、入账中 和 已入账 不得混写。普通经营退款不能把用户可用余额扣成负数；只有审核确认的错误入账或外部支付最终撤销才进入借方冲正。

五段对账

段	核对
1 首次订单	订单、支付、退款、去向和数量级完成
2 实体库存	来源预留、验收、活动占用、批次、退回/平台承接
3 二次零售	普通订单分配、观察期、有效销售和退款
4 业务账本	本金、收益、回购、商户货款和调整
5 正式资金	financial_posting、用户/商户余额和 CRMEB 流水

发现差异时先冻结扩大风险的动作，查看事实和公式快照，使用预演修复和原结果键重放。不得直接改最终余额、汇总进度或库存。

十三、农业与云仓异常

页面：ADM-PD-007/008、ADM-CW-012。

标准流程：

事实发现
→ 记录证据与影响对象
→ 冻结必要动作
→ 重算影响
→ 建立不可覆盖方案版本
→ 预检
→ 审核
→ 必要时用户确认
→ 分步幂等执行
→ 恒等式复核
→ 恢复或关闭

农业异常：

• 完全等价替换且不超过延期容忍期，用户 3 个自然日未响应可按快照接受。
• 减量、降级、超容忍期或需补款的方案，未确认默认拒绝并转未履约退款。
• 生产开始后退款只按交付退款基数和累计未履约数量计算。

云仓异常：

• 供货短缺、运费迟到支付、部分自提、退款回退、批次冻结、入账失败和回购预案均使用独立事实。
• 回购、账本和异常执行失败后以原结果键重试，不通过“改成成功”关闭。

十四、看不到或不能点击操作时

按顺序检查：

1. 当前账号是否有页面路由权限。
2. 对象是否在当前农业数据范围。
3. 后端 allowed_actions 是否包含该动作。
4. 对象状态和版本是否仍满足前置条件。
5. 数量、金额、库存和容量是否闭合。
6. 是否存在退款、争议、冻结或执行中任务。
7. 是否需要另一角色审核或用户确认。
8. 是否为异步操作，需在操作详情查看结果。
9. 外部支付、物流、文件或地图是否降级。

不应通过换超级管理员账号、直接改数据库或重复点击来绕过阻断。

十五、交班与证据

每个未闭合事项至少记录：

• 业务编号和页面编号。
• 对象状态、版本和授权范围。
• 规则/责任/金额快照版本。
• 库存或资金流水。
• 异常编号、方案版本和当前步骤。
• 审核人、执行人、时间和结果。
• operation_no、posting_id、Job 运行号或外部回执摘要。
• 下一责任角色和明确的下一动作。

十六、维护者追踪

业务	页面	API 族	重点测试
农业主数据	ADM-AG-*	farm/agriculture/*、farm/map/*	MAP-*、DB-REF-*、SEC-*
租地	ADM-LA-*	farm/land/*	LAND-*、LAND-ALLOC-*、LAND-EX-*
认养	ADM-AD-*	farm/adoption/*	ADOPT-*、ADOPT-ALLOC-*、ADOPT-EX-*
生产/履约	ADM-PD-*	farm/production/*、farm/output/*、farm/fulfillment/*	PROD-*、OUTPUT-*、FUL-*
溯源	ADM-TR-*	farm/trace/*	TRACE-*
云仓	ADM-CW-*	farm/cloud/*	CW-ACT/SUP/ORDER/DISP/RESALE/BUY-*
财务	ADM-FN-*	云仓账本、结单、入账和对账 API	CW-POST-*、MER-SET-*、CONC-*

详细字段、动作和状态分别以 30、31、33、37 为准；本手册不得成为另一个业务规则来源。