# 灵犀跨境

灵犀跨境是一套面向跨境业务团队的多渠道客户经营 SaaS。系统将 Telegram、普通 WhatsApp 账号和企业邮箱接入统一消息中心，并提供上下文翻译、逐句意图识别、情绪与风险分析、客户画像、商机、任务、知识库和经营分析能力。

当前仓库包含 Web 前端、业务 API、Telegram Gateway 和 WhatsApp Gateway。Telegram Gateway 源码位于 `telegram-gateway/`，运行时仍作为独立服务部署。开放功能均连接真实数据库和真实网关，不使用前端 Mock 作为生产数据源。

## 核心能力

- 多租户注册、登录、RBAC、API Key、密码修改和会话撤销。
- 多 Telegram、WhatsApp、企业邮箱账号绑定、切换和状态管理。
- 实时会话、历史分页、已读、引用、媒体、消息状态和 WebSocket 推送。
- 自动识别目标语言的双向翻译，逐会话上下文压缩与历史后台补齐。
- 情感、意图、风险、摘要、智能回复和知识库辅助。
- 客户、标签、画像、商机、任务、团队、通知、审计和经营分析。
- WhatsApp 群组、联系人、代理、设备、重试、死信重放与备份接口。

## 快速启动

要求：Docker Engine 24+、Docker Compose v2。首次部署应先按 [Telegram Gateway 接入指南](docs/TELEGRAM-GATEWAY.md) 启动网关，再启动平台。

```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`。存活与就绪检查：

```powershell
Invoke-RestMethod http://127.0.0.1:8088/health
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)})"
```

完整部署步骤、生产加固和回滚方法见 [部署文档](docs/DEPLOYMENT.md)。

## 本地开发与测试

```powershell
npm ci
npm run typecheck
npm run build

Push-Location server
npm ci
npm test
Pop-Location

Push-Location whatsapp-gateway
npm ci
npm test
Pop-Location

Push-Location telegram-gateway
npm ci
npm run build
npm test
Pop-Location

npm run test:e2e
```

E2E 默认访问 `http://127.0.0.1:8088`，可通过 `E2E_BASE_URL` 修改。

## 文档

- [系统架构](docs/ARCHITECTURE.md)
- [技术选型](docs/TECH-STACK.md)
- [配置说明](docs/CONFIGURATION.md)
- [部署与回滚](docs/DEPLOYMENT.md)
- [接口目录](docs/API.md)
- [Telegram Gateway 接入](docs/TELEGRAM-GATEWAY.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) 中的私下通报流程处理。