# 情绪博物馆完整功能需求与数据库设计

**文档版本**: v2.0  
**创建时间**: 2025-07-12  
**项目状态**: 基础框架已完成，功能完善中  
**开发框架**: SwiftUI + iOS 18.5  

---

## 📋 目录

- [1. 项目现状分析](#1-项目现状分析)
- [2. 完整功能需求清单](#2-完整功能需求清单)
- [3. 数据库设计](#3-数据库设计)
- [4. 技术架构建议](#4-技术架构建议)
- [5. 实施优先级](#5-实施优先级)

---

## 1. 项目现状分析

### ✅ 已完成功能
- [x] 基础TabView导航框架（记录、治愈、探索、个人）
- [x] 主题系统（深色模式支持）
- [x] 加载状态和骨架屏系统
- [x] 动画过渡效果
- [x] RecordView聊天化改造
- [x] AI对话基础框架
- [x] 情绪日历基础版
- [x] 完整的数据模型定义（DataModels.swift）
- [x] 模拟数据管理系统（MockDataManager.swift）
- [x] 导航管理系统（NavigationManager.swift）
- [x] 主题管理系统（ThemeManager）

### ❌ 待完善功能
- [ ] 完整的AI对话系统
- [ ] 治愈页面（成长课题系统）
- [ ] 探索页面（地图+社区）
- [ ] 个人页面（用户信息+成就）
- [ ] 页面间跳转逻辑
- [ ] 所有弹窗页面的关闭按钮
- [ ] 真实数据存储（Core Data集成）
- [ ] AI服务集成
- [ ] 地图服务集成
- [ ] 语音识别功能

---

## 2. 完整功能需求清单

### 2.1 记录页面（RecordView）

#### 核心功能
1. **智能对话系统**
   - [x] 基础聊天界面
   - [ ] 语音转文字功能
   - [ ] 多模态输入（文字、语音、图片）
   - [ ] AI情绪分析和智能回复
   - [ ] 全屏对话模式
   - [ ] 对话历史记录

2. **情绪日历**
   - [x] 单行日历视图
   - [ ] 日历展开/收起功能
   - [ ] 日期情绪状态标记
   - [ ] 情绪回顾和趋势查看
   - [ ] 情绪数据可视化

3. **对话记录管理**
   - [ ] 聊天记录入口页面（ChatHistoryView）
   - [ ] 对话内容自动保存
   - [ ] 智能分类和标签
   - [ ] 搜索和筛选功能
   - [ ] 对话摘要生成

4. **设置功能**
   - [x] 主题切换基础功能
   - [ ] 完整设置页面（SettingsView）
   - [ ] 音效设置
   - [ ] 隐私设置
   - [ ] 关于页面

### 2.2 治愈页面（GrowthView）

#### 核心功能
1. **个人成长档案**
   - [ ] 成长概览卡片
   - [ ] 五维雷达图（自我感知、情绪韧性、行动力、共情力、生活热度）
   - [ ] 成长轨迹可视化
   - [ ] 个性化成长建议

2. **成长课题系统**
   - [x] 课题数据模型
   - [ ] 课题分类标签界面
   - [ ] 课题详情页面（TopicDetailView）
   - [ ] 课题互动页面（TopicInteractionView）
   - [ ] 进度追踪和等级系统
   - [ ] 课题解锁机制

3. **互动内容**
   - [ ] AI对话互动（TopicChatView）
   - [ ] 知识文章阅读（TopicArticleView）
   - [ ] 练习活动（TopicExerciseView）
   - [ ] 反思日记（TopicReflectionView）
   - [ ] 冥想练习
   - [ ] 小测验

4. **奖励系统**
   - [x] 奖励数据模型
   - [ ] 积分系统
   - [ ] 徽章和称号
   - [ ] 皮肤和道具
   - [ ] 成就展示

### 2.3 探索页面（ExploreView）

#### 核心功能
1. **智能地图系统**
   - [ ] 地图SDK集成（高德地图）
   - [ ] 地点标记和分类
   - [ ] AI推荐地点
   - [ ] 个人收藏地点
   - [ ] 地点详情页面（LocationDetailView）

2. **社区分享系统**
   - [ ] 社区动态页面（CommunityFeedView）
   - [ ] 图文分享功能
   - [ ] 点赞、评论、转发
   - [ ] 内容审核机制
   - [ ] 添加地点页面（AddLocationView）

3. **位置服务**
   - [ ] 地理位置获取
   - [ ] 周边推荐
   - [ ] 导航服务
   - [ ] 隐私保护

4. **视图切换**
   - [ ] 地图模式/社区模式切换
   - [ ] 筛选和排序功能
   - [ ] 搜索功能

### 2.4 个人页面（InsightView/UniverseView）

#### 核心功能
1. **用户信息管理**
   - [ ] 用户资料页面（UserProfileView）
   - [ ] 基础信息编辑
   - [ ] 头像上传
   - [ ] 会员中心

2. **数据统计展示**
   - [ ] 本周数据统计
   - [ ] 累计成就展示
   - [ ] 趋势分析图表
   - [ ] 社交数据统计

3. **成就系统**
   - [x] 成就数据模型
   - [ ] 成就页面（AchievementsView）
   - [ ] 成就分类展示
   - [ ] 进度追踪

4. **快捷功能**
   - [ ] 邀请好友
   - [ ] 数据导出
   - [ ] 反馈建议
   - [ ] 帮助中心

---

## 3. 数据库设计

### 3.1 核心实体关系图

```mermaid
erDiagram
    User ||--o{ Conversation : has
    User ||--o{ EmotionRecord : records
    User ||--o{ GrowthTopic : participates
    User ||--o{ Achievement : earns
    User ||--o{ LocationPin : creates
    User ||--o{ CommunityPost : posts
    
    Conversation ||--o{ Message : contains
    Conversation ||--o| EmotionAnalysis : analyzed_by
    
    GrowthTopic ||--o{ TopicInteraction : has
    GrowthTopic ||--o{ Reward : offers
    GrowthTopic ||--o| TopicContent : contains
    
    LocationPin ||--o{ CommunityPost : located_at
    
    CommunityPost ||--o{ Comment : has
    
    TopicContent ||--o{ Article : includes
    TopicContent ||--o{ ActionSuggestion : includes
```

### 3.2 主要数据表结构

#### 用户表 (User)
| 字段 | 类型 | 说明 | 约束 |
|------|------|------|------|
| id | UUID | 主键 | PRIMARY KEY |
| username | String | 用户名 | UNIQUE, NOT NULL |
| email | String | 邮箱 | UNIQUE, NOT NULL |
| avatar | String? | 头像URL | NULLABLE |
| profile | UserProfile | 用户档案 | NOT NULL |
| createdAt | Date | 创建时间 | NOT NULL |
| lastActiveAt | Date | 最后活跃时间 | NOT NULL |

#### 对话表 (Conversation)
| 字段 | 类型 | 说明 | 约束 |
|------|------|------|------|
| id | UUID | 主键 | PRIMARY KEY |
| userId | UUID | 用户ID | FOREIGN KEY |
| title | String | 对话标题 | NOT NULL |
| startTime | Date | 开始时间 | NOT NULL |
| endTime | Date? | 结束时间 | NULLABLE |
| summary | String? | 对话摘要 | NULLABLE |
| tags | [String] | 标签数组 | NOT NULL |

#### 消息表 (Message)
| 字段 | 类型 | 说明 | 约束 |
|------|------|------|------|
| id | UUID | 主键 | PRIMARY KEY |
| conversationId | UUID | 对话ID | FOREIGN KEY |
| content | String | 消息内容 | NOT NULL |
| type | MessageType | 消息类型 | NOT NULL |
| sender | MessageSender | 发送者 | NOT NULL |
| timestamp | Date | 时间戳 | NOT NULL |
| emotionScore | Float? | 情绪分数 | NULLABLE |
| isRead | Bool | 是否已读 | NOT NULL |

#### 情绪记录表 (EmotionRecord)
| 字段 | 类型 | 说明 | 约束 |
|------|------|------|------|
| id | UUID | 主键 | PRIMARY KEY |
| userId | UUID | 用户ID | FOREIGN KEY |
| date | Date | 记录日期 | NOT NULL |
| emotionType | EmotionType | 情绪类型 | NOT NULL |
| intensity | Float | 情绪强度 | NOT NULL |
| context | String | 情绪背景 | NOT NULL |
| triggers | [String] | 触发因素 | NOT NULL |
| location | String? | 地点 | NULLABLE |
| weather | String? | 天气 | NULLABLE |
| notes | String? | 备注 | NULLABLE |

#### 成长课题表 (GrowthTopic)
| 字段 | 类型 | 说明 | 约束 |
|------|------|------|------|
| id | UUID | 主键 | PRIMARY KEY |
| title | String | 课题标题 | NOT NULL |
| description | String | 课题描述 | NOT NULL |
| category | TopicCategory | 课题分类 | NOT NULL |
| difficulty | Difficulty | 难度等级 | NOT NULL |
| progress | Float | 完成进度 | NOT NULL |
| level | Int | 当前等级 | NOT NULL |
| totalLevels | Int | 总等级数 | NOT NULL |
| isUnlocked | Bool | 是否解锁 | NOT NULL |
| completedAt | Date? | 完成时间 | NULLABLE |
| estimatedDuration | TimeInterval | 预估时长 | NOT NULL |
| prerequisites | [UUID] | 前置课题 | NOT NULL |

#### 地点标记表 (LocationPin)
| 字段 | 类型 | 说明 | 约束 |
|------|------|------|------|
| id | UUID | 主键 | PRIMARY KEY |
| coordinate | Coordinate | 坐标 | NOT NULL |
| title | String | 地点名称 | NOT NULL |
| description | String | 地点描述 | NOT NULL |
| type | LocationType | 地点类型 | NOT NULL |
| emotionTags | [EmotionType] | 情绪标签 | NOT NULL |
| photos | [String] | 图片URLs | NOT NULL |
| createdBy | UUID? | 创建者ID | NULLABLE |
| createdAt | Date | 创建时间 | NOT NULL |
| likes | Int | 点赞数 | NOT NULL |
| visits | Int | 访问数 | NOT NULL |
| address | String? | 详细地址 | NULLABLE |
| category | LocationCategory | 地点分类 | NOT NULL |
| isBookmarked | Bool | 是否收藏 | NOT NULL |

#### 社区帖子表 (CommunityPost)
| 字段 | 类型 | 说明 | 约束 |
|------|------|------|------|
| id | UUID | 主键 | PRIMARY KEY |
| userId | UUID | 用户ID | FOREIGN KEY |
| locationId | UUID? | 地点ID | NULLABLE |
| content | String | 帖子内容 | NOT NULL |
| photos | [String] | 图片URLs | NOT NULL |
| tags | [String] | 标签 | NOT NULL |
| likes | Int | 点赞数 | NOT NULL |
| createdAt | Date | 创建时间 | NOT NULL |
| isPrivate | Bool | 是否私密 | NOT NULL |
| viewCount | Int | 浏览数 | NOT NULL |
| type | PostType | 帖子类型 | NOT NULL |
| authorName | String | 作者名称 | NOT NULL |

#### 成就表 (Achievement)
| 字段 | 类型 | 说明 | 约束 |
|------|------|------|------|
| id | UUID | 主键 | PRIMARY KEY |
| title | String | 成就标题 | NOT NULL |
| description | String | 成就描述 | NOT NULL |
| category | AchievementCategory | 成就分类 | NOT NULL |
| icon | String | 图标名称 | NOT NULL |
| rarity | RewardRarity | 稀有度 | NOT NULL |
| requirement | AchievementRequirement | 解锁条件 | NOT NULL |
| progress | Int | 当前进度 | NOT NULL |
| targetValue | Int | 目标值 | NOT NULL |
| unlockedAt | Date? | 解锁时间 | NULLABLE |
| isHidden | Bool | 是否隐藏 | NOT NULL |

### 3.3 索引设计

#### 主要索引
- User表：username, email, lastActiveAt
- Conversation表：userId, startTime
- Message表：conversationId, timestamp
- EmotionRecord表：userId, date, emotionType
- GrowthTopic表：category, difficulty, isUnlocked
- LocationPin表：coordinate, type, category, createdAt
- CommunityPost表：userId, locationId, createdAt, type
- Achievement表：category, rarity, unlockedAt

#### 复合索引
- EmotionRecord：(userId, date)
- Message：(conversationId, timestamp)
- CommunityPost：(userId, createdAt)
- LocationPin：(type, category)

---

## 4. 技术架构建议

### 4.1 当前架构优势
- ✅ 清晰的MVVM架构
- ✅ 完整的数据模型定义
- ✅ 良好的状态管理（ObservableObject）
- ✅ 模块化的服务层设计
- ✅ 主题系统支持

### 4.2 需要完善的部分

#### 数据持久化
```swift
// 建议集成Core Data
class CoreDataManager: ObservableObject {
    lazy var persistentContainer: NSPersistentContainer = {
        let container = NSPersistentContainer(name: "EmotionMuseum")
        container.loadPersistentStores { _, error in
            if let error = error {
                fatalError("Core Data error: \(error)")
            }
        }
        return container
    }()
    
    var context: NSManagedObjectContext {
        persistentContainer.viewContext
    }
    
    func save() {
        if context.hasChanges {
            try? context.save()
        }
    }
}
```

#### AI服务集成
```swift
// 真实AI服务实现
class OpenAIService: AIServiceProtocol {
    private let apiKey: String
    private let session = URLSession.shared
    
    func sendMessage(_ message: String) async throws -> AIResponse {
        // 实现GPT-4 API调用
    }
    
    func analyzeEmotion(_ text: String) async throws -> EmotionAnalysis {
        // 实现情绪分析
    }
}
```

#### 地图服务集成
```swift
// 高德地图集成
import AMapFoundationKit
import AMapLocationKit

class LocationService: ObservableObject {
    private let locationManager = AMapLocationManager()
    
    func getCurrentLocation() async throws -> CLLocationCoordinate2D {
        // 实现位置获取
    }
    
    func searchNearbyPlaces(coordinate: CLLocationCoordinate2D) async throws -> [LocationPin] {
        // 实现周边搜索
    }
}
```

### 4.3 性能优化建议

1. **图片加载优化**
   - 集成Kingfisher进行图片缓存
   - 实现图片懒加载

2. **数据分页**
   - 对话记录分页加载
   - 社区帖子分页显示

3. **内存管理**
   - 及时释放不需要的数据
   - 使用weak引用避免循环引用

---

## 5. 实施优先级

### Phase 1: 核心功能完善 (2-3周)
- [ ] 完善RecordView的所有子页面
- [ ] 实现AI对话系统
- [ ] 完善情绪日历功能
- [ ] 集成Core Data

### Phase 2: 成长系统开发 (2-3周)
- [ ] 实现GrowthView完整功能
- [ ] 开发课题系统
- [ ] 实现五维雷达图
- [ ] 完善奖励系统

### Phase 3: 地图和社区 (3-4周)
- [ ] 集成地图SDK
- [ ] 实现ExploreView功能
- [ ] 开发社区分享系统
- [ ] 实现位置服务

### Phase 4: 个人中心和优化 (1-2周)
- [ ] 完善InsightView功能
- [ ] 实现成就系统
- [ ] 性能优化
- [ ] 用户体验改进

---

## 6. 详细数据库实现方案

### 6.1 Core Data实体定义

#### User实体
```swift
@objc(UserEntity)
public class UserEntity: NSManagedObject {
    @NSManaged public var id: UUID
    @NSManaged public var username: String
    @NSManaged public var email: String
    @NSManaged public var avatar: String?
    @NSManaged public var nickname: String
    @NSManaged public var birthDate: Date?
    @NSManaged public var location: String?
    @NSManaged public var bio: String?
    @NSManaged public var memberLevel: String
    @NSManaged public var totalDays: Int32
    @NSManaged public var createdAt: Date
    @NSManaged public var lastActiveAt: Date

    // 成长数据
    @NSManaged public var selfAwareness: Float
    @NSManaged public var emotionalResilience: Float
    @NSManaged public var actionPower: Float
    @NSManaged public var empathy: Float
    @NSManaged public var lifeEnthusiasm: Float

    // 关系
    @NSManaged public var conversations: NSSet?
    @NSManaged public var emotionRecords: NSSet?
    @NSManaged public var growthTopics: NSSet?
    @NSManaged public var achievements: NSSet?
    @NSManaged public var locationPins: NSSet?
    @NSManaged public var communityPosts: NSSet?
}
```

#### Conversation实体
```swift
@objc(ConversationEntity)
public class ConversationEntity: NSManagedObject {
    @NSManaged public var id: UUID
    @NSManaged public var title: String
    @NSManaged public var startTime: Date
    @NSManaged public var endTime: Date?
    @NSManaged public var summary: String?
    @NSManaged public var tags: String // JSON字符串存储数组

    // 情绪分析
    @NSManaged public var primaryEmotion: String?
    @NSManaged public var emotionIntensity: Float
    @NSManaged public var emotionTrend: String?
    @NSManaged public var keywords: String? // JSON字符串
    @NSManaged public var aiInsights: String?

    // 关系
    @NSManaged public var user: UserEntity?
    @NSManaged public var messages: NSSet?
}
```

### 6.2 数据迁移策略

#### 版本控制
```swift
class CoreDataMigrationManager {
    static func performMigration() {
        // 检查数据模型版本
        // 执行必要的数据迁移
        // 更新数据结构
    }

    static func migrateFromV1ToV2() {
        // 具体的迁移逻辑
    }
}
```

### 6.3 数据同步方案

#### 本地优先策略
```swift
class DataSyncManager: ObservableObject {
    @Published var syncStatus: SyncStatus = .idle

    func syncToCloud() async {
        // 上传本地变更到云端
    }

    func syncFromCloud() async {
        // 从云端下载更新
    }

    func resolveConflicts() {
        // 处理数据冲突
    }
}

enum SyncStatus {
    case idle
    case syncing
    case success
    case failed(Error)
}
```

---

## 7. API设计规范

### 7.1 RESTful API端点

#### 用户相关
```
GET    /api/v1/users/profile          # 获取用户资料
PUT    /api/v1/users/profile          # 更新用户资料
POST   /api/v1/users/avatar           # 上传头像
```

#### 对话相关
```
GET    /api/v1/conversations          # 获取对话列表
POST   /api/v1/conversations          # 创建新对话
GET    /api/v1/conversations/{id}     # 获取对话详情
POST   /api/v1/conversations/{id}/messages  # 发送消息
```

#### AI服务
```
POST   /api/v1/ai/chat               # AI对话
POST   /api/v1/ai/emotion-analysis   # 情绪分析
POST   /api/v1/ai/recommendations    # 获取推荐
```

#### 成长课题
```
GET    /api/v1/growth/topics         # 获取课题列表
GET    /api/v1/growth/topics/{id}    # 获取课题详情
POST   /api/v1/growth/interactions   # 记录互动
PUT    /api/v1/growth/progress       # 更新进度
```

#### 地图和社区
```
GET    /api/v1/locations             # 获取地点列表
POST   /api/v1/locations             # 创建地点
GET    /api/v1/posts                 # 获取帖子列表
POST   /api/v1/posts                 # 发布帖子
POST   /api/v1/posts/{id}/like       # 点赞帖子
POST   /api/v1/posts/{id}/comments   # 评论帖子
```

### 7.2 数据传输格式

#### 标准响应格式
```json
{
  "success": true,
  "data": {},
  "message": "操作成功",
  "timestamp": "2025-07-12T10:30:00Z",
  "requestId": "uuid"
}
```

#### 错误响应格式
```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "输入数据验证失败",
    "details": {}
  },
  "timestamp": "2025-07-12T10:30:00Z",
  "requestId": "uuid"
}
```

---

## 8. 安全和隐私设计

### 8.1 数据加密
- 敏感数据本地加密存储
- 网络传输使用HTTPS
- API密钥安全管理

### 8.2 隐私保护
- 用户数据匿名化处理
- 位置信息脱敏
- 可选的数据分享设置

### 8.3 权限管理
```swift
enum PermissionType {
    case location
    case microphone
    case camera
    case notifications
}

class PermissionManager {
    func requestPermission(_ type: PermissionType) async -> Bool {
        // 请求系统权限
    }

    func checkPermissionStatus(_ type: PermissionType) -> PermissionStatus {
        // 检查权限状态
    }
}
```

---

## 9. 测试策略

### 9.1 单元测试
- 数据模型测试
- 业务逻辑测试
- 工具类测试

### 9.2 集成测试
- API集成测试
- 数据库操作测试
- 第三方服务集成测试

### 9.3 UI测试
- 页面导航测试
- 用户交互测试
- 响应式布局测试

### 9.4 性能测试
- 内存使用测试
- 网络请求性能测试
- 数据库查询性能测试

---

## 10. 部署和运维

### 10.1 CI/CD流程
```yaml
# GitHub Actions示例
name: iOS Build and Test
on: [push, pull_request]
jobs:
  test:
    runs-on: macos-latest
    steps:
    - uses: actions/checkout@v2
    - name: Build and Test
      run: |
        xcodebuild test -scheme EmotionMuseum -destination 'platform=iOS Simulator,name=iPhone 14'
```

### 10.2 监控和分析
- 崩溃报告收集
- 用户行为分析
- 性能监控
- 错误日志收集

---

*本文档将根据开发进度持续更新和完善*