ci: add Woodpecker pipeline; docs: add review and tasks; docs: add AGENTS.md

.woodpecker.yml

@@ -0,0 +1,15 @@
+pipeline:
+  build_test:
+    image: maven:3.9-eclipse-temurin-17
+    when:
+      event: [ push, pull_request, tag ]
+    commands:
+      - mvn -B -DskipTests=false clean verify
+
+  package:
+    image: maven:3.9-eclipse-temurin-17
+    when:
+      event: [ push, tag ]
+    commands:
+      - mvn -B -DskipTests clean package
+

AGENTS.md

@@ -0,0 +1,47 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- Spring Boot 3 (Java 17) Maven app.
+- Key paths:
+  - `src/main/java` — root package `com.mosquito.project` (modules: `controller`, `service`, `domain`, `dto`, `job`, `exception`).
+  - `src/main/resources` — app config (`application.properties`), Flyway migrations in `db/migration`.
+  - `src/test/java` — JUnit 5 tests mirroring `main` packages.
+  - `docs/`, `specs/` — documentation and specifications.
+  - `target/` — build outputs (generated).
+
+## Build, Test, and Development Commands
+- Build: `mvn clean package` — compile, test, and create JAR in `target/`.
+- Run (dev): `mvn spring-boot:run` — start app with live reload of resources.
+- Run (JAR): `java -jar target/mosquito-0.0.1-SNAPSHOT.jar`.
+- Test all: `mvn test`.
+- Test one: `mvn -Dtest=ActivityServiceTest test`.
+- Verify: `mvn verify` — full lifecycle checks.
+
+## Coding Style & Naming Conventions
+- Java 17; 4-space indentation; one class per file; braces on same line.
+- Packages: lowercase under `com.mosquito.project`.
+- Classes: `PascalCase`; methods/fields: `camelCase`; constants: `UPPER_SNAKE_CASE`.
+- DTOs end with `Request`/`Response`; exceptions end with `Exception`.
+- Use Lombok where present (e.g., `@Getter`, `@Builder`); avoid wildcard imports.
+- Validate inputs with Bean Validation annotations (e.g., `@NotNull`, `@Size`).
+
+## Testing Guidelines
+- Frameworks: JUnit 5, Spring Boot Test, WebMvcTest/MockMvc; H2 and Embedded Redis for tests; Testcontainers available when needed.
+- Location: `src/test/java` with names `*Test.java`; mirror package of code under test.
+- Conventions: method names like `shouldDoX_whenY()`; prefer fast slice tests for controllers, `@SpringBootTest` for integration.
+- Run: `mvn test` or a focused run via `-Dtest=...`.
+
+## Commit & Pull Request Guidelines
+- Use Conventional Commits: `feat|fix|docs|test|refactor|chore(scope): message`.
+- Example: `feat(activity): add graph endpoint with validation`.
+- PRs: include purpose, linked issues, API examples or reproduction steps, updated tests/docs, and ensure `mvn -q verify` passes.
+
+## Security & Configuration Tips
+- App config in `src/main/resources/application.properties` (e.g., `spring.redis.host/port`); DB via `SPRING_DATASOURCE_*` env vars.
+- Never commit secrets; prefer environment variables or an untracked `application-local.properties`.
+- Database schema changes go through Flyway migrations in `src/main/resources/db/migration`.
+
+## Agent-Specific Notes
+- Keep changes minimal and localized; match the existing package layout.
+- Avoid introducing new dependencies without discussion; update tests and docs with behavior changes.
+

docs/review-2025-09-30.md

@@ -0,0 +1,30 @@
+# 代码审查报告（2025-09-30）
+
+## 概览
+- 技术栈：Spring Boot 3、Java 17、Maven、JUnit 5、MockMvc、Flyway、Redis（缓存，测试为嵌入式）。
+- 构建与测试：已联网执行 `mvn clean verify` 成功。产物 `target/mosquito-0.0.1-SNAPSHOT.jar` 生成。
+- 测试统计：共 26 个测试，全通过（0 失败/0 错误/0 跳过），详见 `target/surefire-reports/`。
+
+## 结构与模块
+- 包结构清晰：`controller / service / domain / dto / exception / job`。
+- 资源与迁移：`application.properties` 与 Flyway 迁移（V1–V5）完整，命名规范。
+- 文档完善：`docs/`（API、架构、数据模型、测试计划）与 `specs/` 分层合理。
+
+## 主要发现
+- 控制器：输入校验充分（`@Valid`），返回码语义正确；异常部分依赖注解映射，建议统一异常处理。
+- 服务：`ActivityService` 为内存态实现，具备并发安全；`getLeaderboard` 使用 `Thread.sleep` 模拟耗时，建议替换为可注入的延迟或移除。
+- 领域模型：当前未持久化（无 JPA 注解），与 Flyway 表结构存在偏差（如 JSONB 字段、状态字段等）。
+- 定时任务：`StatisticsAggregationJob` 逻辑简单明确，易扩展为真实数据聚合。
+- 依赖：引入了 JPA/AMQP 但暂未使用；`javax.annotation-api` 在 Boot 3 生态建议迁移至 `jakarta.annotation`（仅测试配置中使用）。
+- 缓存：`@Cacheable("leaderboards")` 生效，建议补充 TTL、序列化策略与命名规范。
+
+## 建议优先级
+1) 统一异常处理与错误响应格式（高）。
+2) 去除 `Thread.sleep` 模拟延迟（高）。
+3) 对齐领域模型与数据库（引入 JPA 实体/仓储）（高）。
+4) 缓存策略（TTL、序列化、命名）与多环境配置（中）。
+5) API Key 安全增强与审计（中）。
+6) 测试覆盖补齐（奖励/多级奖励/上传/权限）（中）。
+7) 依赖精简或尽快落地 AMQP/JPA（中）。
+8) 覆盖率基线（JaCoCo）与质量门禁（中）。
+

