# ThinkPHP极速开发新项目

**Repository Path**: linfeng_study/min-admin

## Basic Information

- **Project Name**: ThinkPHP极速开发新项目
- **Description**: TTH 是基于 ThinkPHP6 + ThinkAdmin 开发的快速开发框架，采用简化型领域驱动设计（DDD）架构，提供开箱即用的工具类、服务类、第三方接口类，支持多端开发（后台管理、API 接口、微信生态、Uniapp 前端）。
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-06-26
- **Last Updated**: 2026-06-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TTH 快速开发框架

## 项目简介

TTH 是基于 ThinkPHP6 + ThinkAdmin 开发的快速开发框架，采用简化型领域驱动设计（DDD）架构，提供开箱即用的工具类、服务类、第三方接口类，支持多端开发（后台管理、API 接口、微信生态、Uniapp 前端）。

## 技术栈

- **后端框架**: ThinkPHP 6.0
- **后台框架**: ThinkAdmin
- **PHP 版本**: >= 8.0
- **数据库**: MySQL >= 5.7
- **缓存**: Redis >= 2.0
- **前端框架**: Uniapp (Vue 2) + uView UI

## 核心特性

### 开箱即用

- ✅ 大量工具类、服务类、第三方接口类、示例代码
- ✅ 提供控制器、服务层、数据仓库层、定时任务基类
- ✅ 已接管异常，无需担心未使用 try 导致异常弹窗的情况
- ✅ 提供多端登录中间件，自动校验并获取登录用户
- ✅ 提供接口请求防抖中间件，无需担心接口请求频率

### 架构设计

采用简化型领域驱动设计（DDD）：

```
├─ 控制器层 (Controller)     - 接收请求、参数校验、调用服务
├─ 服务层 (Service)          - 业务逻辑处理
├─ 数据仓库层 (Repository)   - 数据访问逻辑
└─ 模型层 (Model)            - 数据库映射
```

**灵活的架构调整：**

- 多应用场景下，可将 `models`、`repositories` 分入应用目录下
- 大业务场景下，可将 `repositories` 拆分为 `service`、`dao` 层
- 颗粒度尽量细到一个表对应一个数据仓库

### 后台快速开发

支持两种开发方式：

1. **ThinkAdmin 原生写法** - 传统 MVC 模式
2. **TTH Admin 组件** - 动态构建列表、表单、详情，无需编写后台页面

**支持的组件：**

- **Grid** - 数据列表组件（支持搜索、筛选、排序、操作按钮）
- **Form** - 表单组件（支持多种输入类型、验证、文件上传）
- **Show** - 详情展示组件

**支持的表单字段：**

- Text（文本）、Textarea（文本域）、Number（数字）
- Select（下拉选择）、SelectInfo（联动选择）、Checkbox（复选框）
- Date（日期）、Switch（开关）
- Image（图片）、MultipleImage（多图）、Editor（富文本）
- Hidden（隐藏域）

### 多渠道支付

已集成支付渠道：

- ✅ 微信支付（V2/V3）
- ✅ 支付宝
- ✅ 汇付（MotionPay）
- ✅ 杉德（SandPay）
- ✅ Adapay
- ✅ 通联支付（AllinPay）
- ✅ 余额支付
- ✅ 优惠券支付

**支付接口统一：**

```php
interface PayInterface {
    public function create($orderId, $payPrice, $successAction, $subject, $options);
    public function refund($outTradeNo, $options);
    public function query($orderId, $options);
    public function merchantPay($openid, $orderId, $amount, $options);
    public function handleNotify();
}
```

扩展简单，仅需继承支付接口，编写支付类，就可直接调用。

### 多应用登录凭证

- ✅ 临期凭证自动续期，在请求结果中返回新凭证
- ✅ 可创建多应用凭证，实现账号多端同时登录
- ✅ 支持 JWT Token 认证

### MQTT 协议支持

基于 workerman 的 MQTT 协议实例：

