实现登录权限底座

docs/project/frontend-backend/README.md

@@ -43,9 +43,7 @@
 - 普通任务切换订单接口后置。
 - 任务详情 / 任务写操作是否需要显式 `hotel_id` 已确认后置；第一版先按 ID 定位，后续多酒店隔离 / 权限方案统一补齐。
 - 邮件会话详情已返回 `html_body_sanitized` 和 `html_render_mode`；前端展示 HTML 时优先使用清洗字段，`html_body` 只作为原始内容兼容字段。
-- SuperAgent 查询接口 4 后置，当前先不开发。
-- SuperAgent 查询接口 3 涉及附件解析、OCR、Excel、voucher、rooming list 等能力，当前系统暂不具备，仍后置。
-- 用户身份 / 权限方案后置；当前后端审计 actor 仍是本地占位。
+- 用户 / 权限底座后端 CP1 已完成；前端登录页、动态菜单、管理后台和业务审计 actor 全量迁移仍后置。
 - 真实 OPERA / OHIP 接入后置；当前仅有 OPERA 模拟骨架。
 
 ## 6. 前端开发注意事项

docs/project/frontend-backend/backend-to-frontend-notes.md

@@ -29,13 +29,16 @@
 - 同一订单下，前置任务未结束时，后续任务只能查看，不能编辑、确认或执行 OPERA 模拟操作。
 - 任务状态 `FAILED` 第一版视为结束状态，不阻塞后续任务；但失败的 OPERA 操作不能跳过，必须展示失败原因并允许重试。
 - Message Notification 挂临时订单，只读展示，不参与订单任务执行队列，不阻塞其他任务，也不被其他任务阻塞。
-- Fallback / manual_review 转为 New / Update / Cancel 时需要展示审计轨迹；当前 actor 仍是本地占位，正式用户身份后置。
+- Fallback / manual_review 转为 New / Update / Cancel 时需要展示审计轨迹；登录权限底座已提供，具体业务审计 actor 迁移仍后置。
 - 普通任务切换订单接口已确认后置，前端第一版不要把普通任务拖拽或切换订单做成可提交能力。
 
 ## 5. 当前前端可用接口注意事项
 
 | 接口 | 用途 | 前端注意 |
 | --- | --- | --- |
+| `POST /api/auth/login` | 用户名密码登录 | 成功后返回 `access_token`、当前用户、可访问酒店、权限码和可见菜单；token 只放 `sessionStorage`，不要放 `localStorage`、URL、日志或错误上报。 |
+| `GET /api/auth/me` | 恢复当前登录态 | 前端启动后带 `Authorization: Bearer <access_token>` 调用；401 时清理 token 并进入登录页。 |
+| `POST /api/auth/logout` | 登出当前 session | 带 `Authorization: Bearer <access_token>`；成功后前端必须清理本地 token 和当前用户上下文。 |
 | `GET /api/reservation/orders` | 查询订单列表 | 默认返回全部订单状态；`open_task_count` 排除 `COMPLETED` 和 `FAILED`；用 `next_processable_task_id` 引导用户继续处理。 |
 | `GET /api/reservation/tasks` | 查询任务列表 / 工作台 | 用 `can_process` 和 `readonly_reason_code` 控制入口按钮；列表不返回 AI 原始 payload、邮件正文或附件 URL；已返回来源邮件会话摘要字段，并支持 `order_status` 按任务所属订单状态筛选。 |
 | `GET /api/reservation/orders/{orderId}` | 查询订单详情与任务时间线 | `include_tasks=false` 可只取订单摘要；时间线按后端队列顺序返回，前端不要自行按创建时间重排；`tasks[]` 已返回来源邮件会话摘要字段。 |
@@ -65,7 +68,29 @@
 | `GET /api/source-messages/{sourceMessageId}/conversation` | 新增邮件会话详情接口，并补齐 `html_body_sanitized` / `html_render_mode`。 | 当前唯一推荐路径是这个接口；前端渲染邮件 HTML 时优先使用 `html_body_sanitized`；不要调用历史讨论过的 `/api/source-message-conversations/{externalConversationId}`。 |
 | `POST /api/system/debug/eml-superagent-runs` | 新增 Debug EML 上传到 SuperAgent 调试接口，并补齐独立 Debug 外部消息 ID、原始 Message-ID 保留和安全 HTML 字段。 | 只用于调试页面；请求为 multipart/form-data；必须传 `X-TH-Hotel-Debug-Upload-Key`，但该 key 不能写进前端源码、构建产物、URL、localStorage 或错误上报。 |
 
