135 lines
6.0 KiB
Markdown
135 lines
6.0 KiB
Markdown
|
# 项目文档
|
||
|
|
|
||
|
|
## 1. 技术框架 (Technical Framework)
|
||
|
|
|
||
|
|
本项目基于 **微信小程序 (WeChat Mini Program)** 平台开发。
|
||
|
|
|
||
|
|
* **核心框架**: 微信小程序原生框架 (Native)
|
||
|
|
* **组件框架**: `glass-easel` (在 `app.json` 中配置)
|
||
|
|
* **样式版本**: v2
|
||
|
|
* **插件**: `WechatSI` (微信同声传译插件，版本 0.3.6) - 用于语音识别。
|
||
|
|
* **基础库版本**: 3.11.0
|
||
|
|
|
||
|
|
## 2. 环境 (Environment)
|
||
|
|
|
||
|
|
* **开发工具**: 微信开发者工具 (WeChat DevTools)
|
||
|
|
* **运行环境**: 微信客户端 (iOS/Android/PC)
|
||
|
|
* **API 服务器**: `https://wx-xcx-check.blv-oa.com:4433`
|
||
|
|
* **权限要求**:
|
||
|
|
* `scope.userLocation`: 用于获取用户地理位置 (打卡/显示附近门店)。
|
||
|
|
* `scope.record`: 用于语音输入功能。
|
||
|
|
* `scope.speechRecognition`: 用于语音识别。
|
||
|
|
|
||
|
|
## 3. 项目结构 (Project Structure)
|
||
|
|
|
||
|
|
```text
|
||
|
|
e:\Sync\WxCheck\CommunicationRecords
|
||
|
|
├── app.js # 小程序逻辑
|
||
|
|
├── app.json # 小程序公共配置 (页面路由、窗口设置、插件声明)
|
||
|
|
├── app.wxss # 小程序公共样式
|
||
|
|
├── project.config.json # 项目配置文件
|
||
|
|
├── sitemap.json # 站点地图配置
|
||
|
|
├── assets/ # 静态资源目录
|
||
|
|
├── images/ # 图片资源目录
|
||
|
|
├── pages/ # 页面目录
|
||
|
|
│ ├── chat/ # 聊天/主功能页面
|
||
|
|
│ │ ├── chat.js # 页面逻辑 (核心业务)
|
||
|
|
│ │ ├── chat.json # 页面配置
|
||
|
|
│ │ ├── chat.wxml # 页面结构
|
||
|
|
│ │ ├── chat.wxss # 页面样式
|
||
|
|
│ │ └── mock.js # 本地模拟数据
|
||
|
|
│ └── logs/ # 日志页面 (标准模板)
|
||
|
|
└── utils/ # 工具类目录
|
||
|
|
├── authorize.js # 权限申请工具
|
||
|
|
└── util.js # 通用工具函数 (时间格式化等)
|
||
|
|
```
|
||
|
|
|
||
|
|
## 4. 功能 (Features)
|
||
|
|
|
||
|
|
本项目主要功能为 **"宝来威智能AI"** 对话记录系统，包含以下核心功能：
|
||
|
|
|
||
|
|
1. **智能对话/记录**:
|
||
|
|
* 支持 **文本输入**。
|
||
|
|
* 支持 **语音输入** (按住说话)，利用 `WechatSI` 插件实时转换为文本。
|
||
|
|
2. **消息类型区分**:
|
||
|
|
* 支持发送不同类型的消息 (代码中体现为 `qsendText` 和 `gsendText`，对应 `MessageType` 1 和 2)。
|
||
|
|
* **Tab 切换**: 可在界面上筛选显示 "全部"、"私有" (Type 1) 或 "全局" (Type 2) 消息。
|
||
|
|
3. **历史记录**:
|
||
|
|
* 从服务器分页加载历史对话记录。
|
||
|
|
* **下拉刷新**: 下拉页面加载更早的历史消息。
|
||
|
|
4. **地理位置**:
|
||
|
|
* 发送消息时自动获取当前地理位置 (GCJ02坐标) 并上传。
|
||
|
|
5. **本地缓存**:
|
||
|
|
* 使用 `wx.getStorageSync('openid')` 获取用户标识。
|
||
|
|
|
||
|
|
## 5. 用途 (Usage/Purpose)
|
||
|
|
|
||
|
|
该项目用于 **宝来威 (BLV)** 内部或客户的沟通记录与检查 (WxCheck)。用户可以通过文字或语音的方式记录信息，系统会自动识别语音内容并上传至服务器，同时记录发送时的地理位置。主要用于工作流中的信息采集、汇报或智能助手交互。
|
||
|
|
|
||
|
|
## 6. 数据结构 (Data Structure)
|
||
|
|
|
||
|
|
### 6.1 前端消息对象 (Message Object)
|
||
|
|
在 `chat.js` 的 `msgList` 中使用的数据格式：
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
{
|
||
|
|
id: Number | String, // 消息ID (本地生成或服务器返回)
|
||
|
|
content: String, // 消息内容
|
||
|
|
date: String, // 日期字符串 (YYYY-MM-DD)
|
||
|
|
time: String, // 完整时间字符串 (YYYY-MM-DD HH:mm)
|
||
|
|
isSelf: Number, // 消息类型标识 (1: 私有/用户, 2: 全局/AI)
|
||
|
|
showDate: Boolean // 是否显示日期分割线
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
### 6.2 API 接口数据
|
||
|
|
|
||
|
|
**发送消息 (AddConversation)**
|
||
|
|
* **URL**: `/api/Check/AddConversation`
|
||
|
|
* **Method**: POST
|
||
|
|
* **Request**:
|
||
|
|
```javascript
|
||
|
|
{
|
||
|
|
UserKey: String, // 用户 OpenID
|
||
|
|
ConversationContent: String,// 内容
|
||
|
|
SendMethod: String, // 发送方式 ('text' 或 'voice')
|
||
|
|
UserLocation: String, // 坐标 'latitude,longitude'
|
||
|
|
MessageType: Number // 消息类型 (1 或 2)
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
**获取历史记录 (GetConversationsByPage)**
|
||
|
|
* **URL**: `/api/Check/GetConversationsByPage`
|
||
|
|
* **Method**: POST
|
||
|
|
* **Request**:
|
||
|
|
```javascript
|
||
|
|
{
|
||
|
|
UserKey: String,
|
||
|
|
Page: Number,
|
||
|
|
PageSize: Number,
|
||
|
|
MessageType: Number // 0 代表全部
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## 7. 前端结构和操作流程 (Frontend Structure & Flow)
|
||
|
|
|
||
|
|
### 7.1 核心页面: `pages/chat/chat`
|
||
|
|
|
||
|
|
* **初始化 (`onLoad`)**:
|
||
|
|
1. 调用 `loadHistory()` -> `GetConversations()` 从服务器获取第一页历史数据。
|
||
|
|
2. 调用 `initRecordManager()` 初始化语音识别插件，绑定 `onStart`, `onRecognize`, `onStop`, `onError` 事件。
|
||
|
|
3. 调用 `GetmyScrollhight()` 计算滚动区域高度，适配不同屏幕。
|
||
|
|
|
||
|
|
* **发送消息流程**:
|
||
|
|
* **文本**: 用户输入 -> 点击发送 -> `qsendText`/`gsendText` -> `pushMsg` (渲染到列表) -> `upload` (调用 `wx.getLocation` 获取位置 -> 调用 `post` 上传服务器)。
|
||
|
|
* **语音**: 用户按住按钮 (`handleTouchStart`) -> `manager.start` 开始录音 -> 用户松开 (`handleTouchEnd`) -> `manager.stop` 停止录音 -> `onStop` 回调获取识别文本 -> `pushMsg` & `upload`。
|
||
|
|
|
||
|
|
* **交互细节**:
|
||
|
|
* **上滑取消**: 在录音过程中，如果手指上滑超过一定距离 (`handleTouchMove`)，则触发 "取消发送" 逻辑。
|
||
|
|
* **Tab 切换**: `tabSelect` 函数根据 `isSelf` 字段过滤 `OriginalmsgList` 中的数据，更新 `msgList` 用于渲染。
|
||
|
|
* **下拉加载**: 使用 `scroll-view` 的 `refresher-enabled` 特性，触发 `onRefresh` -> `loadData` 加载下一页数据并拼接到列表头部。
|
||
|
|
|
||
|
|
### 7.2 工具类
|
||
|
|
|
||
|
|
* **`utils/authorize.js`**: 封装了 `authorizeBatch` 函数，用于批量申请小程序权限 (如录音、位置)，采用串行 Promise 链式调用，确保用户依次处理授权请求。
|