灵犀跨境 · 跨境 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 — 图标

快速开始

# 1. 安装依赖
npm install

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

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

登录页点击下方演示角色一键登录即可进入系统：

• 企业管理员 / 业务主管 / 外贸业务员 / 客服人员 / 只读成员

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

构建生产包

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

环境变量与模式切换

项目通过 .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

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