# Repository Guidelines（仓库贡献指南）

## 项目结构与模块组织
- 应用模块：`tlias-web-management/`（Maven，Java 17，Spring Boot）。
- 源码：`tlias-web-management/src/main/java/`（如 `org/example/controller`、`service`、`mapper`、`pojo`、`utils`）。
- 资源：`tlias-web-management/src/main/resources/`（`application.yaml`、`logback.xml`）。
- 测试：`tlias-web-management/src/test/java/`（JUnit 5，Spring Boot 测试）。
- 文档：`docs/`（如 `docs/API.md`）；运行日志位于 `logs/`。

## 构建、测试与本地运行
- 构建产物：`cd tlias-web-management && mvn clean package`
- 本地运行：`mvn spring-boot:run`
- 执行测试：`mvn test`
- 运行打包 JAR：`java -jar target/tlias-web-management-0.0.1-SNAPSHOT.jar`

## 代码风格与命名约定
- Java 17；缩进 4 空格；UTF-8；建议单行 ≤120 列。
- 包名小写（`org.example.*`）；类名 PascalCase；方法/字段 camelCase。
- 分层后缀：`*Controller`、`*Service`、`*Mapper`；数据对象放在 `pojo`。
- 优先使用 Lombok（如 `@Data`、`@Builder`）减少样板代码，避免手写 getter/setter。

## 测试规范
- 测试框架：JUnit 5 + `spring-boot-starter-test`。
- 位置与命名：`src/test/java/`；测试类以 `*Tests.java` 结尾。
- 倡导切片/集成测试覆盖控制器与服务；对外部 IO（DB/OSS）尽量 mock/stub。
- 常用命令：`mvn test` 或 `mvn -DskipTests=false verify`。

## 提交与 Pull Request 规范
- 建议使用 Conventional Commits：`feat:`、`fix:`、`docs:`、`refactor:`、`test:`、`chore:`。
- PR 应包含：变更目的与摘要、关联 issue、API/UI 变更截图、测试说明、迁移/配置变更点。
- 变更应聚焦单一主题；如接口或行为有变更请同步更新 `docs/` 与 README。

## 安全与配置提示
- 禁止提交密钥。通过环境变量覆盖 DB/OSS：`SPRING_DATASOURCE_URL`、`SPRING_DATASOURCE_USERNAME`、`SPRING_DATASOURCE_PASSWORD`、`OSS_ACCESS_KEY_ID`、`OSS_ACCESS_KEY_SECRET`。
- 建议本地使用 `application-local.yaml`，并以 `--spring.profiles.active=local` 启动。

## 架构概览
- 流程：Controller → Service → Mapper（MyBatis）→ DB；分页使用 PageHelper；全局异常由 `GlobalExceptionHandler` 处理。
- 入口类：`tlias-web-management/src/main/java/org/example/TliasWebManagementApplication.java`。

## Agent 注意事项
- 遵循本指南，尽量小步、符合 Spring Boot 惯例地修改。
- 涉及数据库的测试需确保 MySQL 可达且配置正确；否则请使用 mock/stub。