crm-backend-matt/.scratch/dynamic-api-permission-interceptor/spec.md

# Spec: 动态权限拦截 + 封遗留写路径

Status: ready-for-agent

## Problem Statement

管理员在权限资源树中配置了按钮级权限点（含 apiUrl），期望系统自动根据该配置拦截未授权的 API 请求。但当前实现存在两个问题：

1. **无运行时动态拦截**：`sys_menu` 中的 `apiUrl` 字段未被消费，鉴权全靠手动标注 `@PreAuthorize("hasAuthority('crm:xxx:yyy')")`。新增端点忘加注解就漏防。
2. **遗留写路径绕过防护**：`/api/system/menus/save` 和 `/api/system/menus/delete` 直接调用 MyBatis-Plus CRUD，无任何层级校验、子节点检查或授权清理——可从第二个入口损坏权限资源树。
3. **Mapper 泄漏进 Controller**：`assign-menus`、`roles/delete`、`users/assign-roles` 等端点在 Controller 层直接操作 Mapper，无事务保护，违反 locality 原则。

## Solution

构建基于 `apiUrl` 的动态权限拦截机制，并封堵遗留写路径漏洞：

1. **动态拦截器**：MVC 层 `HandlerInterceptor` 读取请求 URL，匹配 `sys_menu` 中 button 节点的 `apiUrl` pattern，检查当前用户是否拥有对应 perms。未注册的 URL 放行（fail-open）。
2. **封遗留端点**：删除 `/api/system/menus/save` 和 `/api/system/menus/delete`，所有资源树写操作统一走 `ResourceController`（已含层级校验、子节点检查、级联清理）。
3. **收拢 Mapper 逻辑**：将 `assign-menus`、`roles/delete`、`users/assign-roles` 的 Mapper 操作收进 Service 层，加 `@Transactional`，消除 Controller 持有 Mapper 的反模式。

## User Stories

1. As an admin, I want to register a button permission point with an apiUrl pattern (e.g., `/api/users/**`), so that all matching requests are automatically protected without manual `@PreAuthorize` annotations.
2. As an admin, I want the system to use Ant-style pattern matching (`*`, `**`) for apiUrl, so that I can flexibly define rules like `/api/users/*/detail` or `/api/orders/**`.
3. As a user with role "Sales", I want to be denied access to `/api/users/list` if my role is not authorized for the corresponding button permission point, so that I cannot bypass UI-level restrictions by calling the API directly.
4. As a user with role "Admin", I want to access endpoints that are not registered in the permission tree (e.g., `/api/system/depts/tree`), so that legacy or internal endpoints remain accessible during transition.
5. As a developer, I want disabled button nodes (`status=disabled`) to be excluded from the interception rules, so that disabling a permission point globally blocks access without modifying role assignments.
6. As an admin, I want changes to the permission resource tree (add/edit/delete button nodes) to immediately take effect on subsequent requests, so that I don't need to restart the application.
7. As an admin, I want the `/api/system/menus/save` endpoint to validate parent-child type constraints (catalog→menu→button), so that I cannot create invalid tree structures.
8. As an admin, I want the `/api/system/menus/delete` endpoint to reject deletion of nodes with children and cascade-clean role-menu references, so that I cannot leave orphaned authorizations.
9. As a developer, I want role-menu assignment (`assign-menus`) to be wrapped in a transaction, so that partial failures don't leave inconsistent authorization state.
10. As a developer, I want user-role assignment (`assign-roles`) to be wrapped in a transaction, so that partial failures don't leave inconsistent user-role relationships.
11. As a security auditor, I want all intercepted requests to log the matched apiUrl pattern and the user's permission codes, so that I can audit access control decisions.
12. As a frontend developer, I want the interceptor to return HTTP 403 with a clear error message when access is denied, so that I can display appropriate UI feedback.
13. As an admin, I want to use wildcard patterns like `/api/resources/**` to protect entire subsystems with a single rule, so that I don't need to register every individual endpoint.
14. As a developer, I want the interceptor to coexist with existing `@PreAuthorize` annotations, so that I can gradually migrate from annotation-based to URL-based authorization.
15. As a tester, I want the cache to be invalidated immediately after resource tree mutations, so that integration tests can verify fresh rules without restarting.

## Implementation Decisions

### Modules Built/Modified

- **New**: `ApiPermissionInterceptor` (HandlerInterceptor in `com.crm.auth.security`) — matches request URL against cached apiUrl patterns, checks user authority set.
- **New**: `ApiPermissionCache` (Caffeine-based in-memory cache in `com.crm.auth.security`) — stores list of `{apiUrlPattern, permsCode}` tuples for enabled button nodes.
- **Modified**: `ResourceServiceImpl` — calls `ApiPermissionCache.invalidate()` on save/delete of button nodes.
- **Modified**: `SystemController` — removes `/menus/save` and `/menus/delete` endpoints; delegates `assign-menus`, `roles/delete`, `users/assign-roles` logic to service layer.
- **Modified**: `ISysRoleService` / `SysRoleServiceImpl` — adds `assignMenus(roleId, menuIds)` with `@Transactional`; moves `deleteRole` cascade logic into service.
- **Modified**: `IAuthUserService` / `AuthUserServiceImpl` — ensures `assignRoles` is transactional (may already be).
- **Modified**: Spring MVC config — registers `ApiPermissionInterceptor` to run after JWT filter, before controllers.

### Interfaces Modified

- `ApiPermissionInterceptor.preHandle()`: reads `HttpServletRequest.getRequestURI()`, matches against cached patterns using `AntPathMatcher`, retrieves current user's authority set from `SecurityContextHolder`, denies if no match found among enabled perms.
- `ApiPermissionCache.load()`: queries `sys_menu` for `menuType=3 (BUTTON) AND status='enabled' AND apiUrl IS NOT NULL`, returns list of `{pattern, perms}`.
- `ApiPermissionCache.invalidate()`: clears cache, forces reload on next request.

