Search-Goods/.trae/documents/系统改进计划：搜索、性能、UX 与部署增强.md

搜索与数据模型

• 引入 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. 测试与日志：单测/集成测试与结构化日志