# 情绪博物馆全栈项目 - Claude 开发指南

## 项目概述

这是一个情绪博物馆全栈项目，包含iOS客户端、Spring Boot微服务后端和Vue.js Web管理界面。项目采用现代化技术栈，实现情绪记录、AI对话、成长陪伴等核心功能。

### 项目结构
- **EmotionMuseum/**: iOS SwiftUI客户端应用
- **backend/**: Spring Cloud Alibaba微服务后端
- **web/**: Vue.js + Vite Web管理界面
- **mysql_*.sql**: 数据库脚本文件
- ***.md**: 项目文档和需求规格书

## 技术栈

### iOS客户端 (SwiftUI)
- **SwiftUI**: 声明式UI框架
- **Core Data**: 本地数据存储
- **Combine**: 响应式编程
- **MapKit**: 地图功能 (高德地图集成)
- **UIKit**: 部分复杂UI组件

### 后端微服务 (Spring Boot)
- **Spring Boot**: 3.0.2 (主框架)
- **Spring Cloud**: 2022.0.0 (微服务支持) 
- **Spring Cloud Alibaba**: 2022.0.0.0 (微服务生态)
- **Java**: 17+ (编程语言)
- **Maven**: 3.6+ (依赖管理)

### Web前端 (Vue.js)
- **Vue.js**: 3.x (前端框架)
- **Vite**: 构建工具
- **Pinia**: 状态管理
- **Vue Router**: 路由管理
- **SCSS**: 样式预处理器

### 数据存储
- **MySQL**: 8.0+ (主数据库)
- **Redis**: 7.0+ (缓存)
- **MyBatis Plus**: 3.5.3.1 (ORM框架)
- **Druid**: 1.2.16 (数据库连接池)

### 微服务基础设施
- **Nacos**: 2.2.0+ (服务注册发现和配置中心)
- **Gateway**: Spring Cloud Gateway (API网关)

### 工具和库
- **Lombok**: 代码简化
- **Hutool**: 工具类库
- **FastJSON2**: JSON处理
- **JWT**: 认证授权
- **Knife4j**: API文档
- **MapStruct**: 对象映射

## 微服务架构

### 服务列表
| 服务名称 | 端口 | 描述 | 包路径 |
|---------|------|------|--------|
| emotion-gateway | 9000 | API网关 | com.emotionmuseum.gateway |
| emotion-user | 9001 | 用户服务 | com.emotionmuseum.user |
| emotion-ai | 9002 | AI对话服务 | com.emotionmuseum.ai |
| emotion-record | 9003 | 情绪记录服务 | com.emotionmuseum.record |
| emotion-growth | 9004 | 成长课题服务 | com.emotionmuseum.growth |
| emotion-explore | 9005 | 地图探索服务 | com.emotionmuseum.explore |
| emotion-reward | 9006 | 成就奖励服务 | com.emotionmuseum.reward |
| emotion-stats | 9007 | 统计分析服务 | com.emotionmuseum.stats |
| emotion-common | - | 公共模块 | com.emotionmuseum.common |

## 开发规范

### 代码结构约定

每个微服务模块遵循标准的MVC分层架构：
```
emotion-[service]/
├── sql                               # 数据库脚本
├── src/main/java/com/emotionmuseum/[service]/
│   ├── [Service]Application.java     # 启动类
│   ├── controller/                   # 控制器层
│   ├── service/                      # 服务层
│   │   └── impl/                     # 服务实现
│   ├── mapper/                       # 数据访问层
│   ├── constants/                       # 常量类
│   ├── enums/                       # 枚举类
│   ├── entity/                       # 实体类
│   ├── request/                       # 请求体
│   ├── response/                       # 响应体
│   ├── dto/                          # 数据传输对象
│   ├── vo/                           # 视图对象
│   └── config/                       # 配置类
├── src/main/resources/
│   ├── application.yml               # 配置文件
│   └── mapper/                       # MyBatis XML文件
└── pom.xml                          # 依赖配置
```

### 命名规范

1. **包命名**: 全小写，使用点分隔
2. **类命名**: 驼峰命名法，首字母大写
3. **方法命名**: 驼峰命名法，首字母小写
4. **常量命名**: 全大写，下划线分隔
5. **数据库表名**: 小写，下划线分隔
6. **字段命名**: 小写，下划线分隔

### API设计规范

1. **RESTful风格**: 使用标准HTTP方法(GET/POST/PUT/DELETE)
2. **URL路径**: `/api/{service}/{resource}`
3. **统一响应**: 使用`Result<T>`包装所有API响应
4. **状态码**: 使用`ResultCode`枚举定义业务状态码
5. **分页**: 使用`PageQuery`进行分页查询
6. **请求体**: 所有请求封装在request中
7. **响应体**: 所有响应封装在response中

### 数据库规范

1. **表命名**: 使用模块前缀，如`user_info`、`ai_conversation`
2. **字段命名**: 全小写，下划线分隔
3. **主键**: 统一使用`id`,使用雪花算法生成，类型为varchar(36) UUID
4. **公共字段**: 继承`BaseEntity`，包含创建时间、更新时间、逻辑删除等
5. **逻辑删除**: 使用`deleted`字段，0=未删除，1=已删除

### 异常处理

1. **全局异常处理**: 在公共模块统一处理
2. **业务异常**: 继承`RuntimeException`
3. **异常响应**: 统一返回`Result.error()`格式

## 开发工具指令

### 自动化开发环境 (推荐)

```bash
# 启动所有服务并监控文件变化
./dev-auto.sh

# 查看服务状态
./dev-auto.sh status

# 停止所有服务
./dev-auto.sh stop

# 查看实时日志
./dev-auto.sh logs
```

**自动化开发环境特性:**
- **自动编译**: 检测Java/YAML/XML文件变化时自动重新编译
- **热重载**: 使用Spring Boot DevTools实现代码变更后自动重启
- **服务监控**: 实时监控所有微服务的健康状态
- **统一日志**: 所有服务日志统一存储在`dev-logs/`目录
- **一键管理**: 支持启动、停止、状态查看、日志查看等操作

建议安装`fswatch`以获得更好的文件监控体验：
```bash
brew install fswatch  # macOS
apt-get install inotify-tools  # Ubuntu
```

### 手动构建和启动

```bash
# 清理编译
mvn clean compile -DskipTests

# 编译所有模块
mvn clean install -DskipTests

# 启动单个服务
cd emotion-[service] && mvn spring-boot:run
```

### 服务操作

```bash
# 健康检查
curl http://localhost:808[x]/actuator/health

# 查看服务日志 (手动启动)
tail -f logs/emotion-[service].log

# 查看服务日志 (自动化环境)
tail -f dev-logs/emotion-[service].log
```

### iOS开发工具指令

```bash
# 在Xcode中打开项目
open EmotionMuseum/EmotionMuseum.xcodeproj

# 构建iOS应用
xcodebuild -project EmotionMuseum/EmotionMuseum.xcodeproj -scheme EmotionMuseum -configuration Debug

# 运行iOS模拟器
xcrun simctl boot "iPhone 15 Pro"
```

### Web前端工具指令

```bash
# 进入web目录
cd web

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建生产版本
npm run build
```

### 数据库操作

```bash
# 导入数据库结构
mysql -u root -p emotion_museum < mysql_deploy_database.sql

# 执行迁移脚本
mysql -u root -p emotion_museum < [migration_file].sql
```

## 测试规范

### 单元测试
- 使用JUnit 5和Spring Boot Test
- 测试覆盖率要求：控制器层>80%，服务层>90%
- Mock外部依赖

### 集成测试
- 使用TestContainers进行数据库测试
- 测试完整的API调用链路

### API测试
- 使用脚本文件测试API端点
- 参考`test-api.sh`、`test-coze-api.sh`

## 配置管理

### Nacos配置
- 环境: `emotion-dev` (开发环境)
- 配置文件: `common-mysql.yml`、`common-redis.yml`、`coze-config.yml`
- 各服务配置: `emotion-[service].yml`

### 敏感信息
- 数据库密码存储在Nacos配置中心
- API密钥使用环境变量或配置中心管理
- 生产环境配置独立管理

## 代码提交规范

### 提交信息格式
```
type(scope): description

[optional body]

[optional footer]
```

### 类型说明
- `feat`: 新功能
- `fix`: 修复bug
- `docs`: 文档修改
- `style`: 代码格式
- `refactor`: 重构
- `test`: 测试相关
- `chore`: 构建工具

### 示例
```
feat(user): add user registration API

- Add user registration endpoint
- Implement email validation
- Add password encryption

Closes #123
```

## 安全要求

1. **认证授权**: 使用JWT token进行用户认证
2. **数据加密**: 敏感数据加密存储
3. **SQL注入**: 使用参数化查询防止SQL注入
4. **XSS防护**: 对用户输入进行过滤和转义
5. **CORS配置**: 限制跨域访问

## 性能优化

1. **数据库优化**: 合理使用索引，避免N+1查询
2. **缓存策略**: 热点数据使用Redis缓存
3. **连接池**: 合理配置数据库连接池参数
4. **异步处理**: 耗时操作使用异步执行

## 监控和日志

1. **健康检查**: 所有服务提供`/actuator/health`端点
2. **Prometheus指标**: 通过`/actuator/prometheus`暴露指标
3. **日志级别**: 开发环境使用DEBUG，生产环境使用INFO
4. **日志格式**: 统一使用结构化日志

## 常见问题处理

### 服务启动失败
1. 检查Nacos服务是否启动
2. 检查数据库连接配置
3. 检查端口是否被占用
4. 查看服务日志定位错误

### 数据库问题
1. 确认数据库服务状态
2. 检查连接参数配置
3. 验证数据库权限
4. 查看慢查询日志

### 缓存问题
1. 检查Redis服务状态
2. 验证缓存配置
3. 清理过期缓存数据

## 扩展开发

### 添加新微服务
1. 复制现有服务模块结构
2. 修改包名和端口配置
3. 添加到父工程pom.xml
4. 更新启动脚本
5. 配置Nacos注册信息

### 添加新API
1. 在对应服务的controller包下创建控制器
2. 定义DTO和VO对象
3. 实现服务层逻辑
4. 添加数据访问层
5. 编写单元测试
6. 更新API文档

## 部署说明

### 开发环境
- 本地启动：使用Maven插件
- Docker部署：提供Dockerfile和docker-compose.yml

### 生产环境
- 容器化部署：使用Kubernetes
- 配置管理：环境变量和配置中心
- 服务监控：Prometheus + Grafana

## Claude 开发助手指南

### 任务执行原则

1. **准确性第一**: 在执行任何任务前，必须先分析项目结构和现有代码，确保理解正确
2. **规范性约束**: 严格遵循项目的代码规范、命名约定和架构模式
3. **功能完整性**: 确保所有修改不会破坏现有功能，新增功能要完整实现
4. **测试验证**: 重要修改后需要运行相关测试，确保代码质量

### 文件操作规范

1. **iOS项目 (SwiftUI)**
   - 修改前先读取 `EmotionMuseum/EmotionMuseum.xcodeproj/project.pbxproj` 了解项目结构
   - 遵循SwiftUI声明式编程范式
   - 使用现有的颜色主题和组件样式
   - 新增文件要正确添加到Xcode项目中

2. **后端微服务 (Spring Boot)**
   - 修改前检查 `backend/pom.xml` 了解模块依赖
   - 遵循MVC分层架构
   - 使用统一的Result响应格式
   - 数据库操作使用MyBatis Plus

3. **Web前端 (Vue.js)**
   - 修改前检查 `web/package.json` 了解依赖版本
   - 使用Vue 3 Composition API
   - 遵循组件化开发模式
   - 样式使用SCSS预处理器

### 常用检查清单

#### 开始任务前
- [ ] 读取相关文档 (*.md 文件) 了解需求
- [ ] 分析现有代码结构和实现模式
- [ ] 确认修改范围和影响面
- [ ] 检查是否有相关测试需要更新

#### 完成任务后
- [ ] 代码符合项目规范
- [ ] 新增功能完整可用
- [ ] 没有破坏现有功能
- [ ] 相关文档已更新
- [ ] 提交信息规范

### 错误预防

1. **避免盲目修改**: 不要在不了解项目结构的情况下直接修改代码
2. **保持一致性**: 新增代码要与现有代码风格保持一致
3. **完整实现**: 不要留下未完成的功能或空实现
4. **谨慎删除**: 删除代码前确认没有其他地方在使用

### 紧急情况处理

如果在开发过程中遇到以下情况，需要立即停止并寻求确认：
- 发现代码存在安全风险
- 修改可能影响核心业务逻辑
- 需要修改数据库结构
- 涉及第三方API集成

---

以上是情绪博物馆全栈项目的完整开发指南，请在开发过程中严格遵循相关规范，确保代码质量和项目的可维护性。