# 益选便利店商品查询

## 概述
- 基于 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，服务器直接拉取镜像，避免远端构建时慢下载

## 前端扫码
- 优先使用浏览器原生 `BarcodeDetector` 实时识别
- 非安全上下文或不支持时，自动切换为“拍照识别”方式
- 识别成功自动填充并触发查询

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

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