1. 维护代码健壮

2. 更新项目结构文档

app/common/constant/AuthConstant.php

@@ -5,50 +5,70 @@ namespace app\common\constant;
 /**
  * 认证相关常量。
  *
- * 统一管理登录域、令牌状态、签名类型等枚举值。
+ * 统一管理登录域、会话状态、接口凭证状态和开放接口签名类型。
  */
 final class AuthConstant
 {
     /**
      * 管理员登录域。
      */
-    public const GUARD_ADMIN = 1;
+    public const GUARD_ADMIN = 'admin';
 
     /**
      * 商户登录域。
      */
-    public const GUARD_MERCHANT = 2;
+    public const GUARD_MERCHANT = 'merchant';
 
     /**
      * JWT 签名算法。
      */
-    public const JWT_ALG_HS256 = 'HS256';
+    public const JWT_ALGORITHM_HS256 = 'HS256';
 
     /**
-     * 令牌禁用状态。
+     * 会话令牌禁用状态。
      */
     public const TOKEN_STATUS_DISABLED = 0;
 
     /**
-     * 令牌启用状态。
+     * 会话令牌启用状态。
      */
     public const TOKEN_STATUS_ENABLED = 1;
 
     /**
-     * 登录禁用状态。
+     * 接口凭证禁用状态。
      */
-    public const LOGIN_STATUS_DISABLED = 0;
+    public const CREDENTIAL_STATUS_DISABLED = 0;
 
     /**
-     * 登录启用状态。
+     * 接口凭证启用状态。
      */
-    public const LOGIN_STATUS_ENABLED = 1;
+    public const CREDENTIAL_STATUS_ENABLED = 1;
 
     /**
      * API 签名类型：MD5。
      */
     public const API_SIGN_TYPE_MD5 = 0;
 
+    /**
+     * API 签名类型：SHA256WithRSA。
+     */
+    public const API_SIGN_TYPE_SHA256_WITH_RSA = 1;
+
+    /**
+     * API 签名类型名称：MD5。
+     */
+    public const API_SIGN_NAME_MD5 = 'MD5';
+
+    /**
+     * API 签名类型名称：SHA256WithRSA。
+     */
+    public const API_SIGN_NAME_SHA256_WITH_RSA = 'SHA256WithRSA';
+
+    /**
+     * API 签名类型归一化名称：SHA256WITHRSA。
+     */
+    public const API_SIGN_NORMALIZED_SHA256_WITH_RSA = 'SHA256WITHRSA';
+
     /**
      * 获取签名类型映射。
      *
@@ -57,24 +77,36 @@ final class AuthConstant
     public static function signTypeMap(): array
     {
         return [
-            self::API_SIGN_TYPE_MD5 => 'MD5',
+            self::API_SIGN_TYPE_MD5 => self::API_SIGN_NAME_MD5,
+            self::API_SIGN_TYPE_SHA256_WITH_RSA => self::API_SIGN_NAME_SHA256_WITH_RSA,
+        ];
+    }
+
+    /**
+     * 获取接口凭证状态映射。
+     *
+     * @return array<int, string> 接口凭证状态名称表
+     */
+    public static function credentialStatusMap(): array
+    {
+        return [
+            self::CREDENTIAL_STATUS_ENABLED => '启用',
+            self::CREDENTIAL_STATUS_DISABLED => '禁用',
         ];
     }
 
     /**
      * 获取登录域映射。
      *
-     * @return array<int, string> 登录域名称表
+     * @return array<string, string> 登录域名称表
      */
     public static function guardMap(): array
     {
         return [
-            self::GUARD_ADMIN => 'admin',
-            self::GUARD_MERCHANT => 'merchant',
+            self::GUARD_ADMIN => '管理后台',
+            self::GUARD_MERCHANT => '商户后台',
         ];
     }
 }
 
 
-
-

app/common/constant/CommonConstant.php

@@ -18,12 +18,12 @@ final class CommonConstant
     public const STATUS_ENABLED = 1;
 
     /**
-     * 否。
+     * 否，通常用于布尔类字段的数值表示。
      */
     public const NO = 0;
 
     /**
-     * 是。
+     * 是，通常用于布尔类字段的数值表示。
      */
     public const YES = 1;
 
@@ -56,4 +56,3 @@ final class CommonConstant
 
 
 
-

app/common/constant/EventConstant.php

