# manage-system

**Repository Path**: xss_code/manage-system

## Basic Information

- **Project Name**: manage-system
- **Description**: react+python
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-23
- **Last Updated**: 2026-08-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 后台管理系统（manage-system）

基于 **React + FastAPI + MySQL** 的 RBAC 后台管理系统，包含完整的用户/角色/菜单三级权限体系、多标签页导航、登录/操作日志审计。

## 功能总览

| 模块 | 说明 |
|---|---|
| 认证 | 登录 / 注册 / 修改密码 / 个人资料 / 刷新令牌（JWT 双令牌，401 自动续期） |
| 用户管理 | 分页搜索、新增/编辑（角色分配）、启用/禁用、单个/批量删除 |
| 角色管理 | 新增/编辑（菜单授权树勾选）、删除（有绑定用户时拒绝）、超级管理员通配 |
| 菜单管理 | 树形维护目录/菜单/按钮三级节点，权限码驱动按钮显隐与路由守卫 |
| 日志审计 | 登录日志（成功/失败含 IP）、操作日志（写操作自动记录操作人/参数/结果） |
| 文件管理 | 本地目录配置（日常照片 / RAW 两类）：照片浏览与 RAW 管理双页面，懒加载缩略图网格、左图右信息预览层，支持重命名 / 复制 / 裁剪（照片）/ 单个与批量删除；RAW 由服务端 rawpy(LibRaw) 解码并磁盘缓存预览（cr3/cr2/crw/nef/nrw/arw/srf/sr2/raf/dng），不支持裁剪以保持原始性 |
| 前端体验 | 顶部 bar + 左侧树形菜单 + **多标签页导航**（历史页签、点击切换、x 关闭）+ 面包屑 |

## 技术架构

```
┌───────────────────────── 前端（frontend/）─────────────────────────┐
│  React 19 + TypeScript + Vite 8                                     │
│  Ant Design v6（UI）+ React Router v7（路由）+ Zustand（状态）        │
│  ├─ api/        API 契约层（realRequest：fetch + Bearer + 信封解析）│
│  ├─ store/      认证状态 / 多标签页状态                               │
│  ├─ router/     静态路由表 + AuthGuard / PermGuard 权限守卫          │
│  ├─ layouts/    MainLayout（Header + Sider + TabsBar + Content）     │
│  └─ pages/      登录注册 / 仪表盘 / 用户 / 角色 / 菜单 / 文件(目录配置·照片浏览·RAW 管理) / 关于│
│  Vite 代理：/api → http://localhost:8000                             │
└──────────────────────────────┬──────────────────────────────────────┘
                               │ HTTP + JSON 信封 {code, message, data}
                               │ Authorization: Bearer <JWT>
┌──────────────────────────────▼──────────────────────────────────────┐
│  后端（backend/）— FastAPI + SQLAlchemy 2.0 + MySQL 8               │
│  三层架构（参考 Java）：                                             │
│  ├─ api/       Controller：HTTP 参数接收 + VO 返回（不写业务）       │
│  ├─ services/  Service：业务逻辑 + 事务边界                          │
│  ├─ dao/       DAO：实体持久化封装                                   │
│  ├─ models/    Entity：SQLAlchemy 声明式模型                         │
│  └─ schemas/   DTO（入参）/ VO（出参，camelCase 输出）               │
│  权限：RBAC 五表（sys_user/role/menu + 两张关联表）                  │
│  安全：JWT 双令牌（access 2h + refresh 7d）、bcrypt 密码哈希         │
│  逻辑删除：全表 deleted 字段 + 全局事件自动过滤（MyBatis-Plus 风格） │
│  审计：登录日志 + 操作日志（@log_operation 装饰器）                  │
│  图像：Pillow 缩略图/裁剪 + rawpy(LibRaw) RAW 解码，磁盘缓存预览     │
└──────────────────────────────┬──────────────────────────────────────┘
                               │ SQLAlchemy + PyMySQL
                        ┌──────▼──────┐
                        │ MySQL 8     │  manage_system 库（utf8mb4_unicode_ci）
                        └─────────────┘
```

