# 售后开发底座二次开发与交付手册

> 内部资料，仅供公司开发、交付、售前技术同事使用。本文档用于帮助同事基于当前项目快速完成客户场景二次开发、打包交付和现场排错，不建议直接转发给客户。

## 1. 文档定位

本项目是一个面向售后、设备运维、技术支持团队的本地化开发底座，核心能力可以概括为：

```text
微信售后数据采集 + AI 话题分析 + 知识库沉淀 + Windows 桌面化交付
```

典型使用场景是：客户的售后工程师长期在微信群里处理设备故障、安装调试、备件更换、参数配置、软件升级等问题。项目通过读取本机 PC 微信聊天记录，把群消息、图片、语音、文件等内容接入到本地业务系统，再调用 AI 进行话题归类、问题总结和知识文档生成，最终形成可搜索、可编辑、可持续沉淀的售后知识库。

这套底座适合用于以下客户项目：

- 设备制造企业售后知识库
- 工业现场运维问题沉淀
- 客户服务群自动归档
- 技术支持经验库
- 多客户微信群统一管理
- 企业内部故障案例库
- 针对某个行业的垂直售后 Agent

本文档面向两类同事：

- 开发同事：理解目录结构、接口边界、数据流、二次开发位置、打包方式。
- 交付同事：理解安装部署、AI 配置、客户现场验证、常见问题排查。

## 2. 项目总览

当前项目采用“Electron 桌面壳 + React 前端 + FastAPI 后端 + chatlog 微信数据服务”的组合架构。业务逻辑主要留在前端和 Python 后端，Electron 主要负责桌面运行、进程管理和安装包交付。

### 2.1 核心目录

| 模块 | 路径 | 技术栈 | 主要职责 |
|---|---|---|---|
| 桌面壳 | `electron-launcher/` | Electron | 启动窗口、启动本地服务、管理子进程、打包配置 |
| 前端页面 | `chatlab-web/frontend/` | React + Vite | 聊天记录、AI 话题分析、知识库、设置页面 |
| 业务后端 | `chatlog_fastAPI/` | Python + FastAPI | API 接口、AI 调用、SQLite 数据、定时任务、文件代理 |
| 微信数据服务 | `chatlog.exe` | Windows 可执行程序 | 读取本机 PC 微信数据，提供 `127.0.0.1:5030` API |
| 本地 DLL | `lib/windows_x64/wx_key.dll` | Windows DLL | 配合微信数据能力 |
| 构建脚本 | `scripts/build-desktop.ps1` | PowerShell | 串联前端构建、后端打包、资源复制、安装包生成 |
| 发布目录 | `release/` | 安装包输出 | 存放最终交付的 `ChatLab-Setup-*.exe` |

### 2.2 技术架构

```text
用户打开桌面应用
        |
        v
Electron 主进程
        |
        +--> 启动 chatlog.exe
        |       默认端口: 127.0.0.1:5030
        |
        +--> 启动 FastAPI 后端
        |       开发默认端口: 8000
        |       桌面打包后由 Electron 动态分配本地端口
        |
        +--> 等待 /health 和 chatlog 就绪
        |
        v
Electron 窗口加载业务页面
        |
        v
React 前端调用 FastAPI
        |
        v
FastAPI 调用 chatlog API / AI 模型 / SQLite 数据库
```

### 2.3 运行端口

| 端口 | 服务 | 说明 |
|---|---|---|
| `5030` | `chatlog.exe` | 微信数据服务，提供聊天记录、群聊、图片、语音、文件等底层数据 |
| `8000` | FastAPI | 开发环境常用后端端口，提供业务 API |
| `5173` | Vite | 前端开发服务端口，仅开发环境使用 |

桌面安装包运行时，用户通常不会看到 `5173`，因为生产环境下前端静态资源由 FastAPI 托管。Electron 会启动后端并加载后端地址。

## 3. 环境要求

### 3.1 基础环境

| 软件 | 建议版本 | 说明 |
|---|---|---|
| Windows | Windows 10/11 64 位 | 当前项目优先面向 Windows 桌面交付 |
| PC 微信 | v4 版本 | 需要先登录 PC 微信，系统才能读取本地聊天数据 |
| Node.js | 20+ LTS | 用于前端开发和 Electron 打包 |
| Python | 3.10+ | 用于运行 FastAPI 后端 |
| Python 打包版本 | 3.12 | `scripts/build-desktop.ps1` 默认优先使用 `py -3.12` |

### 3.2 首次依赖安装

后端依赖：

```powershell
cd chatlog_fastAPI
python -m pip install -r requirements.txt
```

