shanxia2.0/docs/db-migration/ref-backend-adapt.md

地磅后端移植适配细则

实施 P0–P4 时加载。与 00-migration-plan.md 配套。
对照 bx：../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 路由参数建单