实现系统管理后台 V1

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

@@ -2,7 +2,7 @@
 
 ## 1. 文档定位
 
-本文记录后端侧提醒前端开发时必须注意的项目规范、业务规则、接口边界和安全要求。当前内容服务于 Reservation 任务详情、订单详情、任务列表、S000/S999 特殊只读任务、历史 Message Notification 等第一版页面。
+本文记录后端侧提醒前端开发时必须注意的项目规范、业务规则、接口边界和安全要求。当前内容服务于 Reservation 任务详情、订单详情、任务列表、S000/S999 特殊只读任务、历史 Message Notification、系统管理后台等第一版页面。
 
 ## 2. 项目开发注意事项
 
@@ -11,6 +11,7 @@
 - 业务判断必须使用后端返回的稳定 code，不使用中文或英文展示文案做判断。
 - 后端返回的时间点字段统一是带 `Z` 的 ISO 8601 UTC 时间，例如 `created_at`、`updated_at`、`received_at`、`last_updated_at`；前端展示时再按用户或酒店时区格式化。
 - 入住日期、离店日期、酒店营业日属于酒店本地业务日期，不要按 UTC 时间点自动换算日期。
+- 详细时间设计参考 `docs/project/backend-time-design.md`，不要把数据库 UTC 时间直接当酒店当地时间展示。
 - 前端不得保存或传递后端 Secret、replay access key、Provider API Key、Oracle 凭证、AgentBus Token。
 - 后端数据库 ID 未来应尽量以字符串形式给前端，避免 JavaScript 长整型精度问题；如果当前接口仍返回数字，前端不要自行做数学运算。
 - 接口字段发生变化前，需要先更新本目录沟通文档或对应需求文档。
@@ -57,6 +58,12 @@
 | `GET /api/source-messages/{id}/original` | 读取来源消息原文 | 需要受控访问头，返回 HTML 时前端展示前必须 sanitize。 |
 | `GET /api/source-messages/{sourceMessageId}/conversation` | 读取邮件会话详情 | 返回同一外部会话全部邮件的完整 text/html、`html_body_sanitized`、附件外链、内联图片和关联订单 / 任务摘要；前端不传原文读取 key，展示 HTML 时优先使用 `html_body_sanitized`。 |
 | `POST /api/system/debug/eml-superagent-runs` | Debug 页面上传 `.eml` 并调用 SuperAgent | 仅 dev/test 受控调试使用；会写入 SourceMessage Inbox，但不创建订单和任务。 |
+| `GET/POST/PUT /api/admin/users...` | 系统管理用户维护 | 需要 Bearer token 和 `SYSTEM_USER_MANAGE`；用户 ID 返回字符串；禁用用户会撤销其 ACTIVE session。 |
+| `GET/POST/PUT /api/admin/roles...` | 系统管理角色权限维护 | 需要 `SYSTEM_ROLE_MANAGE`；内置角色只读，自定义角色可新增、编辑和分配权限。 |
+| `GET /api/admin/permissions` | 权限码只读列表 | 需要 `SYSTEM_ROLE_MANAGE`；前端只展示和选择已有权限码，不自行造权限码。 |
+| `GET/POST/PUT /api/admin/menus...` | 系统管理菜单维护 | 需要 `SYSTEM_MENU_MANAGE`；允许保存未知路由，前端必须有未知路由兜底页。 |
+| `GET/POST/PUT /api/admin/hotels...` | 系统管理酒店维护 | 需要 `HOTEL_MANAGE`；新增酒店默认 `DISABLED`，单酒店阶段不能启用第二家 `ACTIVE`。 |
+| `GET /api/admin/audits` | 系统管理操作审计 | 需要 `SYSTEM_ADMIN_CONSOLE_ACCESS`；用于查看管理后台写操作审计，不包含密码、token、secret。 |
 
 ### 5.1 本轮新增 / 修改接口说明
 
@@ -209,6 +216,41 @@ run_label: 可选调试标签
 - 返回的 `uploaded_media[]`、`original_eml_oss_url`、`html_body_with_oss_urls`、`html_body_sanitized` 可能包含 OSS URL；前端不要写入普通日志、埋点、错误上报或 URL query。
 - `superagent_parsed_json` 为空时，前端展示 `superagent_raw_answer` 和 `warnings[]`，不要假定 SuperAgent 总能返回 JSON。
 
