# TpProject

**Repository Path**: boume/tp-project

## Basic Information

- **Project Name**: TpProject
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-05
- **Last Updated**: 2026-08-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ThinkPHP 项目说明

> 基于 ThinkPHP 8 + PHP 8.2 的 Web 应用骨架，集成了自动多模块路由、统一 JSON 响应、Sodium 加密、S3 协议文件存储等常用能力。
>
> 目标读者：开发人员、AI 代码编程助手。

---

## 目录

- [环境要求](#环境要求)
- [目录结构](#目录结构)
- [安装与启动](#安装与启动)
- [核心特性](#核心特性)
- [路由规则](#路由规则)
- [配置说明](#配置说明)
- [常用命令](#常用命令)
- [注意事项](#注意事项)

---

## 环境要求

| 依赖 | 版本 |
|------|------|
| PHP | `^8.2` |
| ThinkPHP 框架 | `^8.0` |
| ThinkORM | `^3.0` 或 `^4.0` |
| 扩展 | `ext-sodium` 必须启用 |

> 加密服务 `CryptoService` 依赖 PHP Sodium 扩展，部署前请确认已安装并启用。

---

## 目录结构

```
.
├── app/
│   ├── common.php              # 全局公共函数（响应封装、跳转、Token 获取等）
│   ├── AppService.php          # 应用服务注册类
│   ├── BaseController.php      # 控制器基类（含 validate 方法）
│   ├── ExceptionHandle.php     # 全局异常处理
│   ├── Request.php             # 应用请求对象
│   ├── controller/             # 控制器目录
│   │   └── web/
│   │       └── Index.php
│   ├── extend/                 # 自定义扩展
│   │   └── filesystem/driver/
│   │       └── S3.php          # S3 协议文件系统驱动
│   ├── service/                # 业务服务层
│   │   ├── CryptoService.php   # 加密解密服务
│   │   └── UploadService.php   # 文件上传服务
│   └── view/                   # 视图模板
│       └── jump/               # 成功/失败跳转页
├── config/                     # 应用配置文件
│   ├── app.php                 # 应用基础配置
│   ├── filesystem.php          # 文件系统配置
│   ├── system.php              # 业务配置（加密、上传等）
│   └── ...
├── route/
│   └── app.php                 # 全局路由，启用自动多模块
├── database/                   # SQLite 默认数据库目录
│   └── data.db                 # SQLite 数据文件
├── public/                     # Web 入口
│   ├── index.php               # 前端入口
│   └── storage/                # public 磁盘默认存储目录
├── runtime/                    # 运行时目录
├── .env / .example.env         # 环境变量
├── composer.json
└── think                       # 命令行入口
```

---

## 安装与启动

### 1. 安装依赖

```bash
composer install
```

### 2. 复制环境变量文件

```bash
cp .example.env .env
```

按实际情况修改 `.env` 中的数据库、OSS/COS 等配置。

### 3. 启动开发服务器

```bash
php think run
```

默认访问：`http://127.0.0.1:8000`，根路径会进入默认 `web` 应用的 `Index/index`。

### 4. Web 服务器配置

生产环境请将站点根目录指向 `public/`，并确保以下目录可写：

- `runtime/`：日志、缓存、Session 等运行时文件
- `public/storage/`：`public` 磁盘默认存储目录
- `database/`：SQLite 数据文件目录（若使用 SQLite）

---

## 核心特性

### 1. 自动多模块路由

`route/app.php` 中仅配置一行：

```php
Route::auto();
```

开启后，框架会根据 URL 自动解析到 `app/controller/<应用>/<控制器>/<操作>`，无需为每个应用单独写路由。

### 2. 统一 JSON 响应函数

`app/common.php` 提供了全局响应辅助函数，统一返回格式为：

```json
{
    "code": 200,
    "message": "ok",
    "data": {},
    "time": "2026-08-15 02:55:04"
}
```

可用函数：`success()`、`fail()`、`not_login()`、`no_permission()`、`error()`。

> 函数命名遵循 ThinkPHP 方法命名规范，统一使用下划线命名法（snake_case）。

### 3. 页面跳转封装

支持 `jump_success()` / `jump_error()`，用于表单提交后的成功/失败跳转提示页。

### 4. Sodium 加密服务

`app/service/CryptoService.php` 基于 `sodium_crypto_secretbox` 提供字符串/数组的加密与解密，支持多密钥管理。

### 5. 文件上传服务

`app/service/UploadService.php` 基于 ThinkPHP 验证器校验 MIME、后缀、大小，并通过文件系统保存到指定磁盘。

### 6. S3 协议文件系统扩展

`app/extend/filesystem/driver/S3.php` 实现了 S3 协议驱动，可兼容阿里云 OSS、腾讯云 COS 等支持 S3 协议的对象存储。

---

## 路由规则

当前项目使用 **自动多模块路由**，URL 默认解析规则为：

```
http://domain/<应用>/<控制器>/<操作>
```

例如：

```
http://domain/web/index/index
```

对应：`app/controller/web/Index.php` 的 `index()` 方法。

默认模块为 `web`（见 `config/route.php` 的 `default_module`）。访问根路径 `http://domain/` 会默认进入 `app/controller/web/Index/index`。

> 不需要在 `route/app.php` 中逐条注册应用路由；若某个模块需要自定义路由，可单独创建 `route/<应用>.php`。

---

## 配置说明

### 应用配置 `config/app.php`

| 配置项 | 说明 |
|--------|------|
| `default_app` | 默认应用名，当前为 `index` |
| `with_route` | 是否启用路由，`true` |
| `default_timezone` | 默认时区，`Asia/Shanghai` |
| `app_map` / `domain_bind` / `deny_app_list` | 自动多模块模式下的映射、域名绑定、黑名单 |

### 路由配置 `config/route.php`

| 配置项 | 说明 |
|--------|------|
| `default_module` | 自动多模块模式下默认模块，当前为 `web` |
| `default_controller` | 默认控制器，当前为 `Index` |
| `default_action` | 默认操作，当前为 `index` |
| `url_route_must` | 是否强制使用路由，当前为 `false`（配合 `Route::auto()` 使用） |
| `url_html_suffix` | URL 伪静态后缀，当前为 `html` |

> `default_app`（`config/app.php`）与 `default_module`（`config/route.php`）同时存在时，URL 根路径实际由 `default_module` 决定，当前默认进入 `web` 模块。

### 数据库配置 `config/database.php`

| 配置项 | 说明 |
|--------|------|
| `default` | 默认数据库连接，当前为 `sqlite` |
| `connections.mysql` | MySQL 连接配置，通过 `.env` 读取参数 |
| `connections.sqlite` | SQLite 连接配置，数据库文件为 `database/data.db` |
| `auto_timestamp` | 自动写入时间戳，`true` |
| `datetime_format` | 时间字段输出格式，`Y-m-d H:i:s` |
| `datetime_field` | 自动维护的时间字段，`create_time,update_time` |

> 使用 MySQL 时，修改 `.env` 中的 `DB_TYPE=mysql` 并将 `database.php` 的 `default` 改为 `mysql`。

### 业务配置 `config/system.php`

| 配置项 | 说明 |
|--------|------|
| `crypto.default` | 默认密钥 ID |
| `crypto.keys.*` | 各密钥 ID 对应的 Sodium 密钥（base64 编码二进制） |
| `upload.allow_mime` | 允许上传的 MIME 类型 |
| `upload.allow_ext` | 允许上传的文件后缀 |
| `upload.max_size` | 允许上传的最大字节数，当前为 10 MB |

> ⚠️ **安全提示**：`system.php` 中的 `crypto.keys` 是示例密钥，生产环境必须替换为自行生成的随机密钥。
> 生成命令：
> ```bash
> php -r "echo base64_encode(sodium_crypto_secretbox_keygen()), PHP_EOL;"
> ```

### 文件系统配置 `config/filesystem.php`

| 磁盘 | 说明 |
|------|------|
| `local` | 本地磁盘，根目录为 `runtime/storage` |
| `public` | 本地公共磁盘，根目录为 `public/storage`，URL 前缀 `/storage` |
| `oss` | 阿里云 OSS（S3 协议），通过 `.env` 配置 |
| `cos` | 腾讯云 COS（S3 协议），通过 `.env` 配置 |

### 跨域配置 `config/cors.php`

依赖 `topthink/think-cors`，已开启全局跨域：

| 配置项 | 说明 |
|--------|------|
| `allowed_origins` | 允许的来源，当前为 `['*']` |
| `allowed_methods` | 允许的 HTTP 方法，当前为 `['*']` |
| `allowed_headers` | 允许请求头，当前为 `['*']` |
| `supports_credentials` | 是否允许携带 Cookie，当前为 `false` |

> 若需携带 Cookie 或 Authorization 等凭证，请将 `supports_credentials` 改为 `true`，并将 `allowed_origins` 改为具体域名，避免与通配符 `*` 冲突。

### Session 配置 `config/session.php`

| 配置项 | 说明 |
|--------|------|
| `type` | Session 驱动方式，`file` |
| `expire` | Session 有效期，当前为 `60 * 60 * 24` 秒（24 小时） |
| `name` | Session Cookie 名称，`PHPSESSID` |
| `prefix` | Session 键名前缀，当前为空 |

Session 已通过 `app/middleware.php` 中的 `\think\middleware\SessionInit::class` 默认开启。

### 环境变量 `.env`

参考 `.example.env` 配置基础项。常用环境变量如下：

```env
# 调试
APP_DEBUG=true

# 数据库（使用 MySQL 时配置）
DB_TYPE=mysql
DB_HOST=127.0.0.1
DB_NAME=test
DB_USER=username
DB_PASS=password
DB_PORT=3306
DB_CHARSET=utf8mb4
DB_PREFIX=

# 语言
DEFAULT_LANG=zh-cn

# 阿里云 OSS
OSS_KEY=
OSS_SECRET=
OSS_REGION=
OSS_BUCKET=
OSS_PREFIX=
OSS_ENDPOINT=
OSS_USE_PATH_STYLE_ENDPOINT=false
OSS_URL=

# 腾讯云 COS
COS_KEY=
COS_SECRET=
COS_REGION=
COS_BUCKET=
COS_PREFIX=
COS_ENDPOINT=
COS_USE_PATH_STYLE_ENDPOINT=false
COS_URL=
```

---

## 常用命令

| 命令 | 说明 |
|------|------|
| `php think run` | 启动内置开发服务器 |
| `php think service:discover` | 发现服务 |
| `php think vendor:publish` | 发布 vendor 资源 |
| `php think make:controller <应用>/<控制器>` | 生成控制器 |
| `php think make:service <服务>` | 生成服务类 |
| `php think make:validate <验证器>` | 生成验证器 |

---

## 注意事项

1. **必须启用 `ext-sodium`**，否则加密服务不可用。
2. **必须替换默认加密密钥**，请勿将 `system.php` 中的示例密钥用于生产环境。
3. 自动多模块模式下，URL 中的模块名对应 `app/controller/` 下的目录名；默认模块为 `web`。
4. 文件上传默认限制 10 MB，可在 `config/system.php` 中调整。
5. 默认数据库为 SQLite（`database/data.db`），生产环境如需 MySQL，请修改 `config/database.php` 的 `default` 及 `.env` 中的数据库配置。
6. 全局跨域默认允许所有来源和方法（`'*'`），生产环境应收紧为具体域名。
7. Session 默认已开启，有效期 24 小时；生产环境建议根据安全需求调整 `expire`。
8. 生产环境关闭 `APP_DEBUG`，并确保 `.env`、密钥文件、`database/data.db` 不被 Web 直接访问。

---

## 相关文档

- [开发规范与 AI 助手指南](./DEVELOPER.md)
- [ThinkPHP 8 多模块模式文档](https://doc.thinkphp.cn/v8_0/multi_app_model.html)
- [ThinkPHP 官方文档](https://doc.thinkphp.cn/)