-### 5.2 来源邮件会话字段说明
+### 5.2 登录权限接入注意
+
+后端已提供 M003 登录和权限底座第一版接口：
+
+```text
+POST /api/auth/login
+GET /api/auth/me
+POST /api/auth/logout
+```
+
+前端注意：
+
+- 登录成功后只把 `access_token` 保存到 `sessionStorage`；刷新同一浏览器会话可恢复，关闭浏览器后需要重新登录。
+- 所有需要登录态的后端请求使用 `Authorization: Bearer <access_token>`。
+- 当前后端第一版不强制拦截既有 Reservation / SourceMessage 业务接口；但是前端接入登录后应统一带上 Bearer token，方便后续审计 actor 和权限收口。
+- `/api/auth/me` 返回 `user`、`default_hotel_id`、`hotels[]`、`permissions[]`、`menus[]`；菜单入口应优先使用 `menus[]`，不要继续硬编码订单列表、任务队列、Debug EML。
+- `menus[]` 只包含可见菜单；订单详情、任务详情和邮件会话详情是隐藏详情路由，不会作为菜单项返回。
+- `DEBUG_EML_SUPERAGENT` 菜单第一版只授予 `SYSTEM_ADMIN`；这只表示页面入口是否可见，不代表后端会把 `X-TH-Hotel-Debug-Upload-Key` 下发给前端。
+- `user.id` 是字符串；前端不要把任何后端 ID 转成 JavaScript number。
+- 登录失败统一显示用户名或密码错误，不要根据错误文案推断账号是否存在或是否禁用。
+- 401 的 `AUTH_TOKEN_REQUIRED` / `AUTH_SESSION_INVALID` 应统一走清理 token、回登录页的逻辑。
+
+### 5.3 来源邮件会话字段说明
 
 任务列表、订单详情任务时间线、任务详情顶层会返回以下来源邮件字段：
 
@@ -78,7 +103,7 @@
 | `external_conversation_id` | 外部邮件会话 ID。 | 仅用于展示或调试，不作为当前会话详情接口路径参数。 |
 | `conversation_message_count` | 同一外部会话下的邮件数量。 | 用于提示用户打开的是整段会话，不是单封邮件。 |
 
-### 5.3 邮件会话详情接入注意
+### 5.4 邮件会话详情接入注意
 
 - `GET /api/source-messages/{sourceMessageId}/conversation` 只接收路径参数 `sourceMessageId`；第一版不接收 `hotelId`、`includeBody`、`includeRelated`。
 - 前端当前通过 `VITE_RESERVATION_HOTEL_ID` 统一配置 Reservation 默认酒店上下文，并会在订单列表、任务列表和订单详情查询中传 `hotel_id`；任务详情、任务写操作和邮件会话详情当前后端接口不接收该参数。
@@ -90,7 +115,7 @@
 - 会话详情接口由后端内部写原文读取审计，前端不传 `X-TH-Hotel-Source-Original-Read-Key`。
 - 会话详情外层字段主要是 snake_case，但媒体对象沿用原文读取接口字段，当前是 `mediaType`、`fileName`、`contentType`、`sizeBytes`、`externalUrl`、`externalMediaId` 这种 camelCase，前端类型定义需要单独处理。
 
-### 5.4 订单列表接入注意
+### 5.5 订单列表接入注意
 
 - `GET /api/reservation/orders` 默认返回全部订单状态，包括 `TEMPORARY`、`ACTIVE`、`ENDED`、`LOGIC_DELETED`。
 - `keyword` 会匹配订单业务号、临时订单号、展示名、订单状态，也会匹配来源消息安全摘要命中的 SourceMessage ID；前端可以用邮件主题、外部消息 ID 或会话 ID 辅助查订单。
@@ -99,7 +124,7 @@
 - `display_order_key` 是前端优先展示的订单业务号或临时订单号；`group_code` 和 `confirmation_number` 只有在当前订单业务号类型匹配时返回。
 - 订单 ID、任务 ID、SourceMessage ID 在这些前端接口中按字符串返回，前端不要转换成 JavaScript number。
 
-### 5.5 前端联调演示数据 seed 接口
+### 5.6 前端联调演示数据 seed 接口
 
 后端提供一个受控的 dev/test 演示数据入口，方便前端在空库或本地环境快速看到页面效果。
 
@@ -137,7 +162,7 @@ Content-Type: application/json
 - Message Notification 只读任务。
 - 同一邮件会话下多封邮件、完整 HTML、附件外链和内联图片外链。
 
-### 5.6 任务详情字段元数据接入注意
+### 5.7 任务详情字段元数据接入注意
 
 - `fields[]` 第一版服务于任务详情动态展示，字段来源与白名单规则以 `docs/import/20260708/任务卡前端展示字段表 3.0.xlsx` 为准。
 - `result_type`、`task_type`、`task_subtype`、`default_value_source` 已透出给前端，用于和最新前端白名单对齐。
@@ -145,7 +170,7 @@ Content-Type: application/json
 - 前端保存草稿时不要自行按 `write_path` 重组 OPERA 参数；第一版按任务详情返回的字段和值提交即可，真实 OPERA 参数组装后续由后端 adapter / 转换层处理。
 - 任务详情页控制按钮时以 `availability.editable`、`availability.confirmable`、`availability.executable`、`availability.read_only` 和 `availability.blocked` 为准；`can_process` 和 `readonly_reason_code` 只出现在任务列表 / 订单时间线摘要里。
 
-### 5.7 Debug EML 上传接口接入注意
+### 5.8 Debug EML 上传接口接入注意
 
 后端已提供 Debug 页面专用的 `.eml` 上传和 SuperAgent 调试入口：
 
@@ -187,8 +212,6 @@ run_label: 可选调试标签
 
 ## 7. 需要持续提醒的后置事项
 
-- SuperAgent 查询接口 3 文件解析当前不能做。
-- SuperAgent 查询接口 4 已确认继续后置。
 - 普通任务切换订单接口继续后置。
-- 用户 / 权限方案继续后置。
+- 用户 / 权限底座后端 CP1 已完成；前端登录页、动态菜单和管理后台仍后置。
 - 真实 OPERA / OHIP 接入继续后置。