8.9 KiB
8.9 KiB
地磅业务明细清单（shanxia2.0 现状）
版本：v1.0
日期：2026-06-10
依据：docs/sql/shanxia2.0.sql、docs/db-migration/module-status.md、backend/app/api/db/、web-admin/src/views/db/
源系统：simple-dibang-xiaoshou（独立地磅 Web + 后端），策略为原样搬运 + 门户适配
1. 模块定位
地磅模块负责仓库侧过磅执行：维护过磅计划、出入库单、地磅单（毛/皮/净重）、车牌，并提供统计仪表盘。表前缀 db_*。
重要区分：本模块的 db_purchase_plan（地磅计划）与运输计划新业务 plan_*（合同驱动、SXDDH 编号）不是同一概念。前者源于原地磅系统；后者待在 shanxia2.0 新建。
与运输计划的关系：运输计划在「待入库/待出库」节点应触发或关联本模块的出入库单与地磅单；现场人员/司机填写、磅差回写等执行能力可复用现有联动逻辑。
2. 技术实现
| 项 | 说明 |
|---|---|
| 后端入口 | backend/app/api/db/（plans、inventory、weighing、vehicles、dashboard） |
| 路由聚合 | backend/app/api/db/__init__.py → db_router |
| 认证 | app/core/db_auth.py（对接门户 JWT） |
| 模型 | backend/app/models/db_models.py |
| 服务 | backend/app/services/db/（含地磅联动 _process_weighing_business_logic） |
| 定时任务 | app/tasks/db_auto_plan.py — 每月 1 日 01:30 自动生成计划 |
| 前端 | web-admin/src/views/db/、web-admin/src/api/db/ |
| API 前缀 | /api/plans、/api/inventory、/api/weighing、/api/vehicles、/api/dashboard |
| 响应协议 | 直接 JSON（无 code:0 envelope），列表多为全量返回 |
| 主数据 | 产品/客户不建本地表，使用 CRM API + 存名称/product_id |
3. 数据表清单（5 张）
| 表名 | 说明 |
|---|---|
db_vehicle |
车牌号主数据（仅车牌 + 备注，字段极简） |
db_purchase_plan |
地磅计划（入库/出库、计划量、执行状态） |
db_inbound_outbound |
出入库单 |
db_weighing_slip |
地磅单（过磅记录） |
db_sequence |
租户业务序号（如出入库批次号） |
公共字段：id、tenant_no、order_num、remark、create_by、create_dept_id、create_time、update_by、update_time、del_flag。
4. 业务模块明细
4.1 仪表盘（/db/dashboard）
| 端点 | 说明 |
|---|---|
GET /api/dashboard/stats |
概览统计 |
GET /api/dashboard/inbound/by-cargo |
入库按货物 |
GET /api/dashboard/inbound/by-partner-cargo |
入库按往来单位+货物 |
GET /api/dashboard/outbound/by-cargo |
出库按货物 |
GET /api/dashboard/outbound/by-partner-cargo |
出库按往来单位+货物 |
4.2 地磅计划（db_purchase_plan，/db/plans）
| 能力 | 说明 |
|---|---|
| 列表/详情/新增/更新/删除 | 标准 CRUD |
| 关联查询 | GET /plans/{id}/related — 关联出入库、地磅单 |
| 三方填写页 | GET /plans/{id}/third-party-page — 司机/现场 H5 数据 |
| 填充链接 | 列表含 fillLinkInventoryId 等扩展字段 |
| 按月自动生成 | POST /plans/run-auto-generate；定时任务 db_auto_generate_monthly_plans |
核心字段：
| 字段 | 说明 |
|---|---|
plan_no |
计划号，格式 SX-YYYYMMDDMMHHSS001 |
business_type |
入库 / 出库 |
product_id |
关联 crm_product.id |
product / specification |
产品名称、规格快照 |
planned_quantity |
计划数量（吨） |
customer_name |
往来单位 |
vehicle_no |
车牌 |
execution_status |
待入库/待出库、入库中/出库中、已入库/已出库、已超额等 |
executed_quantity |
已执行量（kg） |
auto_generate_enabled |
是否按月自动生成 |
start_date / end_date |
计划有效期 |
列表筛选 Query：q、businessType、executionStatus、createdFrom/To、startDateFrom/To。
4.3 出入库管理（db_inbound_outbound，/db/inventory）
| 能力 | 说明 |
|---|---|
| CRUD | 列表、详情、新增、更新、删除 |
| 按计划预生成 | POST /inventory/create-link-for-plan — 生成三方填写单 |
| 关联查询 | GET /inventory/{id}/related |
| 列表增强 | 含地磅重量相关字段 |
核心字段：
| 字段 | 说明 |
|---|---|
date |
业务日期 |
partner_company |
往来单位 |
business_type |
入库 / 出库 |
product_id / product / specification |
产品 |
quantity |
本次量（t） |
plan_no / purchase_plan_id |
关联计划 |
batch_no |
批次号（db_sequence 生成） |
vehicle_no |
车牌 |
status |
待入库/待出库、已完成等 |
列表筛选：q、dateFrom/To、status、businessType。
4.4 地磅单管理（db_weighing_slip，/db/weighing）
| 能力 | 说明 |
|---|---|
| CRUD | 新增/更新时触发业务联动 |
| 作废 | POST /weighing/{id}/void — 作废并回滚联动 |
| 关联查询 | GET /weighing/{id}/related |
核心字段：
| 字段 | 说明 |
|---|---|
vehicle_no |
车号 |
plan_no / purchase_plan_id |
关联计划 |
inbound_outbound_id |
关联出入库单 |
cargo_name / specification / product_id |
货物 |
business_type |
入库 / 出库 |
supplier / consignee |
供货单位 / 收货单位 |
gross_weight / tare_weight / net_weight |
毛重/皮重/净重（kg） |
gross_weight_time / tare_weight_time |
过磅时间 |
deduction |
扣杂（kg） |
planned_quantity / executed_quantity / current_quantity |
计划量/执行量/本次量（kg） |
batch_no |
批次号 |
weighing_point |
称重点（默认「山峡地磅」） |
is_voided |
是否作废 |
联动逻辑（必须在 service 层保持完整）：
- 新建/更新地磅单 → 回写出入库单数量、计划执行状态与已执行量；
- 作废 → 反向回滚。
列表筛选：dateFrom/To、vehicleNo、cargoName、businessType。
4.5 车牌管理（db_vehicle，/db/vehicles）
| 能力 | 说明 |
|---|---|
| CRUD | 列表、详情、新增、全量/部分更新、软删除 |
| 字段 | 仅 vehicle_no + 备注 |
说明：运输计划中的「自有车辆/运输公司车辆」字段更丰富（见 docs/sql/vehicle_management.sql），不宜仅用 db_vehicle 作为唯一车辆库。
5. 前端菜单（sys_menu）
| 菜单 | 路径 | 权限 |
|---|---|---|
| 地磅管理 | /db |
— |
| 仪表盘 | /db/dashboard |
db:dashboard:list |
| 计划管理 | /db/plans |
db:plan:list + 增删改查按钮权限 |
| 出入库管理 | /db/inventory |
db:inventory:list |
| 地磅单管理 | /db/weighing |
db:weighing:list |
| 车牌管理 | /db/vehicles |
db:vehicle:list |
6. 业务闭环（现状）
地磅计划(db_purchase_plan)
│
├──► 出入库单(create-link-for-plan / 手工)
│ │
│ └──► 地磅单(过磅) ──联动──► 回写计划执行状态/已执行量
│
└──► 三方填写页(司机/现场，免登录或受限访问)
按月自动计划：适用于固定客户/产品的周期性入库或出库场景，与原系统行为一致。
7. 不移植项及替代
| 原系统模块 | 替代方案 |
|---|---|
auth / users |
门户登录 + sys_user |
cargos |
CRM 产品 API，product_id + 名称快照 |
companies |
CRM 客户 API，存 customer_name / partner_company 文本 |
8. 移植完成度
| 阶段 | 内容 | 状态 |
|---|---|---|
| DDL | 4+1 张表 | ✅ |
| P0 | ORM + db_router + db_auth | ✅ |
| P1 | vehicles + plans | ✅ |
| P2 | inventory + weighing（含联动） | ✅ |
| P3 | dashboard | ✅ |
| P4 | 计划自动生成定时任务 | ✅ |
| P5 | sys_menu | ✅ |
| P6 | 前端拷贝 + 适配 | ✅ |
| P6-FM | Fresh Mint 换皮 | ✅ |
| P7 | 历史数据迁移脚本 | ✅ |
9. 与运输计划集成的改造点（待建）
| 项 | 现状 | 目标 |
|---|---|---|
| 计划来源 | db_purchase_plan 手工/按月生成 |
由 plan_order 在待入出库时触发 |
| 计划编号 | SX-... |
统一关联运输计划 SXDDH... |
| 三方二维码 | 地磅计划维度 | 扩展为运输计划维度（司机/现场分角色） |
db_purchase_plan 去留 |
与运输计划并存易混淆 | 需产品决策：废弃、只读历史或映射 |
10. 参考路径
| 文档/代码 | 路径 |
|---|---|
| 移植方案 | docs/db-migration/00-migration-plan.md |
| API 清单 | docs/db-migration/01-api-inventory.md |
| 模块状态 | docs/db-migration/module-status.md |
| 产品 ID 设计 | docs/superpowers/specs/2026-06-09-db-product-id-design.md |
| SQL | docs/sql/shanxia2.0.sql（db_* 段） |