+### 5.9 系统管理后台接口接入注意
+
+系统管理后台 V1 已提供 `/system` 前端入口和 `/api/admin/**` 后端接口。所有管理接口都必须带 `Authorization: Bearer <access_token>`，无 token 返回 401，已登录但缺少权限返回 403。
+
+前端路由和按钮注意：
+
+- `/system` 入口需要 `SYSTEM_ADMIN_CONSOLE_ACCESS`；子页面按 `SYSTEM_USER_MANAGE`、`SYSTEM_ROLE_MANAGE`、`SYSTEM_MENU_MANAGE`、`HOTEL_MANAGE` 展示。
+- 如果用户只有酒店管理权限，进入 `/system` 时应跳到 `/system/hotels`，不要固定跳 `/system/users`。
+- 系统管理入口只代表可进入后台，不代表拥有所有子页面操作权限；按钮仍需按具体权限控制。
+- 直接访问未知菜单路由时前端必须展示安全兜底页，不要让页面白屏。
+
+接口分页和字段注意：
+
+- 分页统一使用 `page_num`、`page_size`，响应统一是 `{ items, page: { page_num, page_size, total } }`。
+- 后端 `BIGINT` ID 返回字符串，前端不要转成 JavaScript number。
+- 时间点字段是带 `Z` 的 UTC 时间，展示时按用户或酒店时区格式化。
+- 写操作失败时前端应展示后端 `message` 或 `error_code`，尤其是启用第二家 `ACTIVE` 酒店、禁用最后一家 `ACTIVE` 酒店、修改内置角色、用户名重复等 409 场景。
+
+用户管理注意：
+
+- 新增用户必须传初始密码，后端只保存哈希。
+- 用户启用 / 禁用通过 `PUT /api/admin/users/{userId}` 的 `user_status` 完成，没有单独 enable / disable 路径。
+- 禁用用户会撤销该用户全部 ACTIVE session；前端若正用该用户 token，会在下一次 `/api/auth/me` 或业务请求时收到 401。
+- 重置密码接口 `POST /api/admin/users/{userId}/password-reset` 只在本次响应返回 `temporary_password`，前端不能写入日志、埋点、URL、localStorage 或错误上报。
+- 用户授权酒店必须全部是 `ACTIVE` 酒店，默认酒店必须在授权酒店列表内。
+
+角色、菜单、酒店注意：
+
+- 内置角色 `system_builtin=true` 时只读，前端应禁用编辑和权限分配按钮；后端仍会返回 409 兜底。
+- 新增自定义角色后，用户需要重新登录或刷新 `/api/auth/me` 才能拿到最新权限上下文。
+- 新增菜单允许未知路由；未知路由可以保存，但正式开放可见前要确认前端页面已经存在或兜底页可接受。
+- 新增酒店默认 `DISABLED`，`hotel_id` 新增后不能修改。
+- 单酒店阶段只允许一家 `ACTIVE` 酒店，后端会拒绝启用第二家 `ACTIVE`，也会拒绝禁用最后一家 `ACTIVE`。
+- 系统管理写操作会写入 `platform_admin_audit_log`；审计接口 `GET /api/admin/audits` 可按 `target_type`、`target_id`、`action` 查询。
+
 ## 6. 不给前端直接调用的接口
 
 - `POST /api/system/reservation/demo-data` 只用于 dev/test 联调造数，不是生产业务页面接口；访问口令不能进入前端代码。
@@ -221,5 +263,6 @@ run_label: 可选调试标签
 ## 7. 需要持续提醒的后置事项
 
 - 普通任务切换订单接口继续后置。
-- 用户 / 权限底座后端 CP1 已完成；前端登录页、动态菜单和管理后台仍后置。
+- 系统管理后台 V1 已完成；后续若要做用户搜索更多筛选、批量操作、密码策略增强、MFA、登录设备管理，应单独开需求。
+- 现有 Reservation / SourceMessage 业务接口的强制登录、强制权限和业务审计 actor 全量迁移仍后置。
 - 真实 OPERA / OHIP 接入继续后置。