admin-projects/README.md

# 知习 Admin

企业知识管理中台 — 后台管理系统前端。

## 技术栈

- React 19 + TypeScript 6
- Vite 8
- Ant Design 5 + @ant-design/pro-components 2.8
- @tanstack/react-query 5
- ECharts 5 + echarts-for-react 3
- dayjs
- react-router-dom v7

## 项目结构

```
src/
├── components/          # 共享组件
│   ├── AuditLogTable    # 审计日志 ProTable
│   ├── ConfirmDangerModal # 高危操作确认弹窗
│   ├── DetailDrawer     # 侧滑详情抽屉
│   ├── EChartsChartContainer # 图表容器
│   ├── EmptyState       # 空状态占位
│   ├── MetricCard       # 指标卡
│   ├── StatusTag        # 状态标签
│   ├── AuthGuard        # 登录鉴权守卫
│   ├── PageLoading      # 路由懒加载 Spin
│   └── PermissionGuard  # 角色权限守卫
├── config/
│   └── menu.tsx         # 菜单树与角色过滤
├── constants/
│   └── roles.ts         # 角色标签/颜色/层级
├── contexts/
│   └── AuthContext.tsx   # 认证上下文
├── hooks/
│   └── use-auth-query.ts # React Query 认证 hooks
├── layouts/
│   └── AdminLayout.tsx  # 管理后台布局（侧边栏/顶栏/面包屑）
├── pages/
│   ├── Dashboard        # 数据看板（指标卡 + 图表 + 审计日志）
│   ├── UserManagement   # 管理员 CRUD
│   ├── Login            # 登录页
│   ├── Placeholder      # 占位页
│   ├── 403/404/500      # 错误页
├── routes/
│   └── index.tsx        # 路由配置（懒加载 + 角色要求）
├── services/
│   ├── admin-api.ts     # 类型化 API 函数
│   ├── http-client.ts   # Fetch 封装（401 自动刷新队列）
│   ├── token-store.ts   # Token 本地存储
│   └── mock-data.ts     # DEV 模式 Mock 数据
└── types/
    ├── admin.ts         # AdminUser, DashboardStats, AuditLog 等
    └── api.ts           # PaginatedResult, ApiError
```

## 启动

```bash
npm install
npm run dev      # 开发模式，默认 http://localhost:5173
npm run build    # 生产构建
```

## 认证流程

1. `AuthGuard` 检查登录状态，未登录跳转 `/login`
2. `PermissionGuard` 检查角色权限，不足跳转 `/403`
3. HTTP 客户端自动处理 401 → refresh token → 重试请求
4. refresh token 失败时强制退出到 `/login`

## 角色体系

| 角色 | 说明 | 权限范围 |
|------|------|---------|
| SUPER_ADMIN | 超级管理员 | 全部权限，可管理其他管理员 |
| ADMIN | 管理员 | 用户管理、仪表盘、审计日志 |
| OPERATIONS | 运营人员 | 仪表盘、审计日志（只读） |
| DEVELOPER | 开发者 | 仪表盘（只读） |
| READONLY | 只读用户 | 仪表盘（只读） |