提交

2026-06-10 22:59:34 +08:00
1 parent 725774ef0c
commit c3be9d1dce
@@ -0,0 +1,170 @@
+# 地磅系统（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`](../bx-migration/00-migration-plan.md)
+
+---
+
+## 1. 迁移目标
+
+将原地磅系统五模块迁入山峡一体化门户，实现：
+
+1. **业务等价**：仪表盘、计划、出入库、地磅单、车牌及联动逻辑与原系统一致；
+2. **API 契约保持**：路径、HTTP 方法、Query 参数、响应 JSON 结构 **尽量与原系统一致**（直接返回 `list[Read]` / 实体，**不用**门户 CRM 的 `success_response` + `data.list`）；
+3. **体系融合**：用户/角色/菜单/认证使用门户 `sys_*`；业务表使用 `db_*` + 门户公共字段；
+4. **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"
+```
+
+```python
+# 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](./01-api-inventory.md) | 端点全量清单（防遗漏） |
+| [ref-backend-adapt.md](./ref-backend-adapt.md) | Router/Service 改造检查清单 |
+| [module-status.md](./module-status.md) | 实施进度 |
+| [../superpowers/specs/2026-06-07-dibang-migration-design.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` 为准。
@@ -0,0 +1,108 @@
+# 地磅系统 API 全量清单（移植后路径保持不变）
+
+> 源：`simple-dibang-xiaoshou/backend/app/api/routes/` + `art-design-pro/src/api/*Api.ts`  
+> 挂载：门户 `API_V1_PREFIX=/api` + router prefix（**不含** `/api` 前缀）  
+> 响应：**直接 JSON**（非 bx 的 `code:0` envelope，非 CRM 的 `success_response`）
+
+实施时在「门户状态」列打勾。
+
+---
+
+## 车牌 `/api/vehicles`
+
+| 方法 | 路径 | 说明 | 门户状态 |
+|------|------|------|----------|
+| GET | `/api/vehicles/` | 列表 | ⬜ |
+| GET | `/api/vehicles/{vehicle_id}` | 详情 | ⬜ |
+| POST | `/api/vehicles/` | 新增 | ⬜ |
+| PUT | `/api/vehicles/{vehicle_id}` | 全量更新 | ⬜ |
+| PATCH | `/api/vehicles/{vehicle_id}` | 部分更新 | ⬜ |
+| DELETE | `/api/vehicles/{vehicle_id}` | 软删除 | ⬜ |
+
+---
+
+## 计划 `/api/plans`
+
+| 方法 | 路径 | 说明 | 门户状态 |
+|------|------|------|----------|
+| GET | `/api/plans/` | 列表（含 `fillLinkInventoryId`） | ⬜ |
+| POST | `/api/plans/` | 新增 | ⬜ |
+| GET | `/api/plans/{id}` | 详情 | ⬜ |
+| PATCH | `/api/plans/{id}` | 更新 | ⬜ |
+| DELETE | `/api/plans/{id}` | 软删除 | ⬜ |
+| GET | `/api/plans/{id}/related` | 关联出入库/地磅 | ⬜ |
+| GET | `/api/plans/{id}/third-party-page` | 三方填写页数据 | ⬜ |
+| POST | `/api/plans/run-auto-generate` | 手动触发按月自动生成（`?force=true` 跳过每月1日限制） | ✅ |
+
+**定时任务**：APScheduler `db_auto_generate_monthly_plans` — 每月 1 日 01:30 执行（逻辑同 `run-auto-generate`）
+
+**列表 Query（须保留）**：`q`、`businessType`、`executionStatus`、`createdFrom`、`createdTo`、`startDateFrom`、`startDateTo`
+
+---
+
+## 出入库 `/api/inventory`
+
+| 方法 | 路径 | 说明 | 门户状态 |
+|------|------|------|----------|
+| GET | `/api/inventory/` | 列表（含地磅重量字段） | ⬜ |
+| POST | `/api/inventory/` | 新增 | ⬜ |
+| POST | `/api/inventory/create-link-for-plan` | 按计划预生成三方填写单 | ⬜ |
+| GET | `/api/inventory/{id}` | 详情 | ⬜ |
+| PATCH | `/api/inventory/{id}` | 更新 | ⬜ |
+| DELETE | `/api/inventory/{id}` | 软删除 | ⬜ |
+| GET | `/api/inventory/{id}/related` | 关联计划/地磅 | ⬜ |
+
+**列表 Query**：`q`、`dateFrom`、`dateTo`、`status`、`businessType`
+
+---
+
+## 地磅单 `/api/weighing`
+
+| 方法 | 路径 | 说明 | 门户状态 |
+|------|------|------|----------|
+| GET | `/api/weighing/` | 列表（含 `inventoryDate`） | ⬜ |
+| POST | `/api/weighing/` | 新增 + 联动 | ⬜ |
+| GET | `/api/weighing/{id}` | 详情 | ⬜ |
+| PATCH | `/api/weighing/{id}` | 更新 + 联动 | ⬜ |
+| POST | `/api/weighing/{id}/void` | 作废 + 回滚 | ⬜ |
+| DELETE | `/api/weighing/{id}` | 作废式删除 | ⬜ |
+| GET | `/api/weighing/{id}/related` | 关联计划/出入库 | ⬜ |
+
+**列表 Query**：`dateFrom`、`dateTo`、`vehicleNo`、`cargoName`、`businessType`
+
+**联动（必须在 service 层完整迁移）**：`_process_weighing_business_logic`
+
+---
+
+## 仪表盘 `/api/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` | 出库按往来单位+货物 | ✅ |
+
+---
+
+## 不移植（替代方案）
+
+| 原模块 | 原 prefix | 替代 |
+|--------|-----------|------|
+| auth | `/auth` | 门户 `/api/web/auth/login` |
+| users | `/users` | `sys_user` |
+| cargos | `/cargos` | CRM 产品 API |
+| companies | `/companies` | CRM 客户 API |
+
+---
+
+## 前端 API 文件对照
+
+| 源文件 | 目标 | 状态 |
+|--------|------|------|
+| `plansApi.ts` | `web-admin/src/api/db/plans.ts` | ✅ |
+| `inventoryApi.ts` | `web-admin/src/api/db/inventory.ts` | ✅ |
+| `weighingApi.ts` | `web-admin/src/api/db/weighing.ts` | ✅ |
+| `dashboardApi.ts` | `web-admin/src/api/db/dashboard.ts` | ✅ |
+| vehicles（masterDataApi 部分） | `web-admin/src/api/db/vehicles.ts` | ✅ |
@@ -0,0 +1,44 @@
+# 地磅（db）模块移植状态跟踪表
+
+> 策略：**原样搬运 + 门户适配**（见 [00-migration-plan.md](./00-migration-plan.md)）  
+> **2026-06-07**：已删除旧「CRM 式重写」代码（`/api/web/admin/db/*` 及对应 web-admin 页面），从零按新方案实施。
+
+---
+
+## 阶段总览
+
+| 阶段 | 内容 | 状态 | 日期 |
+|------|------|------|------|
+| DDL | 4 张 `db_*` 表 | ✅ 已完成 | 2026-06-07 |
+| 旧重写代码 | admin CRUD 路线 | 🗑️ 已删除 | 2026-06-07 |
+| 方案文档 | `docs/db-migration/*` | ✅ 已完成 | 2026-06-07 |
+| P0 | ORM + db_router + db_auth | ✅ 已完成 | 2026-06-07 |
+| P1 | vehicles + plans | ✅ 已完成 | 2026-06-07 |
+| P2 | inventory + weighing（联动） | ✅ 已完成 | 2026-06-07 |
+| P3 | dashboard | ✅ 已完成 | 2026-06-07 |
+| P4 | 计划自动生成定时任务 | ✅ 已完成 | 2026-06-07 |
+| P5 | sys_menu 菜单 SQL | ✅ 已完成 | 2026-06-07 |
+| P6 | 前端拷贝 + 适配 | ✅ 已完成 | 2026-06-07 |
+| P6-FM | Fresh Mint UI 换皮 | ✅ 已完成 | 2026-06-07 |
+| P7 | 历史数据迁移脚本 | ✅ 已完成 | 2026-06-07 |
+
+---
+
+## 后端模块明细
+
+| 模块 | 表 | 后端 | 前端 | 验证 | 备注 |
+|------|-----|------|------|------|------|
+| 车牌 | `db_vehicle` | ✅ | ✅ | — | prefix `/master-data/vehicles`；P6-5 已完成 |
+| 计划 | `db_purchase_plan` | ✅ | ✅ | — | 含 fill-link、third-party、related；P6-2 已完成 |
+| 出入库 | `db_inbound_outbound` | ✅ | ✅ | — | 含 create-link-for-plan；P6-3 已完成 |
+| 地磅单 | `db_weighing_slip` | ✅ | ✅ | — | 含联动 + void；P6-4 已完成 |
+| 仪表盘 | — | ✅ | ✅ | — | 5 个统计端点；P6-1 已完成 |
+
+---
+
+## 不移植项
+
+| 项 | 替代 |
+|----|------|
+| 原地磅 auth/users | 门户登录 + `sys_user` |
+| cargos / companies | CRM 产品/客户 API（方案 A：存名称文本） |
@@ -0,0 +1,63 @@
+# 地磅后端移植适配细则
+
+> 实施 P0–P4 时加载。与 [00-migration-plan.md](./00-migration-plan.md) 配套。  
+> 对照 bx：[../bx-migration/ref-backend-adapt.md](../bx-migration/ref-backend-adapt.md)
+
+---
+
+## 1. 文件复制对照表
+
+| 原地磅源 | shanxia2.0 目标 | 改造程度 |
+|----------|----------------|---------|
+| `app/schemas/*.py` | `schemas/db/*.py` | id→str；字段名对齐 DDL |
+| `app/api/routes/*.py` | `api/db/*.py` | async→sync、Depends、租户 |
+| `app/models/*.py` | `models/db_models.py` | 按 `db_tables.sql` 重写 SQLAlchemy |
+| `app/db/session.py` | **不复制** | 用 `core/database.get_db` |
+| auth/users 路由 | **不复制** | `core/db_auth.py` |
+
+---
+
+## 2. Router 改造检查清单
+
+复制每个 router 后逐项核对：
+
+- [ ] `APIRouter(prefix="/plans")` 等 **保持原 prefix**（不要改成 `/web/admin/db/plans`）
+- [ ] `AsyncSession` / `get_async_session` → `Session` / `get_db`
+- [ ] 鉴权 → `Depends(get_db_current_user)` 或菜单权限
+- [ ] 路径参数 `{id}: int` → `str`（UUID）
+- [ ] **保留 PATCH**（地磅、计划、出入库更新均为 PATCH）
+- [ ] **保留** `POST /{id}/void`、`create-link-for-plan`、`/related`、`third-party-page`
+- [ ] 列表 **仍返回 `list[Read]`** 或原 response_model，**禁止** `success_response({ list })`
+- [ ] 查询默认过滤 `tenant_no` + `del_flag=0`
+- [ ] 写入设置 `create_by`、`create_dept_id`、`tenant_no`
+
+---
+
+## 3. 业务逻辑迁移检查清单
+
+- [ ] `weighing._process_weighing_business_logic` 完整迁移（计划 executed_quantity、出入库 status、累计 executed_quantity）
+- [ ] 地磅 create/update 后调用联动逻辑
+- [ ] void/delete 地磅后重算计划与出入库
+- [ ] `inventory.create-link-for-plan` 生成「待三方填写」出入库单
+- [ ] `plans` 列表附加 `fillLinkInventoryId`
+- [ ] `inventory` 列表附加地磅重量字段（gross/tare/net 等）
+- [ ] dashboard 五条统计 SQL 与原一致
+- [ ] 单位：计划/出入库 quantity 为 **t**，地磅重量为 **kg**，plan.executed_quantity 为 **kg**
+
+---
+
+## 4. Schema 改造检查清单
+
+- [ ] 所有 `id: int` → `str`
+- [ ] `purchase_plan_id` / `inbound_outbound_id` / `last_weighing_slip_id` → `str | None`
+- [ ] camelCase alias 保留（`populate_by_name=True`）
+- [ ] `remarks` → 读写映射到 ORM `remark`（若 DDL 用 remark）
+
+---
+
+## 5. 前端拷贝检查清单
+
+- [ ] 从 `art-design-pro` 拷贝 `*Api.ts`，URL 仍为 `/plans`、`/weighing` 等
+- [ ] `id: number` → `string`
+- [ ] `cargos/companies` 下拉改为 CRM API
+- [ ] 保留：快捷日期、导出 Excel、合计行、关联查看弹窗、`inboundOutboundId` 路由参数建单