# 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.