地磅系统（db）移植实施方案

编写日期：2026-06-07（修订：搬运 + 适配策略）
状态：方案已定稿，旧重写代码已清理，待按阶段实施
源系统：simple-dibang-xiaoshou/backend + simple-dibang-xiaoshou/art-design-pro
目标系统：shanxia2.0/backend + shanxia2.0/web-admin
DDL 基线：docs/sql/db_tables.sql（已写入 docs/sql/shanxia2.0.sql）
对照参考：docs/bx-migration/00-migration-plan.md

1. 迁移目标

将原地磅系统五模块迁入山峡一体化门户，实现：

业务等价：仪表盘、计划、出入库、地磅单、车牌及联动逻辑与原系统一致；
API 契约保持：路径、HTTP 方法、Query 参数、响应 JSON 结构 尽量与原系统一致（直接返回 list[Read] / 实体，不用门户 CRM 的 success_response + data.list）；
体系融合：用户/角色/菜单/认证使用门户 sys_*；业务表使用 db_* + 门户公共字段；
UI 融合：先拷贝 art-design-pro 页面与 *Api.ts，再逐步适配 Fresh Mint（第二阶段）。

不在本次范围：原 auth/users/cargos/companies 独立模块（分别用门户登录、CRM 下拉替代）。

2. 核心原则（对齐 bx「搬运 + 适配」）

原则	说明
Router 近原样复制	从 `simple-dibang-xiaoshou/backend/app/api/routes/` 复制到 `backend/app/api/db/`，仅改 Depends、import、租户、UUID
Service/联动逻辑整段迁移	尤其 `weighing.py` 的 `_process_weighing_business_logic`、`inventory/create-link-for-plan`、`plans/third-party-page`
响应协议保持原样	列表返回数组或 Pydantic Read 模型；禁止改为 `/web/admin/db/*` + 门户 envelope
路径保持原语义	挂载后仍为 `/api/plans`、`/api/weighing` 等（router prefix 不含 `/api`，由 `main.py` 统一加 `API_V1_PREFIX`）
最小改动	不重命名 URL、不改 PATCH→PUT、不删 special endpoints（`related`、`void`、`create-link-for-plan`）
门户能力注入	认证（`db_auth`）、租户、`tenant_no`、DB Session、MinIO 用 shanxia2.0 现有能力
主数据方案 A	产品/客户用 CRM 远程下拉，存名称文本；不建 `cargos`/`companies` 表

与 bx 的差异（勿混淆）

项	bx	地磅 db
响应 envelope	`code:0` + `msg` + `data.rows`	无 envelope，FastAPI 直接返回 JSON
原 ORM	SQLAlchemy sync	SQLModel async → 须改为 sync Session
列表分页	服务端分页	多数列表全量返回，前端筛选/分页

3. 范围边界

3.1 数据库（4 张业务表，DDL 已完成）

表	用途	DDL
`db_vehicle`	车牌	✅ `docs/sql/db_tables.sql`
`db_purchase_plan`	计划	✅
`db_inbound_outbound`	出入库	✅
`db_weighing_slip`	地磅单	✅

3.2 后端 API（移植清单见 `01-api-inventory.md`）

模块	源文件	原 prefix	优先级
车牌	`routes/vehicles.py`	`/vehicles`	P1
计划	`routes/plans.py`	`/plans`	P1
出入库	`routes/inventory.py`	`/inventory`	P2
地磅单	`routes/weighing.py`	`/weighing`	P2（含联动）
仪表盘	`routes/dashboard.py`	`/dashboard`	P3

不移植：auth.py、users.py、cargos.py、companies.py。

3.3 前端页面（拷贝 + 适配）

分组	源路径	目标
计划	`art-design-pro/src/views/plans`	`web-admin/src/views/db/plans`
出入库	`art-design-pro/src/views/inventory`	`web-admin/src/views/db/inventory`
地磅单	`art-design-pro/src/views/weighing`	`web-admin/src/views/db/weighing`
车牌	master-data 车辆 Tab 或 vehicles 页	`web-admin/src/views/db/vehicles`
仪表盘	`art-design-pro/src/views/dashboard`	`web-admin/src/views/db/dashboard`
API	`art-design-pro/src/api/*Api.ts`	`web-admin/src/api/db/*.ts`

4. 目标架构

backend/app/
├── models/db_models.py          # 按 db_tables.sql 重写（非 SQLModel）
├── schemas/db/                  # 从原 schemas 复制 + id→str
├── services/db/                 # 从原 routes 内联逻辑抽出或直接保留在 router（与 bx 一致，优先 router 薄层）
├── core/db_auth.py              # 类比 bx_auth：门户 user → DbUserContext
└── api/db/
    ├── __init__.py              # db_router 聚合
    ├── vehicles.py              # prefix="/vehicles"
    ├── plans.py                 # prefix="/plans"
    ├── inventory.py             # prefix="/inventory"
    ├── weighing.py              # prefix="/weighing"
    └── dashboard.py             # prefix="/dashboard"

# main.py
from app.api.db import db_router
app.include_router(db_router, prefix=settings.API_V1_PREFIX)
# → /api/plans、/api/weighing ...

5. 门户适配层

5.1 认证（`core/db_auth.py`）

原：get_async_session + 无统一门户用户
新：Depends(get_db_current_user)，从 require_admin_or_super_admin 或菜单权限取 tenant_no、user_id、dept_id

5.2 数据模型改造

原	新
`id: int`	`id: str` UUID
`is_deleted`	`del_flag`
`created_at: str`	`create_time: datetime`
无租户	`tenant_no` 必填
`remarks`	`remark`（门户公共字段）

5.3 async → sync

原系统使用 SQLModel AsyncSession；门户使用同步 Session。搬运时：

await session.exec(select(...)) → db.query(...).filter(...)
await session.commit() → db.commit()（在 router 或 service 层统一）

6. 分阶段交付

阶段	内容	验收
P0	ORM + `db_router` 骨架 + `db_auth` + health	`/api/db/health` 或模块 health
P1	vehicles + plans（含 fill-link、third-party-page、related）	端点对照表 P1 全绿
P2	inventory + weighing（含联动、void、related）	计划→地磅→出入库全链路
P3	dashboard 统计 SQL	与原 dashboard 数值一致
P4	定时任务：计划按月自动生成	手动触发成功
P5	sys_menu 菜单 SQL	侧栏五模块可见
P6	前端拷贝 + API 路径对齐	原页面功能可跑通
P6-FM	Fresh Mint UI 换皮	对照 ui-spec

7. 历史数据

脚本：backend/scripts/migrate_dibang_data.py（保留原地磅 int id，写入 VARCHAR(64) 如 "12"；外键同值传递）
主键策略：int → 同值字符串（非 UUID）；purchase_plan_id、inbound_outbound_id、last_weighing_slip_id 随主键一并保留

8. 文档索引

文件	用途
01-api-inventory.md	端点全量清单（防遗漏）
ref-backend-adapt.md	Router/Service 改造检查清单
module-status.md	实施进度
../superpowers/specs/2026-06-07-dibang-migration-design.md	业务设计（方案 A、联动、单位）

9. 已废弃方案说明

2026-06-07 前曾按「门户 CRM 式 CRUD 重写」实现过 /api/web/admin/db/* 路由与 Fresh Mint 新页面，已全部删除。后续实施必须以本文档与 01-api-inventory.md 为准。

00-migration-plan.md 7.4 KB Historie Surový