merge: LibreDesk 升级到 v2.9.0

.env.example

@@ -3,7 +3,7 @@ POSTGRES_PASSWORD=<change-me>
 POSTGRES_DB=<change-me>
 POSTGRES_IMAGE=pgvector/pgvector:pg18
 REDIS_IMAGE=redis:8.8-alpine
-LIBREDESK_IMAGE=libredesk/libredesk:v2.9.0-rc.10
+LIBREDESK_IMAGE=libredesk/libredesk:v2.9.0
 LIBREDESK_SYSTEM_USER_PASSWORD=<change-me>
 LIBREDESK_ENC_KEY=<change-me>
 LIBREDESK_BASE_URL=<change-me>

README.md

@@ -3,11 +3,11 @@
 **完全新建**的一套 CRM 客服栈：LibreDesk（平台 + 内置 AI）+ Twenty（CRM）+ bridge（业务工具/集成）。
 与旧项目 `/home/dev/code/crm/crm-ai-demo` 完全隔离：独立目录、独立 Postgres/Redis、独立端口，不迁旧数据。
 
-## 当前状态（2026-10-21）
+## 当前状态（2026-10-26）
 
 | 组件 | 状态 |
 |---|---|
-| LibreDesk v2.9.0-rc.10 | ✅ 运行中 :9000（System 密码见 `.env`） |
+| LibreDesk v2.9.0 | ✅ 运行中 :9000（System 密码见 `.env`） |
 | Twenty v2.30.1（全新实例） | ✅ 运行中 :3100，数据库迁移完成（71 张表） |
 | bridge | ✅ 运行中 :4100，4 个工具，单测 18/18 通过 |
 | Postgres / Redis | ✅ :5440 / :6390 healthy |
@@ -53,7 +53,7 @@ Twenty :3100 ── 公司/联系人/商机/备注/任务
 
 | 组件 | 地址 | 镜像/实现 |
 |---|---|---|
-| LibreDesk | http://localhost:9000 | `libredesk:v2.9.0-rc.10`（含 WhatsApp） |
+| LibreDesk | http://localhost:9000 | `libredesk:v2.9.0`（含 WhatsApp） |
 | Twenty | http://localhost:3100 | `twentycrm/twenty:v2.30.1`（全新实例） |
 | bridge | http://localhost:4100 | Node 24，自研 |
 | Postgres | localhost:5440 | pgvector/pg18，库 `libredesk` / `twenty` / `bridge` |
@@ -220,6 +220,6 @@ cd bridge && npm test
 ## 关键约束
 
 - **镜像直接使用 Docker Hub**：`libredesk/libredesk`、`pgvector/pgvector`、`redis`、`twentycrm/twenty`；如网络受限可在 Docker daemon 配自己的 registry mirror
-- **WhatsApp 仅 v2.9 RC 支持**，需要 Meta Cloud API 凭据；RC 版供联调，不直接上生产
+- **WhatsApp 自 v2.9.0 起支持**，需要 Meta Cloud API 凭据；当前运行 v2.9.0 正式版
 - **LibreDesk AI 仍是 beta**，建议低流量验证
 - 旧栈（Chatwoot/bridge/Twenty :3000）保持运行，可并行对照，互不影响

bridge/src/tools.js

