chore(history): import initial web product snapshot
This commit is contained in:
wmq
@@ -0,0 +1,156 @@
|
||||
# 灵犀跨境 · 跨境 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
|
||||
|
||||
本项目为徐州欧汇科技有限公司内部产品，未开源授权。仅供演示评估使用。
|
||||
Reference in New Issue
Block a user