# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

---

## 📌 重要提示

**在开始工作前,请务必先阅读 `skills.md` 文件,了解当前任务的具体约束和技术指南。**

- **CLAUDE.md** (本文件): 项目通用知识库,包含架构、技术栈、开发规范等基础信息
- **skills.md**: 当前任务技能包,定义特定任务的范围约束、禁止事项和专项技术指南

---

## 项目概述

新疆油田健康管理平台 - 基于 JeecgBoot 3.6.3.1-plus 框架的微服务架构后端系统。

## 技术栈

- **框架版本**: Spring Boot 2.7.18, Spring Cloud 2021.0.9, Spring Cloud Alibaba 2021.0.6.0
- **JDK**: Java 1.8
- **构建工具**: Maven 3.x
- **服务治理**: Nacos 2.3.2 (配置中心 + 服务发现)
- **持久层**: MyBatis-Plus 3.5.6, MyBatis-Plus Join 1.5.3
- **数据源**: 动态多数据源 (Dynamic Datasource 4.3.0), Druid 1.2.18
- **数据库支持**: 达梦DM8 (主要), MySQL, Oracle, PostgreSQL
- **认证授权**: Shiro 1.13.0, JWT
- **文档**: Knife4j 4.5.0
- **报表**: 积木报表 1.6.1
- **对象存储**: MinIO, 阿里云OSS, 七牛云

## 微服务模块

项目采用多模块微服务架构,各服务独立部署:

| 服务名称 | 模块路径 | 默认端口 | 说明 |
|---------|---------|---------|------|
| health-system | jeecg-system/jeecg-system-start | 7001 | 系统核心服务(用户、角色、权限、租户管理) |
| health-consultation | health-consultation/health-consultation-start | 7010 | 健康咨询服务 |
| health-emergency | health-emergency/health-emergency-start | - | 急救服务 |
| health-watch | health-watch/health-watch-start | - | 手表数据服务 |
| health-im | health-im/health-im-start | - | 即时通讯服务 |
| health-bank | health-bank/health-bank-start | - | 健康银行服务 |

## 核心架构特性

### 1. 多租户(SaaS)架构

- **实现方式**: MyBatis-Plus TenantLineInnerInterceptor 租户拦截器
- **配置位置**: `jeecg-boot-base-core/src/main/java/org/jeecg/config/mybatis/MybatisPlusSaasConfig.java`
- **租户字段**: 数据表通过 `tenant_id` 字段实现租户隔离
- **隔离范围**: 用户、角色、部门、字典、多数据源等系统模块
- **非隔离表**: 菜单表、租户表不做租户隔离

### 2. 动态多数据源

- **配置**: 支持运行时动态切换数据源
- **主要数据库**: 达梦数据库 DM8 (国产数据库)
- **注解切换**: 使用 `@DS("数据源名称")` 注解切换数据源
- **拦截器**: `DmKeywordInterceptor` 处理达梦数据库关键字转义

### 3. 安眼系统集成

- **模块位置**: `functional-modules/xj-anyan-api`
- **执行器**: `AnYanClientExecutor` 实现与安眼系统的API对接
- **功能**: 统一身份认证、用户数据同步、登录集成

### 4. 环境配置

每个微服务启动模块都包含独立的 `.env` 文件用于环境变量配置:

```
PROFILE_NAME=dev                          # 环境名称
SERVER_PORT=7001                          # 服务端口
NACOS_SERVER_ADDR=192.168.1.80:8848      # Nacos地址
NACOS_USERNAME=xjuser                     # Nacos用户名
NACOS_PASSWORD=Aa135790!123               # Nacos密码
NACOS_NAMESPACE=xjxc-space-common         # 配置命名空间
NACOS_NAMESPACE_DISCOVERY=workspace_lian  # 服务发现命名空间
NACOS_GROUP=dev                           # 配置分组
```

**注意**: `.env` 文件包含敏感信息,不应提交到版本控制系统。

## 常用开发命令

### Maven 构建命令

