53 lines
4.9 KiB
Markdown
53 lines
4.9 KiB
Markdown
# Repository Guidelines
|
||
|
||
## Agent 工作方式
|
||
进入本仓库后，先阅读本文件，再开始分析、修改或输出结论。不要跳过现有文档直接下判断，至少先结合根目录 `README.md`、`docs/`、目标模块代码和相关配置确认上下文。
|
||
|
||
日常交互遵循以下习惯：
|
||
|
||
- 先整理执行方案，说明目标、涉及模块、预计修改点和验证方式，待用户评审确认后再执行。
|
||
- 不要想当然；如果需求存在歧义、前提不清或有多种实现路径，先说清假设与取舍，再继续。
|
||
- 先确认任务位于 `entrance`、`system`、`user`、`detection` 还是 `tools/activate-tool`，再沿配置、Controller、Service、Mapper、XML 和调用链向下分析。
|
||
- 涉及认证、字典、日志、注册资源、WebSocket 或 Netty 通信链路时，先核对已有实现和 `docs/` 中的说明，避免只看局部代码就下结论。
|
||
- 回复风格保持简洁、直接，优先给出可执行结果；如果存在限制、风险或未验证部分，需要明确说明。
|
||
|
||
## 执行与修改原则
|
||
- 简单优先：只做当前需求所需的最小改动，不额外引入新功能、抽象层、配置项或“顺手优化”。
|
||
- 外科手术式修改：只改与任务直接相关的文件和代码行，不重构无关模块，不调整无关格式或注释。
|
||
- 保持现有风格：遵循仓库已有包结构、分层方式、命名和写法，不按个人偏好重写。
|
||
- 只清理自己造成的问题：可以删除因本次修改而产生的未使用 `import`、变量或方法；不要删除仓库中原本就存在的死代码，除非用户明确要求。
|
||
- 先定义验证方式：执行方案里要写清楚“改哪里、怎么判断改对了”；默认通过代码路径、配置一致性和受影响范围检查进行验证。
|
||
- 除非用户明确要求，否则不执行任何 `mvn` 编译、打包、测试或其他构建命令。
|
||
|
||
## 项目结构与模块划分
|
||
`CN_Tool` 是一个 Maven 多模块后端项目，根目录的 [`pom.xml`](C:/code/gitea/cn_tool/CN_Tool/pom.xml) 聚合了 `entrance`、`system`、`user`、`detection` 和 `tools`。
|
||
|
||
- `entrance`：Spring Boot 启动模块，入口类为 `entrance/src/main/java/com/njcn/gather/EntranceApplication.java`。
|
||
- `system`：系统字典、日志、配置、注册资源等公共能力。
|
||
- `user`：认证、用户、角色、功能资源及相关过滤逻辑。
|
||
- `detection`：Netty / WebSocket 通信与连接生命周期管理。
|
||
- `tools/activate-tool`：激活码与许可能力。
|
||
- `docs/`：项目基线、配置和运行说明文档。
|
||
|
||
Java 源码位于 `src/main/java`，配置文件位于 `src/main/resources`，MyBatis XML 映射文件按包结构存放在 `**/mapper/mapping/*.xml`。
|
||
|
||
## 代码风格与命名规范
|
||
保持现有 Java 风格：4 空格缩进、UTF-8 文件编码、基础包名使用 `com.njcn.gather`。命名沿用分层后缀，如 `*Controller`、`*Service`、`*ServiceImpl`、`*Mapper`、`*Param`、`*PO`、`*VO`。优先复用现有 Lombok 注解，如 `@Data`、`@RequiredArgsConstructor`、`@Slf4j`。Mapper XML 文件名应与接口名保持一致。业务代码中，关键流程、分支判断、状态流转或容易误解的节点需要补充简洁的中文注释，但不要添加无信息量的注释。
|
||
|
||
## 数据与 SQL 约束
|
||
- 新增业务表的 DO 优先复用当前 `BaseDO` / 审计字段风格；除非表本身明确不需要逻辑删除，不要再引入另一套审计基类。
|
||
- 不要假设运行时存在自动数据库迁移；如果代码依赖新表、新字段或新索引，必须同步补齐对应 SQL 与文档说明。
|
||
- SQL 脚本应放在目标模块的 `src/main/resources/sql/...` 下，并保持可审阅、可单独执行、语义清晰。
|
||
- 变更缓存、日志、审计相关逻辑时，优先沿用现有机制，不要绕开现有登录上下文、缓存约定和审计字段填充方式。
|
||
|
||
## 注释与编码
|
||
- 新增或修改代码时，关键字段、关键分支、关键约束和非直观实现应补充简洁中文注释。
|
||
- 不要为了省事删除原有有效注释，也不要添加无信息量的注释。
|
||
- 写入中文内容时必须保持 UTF-8 编码，并自行检查中文显示是否正常；不要用“改成英文”规避乱码问题。
|
||
|
||
## 提交与合并请求规范
|
||
当前 `main` 分支尚无可参考的提交历史，仓库内也没有既有提交规范。建议使用“模块前缀 + 动词短句”的提交格式，例如 `user: 优化登录会话校验`、`system: 增加字典参数校验`。提交 PR 时应说明影响模块、配置或数据结构变更、人工验证步骤；若接口行为有变化，附上请求与响应示例。
|
||
|
||
## 安全与配置提示
|
||
将 `application.yml` 视为环境配置文件处理，不要在提交中新增明文密钥、数据库口令或许可证材料。本地运行时需保证 `D:\logs` 可写；如部署环境不同，应通过配置覆盖日志目录。
|