207 lines
10 KiB
Markdown
207 lines
10 KiB
Markdown
# 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.
|