# 安全引导与设置提示修复验收

日期：2026-09-05

## 本次范围

- [✓] 首次登录显示密保问题、外部安全邮箱、安全密钥引导，包含超级管理员。
- [✓] 引导确认状态按账号持久化，确认失败保留弹窗并允许重试。
- [✓] 强制修改密码页面不显示引导，进入邮箱后再提示。
- [✓] 设置标签页按需加载，未启用安全密钥时显示状态说明。
- [✓] 旧版配置模式先读取配置管理状态，不继续请求分区、备份、审计。
- [✓] 退出时销毁会话和 CSRF Cookie，避免下一次登录被残留会话阻断。
- [!] 现有主服务替换及完整 setup 向导重新验收未完成。
- [!] Git 推送因远程认证失败未完成；用户已授权先本地修复。

## 引导语义

新增数据库迁移 15，为用户增加 `security_setup_acknowledged`，默认值为零。
新账号与尚未确认过新引导的旧账号均显示一次引导。
只有点击引导中的确认或前往设置按钮，并且服务端成功持久化后，才停止自动提示。
未确认时刷新仍显示，避免页面刚加载或请求失败就丢失引导。
多标签页已经显示的弹窗不会实时同步关闭，确认接口可重复安全调用。

`POST /api/v1/security/setup/acknowledge` 只处理当前会话用户，不接受目标账号切换。
接口使用正式会话、请求来源、CSRF 与强制改密校验链路。
确认引导不代表已完成任何安全设置，也不会修改密码或安全版本。

普通账号离线恢复码仍可在安全设置内生成，旧恢复码组件文件保留但不再全局自动弹出。
超级管理员不开放网页密码恢复或离线恢复码入口，部署端本机 IPC 安全边界保持不变。

## 浏览器实测

隔离服务地址：`https://localhost:15443/`，采用临时自签名证书。
服务使用独立空 SQLite、正式迁移器、真实登录/会话/CSRF/配置控制器，以及最新前端构建。
测试账号由夹具创建，并非完整 setup 向导创建；未使用当前业务库。

1. 超级管理员通过登录表单进入收件箱，出现三项安全引导。
2. 未带 CSRF 的确认请求返回业务错误，不能确认引导。
3. 点击开始设置，确认成功后进入密保问题页，无配置管理请求和错误通知。
4. 点击安全密钥，显示服务器未启用说明，不发送凭据列表请求。
5. 切到配置管理，只请求一次状态，显示旧版配置迁移说明，无重复错误通知。
6. 刷新后用户信息成功返回，`showSecuritySetupPrompt=false`，保持登录且不再弹窗。
7. 退出重登实测发现原实现保留会话 Cookie；改为销毁后，在干净隔离浏览器上下文重测，登录成功且不再弹窗。

隔离夹具不启动 SMTP/IMAP/POP 或管理员 IPC，不构成完整服务部署验收。
当前旧后端仍需要由具备相应权限的部署人员切换至新版本。
旧版配置迁移及 WebAuthn 服务启用本身不在此次自动操作范围，不能将状态提示当成功能已启用。

## 验证与产物

- 后端全套 `go test ./...` 已运行通过；部分外部数据库或管理员权限相关测试按原有条件跳过。
- 新增迁移默认值/幂等、账号隔离、匿名拒绝、HTTP 方法/CSRF、退出 Cookie 销毁回归测试。
- 前端新增引导与配置请求行为测试；执行 `npm test` 与 `npm run build`。
- 前端构建仍有大型分包警告，不影响本次构建成功。
- 本地后端产物：`backend/.tmp-smail-security-setup.exe`。
- 真实业务 SQLite、现有 DKIM 改动未修改或提交；测试数据保留在忽略目录中。

隔离浏览器夹具需显式设置 `SMAIL_BROWSER_FIXTURE=1`、新的 `SMAIL_BROWSER_ROOT`、
`SMAIL_BROWSER_PASSWORD`、`SMAIL_BROWSER_DIST`，然后仅运行
`TestSecuritySetupBrowserFixture`。默认跳过，启用后最长运行 30 分钟。
不要给夹具指定真实数据目录，也不要把测试密码写入版本控制。