lingxi-web/README.md

# 灵犀跨境 · 跨境 AI 经营服务平台（前端）

> 让跨境沟通更简单 — 徐州欧汇科技有限公司

本仓库为「灵犀跨境」SaaS 平台的前端部分，面向中小外贸企业、跨境卖家和产业带企业，将 WhatsApp / Telegram / 邮件 / 独立站表单等渠道的客户咨询统一接入，通过 AI 翻译、意图识别、情感分析、风险预警与客户建档，将聊天记录沉淀为可追踪、可成交的客户资产。

## 技术栈

- **React 18** + **TypeScript 5**
- **Vite 5** — 开发与构建
- **Tailwind CSS 3.4** — 原子化样式
- **shadcn/ui 风格** — 手写轻量企业 UI 组件
- **React Router 6** — 路由
- **Zustand 4** — 全局状态（认证/UI/Toast/确认弹窗）
- **TanStack Query 5** — 数据请求与缓存
- **Recharts 2** — 图表
- **React Hook Form 7** + **Zod 3** — 表单与校验
- **Lucide React** — 图标

## 快速开始

```bash
# 1. 安装依赖
npm install

# 2. 启动开发服务器（默认 Mock 模式）
npm run dev

# 3. 浏览器打开 http://localhost:5173
```

登录页点击下方**演示角色一键登录**即可进入系统：
- 企业管理员 / 业务主管 / 外贸业务员 / 客服人员 / 只读成员

也可以使用验证码模式：任意手机号 / 邮箱 + 任意 6 位验证码即可登录。

## 构建生产包

```bash
npm run build    # TypeScript 检查 + Vite 构建
npm run preview  # 预览构建结果
```

## 环境变量与模式切换

项目通过 `.env` 文件控制数据来源：

```env
# 使用内置 Mock 服务（默认，无需后端）
VITE_USE_MOCK=true

# 真实后端 API 地址（VITE_USE_MOCK=false 时生效）
VITE_API_BASE_URL=http://localhost:8080/api
```

- **Mock 模式**（`VITE_USE_MOCK=true`）：前端内置完整演示数据集（30 个客户、20 条会话、100+ 条多语种消息、20 个跟进任务、15 条风险预警、30 条企业知识、8 名团队成员、13 个渠道），所有 API 请求在前端通过 Mock 路由处理，无需任何后端服务。
- **真实模式**（`VITE_USE_MOCK=false`）：所有 API 请求转发到 `VITE_API_BASE_URL`，自动携带 Bearer Token。

> ⚠️ **安全提示**：请勿在前端代码中存放任何真实 API 密钥。所有密钥应由服务端环境变量管理。

## 项目结构

```
src/
├── app/
│   ├── router/index.tsx      # React Router 路由配置
│   ├── providers/index.tsx   # QueryClient + i18n + Toast + Confirm
│   └── store/                # Zustand stores (auth / ui / toast / confirm)
├── components/
│   ├── layout/               # AppLayout / Sidebar / Topbar / GlobalSearch
│   ├── common/               # PageHeader / StatCard / ChannelIcon / CountryFlag / StatusBadges / PermissionGate / DemoNote
│   ├── ui/                   # UI 基础组件（button / input / select / dialog / drawer / tabs / table / toast / pagination 等）
│   ├── inbox/                # 统一消息专属组件（ConversationList / MessageBubble / Composer / InsightPanel / AiReplies）
│   ├── customer/             # 客户表单弹窗（CustomerFormDialog）
│   ├── crm/                  # 商机与任务表单（TaskFormDialog）
│   └── charts/               # 图表封装（TrendChart / DonutChart / FunnelChart / RankBars）
├── pages/
│   ├── auth/                 # 登录 / 注册
│   ├── onboarding/           # 8 步企业初始化向导
│   ├── dashboard/            # 今日经营工作台
│   ├── inbox/                # 统一消息中心（三栏布局 + 移动适配）
│   ├── customers/            # 客户管理（表格/卡片/看板） + 客户详情
│   ├── opportunities/        # 商机看板 + 跟进任务 + 日历
│   ├── translate/            # AI 翻译中心
│   ├── interpret/            # 同声传译（模拟实时双向字幕）
│   ├── risks/                # 风险预警中心
│   ├── knowledge/            # 企业知识库 + 检索测试 + 使用统计
│   ├── analytics/            # 数据分析 + 老板看板
│   ├── channels/             # 渠道中心 + 连接向导
│   ├── team/                 # 团队协作 + 角色权限矩阵
│   ├── billing/              # 套餐与账单
│   ├── settings/             # 系统设置（13 组）
│   └── help/                 # 帮助与培训 + 交付进度
├── services/
│   ├── api/                  # 领域 API 服务（auth / dashboard / channels / conversations / ai / customers / crm / knowledge / org / search）
│   └── mock/                 # Mock 路由与处理器（按 HTTP 方法 + 路径匹配，支持 :param 参数）
├── mocks/
│   ├── db.ts                 # 内存数据库（增删改持久到刷新）
│   └── seed/                 # 种子数据（customers / conversations / messages / tasks / opportunities / risks / knowledge / team / channels / analytics / misc）
├── types/                    # TypeScript 类型定义
├── config/                   # 全局配置（套餐价格 / 支持语言数 / 角色权限 / 导航 / 业务常量 / 环境变量）
├── i18n/                     # 国际化（zh / en / ar + RTL）
├── hooks/                    # 自定义 Hooks（usePermission / useDebounce / useMediaQuery）
├── utils/                    # 工具函数（cn / format / misc）
└── styles/                   # 全局样式与 CSS 变量
```

