feat: 配置挪到外边

2025-12-23 11:52:06 +08:00
parent f8810f5199
commit 7a89b80c8f
3 changed files with 1019 additions and 1 deletions
--- a/Touchkebao/src/pages/pc/ckbox/powerCenter/index.data.tsx
+++ b/Touchkebao/src/pages/pc/ckbox/powerCenter/index.data.tsx
@@ -59,7 +59,7 @@ export const featureCategories: FeatureCard[] = [
      "标签化精准推送",
      "接待模式切换",
    ],
-    path: "/pc/powerCenter/ai-reception",
+    path: "/pc/commonConfigss",
  },
  // {
  //   id: "content-library",
--- a/Touchkebao/提示词/功能架构.md
+++ b/Touchkebao/提示词/功能架构.md
@@ -0,0 +1,495 @@
+# 触客宝（Touchkebao）功能架构
+
+> 本文档描述当前 Touchkebao 前端工程在 **页面路由、状态管理、数据访问、本地缓存和核心业务模块** 维度的功能架构，并附带 ASCII 线框图，便于沟通与扩展设计。
+
+## 1. 技术栈与整体结构
+
+- **基础框架**
+  - **React 18 + TypeScript**：单页应用（SPA）
+  - **Vite**：构建与开发服务器（入口 `src/main.tsx`）
+  - **UI 组件**
+    - PC 端：`antd`
+    - 移动端：`antd-mobile`
+  - **状态管理**：`zustand`（含自定义持久化封装）
+  - **请求与数据**
+    - HTTP：`axios` + 统一封装 `api/request.ts`
+    - 本地缓存：`Dexie`（IndexedDB，统一封装在 `utils/db.ts`）
+  - **监控与稳定性**
+    - `@sentry/react`：初始化于 `main.tsx`，并通过 `App.tsx` 中的 `ErrorBoundary` 做兜底
+    - 自定义错误提示与 Toast（`antd-mobile`）
+
+- **入口初始化流程**
+  - `src/main.tsx`
+    - 初始化 Sentry（必须在其他逻辑前）
+    - 设置 `dayjs` 中文
+    - 调用 `initializeDatabaseFromPersistedUser()`：
+      - 从持久化的 user-store 中恢复上次登录用户
+      - 以 `userId` 为维度初始化 Dexie 数据库
+    - 渲染根组件：
+      - `ConfigProvider`（antd 中文配置）
+      - `QueryProvider`（React Query 统一数据请求层）
+      - `App`
+  - `src/App.tsx`
+    - 使用 `Sentry.ErrorBoundary` 包裹整个应用
+    - 内部渲染：
+      - `AppRouter`（统一路由系统）
+      - `UpdateNotification`（版本更新提醒，支持自动刷新）
+
+---
+
+## 2. 路由 & 页面模块架构
+
+路由集中于 `src/router` 目录，通过 `import.meta.glob` 动态加载模块。
+
+### 2.1 路由整体
+
+- **核心文件**
+  - `router/index.tsx`
+    - 使用 `import.meta.glob("./module/*.{ts,tsx}", { eager: true })` 自动导入所有路由模块
+    - 聚合得到 `routes: RouteObject[]`
+    - 对 `auth: true` 的路由包装 `PermissionRoute`
+    - 追加通配符 `*` → `404` 页
+    - 使用 `BrowserRouter + useRoutes` 渲染
+  - `router/permissionRoute.tsx`
+    - 依赖 `useUserStore` 提供的 `user` 与 `isLoggedIn`
+    - 未登录时记录当前 `pathname + search`，跳转至 `/login?returnUrl=...`
+    - 当路由声明 `requiredRole` 时，校验 `user.isAdmin === 1`，否则跳转首页 `/`
+
+- **路由模块划分**
+  - `router/module/common.tsx`
+    - `/` → `Index` 首页：根据终端类型跳转：
+      - 移动端 → `/mobile/dashboard`
+      - PC 端 → `/pc/weChat`
+    - `/login` → 登录页（免登录）
+    - `/guide` → 产品引导页（需要登录）
+    - `/init` → iframe 初始化页（嵌入其他系统对接）
+  - `router/module/pc.tsx`
+    - `/pc` → `CkboxPage`（PC 端总布局，内含顶部导航）
+      - 子路由（均需要登录）：
+        - `/pc/commonConfig` → 通用配置中心
+        - `/pc/dashboard` → 数据看板
+        - `/pc/weChat` → 微信客服工作台（核心聊天场景）
+        - `/pc/powerCenter` → 能力中心（导航页）
+        - `/pc/powerCenter/customer-management` → 客户管理
+        - `/pc/powerCenter/communication-record` → 沟通记录
+        - `/pc/powerCenter/content-management` → 内容管理 & 朋友圈发布
+        - `/pc/powerCenter/ai-training` → AI 训练/话术配置
+        - `/pc/powerCenter/auto-greeting` → 自动欢迎与自动打招呼
+        - `/pc/powerCenter/message-push-assistant` → 消息推送助手
+        - `/pc/powerCenter/message-push-assistant/create-push-task/:pushType` → 新建推送任务多步骤向导
+        - `/pc/powerCenter/data-statistics` → 数据统计
+        - `/pc/powerCenter/push-history` → 推送历史
+  - `router/module/mobile.tsx`
+    - `/profile` → 移动端个人中心/设置页（需要登录）
+
+### 2.2 页面布局与导航
+
+- **PC 布局（`components/Layout`）**
+  - `Layout.tsx / LayoutFiexd.tsx`
+  - 支持传入自定义 header（如 `NavCommon`）
+  - 标准结构：
+    - 顶部：产品标题、用户信息、全局操作区
+    - 中间：左右结构（侧边栏 + 主内容）
+
+- **PC 触客宝主页面（`pages/pc/ckbox/index.tsx` 及子模块）**
+  - `CkboxPage`：
+    - 使用 `Layout` 作为整体页面容器
+    - header 为 `NavCommon`（标题“触客宝”等）
+    - 中间区域通过 `<Outlet />` 渲染子路由页面
+
+---
+
+## 3. 状态管理架构（Zustand）
+
+### 3.1 Store 组织方式
+
+- **统一出口**：`src/store/index.ts`
+  - 导出：
+    - `useUserStore`（用户）
+    - `useAppStore`（应用级状态）
+    - `useSettingsStore`（个性化设置）
+    - `useWebSocketStore`（WebSocket 连接与命令）
+    - 各种 `createPersistStore`、`persistUtils` 工具
+  - 提供：
+    - `getStores()`：一次性获取所有 store 状态
+    - `subscribeToAllStores()`：统一订阅所有 store 变更
+
+- **业务模块 Store（节选）**
+  - `store/module/user.ts`
+    - 用户信息（id、名字、角色、isAdmin 等）
+    - 登录状态 `isLoggedIn` 与 token
+    - 使用 `persist` 中间件，存入 localStorage
+  - `store/module/app.ts`
+    - 全局 loading、布局属性、全局配置开关等
+  - `store/module/settings.ts`
+    - 主题、表格密度等个性化设置
+  - `store/module/websocket/websocket.ts`
+    - WebSocket 连接状态（已连接/重连中等）
+    - `sendCommand` 封装（如 `CmdSendMessage`）
+  - `store/module/weChat/*`
+    - 好友/群列表、客户、当前选中会话
+    - 聊天消息、分页、群成员
+    - AI 对话相关状态与逻辑（见 6 章节）
+
+### 3.2 权限与登录态
+
+- `PermissionRoute` 通过 `useUserStore` 读取：
+  - `isLoggedIn`：控制是否自动跳转登录页
+  - `user.isAdmin`：用于路由级别的角色校验
+- 登录成功后：
+  - 持久化 user store，以便刷新后仍可恢复
+  - `initializeDatabaseFromPersistedUser` 读取该信息并初始化 IndexedDB
+
+---
+
+## 4. 数据访问层（API 封装）
+
+### 4.1 通用请求封装（`api/request.ts`）
+
+- **Axios 实例配置**
+  - `baseURL`：优先取环境变量 `VITE_API_BASE_URL`，否则 `/api`
+  - 默认 `timeout`：20 秒
+  - 默认请求头：`Content-Type: application/json`
+  - 请求拦截器：
+    - 从 `useUserStore.getState()` 中读取 `token`
+    - 自动附加 `Authorization: Bearer <token>`
+
+- **响应拦截器逻辑**
+  - 统一假设服务端返回结构：`{ code, success, msg, data }`
+  - 判断业务成功：
+    - 优先看 `code === 200`
+    - 或 `success === true`
+    - 若都无，则认为是“透明透传”结构，直接返回原数据
+  - 业务失败处理：
+    - 如果 `code === 401`：
+      - 清理本地 `token`
+      - 计算当前路径 `pathname + search`
+      - 重定向到 `/login?redirect=当前路径`
+    - 其它错误：
+      - 根据 `ERROR_SILENT_URLS` 白名单控制是否显示错误 Toast
+      - 使用 `Toast.show({content: msg || "接口错误"})` 提示
+  - 网络错误：
+    - 仍带白名单控制
+    - 默认展示 `"网络异常"` 提示
+
+- **请求防抖机制**
+  - 使用 `debounceMap`（Map<key, timestamp>）记录请求
+  - key 由 `method + url + data` 组成
+  - 默认间隔 `DEFAULT_DEBOUNCE_GAP = 1000ms`
+  - 可通过 `config.debounce = false` 关闭
+  - 高频接口白名单 `NO_DEBOUNCE_URLS`（好友/群列表、消息列表）不走防抖
+
+- **统一导出函数**
+  - `request(url, data?, method = "GET", config?, debounceGap?)`
+    - 自动区分 GET（用 `params`）与非 GET（用 `data`）
+    - 自动处理 FormData（移除默认 `Content-Type`）
+
+### 4.2 文件上传封装（`api/common.ts`）
+
+- `uploadFile(file, uploadUrl = "/v1/attachment/upload")`
+  - 使用原生 `FormData` 封装文件
+  - 根据用户 token 设置 `Authorization` 头
+  - 返回后端 `data.url` 作为上传结果
+
+### 4.3 业务 API 模块
+
+- `api/ai.ts`
+  - `dataProcessing(params)`：新消息到达后进行预处理（发送到存客宝后台）
+  - `aiChat(params)`：根据上下文消息生成 AI 回复内容
+- `api/module/wechat.ts`
+  - 聊天消息列表、群成员、好友/群列表等接口
+- `api/module/group.ts`
+  - 分组/标签等管理类接口
+
+---
+
+## 5. 本地数据库架构（IndexedDB + Dexie）
+
+### 5.1 数据库设计（`utils/db.ts`）
+
+- **数据库命名**
+  - 前缀：`CunkebaoDatabase`
+  - 最终库名：`CunkebaoDatabase_${userId}`
+  - 每个登录用户一个独立数据库，实现物理隔离
+
+- **核心表结构（统一 friend / group 模型）**
+  - `ChatSession`（会话表）
+    - `serverId`：主键（使用服务端的 id）
+    - `userId`：本地用户 ID，用于多用户隔离
+    - `type`：`"friend" | "group"`
+    - 通用字段：`wechatAccountId, nickname, avatar, content, lastUpdateTime` 等
+    - 配置字段：`config.unreadCount, config.top`
+    - 排序字段：`sortKey`
+    - 扩展字段：`extendFields`（字符串 JSON）
+  - `Contact`（统一联系人表）
+    - `serverId`：主键
+    - `userId`：用户 ID
+    - `type`：`"friend" | "group"`
+    - 通用信息：昵称、备注、头像、地区、签名、搜索 key 等
+    - 标签/分组：`groupId`
+    - 扩展结构：`extendFields`
+  - `ContactLabelMap`（联系人与标签映射表）
+    - `serverId`：`${contactId}_${labelId}`
+    - `labelId`、`contactId`、`contactType`
+    - 用于按标签筛选联系人、统计
+  - `UserLoginRecord`（登录记录表）
+    - `serverId`: `user_${userId}`
+    - `lastLoginTime`、`loginCount`、`lastActiveTime` 等
+
+- **索引设计**
+  - 常用组合索引：
+    - `[userId+type]`
+    - `[userId+wechatAccountId]`
+    - `[userId+lastUpdateTime]`
+    - `sortKey / searchKey` 等
+  - 方便实现：
+    - 会话按更新时间与置顶排序
+    - 联系人/会话按关键字搜索
+    - 用户/标签多维度筛选
+
+### 5.2 数据库管理与代理
+
+- `DatabaseManager`
+  - 负责：
+    - 根据 `userId` 打开/切换数据库实例
+    - 维护 `currentDb` 与 `currentUserId`
+    - 提供 `ensureDatabase(userId)`、`getCurrentDatabase()` 等方法
+  - 支持检测是否已初始化（`isInitialized`）和关闭数据库（`closeCurrentDatabase`）
+
+- 启动恢复逻辑
+  - `initializeDatabaseFromPersistedUser()`
+    - 读取持久化 user-store（`PERSIST_KEYS.USER_STORE`）
+    - 解析得到 `user.id` 作为当前 userId
+    - 调用 `databaseManager.ensureDatabase(userId)` 初始化数据库
+
+- 数据库代理对象
+  - 使用 `Proxy` 将 `db` 暴露为“当前数据库”的代理
+  - 调用侧无需感知内部的实例切换逻辑
+
+- 通用 `DatabaseService<T>`
+  - 对 Dexie 的 `Table<T>` 封装：
+    - 增删改查、批量插入/更新、条件查询、分页、排序、统计
+    - 支持 `createWithServerId` / `createManyWithServerId`，与接口 ID 对齐
+  - 基于该服务构建：
+    - `chatSessionService`
+    - `contactUnifiedService`
+    - `contactLabelMapService`
+    - `userLoginRecordService`
+
+---
+
+## 6. 核心业务：微信客服工作台
+
+### 6.1 页面结构（/pc/weChat）
+
+- 路由：`/pc/weChat` → `pages/pc/ckbox/weChat`
+- 典型三栏布局：
+  1. 左侧侧边栏 `SidebarMenu`
+     - 会话列表 MessageList（虚拟列表 + 未读数）
+     - 好友/群/客户切换
+     - 朋友圈入口
+     - 添加好友/新建会话入口
+  2. 中间聊天窗口 `ChatWindow`
+     - 消息列表（`VirtualizedMessageList`）
+       - 文本、图片、语音、视频、小程序、红包、转账等多种消息类型组件
+     - 输入区 `MessageEnter`
+       - 文本输入框
+       - Emoji 表情（`EmojiSeclection`）
+       - 文件/图片/语音/视频上传（复用 `components/Upload` 系列）
+       - 支持 AI 建议文案自动填充（quoteMessageContent）
+     - 辅助弹窗：
+       - 聊天记录搜索 `ChatRecordSearch`
+       - 转发消息 `TransmitModal`
+       - 待办/提醒 `TodoListModal`
+  3. 右侧信息栏 `ProfileCard`
+     - 客户画像与标签
+     - 朋友圈动态（`FriendsCicle`）
+     - 快捷话术（`QuickWords`）
+     - 与当前会话相关的附加信息
+
+### 6.2 微信 Store（`store/module/weChat/weChat.ts`）
+
+> 使用 `zustand + persist` 管理微信聊天域内的复杂状态。
+
+- **状态主体**
+  - 当前对象与消息：
+    - `currentContract`: 当前选中的联系人/群（`ContractData | weChatGroup`）
+    - `currentMessages`: 当前聊天消息数组
+    - `currentMessagesPage` / `currentMessagesPageSize` / `currentMessagesHasMore`
+    - `currentGroupMembers`: 当前群成员列表
+  - AI 相关：
+    - `aiQuoteMessageContent`: AI 接管配置值
+    - `quoteMessageContent`: AI 生成的文案草稿，用于填充输入框
+    - `isLoadingAiChat`: 是否正在生成 AI 回复
+  - 加载与 UI：
+    - `messagesLoading` / `isLoadingData`
+    - `showCheckbox`：是否显示多选框
+    - `EnterModule`: `"common" | "multipleForwarding"` 等
+  - 朋友圈：
+    - `MomentCommon`: 朋友圈列表
+    - `MomentCommonLoading`: 加载标记
+
+- **关键行为**
+  - `setCurrentContact(contract)`
+    - 切换当前会话：
+      - 清除 AI 请求队列与定时器
+      - 重置当前消息与分页状态
+      - 清除未读数（调用 `clearUnreadCount1/2`）
+      - 拉取 AI 配置（`getFriendInjectConfig`）
+      - 更新当前会话并调用 `loadChatMessages(true)` 拉取首屏消息
+  - `loadChatMessages(Init, pageOverride?)`
+    - 根据当前联系人是好友/群决定调用 `getChatMessages` 或 `getChatroomMessages`
+    - 统一消息列表结构，并按时间排序
+    - 处理分页信息（page/limit/hasMore）
+    - 首次加载群聊时同步拉取群成员列表
+  - `SearchMessage({From, To, keyword, Count})`
+    - 在当前会话内按时间 + 关键字搜索消息
+  - `receivedMsg(message)`
+    - 当 WebSocket 收到新消息时调用
+    - 若消息属于当前会话：
+      - 使用 **16ms 批量更新队列**，减少 re-render 次数
+      - 针对“对方发送的文字消息”，根据当前会话 `aiType` 触发 AI 逻辑：
+        - 先将消息加入 `pendingMessages` 队列
+        - 3 秒内无更多新消息，则批量发送到 `dataProcessing`
+        - 再调用 `aiChat` 获取 AI 返回内容
+        - 若 `aiType === 2`（AI 接管）：
+          - 构造本地“发送中”消息并追加到 `currentMessages`
+          - 同时通过 WebSocket `CmdSendMessage` 实际发送
+        - 若 `aiType === 1`（AI 辅助）：
+          - 将 AI 文案写入 `quoteMessageContent`，MessageEnter 自动填充输入框
+  - `manualTriggerAi()`
+    - 用户手动点击“智能回复”等按钮，主动触发 AI 回复流程
+
+---
+
+## 7. 通用组件与能力模块
+
+- **选择器组件**
+  - `AccountSelection / DeviceSelection / ContentSelection / FriendSelection / GroupSelection / PoolSelection / MemberSelection / TwoColumnSelection`
+  - 特点：
+    - 支持弹窗选择、多选、搜索
+    - 复用同一 API 与数据结构
+    - 应用于内容管理、推送任务、新建沟通等多处业务场景
+
+- **上传组件**
+  - 位于 `components/Upload/*`
+  - 包含：
+    - `ImageUpload, FileUpload, VideoUpload, AudioUpload, AvatarUpload, ChatFileUpload, SimpleFileUpload, MainImgUpload`
+  - 与 `uploadFile`（或独立 axios 调用）结合，支持多文件类型与进度回调
+
+- **虚拟列表组件**
+  - `VirtualContactList, VirtualSessionList, VirtualMessageList, InfiniteList`
+  - 依托 `react-window` 等，实现上万级数据的高性能渲染
+
+- **图表组件**
+  - `LineChart, LineChart2`
+  - 基于 `echarts-for-react`，主要用于看板与数据统计模块
+
+---
+
+## 8. ASCII 架构 & 页面线框图
+
+### 8.1 系统高层功能架构（模块关系）
+
+```text
+-------------------------------------------------------------+
+|                        Touchkebao SPA                       |
+|  (React + TS + Vite, Antd, Antd-Mobile, Zustand, Dexie)     |
+--------------------------+----------------------------------+
+                           |
+                           v
+-------------------------------------------------------------+
+|                        App Shell                            |
+|  - App.tsx                                                  |
+|  - Sentry.ErrorBoundary                                     |
+|  - AppRouter (BrowserRouter + useRoutes)                    |
+--------------------------+----------------------------------+
+                           |
+                           v
+-------------------------------------------------------------+
+|                        Router 层                            |
+|  - /           -> Index (设备判断, 跳 /pc/weChat or /mobile) |
+|  - /login      -> Login                                    |
+|  - /guide      -> Guide (auth)                            |
+|  - /init       -> Iframe Init                             |
+|  - /pc/...     -> PC 工作台模块                           |
+|  - /profile    -> Mobile Profile (auth)                   |
+|  - *           -> 404                                     |
+|  权限: PermissionRoute + useUserStore                      |
+--------------------------+----------------------------------+
+                           |
+                           v
+-------------------------------------------------------------+
+|                     业务模块（PC）                          |
+|  /pc (CkboxPage: Layout + NavCommon + <Outlet/>)            |
+|    |- /pc/weChat              -> 微信客服工作台            |
+|    |- /pc/dashboard           -> 数据看板                  |
+|    |- /pc/commonConfig        -> 通用配置                  |
+|    |- /pc/powerCenter/...     -> 能力中心子模块           |
+--------------------------+----------------------------------+
+                           |
+                           v
+-------------------------------------------------------------+
+|                      状态与数据层                           |
+|  - zustand stores                                           |
+|      * user/app/settings/websocket                          |
+|      * weChat store (聊天状态 + AI 队列)                   |
+|  - api/request.ts (Axios 封装 + Token + 防抖 + Toast)       |
+|  - api/ai.ts, api/module/wechat.ts, group.ts 等             |
+|  - Dexie IndexedDB (db.ts)                                  |
+|      * chatSessions / contactsUnified / contactLabelMap     |
+|      * userLoginRecords                                     |
+-------------------------------------------------------------+
+```
+
+### 8.2 PC 微信客服工作台页面线框（/pc/weChat）
+
+```text
+-----------------------------------------------------------------------------------+
+|                                顶部导航 NavCommon                                 |
+|                             [ 触客宝 | 用户信息 | 其他入口 ]                        |
+-----------------------------------------------------------------------------------+
+|                                                                                   |
+|  +------------------------+------------------------------------+----------------+ |
+|  | 左侧侧边栏 SidebarMenu |            中间聊天窗口 ChatWindow | 右侧信息栏      | |
+|  |                        |                                    | ProfileCard 等 | |
+|  |  - 账号/设备切换       |  +------------------------------+  |                | |
+|  |  - 会话列表 MessageList|  | 聊天消息列表 MessageList     |  |  - 客户画像   | |
+|  |      * 虚拟滚动        |  |  (VirtualizedMessageList)    |  |  - 朋友圈动态 | |
+|  |      * 未读数          |  |  - 文本/图片/语音/视频/...   |  |  - 快捷话术   | |
+|  |  - 好友/群/客户列表    |  |  - 各种系统消息类型组件      |  |  - AI 配置    | |
+|  |  - 朋友圈入口          |  +------------------------------+  |                | |
+|  |  - 添加好友/发起会话   |  | 输入区 MessageEnter          |  |                | |
+|  |                        |  |  - 文本输入                  |  |                | |
+|  |                        |  |  - 表情 EmojiPicker          |  |                | |
+|  |                        |  |  - 文件/图片/语音/视频上传   |  |                | |
+|  |                        |  |  - AI 建议文案 (quote…)      |  |                | |
+|  +------------------------+------------------------------------+----------------+ |
+|                                                                                   |
+-----------------------------------------------------------------------------------+
+| 底部（可选）：全局提示 / 更新提示 UpdateNotification                                |
+-----------------------------------------------------------------------------------+
+```
+
+### 8.3 PowerCenter 能力中心线框（简版）
+
+```text
+----------------------------------------------------------------------------+
+|                          /pc/powerCenter                                   |
+----------------------------------------------------------------------------+
+| 顶部：Tab / 菜单导航                                                       |
+|  [ 客户管理 ] [ 沟通记录 ] [ 内容管理 ] [ AI 训练 ] [ 自动欢迎 ] [ 推送助手 ] ... |
+----------------------------------------------------------------------------+
+| 内容区：根据当前子路由渲染                                                 |
+|  - 客户管理: 列表 + 筛选 + 详情侧滑抽屉                                   |
+|  - 沟通记录: 时间线/列表 + 搜索                                            |
+|  - 内容管理: 素材列表 + 编辑弹窗 + 预览 + 定时发布配置                     |
+|  - AI 训练: 话术库配置、模型参数设置                                      |
+|  - 自动欢迎: 规则列表 + 开关 + 编辑                                       |
+|  - 推送助手: 创建推送任务多步骤向导（选择账号 -> 选人群 -> 配置内容 -> 发送） |
+----------------------------------------------------------------------------+
+```
+
+---
+
+以上内容即为当前 Touchkebao 前端工程的高层功能架构说明，可作为后续架构演进、文档输出、分享 PPT 的基础材料。
--- a/Touchkebao/提示词/触客宝功能逻辑流程图.md
+++ b/Touchkebao/提示词/触客宝功能逻辑流程图.md
@@ -0,0 +1,523 @@
+## 触客宝功能逻辑实现流程图
+
+> 本文档基于《触客宝功能架构》整理关键业务链路的**实现流程**，以文本 + ASCII 流程图的形式展示前端在不同场景下的调用关系，便于开发/排查问题与架构沟通。
+
+---
+
+## 一、应用启动 & 初始化流程
+
+### 1.1 启动总体流程
+
+```text
+浏览器访问页面
+    |
+    v
+加载 index.html & Vite 入口脚本
+    |
+    v
+执行 src/main.tsx
+    |
+    v
+初始化 Sentry (initSentry)
+    |
+    v
+initializeDatabaseFromPersistedUser()
+    |
+    +-- 读取 localStorage 中 USER_STORE
+    |       |
+    |       +-- 无用户信息 -> 不初始化 DB -> 返回 null
+    |       |
+    |       +-- 有用户信息 -> 解析 user.id -> ensureDatabase(userId)
+    |                      |
+    |                      +-- DatabaseManager 创建/打开 Dexie DB
+    |
+    v
+创建 React Root
+    |
+    v
+<ConfigProvider zhCN>
+  <QueryProvider>
+    <App />
+  </QueryProvider>
+</ConfigProvider>
+    |
+    v
+App.tsx 内部:
+  Sentry.ErrorBoundary 包裹 AppRouter + UpdateNotification
+```
+
+---
+
+## 二、路由跳转 & 权限控制流程
+
+### 2.1 路由解析与渲染
+
+```text
+AppRouter 渲染
+    |
+    v
+import.meta.glob("./module/*.{ts,tsx}")
+    |
+    v
+收集所有路由模块 default 导出路由数组
+    |
+    v
+组合得到 routes[]
+    |
+    v
+对每个 route:
+    如果 route.auth === true
+        -> 用 <PermissionRoute> 包裹
+    否则
+        -> 直接使用 route.element
+    |
+    v
+追加 404 路由 { path: "*", element: <NotFound /> }
+    |
+    v
+useRoutes(routes) 生成路由树并渲染
+```
+
+### 2.2 权限路由（登录 & 角色校验）
+
+```text
+用户访问受保护路由 (route.auth = true)
+        |
+        v
+渲染 <PermissionRoute requiredRole={...}>
+        |
+        v
+从 useUserStore 读取 user, isLoggedIn
+        |
+        +-- 若 !isLoggedIn 或 !user
+        |       |
+        |       +-- 记录当前路径 currentPath = pathname + search
+        |       |
+        |       +-- navigate("/login?returnUrl=" + encodeURIComponent(currentPath))
+        |       |
+        |       +-- 不渲染子组件 (return null)
+        |
+        +-- 若 requiredRole 存在 且 user.isAdmin !== 1
+        |       |
+        |       +-- navigate("/")
+        |       +-- return null
+        |
+        +-- 否则 (已登录 & 权限满足)
+                |
+                +-- 渲染 children (真正的业务页面)
+```
+
+---
+
+## 三、首页访问 & 端类型分流流程
+
+### 3.1 `/` 首页逻辑
+
+```text
+用户访问 "/" 路径
+    |
+    v
+渲染 IndexPage (pages/index.tsx)
+    |
+    v
+useEffect(() => {
+    判断是否移动端:
+       - UA 匹配移动端关键字
+       - 或 window.innerWidth <= 768
+})
+    |
+    +-- 若 isMobile === true
+    |       |
+    |       +-- navigate("/mobile/dashboard")
+    |
+    +-- 若 isMobile === false
+            |
+            +-- navigate("/pc/weChat")
+    |
+    v
+页面本身只渲染简单 "首页" 占位，主要职责是分流
+```
+
+---
+
+## 四、登录流程 & 本地缓存初始化
+
+> 下面为前端视角，后端返回细节略去，仅关注状态/存储/跳转。
+
+```text
+用户在 /login 输入账号密码
+    |
+    v
+点击登录按钮 -> 触发登录 API
+    |
+    v
+调用 request("/login", formData, "POST")
+    |
+    v
+Axios 请求拦截器:
+  - 若有 token 则附加 Authorization (首次通常无)
+    |
+    v
+服务器返回登录结果 { code/success, data: { user, token } }
+    |
+    v
+响应拦截器:
+  - 判断业务成功
+  - 返回 data (user, token)
+    |
+    v
+前端登录逻辑:
+  - 调用 useUserStore.setState():
+      * 保存 user 信息
+      * 保存 token
+      * 标记 isLoggedIn = true
+  - 按 returnUrl 或默认路径跳转:
+      * 若 URL 中有 ?returnUrl=xxx -> navigate(xxx)
+      * 否则 -> navigate("/")
+    |
+    v
+后续刷新页面:
+  - main.tsx 中 initializeDatabaseFromPersistedUser()
+  - 根据持久化 user.id 初始化对应 Dexie 数据库
+```
+
+---
+
+## 五、PC 端微信客服工作台整体流程（/pc/weChat）
+
+### 5.1 页面三栏布局渲染流程
+
+```text
+用户访问 "/pc/weChat"
+    |
+    v
+路由匹配 pc.tsx 中:
+  path: "/pc", element: <CkboxPage />, children: [...]
+    |
+    v
+渲染 CkboxPage:
+  <Layout header={<NavCommon title="触客宝" />}>
+     <Outlet />   // 当前为 WeChatPage
+  </Layout>
+    |
+    v
+WeChatPage 内部:
+  - 左侧 SidebarMenu (会话列表 / 联系人列表 / 朋友圈入口)
+  - 中间 ChatWindow (消息列表 + 输入框)
+  - 右侧 ProfileCard 等（客户画像/朋友圈/话术等）
+```
+
+### 5.2 选择会话 & 加载消息流程
+
+```text
+用户在 SidebarMenu 中点击某个好友/群聊
+    |
+    v
+onContactClick(contact) 触发
+    |
+    v
+useWeChatStore.setCurrentContact(contact)
+    |
+    v
+setCurrentContact 内部逻辑:
+  1) 清除 AI 请求定时器 & 队列 (防止跨会话 AI 干扰)
+  2) 重置当前聊天状态:
+       - currentMessages = []
+       - currentMessagesPage = 1
+       - currentMessagesHasMore = true
+       - isLoadingAiChat = false
+  3) 构造 params:
+       - 单聊: wechatFriendId = contact.id
+       - 群聊: wechatChatroomId = contact.id
+  4) 调用 clearUnreadCount1/2 清空未读
+  5) 调用 getFriendInjectConfig 获取 AI 配置
+       -> 更新 aiQuoteMessageContent
+  6) 更新 currentContract = contact
+     并更新 currentMessagesRequestId
+  7) 调用 updateConfig({ id: contact.id, config: { chat: true } })
+  8) 调用 state.loadChatMessages(true) 拉取首屏消息
+```
+
+### 5.3 拉取聊天消息流程（首屏 & 翻页）
+
+```text
+调用 loadChatMessages(Init, pageOverride?)
+    |
+    v
+从 store 读取:
+  - currentContract
+  - currentMessagesPage / PageSize / HasMore
+  - currentMessagesRequestId
+    |
+    +-- 若无 currentContract 或 id -> 直接返回
+    +-- 若 !Init 且 !HasMore -> 不再请求
+    +-- 若 messagesLoading && !Init -> 避免并发重复加载
+    |
+    v
+计算 nextPage:
+  - Init === true ? 1 : (pageOverride || currentPage + 1)
+  limit = currentMessagesPageSize (默认 20)
+    |
+    v
+构造请求参数 params:
+  - wechatAccountId: contact.wechatAccountId
+  - page, limit
+  - 单聊: wechatFriendId = contact.id
+  - 群聊: wechatChatroomId = contact.id
+    |
+    v
+根据是否群聊:
+  - 群聊: 调用 getChatroomMessages(params)
+  - 单聊: 调用 getChatMessages(params)
+    |
+    v
+normalizeMessages(response) 标准化为数组
+    |
+    v
+sortMessagesByTime(messages) 统一按时间排序
+    |
+    v
+resolvePaginationState(response, page, limit, listLength)
+    |
+    v
+若 Init 且为群聊:
+  - 额外调用 getGroupMembers({ id: contact.id })
+    |
+    v
+set(state => {
+   若 currentMessagesRequestId 未变化 && currentContract.id 未变化
+      - Init: currentMessages = sortedMessages
+      - 非 Init: currentMessages = [...sortedMessages, ...原有]
+      - 更新 currentGroupMembers (群聊首屏时)
+      - 更新 page / limit / hasMore
+})
+```
+
+---
+
+## 六、新消息接收 & AI 自动回复流程
+
+### 6.1 新消息接收（WebSocket → Store）
+
+```text
+WebSocket 收到新消息 (CmdNewMessage)
+    |
+    v
+WebSocket 层解析消息 -> 调用 useWeChatStore.receivedMsg(message)
+    |
+    v
+receivedMsg(message) 内部:
+  1) 判断消息归属:
+       - getMessageId = message.wechatChatroomId || message.wechatFriendId
+       - isWechatGroup = !!message.wechatChatroomId
+  2) 判断是否为当前选中会话:
+       - 若 currentContract && currentContract.id == getMessageId
+           -> 进入“当前会话处理分支”
+       - 否则
+           -> 当前函数不更新会话列表，MessageList 通过其他事件更新
+```
+
+### 6.2 当前会话消息的批量渲染优化
+
+```text
+当前会话处理分支:
+    |
+    v
+将 message 推入 messageBatchQueue
+    |
+    v
+若已有 messageBatchTimer:
+    -> clearTimeout(messageBatchTimer)
+    |
+    v
+设置新的 messageBatchTimer (延迟 ~16ms):
+    |
+    v
+定时器触发:
+  - 拷贝 messageBatchQueue -> messagesToAdd
+  - 清空 messageBatchQueue
+  - set(state => {
+        currentMessages = [...state.currentMessages, ...messagesToAdd]
+    })
+    |
+    v
+实现一帧内多条消息合并更新，降低渲染压力
+```
+
+### 6.3 AI 自动回复决策流程
+
+```text
+在 receivedMsg 中 (仍然是当前会话分支):
+    |
+    v
+若 message.msgType === 1 (文字) 且 !message.isSend
+   且 currentContract.aiType in [1, 2]
+    |
+    v
+AI 触发逻辑:
+  1) 若存在 aiRequestTimer 或 currentAiGenerationId:
+        - 调用 clearAiRequestQueue("收到新消息")
+        - 清除上一次 AI 请求状态
+  2) 将当前 message 加入 pendingMessages 队列
+  3) set({ isLoadingAiChat: true })
+  4) 启动 aiRequestTimer (延迟 AI_REQUEST_DELAY=3000ms):
+        |
+        v
+        定时器回调:
+          - 复制 pendingMessages -> messagesToProcess
+          - 清空 pendingMessages, 清除 aiRequestTimer
+          - 生成 generationId = generateAiId()
+          - currentAiGenerationId = generationId
+          - 构造 dataProcessing 参数:
+               * type: "CmdNewMessage"
+               * wechatAccountId
+               * chatroomMessage 或 friendMessage = messagesToProcess
+          - 调用 dataProcessing(params)
+          - 若 dataProcessingResult 不为成功标志 (注意实际判断逻辑)
+                -> 取最后一条消息 lastMessage
+                -> 调用 aiChat({ friendId/getMessageId, wechatAccountId, message: lastMessage })
+                -> 得到 aiResponseContent
+                -> 若 currentAiGenerationId 仍等于 generationId (确保未被取消)
+                      |
+                      v
+                      根据 aiType 分支:
+                        - aiType === 2 (AI 接管模式)
+                            * 构造本地发送消息 localMessage
+                            * 将 localMessage append 到 currentMessages
+                            * 调用 useWebSocketStore.sendCommand("CmdSendMessage", {...})
+                            * set({ isLoadingAiChat: false })
+                            * 清空 currentAiGenerationId
+                        - aiType === 1 (AI 辅助模式)
+                            * set({
+                                quoteMessageContent: aiResponseContent,
+                                isLoadingAiChat: false
+                              })
+                            * 清空 currentAiGenerationId
+          - 若中途任何错误:
+                -> 打印错误日志
+                -> set({ isLoadingAiChat: false })
+                -> currentAiGenerationId = null
+```
+
+### 6.4 手动触发 AI 回复流程
+
+```text
+用户在 UI 中点击“智能回复”按钮
+    |
+    v
+调用 manualTriggerAi()
+    |
+    v
+manualTriggerAi 逻辑:
+  1) 读取 currentContract, currentMessages
+  2) 若无 currentContract 或 currentMessages 为空 -> 返回 false
+  3) 校验 aiType in [1, 2]，否则不触发
+  4) 若已有 aiRequestTimer 或 currentAiGenerationId:
+        -> clearAiRequestQueue("手动重新生成")
+  5) 从 currentMessages 中过滤最近 5 条对方文本消息 recentMessages
+  6) set({ isLoadingAiChat: true })
+  7) 生成 generationId, 记录到 currentAiGenerationId
+  8) 调用 aiChat({ friendId, wechatAccountId, message: lastMessage })
+  9) 根据 aiType:
+        - aiType === 2:
+            * 构造本地消息 localMessage，append 到 currentMessages
+            * sendCommand("CmdSendMessage", {...})
+            * set({ isLoadingAiChat: false })
+        - aiType === 1:
+            * updateQuoteMessageContent(aiResponseContent)
+            * set({ isLoadingAiChat: false })
+ 10) 清空 currentAiGenerationId
+```
+
+---
+
+## 七、消息搜索 & 历史记录查看流程
+
+```text
+用户在聊天窗口打开“聊天记录搜索”面板
+    |
+    v
+选择时间范围 (From, To)、输入关键字 keyword、设置数量 Count
+    |
+    v
+调用 useWeChatStore.SearchMessage({ From, To, keyword, Count })
+    |
+    v
+SearchMessage 内部:
+  1) set({ messagesLoading: true })
+  2) 判断当前会话是群聊还是单聊
+  3) 构造 params:
+       - wechatAccountId
+       - keyword
+       - From, To
+       - page = 1
+       - limit = Count
+       - 单聊: wechatFriendId
+       - 群聊: wechatChatroomId
+  4) 调用对应 API:
+       - 群聊: getChatroomMessages(params) + getGroupMembers({ id })
+       - 单聊: getChatMessages(params)
+  5) 对返回结果:
+       - normalizeMessages -> sortMessagesByTime
+       - set({
+            currentMessages,
+            currentGroupMembers (群聊),
+            currentMessagesPage = 1,
+            currentMessagesHasMore = false,
+            currentMessagesPageSize = Count
+         })
+  6) finally: set({ messagesLoading: false })
+```
+
+---
+
+## 八、PowerCenter 能力中心典型流程（示例：创建消息推送任务）
+
+> 这里只给出“消息推送助手”的高层流程，实际每个步骤内部还会调用共用选择组件和上传组件。
+
+```text
+用户访问 "/pc/powerCenter/message-push-assistant"
+    |
+    v
+展示推送任务列表 + “新建推送任务”按钮
+    |
+    v
+点击“新建推送任务”
+    |
+    v
+navigate("/pc/powerCenter/message-push-assistant/create-push-task/:pushType")
+    |
+    v
+渲染 CreatePushTask 页面 (多步骤向导):
+  Step 1: StepSelectAccount
+      - 使用 AccountSelection / DeviceSelection 组件
+      - 选择推送使用的微信/设备账号
+  Step 2: StepSelectContacts
+      - 调用联系人/分组相关 API
+      - 使用 FriendSelection / GroupSelection / PoolSelection 等组件
+      - 支持搜索/筛选与多选
+  Step 3: StepPushParams
+      - 设置推送参数 (时间、频次、规则等)
+  Step 4: StepSendMessage
+      - 选择消息内容:
+          * 直接输入文本
+          * 从内容库选择: ContentSelection + 内容管理 API
+      - 支持图片/文件/视频等资源上传 (复用 Upload 组件)
+    |
+    v
+完成配置 -> 点击“创建任务”
+    |
+    v
+调用创建任务 API
+    |
+    v
+成功后:
+  - 弹出成功提示
+  - 跳转回任务列表或详情页
+  - 列表数据可能通过 React Query 或手动刷新获取最新状态
+```
+
+---
+
+以上流程图覆盖了应用启动、路由与权限、登录、PC 微信客服工作台、AI 自动回复、消息搜索以及能力中心中一个典型场景的端到端逻辑，可作为排查问题和设计新功能时的“全局参考图”。
+如需更详细的**时序图（Sequence Diagram）**或针对某个子模块（例如 IndexedDB 同步、WebSocket 重连策略等）的专门流程图，可以在此文档基础上再拆分子章节。