# 路由权限系统实施记录

## 📋 实施概览

**实施日期**: 2025-11-27
**实施状态**: ✅ 已完成
**实施内容**: 基于路由的细粒度权限管理系统

---

## 🎯 实施目标

实现以下功能：
1. 后端为每个路由返回该用户在该路由下拥有的权限列表
2. 前端构建权限映射表（路由路径 → 权限列表）
3. 权限数据在整个应用中全局共享，避免重复请求
4. 支持基于当前路由的自动权限检查
5. 支持跨路由权限查询

---

## ✅ 已完成的修改

### 1. 后端接口类型更新

**文件**: `app/api/auth/user-routes.ts`

#### 修改内容：

1. **更新 `BackendRouteInfo` 接口** (第5-19行)
   ```typescript
   export interface BackendRouteInfo {
     // ... 现有字段
     permissions?: string[];  // ✅ 新增：该路由下用户拥有的权限列表
     children?: BackendRouteInfo[];
   }
   ```

2. **更新 `MenuItem` 接口** (第56-66行)
   ```typescript
   export interface MenuItem {
     // ... 现有字段
     permissions?: string[];  // ✅ 新增：该菜单项的权限列表
     children?: MenuItem[];
   }
   ```

3. **新增权限映射相关类型和工具函数** (第489-542行)
   - `PermissionMap` 类型定义
   - `buildPermissionMap()` - 从路由树提取权限映射表
   - `permissionMapToObject()` - 将Map转换为普通对象
   - `objectToPermissionMap()` - 从对象恢复Map

4. **更新 `getUserRoutesByRole` 返回类型** (第551-561行)
   ```typescript
   Promise<{
     success: boolean;
     data?: MenuItem[];
     permissionMap?: Record<string, string[]>;  // ✅ 新增
     error?: string;
     shouldRedirectToHome?: boolean
   }>
   ```

5. **构建并返回权限映射表** (第668-682行)
   ```typescript
   const permissionMapObj = permissionMapToObject(buildPermissionMap(routes));
   return {
     success: true,
     data: menuItems,
     permissionMap: permissionMapObj  // ✅ 返回权限映射表
   };
   ```

6. **路由转换时传递权限** (第872-880行)
   ```typescript
   const menuItem: MenuItem = {
     // ... 其他字段
     permissions: route.permissions  // ✅ 传递权限列表
   };
   ```

---

### 2. Root Loader 更新

**文件**: `app/root.tsx`

#### 修改内容：

1. **声明权限映射表变量** (第128行)
   ```typescript
   let permissionMap: Record<string, string[]> = {};
   ```

2. **保存权限映射表** (第171-175行)
   ```typescript
   if (routesResult.permissionMap) {
     permissionMap = routesResult.permissionMap;
   }
   ```

3. **返回权限映射表给客户端** (第251行)
   ```typescript
   return Response.json({
     userRole,
     pathname,
     frontendJWT,
     isPublicPath,
     permissionMap,  // ✅ 传递权限映射表
     ENV: { }
   });
   ```

---

### 3. usePermission Hook 更新

**文件**: `app/hooks/usePermission.tsx`

#### 修改内容：

1. **导入 useLocation** (第25行)
   ```typescript
   import { useRouteLoaderData, useLocation } from "@remix-run/react";
   ```

2. **更新接口定义** (第27-36行)
   ```typescript
   interface RootLoaderData {
     permissions?: string[];
     permissionMap?: Record<string, string[]>;  // ✅ 新增
     userRole: string;
     userInfo?: { /* ... */ };
   }
   ```

3. **获取当前路由权限** (第38-51行)
   ```typescript
   const location = useLocation();
   const permissionMap = rootData?.permissionMap || {};
   const currentPath = location.pathname;
   const currentPermissions = permissionMap[currentPath] || [];
   const legacyPermissions = rootData?.permissions || [];
   ```

