From 156c487c0fa25b3429dd98dfa9d3a68455774868 Mon Sep 17 00:00:00 2001
From: Jerry Yan <792602257@qq.com>
Date: Tue, 22 Jul 2025 17:15:12 +0800
Subject: [PATCH] claude

---
 .gitignore |   2 +
 CLAUDE.md  | 123 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 125 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/.gitignore b/.gitignore
index 5b8c69d..c3a4c0f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,5 @@
 .idea/
 logs/
 target/
+
+.claude
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..63c9ce5
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,123 @@
+# CLAUDE.md
+
+本文件为 Claude Code (claude.ai/code) 在此代码仓库中工作时提供指导。
+
+## 构建和开发命令
+
+### 构建应用程序
+```bash
+# 清理构建（默认跳过测试）
+mvn clean package
+
+# 清理构建并执行测试
+mvn clean package -DskipTests=false
+
+# 运行应用程序
+mvn spring-boot:run
+```
+
+### 测试命令
+```bash
+# 运行特定测试类
+mvn test -Dtest=FaceCleanerTest
+
+# 运行特定包的测试
+mvn test -Dtest="com.ycwl.basic.storage.adapters.*Test"
+
+# 运行所有测试
+mvn test -DskipTests=false
+```
+
+### 开发环境配置
+应用程序使用 Spring 配置文件：
+- 默认激活配置文件：`dev`
+- 生产环境配置文件：`prod`（启用定时任务）
+- 配置文件：`application-dev.yml`、`application-prod.yml`
+
+## 架构概览
+
+这是一个 Spring Boot 3.3.5 应用程序（Java 21），采用多租户架构，通过不同的 API 端点为不同的客户端类型提供服务。
+
+### 控制器架构
+- **移动端 APIs** (`/api/mobile/`)：面向移动应用的客户端端点
+- **PC 端 APIs** (`/api/`)：Web 仪表板/管理面板端点
+- **任务 APIs** (`/task/`)：后台工作和渲染任务端点
+- **外部 APIs**：专用集成（打印机、代理、viid、vpt、wvp）
+
+### 核心业务模块
+
+#### 工厂模式实现
+三个主要工厂类管理第三方集成：
+
+1. **StorageFactory** (`com.ycwl.basic.storage.StorageFactory`)
+   - 管理：本地存储、AWS S3、阿里云 OSS 存储适配器
+   - 配置节：`storage.configs[]`
+
+2. **PayFactory** (`com.ycwl.basic.pay.PayFactory`) 
+   - 管理：微信支付、聪明支付适配器
+   - 配置节：`pay.configs[]`
+
+3. **FaceBodyFactory** (`com.ycwl.basic.facebody.FaceBodyFactory`)
+   - 管理：阿里云、百度人脸识别适配器
+   - 配置节：`facebody.configs[]`
+
+#### 适配器模式
+每个工厂使用标准化接口：
+- `IStorageAdapter`：文件操作（上传/下载/删除/ACL）
+- `IPayAdapter`：支付生命周期（创建/回调/退款）
+- `IFaceBodyAdapter`：人脸识别操作
+
+#### 定时任务系统
+`com.ycwl.basic.task` 包中的后台任务（仅生产环境）：
+- `VideoTaskGenerator`：人脸识别和视频处理
+- `FaceCleaner`：人脸和存储清理任务
+- `DynamicTaskGenerator`：带延迟队列的动态任务创建
+- `ScenicStatsTask`：统计数据聚合
+
+### 数据库和持久化
+- **MyBatis Plus**：具有自动 CRUD 操作的 ORM
+- **MapperScan**：扫描 `com.ycwl.basic.mapper` 及子包
+- **数据库**：MySQL 配合 HikariCP 连接池
+- **Redis**：会话管理和缓存
+
+### 主要库和依赖
+- Spring Boot 3.3.5 启用 Java 21 虚拟线程
+- MyBatis Plus 3.5.5 用于数据库操作
+- JWT (jjwt 0.9.0) 用于身份验证
+- 微信支付 SDK 用于支付处理
+- 阿里云 OSS 和 AWS S3 用于文件存储
+- 阿里云和百度 SDK 用于人脸识别
+- OpenTelemetry 用于可观测性（开发环境中禁用）
+
+### 业务逻辑组织
+- **Service 层**：`service` 包中的业务逻辑实现
+- **Biz 层**：`biz` 包中的高级业务编排
+- **Repository 模式**：`repository` 包中的数据访问抽象
+- **自定义异常**：特定领域的异常处理
+
+### 配置管理
+每个模块使用 Spring Boot 自动配置启动器：
+- 支持多供应商的命名配置
+- 通过配置进行默认供应商选择
+- 针对不同环境的特定配置文件
+
+## 常见开发模式
+
+### 添加新的存储/支付/人脸识别供应商
+1. 实现相应接口（`IStorageAdapter`、`IPayAdapter`、`IFaceBodyAdapter`）
+2. 在相应的类型枚举中添加枚举值
+3. 更新工厂的 switch 表达式
+4. 如需要，添加配置类
+5. 在 application.yml 中更新新供应商配置
+
+### 身份验证上下文
+在整个应用程序中使用 `BaseContextHandler.getUserId()` 获取当前已认证用户 ID。
+
+### API 响应模式
+所有 API 都返回 `ApiResponse<T>` 包装器，通过 `CustomExceptionHandle` 进行一致的错误处理。
+
+### 添加新的定时任务
+1. 在 `com.ycwl.basic.task` 包中创建类
+2. 添加 `@Component` 和 `@Profile("prod")` 注解
+3. 使用 `@Scheduled` 进行基于 cron 的执行
+4. 遵循现有的错误处理和日志记录模式
\ No newline at end of file