# 地磅系统 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` | ✅ |