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. 结论

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