happy-life-star/CLAUDE.md

情绪博物馆全栈项目 - 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()格式

开发工具指令

自动化开发环境 (推荐)

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

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

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

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

自动化开发环境特性:

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

建议安装fswatch以获得更好的文件监控体验：

brew install fswatch  # macOS
apt-get install inotify-tools  # Ubuntu

手动构建和启动

# 清理编译
mvn clean compile -DskipTests

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

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

服务操作

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

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

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

iOS开发工具指令

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

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

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

Web前端工具指令

# 进入web目录
cd web

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建生产版本
npm run build

数据库操作

# 导入数据库结构
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集成

---

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