415 lines
12 KiB
Markdown
415 lines
12 KiB
Markdown
# 情绪博物馆全栈项目 - 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集成
|
|
|
|
---
|
|
|
|
以上是情绪博物馆全栈项目的完整开发指南，请在开发过程中严格遵循相关规范，确保代码质量和项目的可维护性。 |