78 lines
3.2 KiB
Markdown
78 lines
3.2 KiB
Markdown
## 核心目标
|
||
- 以最新Excel为数据来源，支持重复导入并覆盖更新
|
||
- 提供手机/电脑可访问的网页，快速查询“名称、进价、卖价、条码”
|
||
|
||
## 功能范围
|
||
- Excel导入：上传或本地选择文件，解析指定工作表与字段
|
||
- 数据存储：结构化入库并做去重/更新（以条码为准）
|
||
- 查询接口：按条码精准查、按名称模糊查
|
||
- 前端页面：响应式单页，支持键盘输入与移动端友好使用
|
||
|
||
## 技术选型
|
||
- 后端：Python + FastAPI（轻量、易部署、带交互式文档）
|
||
- 存储：SQLite（零运维，小型数据量足够；建立索引）
|
||
- Excel解析：pandas + openpyxl（兼容中文列名与格式）
|
||
- 前端：原生HTML/CSS/JS（或轻量库），移动端响应式布局
|
||
|
||
## 数据模型
|
||
- 表：`products`
|
||
- `barcode` TEXT 主键
|
||
- `name` TEXT
|
||
- `purchase_price` REAL
|
||
- `sale_price` REAL
|
||
- 预留字段：`category`、`created_at`、`source_file`
|
||
- 索引：`name`（模糊查询加速）
|
||
|
||
## Excel导入流程
|
||
1. 读取`Sheet1`，识别列名：`名称（必填）`、`进货价（必填）`、`销售价（必填）`、`条码`
|
||
2. 清洗：
|
||
- 去首尾空格、统一类型；进价/卖价转数值
|
||
- 条码为空的行跳过；负库存不入库（如需可扩展）
|
||
3. Upsert策略：以`条码`为主键；存在则更新名称/价格，不存在则插入
|
||
4. 审计：记录导入时间与源文件名
|
||
|
||
## API设计
|
||
- `POST /import` 上传Excel并执行导入，返回导入统计（插入/更新/跳过数）
|
||
- `GET /products/{barcode}` 按条码查询，返回名称/进价/卖价/条码
|
||
- `GET /products?q=关键词&limit=20` 按名称模糊查询，分页
|
||
- `GET /health` 健康检查
|
||
|
||
## 前端设计
|
||
- 单页结构：搜索输入框 + 结果卡片
|
||
- 查询模式：
|
||
- 条码：输入或粘贴条码，直接命中详情
|
||
- 名称：模糊搜索，列表展示，点选查看详情
|
||
- 关键字段展示：`名称、进价、卖价、条码`
|
||
- 响应式：移动端单列，桌面端居中卡片
|
||
|
||
## 权限与安全
|
||
- 初期无需登录；可选在`/import`增加简单令牌（环境变量）
|
||
- 限制上传文件类型与大小；后端校验列名
|
||
|
||
## 性能与鲁棒性
|
||
- SQLite足以支撑数千到数万条数据；建立`barcode`主键与`name`索引
|
||
- 导入过程批量提交、类型稳健转换；错误行记录到日志
|
||
|
||
## 测试与验收
|
||
- 单元测试：
|
||
- 列名映射与类型转换
|
||
- Upsert逻辑（插入/更新）
|
||
- 集成测试：
|
||
- 上传Excel，查询接口返回期望数据
|
||
- 验收标准：
|
||
- 可成功导入你现有的`商品资料.xlsx`
|
||
- 条码精确查询命中正确的名称/进价/卖价
|
||
- 名称模糊查询返回合理结果
|
||
|
||
## 实施任务清单
|
||
1. 初始化后端项目与SQLite数据表
|
||
2. 实现Excel解析与清洗、Upsert导入模块
|
||
3. 编写API：`/import`、`/products/{barcode}`、`/products`
|
||
4. 实现前端页面（响应式布局、搜索交互）
|
||
5. 编写测试与导入验证、性能与错误日志
|
||
6. 打包运行脚本与简单部署说明（Windows环境）
|
||
|
||
## 可选增强
|
||
- 条码扫描（移动端摄像头 + 前端库，如ZXing/Quagga）
|
||
- 导入历史记录与回滚
|
||
- 导入多工作表与列名自动适配 |