- 支持 MQTT 客户端和服务器推送/订阅消息
- 支持守护进程方式运行
- 配合 EMQ X 可视化面板使用

### 多语言支持

数据库查询、API 数据返回多语言支持：

- 简体中文（zh-cn）
- 繁体中文（zh-tw）
- 英语（en-us）
- 日语（ja-jp）

**使用方式：**

- 前端通过 header 中的 `lang` 参数指定语言
- 数据库字段自动映射（如：`name` → `tw_name`、`us_name`）
- 模型继承 `LangModel`，配置 `langField()` 方法

### 自动生成代码

通过命令行快速生成 API 控制器、数据仓库、模型：

```bash
# 创建完整三层文件
php think tth:CreateApi api@demo/Test

# 创建指定层文件
php think tth:CreateApi api@demo/Test --only models-repositories

# 使用 app 目录
php think tth:CreateApi api@demo/Test --use true
```

### 定时任务

支持定时任务和异步任务：

- 定时任务配置：`config/console.php`
- 异步任务配置：`app/*/sys.php`

## 项目结构

```
├─ app                           应用目录
│  ├─ admin                      后台管理模块（ThinkAdmin）
│  │  ├─ controller              控制器
│  │  │  ├─ api                  API 接口
│  │  │  ├─ Auth.php             权限管理
│  │  │  ├─ Config.php           系统配置
│  │  │  ├─ File.php             文件管理
│  │  │  ├─ Index.php            后台首页
│  │  │  ├─ Login.php            登录管理
│  │  │  ├─ Menu.php             菜单管理
│  │  │  ├─ Module.php           模块管理
│  │  │  ├─ Oplog.php            操作日志
│  │  │  ├─ Queue.php            队列管理
│  │  │  └─ User.php             用户管理
│  │  └─ view                    视图模板
│  ├─ api                        API 接口模块
│  │  ├─ controller              控制器
│  │  │  ├─ DemoController.php   示例接口
│  │  │  ├─ LoginController.php  登录接口
│  │  │  ├─ PayController.php    支付接口
│  │  │  ├─ PublicController.php 公共接口
│  │  │  ├─ UploadController.php 上传接口
│  │  │  └─ WechatController.php 微信接口
│  │  └─ route                   路由配置
│  ├─ data                       数据模块（会员专有）
│  │  ├─ command                 定时任务
│  │  ├─ controller              控制器
│  │  ├─ model                   模型
│  │  └─ service                 服务层
│  ├─ index                      后台业务模块
│  │  ├─ command                 定时任务
│  │  ├─ controller              控制器
│  │  │  ├─ AdminDemo.php        后台组件示例
│  │  │  ├─ ConfigManage.php     配置管理
│  │  │  ├─ Demo.php             示例
│  │  │  ├─ ManageDemo.php       管理示例
│  │  │  ├─ ProjectManage.php    项目管理
│  │  │  └─ UserManage.php       用户管理
│  │  └─ view                    视图模板
│  ├─ wechat                     微信模块
│  │  ├─ command                 定时任务
│  │  ├─ controller              控制器
│  │  ├─ model                   模型
│  │  └─ service                 服务层
│  ├─ lang                       多语言配置
│  ├─ listener                   事件监听
│  ├─ models                     公共模型
│  ├─ repositories               公共数据仓库
│  └─ utils                      工具类
├─ config                        配置文件
│  ├─ app.php                    应用配置
│  ├─ cache.php                  缓存配置
│  ├─ console.php                定时任务配置
│  ├─ database.php               数据库配置
│  ├─ pay.php                    支付配置
│  └─ route.php                  路由配置
├─ tth                           TTH 核心框架
│  ├─ admin                      后台组件
│  │  ├─ form                    表单组件
│  │  ├─ grid                    列表组件
│  │  ├─ show                    详情组件
│  │  ├─ resources               资源模板
│  │  └─ support                 辅助类
│  ├─ basic                      基类
│  │  ├─ BaseCommand.php         命令行基类
│  │  ├─ BaseController.php      控制器基类
│  │  ├─ BaseRepository.php      数据仓库基类
│  │  ├─ BaseService.php         服务基类
│  │  ├─ BaseManager.php         驱动基类
│  │  └─ BaseStorage.php         驱动仓库基类
│  ├─ command                    命令行
│  │  └─ CreateApi.php           生成API文件命令
│  ├─ exceptions                 异常处理
│  │  ├─ AdminException.php      后台异常
│  │  ├─ ApiException.php        API异常
│  │  ├─ ExceptionHandle.php     异常处理器
│  │  └─ PayException.php        支付异常
│  ├─ middleware                 中间件
│  │  └─ api
│  │     ├─ AuthTokenMiddleware.php  Token认证中间件
│  │     └─ BlockerMiddleware.php    防抖中间件
│  ├─ services                   服务类
│  │  ├─ api                     第三方SDK
│  │  │  ├─ AliyunSmsServices.php    阿里云短信
│  │  │  ├─ TencentSmsServices.php   腾讯云短信
│  │  │  ├─ BaiduServices.php        百度服务
│  │  │  ├─ BankCardServices.php     银行卡服务
│  │  │  ├─ BarcodeServices.php      条码识别
│  │  │  └─ WorkWechatServices.php   企业微信
│  │  ├─ image                   图片服务
│  │  │  ├─ BarCodeServices.php      条码生成
│  │  │  ├─ ImageServices.php        图片处理
│  │  │  └─ WaterMarkServices.php    海报水印
│  │  ├─ lang                    多语言服务
│  │  ├─ mqtt                    MQTT服务
│  │  ├─ pay                     支付服务
│  │  │  ├─ extend               扩展支付渠道
│  │  │  ├─ storage              支付实现
│  │  │  ├─ BasePay.php          支付基类
│  │  │  ├─ Pay.php              支付管理
│  │  │  └─ PayInterface.php     支付接口
│  │  ├─ redis                   Redis服务
│  │  ├─ CacheServices.php       缓存服务
│  │  ├─ JwtAuthServices.php     JWT服务
│  │  ├─ SysConfigServices.php   配置服务
│  │  └─ UploadFileServices.php  文件上传服务
│  ├─ traits                     Trait
│  │  ├─ Macroable.php           动态添加方法
│  │  ├─ ModelTrait.php          模型Trait
│  │  └─ RepositoryTrait.php     数据仓库Trait
│  ├─ utils                      工具类
│  │  ├─ Address.php             位置地址
│  │  ├─ Code.php                数字编码
│  │  ├─ Hook.php                动态钩子
│  │  ├─ HttpCurl.php            HTTP请求
│  │  ├─ RsaPwd.php              RSA加解密
│  │  ├─ SendMail.php            发送邮件
│  │  ├─ SnowFlake.php           雪花算法
│  │  ├─ TokenAuth.php           短Token
│  │  ├─ ValidateHelper.php      数据验证
│  │  └─ XlsxSpread.php          导入导出
│  ├─ Json.php                   JSON响应
│  └─ Request.php                请求处理
├─ uniapp                        Uniapp 前端项目
│  ├─ api                        API接口
│  ├─ components                 组件
│  ├─ config                     配置
│  ├─ pages                      页面
│  ├─ static                     静态资源
│  └─ uni_modules                uniapp模块
├─ md                            文档目录
├─ .example.env                  环境配置示例
└─ composer.json                 Composer配置
```