@@ -0,0 +1,67 @@
+<?php
+
+namespace app\common\constant;
+
+/**
+ * 事件名称常量。
+ *
+ * 本类维护已定义的领域事件；事件是否实际启用处理器，以 config/event.php 注册为准。
+ * 生命周期服务可以先 dispatch 关键节点事件，后续需要告警、风控、统计或补偿时再注册 listener。
+ */
+final class EventConstant
+{
+    /**
+     * 系统配置已变更。
+     */
+    public const SYSTEM_CONFIG_CHANGED = 'system.config.changed';
+
+    /**
+     * 支付单首次进入成功态。
+     */
+    public const PAYMENT_PAY_ORDER_SUCCEEDED = 'payment.pay_order.succeeded';
+
+    /**
+     * 支付单进入失败态。
+     */
+    public const PAYMENT_PAY_ORDER_FAILED = 'payment.pay_order.failed';
+
+    /**
+     * 支付单进入关闭态。
+     */
+    public const PAYMENT_PAY_ORDER_CLOSED = 'payment.pay_order.closed';
+
+    /**
+     * 支付单进入超时态。
+     */
+    public const PAYMENT_PAY_ORDER_TIMEOUT = 'payment.pay_order.timeout';
+
+    /**
+     * 退款单进入成功态。
+     */
+    public const REFUND_ORDER_SUCCEEDED = 'payment.refund_order.succeeded';
+
+    /**
+     * 退款单进入失败态。
+     */
+    public const REFUND_ORDER_FAILED = 'payment.refund_order.failed';
+
+    /**
+     * 清算单进入成功态。
+     */
+    public const SETTLEMENT_ORDER_SUCCEEDED = 'payment.settlement_order.succeeded';
+
+    /**
+     * 清算单进入失败态。
+     */
+    public const SETTLEMENT_ORDER_FAILED = 'payment.settlement_order.failed';
+
+    /**
+     * 商户通知派发成功。
+     */
+    public const MERCHANT_NOTIFY_SUCCEEDED = 'payment.merchant_notify.succeeded';
+
+    /**
+     * 商户通知派发失败。
+     */
+    public const MERCHANT_NOTIFY_FAILED = 'payment.merchant_notify.failed';
+}

app/common/constant/FileConstant.php

@@ -69,23 +69,77 @@ final class FileConstant
      */
     public const STORAGE_REMOTE_URL = 4;
 
+    /**
+     * 文件存储默认引擎配置 key。
+     */
     public const CONFIG_DEFAULT_ENGINE = 'file_storage_default_engine';
+    /**
+     * 本地公开目录访问地址配置 key。
+     */
     public const CONFIG_LOCAL_PUBLIC_BASE_URL = 'file_storage_local_public_base_url';
+    /**
+     * 本地公开目录路径配置 key。
+     */
     public const CONFIG_LOCAL_PUBLIC_DIR = 'file_storage_local_public_dir';
+    /**
+     * 本地私有目录路径配置 key。
+     */
     public const CONFIG_LOCAL_PRIVATE_DIR = 'file_storage_local_private_dir';
+    /**
+     * 上传文件大小上限配置 key，单位 MB。
+     */
     public const CONFIG_UPLOAD_MAX_SIZE_MB = 'file_storage_upload_max_size_mb';
+    /**
+     * 远程下载大小上限配置 key，单位 MB。
+     */
     public const CONFIG_REMOTE_DOWNLOAD_LIMIT_MB = 'file_storage_remote_download_limit_mb';
+    /**
+     * 允许上传扩展名配置 key。
+     */
     public const CONFIG_ALLOWED_EXTENSIONS = 'file_storage_allowed_extensions';
+    /**
+     * 阿里云 OSS Endpoint 配置 key。
+     */
     public const CONFIG_OSS_ENDPOINT = 'file_storage_aliyun_oss_endpoint';
+    /**
+     * 阿里云 OSS Bucket 配置 key。
+     */
     public const CONFIG_OSS_BUCKET = 'file_storage_aliyun_oss_bucket';
+    /**
+     * 阿里云 OSS Access Key ID 配置 key。
+     */
     public const CONFIG_OSS_ACCESS_KEY_ID = 'file_storage_aliyun_oss_access_key_id';
+    /**
+     * 阿里云 OSS Access Key Secret 配置 key。
+     */
     public const CONFIG_OSS_ACCESS_KEY_SECRET = 'file_storage_aliyun_oss_access_key_secret';
+    /**
+     * 阿里云 OSS 公开域名配置 key。
+     */
     public const CONFIG_OSS_PUBLIC_DOMAIN = 'file_storage_aliyun_oss_public_domain';
