OmniMerchant

Spring Boot 4 + Spring AI 2 trustworthy ecommerce customer-service agent platform with multi-tenant security, commerce tools, billing controls, deterministic evals, trace replay, RAG safety, observability, and Shopify connector backbone.

这不是只接一个聊天接口的 RAG demo。OmniMerchant v3 的公开展示重点是：最新 Spring Boot 4 / Spring AI 2 技术栈，订单/物流/商品/政策/退货/人工升级的业务闭环，多租户 fail-closed 安全边界，付费 LLM 成本控制，可重复 Agent eval，trajectory replay，RAG ingestion safety，以及 Shopify OAuth/webhook/sync 生产化骨架。

演示动图

下面是由当前仓库真实 runtime 截图生成的短版动图预览，用来让 GitHub 访客快速看到买家咨询、RAG 证据工作台、轨迹回放、评测、可信控制台、工具审计和 Shopify 集成状态。完整 90 秒录制节奏见 scripts/demo-recording.md；该 .md 是拍摄脚本，不是视频产物。

重新生成动图：

.\scripts\capture-screenshots.ps1
.\scripts\create-demo-gif.ps1

公开核验证据

截图矩阵

仓库当前提交公开页和后台页截图矩阵，后台截图来自本地 runtime、seed 数据、管理员账号和租户上下文。可通过 .\scripts\capture-screenshots.ps1 重新生成；脚本默认使用 ADMIN_EMAIL / ADMIN_PASSWORD 登录后台，也可以传 -PublicOnly 只生成公开页面截图。

当前仓库保留买家咨询、登录、可信控制台、智能体评测、轨迹回放、RAG Workbench、RAG 安全等真实截图；没有运行后端时不提交伪造后台截图：

Eval 证据

默认 deterministic eval 覆盖 80 条 seeded golden conversations，按租户持久化 agent_eval_run / agent_eval_result，并输出：

当前已提交报告：reports/agent-eval-report.md，模式 DETERMINISTIC。

LIVE_AGENT 使用真实 LLM，只在显式配置 secret 后运行；默认 CI 和本地验收不依赖外部模型。

RAG 深度证据

OmniMerchant 的 RAG 子系统不是只返回一段拼接文本。v3 增加了可解释检索和证据质量路径：

深度指标中，citation coverage、retrieval precision@k、recall@k、MRR、nDCG@k、no-answer accuracy、P95 retrieval latency、unsupported claim rate、poisoning block rate 都由 deterministic RAG eval 明细聚合并持久化，/api/observability/rag 直接读取最近 eval run 的真实结果，不填假数。

技术栈

项目结构

omnimerchant/
├── omni-merchant-common/       # 共享模块：DTO、异常、JWT 工具、TraceId
├── omni-merchant-tenant/       # 租户管理：CRUD、多租户上下文、拦截器
├── omni-merchant-agent/        # Agent 核心：ReAct、工具调用、模型路由、限流、计费
├── omni-merchant-intent/       # 意图识别模块
├── omni-merchant-knowledge/    # 知识库：RAG 混合检索、文档管理、向量索引
├── omni-merchant-channel/      # 渠道接入模块
├── omni-merchant-message/      # 消息模块：RocketMQ 消费 Token 用量
├── omni-merchant-bootstrap/    # 启动模块：配置、过滤器、全局异常处理
├── omnimerchant-web/           # Vue 3 前端：聊天、管理后台
├── sql/                        # 建表脚本（MySQL + PGVector）
├── docker-compose.yml          # 本地开发中间件
└── Dockerfile                  # 后端多阶段构建

快速启动

v3 收口标准：fresh clone 后按本节启动，管理员登录、Widget session、Widget SSE、租户 fail-closed smoke、deterministic eval 和前端 build 都能复现。v1/v2 验收清单仍保留为历史基线。

环境要求

• Java 21 LTS
• Maven 3.8+
• Docker Desktop
• OpenAI / Anthropic / DeepSeek API Key（可选；不配置时后台、订单、商品、工单和 eval 可运行，AI 聊天返回配置提示）

1. 启动中间件

cp .env.example .env
# 填写 .env 中的 MYSQL_ROOT_PASSWORD、MYSQL_PASSWORD、PG_PASSWORD、ADMIN_PASSWORD、JWT_SECRET、INTEGRATION_ENCRYPTION_KEY
docker-compose up -d

启动 MySQL、Redis、PostgreSQL (pgvector)、RocketMQ (namesrv + broker + dashboard)。
如果本机已有 MySQL 占用 3306，可改用 MYSQL_PORT=13306 docker compose up -d mysql redis postgres rocketmq-namesrv rocketmq-broker，后端启动时同步设置 MYSQL_PORT=13306。

2. 初始化数据库