@@ -421,7 +421,8 @@ function createTools(cfg, deps = {}) {
       const cmd = {
         keyword: rpcQuery,
         page: 1,
-        pageSize: limit,
+        // 多取候选，下面按库存排序后再截断到 limit，避免缺货商品占满前几条
+        pageSize: limit * 4,
         languageId: profile.languageId,
         tenantId: profile.tenantId,
         currencyCode: profile.currencyCode || '',
@@ -439,7 +440,6 @@ function createTools(cfg, deps = {}) {
       const list = Array.isArray(paging) ? paging : (paging.data || paging.list || []);
       total = result.total != null ? result.total : (paging.total != null ? paging.total : null);
       items = (Array.isArray(list) ? list : [])
-        .slice(0, limit)
         .map((p) => {
           const name = p.spuName || p.name || p.title || null;
           const sku = p.sku || p.model || (Array.isArray(p.skus) && p.skus[0] ? p.skus[0].productId : null);
@@ -458,7 +458,13 @@ function createTools(cfg, deps = {}) {
             mark_price: p.markPriceWithCurrency || null,
           };
         })
-        .filter((p) => p.name);
+        .filter((p) => p.name)
+        // 有库存优先：stock>0 → 0，未知 → 1，缺货 → 2；sort 稳定，保留 RPC 原顺序
+        .sort((a, b) => {
+          const rank = (p) => (p.stock > 0 ? 0 : p.stock === null ? 1 : 2);
+          return rank(a) - rank(b);
+        })
+        .slice(0, limit);
     } catch (err) {
       catalogError = err.message;
     }

docker-compose.yml

@@ -48,7 +48,7 @@ services:
 
   # ---------------------------------------------------------------- LibreDesk
   libredesk:
-    image: ${LIBREDESK_IMAGE:-libredesk/libredesk:v2.9.0-rc.10}
+    image: ${LIBREDESK_IMAGE:-libredesk/libredesk:v2.9.0}
     container_name: crmnew-libredesk
     restart: unless-stopped
     ports:

docs/api-mapping.md

@@ -1,6 +1,6 @@
 # Chatwoot → LibreDesk 对照表
 
-迁移旧 `bridge` 时按此表逐项替换。字段/事件均已对照 LibreDesk 源码与文档核对（v2.8.0 / v2.9.0-rc）。
+迁移旧 `bridge` 时按此表逐项替换。字段/事件均已对照 LibreDesk 源码与文档核对（v2.8.0 / v2.9.0）。
 
 ## 1. HTTP API
 

docs/architecture.md

@@ -12,7 +12,7 @@
 | 业务 RPC | Hyperf JSON-RPC over TCP | 商品推荐、订单、库存/ETA、会员 | — |
 | imap-id-proxy | Node 24 | 给 LibreDesk 的 IMAP 连接注入 ID 命令，兼容 163 | 仅本地 POC |
 
-\* WhatsApp 需 LibreDesk v2.9 RC；当前镜像 `v2.9.0-rc.10`。
+\* WhatsApp 自 LibreDesk v2.9.0 起支持；当前镜像 `v2.9.0`。
 
 ## 2. 数据流
 

docs/deploy-wangliang.md

@@ -11,7 +11,7 @@
 
 | 组件 | 容器 | 宿主端口 | 状态 |
 |---|---|---|---|
-| LibreDesk v2.9.0-rc.10（渠道/工作台） | `crmnew-libredesk` | `9000` | ✅ healthy |
+| LibreDesk v2.9.0（渠道/工作台） | `crmnew-libredesk` | `9000` | ✅ healthy |
 | Twenty CRM v2.30.1（server） | `crmnew-twenty-server` | `3100` | ✅ healthy |
 | Twenty worker | `crmnew-twenty-worker` | — | ✅ running |
 | bridge（业务工具 / RPC 集成） | `crmnew-bridge` | `4100` | ✅ healthy |
@@ -42,7 +42,7 @@ grep '^TOOLS_SHARED_KEY='                .env   # bridge 工具密钥
 
 | 项 | 仓库默认 | 本环境 | 原因 |
 |---|---|---|---|
-| `LIBREDESK_IMAGE` | `libredesk/libredesk:v2.9.0-rc.10` | `libredesk/libredesk:v2.9.0-rc.10-**arm64**` | 宿主是 ARM64，`v2.9.0-rc.10` 只有 amd64；官方另发了 `-arm64` 同版本 tag，实测原生 `linux/arm64` 运行 |
+| `LIBREDESK_IMAGE` | `libredesk/libredesk:v2.9.0` | `libredesk/libredesk:v2.9.0-**arm64**` | 宿主是 ARM64；`v2.9.0-arm64` 的 digest 与多架构 `v2.9.0` 的 arm64 子镜像一致，显式 arm64 tag 沿用原部署习惯 |
 | `LIBREDESK_BASE_URL` | `http://localhost:9000` | `https://wangliang-crm.dev.gaia888.com` | 走宿主 nginx 的 HTTPS |
 | `TWENTY_SERVER_URL` | `http://192.168.31.61:3100` | `https://wangliang-twenty.dev.gaia888.com` | 前端 `REACT_APP_SERVER_BASE_URL` 用的就是它（已核对页面内联配置） |
 | `RECOMMEND_URL` | 测试服地址 | `jsonrpc://wangliang-dev:9503` | 用 **本工作区** 的 product-service |
@@ -389,3 +389,11 @@ RAG_PG_URL="postgres://crmnew:${PW}@127.0.0.1:5440/bridge" node scripts/kb-versi
 - agent1/agent2 的**邮件通知已关闭**（assignment/new_reply/SLA 等 email 渠道全部 `false`），仅保留站内通知。
 - 原因：`agent1@yehwang.com` / `agent2@yehwang.com` 在 `yehwang.com` 邮件服务器上被 550 拒绝，导致“New conversation assigned to you”退信。
 - OTP 邮件不受影响，bridge OTP 已实测可发送并送达 163 收件箱。
+
+## 11. 2026-10-26 LibreDesk 升级记录（rc.10 → v2.9.0）
+
+- 目标：`libredesk/libredesk:v2.9.0`（2026-10-22 正式版）；本环境用 `libredesk/libredesk:v2.9.0-arm64`（digest 与多架构 `v2.9.0` 的 arm64 子镜像一致）。
+- 升级前：`pg_dump -Fc libredesk` → `backups/libredesk-before-v2.9.0-2026-10-26.dump`（已验证可 `pg_restore -l`）；记录旧镜像 image ID `sha256:03df145b…`（rc.10-arm64）。
+- 变更范围：rc.10 → v2.9.0 无 DB migration、无 config 变更（仅 UI / 邮件模板 / widget / campaign 修复），数据库 schema 保持 57 张表。
+- 操作：改 `.env` 的 `LIBREDESK_IMAGE` → `docker compose up -d --force-recreate libredesk`（启动链自动 `--install --upgrade`，预期打印 `no upgrades to run`）。
+- 回滚：切回 `libredesk/libredesk:v2.9.0-rc.10-arm64` 并重建；无 schema 变更，不需要恢复数据库。

docs/libredesk-setup.md

@@ -198,10 +198,10 @@ const payload = {
 
 接完后旧桥的 `bridge/mail/`（IMAP 轮询 + 自动回复）可以退役；邮件摘要改为定时调 LibreDesk 报表 API。
 
-## 8. WhatsApp（当前 v2.9.0-rc.10 已可用）
+## 8. WhatsApp（v2.9.0 已可用）
 
-> **版本现状**：本套已运行 `v2.9.0-rc.10`，`channels` 枚举为 `email / livechat / whatsapp`，`whatsapp_templates` 表已就绪。
-> RC 属于预发布版本，生产使用前评估稳定性；回滚见 README「回滚到稳定版」。
+> **版本现状**：本套已运行 `v2.9.0` 正式版（2026-10-22 发布，2026-10-26 从 rc.10 升级），`channels` 枚举为 `email / livechat / whatsapp`，`whatsapp_templates` 表已就绪。
+> 升级前已 `pg_dump` 备份；本次无 DB migration，回滚见 `docs/runbook.md`「回滚」。
 
 1. Meta 侧准备：Business Account、WABA ID、Phone Number ID、Permanent Access Token、App Secret、Webhook Verify Token
 2. `Admin → Inboxes → New inbox → WhatsApp`，填上述凭据
@@ -209,7 +209,7 @@ const payload = {
 4. 模板：`whatsapp_templates` 表 + 后台模板管理；24 小时窗口外的主动消息必须用已审核模板
 5. **AI 对 WhatsApp 的支持文档未覆盖**（文档只写 email + live chat），需实测 assistant 是否在 WhatsApp 会话触发
 
-切换镜像：`.env` 里改 `LIBREDESK_IMAGE=libredesk/libredesk:v2.9.0-rc.9`（若 Docker Hub 无该 tag，则按官方文档从 `v2.9.0-rc.9` 源码构建）。
+切换镜像：`.env` 里改 `LIBREDESK_IMAGE` 后 `docker compose up -d --force-recreate libredesk`；升级前先 `pg_dump` 备份，并记录当前镜像 digest 便于回滚。
 
 ## 9. 验收清单
 

docs/migration-plan.md

@@ -91,11 +91,11 @@
 | RAG 降级 | EU 语种召回下降 | 迁移后用 golden 问题抽检，必要时保留旧 RAG 服务 |
 | 单工作区 | 多站点只能多 inbox，联系人共享 | 用 JWT 的 site 属性 + 隐私口径评审 |
 
-## 7. 版本核实（2026-10-21）
+## 7. 版本核实（2026-10-26 更新）
 
-- LibreDesk 稳定版：**v2.8.0**（2026-08-22），渠道 `email/livechat`
-- 预发布：**v2.9.0-rc.10**（2026-10-21），新增 WhatsApp（Meta Cloud API + 模板）
-- 本套环境已切到 rc.10；稳定版 v2.8.0 仍无 WhatsApp；官方文档暂无 WhatsApp 配置页（仅 release notes / 权限表提及）
+- LibreDesk 稳定版：**v2.9.0**（2026-10-22），渠道 `email/livechat/whatsapp`
+- 升级前为预发布 **v2.9.0-rc.10**（2026-10-21）；rc.10 → v2.9.0 无 DB migration、无 config 变更
+- 本套环境已于 2026-10-26 升到 v2.9.0（升级前 `pg_dump` 备份，回滚只需切回 rc.10 镜像）
 - AI Assistant / AI tools / verified contact 为 v2.8 已有能力，标注 beta
 
 

docs/runbook.md

@@ -160,20 +160,29 @@ docker run --rm -v crm-new_twenty-data:/data -v "$PWD/backups":/backup alpine \
 # 1. 备份
 docker exec crmnew-postgres pg_dump -U crmnew -d libredesk > backups/libredesk-before-upgrade.sql
 
-# 2. 修改 .env 的 LIBREDESK_IMAGE 后重建
+# 2. 记录升级前镜像（回滚基线；tag 可能被上游重推，务必留 digest/image ID）
+docker image inspect libredesk/libredesk:<旧 tag> --format '{{.Id}} {{.RepoDigests}}'
+
+# 3. 修改 .env 的 LIBREDESK_IMAGE 后重建
 docker compose up -d --force-recreate libredesk
 
-# 3. 容器启动命令会自动执行 --upgrade；确认日志
+# 4. 容器启动命令会自动执行 --upgrade；确认日志
 docker compose logs --tail=50 libredesk
 ```
 
+> 2026-10-26 升级记录（rc.10 → v2.9.0，无 DB migration / 无 config 变更）：
+> 本机 amd64 升级前 image ID `sha256:abdc41e7…` → 升级后 `sha256:e7aa3bac…`；
+> 测试服 arm64 升级前 image ID `sha256:03df145b…` → 升级后 `sha256:147d0081…`。
+
 ## 回滚
 
 ```bash
-# 切回稳定版
-sed -i 's#^LIBREDESK_IMAGE=.*#LIBREDESK_IMAGE=libredesk/libredesk:latest#' .env
+# 本次 rc.10 → v2.9.0 无 schema 变更：切回 tag 即可，无需恢复数据库。
+# 若要精确回滚，先确认本地仍缓存升级前镜像（image ID 见上方升级记录），再切 tag：
+sed -i 's#^LIBREDESK_IMAGE=.*#LIBREDESK_IMAGE=libredesk/libredesk:v2.9.0-rc.10#' .env
 docker compose up -d --force-recreate libredesk
-# 跨大版本回滚数据库需恢复备份（升级前 pg_dump）
+
+# 跨大版本回滚（有 migration 时）才需要按升级前 pg_dump 恢复数据库
 ```
 
 ## 端口冲突排查