### Technical Clarifications

- **Fail-open policy**: If request URL does not match any registered apiUrl pattern, the interceptor allows the request to proceed. Only explicitly registered URLs are protected.
- **Ant-style matching**: Uses Spring's `AntPathMatcher` — `*` matches zero or more characters within a path segment, `**` matches zero or more path segments. Example: `/api/users/*` matches `/api/users/123` but not `/api/users/123/detail`; `/api/users/**` matches both.
- **Authority check**: The interceptor extracts the user's authority set from `SecurityContext.getAuthentication().getAuthorities()` (populated by `PermissionGrant.asAuthorities()` in `JwtAuthenticationFilter`). It checks if any authority matches the `perms` code of the matched button node.
- **Disabled nodes excluded**: Only button nodes with `status='enabled'` generate interception rules. Disabling a node removes it from the cache on next invalidation.
- **Coexistence with @PreAuthorize**: The interceptor runs alongside Spring Security's method-level security. Endpoints with `@PreAuthorize` continue to work; the interceptor adds an additional URL-based layer. No conflict — both must pass.

### Schema Changes

No new tables or columns. Reuses existing `sys_menu` fields:
- `menuType = 3` (button)
- `status = 'enabled'` or `'disabled'`
- `apiUrl` (varchar(200), nullable) — only non-null values generate rules
- `perms` (varchar(100)) — the authority code checked by the interceptor

### API Contracts

- **Removed endpoints**:
  - `POST /api/system/menus/save` → replaced by `POST /api/resources/saveOrUpdate`
  - `POST /api/system/menus/delete` → replaced by `POST /api/resources/delete`
- **Unchanged endpoints** (now with transactional service backing):
  - `POST /api/system/roles/assign-menus` — still accepts `roleId` + `menuIds` (comma-separated), but logic moved to `ISysRoleService.assignMenus()`
  - `POST /api/system/roles/delete` — still accepts `roleId`, but cascade cleanup moved to service
  - `POST /api/system/users/assign-roles` — still accepts `userId` + `roleIds` (comma-separated), but wrapped in transaction

### Specific Interactions

1. **Request flow**:
   ```
   Request → JwtAuthenticationFilter (loads PermissionGrant into SecurityContext)
           → ApiPermissionInterceptor (matches URL, checks authority)
           → Controller (if allowed)
   ```
2. **Cache lifecycle**:
   - Startup: cache empty, first request triggers lazy load from `sys_menu`.
   - Mutation: `ResourceServiceImpl.save()` or `.delete()` calls `cache.invalidate()`.
   - Next request: cache rebuilds from DB.
3. **Pattern matching priority**: If multiple patterns match (e.g., `/api/users/*` and `/api/users/**`), the most specific match wins (Spring's `AntPathMatcher` handles this). The interceptor checks if the user has the perms of the matched rule.

## Testing Decisions

### What Makes a Good Test

- Tests external behavior: does the interceptor allow/deny the right requests?
- Does not test implementation details: no assertions about cache internals, SQL queries, or matcher algorithms.
- One assertion per test case: clear pass/fail signal.

### Modules Tested

- **ApiPermissionInterceptor** (new):
  - Matched URL + user has perms → 200 OK
  - Matched URL + user lacks perms → 403 Forbidden
  - Unmatched URL → 200 OK (fail-open)
  - Ant-style wildcard matching (`*`, `**`)
  - Disabled button nodes do not generate rules
  - Multiple matching patterns → most specific wins
- **ResourceServiceImpl** (modified):
  - Save/delete triggers cache invalidation
- **SysRoleServiceImpl** (modified):
  - `assignMenus` is transactional (partial failure rolls back)
  - `deleteRole` cascade-cleans `sys_role_menu`
- **Regression**: Existing `DataScopeIntegrationTest` suite passes unchanged.

### Prior Art

- `DataScopeIntegrationTest` — H2 in-memory DB, real mappers, asserts visible rows. New interceptor tests follow same pattern: H2 seed data with button nodes, simulate requests via MockMvc or direct interceptor invocation, assert HTTP status.
- `ResourceServiceImplTest` — unit tests for validation logic. New cache invalidation tests extend this suite.

## Out of Scope

- **Performance optimization**: No Redis caching, no batch query merging. Caffeine process-local cache is sufficient for single-instance deployment.
- **URL pattern UI editor**: Admins register apiUrl via existing `ResourceController` (JSON body or form params). No dedicated UI for pattern management.
- **Audit logging**: Interceptor does not log matched patterns or decisions. Logging can be added later if needed.
- **Rate limiting / throttling**: Not part of this spec.
- **IP-based or time-based access control**: Only role-based permission codes are checked.
- **Migration of existing @PreAuthorize annotations**: Existing annotated endpoints continue to work. Gradual migration is out of scope.

## Further Notes

- **ADR conflict**: This spec contradicts ADR-0011's decision to "retain `/menus/save` and `/delete` for backward compatibility." The rationale for reopening: backward compatibility became a security vulnerability — unvalidated writes can corrupt the permission tree. The new dynamic interception mechanism makes the legacy endpoints redundant (all protected endpoints can now be registered via apiUrl).
- **Transition strategy**: During rollout, admins should register critical endpoints in the permission tree before removing manual `@PreAuthorize` annotations. The fail-open policy ensures no accidental lockouts.
- **Testing seam**: The highest seam is the `HandlerInterceptor` itself — tests invoke it with mocked HttpServletRequest/Response and SecurityContext. No need to spin up full HTTP server for unit tests; integration tests can use Spring Boot's `@SpringBootTest` + `MockMvc`.