前端依赖：

```powershell
cd chatlab-web\frontend
npm install
```

桌面壳依赖：

```powershell
cd electron-launcher
npm install
```

## 4. 本地开发启动

开发时建议按下面顺序启动，方便定位问题。

### 4.1 启动前检查

1. 确认 PC 微信已经登录。
2. 确认当前项目根目录存在 `chatlog.exe`。
3. 确认 `lib/windows_x64/wx_key.dll` 存在。
4. 确认 Node.js、Python 已安装并加入 PATH。
5. 如果客户电脑安全软件拦截 `chatlog.exe`，需要先加入信任或用管理员权限运行。

### 4.2 启动 chatlog 微信数据服务

在项目根目录执行：

```powershell
.\chatlog.exe server
```

服务正常后，默认监听：

```text
http://127.0.0.1:5030
```

可以用以下方式检查版本：

```powershell
.\chatlog.exe version
```

### 4.3 启动 FastAPI 后端

在项目根目录执行：

```powershell
cd chatlog_fastAPI
python main.py
```

开发环境默认地址：

```text
http://127.0.0.1:8000
```

健康检查地址：

```text
http://127.0.0.1:8000/health
```

`/health` 返回中的关键字段：

| 字段 | 说明 |
|---|---|
| `ok` | FastAPI 是否正常 |
| `chatlog_ok` | FastAPI 是否能连通 `chatlog.exe` |
| `chatlog_error` | chatlog 连接失败时的错误信息 |
| `wxid` | 当前识别到的微信账号 |
| `db_path` | 当前使用的知识库数据库路径 |
| `data_dir` | 当前运行数据目录 |

### 4.4 启动 React 前端

在项目根目录执行：

```powershell
cd chatlab-web\frontend
npm run dev
```

开发环境默认访问：

```text
http://localhost:5173
```

### 4.5 启动 Electron 桌面壳

如果需要调试桌面壳：

```powershell
cd electron-launcher
npm run start
```

Electron 的关键职责：

- 打开启动页和业务窗口。
- 启动 `chatlog.exe`。
- 启动 FastAPI 后端。
- 向后端注入运行目录、数据目录、后端端口等环境变量。
- 关闭应用时清理子进程。
- 打包后加载内置前端静态资源。

## 5. 核心业务流程

### 5.1 微信数据读取

前端不直接访问微信数据文件，而是通过 FastAPI 访问业务接口。FastAPI 再根据场景调用 `chatlog.exe` 提供的 API，或通过代理接口把请求转发给 chatlog。

```text
React 页面
  -> FastAPI 业务接口
    -> chatlog API
      -> 本机 PC 微信数据
```

这样做的好处：

- 前端不需要知道 chatlog 的所有底层细节。
- 后端可以统一做数据格式清洗、分页、媒体解析和异常处理。
- 后续接入客户自己的数据源时，可以只改后端适配层。

### 5.2 群聊和聊天记录检索

相关接口族：

| 接口 | 用途 |
|---|---|
| `/api/search/chatrooms` | 搜索或加载群聊列表 |
| `/api/search/sessions` | 获取最近会话列表 |
| `/api/search/members` | 获取某个群的成员列表 |
| `/api/search` | 按群、时间、发送人、关键词查询聊天记录 |

前端主要封装位置：

```text
chatlab-web/frontend/src/api/index.js
```

相关页面：

```text
chatlab-web/frontend/src/pages/ChatlogPage.jsx
```

### 5.3 AI 设置

相关接口：

| 接口 | 用途 |
|---|---|
| `GET /api/settings` | 读取当前 AI 配置 |
| `PUT /api/settings` | 保存 AI 配置 |

配置项包括：

- AI 接口地址
- AI API Key
- 话题分析模型
- 知识总结模型
- 视觉模型
- 语音模型

相关页面：

```text
chatlab-web/frontend/src/pages/SettingsPage.jsx
```

注意事项：

- 不要把 API Key 写死到前端或后端代码。
- 不要把客户真实 Key 写进 `.env` 后再打包。
- 交付前应使用客户现场提供的模型地址和 Key。

### 5.4 话题分析

相关接口族：

| 接口 | 用途 |
|---|---|
| `/api/groups` | 管理需要分析的微信群 |
| `/api/groups/{group_id}/init` | 初始化某个群的话题分析 |
| `/api/groups/{group_id}/task` | 查询分析任务状态 |
| `/api/topics` | 查询或创建话题 |
| `/api/topics/{topic_id}` | 查看、修改、删除单个话题 |
| `/api/topics/{topic_id}/messages` | 向话题添加消息 |
| `/api/topics/{topic_id}/messages/{seq}` | 从话题移除消息 |
| `/api/topics/{topic_id}/summarize` | 基于话题消息生成知识文档 |

