CLAUDE.md

本文件为 Claude Code 在 C:\code\gitea\rdms\cn-rdms 仓库工作时的常驻指引，等价并补充 AGENTS.md。两份文件冲突时以本文件为准；本文件未覆盖的细节回退到 AGENTS.md。

工作方式

默认先给执行方案：目标、涉及模块、改动点、验证方式。用户明确同意前不要直接动手修改、编译、测试、打包。
用户只要分析或评审时，停在分析层；不要顺手开工。
描述仓库现状以当前代码、配置、文档可验证的事实为准；不要拿历史实现、过渡方案或已废弃模型解释当前状态。
回答保持精简，先给结论、改动点、必要风险；细节等用户追问。
不要废话：默认极简输出，不展开背景、不复述需求、不堆叠章节标题；能用一两句讲清就别写成清单；用户主动追问再展开。

本机环境

JDK：必须使用 JDK 17，路径 C:\Program Files\Java\jdk-17。不要使用 JDK 8 / 11 / 其他版本。
Maven：C:\software\apache-maven-3.8.9，命令优先用完整路径 C:\software\apache-maven-3.8.9\bin\mvn.cmd。不要假设 mvn 在 PATH。
执行任何 Maven / java 命令前，先确认当前 shell 的 JAVA_HOME 指向 JDK 17，且 java -version 输出 17；否则在该命令上下文中显式切换。
只有在用户已明确同意执行编译/测试/打包等命令时，才使用上述路径执行。日常默认不跑任何会实际运行项目的命令。

仓库结构

多模块 Maven 单仓库，Java 17，Spring Boot 3.5.9，根模块打包 pom。

顶层模块：

rdms-system — 系统域（用户/组织/岗位/菜单/角色/权限）
rdms-project — RDMS 核心交付域（项目集/项目/产品/需求/任务/工单/执行）
rdms-framework — 共享框架与内部 starter
rdms-gateway — Spring Cloud Gateway 网关

每个业务模块按 xxx-api + xxx-boot 拆分：

*-api：对外 RPC/Feign 接口、DTO、错误码、枚举、常量
*-boot：启动类、controller、service、dal、convert、api 实现、模块级 framework 配置

主包/启动类：

rdms-system-boot：com.njcn.rdms.module.system.SystemServerApplication
rdms-project-boot：com.njcn.rdms.module.project.ProjectServerApplication
rdms-gateway：com.njcn.rdms.gateway.GatewayServerApplication

rdms-framework 子模块：rdms-common 及一组 rdms-spring-boot-starter-*（env、web、rpc、security、mybatis、redis、mq、websocket、excel、protection、test、biz-ip）。

模块演进判断

新增能力时先判断落点：

落在现有 rdms-system 子域 → 沿用 controller/admin|app、service、dal/dataobject、dal/mysql、convert 的现有结构，跨模块暴露时在 rdms-system-api 补 API/DTO/错误码/枚举。
落在现有 rdms-project 子域 → 同理，跨模块走 rdms-project-api。
已具备独立服务边界（如未来的 rdms-workflow）→ 新建 rdms-xxx + rdms-xxx-api + rdms-xxx-boot，根 pom.xml 加聚合，包路径 / spring.application.name / ApiConstants / RpcConstants / rdms.info.base-package 保持一致。

不要：

把后续业务长期堆进 rdms-system。
为新增子域引入一套平行的 application/domain/infrastructure/adapter 分层。
让外部模块直接依赖 *-boot 的 service 或 mapper（必须走 *-api）。

分层职责

层	职责	红线
`rdms-framework`	基础能力	不承载业务语义；除非框架级缺陷或全局基础设施，不要把业务判断塞进来
`rdms-gateway`	入口、令牌校验、登录用户透传、路由、横切	不要在这里承载组织/成员/负责人/项目/产品/工作流状态/数据可见性
Controller	HTTP 暴露、参数校验、权限注解、结果封装	不要编排复杂业务流程，不要直接操作多个 mapper；用 `ReqVO`/`RespVO`，不要直接暴露 DO
Service	业务规则、事务、缓存、领域编排	已有领域优先扩展，不要为"整齐"平移；不要把规则散到 controller / mapper / util
DAL	DO + Mapper	Mapper 继承 `BaseMapperX<T>`；查询优先 `LambdaQueryWrapperX` 与默认方法封装；非必要不回退 XML；不承担领域校验
Convert	已有 `convert` 风格继续沿用，简单场景直接 `BeanUtils`	不要强推全员 MapStruct，也不要反过来把已有 convert 全删

认证与跨模块调用

默认沿用 OAuth2 / Token / LoginUser / login-user 透传主链。不要另造 ThreadLocal / Session / 自定义 header。
接口级权限走 @PreAuthorize("@ss.hasPermission(...)")，不要绕开。
跨模块/跨服务必须通过 *-api 模块定义契约；不要直接依赖别人的 *-boot。

数据与 SQL

新表 DO 复用现有 BaseDO / 审计字段风格，不要再引一套审计基类（除非该表本身明确不需要逻辑删除）。
不要假设运行时自动数据库迁移：依赖新表/新字段/新索引时，必须同步补 SQL 脚本与文档。
SQL 放在目标模块 src/main/resources/sql/...，可审阅、可单独执行。
缓存/日志/审计变更优先沿用既有机制，不要绕开登录上下文与审计字段填充。

注释与编码

关键字段、关键分支、关键约束、非直观实现补简洁中文注释。
不要为省事删除原有有效注释；也不要写无信息量的注释。
中文写入必须 UTF-8，并自查显示是否正常；不要用"改成英文"规避乱码。
superpowers 产出的功能文档（设计/实施/联调）默认中文落地；代码标识、文件路径、接口路径、SQL、命令保持原样不意译。

工作规则（执行前对照）

优先做有边界的模块内改动，避免跨模块扩散。
业务逻辑落 *-boot；可复用契约落 *-api；可复用框架能力落 rdms-framework。
不要修改 application-local.yaml / application-dev.yaml，除非任务本身就是环境配置调整。
把本地 YAML 当作可能带机器差异的文件，改前先查 git 状态。
包结构：controller / service / dal / convert，保持不变。
新增共享能力优先扩展现有 rdms-spring-boot-starter-*，不要在业务服务里重复堆配置。
改跨模块 API 时，提供方实现与对应 *-api 契约同步更新。
未经用户明确同意，不执行任何 mvn、启动命令、脚本等会实际运行项目的命令。

验证默认动作

先定义验证方式，再做修改。默认静态验证：

调用链是否闭环、是否符合模块边界
配置项 / 接口契约 / 权限标识 / 路由 / 资源注册前后是否一致
改动是否控制在最小集合
文档 / SQL / 配置 / 接口说明是否需要同步更新

如果改动涉及 Spring 配置、序列化、安全、路由、RPC 契约、MyBatis 行为或跨模块 API，必须显式区分哪些是已静态检查、哪些尚未实际运行验证。

给后续我自己的提醒

仓库可能有未提交的本地改动，不要顺手覆盖与当前任务无关的编辑。
docs/ 是当前工作上下文的一部分，不是归档；架构级修改前先查阅。
根 pom.xml 统一版本与依赖；版本调整改根 pom，不要散落到子模块。
推荐使用 Glob / Grep / Read 等专用工具，避免用 Bash 做文件搜索/读取/编辑。

7.4 KiB Raw Blame History Unescape Escape