dingdanquanliucheng/字段映射检查表.md

# 字段映射检查表

> 说明：本文档用于统一《确定版需求说明书》《数据库.sql》《系统标准API文档》的字段命名与口径，便于开发、联调和验收。

---

## 1. 统一字段命名原则

1. 数据库字段采用小写下划线命名。
2. API 字段与数据库字段保持同一语义，优先一致命名。
3. 需求文档中出现的中文业务概念，统一映射到固定英文/拼音字段名。
4. 状态、类型、结果字段统一采用固定枚举值，不允许随意扩展同义字段。
5. 金额字段统一使用 `decimal(18,2)` 口径，百分比统一使用 `decimal(10,4)` 口径。

---

## 2. 核心字段统一映射表

| 业务对象 | 统一字段名 | 数据库字段 | API字段 | 说明 |
| --- | --- | --- | --- | --- |
| 用户ID | `id` | `id` | `user_id` | 用户主键 |
| 用户账号 | `username` | `username` | `username` | 登录账号 |
| 密码哈希 | `password_hash` | `password_hash` | 不返回 | 仅存储 |
| 用户姓名 | `real_name` | `real_name` | `real_name` | 姓名 |
| 手机号 | `mobile` | `mobile` | `mobile` | 手机号 |
| 角色ID | `role_id` | `role_id` | `role_id` | 角色关联 |
| 角色名称 | `role_name` | `role_name` | `role_name` | 角色展示名 |
| 角色编码 | `role_code` | `role_code` | `role_code` | 角色唯一标识 |
| 菜单名称 | `menu_name` | `menu_name` | `menu_name` | 菜单展示名 |
| 菜单路径 | `menu_path` | `menu_path` | `menu_path` | 路由路径 |
| 权限标识 | `permission_code` | `permission_code` | `permission_code` | 按钮/接口权限 |
| 客户姓名 | `customer_name` | `customer_name` | `customer_name` | 客户名 |
| 客户地址 | `address` | `address` | `address` | 地址 |
| 结算方式 | `settlement_type` | `settlement_type` | `settlement_type` | 月结/现结等 |
| 月结天数 | `settlement_days` | `settlement_days` | `settlement_days` | 账期天数 |
| 账期起算口径 | `settlement_start_type` | `settlement_start_type` | `settlement_start_type` | 订单/对账/发货 |
| 客户类型 | `customer_type` | `customer_type` | `customer_type` | 客户分类 |
| 归属业务员ID | `salesman_id` | `salesman_id` | `salesman_id` | 业务员关联 |
| 信用额度 | `credit_limit` | `credit_limit` | `credit_limit` | 金额字段 |
| 欠款金额 | `arrears_amount` | `arrears_amount` | `arrears_amount` | 金额字段 |
| 产品名称 | `product_name` | `product_name` | `product_name` | 产品名 |
| 规格 | `specification` | `specification` | `specification` | 规格 |
| 单位 | `unit` | `unit` | `unit` | 计量单位 |
| 分类 | `category` | `category` | `category` | 产品分类 |
| 成本价 | `cost_price` | `cost_price` | `cost_price` | 金额字段 |
| 售价 | `sale_price` | `sale_price` | `sale_price` | 金额字段 |
| 工厂/供应商名称 | `supplier_name` | `supplier_name` | `supplier_name` | 供应商名称 |
| 工厂/供应商类型 | `supplier_type` | `supplier_type` | `supplier_type` | 工厂/供应商 |
| 订单编号 | `order_no` | `order_no` | `order_no` | 订单唯一编号 |
| 订单来源标签 | `order_source` | `order_source` | `order_source` | 来源字段 |
| 订单状态 | `order_status` | `order_status` | `order_status` | 状态枚举 |
| 发货类型 | `delivery_type` | `delivery_type` | `delivery_type` | 自提/直送等 |
| 销售价总额 | `sale_price_total` | `sale_price_total` | `sale_price_total` | 订单汇总金额 |
| 成本价总额 | `cost_price_total` | `cost_price_total` | `cost_price_total` | 订单汇总金额 |
| 回扣总额 | `rebate_total` | `rebate_total` | `rebate_total` | 订单汇总金额 |
| 运费总额 | `freight_total` | `freight_total` | `freight_total` | 订单汇总金额 |
| 税费总额 | `tax_total` | `tax_total` | `tax_total` | 订单汇总金额 |
| 其他费用总额 | `other_fee_total` | `other_fee_total` | `other_fee_total` | 订单汇总金额 |
| 利润 | `profit_total` | `profit_total` | `profit_total` | 计算结果 |
| 利润率 | `profit_rate` | `profit_rate` | `profit_rate` | 百分比 |
| 任务编号 | `task_no` | `task_no` | `task_no` | 司机任务编号 |
| 任务状态 | `status` | `logistics_task.status` | `status` | 任务状态枚举 |
| 取货地址 | `pickup_address` | `pickup_address` | `pickup_address` | 司机端可见 |
| 送达地址 | `delivery_address` | `delivery_address` | `delivery_address` | 司机端可见 |
| 取件内容 | `pickup_content` | `pickup_content` | `pickup_content` | 司机端可见 |
| 揽货时间 | `pickup_confirmed_at` | `pickup_confirmed_at` | `pickup_confirmed_at` | 时间字段 |
| 送达时间 | `delivered_at` | `delivered_at` | `delivered_at` | 时间字段 |
| 物流节点时间 | `node_time` | `node_time` | `node_time` | 轨迹节点 |
| 物流节点描述 | `node_desc` | `node_desc` | `node_desc` | 轨迹节点 |
| 提醒类型 | `reminder_type` | `reminder_type` | `reminder_type` | 提醒枚举 |
| 提醒状态 | `status` | `system_reminder.status` | `status` | 提醒状态枚举 |
| 审批类型 | `approve_type` | `approve_type` | `approve_type` | 提交/最终/取消 |
| 审批结果 | `approve_result` | `approve_result` | `approve_result` | pass/reject/refuse |
| 审批意见 | `approve_opinion` | `approve_opinion` | `approve_opinion` | 备注信息 |
| 审计结果 | `result` | `result` | `result` | success/fail |
| 配置键 | `config_key` | `config_key` | `config_key` | 配置唯一键 |
| 配置值 | `config_value` | `config_value` | `config_value` | 配置内容 |
| 文件地址 | `file_url` | `file_url` | `file_url` | COS 或下载地址 |
| 图片地址 | `image_url` | `image_url` | `image_url` | AI识别图片 |
| 原始识别结果 | `raw_result` | `raw_result` | `raw_result` | AI原始输出 |
| 修正结果 | `corrected_result` | `corrected_result` | `corrected_result` | 人工修正 |
| 置信度 | `confidence` | `confidence` | `confidence` | AI识别置信度 |
| 业绩统计周期 | `stat_period` | `stat_period` | `stat_period` | 月/季/年 |

