# 周转筐管理平台 · 数据库设计说明 > 版本 **V3.0** | 配套文件:`schema.sql`(可直接执行建库建表) > 作业模型:**① 排线 → ② 用筐登记 → ③ 出仓复核 → ④ 带回与遗留 → ⑤ 回场验收** > 设计原则:**一张表 = 一张纸质表单 = 一个岗位的一次动作**,一线不用重新学记账口径。 > V1.8 新增:`evidence_photo`(影像台账,只增不删)+ 视图 `v_kcp9_evidence`(影像达标动态分母),KCP-9 由「标记」改为「阻断」。 > V1.9 新增:`driver`(司机档案)+ `import_batch`(导入留痕)+ 视图 `v_vehicle`(车辆一览);`school` 扩充主数据字段。 > V2.1 变更:`evidence_photo.has_image`(是否真存像素);`out_check` 支撑**多司机分认领**(`out_check_part` 明细,按人或按校认领,明细合计须等于账面);`basket_qty` 允许 `qty=0`(**空 = 未登记,0 = 登记为 0**,`qty IS NULL` 才算缺登记);新增 `line`(线路可维护)与 `sys_user.vehicle`(司机绑车)。 > V2.7 变更:`plan_school_removed`(排线减校留痕)、`plan_backfill`(历史补录留痕)、`exception_order_type`(异常单按筐型明细)、`inbound_check_type`(⑤ 按筐型验收,**缺行 = 未登记 ≠ 0**)。 > V2.9 变更:⑤ 拆两段 —— `seal_check`(FR-05A 司机回场封存);`inbound_check` 加 `pre_qty` / `pre_at` / `pre_by_id` 快照。详见 5.9。 > **V3.0 变更**:`ck_seal_photo` 由 `>= 2` 放开为 `>= 0`;新增 `seal_check_type`(封存按筐型申报)、`adjust_request`(调整单申请,不参与闭环计算)。详见 5.10。 > **V3.10 变更(11-16 客户三. / 五.1)**:`v_kcp9_evidence` 的 `ck_need` 恒为 0、`ret_need` 恒为 1(取消逐校);新增 `zero_evid` 列(作业三段全无影像)。 > **本次不改表结构** —— 放松的是「张数要求」,不是「留多少证据」;`evidence_photo` 一行一张、只增不删的设计仍然成立,取消强制之后仍然照收照片。唯一的新增数据是 `seal_check.zero_evidence`(封存时刻是否零影像,作为不可变快照)。详见 4.2 ③-b。 > **V3.12 变更(11-16)**:新增 `reset_log`(系统重置留痕,**清库时自己不能被清掉**)。重置语义是 `TRUNCATE` 不是 `DROP` —— 表结构、约束、视图一律不动,只清业务行。详见 5.12。 > **只有 `driver` / `school` 要人录,`vehicle` 行由司机的「绑定车号」自动建立**;导入只写主数据,且只能写这两张。 ## 1. 设计出发点 现行台账(附件《10月份周转筐出回登记台账汇总.xlsx》)有四个结构性缺口,数据库设计就是为了补上它们: | 现状缺口 | 后果 | 设计对策 | |---|---|---| | 排线靠口头/微信群 | 当天临时变动多,事后查不到依据 | `route_plan` + `route_plan_school`,学校清单锁定、改单留痕(KCP-1) | | 只有「合计」,没有学校维度 | 留存算得出总数,查不到是哪所学校压着 | `school_daily` 逐校一行的带回/遗留(KCP-4) | | 只有一个「回收数」,没有第二人复核 | 司机报多少就是多少,12 条异常全挂起 | `out_check` 司机复核 + `inbound_check` 物流经理验收,两次双人 | | 异常只记不闭环 | 无责任人、无时限、无结论 | `exception_order` 强制 `owner` + `deadline` + `status` | | 数字和现场对不上,事后无从查证 | 争议时只能靠嘴说 | `evidence_photo` 一行一张影像 + `v_kcp9_evidence` 校核张数(KCP-9) | ## 2. 表清单(44 张) > **主数据只有 2 张要人录**:`driver`(司机)、`school`(客户)。`vehicle` 行由司机的「绑定车号」自动建立, > **导入写不到它**;其余 28 张是业务表与配置表,导入也一律不碰。这条边界是 V1.9.1 的核心约束,见 4.3 节。 > > **V3.0 加 2 张**:`seal_check_type`(封存按筐型申报)、`adjust_request`(调整单申请,待审批)。见 5.10 节。 > > **V3.8 加 9 张**:`stock_book` / `stock_book_type` / `stock_book_log`(期初建账)、 > `stock_in` / `stock_in_type`(入库登记)、 > `stock_loss_request` / `stock_loss_request_type` / `stock_loss` / `stock_loss_type`(报损申请与生效)。见 5.11 节。 > > **V3.12 加 1 张**:`reset_log`(系统重置留痕)。注意它**不在**被清空的表里 —— 重置完必须还能查到「谁清的、什么时候、清了多少」。见 5.12 节。 ### 组织与人员 | 表 | 说明 | |---|---| | `sys_user` | 用户与角色:admin / manager / **dispatcher(调度)** / **supervisor(生产主管)** / driver / **logistics(物流经理)** / **washer(洗筐员)** / keeper。**V2.6 加 `dept`**:生产主管的归属班组(生鲜/果蔬),空 = 不限 | | `sys_role` | 角色权限定义,对应 SOP 第 4 章 RACI | ### 基础档案(主数据) | 表 | 说明 | |---|---| | `line_info` | 配送线路(城区线/东乡线/南乡线/西乡线/北乡线/补货岗) | | `driver` | **司机档案(V1.9 新增)**:`code` 编码、`name` 姓名、`alias` 称呼、`phone` 手机号(小程序账号)、`license_type` / `license_exp`、**`vehicle_no` 绑定车号**、**`line_id` 所属线路**、`status`、`join_date`。**这张表同时是「车」与「线路」的来源** | | `vehicle` | **车辆(V1.9.1 改为派生)**:`no` 车号、`line_id` / `status`(由该车启用司机推导)、`plate` / `model` / `capacity` / 保险年检(**选填运营字段,平台不维护**)、`qr_code`。行由写 `driver` 时自动 upsert;后台「车辆一览」= 视图 `v_vehicle` | | `school` | 客户档案,**登记遗留的最小维度**;**V1.9 扩充** `full_name` 全称、`cus_type` 类型(学校/企事业单位/机关食堂)、`addr`、`note`;无账号、无签认字段 | | `basket_type` | **筐型字典**(V1.6 可自定义):编码、名称、规格、单价、默认登记人、排序、启用状态;现场几种规格就几行,代码不预设种类、不绑业务线。**V2.6 加 `dept` 归属班组**(生鲜/果蔬/共用) | | `basket_batch` | 采购批次,支持按批核算损耗 | | `basket_unit` | 单筐档案,**升级「一筐一码」时才启用**,数量制下留空 | ### 五步作业单据(一张表 = 一步) | 表 | 步骤 | 对应表单 | |---|---|---| | `route_plan` / `route_plan_school` | ① 物流排线 | FR-01 线路排线单 | | `plan_school_removed` | **① 排线减校留痕**(V2.7) | 不单独对应表单:一行 = 「哪单、哪校、谁、为什么移出、何时恢复」。软删可恢复,已发生业务的不许移出 | | `plan_backfill` | **历史作业日补录留痕**(V2.7) | 不单独对应表单:一行 = 「哪单哪步被补录、谁补的、什么时候补的」 | | `basket_apply` | ② 登记用筐数量 | FR-02 用筐登记单(V2.3:按「学校 × 筐型」一行) | | `plan_reg_type` | **② 的按筐型留痕**(V2.6) | 不单独对应表单:一行 = 某单某筐型「谁、几点、归哪个班组登的」 | | `out_check` | ③ 出仓复核 | FR-03 出仓复核单 | | `school_daily` | ④ 带回与遗留登记 | FR-04 学校带回与遗留登记单(V2.7:不平须写 `diff_reason` + 自动开异常单) | | `school_adjust` | **④ 的期初校正**(V2.3) | 不单独对应表单,是 FR-04 的调整附单 | | `adjust_request` | **调整单的申请**(V3.0) | 不单独对应表单:现场提申请 → 后台审批 → 通过才生成上方 `school_adjust`。**不参与闭环计算** | | `seal_check` | **⑤-A 回场封存**(V2.9) | FR-05A 回场封存单:司机报数 + 电子签署。**V3.0 取消强制拍照**(`seal_qty` / `sealed_at` 仍是 KCP-5 比较基准)。签署后锁定,不可改不可删 | | `seal_check_type` | **⑤-A 的按筐型申报**(V3.0) | 不单独对应表单:一行 = 某次封存某筐型报了几个。**选填,但填了 Σ 必须等于 `seal_check.seal_qty`** | | `inbound_check` | ⑤-B 回场验收 | FR-05 回场验收单(含验收岗位,区分两班;`pre_qty` 存封存申报数快照,`ack_status` 存司机确认) | | `inbound_check_type` | **⑤ 的按筐型验收明细**(V2.7) | 不单独对应表单:一行 = 某次验收某筐型点了几个;**缺行 = 未登记,不等于 0** | | `evidence_photo` | **六类单据的影像留证**(V1.8) | 不单独对应表单,是 FR-02~FR-05、FR-08 的附件行 | ### 其他单据 | 表 | 说明 | |---|---| | `workshop_stock` | FR-06 车间日盘点表(V2.7:四区 + 在途,在途 = 出筐 − 回筐 + 遗留) | | `exception_order` | FR-07 异常差异登记表(V2.7:加「出筐 / 回筐 / 验收数」三列 + 责任判定 `resp`) | | `exception_order_type` | **异常单的筐型明细**(V2.7):让「差 5 个」能定位到具体筐型 | | `broken_report` | FR-08 破损报损单 | | `school_audit` | FR-10 留存抽查表(兜底,偏差率驱动 KCP-10) | | `import_batch` | **导入批次留痕(V1.9 新增)**:`batch_no`、`kind`、`source`、`file_hash`、`add_cnt` / `upd_cnt` / `err_cnt`、`operator`、`result`。只增不改,与 `evidence_photo` 同级权限 | ### 台账与配置 | 表 | 说明 | |---|---| | `ledger_daily` | 日粒度台账,**由系统按五步结果自动汇总**,不手工录入 | | `reconcile` | FR-09 周盘/月盘对账表 | | `kpi_config` | KPI 阈值与校验参数(损耗红线、留存账龄、盘点阈值…),后台可调 | ### 筐具库存(V3.8) | 表 | 说明 | |---|---| | `stock_book` / `stock_book_type` | **期初建账单**:按筐型记期初实盘,**建了就锁定**;`kpi_config.base_stock` 自此只做兼容兜底 | | `stock_book_log` | **期初归档**:开新期时旧账整行进这里,**只增不改**。期初被谁在什么时候动过,只有这里查得到 | | `stock_in` / `stock_in_type` | **入库登记单**:采购 / 调入 / 退回三种来源,带批次与单价。进可盘点基数**分母**,不进损耗**分子** | | `stock_loss_request` / `stock_loss_request_type` | **报损申请**:洗筐员提,状态「待审 / 通过 / 驳回」。**申请绝不参与任何损耗计算** | | `stock_loss` / `stock_loss_type` | **报损生效单**:只由审批通过写入,只增不改不删。`待倒查 = 累计损耗 − Σ本表` | ### 系统运维(V3.12) | 表 | 说明 | |---|---| | `reset_log` | **系统重置留痕**:谁在什么时候清了哪些表、各清多少行、备份文件叫什么。**重置不清这张表**,否则等于自己抹掉自己。见 5.12 | ## 3. 关键关系 ``` line_info 1──n vehicle 1──n route_plan 1──n route_plan_school n──1 school driver n──1 line_info (司机绑线路;车辆与客户的线路都由它推出) driver 按 vehicle_no 聚合 → 车辆(1 台车 n 名司机轮班,主驾取 id 最小者) route_plan 1──n basket_apply (每校每筐型一行,KCP-2;V2.3 起带 school_id) route_plan 1──n plan_reg_type (V2.6:每筐型一行,「谁几点登的」;两组各写自己那几行) route_plan 1──1 out_check (③ 只允许一次有效复核) route_plan 1──n school_daily (④ 逐校一行,闭环约束) route_plan 1──1 inbound_check (⑤ 一车一天一次验收) route_plan 1──n evidence_photo (按 scene + ref_id 归属:reg / ck / ret(逐校) / inb / rep) school 1──n school_daily (每日遗留成为次日 carry_in_qty) school 1──n school_adjust (V2.3 期初校正:只追加带符号调整,不改历史) school 1──n school_audit (抽查,偏差 >10% 开异常单) inbound_check 1──0..1 exception_order (KCP-5) school_audit 1──0..1 exception_order (KCP-10) import_batch 独立表,只记「谁导了什么」,不参与业务外键 ledger_daily ← 由 out_check / inbound_check / school_daily / workshop_stock 每日汇总 reconcile ← 由 ledger_daily + basket_batch + broken_report 周期结算 ``` ## 4. 与 SOP 校验规则的对应 | SOP 控制点 | 数据库落地方式 | |---|---| | KCP-0 作业日归属 | 所有 `biz_date` 由服务端 `bizDateOf()` 推导(≥19:00 归次日);`kpi_config` 存 `sort_open` / `sort_close` / `biz_day_offset`。**V2.3**:只有 `route_plan` 允许手填作业日,且限「预排 +7 天 / 补录 −30 天」,`date_manual=1` 时 `date_reason` 必填(`CHECK` 兜底);现场四步一律自动推导 | | KCP-1 排线前置 | `basket_apply.plan_id` 非空;`route_plan` 唯一键 `(biz_date, vehicle_id)` 防重复排线 | | KCP-2 逐校逐筐型登记 | `basket_apply` 唯一键 `(plan_id, school_id, type_id)` + `CHECK (qty >= 0)`(V2.1 空≠0:未登记是不写行,0 是合法登记);视图 `v_kcp2_apply` 比对「启用筐型数 × 本车学校数 = 该单行数」,服务层据此放行 ③。**V2.6 班组分工不放松这条**:`plan_reg_type` 只用来回答「这组交了没」,整车出仓仍按 `v_kcp2_apply` 全量判 | | KCP-3 出仓双人复核 | `out_check` 唯一键 `plan_id`;`diff_qty ≠ 0` 时服务层拒绝落库 | | KCP-4 分校闭环 | `school_daily` 的 `CHECK (back_qty + left_qty = carry_in_qty + delivered_qty)`,应用层先算 `closure_gap` 再落库,非 0 直接 422 | | KCP-5 回场验收 | `inbound_check.diff_qty ≠ 0` 时同事务插入 `exception_order` 并回填 `exception_id`。**V3.0**:比较基准是 `seal_check.seal_qty`(封存申报)而非回场时刻;`pre_by_type` 存申报明细快照,合计平但分型不平 → 标「串筐」,不算 KCP-5 差异 | | KCP-6 遗留账龄 | 查 `school_daily.left_qty` 与最近 `back_qty=0` 的日期差,超 3 天推送催收 | | KCP-7 损耗红线 | `ledger_daily.total_qty` 与 `kpi_config.base_stock` 对比 | | KCP-8 日结时限 | `ledger_daily.settled=0` 且已过作业日当日 18:00(`kpi_config.settle_deadline`)→ 定时任务催办 | | KCP-9 影像留证 | **硬前置(V1.8)**:`evidence_photo` 一影像一行,视图 `v_kcp9_evidence` 按 `scene` 算 `got/need`(④ 的分母用子查询按校累加);`out_check` / `inbound_check` / `school_daily` 各带 `photo_count` 并由 `CHECK` 兜底;张数不足时服务层拒绝写库。**V3.0 改口径**:判据从「拍够几张」改为「一张能不能证明」——② 1 张、③ 0 张(② 有影像即免拍)、④ 车级 1 张 + 有遗留校各 1 张、⑤-A 0 张(可选补拍)、⑤-B 1–2 张。`seal_check.ck_seal_photo` 同步放开 | | KCP-10 抽查偏差 | `school_audit.dev_rate > 10` → 同事务插入异常单;线路加权平均 > 5% 触发看板告警 | | **主数据唯一性(V1.9)** | `uk_driver_code` / `uk_driver_phone` 兜住「一人两档」;`school.uk_code` 与 `vehicle.uk_no` 兜编码与车号;导入层的「文件内重复」是应用校验,库层是最后一道保险 | | **主数据枚举(V1.9)** | `ck_school_type` 兜客户类型、`ck_driver_vehicle` 兜「车号必须纯数字」、`ck_imp_kind`(三张模板)、`ck_imp_result` 兜批次结果 | | **导入留痕(V1.9)** | `import_batch` 行级记录 + `file_hash`;只授 `INSERT / SELECT`,与 `evidence_photo` 同级 | ## 4.1 筐型为什么要独立成表(V1.6 设计说明) 筐型不是枚举,而是**用户可维护的主数据**。这一条决定了三件事: 1. **`basket_apply` 不能存业务线字符串,只能存 `type_id`。** 存字符串(`'SX'` / `'生鲜'`)意味着每加一种规格都要改代码里的白名单; 存外键则加一行 `basket_type` 就完事,唯一键 `(plan_id, type_id)` 同时兜住 KCP-2 的「不能重复登记」。 2. **KCP-2 的校验必须用「当日启用筐型数」做分母。** 写死 `COUNT(*) = 2` 会在新增第三种筐型时立刻失效;正确写法见视图 `v_kcp2_apply`。 3. **停用不能删行。** `basket_type.is_active = 0` 保留历史;如果物理删除,`basket_apply.type_id` 外键会断, 历史台账就再也解释不清「这一车装的是什么筐」。同理,`basket_type.code` 一经使用就不该改。 对应的可执行 SQL: ```sql -- 某排线单的 KCP-2 是否通过(1=通过) SELECT plan_id, need_types, got_types, kcp2_pass FROM v_kcp2_apply WHERE plan_id = ?; -- 新增一种筐型(不动任何代码) INSERT INTO basket_type (code, type_name, spec, unit, price, owner_name, sort_no, is_active) VALUES ('SC', '水产筐', '580×380×280', '个', 48.00, '周工', 3, 1); -- 停用一种筐型(不回改历史) UPDATE basket_type SET is_active = 0 WHERE code = 'SC'; ``` ## 4.2 影像表为什么这么设计(V1.8 / KCP-9) `evidence_photo` 一行 = 一张照片。设计上有五个不能妥协的点: **① 一行一张,不做「附件 JSON 字段」。** 把 N 张照片塞进一个 `json` 字段,就再也没法在库里按张数做约束,也没法审计「第 3 张什么时候删了」。 拆成行后,`(plan_id, scene, ref_id, seq_no)` 唯一键天然防重复提交。 **② 只授 INSERT / SELECT,不授 UPDATE / DELETE。** 这是**权限层面**的留证,不是代码层面的。只要应用账号有 DELETE,任何一次「误操作」都能把证据清掉, 而且事后查不出来。撤销唯一路径是作废整张单据走 `exception_order`——那张单子上有责任人、有原因、有时间。 **③ 应拍张数不能写死,但也不能一直「动态加法」。** V1.8 时 ④ 的 `ret_need` 用子查询按「每校 1–2 张」实时算;**V3.10(11-16 客户五.1)取消了逐校要求,`ret_need` 直接变成车级常量 1**: ```sql -- V3.10:④ 只要求车级「本车卸货完成全景」1 张,与学校数、遗留数都无关 1 AS ret_need, -- 同时 ck_need 恒为 0(③ 影像不强制),reg_need 恒为 0(② 可选) ``` 写死 `COUNT(*) = n` 会在两种情况立刻错:学校数变了(临时加校 / 减校)、有遗留的学校多了。反过来,**把「动态」当成永久正确也会错** —— 客户一改口径,整个视图的分母就得跟着改,所以视图里每一列都要有一行注释写清「当前口径来自哪一版需求」。这一点比公式本身更容易被忘掉。 **③-b 零影像车要能查出来(V3.10 新增)。** 闸门放松之后,「这辆车一张影像都没有」变成一个**合法但必须可见**的状态。视图加一列: ```sql -- 作业三段(reg + ck + ret)合计为 0 → 零影像车 CASE WHEN (SUM(CASE WHEN e.scene IN ('reg','ck','ret') THEN 1 ELSE 0 END)) = 0 THEN 1 ELSE 0 END AS zero_evid ``` **只数作业三段**:封存(`hand`)与验收(`inb`)不算 —— 否则回场随便补一张就把「车在路上没留证」洗白了。 口径必须与后端 `evidStat().zero`、PC `evidZero()` 完全一致,三处任何一个走偏,抽查都会抽错车。 **④ 时间要双轨记。** `shot_at` 是客户端自报(也就是水印上的时间),`received_at` 是服务器收到的时间,`skew_min` 存两者差。 手机时间能改,服务器时间不能改。`|skew_min| > 30` 只标「待核」**不阻断**—— 可能是网络慢、可能是时区错,直接拒单会误伤,但必须留痕给抽查的人看。 **⑤ 只存 object_key,绝不存 base64。** 一张 base64 缩略图能把单行撑到几百 KB,一天 105 张就是几十 MB, 库表、备份、慢查询全被拖死。缩略图单独一列存自己的 key,列表页拉缩略图、详情页拉原图。 ```sql -- 某车的 KCP-9 达标情况(kcp9_pass=0 即凭证不足) SELECT vehicle_id, reg_got, reg_need, ck_got, ck_need, ret_got, ret_need, inb_got, inb_need, kcp9_pass FROM v_kcp9_evidence WHERE plan_id = ?; -- 查时间可疑的影像(供抽查) SELECT id, scene, shot_at, received_at, skew_min, uploader FROM evidence_photo WHERE ABS(skew_min) > 30 AND biz_date = ? ORDER BY skew_min DESC; ``` ## 4.3 主数据表为什么单独拆出来(V1.9) 前三版一直在补**业务数据**(今天出了多少、回了多少、差在哪)。但业务表能跑起来的前提,是**主数据先建好**:排线要选学校、选车、选司机。所以 V1.9 把主数据单独拆出来维护,并从制度上把它和业务数据隔开。 **① 车辆不单独建档,是「司机绑车号」的投影。** 最直觉的做法是建一张车辆表,录车号、线路、主驾三项。问题是这三项在司机档案里**全都有**——两处都能改,迟早不一致,而现场看到「这边写 3 号线、那边写 5 号线」时没人判断得出哪个对。 所以数据的唯一来源是 `driver`: ```sql -- 司机档案:车号与线路都在这张表里(这是唯一入口) vehicle_no VARCHAR(10) NOT NULL COMMENT '绑定车号,纯数字 1–999', line_id BIGINT NOT NULL COMMENT '所属线路', -- 注意:不设 (vehicle_no) 唯一 —— 一台车允许多人轮班 KEY idx_driver_vehicle (vehicle_no) ``` `vehicle` 表仍然存在,但它变成了**外键锚点**(业务表按 `vehicle_id` 引用,改不动)+**派生物**:写 `driver` 之后按 `vehicle_no` upsert 一行,`line_id` / `status` 由该车启用司机推导。后台那张「车辆一览」就是视图 `v_vehicle`: ```sql CREATE OR REPLACE VIEW v_vehicle AS SELECT v.no AS vehicle_no, v.id AS vehicle_id, COALESCE(m.driver_name, '') AS main_driver, COALESCE(m.line_id, v.line_id) AS line_id, (SELECT COUNT(*) FROM driver d2 WHERE d2.vehicle_no = v.no) AS driver_cnt, (SELECT COUNT(*) FROM driver d3 WHERE d3.vehicle_no = v.no AND d3.status = 1) AS driver_on_cnt, CASE WHEN EXISTS (SELECT 1 FROM driver d4 WHERE d4.vehicle_no = v.no AND d4.status = 1) THEN 1 ELSE 0 END AS status FROM vehicle v LEFT JOIN (SELECT d.vehicle_no, d.name AS driver_name, d.line_id, ROW_NUMBER() OVER (PARTITION BY d.vehicle_no ORDER BY d.id) AS rn FROM driver d WHERE d.status = 1) m ON m.vehicle_no = v.no AND m.rn = 1; ``` **② 一台车允许绑多名司机(轮班),主驾取 `id` 最小者。** 早期版本试过用生成列 + 唯一索引把「一车一主驾」锁死(`uk_driver_active_vehicle`),写完就发现不对:夜班/早班轮换是常态,锁死会逼着每次换班都去改档案,产生大量「停用 A / 启用 B」的噪音,而这些人本来就都是这台车的司机。 正确做法是**允许多人、但主驾必须确定**:`ORDER BY id` 取第一位启用司机,前端 `deriveVehicles()` 与库端 `v_vehicle` 用的是同一条规则,所以两边不会打架。换主驾 = 把要当主驾的那位排到前面(或停用原来的),不需要删任何一行。 **为什么不在 `vehicle` 表存司机姓名**:这跟上面是同一条原则。存了姓名就得同步维护,一旦漏了就会出现「车说王师傅、司机说姓李」。反查的代价只是一次 `find`,而维护两份副本的代价是永久的对账。 **③ `school` 扩充而不新建 `customer` 表。** 客户类型里包含企事业单位与机关食堂,但**登记遗留的最小维度永远是一所学校/一个收货点**。新建 `customer` 表会让 `school_daily` 到底连哪张表变成一个问题。所以做法是给 `school` 补 `full_name`(全称,对账用)、`cus_type`(类型)、`addr`、`note`——**表名还是 `school`,语义扩成「客户」**,业务表一行都不用改。 **④ 导入只允许写主数据表,这条边界要落在代码里,不能只写在文档里。** `applyOne()` 只逐字段覆盖主数据白名单:`customers` 覆盖 `full_name / name / cus_type / line / vehicle / addr / contact / phone / status / note`;`held`(留存数)、`age`(账龄)**不在白名单里**。所以「导入改了个客户名,留存数全没了」这件事在结构上不可能发生——**不是靠人小心,是靠没有那条改的路径**。 对应 SQL 层面的写法: ```sql -- 导入更新客户:只写主数据列,业务列原样不动 UPDATE school SET full_name = ?, name = ?, cus_type = ?, line_id = ?, default_vehicle_id = ?, addr = ?, contact = ?, phone = ?, status = ? WHERE school_code = ?; -- held / age / audit_* 一个都不出现,写漏了也不会被覆盖 ``` **⑤ `import_batch` 与 `evidence_photo` 同级:只增不改。** 主数据导错了要能查到「谁在什么时候导的、从哪个文件、改了多少条」,否则只能全表重来。所以 `import_batch` 记 `file_hash`(同文件重复提交可识别)、`add_cnt` / `upd_cnt` / `err_cnt`、`operator`,并**只授 `INSERT` / `SELECT`**——留痕可改就等于没有留痕。 **⑥ 上线顺序:客户 → 司机 → 排线。** 客户先导(`line_id` 要落在已存在的线路编组上),司机后导(车与线路随它一起产生),排线永远最后(引用了前两张)。顺序颠倒不是「会报错」这么轻——是整批被拒,而操作的人往往以为是文件格式问题。注意 `driver` **可以先于** `vehicle` 行写入:车号是自然键,`vehicle` 行随后自动补。 ## 5. 口径一致性说明(重要) ### 5.0 `biz_date` 是作业日,不是自然日(V1.7 / KCP-0) 库里所有 `biz_date`(`route_plan` / `basket_apply` / `out_check` / `school_daily` / `inbound_check` / `ledger_daily` …)都是**作业日(配送日)**: - 分拣时段 **19:00 → 次日 03:00**,跨零点; - **录入时点 ≥ 19:00 时,`biz_date` = 自然日 + 1**; - 应用层用**单一函数**算(`server.js` 的 `bizDateOf()` / `bizToday()`),**禁止在业务代码里另写一份日期推导**; - `kpi_config` 里落了参数,供后台调整与审计: ```sql ('sort_open','19:00'), ('sort_close','03:00'), ('biz_day_offset','19'), ('settle_deadline','18:00') ``` 为什么不用 `DATE(created_at)`:`created_at` 是自然日,19:00–24:00 的分拣量会被算到前一天,于是出筐虚低、回筐(次日上午才回场)全落到后一天,`ledger_daily.diff` 会长期为负、`cum_diff` 越滚越大,损耗率必然算错。 改日期一律视为越权:`biz_date` 由服务端推导,前端传入值仅供历史补录,必须留审计日志。 ### 5.1 台账的「出筐」「回筐」不是单方登记数 这是最容易写错的地方(V1.2 起口径,V1.6 只是把「业务线」换成「筐型」): | 台账字段 | 取值来源 | **不能**取的值 | |---|---|---| | 出筐 | `out_check.review_qty`(复核一致数) | 生产主管登记的计划数 | | 回筐 | `inbound_check.inspect_qty`(验收数) | 司机登记带回数 | | 学校留存 | `Σ school_daily.left_qty`(期末遗留) | 倒推的 −累差 | 损耗率三个地方(看板、台账、月报)必须同源: ``` 累计损耗率 = (期初实盘 − 最近一次实盘) ÷ 期初实盘 = (3727 − 3610) ÷ 3727 = 3.139% ``` - **期初实盘**:2026-08-28 首次盘点 3727 个(`kpi_config.base_stock`) - **期末实盘**:台账总数 = 车间盘点 + 学校留存(9/30 为 3261 + 349 = 3610) - 附件「备注」栏写的「9 月 30 日盘点 3610,与开学前相差 117 个」与上式完全吻合。 > ⚠️ 附表中 9/30「车间盘点」列写的是 3261,那是**场内库存**,不等于**总实盘**。 > 平台取「车间 + 学校留存」作为实盘口径,才与备注的 3610 对得上。这一点上线时必须统一,否则会出现「同一个损耗率两个数」。 ### 5.2 分校闭环恒等式 ``` 带回 + 期末遗留 = 期初遗留 + 当日送达 (带回含破损) ``` - `broken_qty` 是 `back_qty` 的**子集**,只用于报损,**不参与等式**。 - `carry_in_qty` 不手工填,= **该校上一条 `school_daily.left_qty`(首日取 `school.held`)+ Σ `school_adjust.adjust_qty`**。 基线本身有偏差时**不改历史**,另开调整单冲抵(见 5.2.1)。 - `delivered_qty` **取 ② 按校登记的实际数**(`Σ basket_apply.qty WHERE plan_id, school_id`), 不是排线计划值 —— V2.3 起排线单不再预设送达量。老单据没有按校登记时才回落到历史计划字段。 - `closure_gap ≠ 0` 一律不落库:数据库 `CHECK` 是最后一道保险,服务层应在写库前就拦下并返回 422。 #### 5.2.1 期初遗留为什么用「调整单」而不是直接改(V2.3) `school_daily.left_qty` 是**历史事实**:那天司机报的就是这个数。事后把它改掉, 那天晚上的对账记录就没了,谁也说不清是「当时就错了」还是「后来被人改了」。 所以偏差走 `school_adjust`: ``` 当日期初 = 上一次 left_qty(或 school.held) + Σ school_adjust.adjust_qty ``` - 一张调整单 = 一笔带符号的数量 + 一个**必填**的原因 + 开单人 + 生效作业日; - 只追加不修改(表上不给 UPDATE/DELETE 授权): - 开错了就再开一张反向的,两张都留着; - 等式形式完全不变,仍然 `带回 + 遗留 = 期初 + 送达`,只是期初变成「基线 + 调整」。 - **调整单本身也是一条差错的证据**:一个学校一个月开了 5 张调整单,说明的不是会计勤快,是现场在编数。 #### 5.2.2 班组分工怎么落库(V2.6) 现场的生产主管分**生鲜组 / 果蔬组**两个班组,各管各的筐型。让生鲜组的人盯着果蔬筐填数, 既占屏幕又容易填串。落库分三层: | 层 | 字段 | 作用 | |---|---|---| | 主数据 | `basket_type.dept` | 这个筐归哪个班组;空 = 共用(哪个组都要登) | | 主数据 | `sys_user.dept` | 这个人属于哪个班组;空 = 不限(管理员、总主管看全部) | | 单据 | `plan_reg_type` | 某单某筐型「谁、几点、归哪个班组」登的 | **两条不能破的约束:** 1. **提交按筐型增量化**:两组先后交同一张单,后交的不能覆盖先交的。 应用层做法是「以 `basket_apply` 现有行为底,只 upsert 本次 `codes` 里的筐型」—— 千万不能「先删该单所有行、再插本次的」,那会让先交的那组白干。 2. **KCP-2 按全量判**:`basket_apply` 的「启用筐型数 × 本车学校数」这条不变。 一个组交完只是**他那半边的 `plan_reg_type` 齐了**,整车要出仓仍得两组都齐。 > 为什么不用「一个班组一张单」:排线单是按车排的,一车就是一趟活。 > 拆成两张单会让 ③ 出仓复核面对「这车到底装了多少」,反而制造新的对账缝隙。 > **V3.7:司机的两个来源要分清。** `driver` 表表达的是「这车平时归谁」(长期主数据), > `route_plan.driver` 表达的是「今天这趟谁跑」(当天事实),另有 `route_plan.crew` > 记随车/顶班司机。排线时以 `driver` 表值作默认、允许逐单改,改的是排线单不是档案 —— > 现场换班、新司机未建档都走这条,不能反过来去改司机档案(那是全局生效,会把历史单据的归属一起歪掉)。 > `route_plan.driver_src` 记这次值的来源:`manual`(排线时定下)/ `arch`(弹窗未渲染,回落档案)/ `none`(明确待指派), > 报表里出现 `none` 就是在提醒「这一趟没人认账」。 ### 5.3 抽查折算留存(兜底口径) 当抽查发现某校登记遗留与实盘差异较大时,月末对账用折算值而非登记值: ``` 已抽查学校 → 取 school_audit.real_qty 未抽查学校 → 登记遗留 × (1 + 本线路已抽查学校的加权平均偏差率) 期末实盘 = 车间盘点 + 抽查折算留存 ``` > V1.2 起,日常差异已由 KCP-4 + KCP-5 在当天拦住,抽查主要用于**验证这两道闸有没有被执行**。 > 若抽查频繁出现大偏差,要先查执行,不要靠加抽查频次解决。 ### 5.4 验收岗位(两班当班) `inbound_check.inspector_role` 记录当班验收岗位,不是可有可无的备注字段——它决定「这一车该谁负责」: | 取值 | 场景 | 说明 | |---|---|---| | `logistics` | 洗筐员到岗前 | 物流经理逐车登记每个司机的回筐数量 | | `washer` | 洗筐员到岗后 | 洗筐员接续验收,并负责逐筐分拣(可用 / 破损) | - 两班以「最后一车已验收」为断点交接,**断点前的车归 logistics,断点后的车归 washer**,各自对差异负责。 - 表上 `CHECK (inspector_role IN ('logistics','washer'))` 兜底;`UNIQUE (plan_id)` 保证一车一天只验一次,不允许两班重复点数。 - `broken_qty` 有 `CHECK (broken_qty BETWEEN 0 AND inspect_qty)`:破损不可能多于验收总数,写进去就是数据错误。 ### 5.5 单据变更与影像作废(V1.8) 影像不是「挂在车上」的,是「挂在那一次登记」上的。所以只要登记变了,影像就得重来: | 变更动作 | 影像后果 | 数据库落地 | |---|---|---| | ② 用筐数量追加 / 修改 | ② 的有效影像**全部作废**(V3.10 起不再要求重拍,回到「未附影像」状态) | 原行置 `superseded=1` + `superseded_at` + `superseded_reason`,**不删行**;`v_kcp9_evidence` 只统计 `superseded=0` | | ② 变更 | ③ 出仓复核**自动作废** | `out_check` 行置 `voided=1`;唯一键改用生成列 `active_plan`(作废行映射 NULL),既保证「一单一次有效复核」又保留历史 | | ④ 某校重报 | 该校的 `ret` 影像作废(V3.10 起校级照本就不强制,作废后不影响能否提交) | 按 `(plan_id, 'ret', ref_id)` 范围置 `superseded=1` | | ⑤ 验收差异为 0 → 非 0 | 应拍张数由 1 变 2,需补一张 | 服务层即时按 `photoNeed` 重算,不足拒绝 | > **V3.10 的连带影响要说清楚**:作废影像这条机制**一条没改**,但「作废之后必须重拍」这个后果取消了。 > 原因是作废的语义是「这张照片不再能证明现在这个数」,而不是「你必须马上再拍一张」—— > ② 现在本来就不强制拍,作废后它只是回到「没拍」的状态,与从没拍过没有区别。 > **③ 的复核自动作废仍然照旧**(数字变了必须重新复核),那是 KCP-3,不是 KCP-9。 **为什么唯一键要绕这么一圈**:`out_check` 原本 `UNIQUE(plan_id)`, 但登记变更后要重新复核,直接改 `plan_id` 或物理删行都会把「上一次复核是谁做的、什么时候做的」抹掉—— 而这条历史恰恰是争议时最需要的东西。用生成列把有效行映射成 `plan_id`、作废行映射成 `NULL` (MySQL 唯一索引不比较 `NULL`),一行代码同时满足「唯一」和「留痕」。 **这条规则的道理很简单**:账面数变了,旧照片就不能再证明「现在装了这么多筐」。 它和「登记变更即作废出仓复核」是同一条原则——**账面变了,凭证和复核都得重来**。 ### 5.6 V2.7(11-06 反馈)改了哪些口径 这一轮改的全是「现场用不下去」的地方,每一条都有一句为什么,别只抄字段: | # | 原来 | 现在 | 为什么 | |---|---|---|---| | 1 | 历史作业日只读 | **补录模式**,每次补录写 `plan_backfill` | 只读的结果是「忘了登记」只能去改 `data.json`,比补录危险得多。放行的是补录,成本是留痕 | | 2 | ④ 闭环不平一律 422 | **填 `diff_reason` 才放行**,同时自动开异常单 | 硬拦会把人逼去改数,改完照样平 —— 闸门形同虚设,账还变假了。`ck_closure` 约束随之改成「差不为 0 就必须有原因」 | | 3 | 期末遗留手工填 | 系统按 `期初 + 送达 − 带回` **自动算**,手改要写原因 | 现场心算必错。`auto_left_qty` 与 `left_qty` **分两列存**,否则事后分不清「点出来的」和「凑出来的」 | | 4 | ⑤ 只报一个总数 | **按筐型逐项验收**(`inbound_check_type`),合计由服务端重算 | 只报总数时「差 5 个」不知道差哪种筐,实物复核只能整车翻。客户端传的合计一律不采信 | | 5 | 异常单 `fresh_qty` / `fruit_qty` 永远空 | 加 `book_qty` / `back_qty` / `verify_qty` + `exception_order_type` | 异常表要按「出筐 → 回筐 → 验收数」一条链看,才知道差在哪一环 | | 6 | 盘点 `stock_total = 四区之和` | `= 四区 + 在途`,在途 = `out_qty − back_qty + left_qty` | 漏了在途,当天出车没回来的筐不在车间也不算学校留存,差异一律为负,每次盘点都像盘亏。`book_total` 存**当日快照**,不读档案当前值 | | 7 | 排线学校只能加不能减 | **可移出 + 必填原因 + 可恢复**(`plan_school_removed`) | 已发生业务的学校不许移出 —— 真删会让按日派生的台账出现孤儿数。所以是软删 | | 8 | 密码只能命令行改 | `POST /api/users`,后台建号 / 重置密码 / 启停 | 客户是区县运营团队,不能要求他们会 SSH。**密码永远服务端算**,前端不碰 salt/hash;库里是单向哈希,所以后台只能「重置」,给不出明文 | | 9 | 一个司机一条线 | `driver` 支持多线路 | 实际就是有人跑两条线。落库用关联表 `driver_line`,`line_id` 保留为主线路(兼容旧报表) | ### 5.7 V2.8(11-10 复核确认)补的两处结构 | # | 原来 | 现在 | 为什么 | |---|---|---|---| | 1 | 账号按**姓名**挂人员(应用层 `users.find(u => u.name === staff.name)`) | `sys_user.driver_id` 显式外键,一人一账号(`uk_user_driver`) | 重名就串号:改 A 的密码,同名的 B 反而登不进来。而且停用一个人要在人员与档案两处各点一次,漏一处他还能登录 | | 2 | 一个司机绑多线路时,`vehicle` 单值 → 车辆只归第一条线 | `driver_line` 关联表 + `vehicle_no` 保持单值 | 客户 11-10 明确「一个司机跑两条线是**同一辆车**」,所以车辆不必变成数组,只需把线路挂成多对多。`deriveVehicles()` 汇总该车全部司机的全部线路,不再只取主驾第一条 | **为什么不物理合并 `driver` 和「人员」两张表**:应用层有 40+ 处引用 `drivers`(排线 crew、车辆投影、台账、三个导入模板), 一次性合并等于把回归风险拉满,而收益只是少一张表。统一 ID 已经能拿到全部好处 (不重名串号、停用一处生效、账号挂人不挂姓名),并且可以渐进迁移 —— 老数据由 `relinkRoster()` 一次性补 ID。 ### 5.8 迁移规则:老数据怎么补 `staffId`(V2.8 实战踩出来的) 老库没有 `staffId`,也不能靠人手工对。前后端各有一份补 ID 的逻辑(`relinkRoster()` / `normalize()`), **两份必须逐字一致**,否则服务端补的 ID 和前端推的 ID 分叉,账号永远显示未绑定。 **① ID 只由编码推导,不采信历史值** ``` 人员 ID(非司机) = 'U_' + username 例:zhuguan → U_zhuguan 人员 ID(司机) = 'P' + 司机编码去 D 前缀 例:D01 → P01 ``` 线上曾出现「账号的 `staffId` 写着别人的 ID」和「两条司机档案共用一个 ID」两种脏值。 一旦采信历史值,脏值会被原样继承。统一函数 `pidOfDriver(d)`,只在编码推不出来时才回落到历史值。 **② 「id 在表里」不等于「绑定正确」** 校验必须确认那一行**确实是本人**:`p.account === u.username`,或 `p.name` 与账号名去掉「岗位·」前缀后相等。 只判 `staff.some(x => x.id === u.staffId)` 会把「王建国」放到「雷屿」的人员行上 —— 界面显示两人是同一个, 比「未绑定」更容易误导。对不上就清掉脏值重解析,别让它冒充绑定成功。 **③ 演示人员表要能自动作废** 早期前端会自动灌一张演示人员表(王总 / 张工 / 刘工 / 吴工 / 陈姐 / 赵会计,id 形如 `U01…U06`), 与真实账号根本对不上。判定用**演示特征**,不要用「整表有没有 `account`」—— > 旧逻辑的姓名匹配早就给「刘工」「陈姐」写过 `account`, > 一旦把它们当条件,重建永远不触发,线上就一直是大面积未绑定。 正确判据:统计「姓名属于演示名单 **且** id 匹配 `^U0\d$`」的行数,≥2 行即整表重建。 由账号推导出来的表 id 是 `U_`,碰不到 `U0x`,所以人手工维护过的表不受影响。 **④ 重建之后,「司机账号」和「司机档案」不能各占一行** 账号循环里若发现该账号姓名能在 `drivers` 里精确命中,就**跳过建行**,交给司机循环按 `P<编号>` 建, 两边共用一个人。否则同一个真人会同时出现 `U_siji` 与 `P01` 两行。 **⑤ 反过来,没有车号不能凭空造车** 「角色是配送司机但 `drivers` 里查无此人」时如果自动补一条司机档案,会多出一台空车号的「车」, 车辆一览里突兀地出现一行「车号空」。改为没编车号不补,人员表标「未编车」, 提示去司机档案里补编车 —— 这是真实状态(账号建了、档案没建),不该被代码掩盖。 ## 5.9 为什么 ⑤ 要拆成「封存 + 验收」两张表(V2.9) 客户现场的实际情况:**司机 06:00-07:00 陆续回场,洗筐员 08:00 才上班**,中间 1-2 小时。 原来的做法是「司机拍照发微信群 → 洗筐员上班后点数 → 司机核对签字」。 三处问题,都不是态度问题,是载体问题: | 环节 | 问题 | 后果 | |---|---|---| | 微信群照片 | 可撤回、可发相册旧图、无服务器时间、绑不到单据号、群记录会过期 | KCP-10 抽查时拿不出证据 | | 1-2 小时空档 | 实物在场地上、数字在司机脑子里,没人锁 | 第 10 点少的 20 个,分不清路上丢的还是场地上丢的 | | 司机核对签字 | 系统里没有这个位置,验收人改数没有任何当场制衡 | 只能事后追,追不动 | ### 5.9.1 `seal_check`(FR-05A) 一行 = 一辆车一次封存。**这不是验收**,只回答「几点交了多少」。 | 字段 | 说明 | |---|---| | `plan_id` | 唯一,一辆车一天一次(重复封存 409) | | `qty` / `broken` | **服务端按 ④ 逐校登记重算**,不接受客户端传值 | | `sealed_at` | 服务器时间,不取手机时间 | | `sealed_by` / `sealed_user_id` | 签署人(账号优先) | | `photo_count` | 封存影像张数。**V3.0 起不再强制 ≥ 2**(原「筐垛全景 + 封存区现状」两图要求取消,见 5.10.1),约束改为 `derived = 1 OR photo_count >= 0` | | `derived` | 1 = 由老数据推断补出来的,不是当场签的。**`photo_count=0`,不能当 KCP-9 证据** | 影像走 `evidence_photo(plan_id, scene='hand')`,与 FR-02~FR-05 同一张表、同一套锁定规则。 V3.0 起该 `scene` 只作**可选补拍**(司机愿意拍就存),不再是提交的前置条件; **唯一硬前置留给真正点数的那一端(⑤-B 验收)。** ### 5.9.2 `inbound_check` 新增的三个字段 | 字段 | 说明 | |---|---| | `pre_qty` | 封存申报数**快照**。不从 `school_daily` 现算 —— 现算等于把比较基准交给可变数据 | | `pre_at` | 封存时刻快照,差异出现时能一眼看到「隔了多久才验」 | | `ack_status` | `pending` / `ok` / `dispute`。`diff ≠ 0` 时初始 `pending` | `ack_status` 不与 `exception_order` 合并:异常单是「这个差异怎么处理」, `ack_status` 是「司机认不认这个数」。**认账不改变入账**(本来就按验收数入), **异议也不卡日结**(异常单转「待复核」,台账先走,复核后以调整单修正)。 因一台车卡住全天日结,现场第二天就会绕过系统 —— 这比差异本身更危险。 ### 5.9.3 两个时限不能合成一个 ``` 封存时限 = 回场(④ 最后一校登记完成)+ 30 分钟 验收时限 = 洗筐员 08:00 到岗 + 2 小时(清空「已封存待验收」队列) ``` 合成一个会出现两种误判:按验收时刻算,09:30 回场的车 14:00 才验 = 超时 4.5 小时,所有车全红, 警报直接失去意义;按回场时刻算,司机按时封存了却因为洗筐员在忙被记超时,罚错人。 ### 5.9.4 老数据怎么补 V2.9 之前的数据没有 `seal_check`。迁移判据是**「有没有 `seal` 这个键」,不是「值真不真」**: | 情况 | 处理 | |---|---| | 完全没有 `seal` 键(V2.9 之前的数据) | ④ 登记完成的,按逐校登记汇总补一条派生封存(`derived=1`、`photo_count=0`) | | 有 `seal: null`(新任务,还没封存) | **不补**。这是司机真的还没交数,替他补等于让 KCP 拦截失效 | | 有 `seal` 实体 | 原样使用 | 用真值判断(`if (!t.seal)`)会把「④ 登记完、司机还没封存」误判成已封存, 这是本次最容易踩的坑 —— 拦截面看似存在,实际一次都不会触发。 ## 5.10 V3.0(11-12 现场实测反馈)改了哪些结构 这轮改了 3 处,前两处是「放开」,后两处是「新增」。判断依据只有一条: **留证要证明「这张单是真的」,不是证明「照片够多」。** 张数门槛只会换来敷衍的糊图。 ### 5.10.1 `seal_check`:`photo_count >= 2` → `>= 0` 客户原话是「司机回场还要拍两张筐垛,早上六七点车场里黑漆漆的,拍出来什么都看不清」。 原来的 ≥2 是想保「封存时的一手证据」,但实际执行下来是:司机把相机对着筐堆按两下, 两张几乎一样的黑图,谁也没法用它判断数量。**门槛没换来证据,只换来了动作。** 所以约束放开,`ck_seal_photo` 改为 `derived = 1 OR photo_count >= 0`。 但**取消的是「司机拍照」,不是「交接确认」**: - `sealed_at` 照旧写入,**它才是 KCP-5 的比较基准**(验收超时按 `sealed_at + 24h` 算,不按回场时刻); - `seal_qty` / `broken_qty` 照旧必填,签署后照旧锁定; - ⑤-B 洗筐员验收仍要拍 1 张(有差异 2 张)——**点数的人负责拍,这才是有效证据**。 一句话:原来两个人都要拍,现在只在真正点数的那一端拍。 ### 5.10.2 新表 `seal_check_type`:封存申报按筐型 洗筐员验货是**一堆一堆按筐型点**的。原来封存只有一个总数, 验收时发现少了 5 个,只能定位到「这台车少了 5 个」, 到底是生鲜筐少还是果蔬筐少,事后永远说不清,异常单也只能挂个总数。 ```sql CREATE TABLE seal_check_type ( seal_id BIGINT NOT NULL, type_id BIGINT NOT NULL, qty INT NOT NULL, UNIQUE KEY uk_seal_type (seal_id, type_id), CONSTRAINT ck_seal_type_qty CHECK (qty >= 0) ); ``` 三条口径: 1. **选填**。司机回场已经很累,不逼他分型报数;不填就退化成整车比对。 2. **填了必须自洽**:Σ`qty` 必须等于 `seal_check.seal_qty`。两个数都是他自己报的, 对不上说明有一处填错了,这时候拦下来是对的(服务端 422,不是前端提示)。 3. **验收单要存快照**:`inbound_check.pre_by_type` 记下当时的申报明细。 否则司机事后改了申报、验收单拿新值比对,差异会凭空出现或凭空消失。 对应地,`inbound_check_type` 里多了个「串筐」判定: **合计平、分型不平** → 提示「串筐」,这不算 KCP-5 差异(人没点错,是筐装混了), 但要在验收单上留一句,方便后面追到底是哪条线混的。 ### 5.10.3 新表 `adjust_request`:申请 ≠ 生效 V2.3 的 `school_adjust` 有个隐患:它冲的是**期初遗留**,而期初遗留正是 KCP-4 恒等式的基准。 谁有权限直接开调整单,谁就能在自己不平的时候把式子配平 —— 闸门形同虚设。 V3.0 拆成两张表: | | `school_adjust` | `adjust_request` | |---|---|---| | 语义 | 已生效的账务调整 | 还没生效的请求 | | 参与 KCP-4 计算 | **是** | **绝不** | | 谁写 | 记账员 / 物流经理(审批后自动生成) | 司机(现场) | | 能否驳回 | 不能,只能反向再开一单 | 能,驳回必须写理由 | 流转:**司机申请(待审)→ 记账员/物流经理审批 → 通过则写一条 `school_adjust` 并回填 `adjust_id`**。 申请单本身永久留存,即使驳回了也留着 —— 它记录的是「现场认为账不对」这个事实。 三道 CHECK 约束都是防手抖,不是防恶意: ```sql CONSTRAINT ck_req_qty CHECK (request_qty <> 0 AND ABS(request_qty) <= 200) -- 多打一个 0 就爆 CONSTRAINT ck_req_status CHECK (status IN ('待审','通过','驳回')) CONSTRAINT ck_req_note CHECK (status <> '驳回' OR review_note IS NOT NULL) -- 驳回不写理由 = 不复核 ``` 前端还有个约束:同校同日已有「待审」申请时,再提一条直接 409。 不然一个人反复提交,审批的人要在一堆重复单里找。 ### 5.10.4 老数据怎么补(V3.0) V3.0 **不动存量数据**,只放开约束、加两张新表: | 变化 | 存量处理 | |---|---| | `ck_seal_photo` 放开为 `photo_count >= 0` | 老数据 `photo_count` 是 0 或 2,两种都合法,无需回填 | | 新增 `seal_check_type` | 老封存单没有按筐型申报 → 明细表留空,验收单退化成「只能比总数」。**不是缺陷**,是当时就没这个信息 | | 新增 `adjust_request` | V3.0 之前没有申请单,空表启动 | 唯一要留意的是 `inbound_check.pre_by_type` 快照:老验收单没有这个字段, 前端比对时按 `preByType ? 逐型比对 : 只比合计` 降级,**不要拿 0 去比**(会全车报串筐)。 ## 5.11 V3.8(11-16)筐具库存:期初 / 入库 / 报损 —— 账务模型修正 ### 5.11.1 先说结论:这三件事必须一起做 损耗率的式子看着简单,但**分子分母**各有各的坑,而且三个坑互相咬: ``` 累计损耗 = 期初实盘 − 台账总数(车间盘点 + 学校遗留) 可盘点基数 = 期初实盘 + 累计入库 损耗率 = 累计损耗 ÷ 可盘点基数 待倒查 = 累计损耗 − Σ 已生效报损 ``` 改之前的状态: | 环节 | 旧实现 | 后果 | |---|---|---| | 期初 | `kpi_config.base_stock` 一个数字 | 只记总数、不分筐型,「哪种筐在少」永远查不出来 | | 期初 | 设置页随手可改 | 一改,历史每一天的损耗率一起变 —— 账本可以事后重写 | | 补货 | **没有入口** | 新买的筐无处可记,只能偷偷改期初;分母不动,补得越多同样净灭失越「好看」 | | 破损 | **没有出口** | 破了的筐只能混进「车间盘点差异」,或者手工改在册数量。KCP-7 天天达标,账越对越糊 | | 假数据 | 筐具档案页「本月报损 12」写死在模板里 | 客户看板上的数是编的,比没有更糟 | **所以单修补货、或单修报损,账仍然对不平** —— 三条腿缺一条就站不住。 ### 5.11.2 硬规则:分子**不含**入库 这是本轮实现里唯一写反过的地方,被回归断言抓出来,必须记在这里: ``` loss = 期初实盘 − 台账总数 ← 分子:不含入库 stockBase = 期初实盘 + 累计入库 ← 分母:含入库 ``` 直觉上容易写成 `loss = (期初 + 入库) − 台账总数`,看起来「更完整」。但那等于 **每补一次货就凭空造出一笔损耗**:入库同时抬高了「应有」(期初+入库)与「实有」(实物里本来就有这批新筐), 两端约掉,净效应是 0。把它写进分子,2026-11-16 的回归里期初 3000 补 500 个, 累计损耗当场从 −2931 跳到 −2431,直接反了。 分母则必须含入库 —— 否则补货越多,同一笔净灭失算出来的比率越小,KCP-7 红线被人为稀释。 ### 5.11.3 负损耗照实给,不要 `Math.max(0, …)` 旧式 `loss = Math.max(0, baseStock - total)` 有两个毛病: 1. 盘盈(实盘比账面多)被截断成 0,看起来「没差异」—— 拿一个错误掩盖另一个错误; 2. 截断之后「待倒查」也跟着失真,现场没法判断到底是少了还是多了。 V3.8 起 `loss` 允许为负,前端显示为「盘盈 N 个」并单独着色。 ### 5.11.4 九张新表 | 表 | 作用 | 关键约束 | |---|---|---| | `stock_book` | 期初建账单(当前期) | `uk_period` 一个自然月一期;`locked=1` 建了即锁 | | `stock_book_type` | 期初按筐型明细 | `Σqty = stock_book.total_qty`(服务端重算,不收客户端合计) | | `stock_book_log` | 开新期时旧账归档 | 只增不改;`items_json` 存快照 | | `stock_in` | 入库单(采购/调入/退回) | `ck_in_source` 卡三种来源;带批次与单价,便于追采购质量 | | `stock_in_type` | 入库按筐型明细 | `qty > 0` | | `stock_loss_request` | 报损申请(现场提) | `status ∈ 待审/通过/驳回`;`reason` 必填;`photo_count ≥ 1` | | `stock_loss_request_type` | 申请按筐型明细 | `qty > 0` | | `stock_loss` | 报损生效单 | `req_id` 回填形成闭环;只由审批写入 | | `stock_loss_type` | 生效按筐型明细 | `qty > 0` | 「头表 + 按筐型明细表」是与 `basket_apply` / `inbound_check` / `seal_check` 一致的既有范式, 不为了省一张表塞 JSON —— 因为**按筐型分组汇总**是最常查的读法(「这个月 SX 破了多少」)。 ### 5.11.5 报损为什么也要「申请 ≠ 生效」 和 5.10.3 的 `adjust_request` 是同一个道理,只是作用对象从「期初遗留」换成了「待倒查」: > 报损单会直接减少 `待倒查 = 累计损耗 − 已报损`。 > 现场若能自己生效,盘点一不平,他就能写一张「破损 N 个」把差额解释掉, > 补上来的数正好把式子配平 —— KCP-7 损耗红线当场失效。 所以:**洗筐员只能 `stock_loss_request`(待审),keeper / logistics 审批通过才写 `stock_loss`**。 审批通过时把 `loss_id` 回填到申请单,形成「申请 ↔ 生效」双向可追。 驳回必须写理由(与调整单同款 CHECK)。 与调整单唯一的差别:**报损允许 PC 代录**(`by_proxy=1`)。现场洗筐员手是湿的、戴着手套点不了手机, 打电话报数给文员代录是真实工作方式 —— 与其逼他事后补,不如把「谁代录的」记下来。 调整单不需要这个口子,因为调整单本来就是记账员在 PC 上开的。 ### 5.11.6 老数据怎么补(V3.8) | 变化 | 存量处理 | |---|---| | 新增 9 张表 | 空表启动,**不需要迁移任何存量数据** | | `kpi_config.base_stock` | **保留**,仅作兼容兜底:`stock_book` 为空时才读它。一旦建账,以 `stock_book` 为准 | | 历史 `ledger_daily` | 不动。但要注意:建账基准日之前的损耗率会因分母换源而变化,这是**预期内**的修正,不是 bug | | 历史破损 | 无从追溯,不补录。V3.8 上线后的破损才进 `stock_loss`;`待倒查` 在初期会偏大,属正常 | > **建账基准日建议**取「最近一次真实日盘」的日期,`total_qty` 取那天的四区实盘合计。 > 不要拿台账推算值当基准 —— 那等于用账去建账,差异会被固化成「本来就这样」。 ## 5.12 V3.12(11-16)系统重置:清数据不是删库 ### 5.12.1 为什么要单独说这件事 正式启用前必须把试运行期间的测试数据清掉。第一版实现是「删 `data.json` 再重建」, 这在演示环境没问题、在客户已经用过两天的环境里是**灾难**: | 删库重建的后果 | 实际情况 | |---|---| | 账号回退到种子密码 | 客户改过的密码当场作废,而且**没有任何提示**,登录不上才发现 | | 学校 / 线路回退演示清单 | 客户导入的 28 所学校、6 条线路全没了,得重导 | | 没有备份 | 清错了无法回退,只能重录 | 所以 V3.12 把「重置」重新定义为:**清空业务行,保留一切结构与主数据,且先备份**。 ### 5.12.2 `reset_log`(新增) | 字段 | 类型 | 说明 | |---|---|---| | `id` | BIGINT PK | | | `at` | DATETIME(3) | 执行时刻 | | `by_user_id` | BIGINT | 谁清的;`sys_user` 主数据保留,所以外键查得到人 | | `by_name` | VARCHAR(40) | 冗余存名字:万一人被改名或停用,留痕仍可读 | | `ip` | VARCHAR(64) | 经反向代理,必须取 `X-Forwarded-For` 首段,不是 `remoteAddress` | | `scope` | VARCHAR(8) | `biz` / `all`,见 5.12.4 | | `removed_json` | JSON | 每张表清了多少行,**逐表记账而不是只存个总数** —— 事后复盘要靠它 | | `uploads_moved` | INT | 移走的影像张数 | | `base_stock_before` | DECIMAL(10,2) | 清之前的期初值,这是唯一能还原「原来账上多少」的线索 | | `backup_file` | VARCHAR(255) | 备份文件名 | > **`reset_log` 绝对不能并入 `op_log`**。`op_log` 本身在被清的那批表里,写进去等于自己抹掉自己 —— > 清完看审计,最新一条是空的。这一点在实现里踩过一次,别改回去。 ### 5.12.3 被清 / 被保留的边界 **清(业务流水,用完即弃)** `route_plan` 系 → `basket_qty` → `out_check` → `school_daily` → `seal_check` → `inbound_check` → `evidence_photo` → `adjust_order` / `adjust_request` → `exception_order` → `stock_in` / `stock_loss` / `stock_loss_request` / `stock_book*` → `workshop_check` → `audit_spot` → `op_log` → `import_batch` → 历史月结(`summary_9/10`、`line_total`) **留(清掉系统就废了)** `sys_user`、`school`、`line`、`vehicle`、`driver`、`basket_type`、`staff`、`kpi_config`、`reset_log` > 判断标准一句话:**「重新录一遍要花几天」的留,「明天就能重录」的清**。 > 主数据重录成本极高且容易错,业务流水本来就是一次性的。 ### 5.12.4 `scope` 为什么分两档 `all` = 全清(前端「系统重置」按钮);`biz` = 只清流水、**保留历史基线**。 历史基线指 `workshop_check`、`summary_9`、`summary_10`、`line_total` —— 它们是账面的起点数据, 客户若真运营过几个月,这些是要留着对账的。而自动化测试需要「干净但带基线」的库, 否则第 7、8 节一跑就找不到 9 月损耗 117 和盘点 17 条。 一体两面的结果:**客户看到的是一个按钮,服务端支持两种清法**。别为了少个参数把 `biz` 删掉。 ### 5.12.5 期初库存:置 `NULL` 不是置 0 `stock_book` 清掉后对应的状态是 **`NULL`**,不是 `{}`、也不是 `total_qty = 0`: - `total_qty = 0` 会被前端判成「**建过账,但一个筐都没有**」,损耗率分母变 0, 整页指标全塌成 `—` 或 `Infinity`,现场会以为系统坏了; - `NULL` 才是「**没建账**」,前端走的是「请先去期初建账」的分支。 同理 `kpi_config.base_stock` 也归零,但**不要删这行** —— 它是兼容兜底字段, `stock_book` 为空时才读它(V3.8 设计,见 5.11.6)。 ### 5.12.6 影像文件:移走,不删 `evidence_photo` 的行被清空后,对应的照片文件不应该跟着消失: ``` uploads/ ← 生产目录 _reset-20261117-093000/ ← 重置时整批 rename 进这里 ev-0001.jpg … ``` 理由有两条:① 备份是数据库层面的,`uploads/` 不在备份里,删了就没有第二份; ② 客户说的「清零」是**账面上不想再看到这些单**,不是「把这些照片销毁」。 真要删,由管理员在服务器上手动确认后删,属于运维动作,不该由按钮代劳。 > 若上 MySQL 版:`evidence_photo.file_key` 随行清空,磁盘上的旧文件变成**孤儿文件**。 > 建议保留一个季度再清理,清理前先确认库里确实没有任何 `file_key` 指向它。 ### 5.12.7 迁移与回滚 | 场景 | 做法 | |---|---| | 新增 `reset_log` | 空表启动,无存量数据 | | 升级到 V3.12(**不执行重置**) | 什么都不发生。旧 `/api/reset` 的删库行为已废弃,改成需要管理员口令 | | 重置后想回退 | 用 `data.json.bak-reset-` 覆盖回去,再重启服务。`uploads/_reset-/` 也要挪回 `uploads/` | | MySQL 版回退 | 备份是 `.sql` dump 而非 json;恢复用 `mysql < dump.sql`,先停应用 | > **备份失败必须中止**。`copyFileSync` 抛错时整个请求返回 `500 BACKUP_FAILED` 并且**一行数据都不清** —— > 「没有备份就允许清数据」是这类功能最典型的翻车方式,别为了「先跑通」把它降级成警告。 ## 6. 部署提示 1. 字符集 `utf8mb4`,排序规则 `utf8mb4_general_ci`。 2. 建库后执行 `kpi_config` 初始化 INSERT(已包含在 `schema.sql` 末尾)。 3. MySQL 需 **8.0.16+**,因为 `school_daily` 使用了 `CHECK` 约束。 4. 生产环境务必: - `sys_user.password_hash` 用 bcrypt(cost=10),禁止明文; - 关闭 `data.json` 演示模式,改用真实连接池; - 保留 `ledger_daily.biz_date`、`route_plan (biz_date, vehicle_id)`、`out_check.uk_active_plan`、`inbound_check.plan_id` 四组唯一约束——它们是幂等与防重的基石。 5. **`evidence_photo` 的权限要单独收紧(V1.8)**。留证靠权限保证,不靠代码自觉: ```sql -- 应用账号:只能写和读,不能改、不能删 GRANT SELECT, INSERT ON basket_db.evidence_photo TO 'app_user'@'%'; -- 明确收回(即使默认没授,也写出来作为约束) REVOKE UPDATE, DELETE ON basket_db.evidence_photo FROM 'app_user'@'%'; -- 归档账号只读 GRANT SELECT ON basket_db.evidence_photo TO 'audit_user'@'%'; ``` 为什么必须这样做:只要应用账号有 `DELETE` 权限,任何一次「手滑」都能把证据清掉,而且事后查不出来。 作废影像用 `superseded=1`,作废单据走 `exception_order`(带责任人、原因、时间),物理删除只允许 DBA 走变更流程。 6. 历史数据迁移:把附件台账按 `ledger_daily` 字段映射导入(8/28 为基准行,`out_qty/back_qty` 置空);`school_daily` 无历史数据,从上线首日开始积累,首日 `carry_in_qty` 取 `school.held`。`evidence_photo` 同理,上线首日起才有数据——**历史月份没有影像不是缺陷,是已知边界**,报表里要把「上线前」和「上线后」的凭证率分开看,否则首月数据一定难看。 7. **`import_batch` 的权限同 `evidence_photo`(V1.9)**: ```sql -- 导入留痕:可写可读,不可改不可删 GRANT SELECT, INSERT ON basket_db.import_batch TO 'app_user'@'%'; REVOKE UPDATE, DELETE ON basket_db.import_batch FROM 'app_user'@'%'; ``` 理由与影像表一样:留痕一旦能改,出事时就没有可信的第三方记录。**主数据错一次,全线单据跟着错**,所以「谁导的」必须查得到。 8. **主数据表不建议给应用账号 `DELETE` 权限(V1.9)**。客户、司机、车辆都被 `route_plan` / `school_daily` / `evidence_photo` 引用,物理删除会断链。停用走 `status='停用'`,删除只允许 DBA 走变更流程。 9. **上线导入顺序:客户 → 司机 → 排线**。客户先导(`line_id` 要先有),司机后导(车与线路随它产生),排线最后(引用前两张)。顺序颠倒会整批被拒(不是单行报错),操作者容易误判成文件格式问题。 10. **`vehicle` 行由应用层在写 `driver` 后 upsert,不要给人开放写入口**。`driver.vehicle_no` 改成新车号时,旧车的 `vehicle` 行不要删——业务表按 `vehicle_id` 引用它;只把它的 `status` 置 0,等哪天这台车再有人开,`status` 会自动回到 1。