42 lines
2.5 KiB
Markdown
42 lines
2.5 KiB
Markdown
## 搜索与数据模型
|
||
- 引入 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. 测试与日志：单测/集成测试与结构化日志 |