docs/tasks-2025-09-30.md

@@ -0,0 +1,73 @@
+# 任务清单（质量闭环：分析 → 实施 → 验证 → 优化）
+
+## 0) 推送至 Gitea 并启用 CI/CD（Woodpecker）
+- 分析：需要标准化远程仓库与流水线，以便每个任务完成后自动执行完整验证。
+- 实施：
+  - 在 Gitea 上创建仓库（建议名称：mosquito）。
+  - 本地添加远程并推送：`git remote add origin <gitea_url>; git push -u origin <branch>`。
+  - 使用 Woodpecker：已添加 `.woodpecker.yml`，默认在 push/PR 触发 `mvn clean verify` 全量验证与打包。
+- 验证：在 Gitea 中查看流水线执行成功（build+test 通过，产物成功构建）。
+- 优化：后续按需要加入缓存、制品归档、分支保护与质量门禁。
+
+## 1) 统一异常处理与错误响应格式
+- 分析：当前仅部分异常带 `@ResponseStatus`，无统一错误结构（code/message/path/timestamp）。
+- 实施：新增 `GlobalExceptionHandler`（`@ControllerAdvice`），覆盖验证异常、业务异常与兜底异常；定义标准错误响应模型。
+- 验证：
+  - 控制器集成测试断言 400/403/404 等状态码与错误体结构。
+  - 示例：`mvn -q -Dtest=*ControllerTest test`。
+- 优化：记录错误码表到 `docs/api.md`，引入日志关联 ID。
+
+## 2) 移除 `Thread.sleep` 模拟延迟
+- 分析：`ActivityService#getLeaderboard` 阻塞线程，影响吞吐与可测试性。
+- 实施：引入 `DelayProvider` 接口并在生产实现为无延迟，测试实现可配置；删除 `Thread.sleep`。
+- 验证：缓存测试通过且时延显著下降；`ActivityServiceCacheTest` 仍然命中缓存。
+- 优化：必要时改为异步计算与预热策略。
+
+## 3) 领域模型与数据库对齐（引入 JPA / Repository）
+- 分析：领域为内存态，与 Flyway 表（如 JSONB、状态字段）不一致。
+- 实施：为 `Activity / ApiKey / DailyActivityStats / MultiLevelRewardRule` 增加 JPA 注解与映射；新增 `Repository`；服务改用持久化。
+- 验证：
+  - H2 下 `@DataJpaTest` 与 `@SpringBootTest` 通过；`SchemaVerificationTest` 增强校验关键列与约束。
+  - 示例：`mvn -q -Dtest=*Jpa* test`。
+- 优化：实体与 Flyway 迁移保持前滚兼容；引入测试数据工厂。
+
+## 4) 缓存策略与配置
+- 分析：仅使用 `@Cacheable`，缺少 TTL、序列化与命名规范。
+- 实施：添加 `CacheConfig` 设置默认 TTL（如 5m）、`RedisCacheConfiguration` 与 JSON 序列化；键空间命名统一。
+- 验证：集成测试校验缓存生效与过期；命中率指标可观测。
+- 优化：按端点分组 TTL；加入手动失效接口或消息驱动失效。
+
+## 5) API Key 安全增强
+- 分析：当前为 `UUID + salt + SHA-256`；建议 KDF（BCrypt/Argon2）并完善审计。
+- 实施：引入 `BCryptPasswordEncoder` 存储哈希，新增校验与轮换逻辑，记录 `last_used_at` 更新。
+- 验证：
+  - 单测验证加密强度（无法逆推）与匹配成功；
+  - 集成测试覆盖创建/撤销/使用审计。
+- 优化：支持密钥前缀与分段展示；限流与告警。
+
+## 6) 覆盖率与质量门禁
+- 分析：无覆盖率阈值；关键逻辑测试缺口。
+- 实施：引入 JaCoCo 插件并设置最低阈值（例如 80%）；补充奖励计算、多级奖励、上传大小/类型、权限异常等单测。
+- 验证：`mvn -q verify` 通过且生成 `target/site/jacoco/index.html`。
+- 优化：在 CI 中发布覆盖率报告与趋势。
+
+## 7) 多环境配置（dev/test/prod）
+- 分析：仅 `application.properties`，未分环境。
+- 实施：新增 `application-dev.yml`、`application-test.yml`、`application-prod.yml`；区分数据源/Flyway/日志级别/缓存设置。
+- 验证：本地 `SPRING_PROFILES_ACTIVE=dev` 可运行，测试默认 `test`，构建产物默认 `prod`。
+- 优化：敏感配置使用环境变量或外部化配置。
+
+## 8) 依赖治理（JPA/AMQP）
+- 分析：已引入 `spring-boot-starter-data-jpa`、`spring-boot-starter-amqp`，暂未落地。
+- 实施：二选一：
+  1) 近期不引入消息与持久化：移除未用 starter；
+  2) 落地仓储与消息接口：新增最小可用实现与集成测试。
+- 验证：`mvn -q verify` 通过；依赖树精简（`mvn -q dependency:tree`）。
+- 优化：定期审计依赖、锁定版本、启用漏洞扫描。
+
+## 9) 注解迁移（javax → jakarta，仅测试配置）
+- 分析：`EmbeddedRedisConfiguration` 使用 `javax.annotation`。
+- 实施：迁移至 `jakarta.annotation`；清理 `javax.annotation-api` 依赖或限定 test scope。
+- 验证：测试环境可正常启动嵌入式 Redis，端口注入仍生效。
+- 优化：统一全仓库注解命名空间。
+