```bash
# 全量编译打包(跳过测试)
mvn clean package -DskipTests

# 编译指定模块
mvn clean package -pl jeecg-system/jeecg-system-start -am -DskipTests

# 安装到本地仓库
mvn clean install -DskipTests

# 分包打包(依赖和应用分离,用于Docker部署)
mvn clean package -P divide-package -DskipTests

# 依赖漏洞分析
mvn clean package -P bom-analysis
```

### 启动服务

```bash
# 方式1: IDE直接运行启动类
# 例如: org.jeecg.JeecgSystemCloudApplication

# 方式2: 使用 spring-boot-maven-plugin 启动
cd jeecg-system/jeecg-system-start
mvn spring-boot:run

# 方式3: 打包后启动
java -jar jeecg-system/jeecg-system-start/target/jeecg-system-start.jar
```

### Docker 部署

```bash
# 构建 Docker 镜像(在各服务的 start 模块目录执行)
cd jeecg-system/jeecg-system-start
docker build -t health-system:latest .

# 运行容器
docker run -d \
  -p 7001:7001 \
  -e PROFILE_NAME=dev \
  -e NACOS_SERVER_ADDR=nacos:8848 \
  --name health-system \
  health-system:latest
```

## 代码规范

### 包结构约定

```
com.renkang / org.jeecg
├── modules
│   └── [模块名]
│       ├── controller    # 控制器层
│       ├── service       # 服务层
│       │   └── impl     # 服务实现
│       ├── mapper        # 数据访问层
│       │   └── xml      # MyBatis XML映射文件
│       ├── entity        # 实体类
│       ├── vo            # 视图对象
│       └── dto           # 数据传输对象
```

### Mapper扫描路径

在 `MybatisPlusSaasConfig.java` 中配置了全局 Mapper 扫描:

```java
@MapperScan(value = {"org.jeecg.modules.**.mapper*", "com.renkang.**.mapper*", "com.jeecg.**.mapper*"})
```

### MyBatis XML 映射文件位置

- **方式1**: 放在 `src/main/resources/mapper` 或 `src/main/resources/mapper/xml`
- **方式2**: 与 Mapper 接口同目录,在 `src/main/java` 下 (已配置资源过滤)

### 多租户开发注意事项

1. 新增业务表时,需要添加 `tenant_id` 字段用于租户隔离
2. 如果某些表不需要租户隔离,需要在 `MybatisPlusSaasConfig` 的 `TenantLineHandler` 中排除
3. 租户ID由拦截器自动注入,业务代码无需手动设置

### 动态数据源使用

```java
@Service
public class UserService {

    @DS("slave")  // 切换到从库
    public List<User> queryUsers() {
        // ...
    }

    @DS("master") // 切换到主库
    public void saveUser(User user) {
        // ...
    }
}
```

## 项目特定依赖

- **Aspose Words**: 文档处理库,用于生成Word报告
- **EasyExcel**: Excel导入导出
- **POI-TL**: Word模板引擎
- **极光推送**: 消息推送服务
- **微信小程序**: 小程序API集成
- **北郊工具**: 膳食摄入算法工具 (`yixiong-tools`)
- **重庆风险评估**: 健康风险评估工具 (`cqRisk`)

## 重要配置文件

- **根 pom.xml**: 定义所有依赖版本和Maven仓库配置
- **application.yml**: 各服务启动配置,从Nacos加载配置
- **.env**: 环境变量配置,控制Nacos连接和服务端口
- **Dockerfile**: 各服务的容器化配置

## 开发工具推荐

- **IDE**: IntelliJ IDEA
- **数据库工具**: DM数据库客户端 (达梦官方), Navicat (支持达梦插件)
- **API测试**: Knife4j Web UI (启动服务后访问 `/doc.html`)
- **服务监控**: Nacos 控制台

## 调试建议

1. 确保 Nacos 服务已启动并可访问
2. 检查 `.env` 文件中的 Nacos 配置是否正确
3. 在 Nacos 配置中心确认对应的配置文件存在 (`jeecg.yaml`, `health-system-dev.yaml` 等)
4. 查看日志目录 `logs/` 下的服务日志文件
5. 多租户问题排查: 检查请求Header中的 `tenant-id` 或 `X-Access-Token` (从Token解析租户ID)