q792602257/FrameTour-BE

Fork 0

Files

Jerry Yan 156c487c0f claude

2025-07-22 17:15:12 +08:00

4.1 KiB

Raw Permalink Blame History

CLAUDE.md

本文件为 Claude Code (claude.ai/code) 在此代码仓库中工作时提供指导。

构建和开发命令

构建应用程序

# 清理构建（默认跳过测试）
mvn clean package

# 清理构建并执行测试
mvn clean package -DskipTests=false

# 运行应用程序
mvn spring-boot:run

测试命令

# 运行特定测试类
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）

核心业务模块

工厂模式实现

三个主要工厂类管理第三方集成：

StorageFactory (com.ycwl.basic.storage.StorageFactory)
- 管理：本地存储、AWS S3、阿里云 OSS 存储适配器
- 配置节：storage.configs[]
PayFactory (com.ycwl.basic.pay.PayFactory)
- 管理：微信支付、聪明支付适配器
- 配置节：pay.configs[]
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 自动配置启动器：

支持多供应商的命名配置
通过配置进行默认供应商选择
针对不同环境的特定配置文件

常见开发模式

添加新的存储/支付/人脸识别供应商

实现相应接口（IStorageAdapter、IPayAdapter、IFaceBodyAdapter）
在相应的类型枚举中添加枚举值
更新工厂的 switch 表达式
如需要，添加配置类
在 application.yml 中更新新供应商配置

身份验证上下文

在整个应用程序中使用 BaseContextHandler.getUserId() 获取当前已认证用户 ID。

API 响应模式

所有 API 都返回 ApiResponse<T> 包装器，通过 CustomExceptionHandle 进行一致的错误处理。

添加新的定时任务

在 com.ycwl.basic.task 包中创建类
添加 @Component 和 @Profile("prod") 注解
使用 @Scheduled 进行基于 cron 的执行
遵循现有的错误处理和日志记录模式

4.1 KiB Raw Permalink Blame History