xinyin025/mpay_v2_webman
1
0
Fork 0
mirror of https://gitee.com/technical-laohu/mpay_v2_webman.git synced 2026-04-26 20:14:26 +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

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
}
}
}