# CLAUDE.md

此文件为Claude Code (claude.ai/code) 提供在此代码库中工作的指导。

## AI 行为规则

### 语言偏好
- **始终使用中文回答所有问题和响应**
- 所有代码注释使用中文
- 文档和说明使用中文

### 沟通风格
- 使用简洁、专业的中文表达
- 技术术语优先使用中文翻译，必要时用括号注明英文原文
- 避免过度使用专业术语，确保清晰易懂

## 项目概述

这是一个基于Spring Boot 3.0.0构建的大规模多模块Maven保险报价服务平台(jzg)。该系统集成多家保险公司，提供车辆保险报价和管理服务。

## 架构

### 技术栈
- **框架**: Spring Boot 3.0.0 与 Spring Security
- **Java版本**: 17
- **数据库**: MySQL 8.0.26 配合 MyBatis-Plus 3.5.7
- **缓存**: Redis 配合 Redisson 3.23.3
- **消息队列**: RocketMQ 2.2.1
- **服务发现**: 阿里巴巴 Nacos
- **API网关**: Spring Cloud Gateway
- **文档**: SpringDoc OpenAPI (Swagger)
- **构建工具**: Maven 3.8.9

### 模块结构
```
jzg (父项目)
├── authentication     # 认证授权服务 - Authentication & Authorization
├── commons           # 公共组件 - Common utilities and configurations
├── gateway           # 网关服务 - API Gateway
├── platform          # 总控平台 - Management platform
├── tenant           # 租户模块 - Tenant management
│   ├── insurance    # 保险报价模块 - Insurance quotation
│   │   ├── quotation-commons    # 报价通用组件
│   │   ├── quotation-summary    # 报价汇总
│   │   └── quotation-*          # 各保险公司报价模块 (渤海/大家/恒邦/华农/华泰/国任/泰康/太平洋/阳光/永诚/中安/中美等)
│   ├── organization # 组织管理
│   ├── costsorrule  # 成本规则
│   └── openfeign    # OpenFeign客户端
├── rocketmq         # 消息队列
└── consoleStatistics # 控制台统计
```

## 构建命令

```bash
# 清理并编译整个项目
mvn clean compile

# 打包所有模块（跳过测试）
mvn package -DskipTests

# 安装到本地仓库
mvn install

# 运行指定模块（例如：网关）
cd gateway
mvn spring-boot:run

# 使用指定配置文件运行
mvn spring-boot:run -Dspring-boot.run.profiles=dev

# 运行测试
mvn test

# 构建指定模块
mvn clean package -pl gateway -am
```

## 开发环境配置

### 前置条件
- Java 17+
- Maven 3.8+
- MySQL 8.0+
- Redis
- RocketMQ
- Node.js（如果涉及前端开发）

### 配置文件
每个模块都包含application.yml文件：
- `application.yml` - 主配置文件
- `application-dev.yml` - 开发环境配置
- `application-test.yml` - 测试环境配置

### 数据库配置
- 使用MyBatis-Plus进行ORM操作
- Mapper XML文件位于 `src/main/resources/mapper/` 目录
- 支持多租户，具备租户特定的数据模式

## 核心架构模式

### 1. 多租户架构
- `@IgnoreTenant` 注解用于忽略租户隔离的操作
- 通过AOP切面实现租户感知的数据访问
- 租户特定的配置管理

### 2. 历史记录追踪系统
需要历史记录追踪的服务应该：
- 继承 `HistoryDataService` 并实现 `getHistoryData()` 方法
- 使用 `@OperatorTrajectory` 注解：
```java
@OperatorTrajectory(
    type = "C|U|D",           // 创建/更新/删除
    systemCode = "JZG",
    serviceTag = "userRoleService",
    primary = "id"            // 主键字段名
)
```

### 3. API网关模式
- 所有外部请求通过网关模块
- 通过Nacos进行服务发现
- 负载均衡和健康管理

### 4. 保险公司集成模式
每个保险公司模块（quotation-*）遵循相似模式：
- 请求/响应加密（RSA）
- API客户端组件
- MongoDB用于报价数据持久化
- 公司特定的枚举和配置

## 常见开发任务

### 添加新保险公司
1. 在 `tenant/insurance/quotation-{company}` 下创建新模块
2. 遵循现有模式（例如：quotation-bohai）
3. 实现RSA加密和数字签名
4. 添加MongoDB实体用于报价存储
5. 创建API客户端组件

### 服务开发
1. 继承适当的基础服务
2. 添加历史记录追踪注解
3. 使用commons模块的通用工具
4. 如适用，遵循多租户模式

### API开发
- 使用SpringDoc OpenAPI注解
- 遵循RESTful约定
- 使用 `SystemException` 实现适当的错误处理
- 使用 `InsuranceLog` 进行结构化日志记录

## 核心组件

### 安全与认证
- 自定义认证：`JzgUserDetailsService`、`JzgAuthenticationProvider`
- JWT令牌：`JzgTokenService`
- 多平台支持：微信、支付宝集成

### 数据访问
- MyBatis-Plus配合自定义配置
- Redis缓存配合Redisson
- 多租户数据隔离
- 通过 `MyBatisMetaObjectHandler` 自动处理审计字段

### 消息队列
- RocketMQ集成用于异步处理
- 自定义消息模板和处理

### 文件存储
- MinIO集成用于文件存储
- 支持多种文件类型和元数据

## 测试
- Spring Boot测试框架
- 测试数据文件位于 `src/test/data/`
- 外部API调用的模拟配置

## 部署说明
- 使用Nacos进行服务发现和配置管理
- 网关处理外部路由和负载均衡
- 每个模块可独立部署
- 支持多环境配置文件