主要后端位置：

```text
chatlog_fastAPI/routers/groups.py
chatlog_fastAPI/routers/topics.py
chatlog_fastAPI/services/topic_engine.py
chatlog_fastAPI/services/summary_engine.py
```

主要前端页面：

```text
chatlab-web/frontend/src/pages/TopicsPage.jsx
```

二开常见需求：

- 修改话题分类提示词。
- 增加某个行业的故障类型字段。
- 针对不同客户群使用不同分析模板。
- 把“售后问题”改成“设备巡检”“工单处理”“客户投诉”等业务口径。

### 5.5 知识库

相关接口族：

| 接口 | 用途 |
|---|---|
| `GET /api/knowledge` | 查询知识文档列表，支持关键词 |
| `GET /api/knowledge/{doc_id}` | 查看单篇知识文档 |
| `PATCH /api/knowledge/{doc_id}` | 编辑并保存知识文档 |

相关后端位置：

```text
chatlog_fastAPI/routers/knowledge.py
chatlog_fastAPI/services/fts.py
```

相关前端页面：

```text
chatlab-web/frontend/src/pages/KnowledgePage.jsx
```

知识库使用 SQLite FTS 做全文检索。二开时如果要新增知识字段，应同时考虑：

- 数据表是否需要新增字段。
- 搜索索引是否需要同步更新。
- 前端展示是否要增加筛选条件。
- Word 导出模板是否要同步调整。

### 5.6 文件、图片、语音、视频

相关接口族：

| 接口 | 用途 |
|---|---|
| `/api/files/{md5}` | 根据文件 MD5 获取附件 |
| `/image/{path:path}` | 图片资源代理 |
| `/voice/{path:path}` | 语音资源代理 |
| `/video/{path:path}` | 视频资源代理 |
| `/file/{path:path}` | 文件资源代理 |
| `/data/{path:path}` | 数据资源代理 |

相关后端位置：

```text
chatlog_fastAPI/routers/files.py
chatlog_fastAPI/routers/chatlog_proxy.py
chatlog_fastAPI/services/media_resolver.py
chatlog_fastAPI/services/media_parser.py
```

前端消息展示组件：

```text
chatlab-web/frontend/src/components/MessageBubble.jsx
```

## 6. 接口清单

下面是二开时最常用的接口族。新增能力时，优先复用这些接口边界，不要绕过 FastAPI 直接从前端访问底层数据。

| 接口 | 方法 | 说明 |
|---|---|---|
| `/health` | GET | 后端健康检查，同时检查 chatlog 连接状态 |
| `/api/system/refresh-account` | POST | 强制刷新当前微信账号并切换对应数据库 |
| `/api/system/chatlog-context` | GET/POST | 读取或写入 chatlog 运行上下文 |
| `/api/search` | GET | 聊天记录搜索 |
| `/api/search/chatrooms` | GET | 群聊列表搜索 |
| `/api/search/members` | GET | 群成员列表 |
| `/api/search/sessions` | GET | 最近会话列表 |
| `/api/groups` | GET/POST/PATCH/DELETE | 管理被分析的群 |
| `/api/topics` | GET/POST/PATCH/DELETE | 管理 AI 识别的话题 |
| `/api/knowledge` | GET/PATCH | 管理知识文档 |
| `/api/settings` | GET/PUT | 管理 AI 配置 |
| `/api/ai/parse` | POST | 解析单条消息中的图片、语音、文件等内容 |
| `/api/ai/summarize/stream` | POST | 流式生成聊天摘要 |
| `/api/sse/chatlog` | GET | 聊天记录 SSE 实时订阅 |
| `/api/files/{md5}` | GET | 获取本地附件文件 |
| `/api/v1/{path:path}` | 多方法 | chatlog API 代理接口 |

## 7. 数据目录与数据库

### 7.1 默认数据目录

桌面应用运行时，用户数据默认存放在：

```text
%APPDATA%/ChatLab
```

后端配置来源：

```text
chatlog_fastAPI/config.py
```

关键环境变量：

| 变量 | 说明 |
|---|---|
| `CHATLAB_DATA_DIR` | 指定运行数据目录 |
| `CHATLAB_STATIC_DIR` | 指定前端静态资源目录 |
| `CHATLAB_BACKEND_PORT` | Electron 启动后端时注入的端口 |

### 7.2 微信账号数据库切换

