🔧 技术对接与二次开发文档

# 🔧 技术对接与二次开发文档

## 系统架构

### 整体架构
| 截图位置 | 截图说明 | 预期内容 |
|----------|----------|----------|
| 架构图 | 系统分层架构 | 表现层(View/Template) → 控制层(Controller) → 业务逻辑层(Model/Service/Component) → 数据层(DAO/ActiveRecord) → 数据库 |

### 目录结构
```
deepblog/
├── commands/              # 控制台命令
│   ├── LlmWorkerController.php  # LLM异步任务处理
│   └── PublishController.php    # 内容发布定时任务
├── components/            # 自定义核心组件
│   ├── LLM/               # 大模型相关组件
│   │   ├── LLMFactory.php      # 大模型客户端工厂
│   │   ├── LLMProviderInterface.php # 通用接口
│   │   ├── DeepSeekProvider.php # DeepSeek实现
│   │   ├── OpenaiProvider.php   # OpenAI/GPT实现
│   │   ├── AliyunProvider.php   # 通义千问实现
│   │   ├── KimiProvider.php     # Kimi/月之暗面实现
│   │   ├── HuoshanProvider.php  # 火山引擎实现
│   │   └── XfyunProvider.php    # 讯飞星辰实现
│   ├── CaptchaHelper.php  # 验证码助手
│   ├── MailHelper.php     # 邮件发送助手
│   ├── SecurityHelper.php # 安全工具类
│   ├── SiteConfig.php     # 站点配置管理
│   └── WechatService.php  # 微信相关服务
├── config/                # 配置文件目录
│   ├── web.php            # Web端核心配置
│   ├── console.php        # 控制台配置
│   ├── params.php         # 公共参数配置
│   ├── db.php             # 数据库配置
│   └── wechat.php         # 微信相关配置
├── controllers/           # 前台控制器
│   ├── AuthController.php # 用户认证相关
│   ├── SiteController.php # 首页/公共页面
│   ├── PostController.php # 文章相关
│   ├── CategoryController.php # 分类相关
│   └── DocsController.php # 文档中心相关
├── models/                # 数据模型
│   ├── Post.php           # 文章模型
│   ├── Category.php       # 分类模型
│   ├── Tag.php            # 标签模型
│   ├── User.php           # 用户模型
│   ├── Comment.php        # 评论模型
│   ├── OperationLog.php   # 操作日志模型
│   ├── SiteConfig.php     # 系统配置模型
│   ├── LlmTask.php        # LLM任务模型
│   └── LoginForm.php      # 登录表单模型
├── modules/               # 模块目录
│   ├── admin/             # 后台管理模块
│   └── api/               # API接口模块
├── templates/             # 前台模板目录
│   ├── default/           # 默认模板
│   ├── apple/             # 苹果风格模板
│   └── red/               # 红色风格模板
├── views/                 # 系统默认视图
├── web/                   # Web入口目录
│   ├── assets/            # 静态资源
│   ├── uploads/           # 上传文件目录
│   ├── docs/              # 文档中心
│   └── index.php          # 入口文件
├── runtime/               # 运行时缓存/日志目录
├── vendor/                # Composer依赖
└── yii                    # Yii控制台入口
```

## 数据库设计

### ER图
| 截图位置 | 截图说明 | 预期内容 |
|----------|----------|----------|
| 数据库ER图 | 表关系图 | 文章表关联分类表、标签关联表关联文章和标签、用户表关联文章和评论、评论表关联文章和用户 |

### 核心数据表结构

