hdk-pay/llm.txt

# HDK-Pay 项目分析报告

## 1. 项目基本信息

- **项目名称**: HDK-Pay
- **项目类型**: PHP 支付平台 SDK
- **描述**: 用于连接 LuxPay 支付平台的 SDK
- **版本**: 1.11.1
- **PHP 版本要求**: >= 8.2
- **许可证**: MIT

## 2. 技术栈

### 2.1 核心依赖
- **PHP**: >= 8.2
- **Hyperf**: ~3.1.0 (框架)
- **Guzzle**: 用于 HTTP 请求
- **MoneyPHP**: 货币处理
- **Carbon**: 日期时间处理
- **BCMath 扩展**: 高精度数学计算

### 2.2 开发依赖
- **PHPUnit**: 单元测试
- **Pest**: 测试框架
- **PHPStan**: 静态代码分析
- **PHP-CS-Fixer**: 代码风格检查

## 3. 项目架构

### 3.1 目录结构
```
├── src/                    # 源代码目录
│   ├── Application/        # 应用层
│   │   ├── Command/        # 命令行工具
│   │   └── Dto/            # 数据传输对象
│   ├── Domain/             # 领域层
│   │   ├── Account/        # 账户领域
│   │   ├── Invoice/        # 发票领域
│   │   ├── Product/        # 产品领域
│   │   └── Transaction/    # 交易领域
│   ├── Enum/               # 枚举类
│   ├── Infrastructure/     # 基础设施层
│   │   └── Repository/     # 仓库实现
│   ├── Resource/           # 资源层
│   ├── Sdk/                # SDK 接口
│   ├── Trait/              # 特质
│   └── ConfigProvider.php  # 配置提供者
├── tests/                  # 测试目录
├── publish/                # 发布配置
├── scripts/                # 脚本工具
├── composer.json           # Composer 配置
└── README.md               # 项目说明
```

### 3.2 架构模式
- **领域驱动设计 (DDD)**: 项目采用 DDD 架构，清晰划分了领域层、应用层和基础设施层
- **依赖倒置原则**: 通过接口定义依赖，实现了高层模块与低层模块的解耦
- **聚合根模式**: 核心领域对象如 TransactionRecord、Invoice 等都继承自 AggregateRoot

## 4. 核心功能模块

### 4.1 账户管理
- **账户余额**: 管理用户账户余额和积分
- **积分日志**: 记录积分的增减变动
- **积分类型**: 支持多种积分类型管理

### 4.2 交易管理
- **订单处理**: 支持创建、查询、更新订单
- **支付类型**: 支持卡片支付和积分支付
- **订单状态**: 完整的订单生命周期管理
- **交易记录**: 详细的交易记录和退款记录

### 4.3 发票管理
- **发票创建**: 支持创建发票
- **地址管理**: 支持常用地址管理
- **发票产品**: 管理发票中的产品信息

### 4.4 产品管理
- **充值产品**: 管理充值产品
- **产品类型**: 支持多种产品类型
- **充值效果**: 定义充值产品的效果

## 5. 主要领域模型

### 5.1 账户领域
- **AccountBalance**: 账户余额聚合根
- **PointsBalance**: 积分余额值对象
- **PointLog**: 积分日志聚合根

### 5.2 交易领域
- **TransactionRecord**: 交易记录聚合根
- **Item**: 交易项值对象
- **CardTransaction**: 卡片交易值对象
- **PointTransaction**: 积分交易值对象

### 5.3 发票领域
- **Invoice**: 发票聚合根
- **Address**: 地址值对象
- **InvoiceInfo**: 发票信息值对象
- **InvoiceProduct**: 发票产品值对象

### 5.4 产品领域
- **RechargeProduct**: 充值产品聚合根
- **ProductItem**: 产品项实体
- **RechargeEffect**: 充值效果值对象

## 6. RPC 服务

### 6.1 核心 RPC 类
- **OrderRpc**: 订单相关 RPC 服务
- **GoodsRpc**: 商品相关 RPC 服务
- **StripeRpc**: Stripe 支付相关 RPC 服务
- **WechatRpc**: 微信支付相关 RPC 服务

### 6.2 主要接口
- **create**: 创建订单
- **webhooksNotificationHandler**: 处理 Webhooks 通知

## 7. 配置说明

### 7.1 配置文件
- **payment.php**: 支付平台配置文件，包含基础 URI 等配置

### 7.2 配置项
- **http_request.pay.rpc_base_uri**: RPC 基础 URI，通常为 https://pay.luxcreo.cn 或 https://test-pay.luxcreo.cn
- **payment.base_uri**: 支付平台基础 URI

## 8. 测试策略

### 8.1 测试类型
- **单元测试**: 测试单个类或方法
- **功能测试**: 测试完整的业务流程
- **集成测试**: 测试不同模块之间的交互

### 8.2 测试框架
- **PHPUnit**: 用于单元测试和功能测试
- **Pest**: 用于更简洁的测试编写

### 8.3 测试执行
```bash
vendor/bin/phpunit  # 运行所有测试
composer test       # 运行测试脚本
```

## 9. 开发流程

### 9.1 运行环境说明
项目通过本地运行 Docker 来创建运行容器，因此所有执行的终端命令都应该使用以下方式之一：
- 使用 `run-in-docker.sh` 脚本：`./run-in-docker.sh <command>`
- 使用 `scripts/test/` 下的脚本：`./scripts/test/<script-name>.sh`

### 9.2 安装依赖
```bash
./run-in-docker.sh composer install
```

### 9.3 代码风格检查
```bash
./run-in-docker.sh composer cs-fix
# 或使用专门的脚本
./scripts/test/code-style-check.sh
```

### 9.4 代码风格修复
```bash
./scripts/test/code-style-fix.sh
```

### 9.5 静态代码分析
```bash
./run-in-docker.sh composer analyse
# 或使用专门的脚本
./scripts/test/static-analysis.sh
```

### 9.6 运行测试
```bash
./run-in-docker.sh composer test
# 或使用专门的脚本
./scripts/test/all-tests.sh      # 运行所有测试
./scripts/test/unit-tests.sh     # 运行单元测试
```

### 9.7 CI 流程
```bash
./scripts/test/ci.sh
```

## 10. 发布与部署

### 10.1 发布配置
```bash
php bin/hyperf.php vendor:publish singularity/hdk-pay
```

### 10.2 部署方式
- 支持 Docker 部署
- 支持传统 PHP-FPM 部署
- 支持 Hyperf 协程部署

## 11. 总结

HDK-Pay 是一个基于 Hyperf 框架开发的支付平台 SDK，采用领域驱动设计架构，支持多种支付方式和交易类型。项目具有清晰的代码结构、完整的测试覆盖和良好的扩展性，适合作为企业级支付解决方案的基础组件。

主要特点：
- 基于 DDD 架构，领域模型清晰
- 支持多种支付方式和交易类型
- 完整的订单生命周期管理
- 强大的发票管理功能
- 灵活的配置和扩展机制
- 完善的测试覆盖
- 支持多环境部署

该项目为企业提供了一个可靠、安全、易于扩展的支付解决方案，能够满足不同业务场景的支付需求。