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

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

> 仓库根目录说明见 [README.md](../../README.md)，文档索引见 [docs/README.md](../../docs/README.md)。

## 系统架构

**分层**：表现层（`views/` + `templates/{theme}/`）→ 控制器（`controllers/`、`modules/*`）→ 组件/服务（`components/`）→ 模型（`models/`）→ MySQL。

**主题**：`config/web.php` 的 `beforeRequest` 按 `Template::getActiveTemplate()` 切换 Yii Theme；`/admin/*` 不走前台主题。

**缓存**：默认模板前台数据由 `FrontDataCache` + `CountingFileCache` 管理，后台「缓存管理」可查看/清键。

## 目录结构（当前仓库）

```
deepblog/
├── commands/
│   ├── LlmWorkerController.php    # LLM 队列 Worker
│   ├── PublishController.php      # 定时发布
│   └── ReleaseLogController.php   # 版本日志 Git/SQL 同步
├── components/
│   ├── LLM/                       # 多厂商 Provider + Skill
│   ├── FrontDataCache.php         # 前台 JSON 缓存
│   ├── ReleaseLogGitSync.php      # Git → release_log
│   ├── WechatService.php / WechatCodeAuthService.php
│   ├── SecurityHelper.php / MailHelper.php / …
├── config/                        # web.php、db.php、wechat.php
├── controllers/                   # 前台（Site、Post、Auth、Docs、Changelog、Donate…）
├── modules/
│   ├── admin/                     # 后台（文章、采集、LLM、微信、开发迭代等）
│   └── api/                       # Token 鉴权 API
├── models/                        # Post、User、LlmTask、ReleaseLog、RoadmapItem…
├── templates/default/             # 默认完整 PHP 主题
├── views/                         # 无主题时的视图回退
├── web/
│   ├── index.php                  # 入口
│   ├── templates/dark|red/        # 仅 CSS 皮肤
│   └── docs/                      # 本文档等 Markdown
├── docs/                          # PRD、SQL、release_log_sync.md
└── yii                            # 控制台入口
```

## 部署与运维

| 步骤 | 说明 |
|------|------|
| PHP | 8.2+，`composer install` |
| 密钥 | 修改 `config/web.php` → `cookieValidationKey` |
| 数据库 | 配置 `config/db.php`；表结构以 `docs/*.sql` 为准（无 Migration） |
| Web 根 | 指向 `web/`，开启 Pretty URL |
| 邮件 | 生产关闭 `mailer.useFileTransport`；后台配置 SMTP 键 |
| cron | `php yii publish/index`；`php yii llm-worker/run`（若用队列） |
| 版本日志 | 本地 `php yii release-log/build-docs` → 执行 `docs/git_log_export.txt` 内 SQL |

线上一般**无 `.git`**，勿在线上执行 `git log`；见 [docs/release_log_sync.md](../../docs/release_log_sync.md)。

## 数据库设计

### 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 接口文档

### 鉴权

- 模块路径：`/api/*`
- Query 参数 `token`，对应后台「服务密钥管理」中的 `ApiKey`
- 基类：`modules/api/controllers/BaseController.php`

### 公共响应格式

```json
{
    "code": 200,
    "message": "success",
    "data": {}
}
```

### 已实现接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/post/create` | 远程采集发文（需 `title`、`original_url`、`original_source` 等，见 `PostController::actionCreate`） |
| GET | `/api/test/index` | 连通性测试 |
| POST | `/api/test/ping` | Ping 测试 |

实现代码：`modules/api/controllers/PostController.php`、`TestController.php`。

### 规划中的公开 REST（尚未实现）

以下接口在 PRD 中描述，**当前代码库未提供**，二次开发可自行扩展 `modules/api` 或勿依赖旧文档示例：

- `GET /api/v1/posts` — 文章列表
- `GET /api/v1/posts/{id}` — 文章详情
- `GET /api/v1/categories` — 分类列表

扩展时建议沿用 `BaseController::success()` / `error()` 与 Token 鉴权。

## 二次开发指南

### 创建新模块
本系统基于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（登录后请立即修改密码）