huangting/th-hotel-simple
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
develop
th-hotel-simple/docs/superpowers/plans/2026-07-10-m006-system-admin-v1.md
andy aa5783ba61 实现系统管理后台 V1
2026-07-10 18:32:34 +08:00

10 KiB
Raw Permalink Blame History

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.

  • Add SYSTEM_ADMIN_CONSOLE_ACCESS to platform permission enum.

  • Change SYSTEM_SETTINGS menu to visible and bind SYSTEM_ADMIN_CONSOLE_ACCESS.

  • Include SYSTEM_ADMIN_CONSOLE_ACCESS in SYSTEM_ADMIN built-in permissions.

  • Create admin authorization service with 401 and 403 semantics.

  • Add tests for missing token, missing permission and successful authorization.

  • 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}

  • Add repository list/detail methods with pagination where needed.

  • Add Service interfaces and implementations for read-only admin queries.

  • Add Controller classes with Chinese method comments.

  • Enforce management permissions per endpoint.

  • Return string IDs and UTC time strings.

  • Add MockMvc tests for 401, 403 and successful list responses.

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

  • Add SYSTEM_ADMIN_CONSOLE_ACCESS to auth permission type.

  • Add /system redirect and /system/* child routes.

  • Add system menu label and known route fallback.

  • Implement API service and types.

  • Implement four read-only pages with loading, error and empty states.

  • Add frontend tests for route permission and API parameter mapping.

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

  • Add migration with utf8mb4_bin and Chinese comments.

  • Add Entity, Mapper, Repository, Service.

  • Ensure snapshots exclude password, token and secret.

  • Add tests for audit insert and secret-safe snapshots.

  • 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

  • Implement create/edit user.

  • Implement enable/disable with last active super admin protection.

  • Revoke all ACTIVE sessions when disabling a user.

  • Implement password reset returning temporary password once.

  • Implement role overwrite and hotel overwrite with single default hotel.

  • Record admin audit for every write operation.

  • 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

  • Implement custom role create/edit/status changes.

  • Reject edits to built-in role permissions.

  • Implement permission overwrite for custom roles.

  • Record admin audit for every write operation.

  • 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

  • Implement menu create/edit/sort with enabled permission validation.

  • Allow unknown route persistence while returning route safety hints.

  • Implement hotel create as DISABLED and reject hotel_id edits.

  • Reject enabling second ACTIVE hotel and disabling last ACTIVE hotel.

  • Record admin audit for every write operation.

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

  • Update M006 document with implemented endpoints and remaining later work.

  • Run backend focused tests and full backend test when feasible.

  • Run frontend typecheck and test.

  • Perform code review focused on security, permissions, audit and data consistency.

  • Stage only M006-related files.

  • Commit with Chinese commit message.