191 lines
7.6 KiB
Markdown
191 lines
7.6 KiB
Markdown
# `sftp-manager` AGENTS 指南
|
||
|
||
本文件面向在本仓库内执行任务的自动化 Coding Agent。
|
||
请将其作为本项目在构建、测试、编码规范方面的本地权威说明。
|
||
|
||
## 1）项目概览
|
||
|
||
- 技术栈：Spring Boot 2.7.18、Java 8、Maven、Spring Data JPA、H2、JSch、原生 HTML/CSS/JS。
|
||
- 启动入口：`src/main/java/com/sftp/manager/SftpManagerApplication.java`。
|
||
- 主要目录结构：
|
||
- `src/main/java/com/sftp/manager/controller/`：HTTP 控制器
|
||
- `src/main/java/com/sftp/manager/service/`：业务逻辑（SFTP、本地文件）
|
||
- `src/main/java/com/sftp/manager/model/`：实体模型
|
||
- `src/main/java/com/sftp/manager/repository/`：JPA 仓库
|
||
- `src/main/java/com/sftp/manager/dto/`：接口请求/响应 DTO
|
||
- `src/main/resources/static/`：前端静态资源
|
||
- `src/main/resources/application*.yml`：运行配置
|
||
- 默认端口：`48081`（见 `application.yml`）。
|
||
- 生产环境可启用 `prod` profile（见 `application-prod.yml`）。
|
||
|
||
## 2）Cursor / Copilot 规则检查结果
|
||
|
||
已检查以下路径，当前未发现规则文件：
|
||
|
||
- `.cursor/rules/`
|
||
- `.cursorrules`
|
||
- `.github/copilot-instructions.md`
|
||
|
||
若后续新增上述文件，请立即同步更新本 `AGENTS.md`。
|
||
新增规则应视为更高优先级约束并优先遵循。
|
||
|
||
## 3）构建、运行、测试命令
|
||
|
||
默认在仓库根目录执行命令。
|
||
|
||
### 3.1 Maven 构建与打包
|
||
|
||
- 仅编译：`mvn clean compile`
|
||
- 完整打包（含测试）：`mvn clean package`
|
||
- 跳过测试打包：`mvn clean package -DskipTests`
|
||
- 安装到本地仓库：`mvn clean install`
|
||
|
||
### 3.2 本地运行
|
||
|
||
- 开发运行：`mvn spring-boot:run`
|
||
- 运行 JAR：`java -jar target/sftp-manager-1.0.0.jar`
|
||
- 生产配置运行：`java -jar target/sftp-manager-1.0.0.jar --spring.profiles.active=prod`
|
||
|
||
### 3.3 Docker 运行
|
||
|
||
- Linux/Mac 一键启动：`./run.sh`
|
||
- Windows 一键启动：`run.bat`
|
||
- 手动启动：`docker compose up -d --build`
|
||
- 手动停止：`docker compose down`
|
||
|
||
### 3.4 测试命令（重点：单测定向执行）
|
||
|
||
当前仓库尚无 `src/test/**/*.java` 文件。
|
||
当新增测试后，按以下方式执行：
|
||
|
||
- 执行全部测试：`mvn test`
|
||
- 执行单个测试类：`mvn -Dtest=ConnectionServiceTest test`
|
||
- 执行单个测试方法：`mvn -Dtest=ConnectionServiceTest#connect_success test`
|
||
- 执行多个测试类：`mvn -Dtest=ConnectionServiceTest,FileControllerTest test`
|
||
|
||
若出现“测试未执行”，优先检查命名是否满足 Surefire 默认规则：
|
||
|
||
- `*Test`
|
||
- `*Tests`
|
||
- `*TestCase`
|
||
|
||
### 3.5 Lint / 质量门禁
|
||
|
||
`pom.xml` 当前未配置 Checkstyle、Spotless、PMD 等专用 lint 插件。
|
||
因此以“编译 + 测试”作为质量门禁：
|
||
|
||
- 快速门禁：`mvn clean compile`
|
||
- 完整门禁：`mvn clean test`
|
||
|
||
### 3.6 当前测试覆盖（供 Agent 参考）
|
||
|
||
目前已存在以下单测类，可按需定向执行：
|
||
|
||
- `ConnectionControllerTest`
|
||
- `FileControllerTest`
|
||
- `ConnectionServiceTest`
|
||
- `SessionManagerTest`
|
||
- `LocalFileServiceTest`
|
||
|
||
示例：
|
||
|
||
- 执行单个测试类：`mvn -Dtest=LocalFileServiceTest test`
|
||
- 执行单个测试方法：`mvn -Dtest=LocalFileServiceTest#renameFile_shouldAllowRenameInSameDirectory test`
|
||
|
||
## 4）代码风格与工程约定
|
||
|
||
## 4.1 Java / Spring 通用约定
|
||
|
||
- 必须保持 Java 8 兼容，不使用 Java 9+ 语法。
|
||
- 包路径维持在 `com.sftp.manager` 下。
|
||
- 控制器保持轻量，核心逻辑放到 `service` 层。
|
||
- API 返回统一使用 `ApiResponse<T>`。
|
||
- 延续既有接口前缀：
|
||
- `/api/connection/*`
|
||
- `/api/files/*`
|
||
- 沿用已有术语命名：`sessionId`、`sourcePath`、`targetPath`、`recursive`。
|
||
|
||
## 4.2 依赖注入风格
|
||
|
||
- 现有代码大量使用字段注入 `@Autowired`，修改旧文件时保持一致。
|
||
- 新增类可用构造器注入，但同一类内不要混用多种注入风格。
|
||
- 避免“仅改一点却全文件重构注入方式”的无关变更。
|
||
|
||
## 4.3 Imports 与格式
|
||
|
||
- 保持文件现有 import 分组习惯，尽量与周边代码一致。
|
||
- 一般顺序：项目/第三方 → Spring → `javax.*` → `java.*`。
|
||
- 避免通配符导入（`*`），优先显式导入。
|
||
- 使用 4 空格缩进，不使用 Tab。
|
||
- 保持现有大括号、注解换行和空行风格。
|
||
|
||
## 4.4 类型、DTO 与实体
|
||
|
||
- 避免原始类型集合，优先使用泛型（如 `List<FileInfo>`）。
|
||
- DTO/实体中，允许为空的数值或布尔优先用包装类型（`Integer`、`Long`、`Boolean`）。
|
||
- DTO 只做传输，不承载业务逻辑。
|
||
- 若同类文件已使用 Lombok `@Data`，新增同类对象可延续该模式。
|
||
|
||
## 4.5 命名规范
|
||
|
||
- 类名：PascalCase（如 `ConnectionService`）。
|
||
- 方法/变量/参数：camelCase（如 `getFileInfo`）。
|
||
- 常量：UPPER_SNAKE_CASE（如 `API_BASE`）。
|
||
- REST 路径：小写，必要时使用连字符，优先复用已有路径。
|
||
- Service 方法名优先“动词 + 对象”（如 `uploadToSftp`、`downloadFromSftp`）。
|
||
|
||
## 4.6 错误处理规范
|
||
|
||
- 先做参数校验，再执行核心逻辑。
|
||
- 控制器边界统一捕获异常，并映射为 `ApiResponse.error(...)`。
|
||
- 错误信息要包含上下文（路径、会话、操作类型），但不得泄露敏感信息。
|
||
- 清理流程中的异常可按现有模式忽略，但主流程异常不可静默吞掉。
|
||
- 保持面向用户的提示语风格与现有代码一致（当前以中文提示为主）。
|
||
|
||
## 4.7 文件与流处理
|
||
|
||
- 所有 `InputStream` / `OutputStream` 优先使用 `try-with-resources`。
|
||
- 明确“由谁负责关闭流”，避免重复关闭或泄漏。
|
||
- 递归文件操作需考虑部分失败、非法路径、权限不足等场景。
|
||
- 跨平台路径处理继续使用现有模式（`File.separator`、路径规范化）。
|
||
- 本地路径处理应统一规范化（`getCanonicalFile`），拒绝 `..` 上级目录穿越。
|
||
- 删除操作应防护根目录与系统关键目录（Windows 与 Unix 路径均需考虑）。
|
||
- 重命名默认按“同目录重命名”语义实现，不在重命名接口里隐式做跨目录移动。
|
||
|
||
## 4.8 持久化与配置约定
|
||
|
||
- 实体默认值与时间戳钩子（`@PrePersist` / `@PreUpdate`）保持一致。
|
||
- 不提交 `data/` 下数据库产物（`.gitignore` 已忽略相关文件）。
|
||
- 生产配置中的环境变量占位符应保留（如 `DB_USERNAME`、`DB_PASSWORD`）。
|
||
- 非需求驱动情况下，不扩展 Actuator 暴露范围。
|
||
|
||
## 4.9 前端静态资源约定
|
||
|
||
- 项目未配置 Node 构建链路，前端资源直接编辑 `static` 目录。
|
||
- 保持当前 jQuery 风格与状态驱动结构（见 `static/js/app.js`）。
|
||
- 保持双面板交互和响应式行为，不破坏现有 UX。
|
||
- 保持 CSS 变量与设计令牌风格，不做大规模 UI 体系替换。
|
||
|
||
## 5）Agent 工作流程建议
|
||
|
||
- 开始改动前，先阅读目标文件及相邻文件风格。
|
||
- 以最小必要改动为原则，避免无关重构。
|
||
- 未明确要求时，不更改端口、context-path、profile 行为。
|
||
- 新增功能优先补充可验证逻辑；有测试目录后优先补单元测试。
|
||
- 完成后至少运行一次编译校验；如有测试则执行相关测试。
|
||
- 若新增关键命令或流程，请同步更新本 `AGENTS.md`。
|
||
- 涉及安全边界（认证、文件系统、CORS、主机密钥）变更后，必须补至少一条对应单测。
|
||
|
||
## 6）常用命令速查
|
||
|
||
- `mvn clean compile`
|
||
- `mvn test`
|
||
- `mvn -Dtest=ClassName test`
|
||
- `mvn -Dtest=ClassName#methodName test`
|
||
- `mvn spring-boot:run`
|
||
- `mvn clean package -DskipTests`
|
||
- `java -jar target/sftp-manager-1.0.0.jar --spring.profiles.active=prod`
|
||
- `docker compose up -d --build`
|
||
|
||
请随项目演进持续维护本文件，确保其内容始终与仓库实际配置一致。
|