# MySQL 建表
docker exec -i omni-mysql sh -c 'mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' < sql/db_main.sql
docker exec -i omni-mysql sh -c 'mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' < sql/db_extensions.sql
docker exec -i omni-mysql sh -c 'mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' < sql/db_observability.sql
docker exec -i omni-mysql sh -c 'mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' < sql/db_eval_v2.sql
docker exec -i omni-mysql sh -c 'mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' < sql/db_shopify_v2.sql
docker exec -i omni-mysql sh -c 'mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' < sql/db_rag_safety.sql
docker exec -i omni-mysql sh -c 'mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' < sql/db_rag_deepening.sql
docker exec -i omni-mysql sh -c 'mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' < sql/demo_seed.sql

# PGVector 建表
docker exec -i omni-postgres sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"' < sql/db_vector.sql

也可以使用脚本执行完整 demo 初始化：

.\scripts\demo.ps1

Linux/macOS:

./scripts/demo.sh

3. 配置环境变量

export [email protected]
export ADMIN_PASSWORD='set-a-strong-password'
export JWT_SECRET='set-a-strong-256-bit-secret'
export INTEGRATION_ENCRYPTION_KEY="$(openssl rand -base64 32)"

# 无 LLM key 的本地 demo：禁用 Spring AI 自动模型，后台和业务数据仍可体验
export SPRING_AI_MODEL_CHAT=none
export SPRING_AI_MODEL_EMBEDDING=none
export SPRING_AI_MODEL_AUDIO_SPEECH=none
export SPRING_AI_MODEL_AUDIO_TRANSCRIPTION=none
export SPRING_AI_MODEL_IMAGE=none
export SPRING_AI_MODEL_MODERATION=none

# 启用 AI chat/RAG 时再配置：
# export SPRING_AI_MODEL_CHAT=openai
# export SPRING_AI_MODEL_EMBEDDING=openai
# export OPENAI_API_KEY=sk-your-key
# export ANTHROPIC_API_KEY=sk-your-key      # 可选
# export DEEPSEEK_API_KEY=sk-your-key       # 可选

4. 启动后端

mvn compile -pl omni-merchant-bootstrap -am
mvn -pl omni-merchant-bootstrap -am spring-boot:run -Dspring-boot.run.profiles=dev

应用默认运行在 http://localhost:8090。

5. 启动前端（可选）

cd omnimerchant-web
npm install
npm run dev

前端默认运行在 http://localhost:5173，API 请求自动代理到 localhost:8090。本地调试时请固定使用同一个 host；如果浏览器打开 http://127.0.0.1:5188，就不要混用 http://localhost:5188 的旧页面或 token。

6. 验证

# 健康检查
curl http://localhost:8090/api/health

# 管理员登录
curl -X POST http://localhost:8090/api/admin/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"set-a-strong-password"}'

# 测试对话
curl -X POST http://localhost:8090/api/test/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <JWT_FROM_LOGIN>" \
  -H "X-Tenant-Id: 1" \
  -d '{"message":"hello"}'

7. 本地质量门

mvn -q test
mvn -q -DskipTests package

cd omnimerchant-web
npm ci
npm run build
npm audit --omit=dev --audit-level=high

cd ..
docker compose config --quiet

Testcontainers 集成回归默认不跑，需要 Docker：

mvn -q -Pintegration verify

运行 deterministic Agent eval：

.\scripts\run-evals.ps1

该 eval runner 是基于 seed 数据和业务服务的 keyless deterministic checker；会持久化 eval run/result，并生成可回放 trace。LIVE_AGENT 真实模型评测需要显式启用，不作为默认 CI 依赖。

输出：

• reports/agent-eval-report.json
• reports/agent-eval-report.md
• reports/agent-eval-junit.xml

API 概览

公开接口

管理接口（需 JWT）

对话接口（需 JWT + X-Tenant-Id 头）

核心能力

客服工作台 — /admin/inbox、/admin/orders、/admin/products、/admin/customers、/admin/tickets、/admin/integrations、/admin/usage、/admin/evals、/admin/observability、/admin/traces、/admin/rag-workbench、/admin/rag-safety 覆盖客服操作、回归评测、失败归因、RAG 调试和知识审核。

买家 Widget — /widget 公开聊天入口，不依赖管理员 JWT；创建 session 后使用短期 WIDGET_CUSTOMER token 绑定 tenant 与 conversation，订单敏感信息必须通过订单邮箱或手机号校验。

ReAct Agent — ReAct 风格工具编排，自动调用工具获取真实数据。置信度低于 75%、金额争议 > $100、强负面情绪或客户请求人工时升级人工。