项目会尝试识别当前登录的微信账号 `wxid`，并为不同账号使用不同知识库数据库：

```text
knowledge.db
knowledge_{wxid}.db
```

这样做可以避免同一台电脑上多个微信账号的数据互相污染。

### 7.3 核心数据表

核心表在 `chatlog_fastAPI/database.py` 的 `init_db()` 中初始化：

| 表 | 用途 |
|---|---|
| `groups` | 已添加到系统中进行分析的微信群 |
| `topics` | AI 或人工创建的话题 |
| `topic_messages` | 话题和聊天消息的关联 |
| `knowledge_docs` | 生成后的知识文档 |
| `knowledge_fts` | 知识库全文检索索引 |
| `ai_tasks` | AI 分析和总结任务状态 |
| `app_settings` | AI 地址、模型、Key 等配置 |

## 8. 二次开发指南

### 8.1 开发原则

二开时优先遵守以下原则：

1. 业务入口放前端页面，核心逻辑放 FastAPI 后端。
2. 前端统一通过 `src/api/index.js` 调用接口。
3. 后端新增接口放到 `chatlog_fastAPI/routers/`。
4. 可复用的业务逻辑放到 `chatlog_fastAPI/services/`。
5. 数据结构变更写在 `database.py:init_db()` 中，并兼容老客户数据。
6. AI 能力优先复用现有 `ai_client.py` 和设置页配置。
7. 不要在代码中写死客户名称、API Key、证书密码、客户数据路径。
8. 客户定制内容尽量集中在文案、提示词、模板、配置项，减少对底层架构的改动。

### 8.2 新增前端页面

适用场景：

- 给客户新增一个“工单看板”。
- 新增“设备型号分析”页面。
- 新增“客户问题统计”页面。
- 新增“知识导出”页面。

推荐步骤：

1. 在 `chatlab-web/frontend/src/pages/` 新建页面组件，例如：

```text
chatlab-web/frontend/src/pages/WorkOrderPage.jsx
```

2. 在 `chatlab-web/frontend/src/api/index.js` 中封装接口：

```js
export const getWorkOrders = (params) => api.get('/api/work-orders', { params })
```

3. 在 `chatlab-web/frontend/src/App.jsx` 中增加导航入口和页面渲染分支。
4. 页面样式优先复用现有布局、按钮、表格、侧栏风格。
5. 如果页面依赖后端新接口，先用 Mock 数据搭好界面，再接真实 API。

注意：

- 不建议在页面组件里散落大量 `fetch('/api/...')`。
- 已有 API 封装在 `src/api/index.js`，新接口也应集中管理。
- 新页面应考虑加载中、空数据、错误提示、重试按钮。

### 8.3 新增后端接口

适用场景：

- 给前端新增数据查询接口。
- 接入客户自己的系统数据。
- 增加新的统计分析能力。
- 增加新的导出能力。

推荐步骤：

1. 在 `chatlog_fastAPI/routers/` 新建路由文件，例如：

```text
chatlog_fastAPI/routers/work_orders.py
```

2. 定义 `APIRouter`：

```python
from fastapi import APIRouter

router = APIRouter(prefix="/api/work-orders", tags=["work-orders"])
```

3. 把业务逻辑放入 `chatlog_fastAPI/services/`，例如：

```text
chatlog_fastAPI/services/work_order_service.py
```

4. 在 `chatlog_fastAPI/main.py` 注册新 router：

```python
from routers import work_orders

app.include_router(work_orders.router)
```

5. 在前端 `src/api/index.js` 中封装调用。
6. 在页面中接入接口并处理加载、失败、空数据状态。

注意：

- 接口路径统一使用 `/api/...`。
- 需要访问 chatlog 数据时，优先复用已有 chatlog client 或代理逻辑。
- 不要让前端直接访问 SQLite 文件。

### 8.4 新增数据表或字段

适用场景：

- 给知识文档增加“设备型号”“客户名称”“故障等级”字段。
- 增加工单表。
- 增加客户项目配置表。
- 增加统计缓存表。

推荐步骤：

1. 在 `chatlog_fastAPI/database.py` 的 `init_db()` 中增加 `CREATE TABLE IF NOT EXISTS`。
2. 如果是给老表加字段，先通过 `PRAGMA table_info(...)` 检查字段是否存在。
3. 字段不存在时执行 `ALTER TABLE ... ADD COLUMN ...`。
4. 如果字段影响搜索，更新 FTS 写入逻辑。
5. 如果字段影响前端展示，同步修改接口返回和页面展示。

兼容原则：

