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 聚合了 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 可写；如部署环境不同，应通过配置覆盖日志目录。