287 lines
7.6 KiB
Markdown
287 lines
7.6 KiB
Markdown
# 消息管理系统部署和使用指南
|
||
|
||
## 系统概述
|
||
|
||
基于 UTS Android 规范开发的消息管理系统，具备完整的消息发送、接收、管理功能。系统采用 Supabase 作为后端数据库，支持实时消息推送和离线存储。
|
||
|
||
## 系统架构
|
||
|
||
```
|
||
/pages/msg/ # 消息页面
|
||
├── index.uvue # 消息列表页面
|
||
├── detail.uvue # 消息详情页面
|
||
└── compose.uvue # 写消息页面
|
||
|
||
/components/message/ # 消息组件
|
||
├── MessageItem.uvue # 消息项组件
|
||
├── MessageList.uvue # 消息列表组件
|
||
├── MessageSearch.uvue # 消息搜索组件
|
||
├── MessageStats.uvue # 消息统计组件
|
||
└── MessageInput.uvue # 消息输入组件
|
||
|
||
/utils/ # 工具和服务层
|
||
├── msgTypes.uts # 类型定义
|
||
├── msgUtils.uts # 工具函数
|
||
├── msgDataServiceReal.uts # 真实数据服务（统一使用）
|
||
└── msgSystemInit.uts # 系统初始化配置
|
||
```
|
||
|
||
## 部署步骤
|
||
|
||
### 1. 数据库准备
|
||
|
||
1. 执行 `message_system.sql` 创建所有必要的数据表：
|
||
- `ak_message_types` # 消息类型表
|
||
- `ak_messages` # 消息主表
|
||
- `ak_message_recipients` # 消息接收记录表
|
||
- `ak_message_groups` # 消息群组表
|
||
- `ak_message_group_members` # 群组成员表
|
||
|
||
2. 确保数据库表结构与 `msgTypes.uts` 中的类型定义一致
|
||
|
||
### 2. Supabase 配置
|
||
|
||
1. 在 Supabase 项目中创建上述数据表
|
||
2. 配置行级安全策略（RLS）
|
||
3. 获取项目 URL 和 anon key
|
||
|
||
### 3. 项目配置
|
||
|
||
消息系统会自动使用项目中现有的 Supabase 配置：
|
||
|
||
1. 确保 `/ak/config.uts` 中的 Supabase 配置正确：
|
||
|
||
```typescript
|
||
export const SUPA_URL = 'https://your-project-id.supabase.co'
|
||
export const SUPA_KEY = 'your-actual-anon-key'
|
||
```
|
||
|
||
2. 确保 `App.uvue` 中已调用初始化：
|
||
|
||
```typescript
|
||
onLaunch: function () {
|
||
initMessageSystem()
|
||
}
|
||
```
|
||
|
||
### 4. 组件注册
|
||
|
||
确保所有消息组件已在需要的页面中正确导入和注册。
|
||
|
||
## 功能特性
|
||
|
||
### 消息类型管理
|
||
- 支持多种消息类型（系统、训练、聊天等）
|
||
- 可配置消息图标、颜色、优先级
|
||
- 支持消息过期和自动删除
|
||
|
||
### 消息发送
|
||
- 支持文本、富文本消息
|
||
- 支持定时发送
|
||
- 支持紧急消息标记
|
||
- 支持群发和单发
|
||
|
||
### 消息接收
|
||
- 实时消息推送
|
||
- 消息状态管理（未读/已读）
|
||
- 消息分类筛选
|
||
- 支持搜索功能
|
||
|
||
### 消息管理
|
||
- 批量操作（标记已读、删除）
|
||
- 消息转发和回复
|
||
- 消息统计和报表
|
||
- 消息归档管理
|
||
|
||
## API 接口
|
||
|
||
### 核心数据服务方法
|
||
|
||
```typescript
|
||
// 获取消息类型
|
||
MsgDataServiceReal.getMessageTypes(): Promise<ApiResponse<Array<MessageType>>>
|
||
|
||
// 获取消息列表
|
||
MsgDataServiceReal.getMessages(params: MessageQueryParams): Promise<ApiResponse<PagedResponse<Message>>>
|
||
|
||
// 获取消息详情
|
||
MsgDataServiceReal.getMessageById(id: string): Promise<ApiResponse<Message>>
|
||
|
||
// 发送消息
|
||
MsgDataServiceReal.sendMessage(params: SendMessageParams): Promise<ApiResponse<Message>>
|
||
|
||
// 标记已读
|
||
MsgDataServiceReal.markAsRead(messageId: string, receiverId: string): Promise<ApiResponse<boolean>>
|
||
|
||
// 删除消息
|
||
MsgDataServiceReal.deleteMessage(messageId: string, userId: string): Promise<ApiResponse<boolean>>
|
||
|
||
// 批量操作
|
||
MsgDataServiceReal.batchOperation(messageIds: Array<string>, operation: string, userId: string): Promise<ApiResponse<boolean>>
|
||
|
||
// 获取统计
|
||
MsgDataServiceReal.getMessageStats(userId: string): Promise<ApiResponse<MessageStats>>
|
||
|
||
// 搜索用户
|
||
MsgDataServiceReal.searchUsers(keyword: string): Promise<ApiResponse<Array<UserOption>>>
|
||
|
||
// 获取群组
|
||
MsgDataServiceReal.getGroups(userId: string): Promise<ApiResponse<Array<GroupOption>>>
|
||
```
|
||
|
||
## 使用示例
|
||
|
||
### 1. 显示消息列表
|
||
|
||
```vue
|
||
<template>
|
||
<view>
|
||
<!-- 导航到消息列表页面 -->
|
||
<navigator url="/pages/msg/index">
|
||
<text>消息中心</text>
|
||
</navigator>
|
||
</view>
|
||
</template>
|
||
```
|
||
|
||
### 2. 发送消息
|
||
|
||
```vue
|
||
<template>
|
||
<view>
|
||
<!-- 导航到写消息页面 -->
|
||
<navigator url="/pages/msg/compose">
|
||
<text>写消息</text>
|
||
</navigator>
|
||
</view>
|
||
</template>
|
||
```
|
||
|
||
### 3. 使用消息组件
|
||
|
||
```vue
|
||
<template>
|
||
<view>
|
||
<!-- 使用消息统计组件 -->
|
||
<msg-stats></msg-stats>
|
||
|
||
<!-- 使用消息列表组件 -->
|
||
<msg-list :messages="messages"></msg-list>
|
||
</view>
|
||
</template>
|
||
|
||
<script setup lang="uts">
|
||
import { MsgDataServiceReal } from '@/utils/msgDataServiceReal.uts'
|
||
|
||
const messages = ref<Array<Message>>([])
|
||
|
||
onMounted(async () => {
|
||
const response = await MsgDataServiceReal.getMessages({
|
||
page: 1,
|
||
limit: 20,
|
||
receiver_id: getCurrentUserId(),
|
||
// ... 其他参数
|
||
})
|
||
if (response.success) {
|
||
messages.value = response.data.items
|
||
}
|
||
})
|
||
</script>
|
||
```
|
||
|
||
## 开发和测试
|
||
|
||
### 统一使用真实数据服务
|
||
|
||
现在只有一个统一的数据服务 `MsgDataServiceReal`，直接使用 `aksupainstance.uts` 中的 supa 实例：
|
||
|
||
```typescript
|
||
import { MsgDataServiceReal } from '@/utils/msgDataServiceReal.uts'
|
||
|
||
// 直接调用，无需手动初始化
|
||
const response = await MsgDataServiceReal.getMessages(params)
|
||
```
|
||
|
||
### 数据服务的改进
|
||
|
||
- 🔄 统一的数据服务接口
|
||
- 🔗 直接使用 `aksupainstance.uts` 中的 supa 实例
|
||
- 🚀 无需手动初始化，简化使用
|
||
- 📱 完全兼容 UTS Android 规范
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
### UTS Android 兼容性
|
||
|
||
1. **类型定义**：全部使用 `type`，不使用 `interface`
|
||
2. **判空处理**：使用 `!== null`，避免 `!== undefined`
|
||
3. **数组操作**：使用 `Array<T>`，避免 `map`、`forEach` 等高阶函数
|
||
4. **变量声明**：明确使用 `let`、`const`
|
||
5. **类型转换**：避免复杂的类型断言
|
||
|
||
### 性能优化
|
||
|
||
1. **分页加载**：消息列表采用分页加载，避免一次性加载大量数据
|
||
2. **缓存策略**：消息类型等静态数据可以缓存
|
||
3. **按需加载**：消息详情按需加载，避免预加载
|
||
4. **批量操作**：支持批量标记已读、删除等操作
|
||
|
||
### 安全考虑
|
||
|
||
1. **权限控制**：确保用户只能访问有权限的消息
|
||
2. **数据验证**：所有输入数据都需要验证
|
||
3. **XSS防护**：消息内容需要进行 HTML 转义
|
||
4. **SQL注入防护**：使用参数化查询
|
||
|
||
## 扩展开发
|
||
|
||
### 1. 添加新的消息类型
|
||
|
||
1. 在数据库 `ak_message_types` 表中添加新记录
|
||
2. 更新页面UI支持新类型的图标和样式
|
||
3. 如需特殊处理逻辑，更新相关组件
|
||
|
||
### 2. 添加新的消息操作
|
||
|
||
1. 在 `MsgDataServiceReal` 中添加新的API方法
|
||
2. 在消息列表或详情页面添加操作按钮
|
||
3. 实现相应的事件处理逻辑
|
||
|
||
### 3. 集成推送通知
|
||
|
||
1. 配置 Supabase 实时订阅
|
||
2. 在消息接收时触发本地通知
|
||
3. 处理通知点击跳转逻辑
|
||
|
||
## 问题排查
|
||
|
||
### 常见问题
|
||
|
||
1. **Supabase 连接失败**：检查 URL 和 API Key 配置
|
||
2. **权限错误**：检查 RLS 策略配置
|
||
3. **类型错误**：确保所有类型定义与数据库字段匹配
|
||
4. **页面跳转失败**：检查路由配置和参数传递
|
||
|
||
### 调试建议
|
||
|
||
1. 启用 console.log 输出查看数据流
|
||
2. 使用模拟数据进行功能验证
|
||
3. 检查网络请求和响应
|
||
4. 验证数据库查询结果
|
||
|
||
## 更新日志
|
||
|
||
- v1.0.0: 初始版本，包含基础消息管理功能
|
||
- v1.1.0: 集成真实 Supabase 数据服务
|
||
- v1.2.0: 添加全局 Supabase 管理器
|
||
- v1.3.0: 完善批量操作和统计功能
|
||
|
||
## 技术支持
|
||
|
||
如有问题，请检查：
|
||
1. 数据库表结构是否正确
|
||
2. Supabase 配置是否正确
|
||
3. 类型定义是否与数据库匹配
|
||
4. UTS Android 语法是否规范
|