# Issue #3 第一阶段：管理员首次运行自检

本文记录 Issue #3 的 P1 首次运行自检交付。后续 #14 已另行实现 TOTP、一次性恢复码，以及 MFA 管理操作的当次密码和现有因素验证，详见[账号二次验证与恢复](/help/mfa)。这不表示全部敏感配置均已增加近期认证，也不包含 WebAuthn/Passkey。JWT 多密钥轮换、邮件投递诊断历史、授权趋势及接入沙盒等仍需分别验收，不能据此关闭整个 Issue #3。

## 使用与验收

管理员进入「系统设置 → 首次运行自检」，点击「运行自检」。配置修改后可以重新运行，结果只保留在当前页面；失败重试会清除旧结果。

`POST /api/v1/admin/setup-check` 复用登录会话、CSRF 和 `settings:write` 权限。返回 `data.checked_at` 与 `data.checks`；每项包含 `id`、`name`、`status`、`message`，适用的渠道另有 `callback_url`。状态为 `passed`、`warning`、`failed`、`skipped`。每次完成检查写入 `setup.check / system` 审计，审计写入失败则返回 503。

| 项目 | 检查内容 | 仍需实际验收 |
| --- | --- | --- |
| PostgreSQL / Redis | 分别以最多 2 秒进行 Ping | 服务持续可用性 |
| SMTP | 已保存配置可解密，主机、端口、邮箱、TLS 与凭据满足现有校验 | SMTP 连通、服务器接收、真实邮箱收件 |
| S3 | 启用存储的目标格式及凭据完整，未启用时提示 | 存储页面连接测试、真实上传与下载权限 |
| 支付渠道 | 启用渠道必填字段齐全、配置可解密 | 密钥有效性、支付与退款、回调验签 |
| 三方登录 | 启用渠道标识与密钥齐全、配置可解密 | 平台登记、授权及登录流程 |
| 站点地址 | APP_ORIGIN 格式，HTTP/本机地址提示上线前更换，生成实际路由对应回调地址 | 公网 HTTPS 可达性、渠道后台回调地址一致性 |

自检不向 SMTP、S3 或支付/登录平台发请求，不发送邮件、上传文件或创建交易。字段完整不等于渠道可用。银行转账不显示回调地址。未启用的渠道标记为跳过。

接口使用固定诊断消息，不返回配置原值、密文、凭据、连接串或底层错误；带用户名、密码、查询参数或路径的异常 APP_ORIGIN 不回显。回调地址来自服务端配置。

数据库和 Redis 也是登录验证依赖，服务不可用导致无法验证身份时会返回 503，不能绕过身份验证获取报告；数据库无法保存审计时同样返回 503。单次报告使用 10 秒上下文期限。

## 本机运行与验证记录

遵循根目录 AGENTS.md，应用直接在 Windows 运行。现有容器已检查：Postgres18 健康、映射 127.0.0.1:5432；RedisPwd 健康、映射 127.0.0.1:6379。没有创建、重建或修改容器，没有使用 MYSQL8 或历史测试容器。凭据只从忽略的本地配置读取。

后端启动：`./scripts/run-local.ps1 -Mode api`；前端在 web 目录设置 `API_URL=http://127.0.0.1:13141` 后 `npm run dev`。本次页面测试使用已有 13140 开发服务；新后端通过本机 Go HTTP 路由集成测试验证，并已将本项目 13141 后端重启为本机构建的 `.local/auth-center.exe`。健康检查返回 ready，未登录自检请求返回 401。无需数据库迁移。

已通过：

- `./scripts/run-local.ps1 -Mode test`：Go 单元测试和 `go vet`。默认未配置集成测试变量时集成用例跳过。
- 设置 `TEST_DATABASE_URL`、`TEST_REDIS_URL` 为本地已有服务连接后，在 server 目录运行 `go test ./internal/app -run TestSetup -count=1 -v`：本次新增集成测试实际通过，在 Postgres18 新建随机临时 schema 并清理，不写业务表；Redis 仅 Ping。覆盖匿名/无权限/CSRF 拒绝、默认配置、完整与损坏配置、缺少密钥、回调、脱敏、审计及审计失败。
- `./scripts/run-local.ps1 -Mode build`：后端编译。
- web 目录 `npm run build`：前端构建及 TypeScript 检查。
- 根目录 `node scripts/setup-check-ui-check.cjs`：使用 Playwright（必要时通过 NODE_PATH 指向已安装包），在已有本机前端以 API fixtures 验证 1440/390 像素布局、权限隐藏、执行、失败清除旧结果和重试；不修改真实账号。

未执行：SMTP、S3、支付及三方登录真实渠道联调；已有全套写入式 HTTP 业务测试。本次没有把配置检查或模拟页面测试表述为外部渠道验收成功。