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