xj-platform/CLAUDE.md

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 构建命令

# 全量编译打包(跳过测试)
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

启动服务

# 方式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 部署

# 构建 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 扫描:

@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由拦截器自动注入,业务代码无需手动设置

动态数据源使用

@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)