4. **更新权限检查逻辑** (第58-81行)
   ```typescript
   const hasPermission = (permissionKey: string): boolean => {
     // 优先使用当前路由的权限列表
     if (currentPermissions.length > 0) {
       return currentPermissions.includes(permissionKey);
     }
     // 向后兼容：支持旧的permissions数组
     if (legacyPermissions.length > 0) {
       return legacyPermissions.includes(permissionKey);
     }
     // 降级方案...
   };
   ```

5. **新增路由权限查询方法** (第83-109行)
   - `hasRoutePermission(path, permissionKey)` - 检查指定路由的权限
   - `getCurrentPermissions()` - 获取当前路由的所有权限
   - `getRoutePermissions(path)` - 获取指定路由的所有权限

6. **更新返回对象** (第184-209行)
   ```typescript
   return {
     permissions: currentPermissions,  // ✅ 返回当前路由的权限
     permissionMap,  // ✅ 返回完整的权限映射表
     // ...
     hasRoutePermission,  // ✅ 新增
     getCurrentPermissions,  // ✅ 新增
     getRoutePermissions,  // ✅ 新增
     // ...
   };
   ```

---

## 📖 使用示例

### 1. 基本用法：当前路由权限检查

```typescript
// app/routes/prompts._index.tsx
import { usePermission } from "~/hooks/usePermission";

export default function PromptsIndex() {
  const {
    canCreate,
    canUpdate,
    canDelete,
    getCurrentPermissions
  } = usePermission();

  // 调试：查看当前路由权限
  useEffect(() => {
    console.log('当前路由权限:', getCurrentPermissions());
    // 输出: ["prompt_template:list:read", "prompt_template:delete:delete"]
  }, []);

  const canCreateTemplate = canCreate('prompt_template');
  const canEditTemplate = canUpdate('prompt_template');
  const canDeleteTemplate = canDelete('prompt_template');

  return (
    <div>
      {/* 根据权限显示/隐藏按钮 */}
      {canCreateTemplate && <Button>新增模板</Button>}
      {canEditTemplate && <Button>编辑</Button>}
      {canDeleteTemplate && <Button>删除</Button>}
    </div>
  );
}
```

### 2. 跨路由权限检查

```typescript
import { usePermission } from "~/hooks/usePermission";

export default function Dashboard() {
  const { hasRoutePermission, getRoutePermissions } = usePermission();

  // 检查其他路由的权限
  const canAccessPrompts = hasRoutePermission(
    '/prompts',
    'prompt_template:list:read'
  );

  const documentPermissions = getRoutePermissions('/documents');

  return (
    <div>
      {canAccessPrompts && (
        <Link to="/prompts">前往提示词管理</Link>
      )}
      <p>文档权限: {documentPermissions.join(', ')}</p>
    </div>
  );
}
```

### 3. 查看完整权限映射表（调试）

```typescript
import { usePermission } from "~/hooks/usePermission";

export default function DebugPage() {
  const { permissionMap } = usePermission();

  return (
    <pre>
      {JSON.stringify(permissionMap, null, 2)}
    </pre>
  );
}

// 输出示例:
// {
//   "/prompts": [
//     "prompt_template:list:read",
//     "prompt_template:delete:delete"
//   ],
//   "/documents": [
//     "document:list:read",
//     "document:create:write",
//     ...
//   ]
// }
```

---

## 🔧 后端集成要求

### API 返回格式要求

后端 `/rbac/user/routes` 接口需要在每个路由对象中添加 `permissions` 字段：

```json
{
  "code": 0,
  "msg": "成功",
  "data": {
    "user_id": 123,
    "username": "张三",
    "routes": [
      {
        "id": 10,
        "route_path": "/prompts",
        "route_name": "prompts",
        "route_title": "提示词管理",
        "icon": "ri-chat-1-line",
        "parent_id": 5,
        "sort_order": 3,
        "is_hidden": false,
        "permissions": [
          "prompt_template:list:read",
          "prompt_template:detail:read",
          "prompt_template:delete:delete"
        ]
      }
    ]
  }
}
```

