62 lines
2.8 KiB
Markdown
62 lines
2.8 KiB
Markdown
# 益选便利店商品查询
|
||
|
||
## 概述
|
||
- 基于 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 编码
|