data-manager

Imported from sucls/data-manager (AGENTS.md). Install upstream with npx skills add sucls/data-manager. Copyright stays with the author.

data-manager 项目导览

本文件面向 AI 编程助手。阅读前默认你对本项目一无所知。以下内容基于当前工作区实际文件整理，未做过度推断。

1. 项目概览

• 坐标：com.cycads.manager:data-manager:1.0.0-SNAPSHOT
• 构建工具：Apache Maven 多模块聚合项目
• JDK 版本：Java 17
• 主要框架/生态：
  • Spring Boot 4.1.0
  • Spring Cloud 2025.1.2
  • Spring Session 4.1.0
  • Spring Security / OAuth2（Authorization Server + Resource Server + Client）
  • Spring Cloud Gateway（WebMVC 版本）+ Netflix Eureka
  • Spring Data JPA + Hibernate + PostgreSQL
  • Redis（Redisson + Spring Session Redis）
  • Thymeleaf（登录页 / 同意页模板）
  • EasyExcel / Apache POI / Apache Commons CSV（Excel/CSV 处理）
  • Apache Lucene + Ansj（本地全文检索与中文分词）
  • MapStruct + Lombok + Therapi Runtime Javadoc
  • Druid 连接池、Jasypt 配置加密、BouncyCastle 国密/加解密

项目定位是一个数据管理后台，采用微服务拆分：注册中心、SSO 授权服务、基础业务服务、任务调度服务，以及一个基于 Spring Cloud Gateway 的 Web 入口示例。

2. 仓库结构与模块划分

根 POM 聚合了 4 个一级目录：

data-manager/
├── assist/        # 通用辅助工具库（Excel、索引、行数据处理）
├── modules/       # 业务/公共模块（common、auth、base、security、sso、job、crypto）
├── services/      # 可独立启动的微服务
└── webs/          # Web 入口 / 网关

2.1 assist（工具辅助）

顶层 POM：assist/pom.xml（data-manager-assist）

2.2 modules（业务与公共模块）

顶层 POM：modules/pom.xml（data-manager-parent），聚合 7 个分组：

• common：公共基础设施

  • common-core：异常、常量、消息对象等
  • common-domain：BaseDomain、Domain、ITreeNode 等基类
  • common-base：ORM 查询对象、分页、仓储接口契约
  • common-baseImpl：BaseController、BaseRepository、BaseServiceImpl
  • common-jackson：自定义 Jackson 序列化
  • common-service：统一响应包装 / 全局异常处理
  • common-jpa：JPA 审计、自定义 @Comment 列注释扩展
  • common-remote-proxy：基于 smiley-http-proxy-servlet 的 HTTP 代理

• auth：身份认证与数据权限

  • auth-identity / auth-identityImpl：用户、角色、菜单、ABAC 权限
  • auth-identityClient：Feign / MapStruct 转换器（包名在 com.cycads.agency.convert）
  • auth-dataAccess / auth-dataAccessImpl：数据权限规则管理
  • auth-dataAccessClient：数据权限客户端（注解 + 参数解析器 + Feign 客户端）

• base：基础数据

  • base-agency / base-agencyImpl / base-agencyClient：机构管理
  • base-codemap / base-codemapImpl：码表 / 字典管理
  • base-config / base-configImpl：系统配置管理

• security：通用安全配置

  • security-common：安全配置 API
  • security-server：JWT OAuth2 Resource Server 实现

• sso：单点登录

  • sso-security-principal-api / sso-security-principal-adapter：用户主体抽象
  • sso-auth-server：OAuth2 授权服务器配置与登录页控制器
  • sso-service-client：SSO 客户端支持（Token 获取等）

• job：定时任务

  • job-common / job-quartz / job-quartzImpl / job-quartzClient：Quartz 任务调度

• crypto：加密与安全

  • crypto-api / crypto-core / crypto-support：加解密 SPI、属性配置、密码编码器
  • crypto-jpa：JPA 字段加密 AOP
  • crypto-web：Web 签名过滤器

2.3 services（可启动服务）

顶层 POM：services/pom.xml（data-manager-services），统一配置了 spring-boot-maven-plugin 的 repackage。

