CN_Tool/AGENTS.md

# Repository Guidelines

## Agent 工作方式
进入本仓库后，先阅读本文件，再开始分析、修改或输出结论。不要跳过现有文档直接下判断，至少先结合根目录 `README.md`、`docs/`、目标模块代码和相关配置确认上下文。

日常交互遵循以下习惯：

- 先整理执行方案，说明目标、涉及模块、预计修改点和验证方式，待用户评审确认后再执行。
- 不要想当然；如果需求存在歧义、前提不清或有多种实现路径，先说清假设与取舍，再继续。
- 先确认任务位于 `entrance`、`system`、`user`、`detection` 还是 `tools/activate-tool`，再沿配置、Controller、Service、Mapper、XML 和调用链向下分析。
- 涉及认证、字典、日志、注册资源、WebSocket 或 Netty 通信链路时，先核对已有实现和 `docs/` 中的说明，避免只看局部代码就下结论。
- 回复风格保持简洁、直接，优先给出可执行结果；如果存在限制、风险或未验证部分，需要明确说明。

## 执行与修改原则
- 简单优先：只做当前需求所需的最小改动，不额外引入新功能、抽象层、配置项或“顺手优化”。
- 外科手术式修改：只改与任务直接相关的文件和代码行，不重构无关模块，不调整无关格式或注释。
- 保持现有风格：遵循仓库已有包结构、分层方式、命名和写法，不按个人偏好重写。
- 只清理自己造成的问题：可以删除因本次修改而产生的未使用 `import`、变量或方法；不要删除仓库中原本就存在的死代码，除非用户明确要求。
- 先定义验证方式：执行方案里要写清楚“改哪里、怎么判断改对了”；默认通过代码路径、配置一致性和受影响范围检查进行验证。
- 除非用户明确要求，否则不执行任何 `mvn` 编译、打包、测试或其他构建命令。
- 所有导出或生成文件名统一追加日期，格式为“原文件名 + `_` + `yyyyMMdd` + 原扩展名”，例如 `暂态事件列表_20260516.xlsx`；新增下载导出、临时生成或落盘保存文件时，优先复用目标模块已有文件名工具，不要在业务代码中散落手写日期拼接。

## 项目结构与模块划分
`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 文件名应与接口名保持一致。业务代码中，关键流程、分支判断、状态流转或容易误解的节点需要补充简洁的中文注释，但不要添加无信息量的注释。
- 参照 `user` 模块的组织方式，Controller 与 Service 都按职责拆分；不同职责的方法放到不同 `*Controller`、`*Service`、`*ServiceImpl` 中，同一模块后续新增方法也要沿既有职责边界归类，不再回退为单一大类承载全部接口。

## 数据与 SQL 约束
- 新增业务表的 DO 优先复用当前 `BaseDO` / 审计字段风格；除非表本身明确不需要逻辑删除，不要再引入另一套审计基类。
- 不要假设运行时存在自动数据库迁移；如果代码依赖新表、新字段或新索引，必须同步补齐对应 SQL 与文档说明。
- SQL 脚本应放在目标模块的 `src/main/resources/sql/...` 下，并保持可审阅、可单独执行、语义清晰。
- 变更缓存、日志、审计相关逻辑时，优先沿用现有机制，不要绕开现有登录上下文、缓存约定和审计字段填充方式。
- 涉及 `sys_dict_type`、`sys_dict_data` 的字典类型编码、字典数据编码或固定字典数据 ID 时，必须统一维护在 `system/src/main/java/com/njcn/gather/system/pojo/constant/DictConst.java`；后续新增使用点也要先补常量再引用，不要在业务代码、SQL 或文档中散落硬编码。
- 新增或保留字典初始化 SQL 前，必须先确认对应字典类型在后端代码、配置或明确页面契约中确实被使用；未使用的字典类型和字典数据不要写入 `sys_dict_type`、`sys_dict_data` 初始化脚本。

## 注释与编码
- 新增或修改代码时，关键字段、关键分支、关键约束和非直观实现应补充简洁中文注释。
- 不要为了省事删除原有有效注释，也不要添加无信息量的注释。
- 写入中文内容时必须保持 UTF-8 编码，并自行检查中文显示是否正常；不要用“改成英文”规避乱码问题。

## 提交与合并请求规范
当前 `main` 分支尚无可参考的提交历史，仓库内也没有既有提交规范。建议使用“模块前缀 + 动词短句”的提交格式，例如 `user: 优化登录会话校验`、`system: 增加字典参数校验`。提交 PR 时应说明影响模块、配置或数据结构变更、人工验证步骤；若接口行为有变化，附上请求与响应示例。

## 安全与配置提示
将 `application.yml` 视为环境配置文件处理，不要在提交中新增明文密钥、数据库口令或许可证材料。本地运行时需保证 `D:\logs` 可写；如部署环境不同，应通过配置覆盖日志目录。