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

35
app/service/system/access/AdminAuthService.php
View File

@@ -14,11 +14,18 @@ use app\repository\system\user\AdminUserRepository;
* 管理员认证服务。
*
* 负责管理员账号校验、JWT 签发、登录态校验和主动注销。
*
* @property AdminUserRepository $adminUserRepository 管理用户仓库
* @property JwtTokenManager $jwtTokenManager jwtToken管理器
*/
class AdminAuthService extends BaseService
{
/**
* 构造函数，注入对应依赖。
* 构造方法。
*
* @param AdminUserRepository $adminUserRepository 管理用户仓库
* @param JwtTokenManager $jwtTokenManager jwtToken管理器
* @return void
*/
public function __construct(
protected AdminUserRepository $adminUserRepository,
@@ -28,6 +35,11 @@ class AdminAuthService extends BaseService
/**
* 校验中间件传入的管理员登录 token。
*
* @param string $token 登录令牌
* @param string $ip 请求 IP
* @param string $userAgent 用户代理
* @return AdminUser|null 管理员模型
*/
public function authenticateToken(string $token, string $ip = '', string $userAgent = ''): ?AdminUser
{
@@ -52,6 +64,13 @@ class AdminAuthService extends BaseService
/**
* 校验管理员账号密码并签发 JWT。
*
* @param string $username 管理员账号
* @param string $password 密码
* @param string $ip 请求 IP
* @param string $userAgent 用户代理
* @return array{token: string, expires_in: int, admin: AdminUser} 登录结果
* @throws ValidationException
*/
public function authenticateCredentials(string $username, string $password, string $ip = '', string $userAgent = ''): array
{
@@ -73,6 +92,9 @@ class AdminAuthService extends BaseService
/**
* 撤销当前管理员登录 token。
*
* @param string $token 登录令牌
* @return bool 是否撤销成功
*/
public function revokeToken(string $token): bool
{
@@ -81,6 +103,13 @@ class AdminAuthService extends BaseService
/**
* 签发新的管理员登录 token。
*
* @param int $adminId 管理员ID
* @param int $ttlSeconds 过期秒数
* @param string $ip 请求 IP
* @param string $userAgent 用户代理
* @return array{token: string, expires_in: int, admin: AdminUser} 登录结果
* @throws ValidationException
*/
public function issueToken(int $adminId, int $ttlSeconds = 86400, string $ip = '', string $userAgent = ''): array
{
@@ -111,3 +140,7 @@ class AdminAuthService extends BaseService
];
}
}

63
app/service/system/config/SystemConfigDefinitionService.php
View File

@@ -5,20 +5,35 @@ namespace app\service\system\config;
use app\common\base\BaseService;
use RuntimeException;
/**
* 系统配置定义解析服务。
*
* 负责读取 `system_config` 配置并标准化为标签页、规则和默认值结构。
*/
class SystemConfigDefinitionService extends BaseService
{
protected const VIRTUAL_FIELD_PREFIX = '__';
/**
* 已解析的标签页缓存。
*
* @var array|null
*/
protected ?array $tabCache = null;
/**
* 标签页键到定义的缓存。
*
* @var array|null
*/
protected ?array $tabMapCache = null;
/**
* 获取全部系统配置标签页。
*
* @return array 标签页列表
* @throws RuntimeException
*/
public function tabs(): array
{
if ($this->tabCache !== null) {
@@ -82,6 +97,12 @@ class SystemConfigDefinitionService extends BaseService
return $this->tabCache;
}
/**
* 根据分组代码获取标签页定义。
*
* @param string $groupCode 分组代码
* @return array|null 标签页定义
*/
public function tab(string $groupCode): ?array
{
$groupCode = strtolower(trim($groupCode));
@@ -94,6 +115,13 @@ class SystemConfigDefinitionService extends BaseService
return $this->tabMapCache[$groupCode] ?? null;
}
/**
* 使用当前值回填标签页规则。
*
* @param array $tab 标签页定义
* @param array $values 当前值映射
* @return array 回填后的规则列表
*/
public function hydrateRules(array $tab, array $values): array
{
$rules = [];
@@ -116,6 +144,13 @@ class SystemConfigDefinitionService extends BaseService
return $rules;
}
/**
* 从标签页规则中提取表单提交数据。
*
* @param array $tab 标签页定义
* @param array $values 当前值映射
* @return array 表单数据
*/
public function extractFormData(array $tab, array $values): array
{
$data = [];
@@ -135,6 +170,12 @@ class SystemConfigDefinitionService extends BaseService
return $data;
}
/**
* 生成必填字段校验消息。
*
* @param array $tab 标签页定义
* @return array 字段到错误消息的映射
*/
public function requiredFieldMessages(array $tab): array
{
$messages = [];
@@ -163,6 +204,13 @@ class SystemConfigDefinitionService extends BaseService
return $messages;
}
/**
* 标准化单个标签页定义。
*
* @param string $groupCode 分组代码
* @param array $definition 原始定义
* @return array|null 标准化后的标签页
*/
private function normalizeTab(string $groupCode, array $definition): ?array
{
$key = strtolower(trim((string) ($definition['key'] ?? $groupCode)));
@@ -191,7 +239,13 @@ class SystemConfigDefinitionService extends BaseService
];
}
private function normalizeRule(mixed $rule): ?array
/**
* 标准化单个配置项定义。
*
* @param array|object|null $rule 原始规则
* @return array|null 标准化后的规则
*/
private function normalizeRule(array|object|null $rule): ?array
{
if (!is_array($rule)) {
return null;
@@ -235,8 +289,15 @@ class SystemConfigDefinitionService extends BaseService
return $normalized;
}
/**
* 判断是否为虚拟字段。
*
* @param string $field 字段名
* @return bool 是否为虚拟字段
*/
private function isVirtualField(string $field): bool
{
return str_starts_with($field, self::VIRTUAL_FIELD_PREFIX);
}
}

63
app/service/system/config/SystemConfigPageService.php
View File

@@ -7,14 +7,34 @@ use app\exception\ValidationException;
use app\repository\system\config\SystemConfigRepository;
use Webman\Event\Event;
/**
* 系统配置页面服务。
*
* 负责把配置定义和数据库中的配置值组装成页面所需的数据结构。
* 典型流程是先读取定义，再回填当前值，最后生成表单页数据。
*
* @property SystemConfigRepository $systemConfigRepository 系统配置仓库
* @property SystemConfigDefinitionService $systemConfigDefinitionService 系统配置定义解析服务
*/
class SystemConfigPageService extends BaseService
{
/**
* 构造方法。
*
* @param SystemConfigRepository $systemConfigRepository 系统配置仓库
* @param SystemConfigDefinitionService $systemConfigDefinitionService 系统配置定义解析服务
*/
public function __construct(
protected SystemConfigRepository $systemConfigRepository,
protected SystemConfigDefinitionService $systemConfigDefinitionService
) {
}
/**
* 获取系统配置页面标签页列表。
*
* @return array<string, mixed> 页面所需标签页数据
*/
public function tabs(): array
{
$tabs = [];
@@ -41,6 +61,13 @@ class SystemConfigPageService extends BaseService
];
}
/**
* 查询系统配置页面详情。
*
* @param string $groupCode 分组代码
* @return array<string, mixed> 页面详情
* @throws ValidationException
*/
public function detail(string $groupCode): array
{
$tab = $this->systemConfigDefinitionService->tab($groupCode);
@@ -80,6 +107,14 @@ class SystemConfigPageService extends BaseService
return $tab;
}
/**
* 保存系统配置页面。
*
* @param string $groupCode 分组代码
* @param array<string, mixed> $values 提交值
* @return array<string, mixed> 保存后的页面详情
* @throws ValidationException
*/
public function save(string $groupCode, array $values): array
{
$tab = $this->systemConfigDefinitionService->tab($groupCode);
@@ -119,6 +154,14 @@ class SystemConfigPageService extends BaseService
return $this->detail((string) $tab['key']);
}
/**
* 校验必填配置项。
*
* @param array<string, mixed> $tab 标签页定义
* @param array<string, mixed> $values 配置值
* @return void
* @throws ValidationException
*/
protected function validateRequiredValues(array $tab, array $values): void
{
$messages = $this->systemConfigDefinitionService->requiredFieldMessages($tab);
@@ -131,7 +174,13 @@ class SystemConfigPageService extends BaseService
}
}
protected function isEmptyValue(mixed $value): bool
/**
* 判断配置值是否为空。
*
* @param array|object|bool|float|int|string|null $value 配置值
* @return bool 是否为空
*/
protected function isEmptyValue(array|object|bool|float|int|string|null $value): bool
{
if (is_array($value)) {
return $value === [];
@@ -144,7 +193,14 @@ class SystemConfigPageService extends BaseService
return $value === null || $value === '';
}
protected function stringifyValue(mixed $value): string
/**
* 将配置值转换为可保存字符串。
*
* @param array|object|bool|float|int|string|null $value 配置值
* @return string 可保存字符串
* @throws ValidationException
*/
protected function stringifyValue(array|object|bool|float|int|string|null $value): string
{
if (is_bool($value)) {
return $value ? '1' : '0';
@@ -156,5 +212,6 @@ class SystemConfigPageService extends BaseService
return (string) $value;
}
}

54
app/service/system/config/SystemConfigRuntimeService.php
View File

@@ -7,16 +7,37 @@ use app\repository\system\config\SystemConfigRepository;
use support\Cache;
use Throwable;
/**
* 系统配置运行时服务。
*
* 负责读取、缓存和刷新当前进程可直接使用的系统配置值。
* 读取结果以配置键到字符串值的映射形式提供给业务层。
*
* @property SystemConfigRepository $systemConfigRepository 系统配置仓库
* @property SystemConfigDefinitionService $systemConfigDefinitionService 系统配置定义解析服务
*/
class SystemConfigRuntimeService extends BaseService
{
protected const CACHE_KEY = 'system_config:all';
/**
* 构造方法。
*
* @param SystemConfigRepository $systemConfigRepository 系统配置仓库
* @param SystemConfigDefinitionService $systemConfigDefinitionService 系统配置定义解析服务
*/
public function __construct(
protected SystemConfigRepository $systemConfigRepository,
protected SystemConfigDefinitionService $systemConfigDefinitionService
) {
}
/**
* 获取全部系统配置运行时值。
*
* @param bool $refresh 是否强制刷新
* @return array<string, string> 系统配置值映射
*/
public function all(bool $refresh = false): array
{
if (!$refresh) {
@@ -29,7 +50,15 @@ class SystemConfigRuntimeService extends BaseService
return $this->refresh();
}
public function get(string $configKey, mixed $default = '', bool $refresh = false): string
/**
* 根据配置键获取运行时值。
*
* @param string $configKey 配置键
* @param string|int|float|bool|null $default 默认值
* @param bool $refresh 是否强制刷新
* @return string 配置值字符串
*/
public function get(string $configKey, string|int|float|bool|null $default = '', bool $refresh = false): string
{
$configKey = strtolower(trim($configKey));
if ($configKey === '') {
@@ -41,6 +70,11 @@ class SystemConfigRuntimeService extends BaseService
return (string) ($values[$configKey] ?? $default);
}
/**
* 刷新系统配置运行时缓存。
*
* @return array<string, string> 最新配置值映射
*/
public function refresh(): array
{
$values = $this->buildValueMap();
@@ -49,6 +83,11 @@ class SystemConfigRuntimeService extends BaseService
return $values;
}
/**
* 构建配置值映射。
*
* @return array<string, string> 配置值映射
*/
protected function buildValueMap(): array
{
$values = [];
@@ -102,6 +141,11 @@ class SystemConfigRuntimeService extends BaseService
return $values;
}
/**
* 读取运行时缓存。
*
* @return array<string, string>|null 缓存值
*/
protected function readCache(): ?array
{
try {
@@ -113,6 +157,12 @@ class SystemConfigRuntimeService extends BaseService
return is_array($raw) ? $raw : null;
}
/**
* 写入运行时缓存。
*
* @param array<string, string> $values 配置值映射
* @return void
*/
protected function writeCache(array $values): void
{
try {
@@ -122,3 +172,5 @@ class SystemConfigRuntimeService extends BaseService
}
}
}

37
app/service/system/user/AdminUserService.php
View File

@@ -12,11 +12,16 @@ use app\repository\system\user\AdminUserRepository;
* 管理员用户管理服务。
*
* 负责管理员账号的列表查询、新增、修改和删除，以及密码字段的统一处理。
*
* @property AdminUserRepository $adminUserRepository 管理用户仓库
*/
class AdminUserService extends BaseService
{
/**
* 构造函数，注入管理员用户仓库。
* 构造方法。
*
* @param AdminUserRepository $adminUserRepository 管理用户仓库
* @return void
*/
public function __construct(
protected AdminUserRepository $adminUserRepository
@@ -25,6 +30,11 @@ class AdminUserService extends BaseService
/**
* 分页查询管理员用户。
*
* @param array $filters 筛选条件
* @param int $page 页码
* @param int $pageSize 每页条数
* @return \Illuminate\Contracts\Pagination\LengthAwarePaginator 分页结果
*/
public function paginate(array $filters = [], int $page = 1, int $pageSize = 10)
{
@@ -80,6 +90,9 @@ class AdminUserService extends BaseService
/**
* 根据 ID 查询管理员用户。
*
* @param int $id 管理员用户ID
* @return AdminUser|null 管理员模型
*/
public function findById(int $id): ?AdminUser
{
@@ -88,6 +101,9 @@ class AdminUserService extends BaseService
/**
* 新增管理员用户。
*
* @param array $data 写入数据
* @return AdminUser 新增后的管理员模型
*/
public function create(array $data): AdminUser
{
@@ -96,6 +112,10 @@ class AdminUserService extends BaseService
/**
* 修改管理员用户。
*
* @param int $id 管理员用户ID
* @param array $data 写入数据
* @return AdminUser|null 更新后的管理员模型
*/
public function update(int $id, array $data): ?AdminUser
{
@@ -113,6 +133,9 @@ class AdminUserService extends BaseService
/**
* 删除管理员用户。
*
* @param int $id 管理员用户ID
* @return bool 是否删除成功
*/
public function delete(int $id): bool
{
@@ -121,6 +144,11 @@ class AdminUserService extends BaseService
/**
* 当前管理员资料。
*
* @param int $adminId 管理员ID
* @param string $adminUsername 管理员账号
* @return array<string, mixed> 当前用户资料
* @throws ResourceNotFoundException
*/
public function profile(int $adminId, string $adminUsername = ''): array
{
@@ -170,6 +198,10 @@ class AdminUserService extends BaseService
/**
* 统一整理写入字段，并处理密码哈希。
*
* @param array $data 写入数据
* @param bool $isUpdate 是否更新
* @return array<string, mixed> 标准化后的数据
*/
private function normalizePayload(array $data, bool $isUpdate): array
{
@@ -194,3 +226,6 @@ class AdminUserService extends BaseService
}
}