# ruseoAD

**Repository Path**: corbancc/ruseoAD

## Basic Information

- **Project Name**: ruseoAD
- **Description**: ThinkPHP 广告管理系统，支持7种广告位（首页头部/底部/分类间/对联、工具页头部/底部/对联）、3种广告类型（代码/图片/链接）、后台layui管理、前台 {:ad('position')} 一行代码调用
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ruseoAD — ruseo.cn 广告管理系统

基于 ThinkPHP 6.x 的站点广告管理模块，支持多种广告位、广告类型和展示方式，后台 CRUD 管理，前台一行代码调用。

## 功能特性

- **7 种预设广告位**：首页头部/底部/分类间/对联，工具页头部/底部/对联
- **3 种广告类型**：HTML 代码、图片广告、文字链接
- **3 种展示方式**：并排、轮播、逐条排列
- **页面精准投放**：全站 / 首页 / 工具页，可指定单个工具 ID
- **对联广告**：左右浮动 + 关闭按钮，窄屏自动隐藏
- **分类间广告**：虚线分隔样式，插入首页分类列表之间
- **自定义广告位**：除 7 种预设外，可输入任意英文标识

## 文件清单

| 文件 | 说明 |
|------|------|
| `install_ad.sql` | 建表 SQL（toolbox_ad） |
| `app/controller/admin/Ad.php` | 后台 CRUD 控制器 |
| `app/common.php` | 前台 `ad()` 助手函数 + 渲染函数 |
| `route/admin.php` | 广告管理 API 路由 |
| `app/controller/admin/Menu.php` | 后台菜单项 |
| `public/static/css/style.css` | 广告展示 CSS |
| `public/admin/page/ad.html` | 广告列表页 |
| `public/admin/page/ad/add.html` | 添加广告页 |
| `public/admin/page/ad/edit.html` | 编辑广告页 |

## 部署步骤

### 1. 建表

```sql
SOURCE install_ad.sql;
```

或在 phpMyAdmin 中导入 `install_ad.sql`。

### 2. 同步代码

将上述文件上传到 ruseo.cn 对应目录。

### 3. 清缓存

后台 → 系统设置 → 清除缓存，或访问 `/admin/clear`。

### 4. 验证

后台左侧菜单应出现「广告管理」，进入后可添加/编辑/删除广告。

## 前台调用

在模板任意位置插入：

```html
{:ad('home_top')}
{:ad('tool_bottom')}
{:ad('home_couplet')}
{:ad('home_category')}
```

带参数调用（指定页面类型和工具 ID）：

```html
{:ad('tool_top', 'tool', $plugin.id)}
```

## 预设广告位

| 标识 | 名称 | 渲染方式 |
|------|------|----------|
| `home_top` | 首页头部 | 普通 |
| `home_bottom` | 首页底部 | 普通 |
| `home_category` | 首页分类间 | 虚线分隔 |
| `home_couplet` | 首页对联 | 左右浮动 |
| `tool_top` | 工具页头部 | 普通 |
| `tool_bottom` | 工具页底部 | 普通 |
| `tool_couplet` | 工具页对联 | 左右浮动 |

## 数据表结构

`toolbox_ad` 主要字段：

| 字段 | 类型 | 说明 |
|------|------|------|
| `position` | varchar(50) | 广告位标识 |
| `type` | enum | code / image / link |
| `content` | text | 广告内容 |
| `link_url` | varchar(255) | 链接地址 |
| `image_alt` | varchar(255) | 图片 ALT |
| `pages` | varchar(255) | 投放页面（* / home / tool） |
| `tool_ids` | varchar(255) | 指定工具 ID |
| `display_mode` | enum | inline / carousel / list |
| `enable` | tinyint(1) | 是否启用 |
| `weight` | int(11) | 排序权重 |

## API 端点

| 路由 | 方法 | 说明 |
|------|------|------|
| `/admin/ad/list` | GET | 广告列表（支持搜索/筛选） |
| `/admin/ad/get` | GET | 获取单条广告（?id=N） |
| `/admin/ad/add` | POST | 添加广告 |
| `/admin/ad/edit` | POST | 编辑广告 |
| `/admin/ad/delete` | POST | 删除广告（支持批量） |
| `/admin/ad/enable` | POST | 启用/禁用切换 |