Typesense 搜索（可选）
借助可选的 Typesense 搜索引擎，加快并改进 HWD POS 中的所有搜索。
HWD POS 可以借助 Typesense（一款容错拼写的搜索引擎）加快其所有搜索：商品、客户、供应商，以及销售链中的单据（报价单 → 订单 → 发票 → 交货 → 发货 → 贷项）。
它完全是可选的。系统具有自动回退到 SQL 的机制：如果 Typesense 已关闭、未配置或无响应，每次搜索都会使用与以往相同的 SQL 查询。搜索功能永远不会失效。
开关
开关（默认开启）、连接参数、«Probar conexión»（测试连接）和 «Reindexar todo»（全部重建索引）位于 «Sistema → Salud y respaldos → Servicio de búsqueda»（系统 → 健康与备份 → 搜索服务，/admin/system）。
API key 为空时，开关不起作用：使用 SQL 搜索。这是默认行为。
1. 安装并启动 Typesense 服务器
推荐。 在服务器上打开 hwdpanel，选择 14) Instalar/actualizar servicio de búsqueda (Typesense + auto-arranque)（安装/更新搜索服务（Typesense + 开机自启））。
它会下载官方二进制文件，将其配置为 systemd 服务 typesense-server（重启后自动启动），在不存在时生成管理员 API key，在 HWD POS 中登记连接并重建索引。无需其他任何操作。
YOUR_TYPESENSE_KEY 请使用一个足够长的随机值。
API key
选项 14 会生成或沿用管理员密钥（即 --api-key 所指定的密钥），HWD POS 使用它进行索引和搜索。
如需额外的密钥，例如供外部客户端使用的只读搜索密钥，请使用 hwdpanel 中的 15) Gestionar claves de búsqueda（管理搜索密钥）。它通过 Typesense API 列出、创建（值仅显示一次）和删除密钥。
2. 在 HWD POS 中配置连接
以下任选一种方式即可。在 Ubuntu 上，hwdpanel 的选项 14 已经替您完成。
通过界面。 在 «Sistema → Servicio de búsqueda»（系统 → 搜索服务）中填写：
| 字段 | 值 |
|---|---|
| Host（主机） | 127.0.0.1 |
| Puerto（端口） | 8108 |
| Protocolo（协议） | http |
| API key | 您的 Typesense 密钥 |
点击 «Guardar»（保存），然后点击 «Probar conexión»。
通过 storage/config.php。 在 app 下添加一个 typesense 块（参见应用配置）：
return [
'db' => [ /* … */ ],
'app' => [
// …
'typesense' => [
'host' => '127.0.0.1',
'port' => '8108',
'protocol' => 'http',
'api_key' => 'YOUR_TYPESENSE_KEY',
],
],
];API key 为空时，Typesense 保持关闭，一切通过 SQL 运行。
3. 构建索引（首次必须执行）
cd /var/www/HWDPOS && php scripts/typesense_reindex.php该命令会创建集合（products、customers、suppliers、documents）并上传所有记录。也可以在搜索服务界面中使用 «Reindexar todo» 按钮。
4. 保持索引最新
- 增量（自动）。 保存商品、客户或供应商，或开具报价单、发票、订单或贷项时，HWD POS 会在后台更新 Typesense。它采用尽力而为的方式：绝不会阻塞或中断业务操作。
- Cron（推荐）。 定期重建索引可以覆盖在应用之外进行的任何更改：批量导入、直接编辑数据库，或重命名出现在单据中的客户。
*/10 * * * * cd /var/www/HWDPOS && php scripts/typesense_reindex.php >/dev/null 2>&1Typesense 宕机时
HWD POS 使用较短的连接超时，因此当 Typesense 服务器宕机时，会立即回退到 SQL。搜索会继续通过标准 SQL 搜索工作；重启服务（sudo systemctl restart typesense-server），必要时重建索引。