登录与会话
# 登录与会话
# 目的
让读者用租户或平台口令完成登录、刷新 access、退出和改密，并理解刷新 Cookie 与 access 的分工。成功登录后 JSON 里能看到 accessToken 与 expiresIn，浏览器会收到 HttpOnly 刷新 Cookie；改密或全局退出后应回到登录页且旧 access 不再加载菜单。
# 前置条件
API 已迁移并完成初始化，Redis 可用。浏览器或调用方使用的 Origin 必须与 APP_AUTH_ORIGINS 中登记的精确值一致；租户请求还要带 X-App-Request: admin，平台带 platform。开发 loopback 需 APP_AUTH_COOKIE_PROFILE=development-http。缺 Origin 或不在白名单会返回 403004，不能靠伪造租户头切换身份。
租户身份走 /api/admin/v1，平台身份走 /api/platform/v1。两套账号、会话和 Cookie 分开。
# 租户口令登录
下列请求在开发/测试为明文 JSON；生产须先按 日志、脱敏与请求加密 加密正文，解密后的字段相同。
POST /api/admin/v1/auth/login
Origin: http://127.0.0.1:5174
X-App-Request: admin
Content-Type: application/json
{
"tenantCode": "example",
"clientId": "admin-web",
"username": "admin",
"password": "<操作者提供>"
}
成功时刷新凭证只写入 HttpOnly Cookie，不出现在 JSON：
{
"code": 0,
"data": {
"accessToken": "<access>",
"expiresIn": 900,
"mustChangePassword": true
},
"message": "ok",
"requestId": "req_example"
}
未知账号、口令错误、租户停用和过期，对外统一为 HTTP 401 与 401003，调用方不能据此判断账号是否存在：
{
"code": 401003,
"message": "账号或密码错误",
"requestId": "req_example"
}
平台身份使用 POST /api/platform/v1/auth/login，正文不含 tenantCode，X-App-Request 为 platform，clientId 通常为 platform-web。
客户端须在同 realm 注册表启用；更短期限、同应用会话上限与配置版本 fencing 见 身份客户端与设备会话。access 默认 15 分钟；刷新 Cookie 最长 7 天，会话绝对期限 30 天。业务空闲由租户安全策略决定，种子 30 分钟。必须改密会话绝对期限 30 分钟，刷新不会延长该期限。
连续 5 次口令失败锁定 15 分钟。Redis 限流在校验口令之前；Redis 故障返回 503001，限流拒绝不增加账号失败次数。
# Cookie
刷新 Cookie 按浏览器请求的 Origin 协议选择名称与 Secure：HTTPS 使用 __Secure-admin_rt / __Secure-platform_rt 且带 Secure；HTTP loopback 使用 dev_admin_rt / dev_platform_rt 且不带 Secure。均为 HttpOnly、SameSite=Strict、无 Domain，Path 分别为 /api/admin/v1/auth 与 /api/platform/v1/auth。
development-http 在开发/测试只允许 loopback HTTP Origin。生产允许 HTTP 时 API 启动 WARN，不因此拒绝启动。
# 刷新、退出和改密
携带与登录相同的 Origin、X-App-Request 与刷新 Cookie：
POST /api/admin/v1/auth/refresh
Origin: http://127.0.0.1:5174
X-App-Request: admin
Content-Type: application/json
{}
旧的 refresh 再次使用会先撤销会话，再返回 401002（会话已失效，请重新登录）。合法刷新后，同一会话里尚未到期的旧 access 仍可用到自身过期时间。
改密仅针对当前登录者，成功后撤销全部会话并清除 Cookie，须重新登录：
PUT /api/admin/v1/profile/password
Origin: http://127.0.0.1:5174
X-App-Request: admin
Authorization: Bearer <access>
Content-Type: application/json
{
"currentPassword": "<操作者提供>",
"newPassword": "<操作者提供的新口令>"
}
GET /auth/sessions 与 DELETE /auth/sessions/{id} 只处理本人、同一 realm 的会话；他人会话为 404001。DELETE /auth/sessions 撤销本人当前 realm 下所有 client 的会话。
mustChangePassword 为 true 时，除刷新、退出和本人改密外，受保护入口返回 403003。
# 边界
本页为口令登录与本地会话；浏览器 OIDC 入口见 浏览器单点登录（前端路径）与 账号认证模式。服务账号不使用本页接口。