1. 软件概述
1.1 产品定位
洵美AI智能客服系统（88chat）是轻量、可移植、可独立部署的嵌入式在线客服系统。一行 script 标签可嵌入任意 HTML 站点，所有数据存放在自有服务器（SQLite 文件 / 可平滑切换 PostgreSQL），无第三方依赖。定位为工具型产品而非 SaaS 订阅服务。
1.2 适用场景
中小企业自有官网、B2B 多产品站、内网/隔离环境（政企/制造业）、数据合规要求高的行业（医疗/金融/法律/跨境电商）、希望自建客服系统绕开 SaaS 订阅的团队。
1.3 核心指标
后端代码：单文件约 2581 行；授权模块约 280 行；数据库 16 张表 + 20 索引；运行时依赖 9 个 npm 包；端到端测试 78 步全通过；单实例承载数千在线访客、5k+ 并发 WebSocket。
2. 安装部署
2.1 桌面版（Windows）
下载 NSIS 安装包双击安装。首次启动自动创建管理员账号，浏览器打开 http://127.0.0.1:3088，进入「站点管理」新增站点并复制嵌入代码。数据存储路径：%APPDATA%/洵美AI/。
2.2 Docker 部署（推荐生产环境）
解压 server zip 后执行 docker compose up -d。默认监听 :3088，数据卷挂载在 ./data。可通过 .env 修改端口、JWT 密钥、数据保留策略。
2.3 直接 Node 部署
Node.js ≥ 20。npm ci --omit=dev 安装依赖，node src/server.js 启动。生产环境建议配 PM2 + Nginx 反代 SSL。
3. 嵌入指南
3.1 嵌入代码
<!-- 复制到任意页面的 </body> 之前 -->
<script src="https://your-server.com/widget.js"
data-site-id="your-site-id"></script>3.2 自定义参数
data-site-id（必填）：站点 ID。data-color：主色调 hex。data-position：left/right。data-locale：zh-CN/en-US。详见 widget.js 内联注释。
4. 接口规范
4.1 REST API
全部 /api/v1/ 前缀。鉴权使用 JWT (HS256)，header 携带 Authorization: Bearer <token>。响应统一 JSON，错误码沿用 HTTP 状态码 + body 内 code/message。
4.2 WebSocket
路径 /ws，握手时携带 token 与 site-id。心跳 30 秒 ping，75 秒未响应断开。事件类型见 DOCS.md 第 5 节。
4.3 出站 Webhook
6 类事件（会话开始/结束/转接 + 消息收发 + 评分），HMAC-SHA256 签名，可在站点管理页测试。支持企业微信/钉钉/飞书/Slack/自定义 URL。
5. 授权系统
5.1 授权流程
首次启动自动 30 天试用计时；试用结束写操作锁定（HTTP 402），读操作不受影响。在「授权管理」页面复制 install_id，到本站「授权管理」查询并购买，将获得的授权码粘贴回后台即可激活。
5.2 授权验证
采用 HMAC-SHA256 离线验签，服务端无需联网。支持绑定特定机器（install_id）防止滥用。授权码格式：XXXX-XXXX-XXXX-XXXX-XXXX-XXXX。
6. 运维
6.1 备份
npm run backup 一键打包 DB（VACUUM INTO 安全快照）+ uploads 为 tar.gz。建议配 cron 每日定时执行。
6.2 监控
/metrics 端点输出 Prometheus 风格指标：在线连接数、消息吞吐、错误率、响应延迟分位数。/health 端点返回 200 + JSON 状态。
6.3 数据保留
站点级配置已结束会话保留天数，每 6 小时自动清理；管理后台可手动触发立即清理。