9 大业务工具 — queryOrder、trackLogistics、searchProductCatalog、refundPolicyRAG、createReturnRequest、requestRefundOrReplacement、requestAddressChange、translate、escalateToHuman。查询类可自动执行；退款、补发、改地址只创建内部审批请求，不让 LLM 直接修改外部平台。

Demo 数据闭环 — sql/demo_seed.sql 提供 2 个租户、10 个客户、20 个商品、30 个订单、物流轨迹、政策文档和 80 条 Agent 评测用例。推荐演示问题：

• Where is my order #1001? My email is [email protected].
• Can I return my rain jacket from #1002? [email protected]
• Recommend a waterproof travel backpack under $80.
• I am angry because tracking VL2004US is late.

混合检索 RAG — HNSW 向量检索 + BM25 关键词检索 + RRF 融合 + Cross-Encoder BGE Reranker 重排序。支持退换货政策和商品信息双知识库。

多语言 — Lingua 自动识别 12 种语言，中转英语处理（非英语→翻译为英语→LLM 处理→翻译回原语言），降低 Token 成本。

模型路由 — 根据意图和复杂度自动选择模型：简单请求走 gpt-4o-mini（低成本），中等复杂度走 claude-haiku-4-5（降级），兜底走 deepseek-chat（最低成本）。

三层限流 — Token 速率限制（Redis Lua 令牌桶）→ 模型并发限制（信号量）→ 熔断降级（Resilience4j）。Redis 或租户限流状态不可用时默认拒绝付费 LLM 调用，避免 fail-open。

多租户隔离 — JWT claims 绑定平台管理员或租户授权，X-Tenant-Id 必须通过 membership 校验后才写入上下文；MyBatis-Plus TenantLineInnerInterceptor 自动注入 WHERE tenant_id = ?，缺租户上下文时拒绝业务表 SQL。PGVector 查询手动带 tenant_id。

Agent Eval 与 Trace Replay — agent_eval_run、agent_eval_result、agent_run、agent_step 持久化 80 条 deterministic golden cases 和执行轨迹；失败 case 可跳转 trace timeline 做工具选择和失败归因。

RAG Safety — 文档入库后先经过 RagSafetyScanner 生成 rag_safety_review，高风险 prompt injection、隐藏 HTML/Markdown 指令、疑似密钥/PII、跨租户诱导默认隔离，人工 approve 后才允许索引。

Trust Console / Observability — /admin/observability 和 /admin/traces 从本地 MySQL 聚合 AI resolution、升级、工具成功率、失败类别、RAG citation coverage、retrieval precision@k、unsupported claim rate、eval pass rate、成本、P95 token/tool latency 和 Shopify backlog；Actuator 暴露 health/prometheus。

Shopify connector backbone — 保留 Custom App token 开发路径，同时增加 OAuth install/callback、cursor sync job、GraphQL throttle backoff、webhook status/DLQ/replay 和 order/product/customer/fulfillment/refund cache mutation。当前不声称 Shopify App Store 上架、embedded admin billing 或真实退款写操作。

v3 Scope Notes

• Shopify 已有 OAuth install/callback、HMAC、cursor sync job、GraphQL throttle backoff、webhook 入库、payload-specific cache mutation 和 replay/DLQ 管理面；App Store embedded/billing、token rotation 自动化和真实外部写操作仍是后续生产化工作。
• Agent eval 已有 80 条 seed golden cases、持久化 run/result、tool-selection scorer、citation faithfulness checker、retrieval precision@k、unsupported claim rate、JSON/Markdown/JUnit 报告和 trace link；LIVE_AGENT 真实模型评测是 opt-in，不污染默认 CI。
• Observability 是本地 DB + Micrometer/Prometheus 的 Trust Console；没有强依赖 Langfuse、Jaeger 或 Grafana。
• RAG safety 是 deterministic ingestion scanner + 人工 approve/reject + citation faithfulness checker + eval 指标；LLM-as-judge 和 sentence-level entailment 是 opt-in 增强，不作为默认 CI gate。
• Testcontainers profile 已提供 MySQL、Redis、PostgreSQL/pgvector 回归入口；本地 Docker 不可用时默认单测和 package 不依赖真实外部服务。

Security model

