1. 维护代码健壮

2. 更新项目结构文档

app/service/system/access/AdminAuthService.php

@@ -43,7 +43,7 @@ class AdminAuthService extends BaseService
      */
     public function authenticateToken(string $token, string $ip = '', string $userAgent = ''): ?AdminUser
     {
-        $result = $this->jwtTokenManager->verify('admin', $token, $ip, $userAgent);
+        $result = $this->jwtTokenManager->verify(AuthConstant::GUARD_ADMIN, $token, $ip, $userAgent);
         if ($result === null) {
             return null;
         }
@@ -98,7 +98,7 @@ class AdminAuthService extends BaseService
      */
     public function revokeToken(string $token): bool
     {
-        return $this->jwtTokenManager->revoke('admin', $token);
+        return $this->jwtTokenManager->revoke(AuthConstant::GUARD_ADMIN, $token);
     }
 
     /**
@@ -119,7 +119,7 @@ class AdminAuthService extends BaseService
             throw new ValidationException('管理员不存在');
         }
 
-        $issued = $this->jwtTokenManager->issue('admin', [
+        $issued = $this->jwtTokenManager->issue(AuthConstant::GUARD_ADMIN, [
             'sub' => (string) $adminId,
             'admin_id' => $adminId,
             'username' => (string) $admin->username,
@@ -143,4 +143,3 @@ class AdminAuthService extends BaseService
 
 
 
-

app/service/system/config/SystemConfigDefinitionService.php

@@ -3,7 +3,7 @@
 namespace app\service\system\config;
 
 use app\common\base\BaseService;
-use RuntimeException;
+use app\exception\ConflictException;
 
 /**
  * 系统配置定义解析服务。
@@ -32,7 +32,7 @@ class SystemConfigDefinitionService extends BaseService
      * 获取全部系统配置标签页。
      *
      * @return array 标签页列表
-     * @throws RuntimeException
+     * @throws ConflictException
      */
     public function tabs(): array
     {
@@ -57,7 +57,9 @@ class SystemConfigDefinitionService extends BaseService
 
             $key = $tab['key'];
             if (isset($seenKeys[$key])) {
-                throw new RuntimeException(sprintf('系统配置标签 key 重复：%s', $key));
+                throw new ConflictException(sprintf('系统配置标签 key 重复：%s', $key), [
+                    'key' => $key,
+                ]);
             }
 
             foreach ($tab['rules'] as $rule) {
@@ -67,7 +69,9 @@ class SystemConfigDefinitionService extends BaseService
                 }
 
                 if (isset($seenFields[$field])) {
-                    throw new RuntimeException(sprintf('系统配置项 key 重复：%s', $field));
+                    throw new ConflictException(sprintf('系统配置项 key 重复：%s', $field), [
+                        'field' => $field,
+                    ]);
                 }
 
                 $seenFields[$field] = true;
@@ -300,4 +304,3 @@ class SystemConfigDefinitionService extends BaseService
         return str_starts_with($field, self::VIRTUAL_FIELD_PREFIX);
     }
 }
-

app/service/system/config/SystemConfigPageService.php

@@ -3,6 +3,7 @@
 namespace app\service\system\config;
 
 use app\common\base\BaseService;
+use app\common\constant\EventConstant;
 use app\exception\ValidationException;
 use app\repository\system\config\SystemConfigRepository;
 use Webman\Event\Event;
@@ -147,7 +148,7 @@ class SystemConfigPageService extends BaseService
             }
         });
 
-        Event::emit('system.config.changed', [
+        Event::dispatch(EventConstant::SYSTEM_CONFIG_CHANGED, [
             'group_code' => (string) $tab['key'],
         ]);
 
@@ -213,5 +214,3 @@ class SystemConfigPageService extends BaseService
         return (string) $value;
     }
 }
-
-

app/service/system/user/AdminUserService.php

@@ -5,6 +5,7 @@ namespace app\service\system\user;
 use app\common\base\BaseService;
 use app\common\constant\CommonConstant;
 use app\exception\ResourceNotFoundException;
+use app\exception\ValidationException;
 use app\model\admin\AdminUser;
 use app\repository\system\user\AdminUserRepository;
 
@@ -196,6 +197,40 @@ class AdminUserService extends BaseService
         ];
     }
 
+    /**
+     * 修改当前管理员登录密码。
+     *
+     * @param int $adminId 管理员ID
+     * @param array $data 密码数据
+     * @return array<string, mixed> 修改结果
+     * @throws ResourceNotFoundException
+     * @throws ValidationException
+     */
+    public function changePassword(int $adminId, array $data): array
+    {
+        $admin = $this->adminUserRepository->find($adminId);
+        if (!$admin) {
+            throw new ResourceNotFoundException('管理员不存在', ['admin_id' => $adminId]);
+        }
+
+        $currentPassword = trim((string) ($data['current_password'] ?? ''));
+        $newPassword = trim((string) ($data['password'] ?? ''));
+
+        if (!password_verify($currentPassword, (string) $admin->password_hash)) {
+            throw new ValidationException('旧密码不正确');
+        }
+
+        if ($currentPassword === $newPassword) {
+            throw new ValidationException('新密码不能与旧密码相同');
+        }
+
+        $this->adminUserRepository->updateById($adminId, [
+            'password_hash' => password_hash($newPassword, PASSWORD_DEFAULT),
+        ]);
+
+        return ['updated' => true];
+    }
+
     /**
      * 统一整理写入字段，并处理密码哈希。
      *
@@ -226,6 +261,3 @@ class AdminUserService extends BaseService
     }
 
 }
-
-
-