## 安装指南

### 环境要求

- Nginx / Apache
- PHP >= 8.0
- MySQL >= 5.7
- Redis >= 2.0

### 安装步骤

1. **安装依赖**

```bash
composer install
```

2. **配置环境**

```bash
# 复制环境配置文件
copy .example.env .env

# 自行修改 .env 文件中数据库和Redis等配置信息
```

3. **导入数据库**

导入 `md` 目录下的 SQL 文件

4. **配置 Nginx 伪静态**

```nginx
if (!-e $request_filename) {
    rewrite ^(.*)$ /index.php$1 last;
}
```

### 访问地址

- **后台地址**: `http://www.xx.com/admin`
  - 账号: `tth888`
  - 密码: `tth888..`

- **API地址**: `http://www.xx.com/api`

- **后台表单生成器**: `http://www.xx.com/curd/index.html`

## 开发指南

### 创建 API 接口

```bash
# 创建完整三层
php think tth:CreateApi api@user/User

# 生成文件：
# - app/api/controller/user/UserController.php
# - app/repositories/user/User.php
# - app/models/user/User.php
```

### 控制器开发

```php
<?php
namespace app\api\controller;

use tth\basic\BaseController;
use app\repositories\UserRepository;

class UserController extends BaseController
{
    protected $repository;

    public function __construct(UserRepository $repository)
    {
        $this->repository = $repository;
    }

    public function index()
    {
        try {
            $list = $this->repository->selectList([]);
            return $this->success('获取成功', $list);
        } catch (\Exception $e) {
            return $this->fail($e->getMessage());
        }
    }
}
```