### 权限键命名规范

格式：`module:resource:action`

**示例**：
- `prompt_template:list:read` - 查看提示词列表
- `prompt_template:create:write` - 创建提示词
- `prompt_template:update:write` - 更新提示词
- `prompt_template:delete:delete` - 删除提示词
- `prompt_template:detail:read` - 查看提示词详情

---

## 📊 数据流程

### 完整的数据流

```
1. 用户访问任意路由 (如 /prompts)
   ↓
2. root.tsx loader 执行
   ↓
3. 调用 getUserRoutesByRole(userRole, jwt, true)
   ↓
4. 后端返回路由树（包含每个路由的 permissions 字段）
   ↓
5. 前端执行 buildPermissionMap(routes)
   - 递归遍历路由树
   - 提取每个路由的 route_path 和 permissions
   - 构建 Map<string, string[]>
   ↓
6. 转换为普通对象 permissionMapToObject(map)
   ↓
7. 返回给客户端 Response.json({ permissionMap })
   ↓
8. 数据存储在 Remix 的全局状态
   ↓
9. 组件使用 usePermission() hook
   - useRouteLoaderData("root") 获取 permissionMap
   - useLocation() 获取当前路径
   - 从 permissionMap[currentPath] 获取当前路由权限
   ↓
10. 权限检查：hasPermission('prompt_template:create:write')
```

### 权限映射表构建示例

**输入（后端返回的路由树）**：
```typescript
[
  {
    id: 1,
    route_path: "/prompts",
    permissions: ["prompt_template:list:read", "prompt_template:delete:delete"],
    children: []
  },
  {
    id: 2,
    route_path: "/documents",
    permissions: ["document:list:read", "document:create:write"],
    children: []
  }
]
```

**输出（权限映射表）**：
```typescript
{
  "/prompts": ["prompt_template:list:read", "prompt_template:delete:delete"],
  "/documents": ["document:list:read", "document:create:write"]
}
```

---

## 🔍 调试指南

### 1. 检查后端返回的数据

在浏览器控制台：
```javascript
// 查看 root loader 返回的数据
window.__remixContext.state.loaderData.root

// 查看权限映射表
window.__remixContext.state.loaderData.root.permissionMap
```

### 2. 检查当前路由权限

在组件中：
```typescript
const { getCurrentPermissions } = usePermission();

useEffect(() => {
  console.log('当前路由:', location.pathname);
  console.log('当前权限:', getCurrentPermissions());
}, [location.pathname]);
```

### 3. 检查权限检查逻辑

```typescript
const { hasPermission } = usePermission();

const result = hasPermission('prompt_template:create:write');
console.log('权限检查结果:', result);
```

### 4. 开发模式日志

添加调试日志（仅在开发环境）：
```typescript
useEffect(() => {
  if (process.env.NODE_ENV === 'development') {
    console.group('🔐 权限调试信息');
    console.log('当前路由:', location.pathname);
    console.log('当前权限:', getCurrentPermissions());
    console.log('完整映射表:', permissionMap);
    console.groupEnd();
  }
}, [location.pathname]);
```

---

## ⚠️ 重要注意事项

### 1. 前端权限检查 ≠ 安全防护

- **前端权限检查仅用于UI控制**（隐藏/禁用按钮）
- **真正的权限验证必须在后端进行**
- 攻击者可以绕过前端检查直接调用API
- 永远不要依赖前端权限检查来保护敏感数据

### 2. 动态路由的权限处理

当前实现使用精确路径匹配 (`permissionMap[pathname]`)，对于动态路由需要特殊处理：

**问题场景**：
```
当前路由: /documents/123
权限映射表: { "/documents": [...] }
结果: permissionMap["/documents/123"] 返回 undefined
```

**解决方案**：

