csxj2026/junhong_cmp_fiber

Files

构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 6m33s

Details

- 删除 CSV 解析代码，新增 Excel 解析器 (excelize)

- 更新 IoT 卡和设备导入任务处理器

- 更新 API 路由文档和前端接入指南

- 归档变更到 openspec/changes/archive/

- 同步 delta specs 到 main specs

2026-01-31 14:13:02 +08:00

2.8 KiB

Raw Blame History

Proposal: 替换CSV为Excel格式导入

Why

运营团队在使用Excel编辑CSV文件时,超过15位的长数字(ICCID、设备号等)会被Excel自动转换为科学记数法,导致数据损坏无法使用。这种数据损坏问题每次导入都可能发生,给运营团队带来困扰。由于运营团队日常工作习惯使用Excel,直接支持Excel格式(.xlsx)可以从根本上解决这个问题,同时提升用户体验。

What Changes

核心变更:

移除: 删除所有CSV解析相关代码 (pkg/utils/csv.go, csv_test.go)
新增: 添加Excel解析支持 (pkg/utils/excel.go, excel_test.go),使用 excelize 库
修改: 更新IoT卡导入和设备导入的任务处理器,使用Excel解析器替代CSV解析器
更新: API文档描述从"上传CSV文件"改为"上传Excel文件"
约束: 只支持 .xlsx 格式(Excel 2007+),不支持旧版 .xls 格式

不变部分:

数据结构(CardItem, DeviceRow)保持不变
业务逻辑(验证、批量处理、错误处理)保持不变
对象存储集成保持不变
历史导入任务记录保持不变(仅新任务使用Excel)

Capabilities

New Capabilities

无新增功能

Modified Capabilities

device-import: 设备导入功能的文件格式要求从CSV改为Excel(.xlsx)
iot-card-import-task: IoT卡导入功能的文件格式要求从CSV改为Excel(.xlsx)

Impact

代码影响:

pkg/utils/: 删除CSV解析器,新增Excel解析器
internal/task/iot_card_import.go: 修改文件解析逻辑
internal/task/device_import.go: 修改文件解析逻辑
internal/routes/iot_card.go: 更新API文档描述
internal/routes/device.go: 更新API文档描述
测试文件: 更新相关单元测试和集成测试

依赖影响:

新增依赖: github.com/xuri/excelize/v2 (成熟的Go Excel库,18k+ stars)

前端影响:

上传组件的 accept 属性从 * 改为 .xlsx
文件验证逻辑需更新(检查扩展名为.xlsx)
需提供Excel模板文件下载(前端准备静态文件)
用户提示文案更新

运营影响:

正面: 无需担心数据损坏,直接用Excel编辑即可
培训: 需通知运营团队格式变更(但更简单了)
模板: 需提供标准Excel模板文件

兼容性:

历史数据: 历史CSV导入任务记录保持可查询,但不支持重新导入
迁移策略: 开发环境直接切换,无需灰度(无生产数据)
回滚: 如需回滚,恢复CSV代码即可(Git revert)

风险评估:

文件大小: Excel文件比CSV大3-5倍,但对象存储成本影响很小(1万行约3-5MB)
解析性能: excelize性能良好,1万行Excel解析 < 1秒,不影响现有批量处理
格式兼容: 只支持.xlsx,如用户上传.xls会返回友好错误提示

2.8 KiB Raw Blame History