**关键设计**：
- **统一权限树**：菜单与按钮在同一棵树（`sys_menu.type` = dir/menu/button），后端按角色下发，前端过滤菜单 + 路由守卫 + `<Auth>` 按钮级控制
- **双令牌**：access token 过期后前端自动用 refresh token 续期重试，用户无感
- **逻辑删除**：查询自动过滤 `deleted=0`、删除自动转 `UPDATE SET deleted=1`（全局 `do_orm_execute` 事件），软删唯一字段加后缀防冲突
- **信封契约**：所有接口返回 `{code, message, data}`，code===200 成功；错误码与 HTTP 状态一致

## 环境要求

| 依赖 | 版本 |
|---|---|
| Node.js | ≥ 20.19（Vite 8 要求 ≥20.19 或 ≥22.12） |
| Python | 3.13（项目 venv 使用 3.13） |
| MySQL | 8.x（utf8mb4，建议 utf8mb4_unicode_ci） |

## 快速开始

### 1. 初始化数据库

```bash
# 方式一：直接执行完整初始化 SQL（建库 + 建表 + 种子数据，推荐）
mysql -uroot -p < backend/sql/init.sql

# 方式二：迁移 + 种子（代码演进时用）
mysql -uroot -p -e "CREATE DATABASE IF NOT EXISTS manage_system CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
cd backend
.venv\Scripts\alembic upgrade head      # 建表（Windows；Linux/macOS: .venv/bin/alembic）
.venv\Scripts\python -m scripts.seed    # 种子数据（幂等，可重复执行）
```

> 数据库连接信息在 `backend/.env` 中配置（默认 localhost:3306 / root / 你的密码 / manage_system）。

### 2. 启动后端（:8000）

```bash
cd backend
python -m venv .venv                          # 首次
.venv\Scripts\pip install -r requirements.txt # Windows（Linux/macOS: .venv/bin/pip）
copy .env.example .env                        # 填写 DATABASE_URL 与 JWT_SECRET（生成：python -c "import secrets; print(secrets.token_urlsafe(64))"）
.venv\Scripts\uvicorn app.main:app --port 8000 --reload
```

- Swagger 接口文档：http://localhost:8000/docs
- 日志：控制台 + `backend/logs/app.log`（滚动 10MB×5）

### 3. 启动前端（:5173）

```bash
cd frontend
npm install
npm run dev
```

访问 http://localhost:5173 （前端已配置 `/api` 代理到后端 :8000，`VITE_API_MODE=real`）。

### 4. 演示账号

| 账号 | 密码 | 权限 |
|---|---|---|
| admin | admin123 | 超级管理员（全部权限，含按钮） |
| viewer | viewer123 | 只读访客（仅用户管理列表） |

## 生产部署

### 前端构建

```bash
cd frontend
npm run build        # 产物在 frontend/dist/
```

部署到 nginx（示例）：

```nginx
server {
    listen 80;
    server_name your-domain.com;
    root /path/to/frontend/dist;
    index index.html;

    # SPA 路由回退
    location / {
        try_files $uri $uri/ /index.html;
    }

    # API 反向代理到后端
    location /api/ {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

### 后端部署

```bash
cd backend
.venv\Scripts\uvicorn app.main:app --host 0.0.0.0 --port 8000   # 或 gunicorn -k uvicorn.workers.UvicornWorker app.main:app
```

生产注意：`JWT_SECRET` 使用强随机值；`CORS_ORIGINS` 配置为实际域名；数据库账号使用最小权限专用账号。

## 验证与测试

| 脚本 | 位置 | 说明 |
|---|---|---|
| 前端基础流程 | `frontend/scripts/verify-prototype.mjs` | 登录/注册/菜单过滤/按钮权限/403/404/F5（需 dev server + 无头 Chrome CDP :9222） |
| 管理页面 | `frontend/scripts/verify-admin-pages.mjs` | 菜单/用户/角色 CRUD 全流程 |
| 改密+仪表盘 | `frontend/scripts/verify-password-dashboard.mjs` | 修改密码全流程 + 真实统计 |
| 后端 RBAC | `backend/scripts/verify_rbac.py` | RBAC 接口 37 项 |
| 后端补充接口 | `backend/scripts/verify_supplement.py` | 改密/刷新/批量删除/日志 18 项 |

## 目录结构

```
manage-system/
├── frontend/          # React 前端（详见 frontend/README.md）
├── backend/           # FastAPI 后端（详见 backend/README.md）
├── docs/              # 设计文档
│   ├── 后台管理系统-需求讨论与前端原型方案.md
│   └── 后台管理系统-后端方案.md
└── manage-system.iml  # IntelliJ 项目文件
```