- 不要直接删除老字段。
- 不要直接清空老数据。
- 不要假设客户现场数据库一定是最新结构。
- 数据迁移必须可重复执行，多次启动不应报错。

### 8.5 新增 AI 能力

适用场景：

- 新增行业化话题分类。
- 新增设备故障根因分析。
- 新增日报、周报、月报。
- 新增图片识别、语音识别、文件摘要。
- 新增客户指定模板的知识文档生成。

推荐位置：

```text
chatlog_fastAPI/services/ai_client.py
chatlog_fastAPI/routers/ai.py
chatlog_fastAPI/services/topic_engine.py
chatlog_fastAPI/services/summary_engine.py
chatlab-web/frontend/src/pages/SettingsPage.jsx
```

开发原则：

- 模型地址、模型名、API Key 从设置页或后端配置读取。
- Prompt 模板可以放在 service 层，避免散落在前端。
- 客户行业术语、设备型号、输出格式应抽象为可配置文本。
- 生成结果必须允许人工编辑，不能假设 AI 输出完全正确。
- 流式输出接口适合长文档生成，普通接口适合短文本解析。

### 8.6 修改知识文档模板

如果客户要求固定格式，例如“故障现象、影响范围、排查步骤、根因、解决方案、预防措施”，应优先修改总结 Prompt 和前端展示，而不是把模板逻辑写死在多个地方。

推荐字段：

```text
1. 问题标题
2. 适用设备或系统
3. 故障现象
4. 影响范围
5. 排查过程
6. 根本原因
7. 解决方案
8. 预防建议
9. 引用消息时间范围
10. 相关附件或图片
```

相关位置：

```text
chatlog_fastAPI/services/summary_engine.py
chatlab-web/frontend/src/components/ReportDocumentView.jsx
chatlab-web/frontend/src/utils/wordExport.js
```

### 8.7 客户品牌和交付包定制

常见定制项：

| 定制项 | 位置 |
|---|---|
| 应用名称 | `electron-launcher/package.json`、`electron-launcher/electron-builder.config.cjs`、`electron-launcher/main.js` |
| 窗口标题 | `electron-launcher/main.js` |
| 图标 | `scripts/make-icon.cjs`、`electron-launcher/build/` |
| 前端页面标题 | `chatlab-web/frontend/src/App.jsx` 或相关页面 |
| 菜单名称 | `chatlab-web/frontend/src/App.jsx` |
| 安装包名称 | `electron-launcher/electron-builder.config.cjs` |
| 默认 AI 口径 | `chatlog_fastAPI/services/` 中相关 Prompt |

定制时建议先确认：

- 客户对外显示名称。
- 安装包名称。
- 是否需要客户 Logo。
- 是否要隐藏“ChatLab”字样。
- 是否需要增加免责声明或授权说明。

## 9. 配置与数据安全

### 9.1 不允许进入安装包的内容

以下内容禁止进入 `release/` 交付包：

- `.env`
- `knowledge*.db`
- 客户真实聊天记录
- 客户真实 API Key
- 代码签名证书
- 证书密码
- 私钥文件
- `__pycache__`
- 临时测试文件

构建脚本 `scripts/build-desktop.ps1` 已经包含敏感文件扫描逻辑，二开时不得移除或绕过。

### 9.2 API Key 管理

AI API Key 应通过设置页写入系统配置。对外演示、客户现场部署和正式交付时，应由客户或项目负责人提供真实 Key。

日志中不应输出完整 Key。Electron 主进程已有日志脱敏逻辑，二开新增日志时也要遵守同样原则。

### 9.3 客户数据管理

默认数据目录：

```text
%APPDATA%/ChatLab
```

交付时应告知客户：

- 安装包升级不会自动删除本地数据。
- 如果客户要迁移电脑，需要迁移对应 AppData 数据目录。
- 如客户要求卸载时清理数据，需要单独提供清理方案。
- 严禁把客户现场数据库复制回开发机作为测试数据，除非客户明确授权并完成脱敏。

## 10. 桌面打包交付

### 10.1 一键打包

在项目根目录执行：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\build-desktop.ps1
```

脚本会依次完成：

1. 生成或刷新 Electron 图标。
2. 构建 React 前端。
3. 用 PyInstaller 构建 Python 后端。
4. 重置 `electron-launcher/build-resources`。
5. 复制 `chatlog.exe`、`lib/`、前端 `dist/`、后端 `dist/ChatLabBackend/`、许可证文件。
6. 扫描敏感文件，阻止 `.env`、数据库、证书、私钥、缓存进入发布资源。
7. 生成 `release/manifest.txt`。
8. 调用 `electron-builder` 生成 Windows 安装包。
9. 把安装包和 blockmap 复制到 `release/`。
10. 如果启用签名，校验安装包签名状态。

### 10.2 常用跳过参数

调试时可以跳过部分步骤：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\build-desktop.ps1 -SkipIcon
powershell -ExecutionPolicy Bypass -File .\scripts\build-desktop.ps1 -SkipFrontend
powershell -ExecutionPolicy Bypass -File .\scripts\build-desktop.ps1 -SkipBackend
powershell -ExecutionPolicy Bypass -File .\scripts\build-desktop.ps1 -SkipInstaller
```

