huang
d309951493
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 6m33s
- 删除 CSV 解析代码，新增 Excel 解析器 (excelize) - 更新 IoT 卡和设备导入任务处理器 - 更新 API 路由文档和前端接入指南 - 归档变更到 openspec/changes/archive/ - 同步 delta specs 到 main specs
64 lines
2.8 KiB
Markdown
64 lines
2.8 KiB
Markdown
# 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会返回友好错误提示
|