### 数据仓库开发

```php
<?php
namespace app\repositories;

use tth\basic\BaseRepository;
use app\models\User;

class UserRepository extends BaseRepository
{
    public function __construct(User $model)
    {
        parent::__construct($model);
    }
}
```

### 后台快速开发

```php
<?php
namespace app\index\controller;

use think\admin\Controller;
use tth\admin\Grid;
use tth\admin\Form;

class UserManage extends Controller
{
    protected $table = 'user';

    public function index()
    {
        Grid::make($this->table, function (Grid $grid) {
            $grid->column('id', 'ID')->sortable();
            $grid->column('name', '姓名');
            $grid->column('phone', '手机号');
            $grid->column('created_at', '创建时间');
            
            $grid->quickSearch('name', 'phone');
            $grid->enableDialog();
        });
    }

    public function form()
    {
        Form::make($this->table, function (Form $form) {
            $form->text('name', '姓名')->required();
            $form->text('phone', '手机号')->required();
            $form->image('avatar', '头像');
            $form->number('age', '年龄');
        });
    }
}
```

### 支付开发

```php
<?php
use tth\services\pay\Pay;

// 创建支付
$pay = Pay::wechat();
$result = $pay->create(
    $orderId,        // 订单号
    $payPrice,       // 支付金额
    $successAction,  // 回调方法
    $subject,        // 支付描述
    $options         // 其他参数
);

// 查询订单
$result = $pay->query($orderId);

// 退款
$result = $pay->refund($outTradeNo, $options);

// 转账到零钱
$result = $pay->merchantPay($openid, $orderId, $amount, $options);
```

### 多语言开发

**模型配置：**

```php
<?php
namespace app\models;

use tth\services\lang\LangModel;

class News extends LangModel
{
    public function langField()
    {
        return ['title', 'content'];
    }
}
```

**查询使用：**

```php
// 自动根据语言查询对应字段
$news = News::where(['id' => 1])->find();

// 指定语言查询
$news = News::lang('ja-jp')->where(['id' => 1])->find();
```

## 常见问题

### 无法访问 tth 命名空间

```bash
# 执行
composer dump-autoload
```
### Composer 报错

```bash
# 使用示例配置文件
copy .example.composer.json composer.json
copy .example.composer.lock composer.lock

# 删除 vendor 并重新安装
rd /s /q vendor
composer install
```

### 数据库断线重连

常驻进程（如 MQTT）可能遇到数据库断线问题：

**解决方案：**
- 开启 `config/database.php` 中的 `break_reconnect` 配置

## 开发手册

- [ThinkPHP6 开发手册](https://www.kancloud.cn/manual/thinkphp6_0/content)
- [ThinkAdmin 文档](https://thinkadmin.top)
- [TTH 后台组件文档](/tth/admin/readme.md)
- [多语言文档](/tth/services/lang/readme.md)
- [MQTT 文档](/tth/services/mqtt/readme.md)

## 许可证

- **TTH 框架**: MulanPSL2 开源协议