# 通用框架

**Repository Path**: dreamcz/tdadmin

## Basic Information

- **Project Name**: 通用框架
- **Description**: No description available
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-07-20
- **Last Updated**: 2026-09-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# ThinkDream 企业级后台管理系统

<div align="center">

**基于 Laravel 13 API + React 19 SPA 的现代化企业级后台管理系统**

[![PHP](https://img.shields.io/badge/PHP-8.3+-777BB4?logo=php&logoColor=white)](https://www.php.net/)
[![Laravel](https://img.shields.io/badge/Laravel-13.x-FF2D20?logo=laravel&logoColor=white)](https://laravel.com/)
[![React](https://img.shields.io/badge/React-19.x-61DAFB?logo=react&logoColor=black)](https://react.dev/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Vite](https://img.shields.io/badge/Vite-8.x-646CFF?logo=vite&logoColor=white)](https://vitejs.dev/)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-14+-4169E1?logo=postgresql&logoColor=white)](https://www.postgresql.org/)
[![Redis](https://img.shields.io/badge/Redis-7+-FF4438?logo=redis&logoColor=white)](https://redis.io/)
[![MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

</div>

---

## 项目简介

ThinkDream 是一款功能完善、架构清晰的企业级后台管理系统，采用前后端分离架构设计。项目基于 Laravel 13 构建高性能 API 服务，配合 React 19 SPA 实现现代化用户体验，为中大型管理系统提供坚实的技术基础。

**后端核心能力**：
- 基于 Laravel 13.x 框架，提供高性能 API 和复杂业务逻辑处理
- 集成 JWT 无状态认证，支持"记住我"长效 Token 方案
- 实现 RBAC 三级权限控制（菜单、按钮、API）
- 自研数据权限隔离方案，按组织/部门/岗位维度自动过滤查询
- 内置完善的缓存治理体系，避免缓存脏数据

**前端核心能力**：
- React 19.x + TypeScript + Vite 构建，类型安全且性能优异
- Tailwind CSS 4 + shadcn/ui 组件体系，界面美观可定制
- 动态路由由后端菜单树驱动，前端 SPA 独立部署
- 响应式设计，支持多终端适配

---

## 核心特性

### 架构与开发体验

- **前后端分离**：Laravel 纯 API + React SPA，前后端独立构建部署
- **自动化 API 文档**：集成 Scramble，访问 `/docs/api` 查看实时 OpenAPI 文档
- **类型安全**：前端全面 TypeScript，后端 PHP 8.3 强类型
- **热更新开发**：Vite HMR + Laravel 开发服务器，一键并行启动

### 安全与权限

- **三级权限控制**：菜单、按钮、API 三级权限，基于 RBAC 模型
- **数据权限隔离**：按组织/部门/岗位维度自动注入查询过滤
- **JWT 无状态认证**：Token 本体存 Redis，Cookie 仅存 token_id
- **登录安全**：限流、图形验证码、邮件验证码保护
- **密码安全**：bcrypt 12 轮哈希，支持强制重置

### 业务能力

- **组织架构**：公司（多类型树形）、部门（树形拖拽）、岗位（独立体系）
- **系统管理**：用户、角色、菜单、字典、配置、文件管理
- **行政区划**：全国 5 级行政区数据，含拼音与坐标
- **文件管理**：单文件上传、Range 206 流式下载、图片缩略图

### 性能与治理

- **双库 Redis 隔离**：db0 会话/验证码/限流，db1 业务缓存
- **缓存治理**：`CacheManager` 统一 Key 模板与表变更自动失效
- **队列系统**：Database 驱动，独立 Job 表

---

## 技术栈

### 后端技术

| 技术 | 版本 | 说明 |
|------|------|------|
| **PHP** | ≥ 8.3 | 运行时语言，强类型支持 |
| **Laravel** | ^13.8 | 后端核心框架 |
| **tymon/jwt-auth** | ^2.3 | JWT API 认证 |
| **dedoc/scramble** | ^0.13 | API 文档自动生成 |
| **PHPUnit** | ^12.5 | 单元测试 |

### 前端技术

| 技术 | 版本 | 说明 |
|------|------|------|
| **React** | ^19.2 | UI 框架 |
| **TypeScript** | ^6.0 | 类型安全开发 |
| **Vite** | ^8.1 | 构建工具 |
| **Tailwind CSS** | ^4.3 | 原子化 CSS |
| **react-router-dom** | ^7.18 | 前端路由 |
| **shadcn/ui** | — | 组件体系 |

### 基础设施

| 技术 | 版本 | 用途 |
|------|------|------|
| **PostgreSQL** | ≥ 14 | 主数据库 |
| **Redis** | ≥ 7 | 会话与缓存 |
| **Composer** | ≥ 2.x | PHP 依赖管理 |
| **pnpm** | ≥ 9.x | Node 包管理器 |

---

## 项目结构

```
tdadmin/
├── Backend-Admin-PHP/              # Laravel 后端项目
│   ├── app/
│   │   ├── Console/Commands/       # Artisan 命令
│   │   ├── Events/                 # 事件类
│   │   ├── Http/
│   │   │   ├── Controllers/        # 控制器
│   │   │   │   ├── Admin/          # 后台管理控制器
│   │   │   │   └── Api/            # 公共 API 控制器
│   │   │   ├── Helpers/            # 辅助函数
│   │   │   ├── Middleware/         # 中间件
│   │   │   └── Requests/           # 表单请求验证
│   │   ├── Jobs/                   # 队列任务
│   │   ├── Listeners/              # 事件监听器
│   │   ├── Models/                 # Eloquent 模型
│   │   ├── Services/               # 业务逻辑层
│   │   └── Support/                # 支撑类
│   ├── config/                     # 配置文件
│   ├── database/
│   │   ├── migrations/             # 数据库迁移
│   │   ├── seeders/                # 数据填充
│   │   └── data-source/            # 地区数据源
│   ├── routes/                     # 路由定义
│   ├── tests/                      # 测试用例
│   └── bootstrap/                  # 引导程序
│
├── Backend-Admin-Web/              # React 前端项目
│   ├── src/
│   │   ├── components/             # 通用组件
│   │   ├── views/                  # 页面视图
│   │   ├── layouts/                # 布局组件
│   │   ├── lib/                    # 工具函数
│   │   ├── types/                  # 类型定义
│   │   └── hooks/                  # 自定义 Hooks
│   ├── public/                     # 静态资源
│   └── config/                     # 配置文件
│
├── docs/                           # 项目文档
├── .kimi-code/                     # AI 辅助开发配置
└── README.md                       # 项目说明
```

---

## 核心模块说明

### 认证与安全模块

认证系统集成 `tymon/jwt-auth` 实现无状态 Token 方案：
- **Token 存储**：Token 本体存 Redis，Cookie 仅存 token_id
- **Token 策略**：普通 Token 480 分钟，"记住我" Token 10080 分钟
- **安全保护**：登录限流、图形验证码、密码 bcrypt 12 轮哈希

### 组织架构模块

- **公司管理**：支持集团、项目、党委等多类型组织，树形结构
- **部门管理**：树形层级结构，支持拖拽排序
- **岗位管理**：独立岗位体系，配置数据范围规则

### 权限管理模块

- **RBAC 模型**：用户 → 角色 → 菜单/权限
- **动态菜单**：后端驱动前端路由与权限收敛
- **数据权限**：与岗位联动，实现行级数据隔离

### 数据权限服务

核心服务 `DataScopeService` 在查询构建阶段自动注入过滤条件：
- 全部数据（超管）
- 本公司及以下
- 本部门及以下
- 仅本人

### 缓存治理模块

`CacheManager` 组件提供：
- 注册表驱动，统一 Key 模板命名
- 业务缓存与运行时缓存分层
- 表变更自动失效协议

### 文件管理模块

- **上传**：单文件最大 50MB
- **播放**：Range 206 响应，支持视频和 PDF 预览
- **缩略图**：图片自动生成缩略图
- **存储**：默认 local 驱动，可扩展 OSS/S3

### 队列系统

- **驱动**：Database 队列驱动
- **独立表**：`td_sys_job`、`td_sys_job_batch`、`td_sys_job_failed`
- **用途**：异步邮件、数据导入、缓存预热等

---

## 环境要求

| 依赖 | 最低版本 | 推荐版本 |
|------|----------|----------|
| PHP | 8.3 | 8.3+ |
| Composer | 2.0 | 2.x |
| Node.js | 20.0 | 20 LTS / 22 |
| pnpm | 9.0 | 9.x |
| PostgreSQL | 14 | 16 / 17 |
| Redis | 7.0 | 7.x |

**PHP 扩展**：`pdo_pgsql`、`redis`、`mbstring`、`openssl`、`tokenizer`、`xml`、`ctype`、`json`、`bcmath`

---

## 快速开始

### 1. 克隆项目

```bash
git clone https://gitee.com/dreamcz/tdadmin.git
cd tdadmin
```

### 2. 后端安装

```bash
cd Backend-Admin-PHP

# 安装 PHP 依赖
composer install

# 复制环境配置
cp .env.example .env

# 生成应用密钥
php artisan key:generate

# 生成 JWT 密钥
php artisan jwt:secret
```

### 3. 配置数据库与 Redis

编辑 `.env` 文件：

```env
# PostgreSQL
DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=thinkadmin
DB_SCHEMA=thinkadmin
DB_USERNAME=your_username
DB_PASSWORD=your_password

# Redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_DB=0
REDIS_CACHE_DB=1
CACHE_STORE=redis
```

### 4. 数据库初始化

```bash
# 创建数据表并填充基础数据
php artisan migrate --seed

# 导入全国行政区划数据
php artisan region:restore
```

### 5. 前端安装

```bash
cd ../Backend-Admin-Web
pnpm install
```

### 6. 启动开发环境

**一键启动（推荐）**：

```bash
cd Backend-Admin-PHP
composer dev
```

**分别启动**：

```bash
# 终端 1：后端
cd Backend-Admin-PHP
php artisan serve

# 终端 2：前端
cd Backend-Admin-Web
pnpm dev
```

### 7. 访问系统

- **管理后台**：http://localhost:8000/admin
- **API 文档**：http://localhost:8000/docs/api
- **前端开发服务器**：http://localhost:5173

---

## 配置说明

### 核心环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `APP_ENV` | 运行环境 | local |
| `DB_SCHEMA` | PostgreSQL Schema | thinkadmin |
| `REDIS_CACHE_DB` | 缓存 Redis 库号 | 1 |
| `JWT_TTL` | Token 有效期（分钟） | 480 |
| `JWT_TTL_REMEMBER` | 记住我 Token（分钟） | 10080 |
| `QUEUE_CONNECTION` | 队列驱动 | database |

### JWT 配置说明

项目采用 **Redis 存储 JWT + Cookie 存储 token_id** 方案：

1. 用户登录后，生成 JWT 存入 Redis（Key: `jwt:token:{token_id}`）
2. 响应设置 HttpOnly Cookie `token_id`，有效期与 Token TTL 一致
3. 后续请求携带 Cookie，中间件从 Redis 取出 JWT 验证
4. 登出时删除 Redis 中的 Token，实现即时失效

---

## 数据库约定

### 命名规范

- **表前缀**：统一使用 `td_`
- **系统表**：`td_sys_*`（如 `td_sys_user`、`td_sys_menu`）
- **迁移文件**：`YYYY_MM_DD_HHMMSS_create_{table}_table.php`

### 初始化命令

```bash
# 创建表结构 + 填充基础数据
php artisan migrate --seed

# 导入行政区划数据
php artisan region:restore

# 重置并重新填充（危险！）
php artisan migrate:fresh --seed
```

---

## API 文档

项目集成 **Scramble** 自动生成 OpenAPI 规范文档。

- **文档地址**：`http://localhost:8000/docs/api`
- **格式**：OpenAPI 3.0
- **更新方式**：根据控制器注释自动生成

### 路由分组

| 分组 | 前缀 | 认证 | 说明 |
|------|------|------|------|
| 公共接口 | `/api/public` | 无需 | 登录、验证码等 |
| 认证接口 | `/api/auth` | JWT | 需登录的业务接口 |
| 管理接口 | `/api/admin/*` | JWT | 后台管理接口 |
| 个人中心 | `/api/my/*` | JWT | 个人账户与文件 |

---

## 开发规范

### 后端规范

遵循 Laravel 最佳实践：
- 单用途 Action 类
- 依赖注入
- 代码对接口
- 使用 `mb_*` 字符串函数
- 数据库查询使用 `whereBelongsTo`

### 前端规范

- 组件 Props 类型完整
- 使用自定义 Hooks 抽取逻辑
- 样式遵循 Tailwind CSS 规范
- 条件类名使用 `clsx`/`tailwind-merge`

### 代码质量

```bash
# 后端代码格式化
cd Backend-Admin-PHP
./vendor/bin/pint

# 后端测试
php artisan test

# 前端代码检查
cd Backend-Admin-Web
pnpm lint
```

---

## 生产部署

### 推荐架构

```
Nginx ← HTTPS ← 用户
  ↓
PHP-FPM (Laravel) / Vite Build (dist/)
  ↓
PostgreSQL + Redis + Queue Worker
```

### 部署步骤

1. **构建前端**：`pnpm build`，部署 `dist/` 到静态资源目录
2. **配置后端**：设置 `.env` 为生产环境
3. **优化加载**：`composer install --optimize-autoloader --no-dev`
4. **缓存配置**：`php artisan config:cache`、`route:cache`、`view:cache`
5. **执行迁移**：`php artisan migrate --force`
6. **启动队列**：`php artisan queue:work`（建议使用 Supervisor 守护）
7. **配置 Nginx**：指向 Laravel `public/` 目录，配置 SSL

### 计划任务

```bash
# 每分钟执行
* * * * * cd /path/to/Backend-Admin-PHP && php artisan schedule:run >> /dev/null 2>&1
```

---

## 文档索引

| 文档 | 说明 |
|------|------|
| [API接口文档约定.md](docs/API接口文档约定.md) | API 设计规范 |
| [队列Job中心建设方案.md](docs/队列Job中心建设方案-2026-08-16.md) | 异步队列架构 |
| [命名与文件组织约定.md](docs/命名与文件组织约定.md) | 命名规范 |
| [后端开发与治理规范.md](docs/后端开发与治理规范.md) | 后端开发规范 |
| [前端样式标准.md](docs/前端样式标准.md) | 前端样式规范 |
| [生产部署与安全配置指南.md](docs/生产部署与安全配置指南.md) | 部署指南 |

---

## 贡献指南

### 提交 Issue

发现 Bug 或有功能建议，请在 [Gitee Issues](https://gitee.com/dreamcz/tdadmin/issues) 提交，请包含：
- 复现步骤
- 预期行为与实际行为
- 环境信息
- 相关日志或截图

### 提交 Pull Request

1. Fork 本仓库
2. 创建特性分支：`git checkout -b feature/your-feature`
3. 提交代码：`git commit -m 'feat: 描述你的改动'`
4. 推送分支：`git push origin feature/your-feature`
5. 发起 Pull Request

### 提交信息规范

```
feat: 新增功能
fix: 修复缺陷
docs: 文档更新
style: 代码格式
refactor: 重构
perf: 性能优化
test: 测试相关
chore: 构建/工具/依赖调整
```

---

## 许可证

本项目基于 [MIT 许可证](LICENSE) 开源，可自由使用、修改和分发。

---

## 相关链接

- **项目主页**：https://gitee.com/dreamcz/tdadmin
- **问题反馈**：https://gitee.com/dreamcz/tdadmin/issues
- **API 文档**：启动后访问 `/docs/api`

---

<div align="center">

**如果这个项目对你有帮助，欢迎点个 Star ⭐ 支持一下！**

Made with ❤️ by ThinkDream Team

</div>