+    /**
+     * 阿里云 OSS 地域配置 key。
+     */
     public const CONFIG_OSS_REGION = 'file_storage_aliyun_oss_region';
+    /**
+     * 腾讯云 COS 地域配置 key。
+     */
     public const CONFIG_COS_REGION = 'file_storage_tencent_cos_region';
+    /**
+     * 腾讯云 COS Bucket 配置 key。
+     */
     public const CONFIG_COS_BUCKET = 'file_storage_tencent_cos_bucket';
+    /**
+     * 腾讯云 COS SecretId 配置 key。
+     */
     public const CONFIG_COS_SECRET_ID = 'file_storage_tencent_cos_secret_id';
+    /**
+     * 腾讯云 COS SecretKey 配置 key。
+     */
     public const CONFIG_COS_SECRET_KEY = 'file_storage_tencent_cos_secret_key';
+    /**
+     * 腾讯云 COS 公开域名配置 key。
+     */
     public const CONFIG_COS_PUBLIC_DOMAIN = 'file_storage_tencent_cos_public_domain';
 
     /**
@@ -227,4 +281,3 @@ final class FileConstant
 
 
 
-

app/common/constant/LedgerConstant.php

@@ -7,19 +7,67 @@ namespace app\common\constant;
  */
 final class LedgerConstant
 {
+    /**
+     * 支付冻结流水。
+     */
     public const BIZ_TYPE_PAY_FREEZE = 0;
+    /**
+     * 支付扣费流水。
+     */
     public const BIZ_TYPE_PAY_DEDUCT = 1;
+    /**
+     * 支付释放流水。
+     */
     public const BIZ_TYPE_PAY_RELEASE = 2;
+    /**
+     * 清算入账流水。
+     */
     public const BIZ_TYPE_SETTLEMENT_CREDIT = 3;
+    /**
+     * 退款冲正流水。
+     */
     public const BIZ_TYPE_REFUND_REVERSE = 4;
+    /**
+     * 人工调整流水。
+     */
     public const BIZ_TYPE_MANUAL_ADJUST = 5;
+    /**
+     * 转账扣款流水。
+     */
+    public const BIZ_TYPE_TRANSFER_DEDUCT = 6;
+    /**
+     * 转账手续费流水。
+     */
+    public const BIZ_TYPE_TRANSFER_FEE = 7;
+    /**
+     * 转账释放流水。
+     */
+    public const BIZ_TYPE_TRANSFER_RELEASE = 8;
 
+    /**
+     * 账务事件的创建动作。
+     */
     public const EVENT_TYPE_CREATE = 0;
+    /**
+     * 账务事件的成功动作。
+     */
     public const EVENT_TYPE_SUCCESS = 1;
+    /**
+     * 账务事件的失败动作。
+     */
     public const EVENT_TYPE_FAILED = 2;
+    /**
+     * 账务事件的冲正动作。
+     */
     public const EVENT_TYPE_REVERSE = 3;
 
+    /**
+     * 流水入账方向。
+     */
     public const DIRECTION_IN = 0;
+    /**
+     * 流水出账方向。
+     */
     public const DIRECTION_OUT = 1;
 
     /**
@@ -36,6 +84,9 @@ final class LedgerConstant
             self::BIZ_TYPE_SETTLEMENT_CREDIT => '清算入账',
             self::BIZ_TYPE_REFUND_REVERSE => '退款冲正',
             self::BIZ_TYPE_MANUAL_ADJUST => '人工调整',
+            self::BIZ_TYPE_TRANSFER_DEDUCT => '转账扣款',
+            self::BIZ_TYPE_TRANSFER_FEE => '转账手续费',
+            self::BIZ_TYPE_TRANSFER_RELEASE => '转账释放',
         ];
     }
 
@@ -69,5 +120,3 @@ final class LedgerConstant
 }
 
 
-
-

app/common/constant/MerchantConstant.php

@@ -68,4 +68,3 @@ final class MerchantConstant
 
 
 
-

app/common/constant/NotifyConstant.php

@@ -7,22 +7,74 @@ namespace app\common\constant;
  */
 final class NotifyConstant
 {
+    /**
+     * 商户通知事件：支付成功。
+     */
+    public const EVENT_PAY_SUCCESS = 'PAY_SUCCESS';
+    /**
+     * 商户通知事件：退款成功。
+     */
+    public const EVENT_REFUND_SUCCESS = 'REFUND_SUCCESS';
+    /**
+     * 商户通知事件：清算完成。
+     */
+    public const EVENT_SETTLEMENT_SUCCESS = 'SETTLEMENT_SUCCESS';
+
+    /**
+     * 异步通知类型。
+     */
     public const NOTIFY_TYPE_ASYNC = 0;
+    /**
+     * 查单通知类型。
+     */
     public const NOTIFY_TYPE_QUERY = 1;
 
+    /**
+     * 异步回调类型。
+     */
     public const CALLBACK_TYPE_ASYNC = 0;
+    /**
+     * 同步回调类型。
+     */
     public const CALLBACK_TYPE_SYNC = 1;
 
+    /**
+     * 验证状态：未知。
+     */
     public const VERIFY_STATUS_UNKNOWN = 0;
+    /**
+     * 验证状态：成功。
+     */
     public const VERIFY_STATUS_SUCCESS = 1;
+    /**
+     * 验证状态：失败。
+     */
     public const VERIFY_STATUS_FAILED = 2;
 
+    /**
+     * 处理状态：待处理。
+     */
     public const PROCESS_STATUS_PENDING = 0;
+    /**
+     * 处理状态：成功。
+     */
     public const PROCESS_STATUS_SUCCESS = 1;
+    /**
+     * 处理状态：失败。
+     */
     public const PROCESS_STATUS_FAILED = 2;
 
+    /**
+     * 任务状态：待通知。
+     */
     public const TASK_STATUS_PENDING = 0;
+    /**
+     * 任务状态：成功。
+     */
     public const TASK_STATUS_SUCCESS = 1;
+    /**
+     * 任务状态：失败。
+     */
     public const TASK_STATUS_FAILED = 2;
 
     /**
@@ -92,8 +144,20 @@ final class NotifyConstant
             self::TASK_STATUS_FAILED => '失败',
         ];
     }
+
+    /**
+     * 获取商户通知事件映射。
+     *
+     * @return array<string, string> 商户通知事件名称表
+     */
+    public static function eventTypeMap(): array
+    {
+        return [
+            self::EVENT_PAY_SUCCESS => '支付成功',
+            self::EVENT_REFUND_SUCCESS => '退款成功',
+            self::EVENT_SETTLEMENT_SUCCESS => '清算完成',
+        ];
+    }
 }
 
 
-
-

app/common/constant/PaymentPluginStatusConstant.php

@@ -0,0 +1,98 @@
+<?php
+
+namespace app\common\constant;
+
+/**
+ * 支付插件协议状态常量。
+ *
+ * 这些状态用于插件和平台运行时之间传递渠道结果，不等同于内部订单状态码。
+ */
+final class PaymentPluginStatusConstant
+{
+    /**
+     * 渠道支付成功。
+     */
+    public const SUCCESS = 'success';
+
+    /**
+     * 渠道支付失败。
+     */
+    public const FAILED = 'failed';
+
+    /**
+     * 渠道仍在处理中。
+     */
+    public const PENDING = 'pending';
+
+    /**
+     * 渠道订单已关闭。
+     */
+    public const CLOSED = 'closed';
+
+    /**
+     * 渠道状态未知。
+     */
+    public const UNKNOWN = 'unknown';
+
+    /**
+     * 插件回调允许返回的状态。
+     *
+     * @return array<int, string>
+     */
+    public static function notifyStatuses(): array
+    {
+        return [
+            self::SUCCESS,
+            self::FAILED,
+            self::PENDING,
+        ];
+    }
+
+    /**
+     * 插件查单成功状态别名。
+     *
+     * @return array<int, string>
+     */
+    public static function successQueryAliases(): array
+    {
+        return [
+            self::SUCCESS,
+            'paid',
+            'pay_success',
+            'trade_success',
+            'trade_finished',
+            'finished',
+            'successful',
+        ];
+    }
+
+    /**
+     * 插件查单失败状态别名。
+     *
+     * @return array<int, string>
+     */
+    public static function failedQueryAliases(): array
+    {
+        return [
+            self::FAILED,
+            'fail',
+            'error',
+            'pay_error',
+            'trade_fail',
+        ];
+    }
+
+    /**
+     * 插件查单关闭状态别名。
+     *
+     * @return array<int, string>
+     */
+    public static function closedQueryAliases(): array
+    {
+        return [
+            self::CLOSED,
+            'close',
+            'trade_closed',
+        ];
+    }
+}

app/common/constant/RouteConstant.php

@@ -20,12 +20,12 @@ final class RouteConstant
     public const CHANNEL_TYPE_MERCHANT_SELF = 1;
 
     /**
-     * 代收通道模式。
+     * 代收通道模式，资金直接进入平台侧。
      */
     public const CHANNEL_MODE_COLLECT = 0;
 
     /**
-     * 自收通道模式。
+     * 自收通道模式，资金直接进入商户侧。
      */
     public const CHANNEL_MODE_SELF = 1;
 
@@ -87,4 +87,3 @@ final class RouteConstant
 
 
 
-

app/common/constant/TradeConstant.php

@@ -7,33 +7,105 @@ namespace app\common\constant;
  */
 final class TradeConstant
 {
+    /**
+     * D0 清算周期。
+     */
     public const SETTLEMENT_CYCLE_D0 = 0;
+    /**
+     * D1 清算周期。
+     */
     public const SETTLEMENT_CYCLE_D1 = 1;
+    /**
+     * D7 清算周期。
+     */
     public const SETTLEMENT_CYCLE_D7 = 2;
+    /**
+     * T1 清算周期。
+     */
     public const SETTLEMENT_CYCLE_T1 = 3;
+    /**
+     * 其他清算周期。
+     */
     public const SETTLEMENT_CYCLE_OTHER = 4;
 
+    /**
+     * 订单已创建，等待发起支付。
+     */
     public const ORDER_STATUS_CREATED = 0;
+    /**
+     * 订单支付中。
+     */
     public const ORDER_STATUS_PAYING = 1;
+    /**
+     * 订单支付成功。
+     */
     public const ORDER_STATUS_SUCCESS = 2;
+    /**
+     * 订单支付失败。
+     */
     public const ORDER_STATUS_FAILED = 3;
+    /**
+     * 订单已关闭。
+     */
     public const ORDER_STATUS_CLOSED = 4;
+    /**
+     * 订单已超时。
+     */
     public const ORDER_STATUS_TIMEOUT = 5;
 
+    /**
+     * 手续费未处理。
+     */
     public const FEE_STATUS_NONE = 0;
+    /**
+     * 手续费已冻结。
+     */
     public const FEE_STATUS_FROZEN = 1;
+    /**
+     * 手续费已扣除。
+     */
     public const FEE_STATUS_DEDUCTED = 2;
+    /**
+     * 手续费已释放。
+     */
     public const FEE_STATUS_RELEASED = 3;
 
+    /**
+     * 清算状态为空。
+     */
     public const SETTLEMENT_STATUS_NONE = 0;
+    /**
+     * 清算待处理。
+     */
     public const SETTLEMENT_STATUS_PENDING = 1;
+    /**
+     * 清算已完成。
+     */
     public const SETTLEMENT_STATUS_SETTLED = 2;
+    /**
+     * 清算已冲正。
+     */
     public const SETTLEMENT_STATUS_REVERSED = 3;
 
+    /**
+     * 退款单已创建。
+     */
     public const REFUND_STATUS_CREATED = 0;
+    /**
+     * 退款单处理中。
+     */
     public const REFUND_STATUS_PROCESSING = 1;
+    /**
+     * 退款单成功。
+     */
     public const REFUND_STATUS_SUCCESS = 2;
+    /**
+     * 退款单失败。
+     */
     public const REFUND_STATUS_FAILED = 3;
+    /**
+     * 退款单已关闭。
+     */
     public const REFUND_STATUS_CLOSED = 4;
 
     /**
@@ -231,4 +303,3 @@ final class TradeConstant
 
 
 
-

app/common/constant/TransferConstant.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace app\common\constant;
+
+/**
+ * 转账状态枚举。
+ */
+final class TransferConstant
+{
+    /**
+     * 转账待处理状态。
+     */
+    public const TRANSFER_STATUS_PENDING = 0;
+    /**
+     * 转账成功状态。
+     */
+    public const TRANSFER_STATUS_SUCCESS = 1;
+    /**
+     * 转账失败状态。
+     */
+    public const TRANSFER_STATUS_FAILED = 2;
+
+    /**
+     * 获取转账状态映射。
+     *
+     * @return array<int, string>
+     */
+    public static function transferStatusMap(): array
+    {
+        return [
+            self::TRANSFER_STATUS_PENDING => '待处理',
+            self::TRANSFER_STATUS_SUCCESS => '成功',
+            self::TRANSFER_STATUS_FAILED => '失败',
+        ];
+    }
+}