**方案1**: 使用父路由权限
```typescript
const { getRoutePermissions } = usePermission();
const permissions = getRoutePermissions('/documents');
```

**方案2**: 增强匹配逻辑（在 usePermission 中）
```typescript
const findMatchingRoute = (pathname: string): string[] => {
  // 精确匹配
  if (permissionMap[pathname]) {
    return permissionMap[pathname];
  }

  // 前缀匹配（找最长匹配）
  const matchingRoutes = Object.keys(permissionMap)
    .filter(route => pathname.startsWith(route))
    .sort((a, b) => b.length - a.length);

  return matchingRoutes.length > 0
    ? permissionMap[matchingRoutes[0]]
    : [];
};
```

### 3. 性能考虑

- 权限映射表在 root loader 中加载**一次**
- 在 SPA 导航过程中不会重新加载
- 内存占用极小（通常 < 10KB）
- 无需额外的性能优化

### 4. 降级策略

系统实现了多级降级，确保健壮性：

1. **优先级1**: 当前路由权限（permissionMap[currentPath]）
2. **优先级2**: 旧的 permissions 数组（向后兼容）
3. **优先级3**: 基于 userRole 的角色判断
4. **优先级4**: 默认查看权限（:read）

---

## 📈 后续优化建议

### 1. Session 缓存（可选）

减少 root loader 执行频率：

```typescript
// app/root.tsx
const cachedPermissions = session.get("permissionMap");
const cacheTimestamp = session.get("permissionMapTimestamp");
const CACHE_TTL = 5 * 60 * 1000; // 5分钟

if (cachedPermissions && (Date.now() - cacheTimestamp < CACHE_TTL)) {
  return Response.json({ permissionMap: cachedPermissions });
}
```

### 2. LocalStorage 备份（可选）

提高离线体验：

```typescript
// app/hooks/usePermission.tsx
useEffect(() => {
  if (rootData?.permissionMap) {
    localStorage.setItem('permissionMap', JSON.stringify(rootData.permissionMap));
  }
}, [rootData?.permissionMap]);
```

### 3. 权限变更实时通知

使用 WebSocket 推送权限变更：

```typescript
// 当管理员修改用户权限时
socket.emit('permission-changed', { userId });

// 客户端监听
socket.on('permission-changed', () => {
  window.location.reload(); // 重新加载权限
});
```

---

## ✅ 测试清单

实施完成后，请验证以下项目：

- [ ] 后端 `/rbac/user/routes` 接口已添加 `permissions` 字段
- [ ] 用户登录后，root loader 成功获取权限映射表
- [ ] 在浏览器控制台可以查看 `permissionMap` 数据
- [ ] `/prompts` 页面根据权限正确显示/隐藏按钮
- [ ] `canCreate()`, `canUpdate()`, `canDelete()` 方法正常工作
- [ ] 跨路由权限检查 `hasRoutePermission()` 正常工作
- [ ] `getCurrentPermissions()` 返回正确的权限列表
- [ ] 权限变更后刷新页面可以看到更新
- [ ] 降级策略正常（后端未返回 permissions 时系统仍能运行）
- [ ] TypeScript 类型检查通过，无类型错误
- [ ] 不同角色用户看到的按钮不同
- [ ] 后端 API 正确验证权限（403 错误）

---

## 📚 相关文档

1. [基于路由的权限管理方案](./基于路由的权限管理方案.md) - 详细设计方案
2. [权限系统原理详解](./权限系统原理详解.md) - 技术原理说明
3. [权限控制实施指南](./权限控制实施指南.md) - 通用RBAC实施指南

---

## 📝 变更历史

| 日期 | 版本 | 修改内容 | 修改人 |
|------|------|---------|--------|
| 2025-11-27 | 1.0.0 | 初始实施完成 | Claude Code |

---

**文档版本**: 1.0.0
**最后更新**: 2025-11-27
**状态**: ✅ 实施完成，待后端集成测试