```sql
-- 用户表
CREATE TABLE `user` (
    `id` int(11) NOT NULL AUTO_INCREMENT,
    `username` varchar(255) NOT NULL COMMENT '用户名',
    `email` varchar(255) DEFAULT NULL COMMENT '邮箱',
    `phone` varchar(20) DEFAULT NULL COMMENT '手机号',
    `password_hash` varchar(255) NOT NULL COMMENT '密码哈希',
    `auth_key` varchar(32) NOT NULL COMMENT '自动登录密钥',
    `password_reset_token` varchar(255) DEFAULT NULL COMMENT '密码重置token',
    `avatar` varchar(255) DEFAULT NULL COMMENT '头像路径',
    `is_admin` tinyint(1) DEFAULT '0' COMMENT '是否管理员:0否1是',
    `status` tinyint(1) DEFAULT '10' COMMENT '状态:0删除9禁用10正常',
    `created_at` datetime NOT NULL COMMENT '创建时间',
    `updated_at` datetime NOT NULL COMMENT '更新时间',
    PRIMARY KEY (`id`),
    UNIQUE KEY `username` (`username`),
    UNIQUE KEY `email` (`email`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户表';

-- 文章表
CREATE TABLE `post` (
    `id` int(11) NOT NULL AUTO_INCREMENT,
    `title` varchar(200) NOT NULL COMMENT '标题',
    `slug` varchar(200) DEFAULT NULL COMMENT 'URL别名',
    `content` longtext COMMENT '正文内容',
    `summary` text COMMENT '摘要',
    `category_id` int(11) DEFAULT NULL COMMENT '分类ID',
    `user_id` int(11) NOT NULL COMMENT '作者ID',
    `cover_image` varchar(255) DEFAULT NULL COMMENT '封面图',
    `status` tinyint(1) DEFAULT '0' COMMENT '状态:0草稿1发布2待审核',
    `views` int(11) DEFAULT '0' COMMENT '浏览次数',
    `is_top` tinyint(1) DEFAULT '0' COMMENT '是否置顶:0否1是',
    `seo_title` varchar(200) DEFAULT NULL COMMENT 'SEO标题',
    `seo_description` text COMMENT 'SEO描述',
    `seo_keywords` varchar(200) DEFAULT NULL COMMENT 'SEO关键词',
    `created_at` datetime NOT NULL COMMENT '创建时间',
    `updated_at` datetime NOT NULL COMMENT '更新时间',
    `published_at` datetime DEFAULT NULL COMMENT '发布时间',
    PRIMARY KEY (`id`),
    KEY `category_id` (`category_id`),
    KEY `user_id` (`user_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='文章表';

