2. 供应商目录数据模型设计：核心字段定义

供应商目录是采购管理平台的基础主数据，其数据模型设计的质量直接决定了接口同步的稳定性、查询效率以及后续业务扩展的灵活性。本章将围绕供应商目录的核心字段进行定义与建模，确保字段语义清晰、类型准确、约束完备，为后续的接口同步与错误重试机制奠定坚实的数据基础。

2.1 核心字段总览

供应商目录数据模型包含以下六大类核心字段：标识字段、基础信息字段、状态与等级字段、联系方式字段、资质与财务字段、系统控制字段。下表列出了每个字段的名称、数据类型、长度、约束及说明。

字段分类	字段名称	数据类型	长度	约束	说明
标识字段	supplier_id	VARCHAR	32	PK, NOT NULL	全局唯一供应商ID，由平台生成
	erp_supplier_code	VARCHAR	50	UNIQUE, NOT NULL	ERP侧供应商编码，用于接口映射
基础信息	supplier_name	VARCHAR	200	NOT NULL	供应商法定全称
	short_name	VARCHAR	100		供应商简称，用于界面展示
	unified_social_credit_code	VARCHAR	18	UNIQUE	统一社会信用代码，企业唯一标识
状态与等级	status	TINYINT	1	NOT NULL, DEFAULT 0	0=待审核, 1=已启用, 2=已冻结, 3=已注销
	grade	TINYINT	1	NOT NULL, DEFAULT 3	1=战略级, 2=优选级, 3=普通级, 4=观察级
	cooperation_type	TINYINT	1	NOT NULL	1=正式, 2=试用, 3=一次性
联系方式	contact_person	VARCHAR	50		主要联系人姓名
	contact_phone	VARCHAR	20		手机号或固定电话
	contact_email	VARCHAR	100		企业邮箱
	province / city / district	VARCHAR	50		省/市/区三级地址
资质与财务	taxpayer_type	TINYINT	1	NOT NULL	1=一般纳税人, 2=小规模纳税人
	bank_account_info	VARCHAR	500		JSON格式，含开户行、账号、户名
系统控制	created_at	DATETIME		NOT NULL	记录创建时间
	updated_at	DATETIME		NOT NULL, ON UPDATE	记录最后更新时间
	sync_version	BIGINT		NOT NULL, DEFAULT 0	乐观锁版本号，用于接口同步冲突检测

2.2 状态与等级字段设计详解

状态与等级是供应商目录中业务语义最丰富的字段，直接影响接口同步的过滤逻辑和错误重试策略。

2.2.1 状态枚举（status）

• 0 - 待审核：新注册或信息变更后，需人工审核。接口同步时，该状态的供应商仅同步到中间表，不推送到下游系统。
• 1 - 已启用：审核通过，正常合作。接口同步时，该状态的供应商为全量同步目标。
• 2 - 已冻结：因违规或风险暂停合作。接口同步时，下游系统需标记为不可下单。
• 3 - 已注销：合作关系终止。接口同步时，下游系统需执行软删除或归档操作。

2.2.2 等级枚举（grade）

• 1 - 战略级：核心供应商，享有优先结算、优先采购权。接口同步时，等级字段需作为下游定价策略的输入参数。
• 2 - 优选级：长期合作供应商，享有次优待遇。
• 3 - 普通级：一般供应商，按标准流程处理。
• 4 - 观察级：新引入或绩效不达标供应商，需限制采购额度。

2.3 联系方式字段的规范化设计

联系方式字段在接口同步中容易因格式不一致导致解析失败。建议采用以下规范化策略：

1. 手机号：统一存储为不带国家码的11位数字字符串，前端展示时按需拼接。
2. 邮箱：统一转为小写存储，避免大小写敏感导致的重复数据。
3. 地址：拆分为省/市/区三级独立字段，便于按区域筛选和统计。
4. 多联系人场景：建议使用独立的 supplier_contact 子表，通过 supplier_id 关联，支持1:N扩展。

2.4 数据模型实体关系图

下图展示了供应商目录核心实体及其字段关系，帮助理解数据模型在接口同步中的流转路径。

2.5 接口同步中的字段映射规则

在供应商目录接口同步过程中，平台侧字段与下游系统字段之间需要建立明确的映射关系。以下是常见的映射规则：

• 直接映射：字段名和语义完全一致，如 supplier_name → supplier_name。
• 转换映射：字段值需做格式或枚举转换，如平台侧 status=1 映射为下游系统 status=ACTIVE。
• 组合映射：多个字段组合成一个字段，如 province + city + district 组合为 full_address。
• 忽略字段：平台侧内部字段，如 sync_version，不同步到下游系统。

2.6 数据模型设计的常见避坑指南

常见问题	风险描述	推荐做法
使用VARCHAR存储枚举值	存储空间大，查询性能差，易出现大小写不一致	使用TINYINT + 枚举常量类
联系方式字段过长或过短	手机号截断或邮箱无法存储完整地址	按实际业务场景设置合理长度，手机号20位，邮箱100位
缺少乐观锁版本号	接口并发同步时出现数据覆盖或丢失	必须包含 sync_version 字段，每次更新时递增
地址字段不拆分	按区域统计或筛选时需做字符串解析，效率低	拆分为省/市/区三级独立字段
忽略系统控制字段	无法追踪数据变更历史，排查问题困难	必须包含 created_at、updated_at 和 sync_version

2.7 数据模型在错误重试机制中的角色

供应商目录数据模型中的 sync_version 字段在错误重试机制中扮演关键角色。当接口同步失败并触发重试时，重试请求会携带当前 sync_version 值。下游系统通过比较该值与自身存储的版本号，判断数据是否已被其他请求更新，从而避免“丢失更新”问题。

此外，status 和 grade 字段可作为重试策略的输入参数：

• 对于 已冻结 或 已注销 的供应商，重试时可直接跳过，减少无效请求。
• 对于 战略级 供应商，可设置更高的重试优先级和更短的重试间隔。