常见用途：

| 参数 | 用途 |
|---|---|
| `-SkipIcon` | 图标没变时节省时间 |
| `-SkipFrontend` | 前端已经构建过，只调试后端或安装包 |
| `-SkipBackend` | 后端已经构建过，只调试前端或安装包 |
| `-SkipInstaller` | 只生成资源，不生成最终安装包 |

### 10.3 代码签名

未签名安装包在客户电脑上可能触发 Windows SmartScreen 或安全软件提示。正式客户交付建议使用代码签名证书。

通过命令传参：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\build-desktop.ps1 `
  -Sign `
  -CertificateFile "D:\certs\ChatLab-CodeSigning.pfx" `
  -CertificatePassword "证书密码" `
  -PublisherName "证书中的发布者名称" `
  -ForceSign
```

通过环境变量：

```powershell
$env:CHATLAB_PFX_FILE = "D:\certs\ChatLab-CodeSigning.pfx"
$env:CHATLAB_PFX_PASSWORD = "证书密码"
$env:CHATLAB_CERT_PUBLISHER_NAME = "证书中的发布者名称"
$env:CHATLAB_FORCE_SIGN = "1"
powershell -ExecutionPolicy Bypass -File .\scripts\build-desktop.ps1
```

签名相关变量：

| 变量 | 说明 |
|---|---|
| `CHATLAB_PFX_FILE` | PFX/P12 证书完整路径 |
| `CHATLAB_PFX_PASSWORD` | 证书密码 |
| `CHATLAB_CERT_PUBLISHER_NAME` | 可选，证书发布者名称 |
| `CHATLAB_TIMESTAMP_SERVER` | 可选，默认时间戳服务器 |
| `CHATLAB_FORCE_SIGN` | 设置为 `1` 时，签名失败会中断构建 |

证书安全要求：

- 证书文件必须放在项目目录外。
- 不要把证书、私钥、密码提交到项目目录。
- 不要把证书复制到 `electron-launcher/build-resources`。
- 不要把证书路径写入对客户可见的文档。

### 10.4 交付文件

最终交付目录：

```text
release/
```

交付时一般只需要提供最新的：

```text
ChatLab-Setup-*.exe
```

如果客户需要升级包校验或自动更新能力，再根据实际方案提供 `.blockmap` 等配套文件。

## 11. 客户项目落地流程

### 11.1 需求确认

二开前至少确认以下信息：

| 项目 | 需要确认的问题 |
|---|---|
| 客户场景 | 是售后、运维、客服、巡检，还是其他业务 |
| 微信群规模 | 需要分析几个群，每个群大概多少消息 |
| 数据范围 | 是否只分析指定群，是否包含个人聊天 |
| AI 部署 | 使用公网模型、客户内网模型，还是 AgentBox 本地模型 |
| 模型能力 | 是否需要图片识别、语音识别、长文总结 |
| 知识模板 | 客户希望沉淀成什么格式 |
| 权限要求 | 谁能看知识库，是否需要账号系统 |
| 隐私口径 | 是否允许读取 PC 微信数据，是否需要客户授权说明 |
| 交付方式 | 安装包、本地部署、远程协助，还是现场部署 |
| 验收标准 | 客户认为什么结果算成功 |

### 11.2 二开实施顺序

推荐实施顺序：

1. 先跑通原始项目，确认 chatlog、FastAPI、前端、Electron 都正常。
2. 修改客户可见的产品名称、页面文案、菜单名。
3. 修改话题分析 Prompt 和知识文档模板。
4. 根据客户需求新增页面或接口。
5. 增加必要的数据表和迁移逻辑。
6. 接入客户指定 AI 模型地址。
7. 完成前端构建和桌面打包。
8. 在测试机安装，跑完整验收流程。
9. 输出安装包、部署说明、客户现场配置说明。

### 11.3 现场部署步骤

交付同事现场部署建议按下面顺序：

