chore: initial commit with CI pipeline, review and tasks docs

docs/tech-choices.md

@@ -0,0 +1,35 @@
+# 技术选型与决策
+
+本文档记录了项目在开发过程中所做的主要技术选型和架构决策，以便团队成员理解其背后的原因。
+
+## 1. 核心框架与语言
+
+- **Java 17**: 选用 Java 17 是因为它是一个长期支持（LTS）版本，提供了现代化的语言特性（如 Records, Sealed Classes 等），并拥有稳定的生态系统。
+- **Spring Boot 3**: 作为业界主流的Java开发框架，Spring Boot 极大地简化了配置和部署，通过其强大的自动配置和依赖管理能力，使我们能快速构建健壮的、生产级的Web服务。
+- **Maven**: 作为项目管理和构建工具，Maven 提供了标准的项目结构、强大的依赖管理和一致的构建流程。
+
+## 2. API与Web层
+
+- **RESTful API**: 我们选择构建RESTful风格的API，这是当前Web服务的标准实践，具有无状态、易于理解和前后端分离的优点。
+- **DTO (Data Transfer Object)**: 在Controller层，我们引入了DTO模式（例如 `CreateActivityRequest`）。
+  - **决策依据**: 将API的请求/响应结构与内部的领域模型（Domain Model）解耦。这样做的好处是：
+    1.  **API稳定性**: 内部领域模型的变化不会直接影响外部API的结构。
+    2.  **安全性**: 可以避免意外暴露领域模型中的敏感字段。
+    3.  **专用性**: 可以为特定的API端点定制数据结构，使其更清晰、更高效。
+- **Bean Validation**: 通过引入 `spring-boot-starter-validation` 并在DTO上使用 `@Valid` 和相关约束注解（如 `@NotBlank`），我们在Controller层实现了声明式的输入验证。这是一种标准的、非侵入性的验证方式，能保持业务逻辑的纯净。
+
+## 3. 数据库与持久化
+
+- **Flyway**: 用于数据库迁移管理。它通过版本化的SQL脚本来管理数据库结构演进，确保了在任何环境下（开发、测试、生产）数据库结构的一致性和可追溯性。
+- **H2 Database (用于测试)**: H2是一个轻量级的内存数据库，非常适合在单元测试和集成测试中使用。它启动速度快，无需外部依赖，可以确保测试环境的纯净和可重复性。
+- **PostgreSQL (用于生产)**: 在 `pom.xml` 中预先定义了依赖。PostgreSQL 是一个功能强大、稳定可靠的开源关系型数据库，适用于生产环境。
+
+## 4. 安全
+
+- **API密钥存储**: 采用哈希加盐（Salted Hashing）的方式存储API密钥。
+  - **决策依据**: 直接在数据库中存储明文API密钥是极不安全的。通过为每个密钥生成一个唯一的盐（Salt），并将其与密钥组合后进行哈希（SHA-256），我们只存储盐和哈希值。即使数据库被泄露，攻击者也无法直接反推出原始密钥，大大提高了安全性。
+
+## 5. 异常处理
+
+- **自定义异常**: 我们创建了业务特定的异常类，如 `ActivityNotFoundException` 和 `ApiKeyNotFoundException`。
+  - **决策依据**: 这使得代码的意图更清晰，并且可以利用 `@ResponseStatus` 注解将特定的业务异常直接映射到HTTP状态码（如 `404 Not Found`），简化了全局异常处理逻辑。