feat: release contextual omnichannel customer platform
Add Telegram, WhatsApp and email account management, realtime messaging, contextual multilingual AI, customer intelligence, knowledge workflows, enterprise controls, a unified design system and complete repository documentation.
This commit is contained in:
wmq
@@ -1,53 +1,79 @@
|
||||
# 灵犀跨境
|
||||
|
||||
灵犀跨境是面向跨境业务团队的 Telegram 客户沟通与 AI 经营平台。当前版本只开放 Telegram，所有开放功能均访问真实 API、PostgreSQL、DeepSeek 和 Telegram Gateway，不包含前端 Mock 数据。
|
||||
灵犀跨境是一套面向跨境业务团队的多渠道客户经营 SaaS。系统将 Telegram、普通 WhatsApp 账号和企业邮箱接入统一消息中心，并提供上下文翻译、逐句意图识别、情绪与风险分析、客户画像、商机、任务、知识库和经营分析能力。
|
||||
|
||||
## 服务组成
|
||||
当前仓库包含 Web 前端、业务 API 和 WhatsApp Gateway；Telegram 通过独立部署的 Telegram Gateway 接入。开放功能均连接真实数据库和真实网关，不使用前端 Mock 作为生产数据源。
|
||||
|
||||
- React + TypeScript 前端，由 Nginx 提供静态资源和 API 反向代理。
|
||||
- Node.js API，负责独立租户、用户认证、CRM、会话、AI 和网关适配。
|
||||
- PostgreSQL，持久化租户隔离的业务数据。
|
||||
- 已有 Telegram Gateway，负责真实 Telegram 账号与 TDLib 操作。
|
||||
- DeepSeek Anthropic-compatible API，负责翻译、情感、意图、风险、摘要和回复建议。
|
||||
## 核心能力
|
||||
|
||||
## Docker 启动
|
||||
- 多租户注册、登录、RBAC、API Key、密码修改和会话撤销。
|
||||
- 多 Telegram、WhatsApp、企业邮箱账号绑定、切换和状态管理。
|
||||
- 实时会话、历史分页、已读、引用、媒体、消息状态和 WebSocket 推送。
|
||||
- 自动识别目标语言的双向翻译，逐会话上下文压缩与历史后台补齐。
|
||||
- 情感、意图、风险、摘要、智能回复和知识库辅助。
|
||||
- 客户、标签、画像、商机、任务、团队、通知、审计和经营分析。
|
||||
- WhatsApp 群组、联系人、代理、设备、重试、死信重放与备份接口。
|
||||
|
||||
1. 复制 `.env.example` 为 `.env`。
|
||||
2. 生成数据库、JWT、Webhook 随机密钥。
|
||||
3. 设置轮换后的 `DEEPSEEK_API_KEY`。
|
||||
4. 设置 Telegram Gateway 的租户令牌、租户 ID 和账号 ID。
|
||||
5. 启动：
|
||||
## 快速启动
|
||||
|
||||
要求：Docker Engine 24+、Docker Compose v2，以及一个可访问的 Telegram Gateway。
|
||||
|
||||
```powershell
|
||||
Copy-Item .env.example .env
|
||||
# 编辑 .env，替换所有 replace-with-* 配置
|
||||
docker compose --env-file .env up -d --build
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
默认访问地址：`http://127.0.0.1:8088`。
|
||||
|
||||
健康检查：
|
||||
默认入口为 `http://127.0.0.1:8088`。存活与就绪检查：
|
||||
|
||||
```powershell
|
||||
Invoke-RestMethod http://127.0.0.1:8088/health
|
||||
Invoke-RestMethod http://127.0.0.1:8088/api/dashboard/overview
|
||||
docker compose exec api node -e "fetch('http://127.0.0.1:3100/health/ready').then(async r=>{console.log(await r.text());process.exit(r.ok?0:1)})"
|
||||
```
|
||||
|
||||
业务 API 需要通过注册或登录取得 Bearer Token。浏览器永远不会收到 DeepSeek 或 Telegram Gateway 服务凭据。
|
||||
完整部署步骤、生产加固和回滚方法见 [部署文档](docs/DEPLOYMENT.md)。
|
||||
|
||||
## 开发检查
|
||||
## 本地开发与测试
|
||||
|
||||
```powershell
|
||||
npm install
|
||||
npm ci
|
||||
npm run typecheck
|
||||
npm run build
|
||||
|
||||
Set-Location server
|
||||
npm install
|
||||
node --check src/index.js
|
||||
Push-Location server
|
||||
npm ci
|
||||
npm test
|
||||
Pop-Location
|
||||
|
||||
Push-Location whatsapp-gateway
|
||||
npm ci
|
||||
npm test
|
||||
Pop-Location
|
||||
|
||||
npm run test:e2e
|
||||
```
|
||||
|
||||
## 安全说明
|
||||
E2E 默认访问 `http://127.0.0.1:8088`，可通过 `E2E_BASE_URL` 修改。
|
||||
|
||||
- `.env` 已加入 `.gitignore`，严禁提交真实密钥。
|
||||
- AI 回复只提供人工确认建议，不会自动向 Telegram 发送。
|
||||
- 所有业务资源都通过 JWT 中的租户 ID 隔离。
|
||||
- Webhook 必须配置独立随机密钥；生产部署应进一步使用 HTTPS、反向代理和 IP 白名单。
|
||||
## 文档
|
||||
|
||||
- [系统架构](docs/ARCHITECTURE.md)
|
||||
- [技术选型](docs/TECH-STACK.md)
|
||||
- [配置说明](docs/CONFIGURATION.md)
|
||||
- [部署与回滚](docs/DEPLOYMENT.md)
|
||||
- [接口目录](docs/API.md)
|
||||
- [测试策略](docs/TESTING.md)
|
||||
- [运维手册](docs/OPERATIONS.md)
|
||||
- [备份恢复](docs/BACKUP-RESTORE.md)
|
||||
- [版本历史](CHANGELOG.md)
|
||||
- [协作规范](CONTRIBUTING.md)
|
||||
- [安全策略](SECURITY.md)
|
||||
|
||||
## 版本
|
||||
|
||||
`main` 保存当前版本。历史源码以 `snapshot-YYYY.MM.DD-*` 标签归档，当前稳定版本使用语义化标签。任何历史标签都可通过 `git checkout <tag>` 独立检出。
|
||||
|
||||
## 安全
|
||||
|
||||
禁止提交 `.env`、数据库导出、私钥、Telegram/WhatsApp 登录态或客户媒体。浏览器不接触 DeepSeek 与网关服务凭据。发现安全问题请按 [SECURITY.md](SECURITY.md) 中的私下通报流程处理。
|
||||
|
||||
Reference in New Issue
Block a user