# M006 System Admin Management Console V1 Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 实现 M006 系统管理后台 V1，让系统管理员可以通过受控接口和前端页面管理用户、角色权限、菜单、酒店和用户酒店授权。

**Architecture:** 后端继续使用 `platform.identity`、`platform.access`、`platform.navigation`、`platform.hotel` 分模块承载管理能力，新增平台管理审计和统一管理鉴权服务。前端新增 `/system/*` 子路由和系统管理页面，复用现有 `httpClient`、登录态和菜单权限模型。

**Tech Stack:** Java 17、Spring Boot 3.5、MyBatis-Plus、Flyway、JUnit 5、Vue 3、TypeScript、Pinia、Vitest。

## Global Constraints

- 管理接口统一使用 `/api/admin/**`。
- 管理接口必须强制登录和权限校验，不能依赖 `OptionalAuthTokenFilter` 的兼容行为。
- 系统管理入口使用 `SYSTEM_ADMIN_CONSOLE_ACCESS` 权限码。
- 分页请求使用 `page_num`、`page_size`，响应使用 `{ items, page: { page_num, page_size, total } }`。
- 内置角色第一版只读，自定义角色可管理。
- 单酒店阶段允许新增酒店但默认 `DISABLED`，禁止启用第二家 `ACTIVE`，禁止禁用最后一家 `ACTIVE`。
- `hotel_id` 新增后不可修改。
- 新增菜单允许未知路由，但未知路由前端必须安全兜底。
- 写操作必须写入独立平台管理审计表，审计不得保存密码、token、secret。
- 后端代码遵守 `control`、`service`、`service.impl`、`domain`、`mapper`、`repository`、`common.request/result/dto/enums` 包结构。
- Controller、Service、ServiceImpl 方法必须有中文注释；Entity 字段必须有中文注释。

---

### Task 1: M006 基础权限、菜单入口和管理鉴权

**Files:**
- Modify: `server/src/main/java/cn/nianxx/thhotel/platform/access/common/enums/PlatformPermissionCode.java`
- Modify: `server/src/main/java/cn/nianxx/thhotel/platform/navigation/common/enums/PlatformMenuCode.java`
- Modify: `server/src/main/java/cn/nianxx/thhotel/platform/identity/service/impl/PlatformIdentityBootstrapRunner.java`
- Create: `server/src/main/java/cn/nianxx/thhotel/platform/security/service/AdminAuthorizationService.java`
- Create: `server/src/main/java/cn/nianxx/thhotel/platform/security/service/impl/AdminAuthorizationServiceImpl.java`
- Create: `server/src/main/java/cn/nianxx/thhotel/platform/security/service/impl/AdminAuthorizationException.java`
- Test: `server/src/test/java/cn/nianxx/thhotel/platform/identity/control/AuthControllerTest.java`
- Test: `server/src/test/java/cn/nianxx/thhotel/platform/security/service/impl/AdminAuthorizationServiceImplTest.java`

**Interfaces:**
- Produces: `AdminAuthorizationService.requirePermission(String permissionCode)` returns current `AuthenticatedUserContext` or throws an admin authorization exception.
- Produces: `SYSTEM_ADMIN_CONSOLE_ACCESS` permission code and visible `/system` menu.

- [x] Add `SYSTEM_ADMIN_CONSOLE_ACCESS` to platform permission enum.
- [x] Change `SYSTEM_SETTINGS` menu to visible and bind `SYSTEM_ADMIN_CONSOLE_ACCESS`.
- [x] Include `SYSTEM_ADMIN_CONSOLE_ACCESS` in `SYSTEM_ADMIN` built-in permissions.
- [x] Create admin authorization service with 401 and 403 semantics.
- [x] Add tests for missing token, missing permission and successful authorization.
- [x] Run focused backend tests.

### Task 2: CP4-1 后端只读查询接口

**Files:**
- Create/Modify under `platform.identity.common.result/request/service/control/repository`
- Create/Modify under `platform.access.common.result/request/service/control/repository`
- Create/Modify under `platform.navigation.common.result/request/service/control/repository`
- Create/Modify under `platform.hotel.common.result/request/service/control/repository`
- Test: admin read-only controller tests.

**Interfaces:**
- Produces: `GET /api/admin/users`
- Produces: `GET /api/admin/users/{userId}`
- Produces: `GET /api/admin/roles`
- Produces: `GET /api/admin/roles/{roleId}`
- Produces: `GET /api/admin/permissions`
- Produces: `GET /api/admin/menus`
- Produces: `GET /api/admin/menus/{menuId}`
- Produces: `GET /api/admin/hotels`
- Produces: `GET /api/admin/hotels/{hotelId}`

- [x] Add repository list/detail methods with pagination where needed.
- [x] Add Service interfaces and implementations for read-only admin queries.
- [x] Add Controller classes with Chinese method comments.
- [x] Enforce management permissions per endpoint.
- [x] Return string IDs and UTC time strings.
- [x] Add MockMvc tests for 401, 403 and successful list responses.
- [x] Run focused backend tests.

### Task 3: CP4-1 前端只读系统管理页面

**Files:**
- Modify: `client/src/types/auth.ts`
- Modify: `client/src/router/index.ts`
- Modify: `client/src/layouts/ReservationAppShell.vue`
- Create: `client/src/types/systemAdmin.ts`
- Create: `client/src/services/systemAdminService.ts`
- Create: `client/src/views/system/SystemAdminLayoutView.vue`
- Create: `client/src/views/system/SystemUsersView.vue`
- Create: `client/src/views/system/SystemRolesView.vue`
- Create: `client/src/views/system/SystemMenusView.vue`
- Create: `client/src/views/system/SystemHotelsView.vue`
- Modify: locale files under `client/src/i18n/locales/`
- Test: front-end route/service/view tests.

