# 消息管理系统部署和使用指南

## 系统概述

基于 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 语法是否规范