# 地磅系统移植设计文档 > **日期**: 2026-06-07 > **状态**: 已批准(方案 A) > **源系统**: `simple-dibang-xiaoshou`(Python FastAPI + art-design-pro) > **目标系统**: `shanxia2.0`(Python FastAPI + web-admin Fresh Mint) --- ## 1. 背景与目标 ### 1.1 背景 CRM、报销(bx)业务已迁入 shanxia2.0 一体化门户。原地磅系统(`docs/sql/dibang.sql`)仍为独立部署,与门户用户体系、主数据割裂。目标是将地磅核心业务迁入本仓库,统一认证、租户与 UI 规范。 ### 1.2 移植模块(用户确认) | 模块 | 原前端路径 | 说明 | |------|-----------|------| | 仪表盘 | `views/dashboard/console` | 统计概览 | | 计划管理 | `views/plans` | 含按月自动生成 | | 出入库管理 | `views/inventory` | 与地磅单联动 | | 地磅单管理 | `views/weighing` | 核心业务 | | 车牌号 | `views/master-data` 车辆 Tab | 仅车辆 CRUD | ### 1.3 不移植 | 原模块 | 替代方案 | |--------|---------| | 基础资料-往来单位 | 下拉读 `crm_customer`,存客户名称文本 | | 基础资料-货物 | 下拉读 `crm_product`,存产品名称文本 | | 用户管理 / 独立登录 | 门户 `sys_user` + 菜单权限 | | `cargos` / `companies` 表 | 不建表 | --- ## 2. 设计决策 | 决策点 | 结论 | 理由 | |--------|------|------| | 主数据关联 | **方案 A**:仅存名称文本,不做 FK | 与原系统一致;产品/客户名称存在历史不一致 | | 表前缀 | `db_*` | 与 `bx_*`、`crm_*` 域隔离 | | 主键 | `VARCHAR(64) UUID` | database-conventions | | 软删除 | `del_flag`;地磅作废保留 `is_voided` | 作废是业务态,非物理删除 | | 后端子域 | `app/api/db/`、`app/services/db/` | 参照 bx 子域模式 | | ORM | SQLAlchemy 同步 Session | 与门户一致(非原地磅 SQLModel async) | | 鉴权 | 门户 admin JWT + 菜单权限 | 不复用原地磅 auth | | 租户 | 所有查询/写入带 `tenant_no` | api-conventions | | 前端 UI | Fresh Mint + P02 复杂列表模板 | 参照 `/#/demo/order` | | 历史数据 | 独立迁移脚本 int→UUID 映射 | 生产 dibang-test 库需可导入 | --- ## 3. 数据模型 ### 3.1 新建表(4 张) ``` db_purchase_plan ← purchase_plans db_weighing_slip ← weighing_slips db_inbound_outbound ← inbound_outbound db_vehicle ← vehicles ``` ### 3.2 公共字段(每张业务表末尾) ```sql `tenant_no` VARCHAR(64) NOT NULL DEFAULT 'shanxia2.0', `order_num` INT DEFAULT NULL, `remark` VARCHAR(512) DEFAULT NULL, `create_by` VARCHAR(64) DEFAULT NULL, `create_dept_id` VARCHAR(64) NOT NULL DEFAULT '', `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, `update_by` VARCHAR(64) DEFAULT NULL, `update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, `del_flag` SMALLINT NOT NULL DEFAULT 0 ``` ### 3.3 字段规范改造对照 | 原字段 | 新字段 | 说明 | |--------|--------|------| | `id` INT AUTO_INCREMENT | `id` VARCHAR(64) | UUID | | `is_deleted` | `del_flag` | 0/1 | | `remarks` | `remark` | 公共字段名 | | `created_at` VARCHAR | `create_time` DATETIME | 规范时间类型 | | `purchase_plan_id` INT | `purchase_plan_id` VARCHAR(64) | 关联 ID | | `inbound_outbound_id` INT | `inbound_outbound_id` VARCHAR(64) | 关联 ID | | `last_weighing_slip_id` INT | `last_weighing_slip_id` VARCHAR(64) | 关联 ID | | `plan_date`/`start_date`/`end_date` VARCHAR | DATE 或 DATETIME | 按语义升级 | | `executed_at` VARCHAR | DATETIME | 执行时间 | | `is_voided` | 保留 | 地磅单作废标记 | **业务字段名保持不变**:`plan_no`、`execution_status`、`batch_no`、`vehicle_no`、`cargo_name`、`partner_company` 等。 ### 3.4 主数据映射(方案 A) | 业务字段 | 表单控件 | 存储 | |---------|---------|------| | `product` / `cargo_name` | CRM 产品远程搜索下拉 | 选中项的 `product_name` 文本 | | `customer_name` / `partner_company` / `supplier` / `consignee` | CRM 客户远程搜索下拉 | 选中项的 `customer_name` 文本 | | `vehicle_no` | `db_vehicle` 下拉或手工输入 | 车牌文本 | --- ## 4. 业务链路(须原样保留) ``` 保存地磅单 → 计算净重/本次量 → 更新 db_purchase_plan.executed_quantity、execution_status、last_weighing_slip_id → 创建或更新 db_inbound_outbound → 回写 purchase_plan_id、inbound_outbound_id 作废地磅单 (is_voided=1) → 回滚计划已执行量(若已计入) → 联动出入库单状态 计划 auto_generate_enabled=1 → APScheduler 定时任务按月复制生成新计划(原 auto-create-plan 脚本逻辑) ``` **单位约定(勿改)**:计划/出入库 `planned_quantity`、`quantity` 为 **吨(t)**;地磅重量字段为 **kg**;`executed_quantity` 为 **kg**。 --- ## 5. 后端架构 ``` backend/app/ ├── models/db_models.py # DbPurchasePlan, DbWeighingSlip, DbInboundOutbound, DbVehicle ├── schemas/db/ # CreateBody / UpdateBody / Response ├── services/db/ │ ├── base.py # DbCrudService(参照 BxCrudService) │ ├── plan.py │ ├── weighing.py # 含联动事务 │ ├── inventory.py │ ├── vehicle.py │ └── dashboard.py ├── api/db/ │ ├── __init__.py # db_router │ ├── plan.py │ ├── weighing.py │ ├── inventory.py │ ├── vehicle.py │ └── dashboard.py └── tasks/db_auto_plan.py # 按月自动生成计划 ``` **路由注册**:`app/main.py` 增加 `db_router`,前缀 `/api/admin/db/`(或 `/api/web/admin/db/`,与现有 admin 路由一致)。 **CRM 只读依赖**:计划/地磅/出入库表单调用已有 CRM 产品、客户列表 API,不新建 cargos/companies 路由。 --- ## 6. 前端架构 ``` web-admin/src/ ├── api/db/ │ ├── plan.ts │ ├── weighing.ts │ ├── inventory.ts │ ├── vehicle.ts │ └── dashboard.ts └── views/db/ ├── dashboard/index.vue # 工作台统计 ├── plan/index.vue # P02 ├── inventory/index.vue # P02 ├── weighing/index.vue # P02 + 表单弹窗 └── vehicle/index.vue # P01 ``` **菜单**:侧栏新增「地磅管理」一级菜单,子菜单:仪表盘、计划管理、出入库管理、地磅单管理、车牌管理。 **UI 规范**:`docs/web-admin-ui-spec-fresh-mint.md`;状态字段用 ``;按钮带图标;操作列 `fixed="right"`。 --- ## 7. 数据迁移 1. 自 `dibang.sql` / 生产库导出四表数据 2. 脚本生成 UUID,维护 `legacy_id → new_id` 映射表 3. 重写 `purchase_plan_id`、`inbound_outbound_id`、`last_weighing_slip_id` 外键 4. 补 `tenant_no='shanxia2.0'` 及公共字段 5. CRM 客户/产品:仅保证下拉可选;历史文本名称不强制对齐 CRM 主数据 --- ## 8. 分阶段交付 | 阶段 | 内容 | |------|------| | P1 SQL | 4 张 `db_*` DDL 写入 `docs/sql/` 并合并 `shanxia2.0.sql` | | P2 后端 | vehicle → plan → inventory → weighing → dashboard → 定时任务 | | P3 前端 | 同上顺序 + CRM 下拉 | | P4 迁移 | 历史数据脚本 + 菜单权限 SQL | | P5 验收 | 计划→地磅→出入库全链路 + 看板 | --- ## 9. 风险 | 风险 | 缓解 | |------|------| | 产品/客户名称与 CRM 不一致 | 方案 A 存文本;下拉仅辅助录入 | | int→UUID 关联断裂 | 迁移脚本维护映射表并校验 | | 联动逻辑回归 | 对照原 `weighing.py` 逐场景验收 | | ecosystem-landscape 冲突 | OpenSpec 更新地磅归属为本仓库 | --- ## 10. 参考源码 | 用途 | 路径 | |------|------| | 原 DDL | `docs/sql/dibang.sql` | | 原后端 | `simple-dibang-xiaoshou/backend/app/` | | 原前端 | `simple-dibang-xiaoshou/art-design-pro/src/views/` | | bx 移植参考 | `backend/app/api/bx/`、`backend/app/services/bx/` | | CRM 产品/客户 API | `backend/app/api/crm.py` | | UI 模板 | `web-admin/src/views/system/order/index.vue` |