益选便利店商品查询

概述

• 基于 FastAPI + SQLite 的轻量查询系统，适配手机和桌面
• 支持导入 Excel，条码为主键自动插入/更新（Upsert）
• 支持条码部分匹配（前缀/后缀/任意包含）与名称关键词搜索
• 内置扫码入口：支持浏览器原生条码识别与拍照识别兜底

本地运行

• 安装依赖：python -m pip install fastapi "uvicorn[standard]" pandas openpyxl python-multipart
• 启动服务：python -m uvicorn app.main:app --host 0.0.0.0 --port 57777
• 访问页面：http://localhost:57777/

导入

• 页面“导入Excel”选择文件并提交
• 后端解析Sheet1并映射列：名称（必填）、进货价（必填）、销售价（必填）、条码、可选分类（必填）

接口

• POST /import 表单上传file
• GET /products/{barcode} 精确条码查询
• GET /products?q=关键词&limit=20&page=1&sort=name&order=asc 列表查询
  • 当 q 为数字时：支持条码前缀、后缀与任意包含匹配；同时匹配名称包含
  • 当 q 为文本时：按名称包含匹配
• GET /health 健康检查

数据库

• SQLite 文件：data/products.db
• 表：products(barcode primary key, name, purchase_price, sale_price, category, created_at, source_file)
• 索引：idx_products_name(name)
• 性能：启用 WAL 与适度同步，提升并发读取

Docker（推荐部署）

• 构建并启动：docker compose up --build -d
• 端口映射：57777:57777（保持不变）
• 卷挂载：
  • ./data:/app/data（SQLite 持久化）
  • ./static:/app/static:ro（前端文件可直接更新，无需重建）
• 宝塔/Nginx（可选）：反代到 http://127.0.0.1:57777 并启用 HTTPS
• 详见《部署文档.md》

国内部署加速（腾讯云）

• Docker 加速：在服务器 /etc/docker/daemon.json 配置 registry-mirrors（参见《部署文档.md》）
• Python 依赖：镜像已默认使用腾讯云 PyPI 源 https://mirrors.cloud.tencent.com/pypi/simple
• 预构建：在本地构建并推送到腾讯云 TCR，服务器直接拉取镜像，避免远端构建时慢下载

移动端兼容

• iPhone 输入时不再自动放大：移动端下统一设置输入与按钮字体为 16px
• 采用响应式布局，保证手机与桌面一致可用

项目结构

• app/ 后端 FastAPI
• static/ 前端页面与脚本、样式
• data/ 运行时生成的 SQLite 数据库
• Dockerfile、docker-compose.yml 部署配置
• 部署文档.md 服务器部署说明

常见问题

• 无法唤起相机：请通过 HTTPS 域名访问或使用支持的浏览器；HTTP 下自动切换为拍照识别
• 构建缓存问题：使用 docker compose build --no-cache && docker compose up -d
• 中文命令行乱码：页面显示正常；确保浏览器为 UTF-8 编码