2.4 webs（Web 入口）

• web-simple：基于 Spring Cloud Gateway（WebMVC）+ OAuth2 Client + Thymeleaf 的示例入口，端口 8080。

3. 构建与运行命令

项目未包含 mvnw，请使用本地 Maven（建议 3.9+）。

# 从根目录全量编译、打包（跳过测试可加快）
mvn clean install
mvn clean install -DskipTests

# 单独安装某个子模块（需先安装其依赖）
mvn -pl modules/common/base install -am

# 启动某个服务（开发调试）
mvn -pl services/server-registry spring-boot:run
mvn -pl services/server-sso spring-boot:run
mvn -pl services/server-base spring-boot:run
mvn -pl services/server-job spring-boot:run
mvn -pl webs/web-simple spring-boot:run

# 或运行打包后的 fat-jar
java -jar services/server-sso/target/server-sso-1.0.0-SNAPSHOT.jar

根 POM 使用 ${revision} CI Friendly 版本，配合 flatten-maven-plugin 生成 .flattened-pom.xml。该文件已被 .gitignore 忽略，无需提交。

4. 测试说明

• 测试框架：JUnit Jupiter（JUnit 5），由 modules/pom.xml 统一引入 spring-boot-starter-test 与 junit-jupiter。
• 当前测试覆盖率极低，仅发现两个测试类：
  • modules/common/baseImpl/src/test/java/com/cycads/common/base/orm/DaoHelperTest.java（实际为带 main 方法的临时验证类）
  • modules/job/quartzImpl/src/test/java/com/gw/job/quartz/test/QuartzTests.java（空类）

# 运行全量测试
mvn test

# 运行单个模块测试
mvn -pl modules/common/baseImpl test

5. 代码风格与开发约定

5.1 包名与分层

• 统一包前缀：com.cycads
• 模块包：com.cycads.<领域>.<子模块>.<分层>
  • 实体：...entity
  • 常量：...constant
  • 服务接口：...service
  • 服务实现：...service.impl
  • 控制器：...controller
  • 仓储：...repository
• 注意：auth-identityClient 与 base-agencyClient 的 MapStruct 转换器放在 com.cycads.agency.convert.*，与模块主体包名不一致。

5.2 模块拆分模式

业务模块通常拆分为：

1. API 模块（如 base-codemap）：定义实体、常量、Service 接口。
2. Impl 模块（如 base-codemapImpl）：提供 Controller、Service 实现、Repository。
3. Client 模块（可选）：提供 Feign 客户端或 DTO 转换器。

实现模块的入口通常是一个 ModuleConfig.java，并以 @Configuration("xxx.config") 命名 Bean。

5.3 实体与基类

• 领域基类：com.cycads.common.domain.BaseDomain
  • @MappedSuperclass、@EntityListeners(AuditingEntityListener.class)
  • 包含 creator、createTime、modifier、updateTime、deleted 审计字段
• 实体类继承 BaseDomain，使用 Jakarta Persistence 注解（@Entity、@Table、@Id、@GeneratedValue）。
• common-jpa 提供 @Comment 注解，通过 CommentHibernatePropertiesCustomizer 将注释写入数据库列注释。

5.4 基础设施使用

• Lombok：广泛使用 @Data、@Getter、@Setter、@Builder 等。
• MapStruct：根 POM 已配置注解处理器与 Lombok-MapStruct 桥接，但目前源码中几乎未见 @Mapper。
• Therapi Runtime Javadoc：编译期将 Javadoc 写入字节码，运行时通过 therapi-runtime-javadoc 读取。
• 编译参数：maven-compiler-plugin 开启 -parameters，保留方法参数名用于反射。

5.5 自动配置

• 目前仅有 modules/common/jpa/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports，但文件内容指向 com.cycads.common.jpa.configure.CommentConfig，实际类位于 com.cycads.common.jpa.comment 包下，疑似配置项过期或拼写错误。

6. 安全相关

6.1 认证与授权

