## Context

原地磅系统源码位于 `simple-dibang-xiaoshou`（FastAPI + SQLModel async + art-design-pro），DDL 快照为 `docs/sql/dibang.sql`。shanxia2.0 已具备 CRM 产品/客户主数据、统一用户权限、报销 bx 子域移植先例。用户确认采用方案 A（主数据仅存名称文本）及五模块移植范围。

**原系统核心表关系**：`db_weighing_slip` → `db_purchase_plan` → `db_inbound_outbound`，保存地磅单时在同一事务内更新计划执行量并生成出入库单。

## Goals / Non-Goals

**Goals:**

- 4 张 `db_*` 表符合 database-conventions（UUID、tenant_no、del_flag、create_time 等）
- 完整移植五模块业务功能及地磅→计划→出入库联动
- 计划按月自动生成定时任务
- web-admin Fresh Mint UI + 菜单权限
- 历史数据可迁移脚本

**Non-Goals:**

- 不移植 cargos/companies/users 表及对应 CRUD 页
- 不引入 product_id/customer_id 外键（方案 A）
- 不做小程序端地磅页面（本期仅 web-admin）
- 不改造 CRM 产品/客户模块本身
- 不保留原地磅独立登录与 JWT 体系

## Decisions

### D1: 表前缀 `db_*` 与子域 `app/api/db/`

**选择**: 业务表 `db_purchase_plan` 等，代码子域 `db`（非 `dibang` 缩写混用）  
**理由**: 与 `bx_*`、`crm_*` 命名一致；路由 `/api/.../db/` 简短  
**替代**: 表名保留 `purchase_plans` → 违反门户命名规范，弃用

### D2: 主数据方案 A — 文本冗余

**选择**: 业务表继续存 `product`/`cargo_name`/`customer_name` 等 varchar；表单从 CRM 下拉选中后写入名称  
**理由**: 与原系统行为一致；避免 CRM 与地磅历史名称不一致导致迁移失败  
**替代**: 加 FK 字段 → 改动大、历史数据对齐成本高，用户已拒绝

### D3: 后端参照 bx 子域而非照搬 SQLModel async

**选择**: SQLAlchemy 同步 Session + `DbCrudService` 基类 + 门户 `{ code, data, message }` 响应  
**理由**: 与 shanxia2.0 主栈一致；bx 已验证该模式  
**替代**: 保留 async SQLModel → 与门户 middleware/CRUD 模式割裂

### D4: 地磅作废保留 `is_voided` 字段

**选择**: 除 `del_flag` 外保留 `is_voided`  
**理由**: 作废是业务操作（可回滚计划量），与软删除语义不同；原系统已有此区分  
**替代**: 合并为 status 枚举 → 需大范围改前端逻辑，本期不采用

### D5: 前端按 P02 复杂列表 + order 模板页

**选择**: 计划/出入库/地磅单参照 `views/system/order/index.vue`；车辆参照 `unit/index.vue`  
**理由**: ui-conventions 模板页要求；原 art-design-pro 样式不可直接复用  
**替代**: 复制 art-design-pro 页面 → 违反 Fresh Mint 规范

### D6: 定时任务迁入 APScheduler

**选择**: `app/tasks/db_auto_plan.py`，在 `init_scheduled_tasks` 注册  
**理由**: 门户已有 APScheduler；原独立 cron 脚本可退役  
**替代**: 保留 shell cron → 运维分散，弃用

## Risks / Trade-offs

- **[名称不一致]** CRM 下拉与历史文本可能不匹配 → 允许手工输入；迁移不强制关联 CRM id
- **[联动回归]** weighing 保存逻辑复杂 → 移植时逐函数对照原 `weighing.py`；验收用原库样例数据
- **[ID 迁移]** int→UUID 关联易错 → 迁移脚本输出映射 CSV 并做 count 校验
- **[单位混用]** t vs kg → 文档与代码注释明确；禁止「优化」换算逻辑
- **[ecosystem 文档]** 归档前需更新 landscape spec → 本 change 含 delta

## Migration Plan

1. 执行 DDL 创建 `db_*` 表（空库可开发联调）
2. 部署后端 db 子域 + 前端页面（菜单权限 SQL）
3. 运行历史数据迁移脚本导入生产数据
4. 并行运行：原系统只读对照验收 1–2 周
5. 切换 DNS/入口至门户；退役原 backend 与 art-design-pro
6. **回滚**: 保留原库快照；门户侧 feature flag 关闭地磅菜单

## Open Questions

- （已关闭）主数据 FK vs 文本 → **方案 A 已确认**
- 生产切换窗口与是否双写：实施阶段与业务方确认