refactor: 适配项目目录结构从 app/ 改为 src/

修改 run-in-docker.sh 项目名以保持一致性更新测试脚本和 composer.json 中的目录引用添加项目文档和计划文件
2026-01-15 02:15:07 +08:00 · 2025-11-28 18:07:48 +08:00
parent cb938d6130
commit 6bc423417c
8 changed files with 301 additions and 16 deletions
--- a/.trae/documents/plan_20251128_095845.md
+++ b/.trae/documents/plan_20251128_095845.md
@@ -0,0 +1,19 @@
+# 生成 llm.txt 文件计划
+
+## 任务目标
+阅读整个项目，并生成 llm.txt 文件，总结项目的结构、功能和技术栈。
+
+## 实现步骤
+1. 退出计划模式，进入执行模式
+2. 生成 llm.txt 文件，包含以下内容：
+   - 项目基本信息
+   - 技术栈
+   - 项目架构
+   - 核心功能模块
+   - 主要领域模型
+   - RPC 服务
+   - 配置说明
+3. 确保文件内容全面、准确地反映项目结构和功能
+
+## 预期结果
+生成一个完整的 llm.txt 文件，包含项目的所有重要信息，便于后续参考和使用。
--- a/.trae/documents/plan_20251128_100205.md
+++ b/.trae/documents/plan_20251128_100205.md
@@ -0,0 +1,52 @@
+# 脚本适配计划
+
+## 任务目标
+根据 `/Users/weili/Projects/HDK/Pay/scripts/docker-env.sh` 参考，适配从 LuxPay 项目复制过来的脚本，包括 `run-in-docker.sh` 和 `scripts/test/` 下的所有测试脚本。
+
+## 适配分析
+
+### 1. 脚本文件分析
+
+#### 1.1 run-in-docker.sh
+- 功能：在 Docker 容器中运行命令
+- 镜像：`harbor.luxcreo.cn/library/hyperf:8.2-swoole`
+- 项目名：`lux-pay-run`
+- 行为：检查容器是否运行，如未运行则启动后台容器
+
+#### 1.2 scripts/docker-env.sh（参考）
+- 功能：启动交互式 Docker 容器
+- 镜像：`harbor.luxcreo.cn/library/hyperf:8.2-swoole`
+- 项目名：`hdk-pay`
+- 行为：直接启动交互式容器，退出后容器删除
+
+#### 1.3 测试脚本
+- 所有脚本都使用 `./run-in-docker.sh` 运行命令
+- 代码风格检查和修复脚本使用 `app/` 目录，但本项目使用 `src/`
+- 静态分析脚本使用 `app/` 目录，需要改为 `src/`
+- `phpspec-tests.sh` 可能不需要，因为本项目使用 PHPUnit/Pest
+
+### 2. 适配方案
+
+#### 2.1 适配 run-in-docker.sh
+- 保持基本功能不变
+- 考虑使用与参考脚本一致的项目名 `hdk-pay`
+- 确保容器配置与参考脚本兼容
+
+#### 2.2 适配测试脚本
+- 修改 `code-style-check.sh` 和 `code-style-fix.sh`：将 `app/` 改为 `src/`
+- 修改 `static-analysis.sh`：将 `app/` 改为 `src/`
+- 检查 `phpspec-tests.sh`：如不需要则删除
+- 确保所有脚本使用正确的目录结构
+
+#### 2.3 适配 composer.json 脚本
+- 修改 `analyse` 脚本：将 `./app` 改为 `./src`
+
+## 执行步骤
+
+1. 适配 `run-in-docker.sh` 脚本
+2. 适配 `scripts/test/` 下的所有测试脚本
+3. 适配 `composer.json` 中的脚本配置
+4. 测试脚本是否能正常运行
+
+## 预期结果
+所有脚本都能正确适配本项目，使用正确的目录结构和 Docker 环境，能够正常执行各种测试和代码质量检查任务。
--- a/composer.json
+++ b/composer.json
@@ -48,17 +48,17 @@
    }
  },
  "scripts": {
-    "post-root-package-install": [
-      "@php -r \"file_exists('.env') || copy('.env.example', '.env');\""
-    ],
-    "test": [
-      "rm -rf runtime",
-      "Composer\\Config::disableProcessTimeout",
-      "APP_STATUS=false pest --coroutine --prepend=tests/bootstrap.php --colors=always $1"
-    ],
-    "cs-fix": "php-cs-fixer fix $1",
-    "analyse": "phpstan analyse --memory-limit 300M -l 0 -c phpstan.neon ./app ./config"
-  },
+        "post-root-package-install": [
+            "@php -r \"file_exists('.env') || copy('.env.example', '.env');\""
+        ],
+        "test": [
+            "rm -rf runtime",
+            "Composer\\Config::disableProcessTimeout",
+            "APP_STATUS=false pest --coroutine --prepend=tests/bootstrap.php --colors=always $1"
+        ],
+        "cs-fix": "php-cs-fixer fix $1",
+        "analyse": "phpstan analyse --memory-limit 300M -l 0 -c phpstan.neon ./src ./config"
+    },
  "repositories": {
    "nest": {
      "type": "composer",
--- a/llm.txt
+++ b/llm.txt
@@ -0,0 +1,214 @@
+# 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 架构，领域模型清晰
+- 支持多种支付方式和交易类型
+- 完整的订单生命周期管理
+- 强大的发票管理功能
+- 灵活的配置和扩展机制
+- 完善的测试覆盖
+- 支持多环境部署
+
+该项目为企业提供了一个可靠、安全、易于扩展的支付解决方案，能够满足不同业务场景的支付需求。
--- a/run-in-docker.sh
+++ b/run-in-docker.sh
@@ -1,7 +1,7 @@
 #!/usr/bin/env sh

-# 使用独立项目名，与 docker-env.sh 区分
-project=lux-pay-run
+# 使用与 docker-env.sh 一致的项目名
+project=hdk-pay

 # 检查容器是否在运行
 if ! docker ps | grep -q "$project"; then
--- a/scripts/test/code-style-check.sh
+++ b/scripts/test/code-style-check.sh
@@ -3,4 +3,4 @@
 # 代码风格检查脚本

 # 检查代码风格，只使用配置文件中定义的规则
-./run-in-docker.sh vendor/bin/php-cs-fixer check app/ --allow-risky=yes --config=.php-cs-fixer.dist.php
+./run-in-docker.sh vendor/bin/php-cs-fixer check src/ --allow-risky=yes --config=.php-cs-fixer.dist.php
--- a/scripts/test/code-style-fix.sh
+++ b/scripts/test/code-style-fix.sh
@@ -3,4 +3,4 @@
 # 代码风格修复脚本

 # 修复代码风格，只使用配置文件中定义的规则
-./run-in-docker.sh vendor/bin/php-cs-fixer fix app/ tests/ --allow-risky=yes --config=.php-cs-fixer.dist.php
+./run-in-docker.sh vendor/bin/php-cs-fixer fix src/ tests/ --allow-risky=yes --config=.php-cs-fixer.dist.php
--- a/scripts/test/static-analysis.sh
+++ b/scripts/test/static-analysis.sh
@@ -3,4 +3,4 @@
 # 代码静态分析脚本

 # 运行完整的代码静态分析
-./run-in-docker.sh vendor/bin/phpstan analyse app/ tests/
+./run-in-docker.sh vendor/bin/phpstan analyse src/ tests/