docs: 更新 CLAUDE.md 补充权限系统和代码生成器说明

新增内容:
- pnpm generate 代码生成命令
- 前端权限控制(PermissionGuard 组件、usePermissionStore)
- 后端权限控制(@RequirePermission 装饰器、PermissionModule)
- 代码生成器生成内容说明
- DataTable 通用组件说明

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
charilezhou
2026-01-19 20:50:23 +08:00
parent 2aa992c88d
commit e7496ed41b

View File

@@ -38,6 +38,9 @@ pnpm db:generate # 生成 Prisma Client
pnpm db:push # 推送 schema 到数据库
pnpm db:migrate # 运行迁移
cd apps/api && pnpm db:studio # 打开 Prisma Studio
# 代码生成
pnpm generate # CRUD 模块生成器(交互式,生成后端+前端+类型+种子脚本)
```
## Architecture
@@ -61,6 +64,25 @@ cd apps/api && pnpm db:studio # 打开 Prisma Studio
| 组件本地状态 | useState | 表单输入、弹窗开关 |
| URL 状态 | Next.js Router | 分页参数、筛选条件 |
**前端权限控制**:使用 `<PermissionGuard>` 组件包裹需要权限的 UI 元素:
```tsx
<PermissionGuard permission="user:create">
<CreateButton />
</PermissionGuard>
// 多个权限OR 关系)
<PermissionGuard permission={['user:update', 'user:delete']}>
<ActionMenu />
</PermissionGuard>
// 多个权限AND 关系)
<PermissionGuard permission={['user:update', 'user:delete']} mode="all">
<AdminPanel />
</PermissionGuard>
```
权限数据通过 `usePermissionStore` 管理,登录后自动缓存,退出时清除。
**数据请求分层**
```
@@ -80,9 +102,20 @@ NestJS 采用模块化架构:
- **AuthModule** - JWT 认证注册、登录、token 验证)
- **UserModule** - 用户 CRUD继承 CrudService 基类
- **CaptchaModule** - 验证码服务,支持多场景验证
- **PermissionModule** - 权限管理(角色、权限、菜单)
认证流程:使用 `@Public()` 装饰器标记公开接口,其他接口需要 JWT Bearer Token。使用 `@CurrentUser()` 装饰器获取当前登录用户信息(类型为 `AuthUser`)。
**权限控制**:使用 `@RequirePermission()` 装饰器控制接口权限,配合 `PermissionGuard` 使用:
```typescript
@UseGuards(JwtAuthGuard, PermissionGuard)
@RequirePermission('user:create')
@Post()
create(@Body() dto: CreateUserDto) { ... }
```
权限码格式:`{resource}:{action}`(如 `user:create``user:read``user:update``user:delete`
**后端导入规范:禁止使用 Barrel Imports**
后端代码禁止使用 `index.ts` 统一导出barrel exports必须直接从具体文件导入
@@ -289,3 +322,22 @@ docs/
- `packages/shared/src/types/` - 共享类型定义
- `packages/shared/src/crypto/` - 跨平台加密实现
- `apps/web/src/types/` - 前端特有类型定义
### 代码生成器
`pnpm generate` 启动交互式代码生成器,可一键生成完整 CRUD 模块:
- **后端**: Controller、Service、DTO、Module
- **前端**: Service、Hooks、Table、CreateDialog、EditDialog、Page
- **共享类型**: TypeScript 接口定义
- **Prisma Model**: 数据库模型
- **种子脚本**: 菜单和权限初始化数据
生成的代码自动集成权限控制(`@RequirePermission` + `PermissionGuard`)。详见 `plop/README.md`
### 通用组件
**DataTable** (`components/shared/DataTable/`): 封装 TanStack Table 的通用数据表格组件
- 支持服务端分页、排序、搜索
- 内置加载状态、错误状态、空状态渲染
- 使用示例见 `components/*/XxxTable.tsx`