• SSO 授权服务器：server-sso:9000，基于 Spring Authorization Server。
  • 客户端 app-client：client_credentials 模式，用于服务间调用。
  • 客户端 web-simple：authorization_code + refresh_token，用于 Web 入口登录。
  • JWT issuer-uri：http://127.0.0.1:9000
• 资源服务：server-base、server-job 等通过 spring.security.oauth2.resourceserver.jwt 校验 JWT。
• 网关：web-simple 使用 OAuth2 Login + TokenRelay，将 Token 透传给下游服务。
• 共享 Session：SSO 与 Web 入口使用 Redis 共享 Session（spring-session-data-redis）。

6.2 加密与敏感配置

• Jasypt：jasypt-spring-boot-starter 用于加密配置文件中的敏感值（如数据库密码），密文格式通常为 ENC(...)。
• BouncyCastle：bcprov-jdk18on / bcpkix-jdk18on 提供 RSA、SM2/SM3/SM4 等国密算法支持。
• crypto 模块：提供字段级 JPA 加密、Web 请求签名验证、密码编码器等能力。

6.3 安全开发注意

• env/.env 与 application-self* 已被 .gitignore 忽略，不要将真实密码、密钥提交到仓库。
• 配置中通过环境变量注入数据库与 Redis 凭据：DATASOURCE_URL、DATASOURCE_USERNAME、DATASOURCE_PASSWORD、REDIS_HOST、REDIS_PORT、REDIS_DATABASE、REDIS_PASSWORD。
• 当前配置中 server-base 与 server-job 的 spring.datasource.password 写成了 ${DATASOURCE_USERNAME}，明显是错误，需修正为 ${DATASOURCE_PASSWORD}。

7. 部署与运行架构

7.1 默认端口

7.2 启动顺序建议

1. server-registry（Eureka）
2. server-sso（授权服务，其他服务依赖 JWT issuer）
3. server-base / server-job
4. web-simple

7.3 外部依赖

• PostgreSQL：server-sso、server-base、server-job 均使用 PostgreSQL，通过 currentSchema 分别指向 sso、base、job 模式。
• Redis：用于 Spring Session、Redisson 缓存/锁。
• Eureka：服务注册与发现，默认地址 http://localhost:8761/eureka/。

7.4 环境变量

开发时至少配置以下变量（可放在 env/.env 并通过 IDE 或 shell 导入）：

DATASOURCE_URL=jdbc:postgresql://localhost:5432/data_manager
DATASOURCE_USERNAME=postgres
DATASOURCE_PASSWORD=your_password
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DATABASE=0
REDIS_PASSWORD=
REAL_WEB_IP=127.0.0.1
REAL_WEB_PORT=8080
REAL_SSO_IP=127.0.0.1
REAL_SSO_PORT=9000

7.5 部署产物

• 每个服务模块通过 spring-boot-maven-plugin 生成可执行 fat-jar，位于 services/<service>/target/*.jar。
• 目前仓库中没有 Dockerfile、docker-compose.yml、Jenkinsfile 或 GitHub Actions 工作流，部署方式需自行补充。

8. 已知问题与注意事项

1. AutoConfiguration.imports 指向不存在的类：common-jpa 的自动配置文件中写的 com.cycads.common.jpa.configure.CommentConfig 不存在，真实类在 com.cycads.common.jpa.comment 包下。
2. 数据库密码环境变量引用错误：server-base 与 server-job 的 application-dev.yml 中 spring.datasource.password 错写为 ${DATASOURCE_USERNAME}。
3. 测试覆盖率低：大部分模块没有单元测试，DaoHelperTest 也不是标准 JUnit 测试。
4. 前端产物目录为空：webs/web-simple/pom.xml 配置了将 src/main/webapp/build 复制到 static，但该目录目前为空，若需要前端页面需单独构建并放入对应目录。
5. 工作区存在未提交改动：当前 master 分支有大量未提交修改和新增文件，编写代码前建议先确认分支状态与预期基线。

9. 参考文档

• README.md：仅含 Spring Authorization Server、权限与登录页链接。
• DEPENDENCIES.md：根 POM 依赖详细说明，包含各依赖用途、BOM、插件、注解处理器等。
• Spring Authorization Server 入门文档：见 README.md / REFERENCE.md 中的链接。