• 认证先行：/api/chat/**、/api/test/**、/api/knowledge/**、/api/conversations/**、/api/billing/** 都必须携带 Bearer JWT。
• 租户授权：JWT 中包含 role、tenantIds、platformAdmin。普通租户用户只能访问 token membership 内的 X-Tenant-Id；平台管理员显式使用 platformAdmin=true。
• 公开 Widget 会话：/api/widget/session 公开创建短期客户 token；/api/widget/chat/stream 校验 token 中的 role=WIDGET_CUSTOMER、tenantIds、tenantCode 和 conversationUuid，不再只信任请求体。
• Fail closed：缺 X-Tenant-Id 返回 400，JWT 无效返回 401，tenant mismatch 返回 403；tenant-scoped SQL 缺租户上下文直接拒绝。
• 付费 LLM 保护：限流依赖 Redis Lua + 租户预算；Redis 或租户限流状态不可用时拒绝请求，不自动放行。
• 流式韧性：SSE LLM 调用使用 Reactor timeout、有限重试和 Resilience4j Reactor circuit breaker，并在流结束时清理 tenant/call context。
• LLM 输出处理：前端 Markdown 渲染使用 DOMPurify allowlist 清洗后再进入 v-html，阻断模型输出 HTML/事件属性注入。
• 工具边界：订单、物流、商品、退货和人工升级工具都走租户隔离服务并写入 tool_call_log；退款、改地址等高风险动作只创建内部审批/工单，不让 LLM 直接改外部系统。

完整说明见 docs/security-hardening.md。

架构与公开展示

• 架构图与数据边界：docs/architecture.md
• OpenAPI 草案：docs/openapi.yaml
• Demo 发布脚本与截图清单：docs/demo-launch.md
• v2 求职旗舰收口清单：docs/v2-release-checklist.md
• Agent eval 设计与命令：docs/evals.md
• Trace replay 与观测：docs/observability.md
• RAG 安全审核：docs/rag-security.md
• Shopify 生产化 connector 边界：docs/shopify-production-connector.md
• 短版演示动图：docs/assets/demo/omnimerchant-demo-preview.gif
• 90 秒 demo 录制脚本：scripts/demo-recording.md，这是拍摄脚本，不是录屏文件
• 开源可信度审计：docs/open-source-audit-2026-06-20.md

截图生成：

.\scripts\capture-screenshots.ps1

# 只生成公开页面截图，不需要管理员账号：
.\scripts\capture-screenshots.ps1 -PublicOnly

# 使用已生成截图拼出 README 动图预览：
.\scripts\create-demo-gif.ps1

配置参考

Spring AI 版本策略

当前项目已升级到 Spring Boot 4.1.0 + Spring AI 2.0.0 + Java 21。v3 继续保留 v2 API 兼容面，同时按 Spring AI 2 的 ChatClient、Tool Calling、ChatMemory、Observability 生态进行迁移。

迁移说明：

• MyBatis-Plus 使用 mybatis-plus-spring-boot4-starter，租户拦截和分页依赖 mybatis-plus-jsqlparser。
• Druid 使用 druid-spring-boot-4-starter。
• Resilience4j 不再依赖 Boot 3 starter；项目显式使用 resilience4j-circuitbreaker、resilience4j-retry、resilience4j-reactor。
• Testcontainers 2 使用 testcontainers-* artifact 命名。
• 当前业务 JSON 仍保留 Jackson 2 API，因此引入 Spring Boot spring-boot-jackson2 兼容层；后续可单独评估 Jackson 3 全量迁移。

核心配置项（application-dev.yml）：

spring:
  datasource:
    druid:
      url: jdbc:mysql://localhost:3306/omni_merchant?...
      username: omnimerchant
      password: ${MYSQL_PASSWORD}
  data.redis:
    host: localhost
    port: 6379
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat.options: {model: gpt-4o-mini, temperature: 0.3}
    anthropic:
      api-key: ${ANTHROPIC_API_KEY}
      chat.options: {model: claude-haiku-4-5-20251001, temperature: 0.3}

omnimerchant:
  llm.deepseek:
    api-key: ${DEEPSEEK_API_KEY}
    base-url: https://api.deepseek.com
    model: deepseek-chat
  knowledge.reranker:
    url: http://localhost:8001/rerank
    timeout-seconds: 5

admin:
  email: ${ADMIN_EMAIL:}
  password: ${ADMIN_PASSWORD:}
  jwt-secret: ${JWT_SECRET:}

app:
  cors:
    allowed-origins: ${CORS_ALLOWED_ORIGINS:http://localhost:5173,http://127.0.0.1:5173,http://localhost:5188,http://127.0.0.1:5188}

完整配置参见 omni-merchant-bootstrap/src/main/resources/application-dev.yml。

Docker 部署

# 构建并启动全部服务（后端 + 前端 + 中间件）
export [email protected]
export ADMIN_PASSWORD=your-password
export JWT_SECRET=your-256-bit-secret
export INTEGRATION_ENCRYPTION_KEY=$(openssl rand -base64 32)
# 无 LLM key 先跑业务 demo；有 key 时再启用对应模型
export SPRING_AI_MODEL_CHAT=none
export SPRING_AI_MODEL_EMBEDDING=none
docker-compose up -d --build

服务端口：

• 前端：80 / 443
• 后端：8090
• MySQL：3306
• Redis：6379
• PostgreSQL：5432
• RocketMQ Dashboard：18080

License

MIT