# 登录审计

## 发布顺序

1. 在应用数据库执行 `docs/sql/20261021-login-audit.sql`。
2. 构建、部署应用。不能回溯部署前的登录，旧事件仍需查网关日志。
3. 使用后台 root 凭证访问 `GET /manage/login/audit/get?start=1&limit=20`。
   当前交付查询接口和表，不包含单独前端页面，前端项目不在此仓库。

## 查询

支持 `loginType`、`loginId`、`account`、`result`、`loginMethod`、`ip`、`from`、`to`。
时间格式 `yyyy-MM-dd HH:mm:ss`，URL 编码空格；沿用应用/数据库时间设置。
每页最多 100 条，按 id 倒序；只有后台精确角色 root 可以读取。

```text
/manage/login/audit/get?loginType=user&loginId=1533797&start=1&limit=20
/manage/login/audit/get?result=FAILURE&start=1&limit=20
```

## 字段与语义

- `loginType`：Sa-Token 身份域（普通用户 user，默认后台 login，其他身份域保留原值）。
- `loginId`：实际创建会话的身份 ID；失败时不猜测目标 ID。
- `account`：当前请求白名单 phone/email/login 字段；微信等没有提交账号的请求可为空。
- `loginMethod`：短信、邮箱、Google、微信、小程序、后台凭据检查、管理员代登录、切换账号等；
  未识别入口标记 other，不猜测。方式来自已执行接口和安全字段，UA 仅辅助证据。
- `SUCCESS/session_created`：全局 Sa-Token doLogin 事件，覆盖应用创建的各类登录会话。
- `CHECK_SUCCESS/password_check_passed`：后台密码预检查通过，不等于已签发登录会话。
- `FAILURE`：登录处理入口抛出异常，原因记录异常类型，不保存可能含凭据的异常原文。
  微信发起授权/轮询未完成不计成功；仅返回业务失败而未抛异常的第三方入口需另行适配。
- `remoteIp`：真实 socket 对端地址。`forwardedFor`、`realIp` 原样限长留存，
  是未验证代理头，可能伪造，不当作已确认客户端 IP。ip 筛选匹配 remoteIp 或 realIp。
- `userAgent`、`browser`、`os`、`device`：浏览器原始 UA、粗粒度解析、Sa-Token 设备。
- `requestPath`、`httpMethod`：不含查询字符串；不记录请求体、Cookie、Authorization、密码、验证码、token。
- `createdTime`、`durationMs`：事件时间和到事件发生时的耗时（不是整个 HTTP 请求耗时）。

审计单独事务写入，不跟随登录业务事务回滚；失败不阻断登录，会输出
`LOGIN_AUDIT_WRITE_FAILED` 和白名单字段的 `LOGIN_AUDIT_FALLBACK`，需采集应用日志并告警。
数据库/文件故障或进程中断仍可能丢日志；生产应配合独立日志采集与备份。

## 待执行验收

- 短信/邮箱/微信/Google/后台实际登录各生成 SUCCESS，凭据预检查单独标记 CHECK_SUCCESS。
- 密码错误、验证码错误抛异常时生成 FAILURE，账号、连接 IP 和 UA 可查询。
- 普通用户及非 root 后台请求查询接口被拒绝。
- 检查数据库和兜底日志不含密码、验证码、完整 token。
- 故意中断测试库审计表写入，确认业务不受影响且出现兜底日志。

尚未完成在线验收；本地 Maven 当前受现有腾讯云 SDK 依赖缺失阻断。