Search-Goods/.trae/documents/基于Excel的商品查询系统规划.md

核心目标

• 以最新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）
• 导入历史记录与回滚
• 导入多工作表与列名自动适配