# 周转筐管理平台 · 接口文档 > 版本 V1.9 + V2.0-pilot | 编制:食配官咨询(长沙食安云链信息技术有限公司) > 后端骨架:`server.js`(零依赖 Node,`node server.js 8090` 即可启动) > 作业模型:**① 物流排线 → ② 登记用筐数量 → ③ 出仓复核 → ④ 带回与遗留登记 → ⑤ 回场验收** > V1.8 新增:**KCP-9 影像留证**——六类录入单据附现场影像,张数不足接口拒绝(见第 3.6 节) > **V3.1 修订(11-13)**:② 改为**可选 + `noShot` 打标**(取消强制、保留入口)。判据由「拍够几张」改为「一张能不能证明」。 > **V3.10 修订(11-16 客户三. / 五.1)**:影像**只留 ④ 车级「本车卸货完成全景」一道硬前置**—— > ③ 取消一切影像要求(原「② 没拍就补 1 张」的兜底一并取消),④ 取消「每所有遗留学校各 1 张」; > ②③ 拍照入口保留、上传接口照收。对冲:新增**零影像统计**(`evidStat().zero` / `zeroEvidLines` / > `zeroEvidVehicles`),`/api/return` 与 `/api/seal` 返回 `zeroEvidence`,见 §3.6.4。 > **V3.9(11-16 客户十问反馈)**:期初遗留改成**滚动口径**(`carryInOf`,三端逐字相同,见 §3.4); > ④ 加**封存闸门**(已封存 → 422 `KCP-4` `sealed:true`);`/api/adjust` 返回 `baseHeld/adjustTotal/carryIn` 三者恒等; > 前端 `adaptState()` 把全局 `evidence` 按 `(车, 作业日)` 聚合回 `tasks[].evid`(服务端数据结构未变)。 > V1.9 新增:**基础信息库与表格导入**——`GET/POST /api/master`(客户/司机两份主数据,车辆只读投影)与 `POST /api/import`(三张固定模板先预览后入库),见第 3.10 节 > **V3.0(11-12 现场实测反馈)**:影像整体减张数(判据从「拍够几张」改为「一张能不能证明」); > ⑤-A 取消强制拍照、物流经理退出移动端验收;申报数支持按筐型分列;新增 > `POST /api/out-check/batch`(整车一键复核)与 `POST /api/adjust/apply|review`(调整单申请→审批); > 会话落盘 `sessions.json`(重启不掉线) > V2.0-pilot 新增:**登录与整态同步**——`PILOT_AUTH=1` 开启鉴权(scrypt 密码 / Bearer 会话 / 角色闸门 / 操作审计 / `rev` 乐观锁),见第 3.11 节。**默认关闭,不开就是演示模式** --- ## 0. 五步与岗位对照 | 步骤 | 接口 | 岗位 | 控制点 | |---|---|---|---| | ① 物流排线 | `POST /api/route` | 调度员 | KCP-1 无排线不得出仓;作业日只放开预排 +7 / 补录 −30 | | ② 登记用筐数量 | `POST /api/qty` | 生产主管(按学校 × 筐型分工) | KCP-2 逐校逐筐型登记 + **影像可选**(`noShot=true` 时打「未附影像」标) | | ③ 出仓复核 | `POST /api/out-check` | 配送司机 | KCP-3 账面 = 复核。**V3.10:影像不强制,`photoNeed('ck')` 恒 0,不再有 `PHOTO_REQUIRED`** | | ④ 带回与遗留 | `POST /api/return` | 配送司机 | KCP-4 分校闭环(送达取 ② 实际数、期初含调整单)+ **影像:车级 1 张(硬前置)、校级可选** | | ⑤-A 回场封存(V2.9) | `POST /api/seal` | 配送司机 | **影像可选补拍**(V3.1 起连勾选框也去掉,按钮即确认);申报数由服务端按 ④ 重算;签署后锁定,不可改不可删 | | ⑤-B 回场验收 | `POST /api/inbound` | 洗筐员(08:00 到岗,现场也叫「卫生员」) | **未封存不得验收**;KCP-5 差异自动开单 + **KCP-9 1 张(有差异 2 张)**;验收人以账号为准 | | 差异确认(V2.9) | `POST /api/inbound/ack` | 配送司机 / 物流经理代记 | 认账不改变入账;异议转「待复核」但不卡日结 | | 异常上报 | `POST /api/exceptions` | 任一现场岗 | **KCP-9 影像 1 张** | | 遗留差异调整(V2.3) | `POST /api/adjust` | 记账员 / 管理员 | 不改历史 ④,只往后冲抵期初遗留,必须写原因 | | 主数据维护(V1.9) | `GET/POST /api/master` | 调度员 / 管理员 | 只动客户/司机档案,不碰业务数据;车辆只读 | | 表格导入(V1.9) | `POST /api/import` | 调度员 / 管理员 | 一行错整批不入;排线导入拒绝覆盖已有进度 | **端侧归属**:小程序是**现场四岗共用端**(②③④⑤),调度员不接入小程序,`POST /api/route` 只由 PC 后台调用。 接口本身不区分端,靠 token 里的角色做授权:生产主管只能调 `/api/qty`,司机只能调 `/api/out-check`、`/api/return` 与 `/api/seal`, 物流经理 / 洗筐员只能调 `/api/inbound`,差异确认(`/api/inbound/ack`)司机与物流经理都能调(电话可能是经理打的)。 生产化时必须按此收口,否则四岗共用一个小程序会变成四岗都能改所有数。 **客户端形态(V2.2)**:两端同一份代码,靠 URL 参数切换形态 —— | 参数 | 形态 | 数据来源 | |---|---|---| | `?mode=api` | 连服务端(**内测现场用这个**) | 全部走本文档的接口,登录后写服务端 | | 不带参数 / `?mode=local` | 离线演示 | 本地种子,刷新即恢复,**两个手机看到的不是同一本账** | 移动端只在 `?mode=api` 下出现登录闸门;离线演示不出现(现场演示不需要账号)。 作业日两端同一口径:`bizDate = 录入时点 ≥ 19:00 ? 自然日+1 : 自然日`(KCP-0),**前端不传日期、不允许手选**。 **核心恒等式(KCP-4)** ``` 带回 + 期末遗留 = 期初遗留 + 当日送达 (带回含破损;破损不另加) ``` 任何一条分校记录不满足该式,接口直接返回 422,不允许落库。 --- ## 1. 通用约定 - Base URL:`http://127.0.0.1:8090` - 编码:UTF-8;请求与响应均为 `application/json` - 日期:`YYYY-MM-DD`;时间戳:ISO 8601 - 数据重置:`POST /api/reset`(删除 `data.json` 并恢复种子数据) ### 1.0 作业日口径(KCP-0 · **先看这一节**) 所有 `bizDate` / `biz_date` 字段都是**作业日(配送日)**,**不是自然日**: - 分拣时段 **19:00 开班 → 次日 03:00 收尾**,跨零点; - **录入时点 ≥ 19:00 时,作业日 = 自然日 + 1**; - 服务端由 `bizDateOf()` / `bizToday()` 统一计算,**客户端不传日期时一律默认当前作业日**; - **当日现场登记不接受客户端手工指定日期**(显式 `?date=` 仅用于历史查询)。 - **V2.3 例外:排线(①)允许指定作业日,但只在「预排未来 / 补录历史」两个窗口内**: 补录最多回溯 **30 天**,预排最多 **+7 天**,超出即拒;PC 端预排/补录必须填「原因」留痕。 作业日 ≠ 当前作业日时,排线单记 `dateManual=true` + `dateReason`。 现场四步(②③④⑤)仍然一律由服务端推导,不给任何人手选日期的机会。 > **★ V3.2 注意:排线单上的作业日有两个等价字段 `date` 与 `bizDate`。** > 历史原因 —— PC 端建单与台账只写 `date`,`/api/route`、`/api/import` 只写 `bizDate`, > 移动端按 `bizDate` 过滤,于是「PC 排的线手机看不到」(2026-11-16 现场事故)。 > 现在服务端 `normalize()` 双向补齐,**新建单会同时写两个字段**; > 自行读写状态时请按 `(t.bizDate || t.date)` 取作业日,别只认其中一个。 不按这个口径就会出事:19:00–24:00 的分拣量被算到前一天 → 出筐虚低、回筐全落到后一天 → 日相差长期为负、损耗率算错。 ### 1.1 状态码 | 状态码 | code | 含义 | |---|---|---| | 200 / 201 | — | 成功 / 创建成功 | | 400 | `BAD_REQUEST` | 参数缺失或非法(如破损数 > 带回数) | | 409 | `KCP-1` / `CONFLICT` | 重复排线、重复验收 | | 409 | `IMPORT_HAS_ERRORS` | **导入有错行,整批不入**,返回 `stat` / `rows`(逐行错误原因) | | 400 | `BAD_HEADER` | 导入内容识别不出表头(列名全不匹配) | | 400 | `BAD_RECORD` | 单条主数据 upsert 校验不过(如手机号格式、线路不存在) | | 400 | `BAD_KIND` | `kind` 不在 `customers / drivers / routes` 之内 | | 400 | `READ_ONLY` | 试图写 `vehicles`——车辆由司机的「绑定车号」带出,不单独建档 | | 401 | `UNAUTHORIZED` | **未登录或会话过期**(仅 `PILOT_AUTH=1` 时出现);请求头带 `Authorization: Bearer ` | | 401 | `BAD_CREDENTIAL` | 登录账号或密码不对(与「账号不存在」同文案,不泄露账号是否存在) | | 403 | `FORBIDDEN` | **角色不够**(仅 `PILOT_AUTH=1` 时出现);message 里写明限哪个岗位做,见 3.11.2 | | 409 | `REV_CONFLICT` | **整态同步版本过期**(仅 `PILOT_AUTH=1` 时出现),返回 `serverRev` / `yourRev`,前端应提示刷新而非重试 | | 429 | `TOO_MANY_TRIES` | 同一账号 5 分钟内错 5 次,锁 5 分钟 | | 410 | `GONE` | 已下线接口(旧的 /api/out、/api/back、/api/delivery、/api/sign) | | 422 | `KCP-1`~`KCP-5` | **业务硬校验拦截**,含义见各接口 | | 422 | `PHOTO_REQUIRED` | **KCP-9 影像张数不足**,返回 `scene` / `got` / `need` / `slots`。**V3.10 起只在 ④ 车级与 ⑤-B/异常上报出现**,②③ 不再返回该错误码 | | 500 | `INTERNAL` | 服务端异常 | > 422 与 400 的区别:400 是「参数不合法」,422 是「参数合法但违反业务流程」。前端应分别提示「请检查输入」和「请现场重数 / 请先拍照」。 --- ## 2. 查询类 ### 2.1 健康检查 `GET /api/health` ```json { "ok": true, "ts": "2026-10-19T06:27:16.580Z" } ``` ### 2.1.1 分拣时段与当前作业日(V1.7) `GET /api/shift` 前端顶栏、小程序首页都靠它显示「现在该干什么、录的数据算哪天」。 ```json { "key": "sorting", "label": "分拣中", "hint": "19:00 开班,录入归次日作业日", "bizDate": "2026-10-21", // 当前作业日(19:00 后 = 次日) "today": "2026-10-20", // 自然日 "sortOpen": "19:00", "sortClose": "03:00" } ``` `key` 取值:`sorting`(19:00–23:59 分拣中)/ `closing`(00:00–02:59 分拣收尾)/ `delivery`(03:00–10:59 配送验收)/ `settle`(11:00–17:59 日结窗口)/ `overdue`(18:00 后日结超时)。 ### 2.2 今日任务 `GET /api/tasks?date=2026-10-19` ```json { "date": "2026-10-19", "count": 1, "rows": [{ "id": "RT8-20261019", "bizDate": "2026-10-19", "vehicle": "8", "line": "东乡线", "driver": "李师傅", "planner": "调度员·张工", "schools": [{ "id": "S007", "seq": 1, "eta": "07:00" }], "delivered": { "S007": 10 }, "qty": { "SX": { "q": 14, "by": "生产主管·刘工", "at": "2026-10-19T03:41:00.000Z" }, "GS": { "q": 8, "by": "生产主管·陈工", "at": "2026-10-19T03:44:00.000Z" } }, "outCheck": { "qty": 22, "by": "李师傅", "at": "2026-10-19T04:38:00.000Z" }, "returns": [{ "schoolId": "S007", "back": 18, "broken": 0, "left": 4, "carryIn": 12, "delivered": 10 }], "inbound": null }] } ``` ### 2.3 五步进度 `GET /api/flow?date=2026-10-19` ```json { "date": "2026-10-19", "planned": 1, "planSchools": 3, "qtyLines": 1, "checked": 1, "returnedSchools": 3, "inboundLines": 1, "backSum": 54, "inSum": 49, "accDiff": 5, "identityFail": 0, "fullDone": 1, "closureRate": 100, "accRate": 9.26, "evidence": { "total": 12, "byScene": { "reg": 2, "ck": 1, "ret": 8, "inb": 1, "rep": 0 }, "clockSkew": 0, "pending": 0, "shortLines": ["7"] } } ``` | 字段 | 说明 | 对应 KPI | |---|---|---| | `qtyLines` / `planned` | 用筐登记齐全率(所有启用筐型均已登记即可,**② 影像自 V3.1 起不再计入**) | 分筐型登记率 | | `checked` / `planned` | 出仓复核完成率 | 排线执行率 | | `identityFail` | 闭环不平的学校数(应恒为 0) | 分校闭环通过率 | | `accDiff` / `backSum` | 回场验收差异率 | 回场验收差异率 | | `evidence.shortLines` | 影像张数不足的线路数(V3.10 之后基本只剩「④ 车级没拍」) | 影像留证率 | | `zeroEvidLines` / `zeroEvidVehicles` | **V3.10 新增**:②③④ 一张影像都没有的车数与车号列表 | 零影像车追踪 | | `evidence.onRoad` / `evidence.zero` / `evidence.zeroLines` | 作业三段(reg+ck+ret)张数合计 / 是否为零 / 当日零影像线路数 | 同上(服务端与 PC 同口径) | | `evidence.clockSkew` / `pending` | 时间可疑张数 / 待上传张数 | 影像待核 | ### 2.4 台账 / KPI / 线路 / 异常 / 学校 / 筐具 | 接口 | 说明 | |---|---| | `GET /api/ledger?month=9` | 每日台账(出筐=复核一致数,回筐=验收合格数) | | `GET /api/kpi` | 返回 `month9` / `month10` 两个口径 | | `GET /api/lines` | 线路聚合 + 按车按日明细 | | `GET /api/exceptions?status=待处理` | 异常单列表 | | `GET /api/schools?line=城区线` | 学校档案 + `declaredHeld` / `convertedHeld` | | `GET /api/baskets` | 筐具档案(兼容别名,返回筐型字典) | | `GET /api/types` | **筐型字典**(V1.6):全部筐型 + 启用中的筐型 | | `POST /api/types` | **新增 / 修改 / 启停筐型**(后端没有它,筐型就还是写死的) | | `GET /api/evidence` | **影像台账 + 达标结论**(V1.8):按 `date` / `vehicle` / `scene` 过滤 | `GET /api/kpi` 的损耗口径(**V3.8 重写,先看这段再改代码**): ``` 期初实盘 base = stock_book.total_qty(无建账单时回落 kpi_config.base_stock) 累计入库 inSum = Σ stock_in.total_qty 可盘点基数 stockBase = base + inSum ← 分母 累计损耗 loss = base − (车间盘点 + 学校遗留) ← ★ 分子不含 inSum 损耗率 lossRate = loss ÷ stockBase 已报损 lossExplained = Σ stock_loss.total_qty(只算审批通过的) 待倒查 lossOpen = loss − lossExplained ← 现场真正要盯的数 // 9 月真实数据:117 个 / 3.139%(此时 inSum=0,与旧口径同值) ``` 四个硬规则: 1. **分子不含入库**。入库同时抬高「应有」与「实有」,两端约掉;写进分子 = 补货凭空造损耗。 2. **分母必须含入库**。只用期初当分母,补货越多同一笔净灭失算出来越「好看」,KCP-7 红线被稀释。 3. **`loss` 允许为负**(盘盈)。旧式 `Math.max(0, …)` 把盘盈截断成 0,看着「没差异」,其实掩盖了另一个错误。 4. **`lossExplained` 只统计审批生效的报损**(`stock_loss`),待审批的不算 —— 否则报上去就能减少待倒查,闸门白设。 返回体在原有字段外**新增** `stockBase` / `inSum` / `lossExplained` / `lossOpen`,老客户端可忽略。 --- ## 3. 五步作业接口 ### 3.1 ① 物流排线 `POST /api/route` ```json { "bizDate": "2026-10-19", "vehicle": "8", "driver": "李师傅", "crew": ["李师傅", "王师傅"], "planner": "调度员·张工", "schools": [ { "id": "S007", "seq": 1, "eta": "06:20" }, { "id": "S008", "seq": 2, "eta": "06:55" } ], "delivered": { "S007": 10, "S008": 12 } } ``` - `schools` 中的学校必须存在于 `school` 表,否则 400。 - 同一车同一天重复排线返回 **409 `KCP-1`**(对应库表唯一键 `uk_date_vehicle`)。 - `delivered`(V2.3 起**降级为兼容字段**):**送达筐数不再由排线预设**,一律等 ② 按校登记的实际数。 传了只按显式键记;不传就是空,不会凭空填 0 冒充实际值。新接入方不要依赖它。 - **排线单主键(V2.3)**:`作业日 + 线路 + 车号`。一条线路可以有多台车(一线多车), 每台车的学校按「客户档案的默认车号」自动分配,调度员可逐校改。 - **「待分配」不再静默丢弃(V3.0 / 11-12 反馈一.1)**:客户报「模板不支持一条线路多个学校」, 实测最常见的真实原因是这几所学校的客户档案**没填默认车号** —— 它们不生成排线单, 导入完看着就是「少了几所学校」,而提示只说「生成 N 张」,压根不提被跳过的。 现在预览阶段单独统计 `pending`(涉及哪几所),并给一个「统一挂到 X 号车 + 写回档案」的入口; 没补车号就提交时,返回提示里必须写明「N 所被跳过」。 - **导入模板(V3.6)**:`作业日 / 线路 / 客户名称 / 司机`。 原「序号」「送达筐数」两列取消(序号按导入顺序生成,送达数以 ② 为准); 老模板(`车号` / `客户编码`)仍可导入 —— 车号会反查成线路,客户编码会反查成客户。 **V3.6(11-16)删掉「到校时段」列**:`schools[].slot` / `slots{}` 不再写入, `schools[].eta` 退化为按行序推的粗排值(第 1 站 06:20,每站 +35 分钟),仅供参考、不是承诺时间。 客户档案的 `slot` 字段同步删除;旧表里若还带着这一列,当**多余列忽略**,不会报错。 - `crew`(V2.2):同车司机(主驾 + 副驾/换班),字符串数组或 `、,,/` 分隔的字符串。 **现场端没有司机档案,这是它唯一能知道「这车今天不止一个人」的渠道**; 拿不到名单就没法做 ③ 的多司机分认领(`/api/out-check` 的 `parts`)。 - **V3.7(11-16):`driver` 与 `crew` 由排线界面直接指定。** 以前排线只填车号,司机由 PC 按司机档案按车带出,界面上既看不见也改不了(只有 Excel 导入带「司机」列能改)。 现在新增排线弹窗按每台已分配的车列一行「主驾 / 随车」,默认取档案值、可改, **改的是这一单、不动司机档案**。落库多带一个 `driverSrc`: `manual`(排线时定下)/ `arch`(弹窗未渲染司机区,回落档案)/ `none`(明确选了「待指派」)。 `driver` 允许为空串以外的 `待指派`,但 `driverSrc=none` 的单子会进「未定司机」统计。 ### 3.2 ② 登记用筐数量(KCP-2 · 按「学校 × 筐型」逐项登记) `POST /api/qty` **按校提交(V2.3,推荐;现场是「按学校分开装」,只有某校某筐型才是实数)**: ```json { "bizDate": "2026-10-19", "vehicle": "8", "by": "刘工", "bySchool": { "S001": { "SX": 10, "GS": 2 }, "S002": { "SX": 5, "GS": 0 }, "S003": { "SX": 4, "GS": 1 } } } ``` - 传了 `bySchool` 就**不再需要 `items`**(传了也忽略)。线路级 `t.qty` 由各校合计派生。 - 缺学校、缺筐型、给 `null` → 400;给 **`0` 是合法登记**(今天这所学校不用这种筐)。 - 学校不在本车排线单里 → 400 `BAD_REQUEST`。 - 某校某筐型留空时,`missingDetail` 按「学校·筐型」返回,现场才知道去哪补: ```json { "ok": true, "readyForOut": false, "missing": ["GS"], "missingDetail": ["第三小学·果蔬筐", "第三小学·水产筐"], "detail": [ { "code": "SX", "name": "生鲜筐", "q": 19, "by": "刘工" } ], "total": 21 } ``` #### 3.2.0 班组分工提交(V2.6) 生产主管分**生鲜组 / 果蔬组**两个班组,各登各的筐型。请求里多带一个 `codes`: ```json { "bizDate": "2026-11-09", "vehicle": "21", "by": "生产主管·刘工(生鲜组)", "codes": ["SX"], "bySchool": { "S001": { "SX": 4 }, "S002": { "SX": 6 } } } ``` - `codes` = **本次提交负责的筐型**。服务端只校验、只落库这些筐型;`codes` 之外的键**直接忽略**(另一组的地盘,传了空值也不算本组漏填)。 - **增量合并**:`qtyBySchool` 以原有数据为底,只覆盖 `codes` 里的筐型。两组先后提交同一张单,**后交的不会把先交的清掉**。 - 不传 `codes` = 全量提交,行为与 V2.3 完全一致(旧调用方无需改动)。 - 按筐型留痕写进 `t.regByType`:谁、几点、登了哪种筐、归哪个班组。 ```json { "ok": true, "scope": ["SX"], "myReady": true, "myMissing": [], "myMissingNames": [], "readyForOut": false, "missing": ["GS"], "missingNames": ["果蔬筐"], "regByType": { "SX": { "at": "2026-11-05T03:40:00.000Z", "by": "生产主管·刘工(生鲜组)", "byUserId": "U03", "dept": "生鲜", "name": "生鲜筐" } }, "message": "本组登记已完成;整车出仓还需等 果蔬筐 登记" } ``` | 字段 | 含义 | |---|---| | `scope` | 本次提交负责的筐型(不传 `codes` 时为 `null`) | | `myReady` | **本组**是否登齐(可以提交、可以走了) | | `myMissing` / `myMissingDetail` | 本组还缺什么(只报自己这摊) | | `readyForOut` / `missing` | **整车**是否可出仓、还缺什么(仍是全量判定) | > **KCP-2 一点没松**:分工只改「谁登哪些筐」,`/api/out-check` 仍要求**所有启用筐型 × 所有学校**都登记齐全。 > 只交了一组的车,③ 会被 422 `KCP-2` 拦住 —— 整车装车时两种筐都在车上。 **线路级提交(兼容旧调用;没有按校数据时仍可用)**: 单项: ```json { "bizDate": "2026-10-19", "vehicle": "8", "biz": "SX", "qty": 14, "by": "刘工" } ``` 批量: ```json { "bizDate": "2026-10-19", "vehicle": "8", "items": [ { "biz": "SX", "qty": 14, "by": "刘工" }, { "biz": "GS", "qty": 8, "by": "陈工" }, { "biz": "SC", "qty": 4, "by": "周工" } ] } ``` ```json { "ok": true, "readyForOut": false, "missing": ["GS", "SC"], "missingNames": ["果蔬筐", "水产筐"], "detail": [ { "code": "SX", "name": "生鲜筐", "q": 14, "by": "刘工" }, { "code": "GS", "name": "果蔬筐", "q": 8, "by": "陈工" } ], "total": 22, "evidence": { "scene": "reg", "got": 0, "need": 2, "ready": false, "slots": ["装筐区全景(能看出筐型)", "已装车筐垛 / 分筐型特写"] }, "message": "KCP-2:还缺 果蔬筐、水产筐 登记,该线路不得出仓" } ``` - `biz` 可传**筐型编码**(`SX`)或**筐型名称**(`生鲜筐`);旧版中文业务线名(`生鲜` / `果蔬`)自动映射到 `SX` / `GS`。 - 传了未定义的筐型 → 400 `BAD_BASKET_TYPE`;传已停用的筐型 → 400 `BAD_BASKET_TYPE`。 - **空 ≠ 0(V2.1)**:留空 / `null` → 400 `BAD_REQUEST`(未登记);`0` → 201(登记为 0)。旧规则「`qty <= 0` 一律 400」会让「今天这条线不分果蔬筐」永远提交不了。 - **周转筐不区分颜色**,每种筐型只传一个 `qty`。旧字段 `whiteQty` / `blueQty` 仍兼容(服务端自动求和),仅为迁移期使用。 - **允许先登记部分筐型**(`201`),但 `readyForOut=false`;真正出仓时由 `/api/out-check` 拦截。 - **KCP-9(V3.10)**:数量允许先落库(司机那边要等着看账面数)。**② 影像可选,不影响 `readyForOut`** —— 只有「缺筐型登记」才会 `readyForOut=false`。没拍照的单子照常出仓,`evidence.need=0 / optional=true`,`message` 如实提示「② 未附影像,不强制补拍;若全车都没拍会标「零影像」」。 - **`noShot` 三态**:客户端传 `true` → 写 `task.regNoShot`;传 `false` → 清除该标记;**不传(老客户端)→ 既不写也不清**。最后这条是关键:默认写 false 会把历史数据一夜之间全标成「无影像」,报表直接失真。 - 登记变更后,已完成的出仓复核**自动作废**(账面数变了,必须重新复核);**同时 ② 的有效影像也作废**——账面数变了,旧照片就不能再证明「现在装了这么多筐」。V3.10 起作废后不再要求补拍,只是回到「未附影像」状态。 - 无排线单时返回 **422 `KCP-1`**;系统无启用筐型时返回 **400 `NO_BASKET_TYPE`**。 ### 3.2.1 筐型字典(V1.6 可自定义) `GET /api/types` ```json { "count": 3, "activeCount": 2, "rows": [ { "code": "SX", "name": "生鲜筐", "spec": "600×400×300", "price": 43, "qty": 2500, "status": "启用", "sort": 1, "owner": "刘工" } ], "active": [ ] } ``` `POST /api/types` —— **带已存在 `code` = 编辑,不带 = 新增** ```json { "code": "SC", "name": "水产筐", "spec": "580×380×280", "price": 48, "qty": 300, "owner": "周工", "note": "水产专用", "dept": "水产" } ``` **`dept` 归属班组(V2.6)**:填「生鲜」/「果蔬」则该筐型只出现在对应班组的生产主管小程序上; 留空或「共用」= 哪个组都要登。默认 `SX → 生鲜`、`GS → 果蔬`,新建筐型按编码自动带默认值。 超过 10 个字 → 400 `BAD_DEPT`。 | 场景 | 返回 | |---|---| | 新增成功 | 201,`{ ok, created:true, type }` | | 编辑成功 | 200,`{ ok, updated:true, type }` | | 编码格式非法(非 2–8 位大写字母数字) | 400 `BAD_TYPE_CODE` | | 新增时编码重复 | 409 `DUP_TYPE_CODE` | | 名称重复 | 409 `DUP_TYPE_NAME` | | 停用最后一种启用筐型 | 409 `LAST_ACTIVE_TYPE` | | `status` 非法 | 400 `BAD_STATUS` | | `dept` 超过 10 个字 | 400 `BAD_DEPT` | 启停切换就传 `{ "code": "SC", "status": "停用" }`。停用只影响后续登记,历史登记与台账不回改; 停用当日已登记该筐型的线路,其数量仍计入当日合计。 > **为什么必须有这个接口**:KCP-2 的校验口径是「当日启用的每种筐型都必须登记」。 > 如果筐型只能写在代码里,现场多一种规格就得改程序、重新部署,流程落地立刻卡住。 ### 3.3 ③ 出仓复核(KCP-3) `POST /api/out-check` ```json { "bizDate": "2026-10-19", "vehicle": "8", "reviewQty": 22, "driver": "李师傅" } ``` | 场景 | 返回 | |---|---| | 无排线 | 422 `KCP-1` | | 缺任一启用筐型的登记 | 422 `KCP-2` + `missing` / `missingNames` | | 复核数 ≠ 账面数 | 422 `KCP-3` + `bookQty` / `reviewQty` | | **V3.10:影像一张都没有** | **201 照常放行**(不再有 `PHOTO_REQUIRED`;返回体带 `evidence.zero` 标记) | | 一致 | 201,写入 `outCheck`,该数量进入台账「出筐」 | **校验顺序:KCP-2(筐型)→ KCP-3(数字)→ 结束。** V3.10 起本接口不再有影像闸门,`photoNeed('ck')` 恒为 0;`outCheck.photoCount` 仍如实记录(拍了就 > 0),供台账与抽查参考。 ```json { "ok": true, "bookQty": 22, "reviewQty": 22, "evidence": { "total": 0, "byScene": { "reg": 0, "ck": 0, "ret": 0, "inb": 0 }, "onRoad": 0, "zero": true, "clockSkew": 0, "pending": 0 }, "task": { } } ``` > `bookQty` 由服务端按 `basket_apply` 逐筐型汇总,客户端**不可传账面数**,防止前端算错或篡改。 > 影像张数由服务端按 `evidence` 表实时统计,客户端传的 `photoCount` **只作参考、不作放行依据**。 > **V3.10 迁移提示**:老客户端若收到过 `PHOTO_REQUIRED` 并据此弹「请补拍」,升级后会直接失败到 201 —— 属预期变化,客户端应把「③ 补拍」的引导文案改成「可选」。 #### 3.3.1 整车一键复核(V3.0 / 11-12 反馈四.3) `POST /api/out-check/batch` 一个司机跑两三条线是常态,逐台切进去复核全是重复劳动 —— 现场最后就是干脆不点。 ```json { "bizDate": "2026-10-19", "items": [{ "vehicle": "8" }, { "vehicle": "9", "reviewQty": 22 }] } ``` **★ 一键 ≠ 免检。** 每台车仍逐单跑 KCP-2 / KCP-9 / KCP-3,账也逐单落; 改变的只是「一次提交一台」变成「一次提交多台」。任一车不合格**只跳过那一台**, 不让一台车把其余车卡住。 | 字段 | 说明 | |---|---| | `items[].reviewQty` | 省略时按账面数确认(前端「一键」用的就是这个);给了就必须等于账面,否则该车判 KCP-3 | | 响应 `results[]` | 逐车结果 `{ vehicle, ok, qty?, code?, message?, skipped? }` | ```json { "ok": true, "confirmed": 2, "total": 3, "results": [ { "vehicle": "8", "ok": true, "qty": 22 }, { "vehicle": "9", "ok": true, "qty": 18 }, { "vehicle": "10", "ok": false, "code": "KCP-2", "message": "缺 果蔬筐 登记" } ] } ``` - 全部跳过(都已复核过)返回 **200**,`confirmed: 0`,逐车 `skipped: true`; - 至少落了一单返回 **201**; - 登录态下以账号为准:只认这个人档案里绑的车,客户端多报的车号一律丢弃(无车 → 403 `NO_VEHICLE`)。 ### 3.4 ④ 带回与遗留登记(KCP-4) `POST /api/return` ```json { "bizDate": "2026-10-19", "vehicle": "8", "schoolId": "S007", "backQty": 18, "brokenQty": 1, "leftQty": 4, "diffReason": "3 个被学校食堂借走,下周归还", "photoCount": 2 } ``` ```json { "ok": true, "record": { "schoolId": "S007", "carryIn": 12, "delivered": 10, "back": 18, "broken": 1, "left": 4, "adjustIn": 0, "autoLeft": 4, "diffReason": "", "gap": 0 }, "schoolHeld": 4, "progress": "1/3", "exception": null } ``` 校验顺序: 1. 无排线 → 422 `KCP-1` 2. 未完成出仓复核 → 422 `KCP-3` 3. **该车该作业日已封存 → 422 `KCP-4`(`sealed: true`)** —— V3.9,见下 4. 学校不在当日排线清单 → 400 5. `brokenQty > backQty` → 400 6. `back + left ≠ carryIn + delivered` **且没传 `diffReason`** → **422 `KCP-4`**,返回完整算式、`gap` 与 `autoLeft` 7. 缺车级「本车卸货完成全景」(`ref:'@car'`) → **422 `PHOTO_REQUIRED`** —— **V3.10:只剩这一道**。原第 7 条的「该校有遗留 → 要 1 张遗留筐照片」已取消, 校级照片仍可上传(`ref=学校 id`),`record.photos` 会如实记录,但不再拦提交。 **封存闸门排在闭环校验之前**:已封存的单子不该再纠结「平不平」,直接告诉司机数据锁了、要改走调整单。 **闭环(KCP-4)在影像(KCP-9)之前**:数字都不自洽的话,拍了照也没意义,先让他把数对上。 返回体新增 `evidence`(`evidStat` 结果)与 `zeroEvidence`(`= evidence.zero`):**本车 ②③④ 一张影像都没有**。 它不拦提交,但前端要在提交成功的那一刻就把这个事实告诉司机 —— 等事后抽查才通知,他只会觉得系统在找茬。 ```json { "code": "KCP-4", "message": "分校闭环不平:带回 18 + 遗留 2 = 20,应等于 期初 12 + 送达 10 = 22,差 -2。回车上重数,或填写差异原因", "carryIn": 12, "delivered": 10, "back": 18, "broken": 1, "left": 2, "gap": -2, "autoLeft": 4 } ``` #### V2.7(11-06 反馈二.2):不平可以过,但必须留痕 原来的 422 是**硬拦**。硬拦的实际后果是现场回去把某一头的数改平 —— 改完照样平, 闸门形同虚设,而且账面从此是假的。所以改成**留痕才过**: | 请求 | 结果 | |---|---| | 不平 + 无 `diffReason` | 422 `KCP-4`(不放松这一档) | | 不平 + 有 `diffReason` | 201,`record.diffReason` 落库,**同时自动开一张「④ 遗留差异」异常单** | | 平 | 201,不写 `diffReason`、不开异常单 | 放行的只有「静默通过」这一种,异常单与原因都留在库里,月底对账翻得到。 `record.autoLeft` 是系统按 `期初 + 送达 − 带回` 算出来的应留数 —— **它和人工填的 `left` 分两个字段存**,否则事后没人分得清这个「遗留」是真点出来的还是被凑出来的。 #### V3.9:④ 封存后锁定(客户五.4) 封存 = 司机报数 + 签署,洗筐员随后按这份快照点数。封存之后还能改数, 快照与验收基准立刻错开,而账面上查不出是谁改的 —— 所以服务端在这里加了一道硬闸门: ```json { "code": "KCP-4", "sealed": true, "sealAt": "2026-11-16T06:12:33.000Z", "message": "该车已于 06:12 封存,数据锁定;确需修正请走差异调整单" } ``` - 前端拿到 `sealed: true` 会把送回页切成**只读态**并指路 `POST /api/adjust/apply`。 - 口子没堵死:确有错的走**差异调整单**(有申请、有审批、有留痕,冲抵的是期初而不是历史)。 - 老数据里 `seal` 为 `null`(未封存)与没有这个键都视为未封存 —— 判存在用 `'seal' in t`。 `carryIn` 与 `delivered` 的口径(V3.9 重写,三端逐字相同): | 场景 | 期初遗留 `carryIn` | |---|---| | 当日已登记过 ④ | `record.carryIn − record.adjustIn + adjustOn(当日)`(历史账不改写,但当天新开的调整单要能立刻生效) | | 该日之前有 ④ 记录 | `最近一次的 left + (那次日期, 当日] 的调整`(滚动口径,不回到档案基线) | | 都没有 | `school.opening || school.held + (≤ 当日) 的调整`(此时档案值仍是导入基线) | - **`adjustIn`** 是 V3.9 新字段:提交这一刻已经算进 `carryIn` 的「当日调整合计」。 当日再开调整单时靠它把旧 `carryIn` 换算成新值;V3.8 之前的老记录没有这个字段,原样沿用 `carryIn`。 - `record.carryIn` 是**签字那一刻的数**,永远不被后续调整单改写(否则历史对不上)。 - **当日送达 `delivered` = ② 按校登记的实际数**(`t.qtyBySchool[sid]` 各筐型求和)。 没有按校登记的老单据才回落到排线计划值 `t.delivered[sid]`。 成功后 `school.held` 仍会被更新为 `leftQty`,但它已**降级为「没有 ④ 记录时的兜底基线」** —— 主口径是滚动推算。修 V3.9 之前,三端一边拿这个会被改写的字段当基准、一边又各算一套, 同一所学校能同时出现 16 和 32 两个数(客户报的九.1 就是这么来的)。 > **为什么 ④ 是逐校而不是整车**:「遗留」是整条链上最容易编的一个数——学校压着多少筐,没有第三方能核。 > 整车一张照片只能证明「车来过」,证明不了「A 校留了 4 个、B 校留了 0 个」。所以必须逐校拍,且该校仍有遗留时加拍遗留筐存放位置。 ### 3.4.1 遗留差异调整单(V2.3) `POST /api/adjust` 期初遗留是**只读基线**。盘点发现基线本身有偏差时,不改历史,而是开一张有原因的调整单往后冲抵。 ```json { "sid": "S007", "date": "2026-10-19", "qty": -4, "reason": "9 月盘点盘亏冲抵" } ``` - `qty` 为带符号数量:盘亏给负数、盘盈给正数;**0 会被拒绝**(不调整就别开单)。 - `reason` 必填 —— 对账时要能解释这一笔。 - 登录态下 `by` 一律取账号姓名。 ```json { "ok": true, "record": { "id": "ADJ1234567", "sid": "S007", "date": "2026-10-19", "qty": -4, "reason": "9 月盘点盘亏冲抵", "by": "记账员·孙会计" }, "baseHeld": 12, "adjustTotal": -4, "carryIn": 8 } ``` 调整生效后,按旧数提交 ④ 会平不上,返回 422 `KCP-4`,且响应里同时给出 `baseIn` / `adjust` / `delivered` 三个数,方便现场一眼看出差在哪。 **V3.9:响应里这三个数是同一套算式解出来的**,且恒满足 `carryIn = baseHeld + adjustTotal`: ```json { "baseHeld": 12, "adjustTotal": -4, "carryIn": 8 } ``` - `baseHeld` 定义为「**不含当日的当前基准**」。当日已登记过 ④ 时,`carryIn` 以那条记录为锚 (见 §3.4 的 `adjustIn` 规则),此时 `baseHeld` 只能由 `carryIn` 反推 —— 否则三个数之间没有恒等关系,前端拿去做二次换算就会又分叉出一个口径。 #### 3.4.1.1 调整单「申请 → 审批」(V3.0 / 11-12 反馈五.2) `POST /api/adjust` 是**记账员**直接生效的口径。现场司机要的是「能提一张单」, 不是「能改账」—— 所以另开一条链路:**申请**进待审队列,**审批通过**才生成正式调整单。 > 为什么非要分两步:调整单冲的是「期初遗留」,也就是 KCP-4 分校闭环恒等式的基准。 > 现场若有即时生效权,不平的时候他自己就能把式子配平 —— 改完照样平,闸门立刻形同虚设。 **① 申请** `POST /api/adjust/apply`(角色:司机) ```json { "sid": "S007", "date": "2026-10-19", "qty": -3, "reason": "上学期末 3 个被食堂借走,本周已归还", "vehicle": "8" } ``` | 校验 | 返回 | |---|---| | `qty` 为空或 0 | 400(没差异就别开单) | | `\|qty\|` > 200 | 400(手抖多打一个 0 是现场最常见的错) | | `reason` 少于 4 字 | 400(对账时要能解释这一笔) | | 同校同日已有待审单 | 409 `CONFLICT` | **申请绝不进 `adjust` 表**,只进 `adjustReq`,不参与任何闭环计算。 **② 审批** `POST /api/adjust/review`(角色:记账员 / 物流经理) ```json { "id": "ADR1234567", "pass": true, "note": "已与学校核实" } ``` - `pass: true` → 生成一条正式调整单(带 `fromReq` 指回申请单),期初遗留随之重算; - `pass: false` → 只把状态改成「驳回」,**账上什么都不动**,`note` 必填; - 已处理过的申请再审 → 409(不重复入账)。 ```json { "ok": true, "record": { "id": "ADR1234567", "status": "通过", "reviewedBy": "记账员·孙会计", "adjustId": "ADJ7654321" }, "adjust": { "id": "ADJ7654321", "sid": "S007", "qty": -3, "fromReq": "ADR1234567" }, "adjustTotal": -3, "carryIn": 9 } ``` ### 3.5 ⑤ 回场验收(KCP-5) `POST /api/inbound` > **V2.9 前置:必须先有「回场封存单」(`POST /api/seal`)。** > 客户现场:司机 06:00-07:00 陆续回场,洗筐员 08:00 才上班,中间 1-2 小时 > 原来靠「司机拍照发微信群 + 洗筐员上班后点数 + 司机核对签字」。 > 微信群图可撤回、可发相册旧图、没有服务器时间、绑不到单据号 → 不能当留证。 > 所以 ⑤ 拆两段:**司机封存(FR-05A,报数 + 一键确认签署,V3.1 起不强制拍照)→ 洗筐员点数(FR-05)**。 > 没有封存单就调本接口 → **422 `KCP-4`**:差异没有比较基准,异常单也判不出责任在谁。 ```json { "bizDate": "2026-10-19", "vehicle": "8", "inspectQty": 49, "brokenQty": 1, "inspectorRole": "logistics", "by": "吴工", "byType": { "SX": { "q": 42 }, "GS": { "q": 7 } } } ``` `inspectorRole` 表示当班验收岗位,用于区分两班: | 值 | 含义 | 使用时机 | |---|---|---| | `logistics` | 物流经理(默认值,可省略) | 封存车积压时协助验收 / 差异复核 | | `washer` | 洗筐员 | **正常路径**:08:00 到岗后逐车点数 | `by` 只填姓名,服务端会拼成「岗位·姓名」(如 `洗筐员·李师傅`)后落库,便于交接与差异倒查。 > **V2.3:开了鉴权(`PILOT_AUTH=1`)时,`inspectorRole` 与 `by` 一律作废,以登录账号为准。** > 账号角色是 物流经理 → 强制 `logistics`;洗筐员 → 强制 `washer`;其他角色 → **403 `FORBIDDEN_ROLE`**。 > 落库同时写 `byUserId`。理由很直白:验收人是「谁为这个数负责」的证据,让调用方自己声明等于没有证据。 > 身份判定放在数据校验之前 —— 连验收资格都没有的人,不该先看到「还差几所」这种内部细节。 | 场景 | 返回 | |---|---| | 账号不是验收岗位(鉴权开启时) | 403 `FORBIDDEN_ROLE` | | **未完成回场封存** | **422 `KCP-4`**(V2.9) | | 带回登记未完成 | 422 `KCP-4`(前置条件不足) | | 验收岗位非法 | 400 `BAD_INSPECTOR_ROLE`(只接受 `logistics` / `washer`) | | 破损数 > 验收数 | 400 `BAD_BROKEN` | | `byType` 里有未知 / 已停用筐型、或数量不是非负整数 | 400 `BAD_TYPE_QTY` | | `byType` 少报某一种启用筐型 | **422 `KCP-5`**(「空」是没登记,不是 0) | | 影像不足(`diff ≠ 0` 要 2 张) | 422 `PHOTO_REQUIRED` + `scene:"inb"` | | 重复验收 | 409 | | 验收数 ≠ 封存申报数 | 201,`diffQty` 非 0,自动生成异常单 + `ack.status:"pending"` | | 一致 | 201,无异常单 | ```json { "ok": true, "driverBackQty": 54, "inspectQty": 49, "diffQty": -5, "bookedQty": 49, "qtySource": "byType", "byType": { "SX": { "code":"SX", "name":"生鲜筐", "q": 42 }, "GS": { "code":"GS", "name":"果蔬筐", "q": 7 } }, "inspectorRole": "logistics", "inspector": "物流经理·吴工", "shift": "洗筐员到岗前(物流经理代验)", "exception": { "id": "EX908721", "level": "Ⅱ", "step": "⑤ 回场验收", "fresh": 42, "fruit": 7, "book": 54, "back": 54, "driver": 49, "owner": "物流经理·吴工", "deadlineAt": "2026-10-20T06:27:00.000Z" } } ``` #### V2.7(11-06 反馈九.1):⑤ 改为按筐型逐项验收 带 `byType` 时,两条铁律: 1. **合计一律服务端重算。** `inspectQty` 只当提示,落库的 `qty` / `bookedQty` 是 `Σ byType.q`。 否则改一个数字就能把差异抹平,KCP-5 这道闸门等于没装。 2. **启用的筐型一种都不能缺。** 缺了直接 422 并点名缺哪种(与 PC 端「还有 N 种筐型没点」同一口径)。 放过去只会变成「合计偏小 → 开异常单 → 没人处理」的假异常。 不带 `byType` 的老客户端退回**总数模式**(`qtySource: "total"`,`byType: null`),行为与 V2.6 完全一致。 > **入账口径**:`bookedQty = Σ byType.q`(分筐型模式)或 `inspectQty`(总数模式),不是 `driverBackQty`。差异一律以实物验收为准。 > **两班交接**:以「最后一车已验收」为断点。断点前的车 `inspectorRole=logistics`,断点后的车为 `washer`,同一车不得两次验收(唯一键 `uk_plan`)。 > **有差异就必须拍到差异筐**:说「少 2 个」但拿不出一张能看出破损的图,这个差异在月底对账时一定被翻案。所以 `diff ≠ 0` 时要求 2 张。 > **异常单五列**:`fresh` / `fruit` / `book`(③ 复核账面)/ `back`(封存申报)/ `driver`(验收数), > 对应异常管理表格的「生鲜筐 / 果蔬筐 / 出筐 / 回筐 / 验收数」。以前这五列一半是空的,比不显示更误导。 #### 3.5.1 回场封存(FR-05A · V2.9 / V3.0 取消强制拍照) `POST /api/seal` ```json { "bizDate": "2026-10-19", "vehicle": "8", "byType": { "SX": { "q": 42 }, "GS": { "q": 7 } } } ``` 司机把筐推到封存区后调用。**这不是验收**:只锁「几点交了多少」,验收数仍由洗筐员点数得出。 | 场景 | 返回 | |---|---| | 该车当日无排线单 | 422 `KCP-1` | | 未完成 ③ 出仓复核 | 422 `KCP-3` | | ④ 带回登记未完成 | 422 `KCP-4` | | **V3.0:不再要求现场影像** | 封存影像改为「可选补拍」,0 张也放行(点数拍照统一由洗筐员在 ⑤-B 完成) | | `byType` 出现负数 | 422 `KCP-2` | | `byType` 合计 ≠ 申报总数 | 422 `KCP-4`(两个数都是司机自己报的,必须自洽) | | 重复封存 | 409 `CONFLICT`(封存后数量与影像锁定,不可改不可删) | | 成功 | 201 | ```json { "ok": true, "date": "2026-10-19", "vehicle": "8", "seal": { "qty": 49, "broken": 1, "at": "2026-10-19T22:47:13.000Z", "by": "配送司机·王建国", "byUserId": "U1003", "photoCount": 0, "byType": { "SX": { "code": "SX", "name": "生鲜筐", "q": 42 }, "GS": { "code": "GS", "name": "果蔬筐", "q": 7 } }, "sig": { "by": "配送司机·王建国", "at": "2026-10-19T22:47:13.000Z" } } } ``` 口径说明: - `qty` / `broken` 一律由服务端按 ④ 的逐校登记**重算**,客户端不传数 —— 传了就能改。 - 角色闸门:仅 `driver`。物流经理 / 洗筐员调本接口 → 403(他们不该替司机交数)。 - `sig` 是电子签署(人 + 服务器时间)。移动端没有手写签名,签署 = 勾选确认 + 账号身份 + 落库时间。 - **`byType` 是选填的「按筐型申报」(V3.0 / 11-12 反馈七.2)**:洗筐员是「一堆一堆按筐型点」的, 申报数不分列,差异就只能定位到整车、定位不到筐型。选了就必须与申报总数自洽; 申报总数本身仍由 ④ 逐校登记推出,**不取客户端传值**。 - **V3.0 取消的是「司机拍照」,不是「交接确认」**:06:30 回场到 08:00 卫生员到岗这段, 要是连时间戳都没有,少的筐永远归不了属。交接单仍在,`sig.at` 仍是 KCP-5 的比较基准。 #### 3.5.2 验收差异确认(V2.9) `POST /api/inbound/ack` 客户现场是「洗筐员点数时司机早走了,靠事后电话沟通」,所以这一步**异步**,可以在家点。 ```json { "bizDate": "2026-10-19", "vehicle": "8", "accept": true, "channel": "电话", "note": "9:40 电话核对,5 个破损已单独放置" } ``` | 场景 | 返回 | |---|---| | 该车尚未验收 | 422 `KCP-5` | | 验收无差异 | 400 `NO_DIFF`(没有可确认的东西) | | 提异议但没写原因 | 400 `BAD_REQUEST` | | 已经确认过 | 409 `CONFLICT`(`ok` / `dispute` 都不许改) | | 认账 / 异议 | 200,返回 `ack` 与完整 `inbound` | ```json { "ok": true, "ack": { "status": "ok", "at": "2026-10-20T01:12:00.000Z", "by": "司机·王建国", "byUserId": "U1003", "channel": "电话", "note": "9:40 电话核对,5 个破损已单独放置" } } ``` 三条口径,别改: 1. **认账不改变入账** —— 本来就是按验收数入账,这一步补的是「司机知情」。 2. **异议也不卡日结** —— 异常单转「待复核」,台账先按验收数走,复核后以调整单修正。 因一台车卡住全天日结,现场第二天就会绕过系统。 3. **允许物流经理代记** —— 电话是谁打的就记谁;`by` 取登录账号,不取请求体。 > 为什么需要这一步:验收人改数原来**没有任何当场制衡**,只有事后追。 > 客户主动提了「司机核对签字」,正好把单向签字变成双向。 **两个入口,都要有**: | 入口 | 谁用 | 说明 | |---|---|---| | 移动端「封存」页待办 | 司机本人 | 看到申报数 / 验收数 / 差额 / 各筐型明细后点「认账 / 有异议」 | | PC ⑤ 回场验收列表「代录确认」 | 物流经理 | 电话核对后代司机记录;系统记代录人 + 渠道 + 时间,与本人操作区分开 | 只把入口放在移动端,等于把这一步挂在司机身上 —— 他不点,差异就永远挂着,而这恰恰是给验收人加的唯一制衡。 **联带的状态变更**:提异议时异常单 `status` 由「待处理」改为「**待复核**」,`exceptions` 的筛选档也从三档扩到四档(待处理 / 待复核 / 处理中 / 已闭环)。新增一档时必须同步改这三处,否则这类单子只在「全部」里看得见:`server.js` 的状态赋值、PC 异常页筛选数组、`schema.sql` 的 `status` 注释。 ### 3.6 影像留证(KCP-9 · V3.10 只留一道硬前置 + 零影像打标) **现行规则一句话**:只有 ④ 车级「本车卸货完成全景」缺图会阻断;②③ 与 ⑤-A 拍不拍由现场定,缺图只打标。 `photoNeed()` 的口径: | scene | 应拍张数 | 说明 | |---|---|---| | `reg` | 0 | 可选,`noShot` 打标 | | `ck` | **0(恒为 0)** | V3.10 取消,含原「② 没拍就补 1 张」 | | `ret` | **`opt.car ? 1 : 0`** | 车级必拍 1 张;校级(原来按 `left>0` 判)已取消 | | `inb` | 1 或 2 | 有验收差异 → 2 | | `hand` | 0 | 可选补拍 | | `rep` | 1 | 异常单必须留证 | #### 3.6.1 上报影像 `POST /api/photos` 客户端先把文件传到对象存储,拿到 key 后再报这里;本骨架只存元数据,一行一张。 ```json { "bizDate": "2026-10-19", "vehicle": "8", "scene": "ret", "ref": "S007", "by": "李师傅", "role": "driver", "left": 4, "photos": [ { "id": "IMG-20261019-0007", "idx": 1, "slot": "卸货点全景(带回与遗留同框)", "at": "07:12:33", "ts": 1760000000000, "src": "camera", "geo": { "lat": 28.19, "lng": 112.97, "addr": "长沙·望城区·某小学" }, "watermark": "2026-10-19 07:12:33 · ④送达 · 8号车 · 李师傅", "kb": 176, "thumb": "(可选,base64 会被服务端剥离)" } ] } ``` ```json { "ok": true, "saved": [ { "id": "IMG-20261019-0007", "skewMin": 1, … } ], "scene": "ret", "sceneName": "④ 送达与带回", "got": 1, "need": 2, "ready": false, "pending": 0, "clockSkew": 0, "message": "④ 送达与带回还差 1 张(1/2)" } ``` | 参数 | 必填 | 说明 | |---|---|---| | `scene` | ✔ | `reg` / `ck` / `ret` / `inb` / `rep`,无效返回 400 `BAD_SCENE` | | `ref` | | ④ 传学校 ID;其余不传,默认取车号 | | `photos[].src` | | `camera`(默认,现场拍)/ `album`(相机故障降级通道,须同时 `degraded:true`) | | `photos[].ts` | | 照片自报时间(毫秒)。不传则从 `at` 解析,都没有则取服务器当前时间 | | `photos[].data` | | **V2.1** JPEG base64(`data:image/jpeg;base64,...`)。带了就落盘,不带只存元数据 | | `left` / `diff` | | 供服务端回算 `need`(④ 有遗留的学校各加 1 张、⑤ 有差异 2 张、③ 看 ② 是否留证) | - **服务端不做张数拦截**,只记账并回 `got / need / ready`。拦截放在各单据提交口——否则校验点会散在多处,改一次规则要改五个接口。 - **`receivedAt` 与 `skewMin` 由服务端算**:`skewMin = round((now − ts) / 60000)`。`|skewMin| > 30` 说明手机时间可疑,**只标记不阻断**(可能是网络慢或时区问题,直接拒绝会误伤)。 - **像素落盘,不进 `data.json`(V2.1)**:客户端把 JPEG 以 `data:image/jpeg;base64,...` 放在 `photos[].data` 里一起报,服务端写到 `uploads/IMG-….jpg`,库里只留 `file` / `sizeKb` / `hasImage`。理由很实在:一张 base64 就能把状态文件撑到几百 KB,而 `GET /api/state` 是整包下发的,几分钟就能把现场的 4G 拖死。 - **体积上限 600KB/张**:超了不收文件但**元数据照样入库**——不能因为图片太大就把整条登记丢掉。请求体上限 6MB(`BODY_LIMIT`),留给 base64 展开的余量。 - **`thumb` 仍会被剥离**:缩略图只在前端本地用,不上传。 - **`uploads/` 必须进备份**:备份脚本 `basket-backup.sh` 已改为「data.json 快照 + uploads 增量镜像」。不备份影像等于只备份了照片目录,出事一张都恢复不出来。 - `IMG-YYYYMMDD-NNNN` 编号由服务端生成,客户端传的 `id` 仅作兼容。 #### 3.6.2 查询影像与达标情况 `GET /api/evidence?date=2026-10-19&vehicle=8&scene=ret` ```json { "date": "2026-10-19", "vehicle": "8", "scene": "ret", "count": 7, "stat": { "total": 9, "byScene": { "reg": 1, "ck": 0, "ret": 7, "inb": 1, "rep": 0 }, "clockSkew": 0, "pending": 0 }, "skewLimitMin": 30, "rules": { "reg": { "min": 2, "slots": ["…"] }, "…": {} }, "rows": [ { "id": "IMG-20261019-0007", "scene": "ret", "ref": "S007", "at": "2026-10-19T07:12:33+08:00", "ts": 1760000000000, "receivedAt": "2026-10-19T07:13:10+08:00", "skewMin": 1, "src": "camera", "sync": "uploaded" } ], "lines": [ { "vehicle": "8", "bizDate": "2026-10-19", "line": "东乡线", "checks": { "reg": { "got": 1, "need": 1, "state": "ok" }, "ck": { "got": 0, "need": 0, "state": "ok" }, "ret": { "got": 4, "need": 4, "state": "ok" }, "inb": { "got": 0, "need": 0, "state": "na" } }, "short": [], "pass": true } ] } ``` - `state` 三态:`ok` 达标 / `short` 凭证不足 / `na` 未到那一步(应拍数记 0,不参与考核)。 - **V3.0 张数(判据从「拍够几张」改成「一张能不能证明」)**: | 环节 | 应拍 | 说明 | |---|---|---| | ② 用筐登记 `reg` | 1 | 装筐区全景(能看出筐型与已装车筐垛) | | ③ 出仓复核 `ck` | **0** | ② 已留证则免拍;② 一张都没有才补 1 张车厢全景 | | ④ 送达与带回 `ret` | 1 + 有遗留校数 | 车级 1 张卸货完成全景(`ref=@car`)+ 仅有遗留的学校各 1 张 | | ⑤-A 回场交接 `hand` | **0**(可选补拍) | 点数拍照统一由洗筐员在 ⑤-B 完成 | | ⑤-B 回场验收 `inb` | `diff ≠ 0 ? 2 : 1` | 有差异须拍到差异筐实物 | 一站一车的张数从原来的约 40 张降到约 5 张。**减张数不等于撤证据**: ④ 的车级全景是「校门口唯一证据」,撤掉之后 KCP-4 与 KCP-5 都会变成摆设, 所以是「每车 1 张 + 有遗留校各 1 张」,不是「全撤」。 - ④ 的 `ref` 现在有两种:`@car`(车级全景)与学校 ID(该校遗留筐);`need` 由两者共同决定。 - **没有 DELETE 接口**,也不打算有。撤销唯一路径是作废整张单据走 `exception_order`,留痕可追。 #### 3.6.5 V3.10:零影像统计(放松闸门的对价) 影像要求降到「只剩 ④ 车级一张」之后,一辆车当天可以**完全零影像**而账面全绿 —— 事后想抽查都没有抓手。所以同批加了这套标记,**它是这次改动能被接受的前提,不是装饰**。 **口径(三端必须一致)**:只数作业三段 `reg + ck + ret`。 封存(`hand`)与验收(`inb`)**不算** —— 否则司机回场随便补一张就把「车在路上没留证」洗白了。 | 位置 | 字段 | 含义 | |---|---|---| | `evidStat(vehicle, bizDate)` | `onRoad` / `zero` | 作业三段张数合计 / 是否为零 | | `/api/out-check` 返回 | `evidence` | 含 `zero`,复核那一刻就能看到 | | `/api/return` 返回 | `evidence` / `zeroEvidence` | ④ 每次提交都回;前端要在 toast 里告诉司机 | | `/api/seal` 返回 | `evidence` / `zeroEvidence` | 同时写进 `task.seal.zeroEvidence` | | `/api/reports/daily`(看板聚合) | `zeroEvidLines` / `zeroEvidVehicles` | 零影像车数 + 车号列表 | **`seal.zeroEvidence` 为什么要单独存**:封存这一刻的事实不能被事后补拍改写。 台账上另有一个现算值,两者分开看 —— 「当时有没有」与「现在有没有」是两个问题。 > **考核口径提醒**:`zero` 只有在该车**已完成出仓复核**时才计入统计。 > 还没装车的线路本来就不该有影像,混进去数会让这个指标彻底失去意义。 #### 3.6.4 V3.9:`evidence` 是全局数组,`tasks[].evid` 由前端派生 服务端存影像只有一张平表 `ST.evidence`(按 `(vehicle, bizDate, scene, ref)` 归属), **从来没有把影像挂回 `tasks[].evid`** —— 线上 `/api/state` 里 `tasks` 的 `evid` 字段恒为空的。 PC 后台所有影像判定读的都是任务内嵌的 `t.evid`,于是「影像核查」整页在线上恒为 0/缺证, ②③④⑤ 四格全空。客户只先注意到了 ⑤-B 那一格(十. 反馈)。 **修法是前端一处派生**:`adaptState()` 在 `fixTaskDates()` 之后,把 `st.evidence` 按 `(vehicle, bizDate)` 聚合写进对应 `task.evid`,字段保持 `{scene, ref, id, at}`, 场景补上中文名(PC 列表直接显示,不用再查表)。 - **必须幂等**:`apiLoad()` 会反复调 `adaptState()`,重复聚合不能越挂越多(按 `id` 去重)。 - **顺序有讲究**:晚于 `fixTaskDates()`,否则 `date` / `bizDate` 没对齐,按 `(车, 作业日)` 挂不上。 - **不伪造**:没有 `evidence` 时不动 `task.evid`,空就是空。 - 规则与 `/api/evidence` 的 `evidStat` 保持一致,避免两边再分叉;服务端库结构未改。 #### 3.6.3 取影像文件(V2.1) `GET /api/evidence/photo?id=IMG-20261019-0007` 返回图片二进制(`image/jpeg` 或 `image/png`,`Cache-Control: private, max-age=86400`)。 - 库里只有 key,像素在 `uploads/` 下,所以**缩略图不能塞进 `/api/state`**,必须走这个接口。 - 鉴权走 Bearer 头;**`` 标签带不了头**,所以同时支持 `?token=` 查询参数(服务端本来就预留了这个通道)。内测开了 `PILOT_AUTH=1` 之后,不带 token 的图片请求一律 401,页面会全是碎图。 - 只存了元数据、没有文件的历史记录返回 `404 NO_FILE`,前端回退成占位块而不是碎图。 ### 3.7 留存抽查(KCP-10 兜底) `POST /api/audit` ```json { "schoolId": "S007", "realQty": 3, "bizDate": "2026-10-19", "auditor": "台账记账员·陈工", "photos": ["p1", "p2"] } ``` - 偏差率 `dev > 10%` 时自动生成 Ⅲ 级异常单。 - 由物流经理或台账记账员独立执行,**司机不参与**。 ### 3.8 异常闭环 `POST /api/exceptions/{id|orderNo}/close` ```json { "owner": "司机 王师傅", "resolution": "现场复核后确认差异 5 个,按单价赔付" } ``` ### 3.9 已下线接口 | 接口 | 状态 | |---|---| | `POST /api/out` | 410,改用 `/api/qty` + `/api/out-check` | | `POST /api/back` | 410,改用 `/api/return` | | `POST /api/delivery` | 410,送达数并入 `/api/route` 的 `delivered` | | `POST /api/sign` | 410,学校从不下场登记 | ### 3.10 基础信息库与表格导入(V1.9) **只有两份主数据要人录:客户、司机。** 车辆不单独建档——`driver.vehicle`(绑定车号)一填,后台「车辆一览」就出现这台车;`driver.line`(所属线路)一填,这台车跑哪条线也定了。所以接口层面: **V2.8:一个司机可以跑多条线路,但仍是同一辆车**(客户 11-10 确认)。因此: - `vehicle` 仍是单值 —— 一个司机只绑一辆车; - 线路变成 `lines[]`(`line` 保留为兼容字段 = `lines[0]`); - 导入模板里「所属线路」**一格填多条**,用 `/ 、 , ; |` 任一分隔,例如 `城区线/南乡线`; - 同一司机写成两行也可以(同名 + 同车号会自动认作同一人并合并线路),不再判「编码重复」整批不入; - 「车辆一览」的 `lines` 汇总该车**全部司机的全部线路**,不再只取主驾第一条。 | 资源 | 可读 | 可写 | 导入 | |---|---|---|---| | `customers` 客户 | ✅ | ✅ | ✅ 客户信息模板 | | `drivers` 司机 | ✅ | ✅ | ✅ 司机信息模板(线路可填多条) | | `vehicles` 车辆 | ✅(投影) | ❌ 400 `READ_ONLY` | ❌ 无模板 | | `routes` 排线 | ✅(走 `/api/tasks`) | ❌ | ✅ 物流排线模板 | 任何导入都不会覆盖留存数、账龄、抽查结果、排线进度。 #### 3.10.1 查询主数据 `GET /api/master` | `GET /api/master?kind=drivers` ```json { "ok": true, "customers": [ { "id": "S001", "fullName": "长沙市雨花区实验小学", "name": "实验小学", "type": "学校", "line": "城区线", "vehicle": "8", "addr": "…", "contact": "刘主任", "phone": "138…", "status": "启用", "held": 37, "age": 2 } ], "drivers": [ { "id": "D01", "name": "王建国", "alias": "王师傅", "phone": "139…", "license": "A2", "licenseExp": "2028-02-15", "vehicle": "1", "line": "城区线", "status": "启用", "joinDate": "2023-01-02" } ], "vehicles": [ { "vehicle": "1", "line": "城区线", "status": "启用", "driver": "王建国", "driverId": "D01", "driverCount": 1, "onCount": 1 } ], "stat": { "customers": 28, "drivers": 31, "vehicles": 31 }, "importLog": [ { "at": "2026-10-20 17:02", "kind": "drivers", "file": "司机信息.csv", "add": 0, "upd": 31, "err": 0, "by": "调度员·张工" } ] } ``` - `vehicles` 是**投影**:`vehicle` 来自 `driver.vehicle`,`line` 与 `driver` 取该车**排在最前的启用司机**(主驾),`driverCount` / `onCount` 是在册/在岗司机数。 - **车辆对象里没有 `plate` / `model` / `capacity` / `insuranceExp`** —— 这些属于车辆运营台账,本平台不维护(接了路单或保险系统再补)。 - 传 `kind` 时只返回该份 + `stat`,用于只刷新一个页面;`kind=vehicles` 额外带 `note` 说明只读。 - `kind` 不在 `customers / drivers / vehicles` 内 → 400 `BAD_KIND`。 #### 3.10.2 单条新增 / 修改(PATCH 语义) `POST /api/master` ```json { "kind": "drivers", "rec": { "id": "D08", "vehicle": "90" } } ``` ```json { "ok": true, "action": "upd", "kind": "drivers", "row": { "id": "D08", "name": "李志强", "vehicle": "90", "line": "东乡线", … }, "warnings": [] } ``` - **只覆盖 `rec` 里真正出现的字段**。上例只改车号,姓名、手机号、驾照、线路原样保留——不会被默认值冲掉。 - 派生字段(车号带出的线路)只在原本缺失时补上,不覆盖已有值。 - 新增(`customers` 按 `id`、`drivers` 按 `id`)返回 `action: "add"`;编码留空自动生成(`S001` / `D01`)。 - **`kind: "vehicles"` → 400 `READ_ONLY`**,message 会指回司机档案。`routes` 也不支持单条 upsert,请走 3.10.3。 - 校验规则与导入**完全一致**(同一套 `check`),手工填错和导入填错拦的理由一样。 - 失败:400 `BAD_RECORD`,返回 `errors: ["手机号格式不对", …]`。 #### 3.10.3 表格导入(三张模板) `POST /api/import` ```json { "kind": "drivers", "text": "司机编码\t姓名\t手机号\t绑定车号\nD90\t测试司机\t13900001111\t90", "commit": false, "file": "司机信息.csv", "by": "调度员·张工" } ``` **预览(`commit: false`,默认)** 返回逐行判定,**不落库**: ```json { "ok": true, "commit": false, "kind": "drivers", "stat": { "add": 1, "upd": 0, "err": 0, "warn": 0, "total": 1 }, "rows": [ { "no": 2, "act": "add", "rec": { … }, "errs": [], "warns": [] } ] } ``` **提交(`commit: true`)**,成功 201: ```json { "ok": true, "commit": true, "kind": "drivers", "stat": { "add": 1, "upd": 0, "err": 0, "warn": 0, "total": 1 }, "addCount": 1, "updCount": 0, "message": "导入完成:新增 1 条,更新 0 条" } ``` 规则: | 项 | 说明 | |---|---| | `kind` | `customers` / `drivers` / `routes`(**没有 `vehicles`**) | | 分隔符 | 自动识别 Tab / 逗号 / 分号 / 竖线;首字符 `\uFEFF` 自动剥离 | | 表头 | 按**列名**对齐,**允许乱序、允许只贴部分列**;首行不像表头时按模板列序解析 | | 示例行 | 首列以「示例」开头的行自动跳过,不计入 `stat` | | 编码 | 客户 / 司机编码留空时自动生成(`S001` / `D01`…) | | 有错行 | **409 `IMPORT_HAS_ERRORS`,整批不入**;`rows[].errs` 给出具体列与原因 | | 司机绑车 | `绑定车号` 填一个新车号即可建档新车;非纯数字(车牌)只 warn | | 排线聚合 | `kind: "routes"` 时按车号聚合,一校一行 → 一张排线单;`stepOf(t) > 1` 的车**拒绝覆盖** | | 留痕 | 每次 `commit: true` 追加一条 `importLog` / `import_batch` | **导入绝不触碰的字段**(业务数据):`held`(留存数)、`age`(账龄)、`auditQty` / `auditDev` / `auditDate`(抽查)、`school_daily` 全表、`out_check` / `inbound` / `evidence_photo` 全表。 **上线顺序固定**:客户 → 司机 → 排线。客户先导(所属线路要落在已存在的线路编组上),司机后导(车与线路随它一起产生),排线永远最后。 ## 3.11 登录、会话与整态同步(V2.0-pilot) > **默认关闭,`PILOT_AUTH=1` 或启动参数 `--auth` 才启用。** > 不开就是演示模式(现有 165 条断言与线上演示站都跑这个形态);开了就是内测形态,同一份 `server.js`。 ### 开关与语义 ```bash node server.js # 演示:接口全开,任何人都能读写 PILOT_AUTH=1 node server.js # 内测:除 /api/health、/api/login、/api/whoami 外都要 Bearer token ``` `GET /api/health` 返回 `{ ok:true, auth:true|false }`,前端据此判断自己连的是哪种形态。 ### 3.11.1 登录 | 方法 | 路径 | 说明 | |---|---|---| | POST | `/api/login` | `{username, password}` → `{token, expiresIn, mustChange, user}` | | POST | `/api/logout` | 注销当前 token(服务端删除会话) | | GET | `/api/whoami` | 当前身份;**免登录**,未登录返回 `user: null`,供 H5 启动探活 | | POST | `/api/password` | `{oldPassword, newPassword}` 改自己的密码,新密码 ≥ 6 位 | | GET | `/api/users` | 账号列表(`rows`,**不含 hash/salt**)+ 可分配角色 `roles` | | POST | `/api/users` | 账号管理,`action` = `create` / `passwd` / `status` / `dept`,见 3.11.5 | ```bash curl -X POST http://127.0.0.1:8090/api/login \ -H 'Content-Type: application/json' \ -d '{"username":"diaodu","password":"zzk2026"}' # → { "ok":true, "token":"…32位…", "expiresIn":43200000, "mustChange":true, # "user":{"id":"U02","username":"diaodu","name":"调度·李工","role":"dispatcher", # "roleName":"调度员","dept":""} } curl http://127.0.0.1:8090/api/master -H "Authorization: Bearer " ``` 约定: - 密码哈希 `scrypt(password, salt, 32)`(Node 自带 crypto,不引 bcrypt),比较用 `timingSafeEqual`; - 会话存内存,TTL 12 小时,**服务重启即全部失效**(内测可接受,换来「不需要会话表」); - 同一账号 5 分钟内错 5 次 → `429 TOO_MANY_TRIES`,锁 5 分钟; - 账号不存在与密码错**返回同一文案**,不泄露账号是否存在; - 除 `Authorization` 头外,允许 `?token=xxx`(给 `` / `` 这类带不了头的场景); - 初始账号 7 个,用 `node user.js list|add|dept|passwd|enable|disable` 维护。 ⚠️ **改完必须 `systemctl restart basket`**:`user.js` 直接改 `data.json`, 而运行中的 `server.js` 手里有一份内存状态,不重启会被覆盖回去。 - **`dept` 班组(V2.6)**:生产主管分生鲜/果蔬两组时,给账号设班组即可 —— `node user.js dept zhuguan 生鲜`。登录后小程序 ② **只显示本组筐型**、只提交本组筐型。 留空 = 不限(管理员、总主管用,看全部筐型)。账号上的 `dept` 不参与授权判定, 只决定「看到哪些筐型」,角色闸门仍按 `role` 走。 ### 3.11.2 角色闸门(只拦高风险写操作) | 接口 | 允许的角色 | |---|---| | `POST /api/route`(① 排线) | `dispatcher` | | `POST /api/qty`(② 用筐登记) | `supervisor` | | `POST /api/out-check`(③ 出仓复核) | `driver` | | `POST /api/return` / `/api/back` / `/api/sign`(④) | `driver` | | `POST /api/inbound`(⑤ 回场验收) | `logistics` / `washer` | | `POST /api/adjust`(遗留差异调整单) | `keeper` | | `POST /api/types`(筐具档案) | `keeper` | | `POST /api/master`、`POST /api/import`(主数据) | `keeper` / `dispatcher` | | `POST /api/audit`、`POST /api/exceptions/:id/close` | `keeper` / `logistics` | | `POST /api/reset` | **只有 `admin`** | `admin` 永远放行。不在表内的接口(查询类、`/api/photos`)任何登录用户都可调用。越权返回 `403 FORBIDDEN`,message 里直接写明「限谁做」。 ### 3.11.3 整态同步(内测期的务实做法) | 方法 | 路径 | 说明 | |---|---|---| | GET | `/api/state` | `{rev, state}` 全量状态(账号只给 id/用户名/角色,**不含 hash/salt**) | | POST | `/api/state` | `{rev, state}` 全量覆盖,`rev` 不匹配返回 `409 REV_CONFLICT` | ```bash # 拉一次,记下 rev curl -s http://127.0.0.1:8090/api/state -H "Authorization: Bearer $TK" | head -c 200 # 覆盖回去(rev 必须是刚拿到的那个) curl -X POST http://127.0.0.1:8090/api/state -H "Authorization: Bearer $TK" \ -H 'Content-Type: application/json' -d '{"rev":7,"state":{…}}' # 拿旧 rev 再写 → 409 {"code":"REV_CONFLICT","serverRev":8,"yourRev":7,…} ``` **为什么做这个**:PC 后台有 20 个页面、上百个读点,逐个改成异步接口至少一周且容易漏。整态同步让「多人共用一本账」先跑通,把时间花在现场反馈上。 两条底线: 1. **`rev` 对不上就 409,绝不静默覆盖。** 每次落盘 `rev + 1`(只加审计的落盘不递增,避免审计让别人手上的版本失效)。 2. **账号与审计只由服务端维护。** 客户端传什么 `users` / `opLog` 都不收,服务端用原值覆盖回去——前端清不掉审计,也加不了假管理员。 `rev` 每次写都变,所以两个人改**不同**车辆也会撞。内测期用「改完点刷新」规避;正式版改成按接口增量提交(见第 4 节第 3 条)。 ### 3.11.4 操作审计 | 方法 | 路径 | 说明 | |---|---|---| | GET | `/api/oplog?n=50` | 最近 N 条(≤500)。鉴权开启时只有 `admin` / `keeper` 能看 | 所有**非 GET** 的 `/api` 请求自动记一条:`{at, method, path, status, userId, userName, role, ip, detail}`,保留最近 2000 条。 ```json { "at":"2026-10-20T10:19:03.512Z", "method":"POST", "path":"/api/route", "status":201, "userId":"U02", "userName":"调度·李工", "role":"dispatcher", "ip":"127.0.0.1", "detail":"" } ``` 关键点:**记的是服务端看到的事实**(含被 403 拒掉的越权尝试),不是客户端自报。内部核对与追责只认这张表。 ### 3.11.5 账号管理(V2.7 · 后台建号 / 重置密码 / 启停) `GET /api/users` → `{ rows: [...], roles: { "admin":"管理员", "dispatcher":"调度员", … } }`,`rows` 里**只有** `id / username / name / role / roleName / status / dept / mustChange / staffId`,**永远不含 `salt` / `hash`**。 `roles` 是「角色码 → 岗位名」的映射(不是数组),建号时 `role` 传角色码。 `POST /api/users`,四种 `action`: ```json { "action": "create", "username": "zhougang", "name": "周刚", "role": "driver", "dept": "", "pass": "zzk2026", "staffId": "P03" } { "action": "passwd", "username": "zhougang", "pass": "newpass99" } { "action": "status", "username": "zhougang", "status": "停用" } { "action": "dept", "username": "zhougang", "dept": "生鲜" } ``` | action | 关键校验 | 说明 | |---|---|---| | `create` | 账号 3–16 位、角色必须在 `roles` 内、密码 ≥ 6 位、账号不重复 | 建号后 `mustChange: true`,首次登录强制改密 | | `passwd` | 账号必须存在、新密码 ≥ 6 位 | **服务端重新生成 salt + hash**,并重置 `mustChange: true` | | `status` | 只能是 `启用` / `停用` | 停用只拦登录,历史审计里的姓名照样保留 | | `dept` | ≤ 10 个字 | 生产主管分组用(`dept` 只决定看到哪些筐型,不参与授权) | **`staffId` 是 V2.8 加的**:账号挂到统一的人员 ID 上(人员与角色页面的那一行)。 以前应用层按**姓名**把账号和人员对上,重名就串号 —— 改了一个人的密码,另一个同名的人反而登不进来; 停用也要在「人员」和「司机档案」两处各点一次,漏一处他还是能登录。 传空或不传 = 暂不挂人(PC 人员页面显示「未建号」)。 **`staff` 表由服务端推导,不是前端灌的演示数据。** `normalize()` 启动时按「真实账号 + 司机档案」重建人员表(仅在表为空、或识别为演示表时重建): ① 每个账号一行,姓名去掉「岗位·」前缀,角色由系统角色码反查中文岗位名; ② 司机档案里有、但没有账号的补一行(现场不登录的人也得在岗)。 ID 规则 `D01 → P01` / `U_`,与 PC 端 `defaultStaff()` / `relinkRoster()` 必须**逐字一致**。 两条容易写错的判定: - **演示表识别**:早期前端自动灌的演示岗位 id 形如 `U01…U06`。统计「姓名在演示名单里 **且** id 匹配 `^U0\d$`」 的行数,≥2 行即整表重建。**不能拿「整表有没有 `account`」当判据** —— 旧逻辑的姓名匹配早就给 「刘工」「陈姐」写过 `account`,那样条件永远不成立,线上就一直是大面积未绑定。 - **绑定校验**:`u.staffId` 指向的行必须**确实是本人**(account 对得上,或姓名对得上),否则清掉脏值重新解析。 只判「id 在不在表里」会把账号挂到别人头上 —— 线上就出现过「王建国」被挂到司机「雷屿」的行上, 人员页显示两人是同一个,比未绑定更容易误导。 三条硬规矩: 1. **密码永远在服务端算。** 前端只传明文 `pass`,`salt` / `hash` 前端既不传也不收。 库里存的是 `scrypt(密码, 盐)` 单向哈希 —— **拿不回明文,任何「显示原密码」都是伪需求**。 后台能做的只有「重置」,所以 PC 人员页面显示的是**密码状态**(初始 / 已自改 / 未建号)+ 重置按钮。 2. **只有 `admin` 能调这个接口。** 鉴权关闭(演示模式)时不拦,与其它写接口一致。 3. 改完账号数据即时落盘,但**改 `data.json` 的 CLI 方式(`user.js`)仍需重启服务**,原因见 3.11.1。 ### 3.11.5.1 会话落盘(V3.0 / 11-12 反馈七.1) `sessions` 原来只存内存:服务一重启(发版 / OOM / 半夜维护)所有人立刻掉线。 现场看到的却是「刚拍完照就退出登录了」—— 手机拍照返回会重载页面, 两个现象叠在一起,很容易被当成「上传影像把人踢下线」。 - 会话写入 `sessions.json`(**0600**,只存 `token / uid / name / role / at / last`,**不含密码与盐**); - 登录、注销立刻落盘;心跳更新 `last` 时 **1 秒合批**写一次,避免把磁盘写爆; - 启动时回读并**丢弃超过 12 小时**的记录; - 文件名可用环境变量 `SESSION_FILE` 覆盖(多系统同机部署、测试隔离都要用); - 备份脚本要把它一起带上:**掉了 `sessions.json` 等于把所有人踢下线**。 ### 3.11.6 与生产化的差距(别把它当终态) | 项 | 内测现状 | 生产要求 | |---|---|---| | 存储 | `data.json` 单文件 + 内存态 | MySQL + 事务 | | 同步 | 整态覆盖 + `rev` 乐观锁 | 按接口增量提交 | | 会话 | 内存 Map,重启失效 | Redis / JWT 无状态 | | 审计 | 最近 2000 条,随 `data.json` | `audit_log` 表,只授 INSERT/SELECT | | 密码 | scrypt(够用) | 同左 + 复杂度策略 + 定期强制改 | ### 3.12 筐具库存:期初建账 / 入库 / 报损(V3.8 / 11-16) 四个接口,解决同一件事:**让损耗率这个数自洽**。口径推导见 2.4 节,这里只讲怎么调。 > **为什么报损要分「申请 / 审批」两个接口**:报损会减少「待倒查」。 > 现场若能自己生效,盘点一不平就能写一张「破损 N 个」把差额解释掉 —— KCP-7 立刻失效。 > 与调整单(3.4.1.1)同一个道理,唯一差别是**报损允许 PC 代录**(洗筐员戴着手套点不了手机, > 打电话报数给文员代录是真实工作方式),代录记 `byProxy: true`。 #### 3.12.1 期初建账 `POST /api/stock-book`(角色:keeper) ```json { "date": "2026-11-16", "period": "2026-11", "note": "11-16 日盘四区实盘", "items": { "SX": 3000, "GS": 727 } } ``` | 校验 | 返回 | |---|---| | `date` 非 `YYYY-MM-DD` | 400 | | 全部筐型数量为 0 / 无启用筐型 | 400(空账没有意义) | | 同 `period` 已有建账单 | 201 但**旧账进 `stockBookLog` 归档**,不报错 | ```json { "ok": true, "stockBook": { "period": "2026-11", "date": "2026-11-16", "items": { "SX": 3000, "GS": 727 }, "total": 3727, "by": "记账员·孙会计", "at": "…", "locked": true } } ``` - 建账即**锁定**(`locked: true`)。要改只能再调一次,旧账整行进 `stockBookLog` 留痕 —— **绝不覆盖**,否则「期初被谁在什么时候动过」永远查不到。 - `total` 由服务端按 `items` 重算(`Σqty`),不收客户端合计;只认启用中的筐型,数量取整、非负。 #### 3.12.2 入库登记 `POST /api/stock-in`(角色:keeper) ```json { "date": "2026-11-16", "type": "采购", "batch": "PO-20261115", "price": 45.5, "note": "补 500 个生鲜筐", "items": { "SX": 500 } } ``` | 校验 | 返回 | |---|---| | `date` 非法 | 400 | | `type` 不在 `采购 / 调入 / 退回` | 400 | | 合计为 0 | 400 | ```json { "ok": true, "record": { "id": "IN261116-0001", "date": "2026-11-16", "type": "采购", "items": { "SX": 500 }, "total": 500, "batch": "PO-20261115", "price": 45.5, "by": "记账员·孙会计" }, "inSum": 500 } ``` - 入库**抬高分母、不动分子**。所以补货之后 `loss` 一分不变,`lossRate` 被摊薄 —— 这是对的。 - `batch` / `price` 选填,但建议填:哪一批新筐上手就破是采购质量问题,得能追到批次。 #### 3.12.3 报损申请 `POST /api/stock-loss`(角色:washer / keeper) ```json { "date": "2026-11-16", "reasonType": "破损", "reason": "西乡线回场的 SX 筐压裂 6 个,已在洗筐区单独堆放", "items": { "SX": 6 }, "byProxy": false, "photos": ["ph_xxx"] } ``` | 校验 | 返回 | |---|---| | `date` 非法 | 400 | | `reasonType` 不在 `破损 / 丢失 / 污染 / 其他` | 400 | | `reason` 为空 | 400(「只写破损等于没写」) | | 合计为 0 | 400 | ```json { "ok": true, "record": { "id": "LS261116-0001", "status": "待审", "total": 6, "reasonType": "破损", "reason": "…", "by": "洗筐员·李姐" } } ``` - 返回 `201` 但**账上还没动**。`待审` 期间不进 `lossExplained`,`lossOpen` 不变。 - 移动端硬前置 1 张现场照片;PC 代录可不带(电话报数的场景本来就拍不了)。 #### 3.12.4 报损审批 `POST /api/stock-loss/review`(角色:keeper / logistics) ```json { "id": "LS261116-0001", "pass": true, "note": "已核对实物,与洗筐区堆放一致" } ``` - `pass: true` → 生成一条 `stock_loss` 生效单,`lossSum` 随之增加,`lossOpen` 相应减少; - `pass: false` → 只改状态为「驳回」,**账上什么都不动**,`note` 必填; - 已处理过的申请再审 → 409(不重复入账)。 ```json { "ok": true, "record": { "id": "LS261116-0001", "status": "通过", "reviewedBy": "记账员·孙会计", "lossId": "L2611160000123" }, "loss": { "id": "L2611160000123", "reqId": "LS261116-0001", "total": 6 }, "lossSum": 6 } ``` #### 3.12.5 一并修复的两处假数 | 位置 | 旧 | 新 | |---|---|---| | 筐具档案页「本月报损」 | 模板里写死 `12` | 按 `stock_loss` 当月汇总,金额按 `basketPrice` 折算 | | 设置页「期初实盘」 | 可直接编辑 | **只读**,指路到「筐具库存 → 期初建账」 | 改期初会把历史每一天的损耗率一起改掉,等于账本可以事后重写 —— 所以入口必须收在带留痕的建账单上。 ### 3.13 系统重置(V3.12 · 正式启用前清空测试数据) **这是全系统唯一一个删数据的接口**,所以约束比别处多。两个端点,都只给 `admin`: | 方法 | 路径 | 说明 | |---|---|---| | POST | `/api/reset/preview` | 只读盘点:将清多少条、保留多少条、磁盘上有几张影像 | | POST | `/api/reset` | 执行重置,需要确认口令 | 非管理员一律 **403**(`ROLE_RULES` 里 `roles: []`)。**注意权限先于口令**: 记账员就算知道口令也进不来,不会出现「谁都能清库,只要猜到四个字」。 #### 3.13.1 preview ```jsonc // POST /api/reset/preview { "scope": "all" } // scope 可省略,默认 all { "ok": true, "phrase": "清空确认", "clear": [ { "key": "tasks", "name": "排线与作业单", "n": 81 }, ... ], // 17 项 "clearTotal": 186, "keep": { "users": 7, "schools": 28, "lines": 6, "types": 2, "drivers": 31, "staff": 37 }, "uploads": 29, // uploads/ 下待移走的影像文件数 "openTasks": 3, // 未验收的作业单 —— 这些进度会一起消失,确认页要标红 "baseStock": 3727, "stockBook": { "date": "2026-08-28", "total": 3727 } } ``` #### 3.13.2 执行 ```jsonc // POST /api/reset { "confirm": "清空确认", "scope": "all" } // 口令不对 → 400 CONFIRM_REQUIRED(不会清任何数据) { "ok": true, "scope": "all", "rev": 65, "uploadsMoved": 29, "backup": "/opt/basket/data.json.bak-reset-20261116-231500", "reset": { "at": "...", "by": "系统管理员", "uid": "U01", "ip": "1.2.3.4", "removed": { "tasks": 81, "evidence": 29, ... }, "baseStockBefore": 3727 }, "message": "已清空 186 条业务流水与 29 张影像;账号、学校、线路、筐型全部保留。备份:..." } ``` #### 3.13.3 三段不可省的保险 1. **先备份,备份失败就中止**。返回 `500 BACKUP_FAILED`,一个字节都不清。 顺序是「先 `saveState` 落盘 → 再 copy」——内存比磁盘新时,备份滞后的那份等于白备。 2. **口令在服务端校验**。前端那个输入框只是防手滑,真正拦人的是这里。 3. **影像文件移动而不是删除**:`uploads/*` → `uploads/_reset-<时间戳>/`。 流水能重录,照片删了就真没了。移动失败不影响数据清理,返回 `moveError` 说明原因。 #### 3.13.4 清什么、留什么 | 留(清掉系统就废了) | 清 | |---|---| | `users` 账号 | `tasks` 排线作业单 | | `schools` 学校/客户 | `evidence` 影像记录 | | `lines` 线路车辆 | `adjust` / `adjustReq` 调整单与申请 | | `types` 筐型字典 | `workshop` 车间盘点 | | `drivers` 司机档案 | `stockIn` / `stockLoss` / `stockLossReq` / `stockBookLog` | | `staff` 人员 | `exceptions` 异常单 | | | `auditLog` / `opLog` / `importLog` 各类留痕 | | | `summary9` / `summary10` / `lines10` / `lineTotals` 历史月结 | | | `stockBook`(置 `null`)+ `baseStock` 归零 | `stockBook` 必须是 `null` 不能是 `{}` —— `{}` 会被前端判成「有建账单但 total=0」,损耗率分母变 0,整页指标全塌。 **期初库存归零是刻意的**:演示基数 3727 一旦带进正式账,第一天算出的损耗率就是错的。 #### 3.13.5 `scope` 两档 | 值 | 行为 | 谁用 | |---|---|---| | `all`(默认) | 连历史月结、车间盘点、期初一起清 | PC 后台危险区按钮 | | `biz` | 只清单据与留痕,保留 `workshop` / `summary9` / `summary10` / `lines10` / `lineTotals` / 期初 | 回归测试清场 | 分两档的原因很实际:测试各节之间要「从零走一遍」,但同时又读「9 月损耗 117」这类基线, 全清档会把基线一起抹掉,断言就变成在空数据上比对。 #### 3.13.6 重置留痕写在哪 写 `ST.resetLog`,**不写 `opLog`** —— `opLog` 本身就在被清的那批里,写进去等于自己抹掉自己。 `resetLog` 只留最近 20 次,每条含操作人、IP、逐项删除条数、备份文件名。 同时 `rev` 会 +1:客户端手里那份旧状态一旦推回来,会被 409 拦住。 ## 4. 生产化待补清单 1. **鉴权与权限** - 骨架已内置内测版(`PILOT_AUTH=1`):scrypt 密码、Bearer 会话、角色闸门、操作审计,见 3.11; - 生产化还差:JWT / Redis 会话(当前会话存内存,重启失效)、数据行级权限(司机只能碰自己车号)、账号管理界面(当前用 `user.js`)。角色:`dispatcher / supervisor / driver / logistics / washer / keeper / admin`。 2. **参数校验与事务** - 引入 `zod` / `joi`;「排线 + 明细」与「验收 + 异常单」必须同事务。 3. **并发与幂等** - 司机端提交带 `requestId`;`uk_plan` / `uk_plan_school` 唯一键兜底重复提交。 - 排线改单走 `version` 乐观锁。 4. **文件与图片(V1.8 重点)** - 影像走对象存储(OSS / COS / MinIO),库里只存 `object_key` / `thumb_key`,**禁止存 base64**; - 上传走「客户端直传 + 服务端签名」:客户端拿到临时凭证直传对象存储,成功后把 key 报给 `POST /api/photos`; - **`evidence_photo` 表只授 `INSERT` / `SELECT`,不授 `UPDATE` / `DELETE`**。撤销唯一路径是作废整张单据走 `exception_order`,留痕可追; - 生命周期:热存 3 个月、归档至 12 个月;缩略图单独保存(列表页不拉原图); - 客户端侧:断网写本地待传队列(`sync:'pending'`),联网补传后置为 `uploaded`;水印在**拍照时烧进像素**,不是列表页叠 div。 5. **主数据维护权限(V1.9)** - `/api/master` 与 `/api/import` 只开放给 `dispatcher` / `admin`。**司机、生产主管、洗筐员一律不可调用**——主数据错一次,当天全线单据跟着错; - **车辆没有写接口**(`kind: "vehicles"` 返回 400 `READ_ONLY`),写权限只到 `school` / `driver` 两张表; - 排线导入(`kind: "routes"`)只给 `dispatcher`,且必须校验「该车当日 `stepOf > 1` 时拒绝覆盖」; - `import_batch` 表**只授 `INSERT` / `SELECT`**,与 `evidence_photo` 同理:留痕可查不可改; - 每次导入落 `file_hash`,同一文件重复提交给出提示,避免「同一个表导了三遍」。 6. **定时任务** - **作业日当日 18:00** 检查日结(KCP-8,下一轮分拣 19:00 开班);每日扫描「有排线无复核」「有带回无验收」的线路并催办。 - 每周生成抽查任务(KCP-10)。 7. **可观测性** - 结构化日志记录每次 KCP 拦截(code + vehicle + gap),用于分析流程卡点。 - `/api/health` 接入监控;Ⅲ 级异常超期告警到负责人。 --- ## 5. 快速自测 ```bash # 启动(演示模式) cd 交付物/开发包 && node server.js 8090 # 一键跑完 266 项接口断言 # (覆盖 KCP-0~5、KCP-9 影像硬前置、筐型字典、作业日归属、主数据与导入、 # V2.7 分筐型验收 / ④ 差异留痕 / 服务端重算合计 / 老客户端兼容) node ../../_src/test_api.js http://127.0.0.1:8090 # 内测形态:自己拉起一个鉴权服务,跑 69 项鉴权断言(脚本内部起停,不污染 data.json) node ../../_src/test_auth.js 8112 # PC 后台内测模式(登录门 / 拉全量状态 / 回推 / 版本冲突),32 项 NODE_PATH= node ../../_src/test_pc_api.js 8116 # 看当前作业日与时段 curl -s http://127.0.0.1:8090/api/shift # 主数据:三份档案 + 导入留痕 curl -s http://127.0.0.1:8090/api/master | head -c 600 curl -s "http://127.0.0.1:8090/api/master?kind=vehicles" | head -c 300 # 只读投影 # 导入预览(不落库):故意把手机号写短,应返回 stat.e = 1 curl -s -X POST http://127.0.0.1:8090/api/import \ -H "Content-Type: application/json" \ -d '{"kind":"drivers","text":"司机编码\t姓名\t手机号\nD90\t测试司机\t139","commit":false}' # 导入提交(201),再看列表里多了一条 curl -s -X POST http://127.0.0.1:8090/api/import \ -H "Content-Type: application/json" \ -d '{"kind":"drivers","text":"司机编码\t姓名\t手机号\t绑定车号\nD91\t测试司机二\t13900001112\t5","commit":true}' # 单条 upsert 的 PATCH 语义:只改车号,姓名/手机/线路不动 curl -s -X POST http://127.0.0.1:8090/api/master \ -H "Content-Type: application/json" \ -d '{"kind":"drivers","rec":{"id":"D08","vehicle":"90"}}' # 车辆只读:写接口直接 400 READ_ONLY curl -s -X POST http://127.0.0.1:8090/api/master \ -H "Content-Type: application/json" \ -d '{"kind":"vehicles","rec":{"vehicle":"8","status":"停用"}}' # 手工验一条完整流程 curl -s -X POST http://127.0.0.1:8090/api/reset curl -s -X POST http://127.0.0.1:8090/api/route \ -H "Content-Type: application/json" \ -d '{"vehicle":"8","schools":[{"id":"S007","seq":1}],"delivered":{"S007":10}}' # ② 登记(影像可选:noShot=true 时台账打「未附影像」标;readyForOut 只看筐型是否登齐) curl -s -X POST http://127.0.0.1:8090/api/photos \ -H "Content-Type: application/json" \ -d '{"vehicle":"8","scene":"reg","photos":[{"slot":"装筐区全景"},{"slot":"已装车筐垛"}]}' curl -s -X POST http://127.0.0.1:8090/api/qty \ -H "Content-Type: application/json" \ -d '{"vehicle":"8","biz":"SX","qty":14}' # 缺果蔬筐 → 出仓应被 KCP-2 拦截 curl -s -X POST http://127.0.0.1:8090/api/out-check \ -H "Content-Type: application/json" -d '{"vehicle":"8","reviewQty":14}' # 看影像达标情况 curl -s "http://127.0.0.1:8090/api/evidence?vehicle=8" ``` --- ## 6. 静态页面 | 路径 | 说明 | |---|---| | `GET /` 或 `/平台-PC管理后台.html` | PC 管理后台(**基础信息库** + 五步作业台 + 影像核查) | | `GET /平台-小程序端.html` | 小程序端原型(现场四岗共用:②③④⑤) | | `GET /SOP-周转筐管理标准作业程序.html` | SOP 可打印手册 |