**Interfaces:**
- Consumes: Task 2 admin read-only endpoints.
- Produces: visible `/system/*` routes and read-only admin tables.

- [x] Add `SYSTEM_ADMIN_CONSOLE_ACCESS` to auth permission type.
- [x] Add `/system` redirect and `/system/*` child routes.
- [x] Add system menu label and known route fallback.
- [x] Implement API service and types.
- [x] Implement four read-only pages with loading, error and empty states.
- [x] Add frontend tests for route permission and API parameter mapping.
- [x] Run frontend typecheck and tests.

### Task 4: 平台管理审计底座

**Files:**
- Create: `server/src/main/resources/db/migration/V15__create_platform_admin_audit_log.sql`
- Create: `server/src/main/java/cn/nianxx/thhotel/platform/audit/domain/PlatformAdminAuditLogEntity.java`
- Create: `server/src/main/java/cn/nianxx/thhotel/platform/audit/mapper/PlatformAdminAuditLogMapper.java`
- Create: `server/src/main/java/cn/nianxx/thhotel/platform/audit/repository/PlatformAdminAuditLogRepository.java`
- Create: `server/src/main/java/cn/nianxx/thhotel/platform/audit/repository/MybatisPlatformAdminAuditLogRepository.java`
- Create: `server/src/main/java/cn/nianxx/thhotel/platform/audit/common/dto/PlatformAdminAuditLogDraft.java`
- Create: `server/src/main/java/cn/nianxx/thhotel/platform/audit/service/PlatformAdminAuditLogService.java`
- Create: `server/src/main/java/cn/nianxx/thhotel/platform/audit/service/impl/PlatformAdminAuditLogServiceImpl.java`
- Test: audit migration/repository/service tests.

**Interfaces:**
- Produces: `record(PlatformAdminAuditLogDraft draft)` for management write operations.

- [x] Add migration with utf8mb4_bin and Chinese comments.
- [x] Add Entity, Mapper, Repository, Service.
- [x] Ensure snapshots exclude password, token and secret.
- [x] Add tests for audit insert and secret-safe snapshots.
- [x] Run focused backend tests.

### Task 5: CP4-2 用户管理写操作

**Files:**
- Modify identity repository/service/control request/result classes.
- Modify access and hotel repositories for user-role and user-hotel overwrite operations.
- Test: user management controller/service tests.

**Interfaces:**
- Produces: `POST /api/admin/users`
- Produces: `PUT /api/admin/users/{userId}`
- Produces: `POST /api/admin/users/{userId}/enable`
- Produces: `POST /api/admin/users/{userId}/disable`
- Produces: `POST /api/admin/users/{userId}/password-reset`
- Produces: `PUT /api/admin/users/{userId}/roles`
- Produces: `PUT /api/admin/users/{userId}/hotels`

- [x] Implement create/edit user.
- [x] Implement enable/disable with last active super admin protection.
- [x] Revoke all ACTIVE sessions when disabling a user.
- [x] Implement password reset returning temporary password once.
- [x] Implement role overwrite and hotel overwrite with single default hotel.
- [x] Record admin audit for every write operation.
- [x] Add tests for success, 401, 403 and conflict paths.

### Task 6: CP4-3 角色权限写操作

**Files:**
- Modify access repository/service/control request/result classes.
- Test: role management controller/service tests.

**Interfaces:**
- Produces: `POST /api/admin/roles`
- Produces: `PUT /api/admin/roles/{roleId}`
- Produces: `POST /api/admin/roles/{roleId}/enable`
- Produces: `POST /api/admin/roles/{roleId}/disable`
- Produces: `PUT /api/admin/roles/{roleId}/permissions`

- [x] Implement custom role create/edit/status changes.
- [x] Reject edits to built-in role permissions.
- [x] Implement permission overwrite for custom roles.
- [x] Record admin audit for every write operation.
- [x] Add tests for built-in role rejection and custom role updates.

### Task 7: CP4-4 菜单和酒店写操作

**Files:**
- Modify navigation repository/service/control request/result classes.
- Modify hotel repository/service/control request/result classes.
- Test: menu and hotel management controller/service tests.

**Interfaces:**
- Produces: `POST /api/admin/menus`
- Produces: `PUT /api/admin/menus/{menuId}`
- Produces: `PUT /api/admin/menus/sort-order`
- Produces: `GET /api/admin/menu-route-options`
- Produces: `POST /api/admin/hotels`
- Produces: `PUT /api/admin/hotels/{hotelId}`
- Produces: `POST /api/admin/hotels/{hotelId}/enable`
- Produces: `POST /api/admin/hotels/{hotelId}/disable`

- [x] Implement menu create/edit/sort with enabled permission validation.
- [x] Allow unknown route persistence while returning route safety hints.
- [x] Implement hotel create as DISABLED and reject hotel_id edits.
- [x] Reject enabling second ACTIVE hotel and disabling last ACTIVE hotel.
- [x] Record admin audit for every write operation.
- [x] Add tests for menu unknown route and hotel single-active constraints.

### Task 8: Full verification, docs, review and commit

**Files:**
- Modify: `docs/project/requirements/M006-system-admin-management-console-v1.md`
- Modify: front-back communication docs if API contracts change.

- [x] Update M006 document with implemented endpoints and remaining later work.
- [x] Run backend focused tests and full backend test when feasible.
- [x] Run frontend typecheck and test.
- [x] Perform code review focused on security, permissions, audit and data consistency.
- [x] Stage only M006-related files.
- [x] Commit with Chinese commit message.
