人机验证体系升级方案：滑块样式修复 + 多验证方式 + 后台可配置

版本：v1.1.0 ｜ 适用：统一身份认证中心（UIC）前后台登录、找回密码 相关代码：app/Model/CaptchaModel.php、public/assets/captcha.js、app/View/partials/captcha_card.php、public/assets/app.css、app/View/admin/settings.php

一、背景与问题定位

原滑块验证码（后台登录页红框区域）存在以下问题：

二、总体设计

2.1 验证方式矩阵

设计要点：click/icon 的图片由服务端直接生成 SVG 文本（data:image/svg+xml;base64,...），文字用系统字体栈、图标用内联路径，不依赖服务器 CJK 字体，规避了"服务器缺中文字体导致点选码变成方框"的经典兼容性问题；passive 不下发任何图片。

2.2 架构（前后端分离）

登录/找回密码视图 (portal/login, admin/login, portal/findpwd)
   └─ include partials/captcha_card.php      # 全模式 DOM 骨架 + <script captcha.js>
        └─ UicCaptcha.init({req, api, show, style, fallback})
             ├─ GET/POST m=captcha&a=issue  → CaptchaModel::issue(style)
             │      ├─ slide/digits/mixed → GD 渲染
             │      ├─ click/icon         → SVG 拼装
             │      └─ passive            → 仅签发票据
             ├─ (passive) m=captcha&a=verify（预检，不消耗）→ passiveScore()
             │      └─ 低分 → 自动 load(captcha_fallback) 无感回退
             └─ 表单提交 captcha_token + captcha_answer
                    └─ 服务端 requireCaptchaIfEnabled / admin_login
                         → CaptchaModel::verify(token, answer, consume=true)

• 后端只认 token + answer 两个字段，与样式完全解耦：新增验证方式不需要改任何登录逻辑。
• 前端统一为 UicCaptcha 模块，六个样式共用一套加载/刷新/取值 API（token / answer() / ready() / reset()）。

2.3 无感验证（passive）流程

1. 签发：issue('passive') 只落库 token，不下发图片。
2. 采集：前端监听 mousemove / touchmove 1.6s，统计耗时 t、移动次数 mv、方向熵 ent（8 个角度桶的覆盖率）、是否触摸设备。
3. 预检：行为数据 POST captcha&a=verify（不消耗 token），服务端按阈值评分：

• t < 600ms → 拒绝（机器过快）
• mv < 5（触摸设备 < 3）→ 拒绝
• ent < 25 → 拒绝（轨迹过于机械）

1. 回退：评分未通过 → 前端无感切换到 captcha_fallback 指定的交互式验证码，用户无感知续操作。
2. 终检：登录提交时服务端再次评分并消耗 token（防重放）。

三、后端修改清单

verify() 答案格式约定

安全不变量：token 单次有效、5 分钟过期、最多 5 次尝试；字符/点选答案均以 sha256(answer+salt) 存储，hashequals 常量时间比对；slide 答案强制 ctypedigit；passive 评分阈值集中在模型常量（PASSIVEMINMS/MOVE/ENT），便于按业务调整。

四、前端修改清单

三个登录页的接入代码（模式完全一致）

<?php
$showCap     = Config::get('login_captcha') ? 1 : 0;          // 后台页用 admin_login_captcha
$capStyle    = (string)Config::get('captcha_style', 'slide');
$capFallback = (string)Config::get('captcha_fallback', 'slide');
$capApi      = $base . '/api/index.php';
?>
<div class="field <?= $showCap ? '' : 'hide' ?>" id="capField">
  <?php $capShow = $showCap ? 1 : 0; include __DIR__ . '/../partials/captcha_card.php'; ?>
</div>
<script>
UicCaptcha.init({
  req: function(){ return App.req.apply(App, arguments); },   // 布局末尾才定义 App，必须惰性求值
  api: '<?= e($capApi) ?>',                                   // 无感预检直连，避免通用 req 弹错误 toast
  show: <?= $showCap ? 'true' : 'false' ?>,
  style: '<?= e($capStyle) ?>',
  fallback: '<?= e($capFallback) ?>'
});
// 提交时：
//   if (!UicCaptcha.ready()) { toast('请完成安全验证'); return; }
//   d.captcha_token = UicCaptcha.token; d.captcha_answer = UicCaptcha.answer();
// 失败后：UicCaptcha.reset();
</script>

后台登录页额外传 active: function(){ return step === 1; }，进入 TOTP 二步验证时自动停用验证码模块。

五、滑块样式修复明细（对应截图问题）

1. thumb 居中改为 transform 方案（核心修复）

• 旧：left: calc(pct% - 18px)，JS 硬编码半宽，断点改宽度后必偏。
• 新：CSS left:0; transform:translate(-50%,-50%)，JS 只写 left: pct%；宽度 36px→40px 自适应，hover/active 缩放全部走 transform，不再冲突。

1. 舞台占位防跳动：.verify-slide-stage{aspect-ratio:300/150}，图片未加载时卡片高度已确定，消除 CLS；不支持 aspect-ratio 的老浏览器由图片自身高度自然兜底。
2. 触摸拖动：滑块容器保留 touch-action:pan-y（横向手势归滑块、纵向仍可滚页）；点选瓦片 touch-action:manipulation + -webkit-tap-highlight-color:transparent，消除移动端点击蓝框与 300ms 延迟感。
3. 拼图块定位：按 left/top 百分比 + drop-shadow，随背景图缩放自动对齐；缺口纵向坐标由服务端 hole_y 下发，前端不再"猜"垂直位置。
4. 加载态：四类模式共用一个 overlay 调度函数，切模/换图/刷新不再出现"两个 loading 叠显示"。
5. 暗色模式与降级：新增点选/无感组件的 prefers-color-scheme: dark 覆盖；prefers-reduced-motion 下关闭shake/淡入动画。
6. 可达性：range 保留原生键盘操作（方向键/Home/End），点选瓦片为真实 <button> 带 aria-label 与 :focus-visible 描边。

六、后台配置（管理员切换默认验证方式）

路径：后台 → 系统设置 → 系统基础（manage:system 权限），两项新配置：

• 存量库无这两行时，设置页按默认值兜底展示，保存一次即落库（与既有 adminlogincaptcha 同机制）。
• 服务端对非法取值直接拒绝保存（Response::error），防止把配置写坏后全员无法登录。
• 也可直接用 API：POST admin&a=settingssave，data={"captchastyle":"passive","captcha_fallback":"slide"}。

settings 表示例

('captcha_style',    '"passive"', 'system', '图形验证码样式: slide/click/icon/passive/digits/mixed', 0),
('captcha_fallback', '"slide"',   'system', '无感验证未通过时回退的验证码: slide/click/icon/digits/mixed', 0),

七、兼容性处理建议

升级步骤建议

1. 部署代码（PHP/JS/CSS 同版本发布，注意 app.css/captcha.js 已带 ?v=20261013 版本参数，发布后强刷缓存）。
2. 后台「系统设置」把 captcha_style 先设为 click 或 icon 观察一日，再按需切 passive（无感对正常用户零打扰，机器人自动落交互式验证）。
3. 若站点以老旧设备为主，保持 slide 或 digits 即可——样式修复对旧方式同样生效。

八、自测结果

• CaptchaModel 6 种样式签发/校验桩件测试：39/39 通过（含顺序敏感、容差边界、token 消耗、passive 各阈值、配置驱动回退）。
• 5 个视图渲染冒烟测试通过（DOM id 齐全、无旧 id/旧函数残留、设置页下拉选中态正确）。
• php -l 全部通过；node --check captcha.js 通过。