## 接入真实后端

项目中预留了完整的 API 接口层，对应后端路由如下：

| 领域 | 核心接口 |
|------|---------|
| 认证 | `POST /api/auth/login`, `POST /api/auth/register`, `GET /api/auth/me` |
| 工作台 | `GET /api/dashboard/overview` |
| 渠道 | `GET /api/channels`, `POST /api/channels/connect`, `POST /api/channels/test`, `PATCH /api/channels/:id`, `DELETE /api/channels/:id` |
| 会话 | `GET /api/conversations`, `GET /api/conversations/:id`, `GET /api/conversations/:id/messages`, `POST /api/conversations/:id/messages`, `PATCH /api/conversations/:id` |
| AI | `POST /api/ai/translate`, `POST /api/ai/analyze`, `POST /api/ai/replies`, `POST /api/ai/summarize`, `POST /api/ai/interpretation`, `POST /api/ai/text-action` |
| 客户 | `GET/POST /api/customers`, `GET/PATCH/DELETE /api/customers/:id`, `POST /api/customers/merge`, `POST /api/customers/import`, `GET /api/customers/export`, `GET /api/customers/duplicates` |
| 商机 | `GET/POST /api/opportunities`, `PATCH /api/opportunities/:id` |
| 任务 | `GET/POST /api/tasks`, `PATCH /api/tasks/:id` |
| 风险 | `GET /api/risks`, `PATCH /api/risks/:id` |
| 知识库 | `GET/POST /api/knowledge`, `PATCH/DELETE /api/knowledge/:id`, `POST /api/knowledge/upload`, `POST /api/knowledge/search-test`, `GET /api/knowledge/stats` |
| 分析 | `GET /api/analytics` |
| 团队 | `GET /api/team`, `POST /api/team/invite`, `PATCH/DELETE /api/team/:id` |
| 账单 | `GET /api/billing`, `POST /api/billing/upgrade` |
| 设置 | `GET/PATCH /api/settings` |
| 通知 | `GET /api/notifications`, `POST /api/notifications/read-all` |
| 搜索 | `GET /api/search?q=` |

后端可使用 Java / Node.js / Python 等任意技术栈实现。参考 Mock 服务中 `src/services/mock/handlers/` 目录下的处理器即可了解各接口的请求/响应 Shape。

## 套餐与价格配置

所有套餐价格集中维护在 `src/config/pricingPlans.ts` 中，包含四档套餐（轻助手版 / 标准工作台版 / 专业版 / 增长版/定制版），一处修改全局生效。

## 语言支持

平台 UI 支持中文 / English / العربية（RTL），RTL 布局通过 `document.documentElement.dir = 'rtl'` 原生实现。

翻译引擎支持语言数配置在 `src/config/languages.ts` 的 `supportedLanguageCount` 字段，当前默认值为 96。

## 演示数据说明

所有图表、经营指标与客户数据均为**模拟演示数据**（数据来源：`src/mocks/seed/` 目录），不代表真实企业经营状况。每个图表卡片均标注「演示数据」提示。

客户与消息覆盖以下真实语言场景：
- 🇵🇰 乌尔都语（巴基斯坦 · WhatsApp）
- 🇦🇪 / 🇸🇦 阿拉伯语（阿联酋 / 沙特 · 邮件 / Telegram）
- 🇧🇩 孟加拉语（孟加拉国 · WhatsApp）
- 🇪🇸 西班牙语（西班牙 · 独立站表单 / WhatsApp）
- 🇬🇧 / 🇺🇸 / 🇩🇪 英语（英国 / 美国 / 德国 · 邮件 / Messenger）

## License

本项目为徐州欧汇科技有限公司内部产品，未开源授权。仅供演示评估使用。