核心特性详解

// JWT Payload 结构（HS256 签名）
{
  "user_id": 1,
  "login_type": "admin",        // admin 或 wechat
  "type": "access",             // access 或 refresh
  "key_ver": "v1",              // 密钥版本，用于滚动升级
  "ip": "192.168.1.1",          // 签发 IP
  "exp": 1735689600,            // 过期时间戳
  "iat": 1735675200             // 签发时间
}

// 过期时间策略
// wechat access: 7200s (2h)   refresh: 604800s (7d)
// admin   access: 14400s (4h) refresh: 1209600s (14d)

// Redis 缓存键结构
{prefix}token:{userId}:{deviceId}          // 访问令牌
{prefix}refresh_token:{userId}:{deviceId}  // 刷新令牌
{prefix}device:{userId}:{tokenId}          // 设备绑定
{prefix}user:{userId}                       // 用户信息（JSON）

// 前缀示例
admin:token:1:abc123      // 管理后台用户 1 的 token
wx:token:3:def456         // 小程序用户 3 的 token
user:perm_codes:1         // 权限码缓存（无前缀，1 小时过期）

// 请求头示例
GET /user/my-info HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
device-id: 550e8400-e29b-41d4-a716-446655440000

// Redis 设备键
admin:device:1:token_abc123  →  "550e8400-e29b-41d4-a716-446655440000"

// 校验流程
// 1. AuthMiddleware 提取 Authorization Bearer token
// 2. JwtService::verifyToken 解码得到 user_id + tokenId
// 3. 从 device-id 头取值，与 Redis {prefix}device:{userId}:{tokenId} 比对
// 4. 不匹配返回 4003 DEVICE_VERIFY_FAILED

// 小程序 request.js 核心逻辑
let isRefreshing = false
const requestQueue = []

function handle401Error(originalRequest) {
  if (isRefreshing) {
    // 已在刷新中，入队等待
    return new Promise((resolve, reject) => {
      requestQueue.push({ originalRequest, resolve, reject })
    })
  }
  if (originalRequest._retry) {
    // 已重试过仍 401，跳登录
    return redirectToLogin()
  }
  isRefreshing = true
  return refreshTokenApi({ refresh_token: getRefreshToken() })
    .then(res => {
      // 写入新 token
      saveToken(res.data)
      // flush 队列，每个请求标 _retry=true 重发
      requestQueue.forEach(({ originalRequest, resolve, reject }) => {
        originalRequest._retry = true
        request(originalRequest).then(resolve).catch(reject)
      })
      requestQueue.length = 0
    })
    .catch(() => {
      // 刷新失败，reject 队列
      requestQueue.forEach(({ reject }) => reject(new Error('登录已过期')))
      requestQueue.length = 0
      redirectToLogin()
    })
    .finally(() => { isRefreshing = false })
}

// 登录返回的 userInfo 结构（节选）
{
  "user_id": 1,
  "real_name": "张三",
  "active_department_id": 1,
  "active_role_id": 2,
  "active_role_code": "system_admin",
  "active_permission_codes": [
    "system:user:view",
    "system:user:create",
    "system:user:update",
    "system:department:view",
    "feedback:reply"
  ],
  "departments": [
    {
      "department_id": 1,
      "department_name": "技术部",
      "is_default": 1,
      "roles": [{ "role_id": 2, "role_name": "系统管理员", "is_default": 1 }]
    }
  ]
}

// 管理后台按钮级权限指令
<el-button v-permission="'system:user:create'">新增用户</el-button>
<el-button v-permission="['system:user:update', 'system:user:delete']">操作</el-button>

-- 三向关联表：用户在不同部门有不同角色
SELECT u.real_name, d.name AS dept, r.name AS role, udr.is_default
FROM system_user_department_role udr
JOIN system_user u ON udr.user_id = u.id
JOIN system_department d ON udr.department_id = d.id
JOIN system_role r ON udr.role_id = r.id
WHERE udr.user_id = 1;

-- 直接授权表：绕过角色直接授权
SELECT u.real_name, p.code, p.name
FROM system_user_permission up
JOIN system_user u ON up.user_id = u.id
JOIN system_permission p ON up.permission_id = p.id
WHERE p.can_direct_assign = 1;

-- 直接授权 API
POST /admin/system/addDirectPermission    { user_id, permission_id }
POST /admin/system/removeDirectPermission { id }

// 登录请求（统一入口 POST /public/login）
{
  "login_type": "wechat_one_click",
  "code": "wx_login_code_xxx",
  "phone_code": "wx_phone_code_yyy"
}

// 登录成功返回
{
  "code": 1,
  "msg": "登录成功",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_in": 7200,
    "userInfo": {
      "user_id": 3,
      "real_name": "张三",
      "active_permission_codes": ["feedback:view", "feedback:reply"]
    },
    "need_complete_profile": false
  },
  "timestamp": 1735689600
}

// AI Key 加密/解密（AiConfigService.php）
public function encryptApiKey($apiKey) {
    $key = hash('sha256', env('AI_CONFIG_ENCRYPT_KEY', 'default'), true);
    $iv = random_bytes(16);
    $encrypted = openssl_encrypt($apiKey, 'AES-256-CBC', $key, OPENSSL_RAW_DATA, $iv);
    return base64_encode($iv . $encrypted);
}

// SSRF 防护
public function validateApiUrl($url) {
    $host = parse_url($url, PHP_URL_HOST);
    $ip = gethostbyname($host);
    // 过滤私有/保留 IP 段
    return filter_var($ip, FILTER_VALIDATE_IP,
        FILTER_FLAG_NO_PRIV_RANGE | FILTER_FLAG_NO_RES_RANGE);
}

// 上传三重校验
// 1. 扩展名白名单：jpg/jpeg/png/gif/webp
// 2. MIME 类型校验：image/jpeg、image/png 等
// 3. 魔数校验：FF D8 FF (JPEG)、89 50 4E 47 (PNG)
// 4. GD 重处理：imagecreatefromjpeg + imagecopy 剥离恶意代码

// 成功响应
{
  "code": 1,
  "msg": "操作成功",
  "data": { "id": 1, "name": "张三" },
  "timestamp": 1735689600
}

// 失败响应
{
  "code": 0,
  "msg": "参数缺失",
  "data": null,
  "timestamp": 1735689600
}

// 业务码常量表（部分）
SUCCESS             = 1    // 成功
ERROR               = 0    // 失败
VALIDATE_FAILED     = 7    // 验证失败
USER_DISABLED       = 1000 // 用户已禁用
LOGIN_FAILED        = 4000 // 登录失败
NO_TOKEN            = 4001 // 未提供 token
VALIDATE_TOKEN      = 4002 // token 验证失败
DEVICE_VERIFY_FAILED= 4003 // 设备验证失败
REFRESH_TOKEN_INVALID=4004 // refresh token 无效