提交

2026-06-10 22:59:34 +08:00
1 parent 725774ef0c
commit c3be9d1dce
@@ -0,0 +1,222 @@
+# 地磅系统移植设计文档
+
+> **日期**: 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`；状态字段用 `<el-tag>`；按钮带图标；操作列 `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` |
@@ -0,0 +1,27 @@
+# 地磅三表 CRM 产品 ID + 规格 — 设计文档
+
+> **日期**: 2026-06-09  
+> **状态**: 已批准（方案 B + 新建必选 CRM 产品）  
+> **前置**: `docs/superpowers/specs/2026-06-07-dibang-migration-design.md` 方案 A 升级
+
+## 目标
+
+计划、出入库、地磅单三表均存储 `product_id`（`crm_product.id`）与 `specification`（规格快照，来源 `crm_product.model`），新建/编辑时必须从 CRM 选择产品，禁止手输纯文本。
+
+## 字段
+
+| 表 | 新增/补齐 | 保留快照 |
+|---|---|---|
+| `db_purchase_plan` | `product_id` | `product`、`specification` |
+| `db_inbound_outbound` | `product_id`、`specification` | `product` |
+| `db_weighing_slip` | `product_id`、`specification` | `cargo_name` |
+
+不建 DB 外键；服务端按 `tenant_no` 校验 CRM 产品存在且 `status=on`，并用 CRM 数据回填名称与规格。
+
+## 级联
+
+计划 → 出入库 → 地磅：复制 `product_id`、`product`/`cargo_name`、`specification`。自动按月生成计划同步复制。
+
+## 历史数据
+
+已有行 `product_id` 可为 NULL；编辑保存时需重新选择 CRM 产品后方可提交。