1. 安装 Windows 桌面安装包。
2. 登录 PC 微信。
3. 启动桌面应用。
4. 等待应用完成微信数据识别。
5. 进入设置页配置 AI 地址、API Key、模型名称。
6. 打开聊天记录页，确认群列表和消息可见。
7. 进入 AI 话题分析页，添加一个目标群。
8. 选择一个较小时间范围跑首次分析。
9. 生成一篇知识文档。
10. 进入知识库页搜索关键词。
11. 重启应用，确认配置和知识库数据仍然存在。

### 11.4 验收清单

| 验收项 | 通过标准 |
|---|---|
| 应用能启动 | 桌面应用打开后无白屏、无异常退出 |
| 微信数据可读 | 群列表可见，聊天记录可查询 |
| chatlog 连接正常 | `/health` 中 `chatlog_ok=true` |
| AI 配置可保存 | 设置页保存后刷新仍能看到配置 |
| 话题分析可执行 | 添加群后可以生成话题列表 |
| 知识文档可生成 | 对某个话题可生成结构化知识文档 |
| 知识库可搜索 | 输入关键词能检索到相关文档 |
| 数据可持久化 | 重启后群、话题、知识库仍存在 |
| 安装包可复装 | 卸载重装或覆盖安装后应用可打开 |
| 客户口径一致 | 页面名称、文档模板、提示词符合客户项目要求 |

## 12. 常见问题排查

### 12.1 群列表为空

可能原因：

- PC 微信没有登录。
- `chatlog.exe` 没有启动。
- `5030` 端口被占用或被拦截。
- 微信版本不兼容。
- 安全软件拦截了 `chatlog.exe` 或 DLL。

排查步骤：

1. 确认 PC 微信已登录。
2. 在项目根目录执行 `.\chatlog.exe version`。
3. 启动 `.\chatlog.exe server`。
4. 访问或检查 `http://127.0.0.1:5030` 是否可用。
5. 打开 FastAPI `/health`，查看 `chatlog_ok` 和 `chatlog_error`。
6. 必要时用管理员身份启动应用。

### 12.2 AI 无响应或分析失败

可能原因：

- 设置页没有配置 API Key。
- AI 接口地址不正确。
- 模型名称不正确。
- 客户内网无法访问模型服务。
- 模型不支持当前请求格式。
- 长文本超出模型上下文限制。

排查步骤：

1. 进入设置页检查 AI 接口地址。
2. 检查 API Key 是否为空。
3. 检查话题分析模型、知识总结模型、视觉模型、语音模型名称。
4. 用较小时间范围重新测试。
5. 查看后端日志中的 AI 错误信息。
6. 如果是客户内网模型，确认本机能访问模型服务地址。

### 12.3 前端打不开或白屏

开发环境排查：

- 确认 `npm run dev` 正常运行。
- 确认浏览器访问 `http://localhost:5173`。
- 确认 FastAPI 正常运行。
- 检查浏览器控制台报错。

生产安装包排查：

- 确认安装包内有前端静态资源。
- 确认 `CHATLAB_STATIC_DIR` 指向正确资源目录。
- 确认 Electron 能启动 FastAPI。
- 查看 Electron 启动页日志。

### 12.4 打包失败

常见原因：

- Node.js 未安装或版本过低。
- Python 3.12 未安装。
- PyInstaller 未安装。
- 前端依赖缺失。
- 后端依赖缺失。
- `chatlog.exe` 不存在。
- `lib/windows_x64/wx_key.dll` 不存在。
- 敏感文件扫描发现 `.env`、数据库或证书文件。

排查命令：

```powershell
node -v
npm -v
py -3.12 -V
.\chatlog.exe version
```

重新安装依赖：

```powershell
cd chatlab-web\frontend
npm install

cd ..\..\chatlog_fastAPI
python -m pip install -r requirements.txt
```

### 12.5 客户电脑提示不安全

可能原因：

- 安装包未签名。
- 客户电脑安全策略严格。
- Windows SmartScreen 对未知发布者提示风险。
- 安全软件对读取微信数据的工具敏感。

处理建议：

- 正式交付使用代码签名证书。
- 给客户 IT 提供发布者、安装包哈希、部署说明。
- 必要时由客户 IT 加入白名单。
- 对外说明系统为本地读取和本地分析，不主动发送微信消息。

### 12.6 换微信账号后数据变化

系统会自动识别当前微信账号，并切换到对应数据库。表现为：

- A 账号生成的知识库在 A 账号数据库中。
- B 账号登录后，会切换到 B 账号数据库。
- 切回 A 账号后，A 账号数据仍可继续使用。

如需强制刷新账号：

```text
POST /api/system/refresh-account
```

