41 v1 service and field manual

SmartFarm V1 客服与现场作业手册

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

本文依据已确认的服务端身份、页面、权限和接口契约编写。对应页面完成开发、测试和发布后，才可作为正式操作手册。当前 smartfarm_service 原客服能力继续保留，V1 在同一项目新增农业桌面工作区和移动现场工作区。

一、职责与工作区

职责码	主要工作区	可操作范围
platform_customer_service	农业桌面	平台范围内租地、认养、云仓订单查询和异常建议
merchant_customer_service	农业桌面	商户上限内订单查询、联系记录和建议
crop_operator	移动现场	被分派农场/地块/种植批次与任务
livestock_operator	移动现场	被分派栏舍、个体/批次、健康和养殖任务
warehouse_operator	移动现场	被分派仓库、库位、验收、打包、发货和云仓核销
farm_reviewer	农业桌面	授权范围内生产/产出记录审核

固定入口：

路由	用途
/kefu/dashboard	原 PC 三栏客服工作台
/kefu/farm/desk/*	PC/平板横屏农业查询、协同和审核
/kefu/farm/work/*	手机/平板竖屏任务、扫码和现场录入
/kefu/entry	同时有多个工作区时选择入口

二、登录与授权范围

页面：SVC-AU-001~003。

登录复用现有客服账号和 service Token。登录后系统读取 farm/context，返回：

• 当前职责。
• 权限码。
• 农场、仓库、自提点和业务对象范围摘要。
• scope_version。
• 默认入口。
• 地图、扫码、上传和离线草稿能力状态。

规则：

1. 同时满足职责权限码和对象范围才可操作。
2. 列表先过滤范围再分页。
3. 按 ID 查询越界对象统一显示“未找到”，不能据此判断对象是否存在。
4. 范围变化后旧 scope_version 触发刷新，旧页面不能继续提交。
5. 看得到页面不代表能执行每个按钮，仍以 allowed_actions 为准。

三、农业订单查询

页面：SVC-CM-001。

可按用户、脱敏手机号、订单号、租地/认养类型和状态检索。详情展示：

• 用户脱敏信息。
• 套餐和订单快照。
• 真实地块、个体或批次份额。
• 生产批次和过程时间线。
• 产出、邮寄履约和售后。
• 异常方案和用户确认。
• 溯源入口。

客服可以解释状态、记录联系结果和提交建议，不能：

• 改地块/资产分配。
• 改承诺产出或退款金额。
• 改用户余额。
• 伪造生产、发货或确认事实。

四、云仓订单查询与异常协同

页面：SVC-CW-001/002。

详情展示：

• 首次订单和支付。
• 选择截止和最终去向。
• 邮寄补运费/退款。
• 云仓自提凭证、核销和剩余量。
• 代销持仓、批次进度和账本。
• 到期宽限、回购和冻结。
• 责任快照、通知和审计。

可提交的协同内容

• 联系记录。
• 事实补充和证据。
• 去向异常建议。
• 云仓自提逾期的继续保留、改寄、退款或异常回购建议。
• 需平台审核的库存/质量/账本异常。

客服不能直接修改批次进度、账本金额、回购比例或用户余额。

五、我的农业任务

页面：SVC-PD-001。

任务状态：

待接受 → 进行中 → 待审核/待依赖 → 已完成
                      ↘ 异常/已转派/已取消

标准步骤：

1. 查看任务对象、地点、要求、截止和版本。
2. 确认任务属于本人职责和范围。
3. 接受并开始任务。
4. 扫码或打开对象详情。
5. 完成对应业务记录和证据上传。
6. 提交审核或完成。
7. 查看结果和下一动作。

任务已转派、取消、完成或对象版本改变时，不得用旧页面继续提交。

六、扫码入口

页面：SVC-PD-002。

支持：

• 摄像头扫码。
• 从图片识别。
• 手工输入码。

可识别对象包括地块、养殖资产、生产批次、产出批次、履约和云仓自提。

扫码后必须由后端解析和验签，前端只展示后端返回的对象摘要和允许动作。二维码无效、过期、类型不符或超出范围时不显示内部对象信息。

移动浏览器无法打开摄像头时：

1. 检查 HTTPS 和相机权限。
2. 尝试图片识别。
3. 使用手工输入。
4. 仍失败时记录任务号和错误，不能跳过对象校验。

七、过程与健康记录

页面：SVC-PD-003。

农事/养殖过程记录

• 任务和生产批次。
• 事件类型。
• 发生时间。
• 物料、用量和指标。
• 内容和备注。
• 图片/视频证据。
• 是否建议对用户公开。

健康/防疫记录

• 个体资产或养殖批次。
• 健康类型和结果。
• 处理、用药或防疫信息。
• 发生时间和证据。
• 是否触发异常。

提交前重新核对对象范围、状态和版本。提交审核后不能直接覆盖原内容，需要修改时建立新版本或按驳回要求补充。

八、采收和产出录入

页面：SVC-PD-004。

填写：

• 来源生产批次。
• 品类、规格和单位。
• 总数量、合格数量、损耗数量和待检数量。
• 采收/生产日期、保质期。
• 仓库和库位。
• 质量说明和证据。

必须满足：

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

页面校验通过不代表最终入库成功。提交时后端会重新锁定对象、校验任务、范围、版本和数量。

九、仓储履约

页面：SVC-PD-005。

1. 入库验收

• 核对来源、应收、实收、合格、拒收和短少。
• 选择授权仓库/库位。
• 填写差异原因和证据。
• 提交后生成不可变入库/验收流水。

2. 拣货和打包

• 按分派任务进入，不进行全仓任意搜索。
• 按到期优先提示选择批次/库位。
• 核对履约明细和可拣数量。
• 记录包裹、重量和打包证据。

3. 出库和发货

• 核对包裹、地址状态和运费。
• 填写承运商、运单和出库时间。
• 运单唯一，重复时拒绝。
• 提交后不能覆盖原出库流水。

4. 云仓自提核销

云仓核销可以从 SVC-PD-005 移动任务或 SVC-CW-002 桌面协同进入，二者复用同一个 CW_PICKUP_VERIFY 业务操作。

核销前确认：

• 自提点/仓库在本人范围。
• 凭证有效。
• 用户脱敏信息匹配。
• 0 < 本次核销量 <= 剩余可提数量。

每次核销生成不可变记录并更新累计/剩余量。部分核销不等于整条明细完成；剩余量按继续保留、改寄、退款或异常回购处理。

租地和认养产出只有邮寄，不进入云仓自提核销。

十、异常上报

页面：SVC-PD-006。

填写：

• 异常类型和严重程度。
• 农场、资产、生产批次、订单或履约。
• 影响数量。
• 发生时间和原因。
• 证据。
• 建议方案。
• 是否建议暂停履约/销售。

现场人员只记录事实和建议。最终替换、退款、回购、账本和恢复决定由平台有权角色审核。

严重异常提交后应显示唯一异常编号和平台接收状态。重复点击使用同一 request_id，不得生成多条事实。

十一、生产/产出审核

页面：SVC-PD-007。

审核人查看：

• 原始录入。
• 数量方程。
• 证据附件。
• 任务、对象和范围。
• 当前版本和历史版本。
• 发布影响。

审核动作：

• 通过。
• 驳回并填写结构化原因和补充要求。

审核人不能直接编辑提交内容，不能审核本人无范围、已撤回、已被新版本替代或状态不允许的记录。

十二、本机离线草稿

页面：SVC-PD-008。

V1 是“本机离线草稿，不离线提交”：

• JSON 字段和可持久化媒体 Blob 保存在 IndexedDB。
• 草稿按账号、对象和 schema 版本隔离。
• 离线时可以编辑和保存，不能显示“已提交”。
• 网络恢复后重新上传媒体，并使用原 request_id 提交。
• 恢复前重新校验账号、范围、任务归属、对象状态和版本。

以下情况只允许查看可读摘要或删除：

• 账号已切换。
• 范围已撤销。
• 任务已完成/取消/转派。
• schema 不兼容。
• 媒体无法恢复且必需证据缺失。

登出后其他账号不得看到原账号草稿。

十三、证据附件

附件流程：

选择文件
→ 压缩/校验
→ 上传
→ 获得 attachment_id
→ 随业务请求绑定
→ 业务事实保存

只有 URL 不算正式证据。未绑定附件有有效期，过期后会被清理；已绑定业务事实的证据不能因人员调岗或任务完成而删除。

提交前检查：

• 上传状态为成功。
• attachment_id 属于当前账号和对象范围。
• 文件类型、大小和内容符合要求。
• 当前业务请求实际包含附件 ID。

十四、不可操作原因

场景	处理
账号/农业档案停用	停止操作，联系管理员
缺少职责权限	不换账号绕过，申请正确授权
对象未找到	可能不存在或越界，不探测其他 ID
范围版本变化	刷新 farm/context
任务已转派/完成	返回任务列表查看最新状态
二维码无效/过期	重新扫描或手工输入，仍失败则上报
对象版本冲突	刷新对象并重新确认内容
附件上传中/过期	等待重试或重新选择
数量方程不成立	复核实物，不强行提交
不在当前仓库/农场	由有权人员处理或重新分派
离线	保存本机草稿，恢复网络后提交
外部地图/物流/存储失败	使用允许的降级路径并保留错误摘要

十五、升级路径

问题	交给
账号、权限和范围	平台管理员/客服主管
任务分派和现场事实	农业运营/仓储主管
商品、供货和责任	云仓运营
严重生产/质量异常	农业审核和平台异常负责人
退款、账本、回购和冲正	财务/有权平台管理员
支付、队列、接口和系统错误	技术支持，附操作号和错误摘要

客服和现场人员不能通过直接改金额、库存、状态或数据库解决问题。

十六、交班证据链

task_id
→ 对象与范围
→ 开始时间
→ 业务记录版本
→ attachment_id
→ 提交结果
→ 审核记录
→ 异常编号
→ 最终状态

交班记录至少包含：

• 页面和任务编号。
• 当前状态、截止和下一动作。
• 已完成数量/剩余数量。
• 证据和版本。
• 异常/操作号。
• 已联系对象和结果。
• 下一责任角色。

十七、维护者追踪

流程	页面	API	测试
登录/上下文	SVC-AU-001~003	farm/context、farm/me	SVC-AUTH-*、SVC-CONTEXT-*、SEC-*
客服查询	SVC-CM-001、SVC-CW-001/002	order/cloud order/exception	SVC-AUTH-*、PAGE-SVC-001
任务/扫码	SVC-PD-001/002	task、scan resolve	SVC-SCAN-*、IDEM-*
过程/产出	SVC-PD-003/004	production、health、output	PROD-*、OUTPUT-*
仓储履约	SVC-PD-005	warehouse、fulfillment、cloud pickup	FUL-*、CW-PICKUP-*
异常/审核	SVC-PD-006/007	exception、review	LAND-EX-*、ADOPT-EX-*、SVC-REVIEW-*
离线草稿/附件	SVC-PD-008	attachment upload、正式业务提交	SVC-DRAFT-*、SVC-EVIDENCE-*

字段契约以 37 为准，操作和错误以 19/31 为准，状态竞态以 33 为准，测试以 22/43 为准。