xinyin025/mpay_v2_webman
1
0
Fork 0
mirror of https://gitee.com/technical-laohu/mpay_v2_webman.git synced 2026-04-25 19:44:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

更新统一使用 PHPDoc + PSR-19 标准注释

Browse Source
This commit is contained in:
技术老胡
2026-04-21 08:38:59 +08:00
parent dcd58e24ce
commit 9a16a88640
252 changed files with 9218 additions and 659 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
app/common/base/BaseController.php
View File

@@ -16,6 +16,11 @@ class BaseController
{
/**
* 返回成功响应。
*
* @param mixed $data 响应数据
* @param string $message 响应消息
* @param int $code 响应码
* @return Response 响应对象
*/
protected function success(mixed $data = null, string $message = '操作成功', int $code = 200): Response
{
@@ -28,6 +33,11 @@ class BaseController
/**
* 返回失败响应。
*
* @param string $message 响应消息
* @param int $code 响应码
* @param mixed $data 响应数据
* @return Response 响应对象
*/
protected function fail(string $message = '操作失败', int $code = 500, mixed $data = null): Response
{
@@ -40,6 +50,9 @@ class BaseController
/**
* 返回统一分页响应。
*
* @param mixed $paginator 分页器实例
* @return Response 响应对象
*/
protected function page(mixed $paginator): Response
{
@@ -63,7 +76,10 @@ class BaseController
/**
* 通过校验器类验证请求数据。
*
* @param class-string $validatorClass
* @param array $data 请求数据
* @param string $validatorClass 校验器类
* @param string|null $scene 校验场景
* @return array 校验后的数据
*/
protected function validated(array $data, string $validatorClass, ?string $scene = null): array
{
@@ -80,6 +96,9 @@ class BaseController
/**
* 获取中间件预处理后的标准化参数。
*
* @param Request $request 请求对象
* @return array 标准化参数
*/
protected function payload(Request $request): array
{
@@ -95,6 +114,11 @@ class BaseController
/**
* 读取请求属性。
*
* @param Request $request 请求对象
* @param string $key 属性名
* @param mixed $default 默认值
* @return mixed 请求上下文值
*/
protected function requestAttribute(Request $request, string $key, mixed $default = null): mixed
{
@@ -103,6 +127,9 @@ class BaseController
/**
* 获取中间件注入的当前管理员 ID。
*
* @param Request $request 请求对象
* @return int 当前管理员ID
*/
protected function currentAdminId(Request $request): int
{
@@ -111,6 +138,9 @@ class BaseController
/**
* 获取中间件注入的当前商户 ID。
*
* @param Request $request 请求对象
* @return int 当前商户ID
*/
protected function currentMerchantId(Request $request): int
{
@@ -119,6 +149,9 @@ class BaseController
/**
* 获取中间件注入的当前商户编号。
*
* @param Request $request 请求对象
* @return string 当前商户编号
*/
protected function currentMerchantNo(Request $request): string
{
@@ -126,3 +159,8 @@ class BaseController
}
}

4
app/common/base/BaseModel.php
View File

@@ -43,9 +43,13 @@ class BaseModel extends Model
*
* 避免前端收到 ISO8601（如 2026-04-02T01:50:40.000000Z）这类不直观的时间串，
* 统一改为后台常用的本地展示格式。
*
* @param DateTimeInterface $date 时间对象
* @return string 格式化后的日期时间
*/
protected function serializeDate(DateTimeInterface $date): string
{
return FormatHelper::dateTime($date);
}
}

79
app/common/base/BasePayment.php
View File

@@ -14,7 +14,7 @@ use support\Log;
/**
* 支付插件基类（建议所有插件继承）
*
* 目标：把“插件共性”集中在这里，具体渠道差异留给子类实现 `PaymentInterface`。
* 目标：把“插件共性”集中在这里，具体渠道差异留给子类补齐支付动作能力。
*
* 生命周期：
* - 服务层会在每次动作前调用 `init($channelConfig)` 注入该通道配置。
@@ -48,15 +48,19 @@ abstract class BasePayment implements PayPluginInterface
*/
protected array $channelConfig = [];
/** HTTP 请求客户端（GuzzleHttp） */
/**
* HTTP 请求客户端（GuzzleHttp）
*
* @var Client|null
*/
private ?Client $httpClient = null;
// ==================== 初始化 ====================
/**
* 初始化插件，加载通道配置并创建 HTTP 客户端
* 初始化插件，加载通道配置并创建 HTTP 客户端。
*
* @param array<string, mixed> $channelConfig 通道配置（商户号、密钥等）
* @param array $channelConfig 渠道配置
* @return void
*/
public function init(array $channelConfig): void
@@ -71,11 +75,11 @@ abstract class BasePayment implements PayPluginInterface
}
/**
* 获取通道配置项
* 获取通道配置项。
*
* @param string $key 配置键
* @param mixed $default 默认值（键不存在时返回）
* @return mixed
* @param string $key 配置键
* @param mixed $default 默认值
* @return mixed 通道配置值
*/
protected function getConfig(string $key, mixed $default = null): mixed
{
@@ -84,31 +88,51 @@ abstract class BasePayment implements PayPluginInterface
// ==================== 插件元信息 ====================
/** 获取插件代码（唯一标识） */
/**
* 获取插件代码（唯一标识）。
*
* @return string 插件代码
*/
public function getCode(): string
{
return $this->paymentInfo['code'] ?? '';
}
/** 获取插件名称 */
/**
* 获取插件名称。
*
* @return string 插件名称
*/
public function getName(): string
{
return $this->paymentInfo['name'] ?? '';
}
/** 获取作者名称 */
/**
* 获取作者名称。
*
* @return string 作者名称
*/
public function getAuthorName(): string
{
return $this->paymentInfo['author'] ?? '';
}
/** 获取作者链接 */
/**
* 获取作者链接。
*
* @return string 作者链接
*/
public function getAuthorLink(): string
{
return $this->paymentInfo['link'] ?? '';
}
/** 获取版本号 */
/**
* 获取版本号。
*
* @return string 版本号
*/
public function getVersion(): string
{
return $this->paymentInfo['version'] ?? '';
@@ -117,9 +141,9 @@ abstract class BasePayment implements PayPluginInterface
// ==================== 能力声明 ====================
/**
* 获取插件支持的支付方式列表
* 获取插件支持的支付方式列表。
*
* @return array<string> 支付方式代码数组，如 ['alipay', 'wechat']
* @return array 支持的支付方式编码
*/
public function getEnabledPayTypes(): array
{
@@ -127,9 +151,9 @@ abstract class BasePayment implements PayPluginInterface
}
/**
* 获取插件支持的转账方式列表
* 获取插件支持的转账方式列表。
*
* @return array<string> 转账方式代码数组
* @return array 支持的转账方式编码
*/
public function getEnabledTransferTypes(): array
{
@@ -137,9 +161,9 @@ abstract class BasePayment implements PayPluginInterface
}
/**
* 获取插件配置表单结构（用于后台配置界面）
* 获取插件配置表单结构（用于后台配置界面）。
*
* @return array<string, mixed> 表单字段定义数组
* @return array 配置表单结构
*/
public function getConfigSchema(): array
{
@@ -149,13 +173,13 @@ abstract class BasePayment implements PayPluginInterface
// ==================== HTTP 请求 ====================
/**
* 统一 HTTP 请求（对外调用支付渠道 API）
* 统一 HTTP 请求（对外调用支付渠道 API）。
*
* @param string $method 请求方法（GET/POST/PUT/DELETE 等）
* @param string $url 请求地址
* @param array<string, mixed> $options Guzzle 请求选项（headers、json、form_params 等）
* @return ResponseInterface
* @throws PaymentException 未调用 init() 或渠道请求失败时
* @param string $method 请求方法
* @param string $url 请求地址
* @param array $options 请求选项
* @return ResponseInterface 响应对象
* @throws PaymentException
*/
protected function request(string $method, string $url, array $options = []): ResponseInterface
{
@@ -171,3 +195,8 @@ abstract class BasePayment implements PayPluginInterface
}
}
}

61
app/common/base/BaseRepository.php
View File

@@ -15,11 +15,16 @@ abstract class BaseRepository
{
/**
* 当前仓储绑定的模型实例。
*
* @var Model
*/
protected Model $model;
/**
* 构造函数，绑定模型实例。
* 构造方法。
*
* @param Model $model 模型实例
* @return void
*/
public function __construct(Model $model)
{
@@ -28,6 +33,8 @@ abstract class BaseRepository
/**
* 获取查询构造器。
*
* @return \Illuminate\Database\Eloquent\Builder 查询构造器
*/
public function query()
{
@@ -36,6 +43,10 @@ abstract class BaseRepository
/**
* 按主键查询记录。
*
* @param int|string $id 主键
* @param array $columns 字段列表
* @return Model|null 记录或空
*/
public function find(int|string $id, array $columns = ['*']): ?Model
{
@@ -44,6 +55,9 @@ abstract class BaseRepository
/**
* 新增记录。
*
* @param array $data 新增数据
* @return Model 新增后的模型
*/
public function create(array $data): Model
{
@@ -52,6 +66,10 @@ abstract class BaseRepository
/**
* 按主键更新记录。
*
* @param int|string $id 主键
* @param array $data 更新数据
* @return bool 是否更新成功
*/
public function updateById(int|string $id, array $data): bool
{
@@ -60,6 +78,10 @@ abstract class BaseRepository
/**
* 按唯一键更新记录。
*
* @param int|string $key 键值
* @param array $data 更新数据
* @return bool 是否更新成功
*/
public function updateByKey(int|string $key, array $data): bool
{
@@ -68,6 +90,10 @@ abstract class BaseRepository
/**
* 按条件批量更新记录。
*
* @param array $where 条件
* @param array $data 更新数据
* @return int 受影响行数
*/
public function updateWhere(array $where, array $data): int
{
@@ -82,6 +108,9 @@ abstract class BaseRepository
/**
* 按主键删除记录。
*
* @param int|string $id 主键
* @return bool 是否删除成功
*/
public function deleteById(int|string $id): bool
{
@@ -90,6 +119,9 @@ abstract class BaseRepository
/**
* 按条件批量删除记录。
*
* @param array $where 条件
* @return int 受影响行数
*/
public function deleteWhere(array $where): int
{
@@ -104,6 +136,10 @@ abstract class BaseRepository
/**
* 按条件获取首条记录。
*
* @param array $where 条件
* @param array $columns 字段列表
* @return Model|null 记录或空
*/
public function firstBy(array $where = [], array $columns = ['*']): ?Model
{
@@ -118,6 +154,10 @@ abstract class BaseRepository
/**
* 先查后更，不存在则创建。
*
* @param array $where 条件
* @param array $data 更新数据
* @return Model 记录
*/
public function updateOrCreate(array $where, array $data = []): Model
{
@@ -156,6 +196,9 @@ abstract class BaseRepository
/**
* 按条件统计数量。
*
* @param array $where 条件
* @return int 数量
*/
public function countBy(array $where = []): int
{
@@ -170,6 +213,9 @@ abstract class BaseRepository
/**
* 判断条件下是否存在记录。
*
* @param array $where 条件
* @return bool 是否存在
*/
public function existsBy(array $where = []): bool
{
@@ -185,7 +231,11 @@ abstract class BaseRepository
/**
* 分页查询。
*
* @param array $where 条件数组，空值会被忽略
* @param array $where 条件
* @param int $page 页码
* @param int $pageSize 每页条数
* @param array $columns 字段列表
* @return \Illuminate\Contracts\Pagination\LengthAwarePaginator 分页结果
*/
public function paginate(array $where = [], int $page = 1, int $pageSize = 10, array $columns = ['*'])
{
@@ -198,3 +248,8 @@ abstract class BaseRepository
return $query->paginate($pageSize, $columns, 'page', $page);
}
}

53
app/common/base/BaseService.php
View File

@@ -18,6 +18,9 @@ class BaseService
*
* 适用于 biz_no / pay_no / refund_no / settle_no / notify_no / ledger_no 等场景。
* 默认使用时间前缀 + 随机数，保证可读性和基本唯一性。
*
* @param string $prefix 单号前缀
* @return string 单号
*/
protected function generateNo(string $prefix = ''): string
{
@@ -31,6 +34,8 @@ class BaseService
* 获取当前时间字符串。
*
* 统一返回 `Y-m-d H:i:s` 格式，便于数据库写入和日志输出。
*
* @return string 时间字符串
*/
protected function now(): string
{
@@ -39,6 +44,9 @@ class BaseService
/**
* 金额格式化，单位为元。
*
* @param int $amount 金额（分）
* @return string 格式化后的金额
*/
protected function formatAmount(int $amount): string
{
@@ -47,6 +55,9 @@ class BaseService
/**
* 金额格式化，0 时显示不限。
*
* @param int $amount 金额（分）
* @return string 格式化后的金额
*/
protected function formatAmountOrUnlimited(int $amount): string
{
@@ -55,6 +66,9 @@ class BaseService
/**
* 次数格式化，0 时显示不限。
*
* @param int $count 次数
* @return string 格式化后的次数
*/
protected function formatCountOrUnlimited(int $count): string
{
@@ -63,6 +77,9 @@ class BaseService
/**
* 费率格式化，单位为百分点。
*
* @param int $basisPoints 基点值
* @return string 格式化后的费率
*/
protected function formatRate(int $basisPoints): string
{
@@ -71,6 +88,9 @@ class BaseService
/**
* 延迟格式化。
*
* @param int $latencyMs 延迟毫秒数
* @return string 格式化后的延迟
*/
protected function formatLatency(int $latencyMs): string
{
@@ -79,6 +99,10 @@ class BaseService
/**
* 日期格式化。
*
* @param mixed $value 日期时间值
* @param string $emptyText 为空时显示文案
* @return string 格式化后的日期
*/
protected function formatDate(mixed $value, string $emptyText = ''): string
{
@@ -87,6 +111,10 @@ class BaseService
/**
* 日期时间格式化。
*
* @param mixed $value 日期时间值
* @param string $emptyText 为空时显示文案
* @return string 格式化后的日期时间
*/
protected function formatDateTime(mixed $value, string $emptyText = ''): string
{
@@ -95,6 +123,10 @@ class BaseService
/**
* JSON 文本格式化。
*
* @param mixed $value JSON 值
* @param string $emptyText 为空时显示文案
* @return string 格式化后的 JSON 文本
*/
protected function formatJson(mixed $value, string $emptyText = ''): string
{
@@ -103,6 +135,11 @@ class BaseService
/**
* 映射表文本转换。
*
* @param int $value 待映射值
* @param array $map 映射表
* @param string $default 默认值
* @return string 映射后的文本
*/
protected function textFromMap(int $value, array $map, string $default = '未知'): string
{
@@ -111,6 +148,10 @@ class BaseService
/**
* 接口凭证明文脱敏。
*
* @param string $credentialValue 凭证原文
* @param bool $maskShortValue 是否对短值也进行脱敏
* @return string 脱敏后的文本
*/
protected function maskCredentialValue(string $credentialValue, bool $maskShortValue = true): string
{
@@ -119,6 +160,9 @@ class BaseService
/**
* 将模型或对象归一化成数组。
*
* @param mixed $value 模型实例、数组或可序列化对象
* @return array|null 归一化结果
*/
protected function normalizeModel(mixed $value): ?array
{
@@ -130,8 +174,8 @@ class BaseService
*
* 适合单次数据库事务，不包含自动重试逻辑。
*
* @param callable $callback 事务体
* @return mixed
* @param callable $callback 回调
* @return mixed 回调原始返回值
*/
protected function transaction(callable $callback)
{
@@ -144,6 +188,11 @@ class BaseService
* 支持重试的事务封装。
*
* 适合余额冻结、扣减、状态推进和幂等写入等容易发生锁冲突的场景。
*
* @param callable $callback 回调
* @param int $attempts 重试次数
* @param int $sleepMs 重试间隔毫秒数
* @return mixed 回调原始返回值
*/
protected function transactionRetry(callable $callback, int $attempts = 3, int $sleepMs = 50)
{