## 13. 开发交付检查清单

### 13.1 开发完成前

- 新增页面已接入导航。
- 新增接口已在 `main.py` 注册。
- 前端 API 已集中封装到 `src/api/index.js`。
- 数据库变更已写兼容迁移。
- AI Prompt 已按客户场景调整。
- 页面空状态、加载状态、错误状态完整。
- 未写死客户 API Key。
- 未把客户数据放入项目目录。
- 未破坏原有聊天记录、话题分析、知识库功能。

### 13.2 打包前

- `chatlog.exe` 存在且版本检查通过。
- `lib/windows_x64/wx_key.dll` 存在。
- 前端 `npm run build` 成功。
- 后端 PyInstaller 构建成功。
- `release/manifest.txt` 已生成。
- `release/` 中无 `.env`、`knowledge*.db`、证书、私钥。
- 安装包名称、图标、产品名符合客户项目。

### 13.3 交付前

- 在干净测试机安装成功。
- PC 微信登录后群列表正常。
- AI 设置可保存。
- 能完成一次话题分析。
- 能生成一篇知识文档。
- 能搜索知识库。
- 应用重启后数据不丢。
- 客户部署说明已准备。
- 客户隐私和数据使用口径已确认。

## 14. 推荐二开场景示例

### 14.1 设备售后知识库

目标：

- 自动整理客户微信群中的设备故障处理过程。
- 生成标准故障案例。
- 支持按设备型号、故障现象、备件名称搜索。

重点改造：

- 修改话题分析 Prompt，让 AI 关注设备型号、故障现象、处理结论。
- 修改知识文档模板，增加“设备型号”“故障等级”“备件清单”。
- 在知识库页面增加设备型号筛选。

### 14.2 运维日报生成

目标：

- 每天自动总结微信群里的运维事项。
- 输出今日问题、处理中事项、已解决事项、风险提醒。

重点改造：

- 新增日报页面。
- 新增后端日报接口。
- 复用 `/api/search` 拉取当天消息。
- 调用 AI 生成日报。
- 可选增加 Word 导出。

### 14.3 客服投诉归档

目标：

- 从客户服务群中识别投诉、建议、售后问题。
- 按客户、产品线、严重程度归档。

重点改造：

- 修改话题分类规则。
- 新增投诉等级字段。
- 新增统计看板。
- 知识库模板改成“投诉原因、处理过程、补偿方案、复盘建议”。

## 15. 重要注意事项

1. 本系统依赖 PC 微信本地数据读取能力，部署前必须确认客户允许该类本地工具运行。
2. 本系统默认只做读取、分析和归档，不应主动向客户微信群发送消息。
3. AI 生成内容必须允许人工编辑和复核，不能直接作为最终技术结论。
4. 二开时优先控制改动范围，避免同时大改前端、后端、Electron 和打包脚本。
5. 客户现场问题优先看 `/health`、Electron 启动日志、FastAPI 日志、AI 设置页。
6. 打包脚本中的敏感文件扫描是交付安全底线，不要删除。
7. 如果客户需要私有化模型，应先确认模型是否兼容 OpenAI 格式接口。
8. 如果客户群消息量很大，首次分析建议限制时间范围，先小批量验收。

## 16. 快速命令索引

项目根目录：

```powershell
C:\Users\12138\Desktop\get_wechat_new\用户使用版本\大铁\get_wechat_me
```

检查 chatlog 版本：

```powershell
.\chatlog.exe version
```

安装后端依赖：

```powershell
cd chatlog_fastAPI
python -m pip install -r requirements.txt
```

启动后端：

```powershell
cd chatlog_fastAPI
python main.py
```

安装前端依赖：

```powershell
cd chatlab-web\frontend
npm install
```

启动前端：

```powershell
cd chatlab-web\frontend
npm run dev
```

构建前端：

```powershell
cd chatlab-web\frontend
npm run build
```

启动桌面壳：

```powershell
cd electron-launcher
npm run start
```

一键打包：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\build-desktop.ps1
```

只构建资源不生成安装包：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\build-desktop.ps1 -SkipInstaller
```

## 17. 给同事的建议

拿到这个项目后，不建议一开始就改打包脚本或 Electron 主进程。更稳妥的顺序是：

1. 先完整跑通原项目。
2. 再改前端文案和页面。
3. 再改后端 Prompt 和接口。
4. 再做数据库兼容变更。
5. 最后做品牌、图标、安装包名称和签名。

如果客户需求只是“换一个行业场景”，大多数情况下优先改 Prompt、知识文档模板、页面文案和少量字段即可，不需要重构整体架构。