IMEI 导入与型号核验·需求文档 V1.0

INTERACTIVE SPEC

方案总览

库管选型号→完成注册→可查厂商回查→只做核验，不改业务型号

● 可进入评审

☰FoneGo Backend / IMEI ManagerWarehouse Admin ▾

新增的 Model verification 是“质量核验结果”；业务流程仍使用库管在导入时选择的 Model。

IMEI	Brand	Selected Model	Model verification	Register	Batch NO	Create Time
86*********1042	OPPO	A3x 4+128GB	Consistent	Success	GH-260909-01	2026-09-09 10:21
86*********4921	vivo	Y19s 6+128GB	Y19s 4+128GB	Success	GH-260909-01	2026-09-09 10:21
35*********8806	TECNO	SPARK 30C 4+128GB	Checking	Success	GH-260909-02	2026-09-09 10:28
86*********3370	Xiaomi	Redmi 14C 4+128GB	Unknown	Success	GH-260909-03	2026-09-09 10:32

01 / PRODUCT DECISION

结论与范围

不再要求系统通过 IMEI 自动决定业务 SKU。库管的型号选择是业务事实，厂商查询是质量校验。

1问题

小米渠道无法返回具体到内存组合的 SKU，导致“注册后自动识别型号”链路无法对四个厂商采用统一逻辑，未识别型号又会影响后续库存和销售流程。

2目标

Add IMEI 和 Upload IMEI 均必选 Model，并传入后端落库。
不以厂商查询成功作为导入成功前提。
OPPO、vivo、传音注册成功后查真实型号并对比；Xiaomi 不查，固定 Unknown。
列表一眼识别一致、不一致和无法核验。

3非目标

本期不自动改写库管选择的型号。
本期不阻断不一致 IMEI 的分配或销售；如需阻断另立策略。
不修改 IMEI Excel 模板的单行结构，型号仍由弹窗统一选择。

1交互

点击 Add IMEI 打开弹窗。
先选 Brand，Model 列表按 Brand + 当前 Biz Line 联动。
Model 必选，保存值为 devModelId，展示完整 SKU（型号 + RAM + ROM）。
输入批次号和 IMEI 后提交，确认框后开始导入。

2校验

Model 为空

不允许提交：“Model cannot be empty”。

型号与品牌不匹配

后端按 devModelId 反查配置，不信任前端字符串，拒绝伪造请求。

3提交体

POST /api/api/devImei/imeiUpload
{ devBrand, devModelId, bizLine, batchNo, imeis }

1交互

与 Add IMEI 共用品牌、型号、批次校验；差异仅在 IMEI 来源为 Excel。一个文件只能对应一个库管选择的 SKU；多 SKU 必须分文件导入。

2文件规则

支持 .xlsx / .xls，只保留最后一个选中文件。
前端以 multipart 上传 file，同时携带 devBrand、devModelId、bizLine、batchNo。
结果继续返回总数、成功数、格式错误、本次重复、历史重复和导入异常。

3提交体

POST /api/api/devImei/imeiUpload/xlsxFile
Content-Type: multipart/form-data
file + devBrand + devModelId + bizLine + batchNo

1新增列

列名建议使用 Model verification（型号核验），紧跟 Selected Model 展示。页面不把“真实型号”叫做 Model，避免两个型号主语混淆。

2展示映射

状态

单元格展示

MATCH

Consistent

MISMATCH

厂商实际 SKU，如 Y19s 4+128GB

UNKNOWN

Unknown（Xiaomi 固定）

PENDING

Checking

QUERY_FAILED

Unknown，鼠标悬停可见失败原因

3对比口径

以 channel_model + RAM + ROM 形成完整 SKU：型号忽略大小写和首尾空格，RAM/ROM 去掉 GB 后按整数精确比较。任一维不同即 MISMATCH。

1主链路

校验 devModelId 存在、启用，且属于所选 devBrand + bizLine。
导入 IMEI，将 devModelId 直接写主表及入库明细；不再先写 -1 等待识别。
异步注册；注册成功先回写 upload_register_status=1。
OPPO / vivo / 传音：异步查询型号，对比后回写核验字段。
Xiaomi：不调查询接口，直接回写 UNKNOWN。

2失败隔离

型号查询失败不得回滚导入或注册结果。查询任务可重试，但只更新“厂商回查/核验”字段，绝不更新 dev_model_id。

3幂等

同一 IMEI 使用分布式锁或状态条件更新；重试时允许 QUERY_FAILED/PENDING 转为 MATCH/MISMATCH，已有有效结果不必重复调厂商。

1现有事实

主表 zeus.config_store_dev_imei 已有 imei、dev_brand、dev_model_id、biz_line、upload_register_status、batch_no 等字段；型号配置来自 zeus.config_dev_model。

2建议新增字段

ALTER TABLE zeus.config_store_dev_imei
ADD model_check_status TINYINT NOT NULL DEFAULT 0
COMMENT '0 pending,1 match,2 mismatch,3 unknown,4 query_failed',
ADD queried_model VARCHAR(128) NULL,
ADD queried_ram INT NULL,
ADD queried_rom INT NULL,
ADD model_query_time INT NOT NULL DEFAULT 0,
ADD model_query_error VARCHAR(255) NULL;

如团队要最小改动，可只增 model_check_status + queried_sku；但会损失结构化排查能力，不推荐。

3列表返回

GET /api/api/devImei/page
新增：modelCheckStatus, queriedSku,
modelQueryTime, modelQueryError

1P0 验收

Add/Upload 未选 Model 时无法提交。
两种导入都把同一 devModelId 送到后端并落库。
注册失败时不调用型号查询。
OPPO/vivo/传音注册成功后进入查询，同 SKU 显示 Consistent，不同则显示厂商真实 SKU。
Xiaomi 注册成功后不产生型号查询请求，显示 Unknown。
查询超时/异常不影响注册成功状态，可后续重试。
任何核验结果都不改写 dev_model_id。

2回归范围

库存统计、分配汇总、销售选机、换机同型号判断、入库明细、Excel 导出，都必须继续使用库管选择的 dev_model_id。

3上线观测

按厂商统计查询成功率和 P95 耗时。
统计 mismatch 率，用于发现供应商错货或库管选错。
监控 pending 超过 30 分钟和 query_failed 连续重试失败。

★主数据决策

dev_model_id = 库管选择的业务 SKU。它用于库存、分配、销售和换机等业务流程，厂商查询结果不得覆盖。

queried_* = 厂商回查事实。它只用于展示、审计和数据质量分析。

!原因

若用厂商结果直接改写 dev_model_id，则小米无法得到 SKU 时仍会回到 -1/Unknown；同时，错货或库管选错会被系统“静默纠正”，失去追责和核验价值。

代码核查基线
operation-bnpl · release/gha/2.1.2.RELEASE · fffb576

已核对主路径
storeImei.vue → storeImei.js → ConfigStoreDevImeiController → ConfigStoreDevImeiServiceImpl → ImeiUploadThread → config_store_dev_imei / stock_in_detail

证据边界
本文档使用本地发布基线与现有库表快照。厂商品牌枚举的精确字符值、传音子品牌映射需在联调前由后端确认。