记录显式 status 提交流程,并标注旧出入库设计中现场自动完成规则已被覆盖。 Co-authored-by: Cursor <cursoragent@cursor.com>
9.7 KiB
9.7 KiB
运输计划 · 入库单 / 出库单设计
日期: 2026-07-19
状态: 已确认并实现中
范围: web-admin 运输管理 + backend PL API + 免登录现场公共页
界面模式: 列表对齐标准列表(P01 / system/unit);编辑弹窗对齐 Fresh Mint dialog-form-layout
1. 背景与问题
现状为双轨:
- 安排运输后按产品生成
pl_transport_site_link(现场仅备注+附件,数量只读) - 可选勾选生成地磅
db_inbound_outbound(合一列表/#/db/inventory)
客户需要运输计划域下独立入库单 / 出库单界面:安排后落单、现场按产品填实际数量、整单附件备注、归档可见;并覆盖取消与「只能作废重建」的约束。
2. 已确认决策
| # | 决策 | 选择 |
|---|---|---|
| D1 | 单据域 | 新建 PL 主从表:入库一套 + 出库一套(对称),不复用地磅表作主单据 |
| D2 | 地磅关系 | 有关联地磅单时,用其数量预填 actual_qty,仍可改;不做双向自动覆盖 |
| D3 | 现场链接 | 免登录公共页;一单一链(多产品同页) |
| D4 | 多产品 | 明细各自填实际数量;附件+备注在主表整单共用 |
| D5 | 状态 | in_progress / completed / voided;新建默认进行中;现场首次提交 → 自动已完成;管理端可手动选择进行中/已完成;已作废主要由计划作废写入(管理端也可手动置作废,作废后禁止现场提交)(现场自动完成规则已被 2026-07-19-pl-site-io-order-status-select-design.md 覆盖:现场提交须显式传 status) |
| D6 | 已完成可改 | 已完成仍可继续完善数量/附件/备注 |
| D7 | 归档 | 以入库/出库单为权威,归档只读展示;可选同步到 pl_plan_product |
| D8 | 快照 | 最小快照(兼容作废单历史展示)+ 保留 plan_id / transport_id |
| D9 | 计划冻结 | 安排后完全冻结:不可编辑计划、不提供调整运输;只可作废 → 新建计划再安排 |
| D10 | 菜单 | 一级「运输管理」→ 二级「库存管理」→「入库单」「出库单」 |
| D11 | 直销单 | 不生成入库/出库单 |
3. 菜单与路由
运输管理(PL_MENU_ROOT,既有)
└── 库存管理(新建 M,建议 id: PL_GROUP_STOCK)
├── 入库单(C,perms: pl:inbound:list)
└── 出库单(C,perms: pl:outbound:list)
| 菜单 | 建议 path | component | 路由 Hash(示意) |
|---|---|---|---|
| 库存管理 | stock-module |
— | /#/pl/stock-module/... |
| 入库单 | inbound |
pl/inbound/index |
/#/pl/stock-module/inbound |
| 出库单 | outbound |
pl/outbound/index |
/#/pl/stock-module/outbound |
说明:
- 与既有「地磅出入库」
/#/db/inventory、证件提醒路径pl/inventory/...分离,故二级目录用stock-module,避免与pl_inventory库存台账语义混淆。 - 权限按钮:列表查看、编辑、改状态、复制现场链接(细项实现阶段落库
sys_menu)。 - 角色授权:实现时挂到既有运输相关角色;
super_admin默认可见。
4. 数据模型
4.1 入库主表 pl_inbound_order
| 字段 | 说明 |
|---|---|
id |
VARCHAR(64) UUID |
order_no |
业务单号(如 RK + 日期序号) |
plan_id |
→ pl_plan |
transport_id |
→ pl_transport |
status |
in_progress | completed | voided |
partner_company |
最小快照:往来单位 |
vehicle_no |
最小快照:车牌 |
plan_no |
最小快照:计划号 |
plan_date |
最小快照:计划日期 |
site_access_token |
一单一链,唯一 |
site_feedback_remark |
整单现场备注 |
site_feedback_images |
回执图(逗号分隔 URL 或 JSON,与现现场链路一致) |
site_feedback_time |
最近提交时间 |
site_first_submitted_at |
首次提交时间;用于自动置 completed |
| 公共字段 | tenant_no, order_num, remark, create_by, create_dept_id, create_time, update_by, update_time, del_flag |
4.2 入库明细 pl_inbound_order_item
| 字段 | 说明 |
|---|---|
id |
UUID |
order_id |
→ pl_inbound_order |
plan_product_id |
→ pl_plan_product |
product_id / product_name / specification / unit |
产品快照 |
plan_qty |
安排时计划数量 |
actual_qty |
实际数量(可改) |
qty_source |
plan | dibang | manual |
| 公共字段 | 同规范 |
4.3 出库
pl_outbound_order / pl_outbound_order_item 与上表字段对称(单号前缀 CK)。
4.4 索引建议
(tenant_no, plan_id)、(tenant_no, transport_id)、(tenant_no, status)、site_access_tokenUNIQUE- 明细
(order_id)、(plan_product_id)
4.5 与旧对象
| 对象 | 关系 |
|---|---|
pl_transport_site_link |
新安排不再生成;历史数据只读兼容或后续迁移脚本(实现计划中单列任务) |
db_inbound_outbound |
仍可选「生成地磅」;有关联时预填 actual_qty,不互相覆盖写死 |
pl_plan / pl_transport |
关联键 + 最小快照;列表可跳转计划 |
5. 生命周期
安排运输(入库/出库计划)
→ 创建 1 主表 + N 明细,status=in_progress,生成 token
→ actual_qty 默认 = plan_qty
→ 若有地磅关联产品行 → 预填 actual_qty,qty_source=dibang
现场首次成功提交
→ 写明细 actual_qty + 主表备注/附件
→ site_first_submitted_at 有值则 status → completed(若仍为 in_progress)
管理端
→ 可手动改 status(含 completed ↔ in_progress)
→ 已完成仍可改数量/附件/备注
计划作废
→ 关联未作废的入库/出库单 → voided
→ token 失效(公共页只读提示已作废,禁止提交)
已安排后
→ 禁止编辑计划正文
→ 禁止「调整运输」
→ 纠错路径:作废计划 → 新建计划 → 再安排(新单 + 新链接)
直销单:安排运输不创建入库/出库单(可继续仅司机链接,若现网有)。
6. 接口(示意)
6.1 管理端
GET /api/.../pl/inbound列表GET /api/.../pl/inbound/{id}详情(含 items)PATCH /api/.../pl/inbound/{id}编辑(数量、备注、附件、status)GET /api/.../pl/inbound/{id}/site-url复制现场链接- 出库对称:
/pl/outbound/...
安排运输成功响应中返回:inboundOrder / outboundOrder(含 siteUrl),供安排成功弹窗复制。
作废计划:在现有 cancel 流程中追加作废关联入库/出库单。
6.2 公共页
GET /api/public/pl/inbound/{token}摘要 + 明细POST /api/public/pl/inbound/{token}/feedback提交实际数量(按 item)+ 备注 + 附件- 出库对称
URL 形态:{PUBLIC_WEB_ORIGIN}/#/public/pl/inbound/{token}(出库 /public/pl/outbound/{token})。
7. 前端界面
7.1 列表
- 筛选:单号、计划号、状态、日期、往来单位、车牌等
- 列:单号(主标识链接打开查看/编辑)、状态 Tag、计划号、往来单位、车牌、产品摘要、实际量合计、首次/最近提交时间
- 工具栏:复制现场链接(选中一行)等
- 状态 Tag:
进行中=warning,已完成=success,已作废=info(或 danger,实现时对齐 UI 规范枚举)
7.2 编辑弹窗
- 主表:状态(可选手动改)、快照信息只读、整单备注与附件
- 明细表:计划数量只读、实际数量可编辑
label-position="top",无背景模糊
7.3 现场公共页
- 免登录;布局对齐「一张单编辑」:产品行实际数量 + 底部备注/附件 + 提交
voided:不可提交;completed:仍可再次提交完善
7.4 归档
PlPlanViewTabs/ 归档弹窗:以关联入库/出库单只读展示实际数量、附件、备注- 可选:归档保存时同步
pl_plan_product.actual_qty(及 inbound/outbound 数量字段)
7.5 运输计划
arranged后:隐藏/禁用编辑与「调整运输」;作废入口保留- 安排成功:复制现场链接改为入库/出库单单链(替代按产品多条旧现场 link)
8. 非目标(本期不做)
- 入库/出库与地磅单双向自动覆盖
- 拼车多计划共用一张出入库单
- 强制迁移全部历史
pl_transport_site_link(可后续脚本) - 小程序端入库/出库列表(若未单列需求)
9. 验收要点
| ID | 场景 |
|---|---|
| V1 | 入库计划安排 → 库存管理-入库单可见,状态进行中,有现场链接 |
| V2 | 多产品:一链打开,各产品实际数量独立,备注附件整单 |
| V3 | 有地磅时 actual 预填地磅量,可改 |
| V4 | 现场首次提交 → 已完成;管理端可改回进行中/再改完成 |
| V5 | 已完成后仍可改数量与附件 |
| V6 | 作废计划 → 单作废,链接不可再提交 |
| V7 | 已安排计划不可编辑、无调整运输;须作废重建 |
| V8 | 归档只读看到单上实际数据 |
| V9 | 菜单:运输管理 → 库存管理 → 入库单/出库单 |
| V10 | 直销单不产生入库/出库单 |
10. 实现备注
- DDL 同步
docs/sql/;遵守 database-conventions 公共字段与软删 - 租户隔离、数据权限与现有 PL API 一致
- 字段一致性:
_row_to_dict/ CreateUpdateBody / 前端 form 对齐 - 替代旧现场 link 时,安排运输 API 与前端复制链接 UX 一并切换
11. 决策记录(brainstorm)
- 可视化会话:
.superpowers/brainstorm/下 HTML 选项页 - 方案选型:主从表分离 A;现场公共页 A;一单一链 A;归档权威 A;最小快照 A;计划完全冻结 B