update 20260912

开发指南与架构.md

@@ -28,6 +28,7 @@ npm run build
 ## 接口与鉴权约定
 
 - 控制器使用 `[Authorize]` 与角色限制，并在业务查询和写入中落实数据范围。
+- 登录页通过匿名 `POST /api/auth/login/captcha` 获取验证码图片和 `captchaId`；登录请求提交 `captchaId` 与 `captchaCode`，服务端校验后再执行密码认证。验证码约两分钟过期且一次性消费，普通登录和 Keycloak SSO 登录都必须完成该校验。
 - `CurrentUserDataScope` 等服务负责当前用户的学院、行政班、本人等范围；新增接口不得只在前端限制数据。
 - 教师与教学任务关系、学生与档案关系必须从数据库按当前用户验证。对依赖导航属性的授权判断，显式加载需要的关系或改用数据库查询，避免跟踪上下文偶然掩盖授权缺陷。
 - 列表接口优先提供服务端筛选、`Count / Skip / Take` 分页；不要先加载所有数据再在浏览器分页。

快速开始与账号.md

@@ -11,8 +11,11 @@
 ## 登录与退出
 
 1. 在登录页输入已有账号和密码。
-2. 登录成功后，系统保存短期访问令牌并依据 Web 或 App 的空闲时长维持会话。
+2. 按页面验证码图片输入字符；验证码可点击图片或“换一张”刷新。验证码有效期约两分钟，每次登录或单点登录只使用一次。
-3. 使用完毕后从右上角个人菜单退出，尤其是在公共计算机上。
+3. 登录成功后，系统保存短期访问令牌并依据 Web 或 App 的空闲时长维持会话。
+4. 使用完毕后从右上角个人菜单退出，尤其是在公共计算机上。
+
+验证码输入错误、过期或登录失败后，页面会自动刷新验证码；请使用新图片重新输入。验证码只用于登录前的安全校验，不是“个人账户”中的动态验证码。若账号已启用认证器二次验证，密码正确后还需输入认证器生成的 6 位验证码或恢复码。
 
 若学校启用了 Keycloak 单点登录，登录页会显示统一身份认证入口。Keycloak 仅负责确认身份；本系统中的账号启用状态、角色和数据范围仍由本系统控制。首次单点登录会优先匹配同名本地账号；用户名不同则按页面提示验证已有本地账号完成绑定，不会自动创建高权限账号。
 
@@ -50,6 +53,7 @@
 | 现象 | 优先处理方式 |
 | --- | --- |
 | 忘记密码 | 联系有账号管理权限的管理员按学校流程重置，不要新建重复账号。 |
+| 验证码看不清或提示失效 | 点击验证码图片或“换一张”获取新图片，并在同一次登录尝试中输入新验证码。 |
 | 自助激活失败 | 对照学生档案逐项核对六项身份信息；无法确认时由学院核查。 |
 | 看不到菜单 | 确认账号角色、关联的教师/学生档案、学院范围及业务状态。 |
 | 登录后频繁失效 | 检查网络、浏览器隐私/存储限制和部署的 JWT 空闲时长配置。 |

部署指南.md

@@ -82,7 +82,7 @@ curl --fail http://127.0.0.1:8080/health/ready
 
 - [ ] MySQL 连接、迁移和备份恢复演练通过。
 - [ ] `/health/ready` 可用，HTTPS 证书和反向代理正确。
-- [ ] 管理员可登录，学生自助激活和普通登录可用。
+- [ ] 管理员可登录，验证码获取/刷新/一次性校验、学生自助激活和普通登录可用。
 - [ ] CORS、JWT、SSO 回调与公开域名一致。
 - [ ] 排课、选课、成绩、考试、凭证验真等关键链路按角色验证。
 - [ ] Redis/RabbitMQ（如启用）连接、后台消费者和失败告警可用。