一个手机快速搜索商品的网页

2025-12-07 15:09:21 +08:00
commit fcbcdb7f95
17 changed files with 815 additions and 0 deletions
@@ -0,0 +1,70 @@
+## 目标
+- 顶部菜单切换“搜索/导入”，各模块彼此独立、互不干扰
+- 统一白色背景与高对比度主题，在暗黑系统模式下也能清晰可见
+- 强化搜索结果的可读性，突出名称、卖价、进价、条码等关键字段
+
+## 导航与布局
+- 顶部加入切换菜单（Tabs）：“搜索”、“导入”，使用吸附（sticky）头部
+- 页面分区：`SearchSection` 与 `ImportSection`，仅显示当前选中的模块
+- 保持响应式：移动端单列、桌面端居中卡片布局
+
+## 视觉与主题
+- 全局白色背景（`body{background:#fff}`），系统暗黑模式下也保持白底
+- 高对比文本色（近黑 `#111`），卡片投影与边框弱化但清晰
+- 关键信息强调：
+  - 名称加粗加大
+  - 卖价着重色（如 `#d32f2f`），进价次级色（如 `#455a64`）
+  - 条码固定等宽字体便于核对与复制
+- 统一间距与行高，提升可读性
+
+## 搜索体验优化
+- 输入框占位提示区分条码/名称（支持回车搜索）
+- 结果空态与错误态：展示“无结果/接口错误”提示
+- 加载态：搜索时按钮与列表显示“加载中”
+- 条码精确命中优先；名称模糊查询展示列表
+- 结果操作：点击复制条码（可选增强）
+
+## 结果呈现
+- 结果卡片字段顺序：名称（粗体）→ 卖价（显著）→ 进价 → 条码（等宽）
+- 列表模式下每条结果为独立卡片；单条命中时以详情样式展示
+- 支持分页/条数限制（沿用 `limit` 参数，可在前端提供下拉或固定值）
+
+## 导入模块
+- 独立导入区域仅在“导入”Tab显示
+- 显示文件名与导入进度，导入完成后展示统计（插入/更新/跳过）
+- 失败提示与重试按钮；限制文件类型（`xlsx/xls`）
+- 可选增强：拖拽上传
+
+## 代码改动清单
+- `static/index.html`
+  - 添加顶部 `nav` Tabs（搜索/导入）
+  - 拆分两个主容器：`#searchSection` 与 `#importSection`
+- `static/styles.css`
+  - 设置全局白色背景与高对比文本
+  - Tabs样式（选中态、悬停态、移动端适配）
+  - 结果卡片样式（标题、价格颜色、条码等宽字体、间距）
+  - 空态/加载态提示样式
+- `static/app.js`
+  - 管理当前Tab状态与切换逻辑
+  - 搜索渲染函数：突出关键字段、空态/错误态/加载态
+  - 导入渲染函数：进度提示、结果统计
+  - 小增强：复制条码、回车触发、简单节流
+
+## 验收标准
+- 在系统暗黑模式下仍保持白底，内容清晰可见
+- 移动端下布局舒适、操作便捷；桌面端居中显示
+- 搜索与导入切换明确，互不串场
+- 名称、卖价、进价、条码呈现明显、易读
+- 无控制台错误，接口异常时有友好提示
+
+## 风险与兼容
+- 中文编码与字体在部分终端显示差异；通过指定通用中文字体栈缓解
+- 保持原生HTML/CSS/JS，不引入新框架，降低兼容风险
+- 与现有接口契合，无需后端改动
+
+## 实施步骤
+1. 修改 `index.html`：加入导航与两个分区容器
+2. 更新 `styles.css`：白色主题、Tabs与卡片样式、提示态
+3. 更新 `app.js`：Tab切换、渲染优化、状态管理（空/错/载）
+4. 自测：手机与桌面浏览器，验证切换、搜索与导入流程
+5. 如有需要更新 `README.md` 截图与使用说明
@@ -0,0 +1,86 @@
+## 总览
+- 目标：在 Ubuntu 22.04（装有宝塔面板）部署现有 FastAPI + SQLite 项目，绑定域名并启用 HTTPS，支持前端查询与 Excel 导入。
+- 推荐路径：使用宝塔 Nginx 站点做反向代理，后端用虚拟环境 + `uvicorn` 常驻（systemd）或使用宝塔的 Python 项目插件；也可选 Docker 方案。
+
+## 路径A：Python 虚拟环境 + systemd + Nginx 反代（稳定通用）
+1. 上传项目到服务器
+- 位置：`/www/wwwroot/product-query`（宝塔默认网站目录）
+- 结构：包含 `app/`、`static/`、`requirements.txt`、`scripts/`、`README.md`
+
+2. 安装依赖并准备运行目录
+- `sudo apt update && sudo apt install -y python3.10-venv`（22.04 默认 Python3.10）
+- `cd /www/wwwroot/product-query`
+- `python3 -m venv venv && source venv/bin/activate`
+- `pip install -r requirements.txt`
+- `mkdir -p data && chown -R www:www /www/wwwroot/product-query`
+
+3. 创建 systemd 服务
+- 新建 `/etc/systemd/system/product-query.service`：
+```
+[Unit]
+Description=Product Query FastAPI
+After=network.target
+
+[Service]
+WorkingDirectory=/www/wwwroot/product-query
+ExecStart=/www/wwwroot/product-query/venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 9000
+Restart=always
+User=www
+Environment=PYTHONUNBUFFERED=1
+
+[Install]
+WantedBy=multi-user.target
+```
+- 执行：`sudo systemctl daemon-reload && sudo systemctl enable product-query && sudo systemctl start product-query && sudo systemctl status product-query`
+
+4. 宝塔创建网站并配置反向代理
+- 在宝塔面板 → 网站 → 添加站点，绑定你的域名（示例 `query.example.com`）
+- 在该站点的“反向代理”中设置：
+  - 目标地址：`http://127.0.0.1:9000`
+  - 开启“缓存/压力测试”时先关闭，调试稳定后再按需开启
+- SSL：在站点的“SSL”中申请 Let’s Encrypt 并开启强制 HTTPS
+
+5. 验证
+- `curl http://127.0.0.1:9000/health` 返回 `{"status":"ok"}`
+- 访问 `https://query.example.com/` 打开前端页面
+
+## 路径B：宝塔 Python 项目插件（图形化管理）
+1. 在宝塔应用商店安装“Python 项目管理器”（版本需支持 FastAPI/uvicorn）
+2. 新建项目：
+- 运行目录：`/www/wwwroot/product-query`
+- 选择 Python 解释器或创建虚拟环境
+- 安装依赖：在插件里执行 `pip install -r requirements.txt`
+- 启动命令：`uvicorn app.main:app --host 127.0.0.1 --port 9000`
+- 日志路径与守护设置按需配置
+3. 按路径A第4步在 Nginx 站点做反向代理与 SSL
+
+## 路径C：Docker / Compose（面板或命令行皆可）
+1. 安装 Docker 与 Compose（或使用宝塔 Docker 管理器）
+- `sudo apt install -y docker.io docker-compose`
+2. 在项目目录执行：
+- `docker compose up -d`（使用仓库内 `docker-compose.yml`）
+- 容器监听 `8000`，宿主机映射 `8000:8000`，数据持久化到宿主 `./data`
+3. 在宝塔 Nginx 站点反代到 `127.0.0.1:8000` 并配置 SSL
+
+## 数据与权限
+- 数据库存放在 `data/products.db`，务必保留该目录的持久化
+- 权限建议：`chown -R www:www /www/wwwroot/product-query`，确保 Nginx/反代用户读写正常（写入仅限后端进程）
+
+## 运维与排错
+- 服务日志：
+  - systemd：`journalctl -u product-query -f`
+  - Python插件/Docker：在面板或 `docker logs -f product-query`
+- 常见问题：
+  - 反代 502：检查后端是否启动、端口是否匹配、站点安全组/防火墙是否放行
+  - 中文编码：浏览器显示正常；命令行可能乱码，不影响功能
+
+## 上线Checklist
+- 站点域名与反向代理已配置
+- SSL 已启用且强制跳转 HTTPS
+- 后端进程已常驻（systemd 或插件守护）
+- `/import` 上传上限：在 Nginx/站点上传限制按需提高（如 50MB）
+- 防火墙安全：只开放 80/443，后端端口用 127.0.0.1 回环
+
+## 你需准备的信息
+- 目标域名（如需绑定）
+- 选择的部署路径（A/B/C），我可以据此输出一键命令与面板操作截图式步骤
@@ -0,0 +1,78 @@
+## 核心目标
+- 以最新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）
+- 导入历史记录与回滚
+- 导入多工作表与列名自动适配
@@ -0,0 +1,42 @@
+## 搜索与数据模型
+- 引入 FTS5 全文索引：为 `name`、`barcode`、（可选）`拼音码` 建立虚拟表，支持高性能模糊匹配与相关性排序
+- 扩展导入：将 Excel 的 `拼音码` 一并入库；若缺失可后续考虑使用库生成（规划阶段不变更依赖）
+- 排序策略：前缀匹配 > 后缀匹配 > 任意包含；同分时按匹配长度和最近导入时间排序
+- 分页与上限：为 `/products` 增加 `page` 与 `limit`，默认 `limit=20`、`page=1`
+
+## API 与后端性能
+- WAL 模式：启用 SQLite `PRAGMA journal_mode=WAL` 与适度 `synchronous=NORMAL` 提升并发读性能
+- 统一查询端点：保留 `/products?q=`（已支持数字部分匹配），增加 `sort`/`order` 参数
+- 健壮性：为 `/import` 增加上传类型/大小校验与导入报告（插入/更新/跳过及示例错误行）
+
+## 前端 UX
+- 结果高亮：在卡片中高亮匹配片段（名称与条码）
+- 分页与空态：在列表底部提供分页控件；无结果时引导用户切换到“导入”或修改关键词
+- 条码复制与扫码：卡片“复制条码”按钮；可选增加移动端扫码（后续集成 ZXing）
+
+## 安全与配置
+- `/import` 简单令牌：通过环境变量 `IMPORT_TOKEN` 校验；面板或 Docker Compose 注入
+- CORS 与限流：允许必要来源；基础限流防滥用（规划阶段暂不改动）
+
+## 部署与维护
+- Docker：保留端口 `57777`；增加 `.env` 支持 `PORT`、`IMPORT_TOKEN`、`WAL_OPEN=1`
+- 备份与导出：每日备份 `data/products.db`；提供 `/export` 导出 CSV（权限受控）
+
+## 监控与测试
+- 日志：结构化日志（导入错误行、查询参数与耗时）
+- 测试：导入与搜索单测（前后缀、包含）；接口集成测试覆盖分页与排序
+
+## 验收标准
+- 搜索在 5–10k 条数据下 100ms–300ms 返回
+- 支持关键词与数字部分匹配，分页与排序可用
+- `/import` 需令牌；导入报告清晰，错误不影响其他行
+- 前端在手机/桌面下可用；匹配高亮明显；复制条码便捷
+
+## 实施清单
+1. 数据层：开启 WAL；新增 FTS5 虚拟表与同步触发器
+2. 导入模块：扩展列映射、报告输出、基础校验
+3. API：分页/排序参数；统一查询逻辑对接 FTS5（无破坏旧参数）
+4. 前端：高亮、分页控件、复制条码按钮（扫码为可选后续）
+5. 安全：`IMPORT_TOKEN` 校验与 `.env` 注入；文档与面板配置说明
+6. 部署：Compose 加载 `.env`；备份脚本与导出接口
+7. 测试与日志：单测/集成测试与结构化日志