-- 分类表
CREATE TABLE `category` (
    `id` int(11) NOT NULL AUTO_INCREMENT,
    `name` varchar(100) NOT NULL COMMENT '分类名称',
    `slug` varchar(100) DEFAULT NULL COMMENT '别名',
    `parent_id` int(11) DEFAULT '0' COMMENT '父分类ID',
    `description` text COMMENT '分类描述',
    `sort` int(11) DEFAULT '0' COMMENT '排序值',
    `is_display` tinyint(1) DEFAULT '1' COMMENT '是否显示:0否1是',
    `template` varchar(100) DEFAULT NULL COMMENT '自定义模板',
    `created_at` datetime NOT NULL COMMENT '创建时间',
    `updated_at` datetime NOT NULL COMMENT '更新时间',
    PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='分类表';

-- 标签表
CREATE TABLE `tag` (
    `id` int(11) NOT NULL AUTO_INCREMENT,
    `name` varchar(50) NOT NULL COMMENT '标签名称',
    `slug` varchar(50) DEFAULT NULL COMMENT '别名',
    `color` varchar(20) DEFAULT NULL COMMENT '标签颜色',
    `count` int(11) DEFAULT '0' COMMENT '关联文章数',
    `created_at` datetime NOT NULL COMMENT '创建时间',
    PRIMARY KEY (`id`),
    UNIQUE KEY `name` (`name`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='标签表';

-- 文章标签关联表
CREATE TABLE `post_tag` (
    `id` int(11) NOT NULL AUTO_INCREMENT,
    `post_id` int(11) NOT NULL COMMENT '文章ID',
    `tag_id` int(11) NOT NULL COMMENT '标签ID',
    PRIMARY KEY (`id`),
    KEY `post_id` (`post_id`),
    KEY `tag_id` (`tag_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='文章标签关联表';

-- 评论表
CREATE TABLE `comment` (
    `id` int(11) NOT NULL AUTO_INCREMENT,
    `post_id` int(11) NOT NULL COMMENT '文章ID',
    `user_id` int(11) DEFAULT NULL COMMENT '用户ID',
    `parent_id` int(11) DEFAULT '0' COMMENT '父评论ID',
    `content` text NOT NULL COMMENT '评论内容',
    `nickname` varchar(100) DEFAULT NULL COMMENT '匿名用户昵称',
    `email` varchar(255) DEFAULT NULL COMMENT '匿名用户邮箱',
    `ip` varchar(45) DEFAULT NULL COMMENT '评论IP',
    `status` tinyint(1) DEFAULT '0' COMMENT '状态:0待审核1已通过2已拒绝',
    `like_count` int(11) DEFAULT '0' COMMENT '点赞数',
    `created_at` datetime NOT NULL COMMENT '创建时间',
    PRIMARY KEY (`id`),
    KEY `post_id` (`post_id`),
    KEY `user_id` (`user_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='评论表';

-- 操作日志表
CREATE TABLE `operation_log` (
    `id` int(11) NOT NULL AUTO_INCREMENT,
    `user_id` int(11) DEFAULT NULL COMMENT '操作用户ID',
    `username` varchar(255) DEFAULT NULL COMMENT '用户名',
    `operation_type` varchar(50) NOT NULL COMMENT '操作类型',
    `operation_desc` text DEFAULT NULL COMMENT '操作描述',
    `ip_address` varchar(45) DEFAULT NULL COMMENT 'IP地址',
    `user_agent` text DEFAULT NULL COMMENT '用户UA',
    `request_data` json DEFAULT NULL COMMENT '请求数据',
    `response_data` json DEFAULT NULL COMMENT '响应数据',
    `status` smallint(6) NOT NULL DEFAULT '1' COMMENT '状态:1成功0失败',
    `created_at` datetime NOT NULL COMMENT '创建时间',
    PRIMARY KEY (`id`),
    KEY `user_id` (`user_id`),
    KEY `operation_type` (`operation_type`),
    KEY `created_at` (`created_at`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='操作日志表';
```

## API接口文档

### 公共响应格式
```json
{
    "code": 200,
    "message": "success",
    "data": {}
}
```
| 字段 | 说明 |
|------|------|
| code | 响应码：200成功，400参数错误，401未登录，403无权限，404资源不存在，500服务器错误 |
| message | 响应说明 |
| data | 响应数据 |

### 获取文章列表
**接口地址**：`GET /api/v1/posts`

**请求参数**：
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | int | 否 | 页码，默认1 |
| pageSize | int | 否 | 每页数量，默认10，最大50 |
| category_id | int | 否 | 分类ID筛选 |
| keyword | string | 否 | 关键词搜索 |
| tag | string | 否 | 标签名称筛选 |
| order | string | 否 | 排序方式：latest最新（默认）、hot热门、views浏览量 |

**返回示例**：
```json
{
    "code": 200,
    "message": "success",
    "data": {
        "list": [
            {
                "id": 1,
                "title": "文章标题",
                "slug": "article-slug",
                "summary": "文章摘要...",
                "cover_image": "/uploads/cover.jpg",
                "category_name": "技术分享",
                "author": "管理员",
                "views": 123,
                "published_at": "2026-04-21 10:00:00"
            }
        ],
        "total": 100,
        "page": 1,
        "pageSize": 10,
        "totalPage": 10
    }
}
```

### 获取文章详情
**接口地址**：`GET /api/v1/posts/{id}`

**路径参数**：
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | int | 是 | 文章ID |

**返回示例**：
```json
{
    "code": 200,
    "message": "success",
    "data": {
        "id": 1,
        "title": "文章标题",
        "content": "<p>文章正文...</p>",
        "category_name": "技术分享",
        "author": "管理员",
        "avatar": "/uploads/avatar.jpg",
        "tags": ["PHP", "Yii2"],
        "views": 123,
        "published_at": "2026-04-21 10:00:00",
        "related_posts": []
    }
}
```

### 获取分类列表
**接口地址**：`GET /api/v1/categories`

**返回示例**：
```json
{
    "code": 200,
    "message": "success",
    "data": [
        {
            "id": 1,
            "name": "技术分享",
            "slug": "tech",
            "description": "技术相关文章分类",
            "post_count": 50
        }
    ]
}
```

## 二次开发指南

### 创建新模块
本系统基于Yii2模块化设计，扩展新功能非常方便：

1. **创建模块目录结构**
```
modules/
└── forum/
    ├── ForumModule.php
    ├── controllers/
    │   └── DefaultController.php
    ├── models/
    ├── views/
    │   └── default/
    │       └── index.php
    └── config/
        └── main.php
```

2. **创建模块主类**
```php
// modules/forum/ForumModule.php
namespace app\modules\forum;

class ForumModule extends \yii\base\Module
{
    public function init()
    {
        parent::init();
        // 加载模块自定义配置
        \Yii::configure(this, require __DIR__ . '/config/main.php');
    }
}
```

3. **注册模块到配置**
```php
// config/web.php
return [
    'modules' => [
        'forum' => [
            'class' => 'app\modules\forum\ForumModule',
        ],
    ],
];
```

4. **添加路由规则**
```php
// config/web.php
'rules' => [
    'forum' => 'forum/default/index',
    'forum/<action:[\w\-]+>' => 'forum/default/<action>',
],
```

### 扩展点说明

#### Events（事件）
系统内置多个事件点，方便扩展功能：
```php
// 支持的文章事件
- \app\models\Post::EVENT_BEFORE_INSERT  // 文章创建前
- \app\models\Post::EVENT_AFTER_INSERT   // 文章创建后
- \app\models\Post::EVENT_BEFORE_UPDATE  // 文章更新前
- \app\models\Post::EVENT_AFTER_UPDATE   // 文章更新后
- \app\models\Post::EVENT_BEFORE_DELETE  // 文章删除前
- \app\models\Post::EVENT_AFTER_DELETE   // 文章删除后

// 使用示例：文章发布后自动推送搜索引擎
\Yii::$app->on(\app\models\Post::EVENT_AFTER_INSERT, function ($event) {
    $post = $event->sender;
    if ($post->status == 1) { // 已发布
        // 执行推送逻辑
        \Yii::info("文章{$post->id}已发布，自动推送到搜索引擎");
    }
});
```

#### Behaviors（行为）
可通过行为扩展模型功能：
```php
// 自定义示例：自动为文章生成摘要
class AutoSummaryBehavior extends \yii\base\Behavior
{
    public $contentAttribute = 'content';
    public $summaryAttribute = 'summary';
    public $length = 200;

public function events()
    {
        return [
            \app\models\Post::EVENT_BEFORE_INSERT => 'generateSummary',
            \app\models\Post::EVENT_BEFORE_UPDATE => 'generateSummary',
        ];
    }

public function generateSummary($event)
    {
        $post = $this->owner;
        if (empty($post->{$this->summaryAttribute})) {
            $text = strip_tags($post->{$this->contentAttribute});
            $post->{$this->summaryAttribute} = mb_substr($text, 0, $this->length) . '...';
        }
    }
}

// 模型中使用：
public function behaviors()
{
    return array_merge(parent::behaviors(), [
        'autoSummary' => [
            'class' => AutoSummaryBehavior::class,
            'length' => 300,
        ],
    ]);
}
```

### 大模型功能扩展
系统内置多厂商大模型支持，可快速扩展新厂商：
1. 新建Provider类实现`LLMProviderInterface`接口
2. 在`LLMFactory::make()`方法中添加对应case
3. 在后台系统设置中添加对应配置项即可使用

## 部署与配置

### 环境要求
| 环境 | 最低要求 | 推荐配置 |
|------|----------|----------|
| PHP | 8.2 | 8.2+ |
| MySQL | 5.7 | 8.0+ |
| Composer | 2.0 | 2.6+ |
| Web服务器 | Nginx 1.18+ / Apache 2.4+ | Nginx 1.24+ |
| 内存 | 512M | 1G+ |
| 存储空间 | 10G | 50G+（根据上传文件需求） |

### 核心配置说明
```php
// config/db.php 数据库配置
return [
    'class' => 'yii\db\Connection',
    'dsn' => 'mysql:host=localhost;dbname=deepblog;charset=utf8mb4',
    'username' => 'root',
    'password' => 'your_password',
    'charset' => 'utf8mb4',
    'enableSchemaCache' => true, // 生产环境开启表结构缓存提升性能
    'schemaCacheDuration' => 3600,
];

// config/web.php 核心配置
return [
    'name' => 'DeepBlog博客系统',
    'language' => 'zh-CN',
    'timeZone' => 'Asia/Shanghai',
    'components' => [
        'cache' => [
            'class' => 'yii\caching\FileCache', // 生产环境建议换成Redis
        ],
        'user' => [
            'identityClass' => 'app\models\User',
            'enableAutoLogin' => true,
            'loginUrl' => ['auth/login'],
        ],
        'urlManager' => [
            'enablePrettyUrl' => true,
            'showScriptName' => false,
            'rules' => [
                'post/<slug:[\w\-]+>' => 'post/view',
                'category/<slug:[\w\-]+>' => 'category/view',
                'tag/<slug:[\w\-]+>' => 'tag/view',
            ],
        ],
    ],
];
```

### Nginx配置示例
```nginx
server {
    listen 80;
    server_name your-domain.com;
    root /wwwroot/deepblog/web;
    index index.php;

location / {
        try_files $uri $uri/ /index.php?$args;
    }

location ~ \.php$ {
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

# 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

# 保护敏感目录
    location ~ /\. {
        deny all;
    }

location ~ /(runtime|vendor|config|commands|models|modules)/ {
        deny all;
        return 403;
    }
}
```

### 部署步骤
1. 克隆代码到服务器目录
2. 执行`composer install`安装依赖
3. 复制`config/db.php.example`为`config/db.php`并配置数据库信息
4. 执行`php yii migrate`执行数据库迁移（或手动导入SQL文件）
5. 配置Nginx/Apache虚拟主机，root指向`web`目录
6. 设置`runtime`和`web/uploads`目录权限为777
7. 访问站点，后台默认账号：admin/admin123（登录后请立即修改密码）