# 功能说明文档

本文档详细介绍留言板 API 服务的所有功能模块及使用方法。

---

## 目录

1. [前台功能](#前台功能)
2. [API 接口](#api-接口)
3. [后台管理](#后台管理)
4. [安全机制](#安全机制)
5. [系统设置](#系统设置)

---

## 前台功能

### 首页文档 (`index.php`)

首页作为 API 服务的展示页面，提供以下内容：

- **Hero 区域** — 站点名称、简介和快捷导航按钮（快速开始 / API 文档 / 后台管理）
- **特性展示** — 6 大特性卡片（RESTful API、多站点隔离、智能过滤、域名白名单、IP 归属地、访客回复）
- **快速开始指南** — 三步接入指引 + API 端点地址
- **API 接口文档** — 6 个可折叠接口卡片，包含参数说明、cURL 示例、JavaScript 示例和响应示例
- **错误码说明** — 所有 HTTP 状态码的含义
- **功能更新时间线** — 从数据库读取版本更新记录，以时间线形式展示
- **页脚备案信息** — 动态显示后台设置的备案信息

### 站点名称与页脚

站点名称和页脚备案信息可在后台「系统设置」中自定义，支持 HTML 格式。

---

## API 接口

所有接口统一入口为 `api.php`，通过 `action` 参数路由。详细说明请参阅 [API.md](./API.md)。

### 认证方式

所有接口均需携带有效的 `api_key` 参数：

- **GET 请求**：作为 URL 参数 `?api_key=YOUR_KEY`
- **POST 请求**：作为 URL 参数或 JSON Body 中的 `api_key` 字段

### 6 个端点

| 端点 | 方法 | 功能 | 主要参数 |
|------|------|------|---------|
| `verify` | GET | 验证密钥有效性 | api_key |
| `post` | POST | 提交留言 | nickname, content |
| `reply` | POST | 回复留言 | message_id, nickname, content |
| `list` | GET | 留言列表 | page, per_page |
| `detail` | GET | 留言详情 | id |
| `count` | GET | 留言统计 | 无 |

---

## 后台管理

后台管理入口：`/admin/`

### 管理员登录 (`login.php`)

- 全新双栏 UI 设计：左侧品牌展示区，右侧登录表单
- 支持「忘记密码」功能
- 密码使用 bcrypt 加密存储

### 仪表盘 (`index.php`)

- 统计数据概览（总留言数、待审核数、今日新增等）
- 留言列表管理（审核通过 / 驳回 / 删除）
- 管理员回复功能

### API 密钥管理 (`api.php`)

- **生成密钥** — 32 位十六进制随机字符串
- **管理密钥** — 查看、启用/禁用、删除
- **域名白名单** — 每个密钥可配置多个域名，支持通配符 `*.example.com`
- **密钥状态** — 可随时启用或停用密钥

### 敏感词管理 (`words.php`)

- 添加/删除敏感词
- 预设约 40 个常见敏感词
- 留言提交和回复时自动检测并过滤

### 垃圾拦截 (`spam.php`)

- 配置垃圾拦截规则
- 内置规则包括：空内容检测、重复内容检测、URL 数量限制、纯数字/英文比例等
- 每条规则可独立启用/禁用和调整参数

### 修改密码 (`password.php`)

- 修改当前管理员登录密码
- 需输入当前密码验证身份

### 忘记密码 (`forgot-password.php` + `reset-password.php`)

完整密码找回流程：

1. 在登录页点击「忘记密码」
2. 输入管理员用户名
3. 系统向管理员邮箱发送密码重置邮件
4. 点击邮件中的链接进入重置页面
5. 设置新密码（令牌有效期 1 小时，一次性使用）

### 系统设置 (`settings.php`)

包含三个核心模块：

#### 站点设置

- **站点名称** — 显示在首页 Hero 区域
- **页脚备案信息** — 显示在首页底部，支持 HTML

#### 邮件设置

- **SMTP 配置** — 服务器地址、端口、加密方式（SSL/TLS）、账号、密码
- **发件人地址** — 自定义发件人显示
- **管理员邮箱** — 用于接收密码重置邮件
- **测试邮件** — 发送测试邮件验证配置是否正确

#### 更新日志

- 添加/删除版本更新记录
- 每条记录包含：版本号、更新标题、更新内容
- 更新内容显示在首页时间线模块

---

## 安全机制

### 留言安全

| 机制 | 说明 |
|------|------|
| 敏感词过滤 | 自动将敏感词替换为 `*` |
| 垃圾检测 | 多维度检测（空内容、重复、URL 数量、纯数字/英文比例等） |
| IP 限流 | 同一 IP 在指定时间内只能提交一次 |
| 内容长度限制 | 昵称 ≤ 30 字符，内容 ≤ 500 字符 |

### API 安全

| 机制 | 说明 |
|------|------|
| 密钥认证 | 所有 API 调用必须携带有效 api_key |
| 域名白名单 | 限制 API 调用来源域名 |
| 密钥禁用 | 可随时停用泄漏的密钥 |

### 后台安全

| 机制 | 说明 |
|------|------|
| 密码加密 | bcrypt 哈希存储 |
| Session 认证 | 登录状态基于服务端 Session |
| 令牌安全 | 密码重置令牌随机生成、一次使用、定时过期 |

---

## 系统设置

### SMTP 邮件发送原理

系统使用 PHP 原生 socket 实现 SMTP 协议通信，无需第三方邮件库：

1. 通过 SSL/TLS 连接到 SMTP 服务器
2. 使用 AUTH LOGIN 方式认证
3. 发送 HTML 格式邮件
4. 支持主流邮件服务（QQ 邮箱、163 邮箱、Gmail 等）

### 常见 SMTP 配置参考

| 邮箱服务 | SMTP 服务器 | 端口 | 加密 |
|---------|-----------|------|------|
| QQ 邮箱 | smtp.qq.com | 465 | SSL |
| 163 邮箱 | smtp.163.com | 465 | SSL |
| Gmail | smtp.gmail.com | 587 | TLS |

> **注意**：使用第三方客户端发信时，通常需要在邮箱设置中开启 SMTP 服务并获取授权码（而非登录密码）。

### 页脚备案信息

支持在后台设置自定义 HTML 内容，常见用法：

```html
<a href="https://beian.miit.gov.cn/" target="_blank">京ICP备XXXXXXXX号-1</a>
```