---

## 3. 状态字段统一口径

### 3.1 订单状态 `order_status`

统一使用：
- `draft`
- `pending_approve`
- `approved`
- `rejected`
- `pending_factory`
- `pending_driver`
- `accepted`
- `picked_up`
- `delivered`
- `production`
- `shipped`
- `completed`
- `settled`
- `canceled`

### 3.2 任务状态 `logistics_task.status`

统一使用：
- `pending`
- `accepted`
- `picked_up`
- `delivered`
- `canceled`

### 3.3 提醒状态 `system_reminder.status`

统一使用：
- `pending`
- `sent`
- `read`
- `canceled`

### 3.4 欠款状态 `customer_arrears.status`

统一使用：
- `pending`
- `overdue`
- `paid`
- `closed`

### 3.5 审批结果 `approve_result`

统一使用：
- `pass`
- `reject`
- `refuse`

### 3.6 审计结果 `audit_log.result`

统一使用：
- `success`
- `fail`

---

## 4. 三份文档对齐说明

### 4.1 《确定版需求说明书》

- 以业务语义为准，描述规则、流程和权限。
- 字段名以本检查表为统一口径。

### 4.2 《数据库.sql》

- 以本检查表中的数据库字段为准。
- 所有表结构应与统一字段命名一致。

### 4.3 《系统标准API文档》

- 以本检查表中的 API 字段为准。
- API 请求和响应字段应尽量与数据库字段同名同义。

---

## 5. 需要特别注意的字段

1. `status` 是高频字段，在不同表中语义不同，必须结合表名判断，不可混用。
2. `id` 为各表主键统一字段，但对外接口应根据业务对象返回如 `user_id`、`order_id`、`customer_id` 等。
3. 金额类字段统一采用数字型，不使用字符串。
4. 时间类字段统一使用 `datetime` / ISO 时间字符串。
5. 所有快照字段如 `customer_name_snapshot`、`product_name_snapshot` 必须保留历史业务语义，不可用动态关联字段替代。

---

## 6. 结论

本检查表用于统一三份核心文档的字段语义、字段命名和状态口径。后续开发、接口联调、数据库建模均以本文档为准。