1316 lines
28 KiB
Markdown
1316 lines
28 KiB
Markdown
# 投票系统 API 接口文档
|
||
|
||
## 概述
|
||
|
||
本文档描述了投票系统的所有API接口，包括用户管理、投票操作、投票主题管理、管理员功能和文件上传等功能。该API支持GET和POST两种请求方式，并支持JSON格式的请求体。
|
||
|
||
## 基础信息
|
||
|
||
- **基础URL**: `https://poe.vogov.cn/toupiao/`
|
||
- **请求方式**: GET / POST
|
||
- **数据格式**: JSON
|
||
- **字符编码**: UTF-8
|
||
- **跨域支持**: 已启用CORS
|
||
|
||
## 通用响应格式
|
||
|
||
所有接口返回统一的JSON格式：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "操作成功",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
### 响应字段说明
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | int | 状态码，0表示成功，非0表示失败 |
|
||
| msg | string | 提示信息 |
|
||
| data | object/array | 返回数据，具体内容根据接口而定 |
|
||
|
||
---
|
||
|
||
# 数据库结构
|
||
|
||
## 1. 用户表 (tp_users)
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | int(11) | 用户ID，主键，自增 |
|
||
| username | varchar(255) | 用户账号（手机号/邮箱/微信号） |
|
||
| password | varchar(255) | 密码（加密存储） |
|
||
| irole | tinyint(1) | 角色（0:普通用户, 1:管理员） |
|
||
| status | tinyint(1) | 状态（0:禁用, 1:正常） |
|
||
| regtime | datetime | 注册时间 |
|
||
| logtime | datetime | 最后登录时间 |
|
||
| user_identifier | varchar(100) | 用户标识（可选） |
|
||
|
||
## 2. 投票主题表 (tp_vote)
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | int(11) | 主题ID，主键，自增 |
|
||
| title | varchar(255) | 投票标题 |
|
||
| idesc | text | 投票描述 |
|
||
| statime | datetime | 开始时间 |
|
||
| endtime | datetime | 结束时间 |
|
||
| status | tinyint(1) | 状态（0:禁用, 1:正常） |
|
||
| itype | tinyint(1) | 类型（0:单选, 1:多选） |
|
||
| maxtime | int(11) | 多选时最多可选几项 |
|
||
| addtime | datetime | 创建时间 |
|
||
| adduser | int(11) | 创建用户ID |
|
||
| iview | int(11) | 查看次数 |
|
||
|
||
## 3. 投票选项表 (tp_xuan)
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | int(11) | 选项ID，主键，自增 |
|
||
| topic_id | int(11) | 所属投票主题ID |
|
||
| name | varchar(255) | 选项名称 |
|
||
| idesc | text | 选项描述 |
|
||
| imgs | varchar(255) | 选项图片 |
|
||
| sort | int(11) | 排序值 |
|
||
| addtime | datetime | 创建时间 |
|
||
| adduser | int(11) | 创建用户ID |
|
||
|
||
## 4. 投票记录表 (tp_recs)
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | int(11) | 记录ID，主键，自增 |
|
||
| topic_id | int(11) | 投票主题ID |
|
||
| user_id | int(11) | 用户ID |
|
||
| option_id | int(11) | 选项ID |
|
||
| vote_time | datetime | 投票时间 |
|
||
| ip | varchar(50) | 投票IP |
|
||
|
||
## 5. 系统日志表 (tp_logs)
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | int(11) | 日志ID，主键，自增 |
|
||
| user_id | int(11) | 用户ID |
|
||
| action | varchar(50) | 操作类型 |
|
||
| idesc | text | 操作描述 |
|
||
| ip | varchar(50) | 操作IP |
|
||
| logtime | datetime | 操作时间 |
|
||
|
||
---
|
||
|
||
# 一、用户API (tapi.php)
|
||
|
||
**接口地址**: `/tapi.php`
|
||
|
||
## 1.1 用户登录
|
||
|
||
**接口描述**: 用户使用账号（手机号/邮箱/微信号）和密码登录系统
|
||
|
||
**请求方式**: GET / POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：login |
|
||
| username | string | 是 | 用户账号，支持手机号、邮箱或微信号 |
|
||
| password | string | 是 | 用户密码 |
|
||
|
||
**请求示例**:
|
||
|
||
```
|
||
POST /tapi.php
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"act": "login",
|
||
"username": "13800138000",
|
||
"password": "123456"
|
||
}
|
||
```
|
||
|
||
**响应示例** (成功):
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "登录成功",
|
||
"data": {
|
||
"id": 1,
|
||
"username": "13800138000",
|
||
"irole": 0,
|
||
"status": 1,
|
||
"regtime": "2026-03-27 10:00:00",
|
||
"logtime": "2026-03-27 14:30:00",
|
||
"user_identifier": "user123"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码说明**:
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 1 | 账号和密码不能为空 |
|
||
| 1 | 账号或密码错误 |
|
||
| 1 | 账号已被禁用，请联系管理员 |
|
||
|
||
---
|
||
|
||
## 1.2 用户注册
|
||
|
||
**接口描述**: 新用户注册账号，支持手机号、邮箱或微信号作为账号
|
||
|
||
**请求方式**: GET / POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：register |
|
||
| username | string | 是 | 用户账号，支持手机号、邮箱或微信号 |
|
||
| password | string | 是 | 用户密码，长度不少于6位 |
|
||
| user_identifier | string | 否 | 用户标识（可选） |
|
||
|
||
**账号格式要求**:
|
||
|
||
- **手机号**: 以1开头，第二位为3-9，共11位数字
|
||
- **邮箱**: 标准邮箱格式，如 user@example.com
|
||
- **微信号**: 6-20位字母、数字、下划线或连字符
|
||
|
||
**请求示例**:
|
||
|
||
```
|
||
POST /tapi.php
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"act": "register",
|
||
"username": "13800138000",
|
||
"password": "123456",
|
||
"user_identifier": "user123"
|
||
}
|
||
```
|
||
|
||
**响应示例** (成功):
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "注册成功",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
**错误码说明**:
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 1 | 账号和密码不能为空 |
|
||
| 1 | 请输入正确的手机号、邮箱或微信号 |
|
||
| 1 | 密码长度不能少于6位 |
|
||
| 1 | 该账号已被注册 |
|
||
| 1 | 注册失败，请稍后重试 |
|
||
|
||
---
|
||
|
||
## 1.3 获取用户信息
|
||
|
||
**接口描述**: 获取当前登录用户的详细信息
|
||
|
||
**请求方式**: GET / POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：getUserInfo |
|
||
|
||
**请求示例**:
|
||
|
||
```
|
||
GET /tapi.php?act=getUserInfo
|
||
```
|
||
|
||
**响应示例** (成功):
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "获取成功",
|
||
"data": {
|
||
"id": 1,
|
||
"username": "13800138000",
|
||
"irole": 0,
|
||
"status": 1,
|
||
"regtime": "2026-03-27 10:00:00",
|
||
"logtime": "2026-03-27 14:30:00",
|
||
"user_identifier": "user123"
|
||
}
|
||
}
|
||
```
|
||
|
||
**注意**: 此接口需要用户已登录，否则会返回错误。
|
||
|
||
---
|
||
|
||
## 1.4 用户登出
|
||
|
||
**接口描述**: 用户退出登录，清除session
|
||
|
||
**请求方式**: GET / POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：logout |
|
||
|
||
**请求示例**:
|
||
|
||
```
|
||
GET /tapi.php?act=logout
|
||
```
|
||
|
||
**响应示例** (成功):
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "登出成功",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 1.5 更新用户标识
|
||
|
||
**接口描述**: 更新当前登录用户的标识信息
|
||
|
||
**请求方式**: GET / POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：updateUserIdentifier |
|
||
| user_identifier | string | 否 | 用户标识（可选），长度不超过100个字符 |
|
||
|
||
**请求示例**:
|
||
|
||
```
|
||
POST /tapi.php
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"act": "updateUserIdentifier",
|
||
"user_identifier": "new_identifier"
|
||
}
|
||
```
|
||
|
||
**响应示例** (成功):
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "更新成功",
|
||
"data": {
|
||
"id": 1,
|
||
"username": "13800138000",
|
||
"irole": 0,
|
||
"status": 1,
|
||
"regtime": "2026-03-27 10:00:00",
|
||
"logtime": "2026-03-27 14:30:00",
|
||
"user_identifier": "new_identifier"
|
||
}
|
||
}
|
||
```
|
||
|
||
**注意**: 此接口需要用户已登录，否则会返回错误。
|
||
|
||
---
|
||
|
||
# 二、投票API (vote_api.php)
|
||
|
||
**接口地址**: `/vote_api.php`
|
||
|
||
## 2.1 获取投票列表
|
||
|
||
**接口描述**: 获取投票列表，支持分页和筛选
|
||
|
||
**请求方式**: GET / POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：getVoteList |
|
||
| page | int | 否 | 当前页码，默认1 |
|
||
| pageSize | int | 否 | 每页记录数，默认10 |
|
||
| status | int | 否 | 状态筛选，-1表示全部，0表示禁用，1表示正常 |
|
||
| type | int | 否 | 类型筛选，-1表示全部，0表示单选，1表示多选 |
|
||
|
||
**请求示例**:
|
||
|
||
```
|
||
GET /vote_api.php?act=getVoteList&page=1&pageSize=10
|
||
```
|
||
|
||
**响应示例** (成功):
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "获取成功",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": 1,
|
||
"title": "最喜欢的水果",
|
||
"idesc": "请选择您最喜欢的水果",
|
||
"itype": 0,
|
||
"maxtime": 1,
|
||
"status": 1,
|
||
"iview": 14,
|
||
"addtime": "2026-03-25 22:25:46",
|
||
"statime": "2026-03-24 22:25:46",
|
||
"endtime": "2026-04-01 22:25:46",
|
||
"status_text": "进行中",
|
||
"status_class": "vote-status-active"
|
||
}
|
||
],
|
||
"pagination": {
|
||
"total": 1,
|
||
"page": 1,
|
||
"pageSize": 10,
|
||
"totalPage": 1,
|
||
"offset": 0
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 投票项字段说明 (VoteItem)
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | int | 投票ID |
|
||
| title | string | 投票标题 |
|
||
| idesc | string | 投票描述 |
|
||
| itype | int | 类型（0:单选, 1:多选） |
|
||
| maxtime | int | 多选时最多可选几项 |
|
||
| status | int | 状态（0:禁用, 1:正常） |
|
||
| iview | int | 查看次数 |
|
||
| addtime | string | 创建时间 |
|
||
| statime | string | 开始时间 |
|
||
| endtime | string | 结束时间 |
|
||
| status_text | string | 状态文本（进行中/已结束/未开始/已禁用） |
|
||
| status_class | string | 状态样式类 |
|
||
|
||
### 状态说明
|
||
|
||
| status_text | status_class | 说明 |
|
||
|-------------|--------------|------|
|
||
| 进行中 | vote-status-active | 投票正在进行中 |
|
||
| 已结束 | vote-status-ended | 投票已结束 |
|
||
| 未开始 | vote-status-pending | 投票尚未开始 |
|
||
| 已禁用 | vote-status-disabled | 投票已被禁用 |
|
||
|
||
---
|
||
|
||
## 2.2 获取投票详情
|
||
|
||
**接口描述**: 获取投票详情和选项信息
|
||
|
||
**请求方式**: GET / POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：getVoteDetail |
|
||
| id | int | 是 | 投票ID |
|
||
|
||
**请求示例**:
|
||
|
||
```
|
||
GET /vote_api.php?act=getVoteDetail&id=1
|
||
```
|
||
|
||
**响应示例** (成功):
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "获取成功",
|
||
"data": {
|
||
"vote": {
|
||
"id": 1,
|
||
"title": "最喜欢的水果",
|
||
"idesc": "请选择您最喜欢的水果",
|
||
"itype": 0,
|
||
"maxtime": 1,
|
||
"status": 1,
|
||
"iview": 15,
|
||
"addtime": "2026-03-25 22:25:46",
|
||
"statime": "2026-03-24 22:25:46",
|
||
"endtime": "2026-04-01 22:25:46",
|
||
"status_text": "进行中",
|
||
"status_class": "vote-status-active"
|
||
},
|
||
"options": [
|
||
{
|
||
"id": 1,
|
||
"topic_id": 1,
|
||
"name": "苹果",
|
||
"idesc": "红富士苹果",
|
||
"imgs": "",
|
||
"sort": 0
|
||
},
|
||
{
|
||
"id": 2,
|
||
"topic_id": 1,
|
||
"name": "香蕉",
|
||
"idesc": "进口香蕉",
|
||
"imgs": "",
|
||
"sort": 1
|
||
}
|
||
],
|
||
"hasVoted": false,
|
||
"userVotes": [],
|
||
"canVote": true
|
||
}
|
||
}
|
||
```
|
||
|
||
### 响应字段说明
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| vote | object | 投票详情 |
|
||
| options | array | 选项列表 |
|
||
| hasVoted | bool | 当前用户是否已投票 |
|
||
| userVotes | array | 当前用户已投的选项ID列表 |
|
||
| canVote | bool | 是否可以投票 |
|
||
|
||
### 选项字段说明 (VoteOption)
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | int | 选项ID |
|
||
| topic_id | int | 所属投票主题ID |
|
||
| name | string | 选项名称 |
|
||
| idesc | string | 选项描述 |
|
||
| imgs | string | 选项图片URL |
|
||
| sort | int | 排序值 |
|
||
|
||
**错误码说明**:
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 1 | 参数错误 |
|
||
| 1 | 投票不存在 |
|
||
|
||
---
|
||
|
||
## 2.3 提交投票
|
||
|
||
**接口描述**: 提交用户的投票选择
|
||
|
||
**请求方式**: GET / POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：submitVote |
|
||
| topic_id | int | 是 | 投票ID |
|
||
| options | array/string | 是 | 选项ID数组或逗号分隔的字符串 |
|
||
|
||
**请求示例**:
|
||
|
||
```
|
||
POST /vote_api.php
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"act": "submitVote",
|
||
"topic_id": 1,
|
||
"options": [1, 2]
|
||
}
|
||
```
|
||
|
||
**响应示例** (成功):
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "投票成功",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
**错误码说明**:
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 1 | 请先登录 |
|
||
| 1 | 参数错误 |
|
||
| 1 | 请至少选择一个选项 |
|
||
| 1 | 投票不存在 |
|
||
| 1 | 该投票已被禁用 |
|
||
| 1 | 该投票尚未开始 |
|
||
| 1 | 该投票已经结束 |
|
||
| 1 | 您已经参与过该投票 |
|
||
| 1 | 最多只能选择 X 项 |
|
||
| 1 | 选项不存在 |
|
||
| 1 | 提交投票失败 |
|
||
|
||
**注意**: 此接口需要用户已登录，否则会返回错误。
|
||
|
||
---
|
||
|
||
## 2.4 获取投票结果
|
||
|
||
**接口描述**: 获取投票结果和统计数据
|
||
|
||
**请求方式**: GET / POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：getVoteResult |
|
||
| id | int | 是 | 投票ID |
|
||
|
||
**请求示例**:
|
||
|
||
```
|
||
GET /vote_api.php?act=getVoteResult&id=1
|
||
```
|
||
|
||
**响应示例** (成功):
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "获取成功",
|
||
"data": {
|
||
"vote": {
|
||
"id": 1,
|
||
"title": "最喜欢的水果",
|
||
"idesc": "请选择您最喜欢的水果",
|
||
"itype": 0,
|
||
"maxtime": 1,
|
||
"status": 1,
|
||
"iview": 15,
|
||
"addtime": "2026-03-25 22:25:46",
|
||
"statime": "2026-03-24 22:25:46",
|
||
"endtime": "2026-04-01 22:25:46"
|
||
},
|
||
"options": [
|
||
{
|
||
"id": 1,
|
||
"name": "苹果",
|
||
"idesc": "红富士苹果",
|
||
"imgs": "",
|
||
"count": 50,
|
||
"percentage": 50
|
||
},
|
||
{
|
||
"id": 2,
|
||
"name": "香蕉",
|
||
"idesc": "进口香蕉",
|
||
"imgs": "",
|
||
"count": 30,
|
||
"percentage": 30
|
||
},
|
||
{
|
||
"id": 3,
|
||
"name": "橙子",
|
||
"idesc": "新鲜橙子",
|
||
"imgs": "",
|
||
"count": 20,
|
||
"percentage": 20
|
||
}
|
||
],
|
||
"totalVotes": 100,
|
||
"hasVoted": true,
|
||
"userVotes": [1]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 结果选项字段说明 (VoteResultOption)
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | int | 选项ID |
|
||
| name | string | 选项名称 |
|
||
| idesc | string | 选项描述 |
|
||
| imgs | string | 选项图片URL |
|
||
| count | int | 投票数量 |
|
||
| percentage | float | 投票百分比 |
|
||
|
||
**错误码说明**:
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 1 | 参数错误 |
|
||
| 1 | 投票不存在 |
|
||
| 1 | 暂无投票选项 |
|
||
|
||
---
|
||
|
||
## 2.5 获取用户投票记录
|
||
|
||
**接口描述**: 获取用户参与过的投票记录
|
||
|
||
**请求方式**: GET / POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：getUserVotes |
|
||
| page | int | 否 | 当前页码，默认1 |
|
||
| pageSize | int | 否 | 每页记录数，默认10 |
|
||
|
||
**请求示例**:
|
||
|
||
```
|
||
GET /vote_api.php?act=getUserVotes&page=1&pageSize=10
|
||
```
|
||
|
||
**响应示例** (成功):
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "获取成功",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": 1,
|
||
"title": "最喜欢的水果",
|
||
"idesc": "请选择您最喜欢的水果",
|
||
"itype": 0,
|
||
"maxtime": 1,
|
||
"status": 1,
|
||
"iview": 15,
|
||
"addtime": "2026-03-25 22:25:46",
|
||
"statime": "2026-03-24 22:25:46",
|
||
"endtime": "2026-04-01 22:25:46",
|
||
"status_text": "进行中",
|
||
"status_class": "vote-status-active"
|
||
}
|
||
],
|
||
"pagination": {
|
||
"total": 1,
|
||
"page": 1,
|
||
"pageSize": 10,
|
||
"totalPage": 1,
|
||
"offset": 0
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**注意**: 此接口需要用户已登录，否则会返回错误。
|
||
|
||
---
|
||
|
||
# 三、用户API (api/user.php)
|
||
|
||
**接口地址**: `/api/user.php`
|
||
|
||
## 3.1 用户登录
|
||
|
||
**请求方式**: POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：login |
|
||
| username | string | 是 | 用户账号 |
|
||
| password | string | 是 | 用户密码 |
|
||
|
||
---
|
||
|
||
## 3.2 用户注册
|
||
|
||
**请求方式**: POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：register |
|
||
| username | string | 是 | 用户账号 |
|
||
| password | string | 是 | 用户密码 |
|
||
| user_identifier | string | 否 | 用户标识 |
|
||
|
||
---
|
||
|
||
## 3.3 用户登出
|
||
|
||
**请求方式**: GET/POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：logout |
|
||
|
||
**注意**: 登出后会重定向到首页。
|
||
|
||
---
|
||
|
||
## 3.4 获取用户信息
|
||
|
||
**请求方式**: GET/POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：getUserInfo |
|
||
|
||
---
|
||
|
||
## 3.5 更新用户信息（修改密码）
|
||
|
||
**请求方式**: POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：updateUserInfo |
|
||
| new_password | string | 是 | 新密码 |
|
||
| confirm_password | string | 是 | 确认密码 |
|
||
|
||
---
|
||
|
||
## 3.6 更新用户标识
|
||
|
||
**请求方式**: POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：updateUserIdentifier |
|
||
| user_identifier | string | 否 | 用户标识 |
|
||
|
||
---
|
||
|
||
# 四、投票操作API (api/vote.php)
|
||
|
||
**接口地址**: `/api/vote.php`
|
||
|
||
## 4.1 提交投票
|
||
|
||
**请求方式**: POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：submit |
|
||
| topic_id | int | 是 | 投票ID |
|
||
| options | string | 是 | 选项ID，多个用逗号分隔 |
|
||
|
||
---
|
||
|
||
## 4.2 检查是否已投票
|
||
|
||
**请求方式**: GET/POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：checkVoted |
|
||
| topic_id | int | 是 | 投票ID |
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "查询成功",
|
||
"data": {
|
||
"hasVoted": true
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4.3 获取投票结果
|
||
|
||
**请求方式**: GET/POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：getResult |
|
||
| topic_id | int | 是 | 投票ID |
|
||
|
||
---
|
||
|
||
# 五、投票主题管理API (api/topic.php)
|
||
|
||
**接口地址**: `/api/topic.php`
|
||
|
||
**注意**: 大部分接口需要管理员权限
|
||
|
||
## 5.1 获取投票主题列表
|
||
|
||
**请求方式**: GET/POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：getList |
|
||
| page | int | 否 | 当前页码，默认1 |
|
||
| page_size | int | 否 | 每页记录数，默认10 |
|
||
| status | int | 否 | 状态筛选 |
|
||
| type | int | 否 | 类型筛选 |
|
||
| keyword | string | 否 | 关键词搜索 |
|
||
|
||
**权限要求**: 管理员
|
||
|
||
---
|
||
|
||
## 5.2 获取投票主题详情
|
||
|
||
**请求方式**: GET/POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：getDetail |
|
||
| id | int | 是 | 投票ID |
|
||
|
||
---
|
||
|
||
## 5.3 添加投票主题
|
||
|
||
**请求方式**: POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：add |
|
||
| title | string | 是 | 投票标题 |
|
||
| desc | string | 否 | 投票描述 |
|
||
| statime | string | 是 | 开始时间 |
|
||
| endtime | string | 是 | 结束时间 |
|
||
| type | int | 否 | 类型（0:单选, 1:多选），默认0 |
|
||
| maxtime | int | 否 | 多选时最多可选几项，默认1 |
|
||
| status | int | 否 | 状态，默认1 |
|
||
|
||
**权限要求**: 管理员
|
||
|
||
---
|
||
|
||
## 5.4 更新投票主题
|
||
|
||
**请求方式**: POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：update |
|
||
| id | int | 是 | 投票ID |
|
||
| title | string | 是 | 投票标题 |
|
||
| desc | string | 否 | 投票描述 |
|
||
| statime | string | 是 | 开始时间 |
|
||
| endtime | string | 是 | 结束时间 |
|
||
| type | int | 否 | 类型 |
|
||
| maxtime | int | 否 | 多选时最多可选几项 |
|
||
| status | int | 否 | 状态 |
|
||
|
||
**权限要求**: 管理员
|
||
|
||
---
|
||
|
||
## 5.5 删除投票主题
|
||
|
||
**请求方式**: POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：delete |
|
||
| id | int | 是 | 投票ID |
|
||
|
||
**权限要求**: 管理员
|
||
|
||
**注意**: 删除投票主题会同时删除相关的选项和投票记录。
|
||
|
||
---
|
||
|
||
## 5.6 获取投票选项
|
||
|
||
**请求方式**: GET/POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：getOptions |
|
||
| topic_id | int | 是 | 投票ID |
|
||
|
||
---
|
||
|
||
## 5.7 添加投票选项
|
||
|
||
**请求方式**: POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：addOption |
|
||
| topic_id | int | 是 | 投票ID |
|
||
| name | string | 是 | 选项名称 |
|
||
| imgs | string | 否 | 选项图片URL |
|
||
| desc | string | 否 | 选项描述 |
|
||
| sort | int | 否 | 排序值，默认0 |
|
||
|
||
**权限要求**: 管理员
|
||
|
||
---
|
||
|
||
## 5.8 更新投票选项
|
||
|
||
**请求方式**: POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：updateOption |
|
||
| id | int | 是 | 选项ID |
|
||
| name | string | 是 | 选项名称 |
|
||
| imgs | string | 否 | 选项图片URL |
|
||
| desc | string | 否 | 选项描述 |
|
||
| sort | int | 否 | 排序值 |
|
||
|
||
**权限要求**: 管理员
|
||
|
||
---
|
||
|
||
## 5.9 删除投票选项
|
||
|
||
**请求方式**: POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：deleteOption |
|
||
| id | int | 是 | 选项ID |
|
||
|
||
**权限要求**: 管理员
|
||
|
||
**注意**: 删除选项会同时删除相关的投票记录。
|
||
|
||
---
|
||
|
||
# 六、管理员API (api/admin.php)
|
||
|
||
**接口地址**: `/api/admin.php`
|
||
|
||
**权限要求**: 所有接口都需要管理员权限
|
||
|
||
## 6.1 添加用户
|
||
|
||
**请求方式**: POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：addUser |
|
||
| username | string | 是 | 用户名（手机号） |
|
||
| password | string | 是 | 密码 |
|
||
| role | int | 否 | 角色（0:普通用户, 1:管理员），默认0 |
|
||
|
||
---
|
||
|
||
## 6.2 更新用户信息
|
||
|
||
**请求方式**: POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：updateUser |
|
||
| id | int | 是 | 用户ID |
|
||
| role | int | 否 | 角色 |
|
||
| status | int | 否 | 状态 |
|
||
|
||
---
|
||
|
||
## 6.3 重置用户密码
|
||
|
||
**请求方式**: POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：resetPassword |
|
||
| id | int | 是 | 用户ID |
|
||
| password | string | 是 | 新密码 |
|
||
|
||
---
|
||
|
||
## 6.4 获取投票统计数据
|
||
|
||
**请求方式**: GET/POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：getVoteStats |
|
||
| topic_id | int | 否 | 投票ID，不传则返回所有投票统计 |
|
||
|
||
**响应示例** (指定投票):
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "获取成功",
|
||
"data": {
|
||
"vote": { ... },
|
||
"options": [
|
||
{
|
||
"id": 1,
|
||
"name": "苹果",
|
||
"count": 50,
|
||
"percentage": 50
|
||
}
|
||
],
|
||
"totalVotes": 100,
|
||
"participants": [
|
||
{
|
||
"username": "13800138000",
|
||
"vote_time": "2026-03-27 10:00:00",
|
||
"ip": "127.0.0.1"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6.5 获取系统日志
|
||
|
||
**请求方式**: GET/POST
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| act | string | 是 | 操作类型，固定值：getLogs |
|
||
| page | int | 否 | 当前页码，默认1 |
|
||
| page_size | int | 否 | 每页记录数，默认20 |
|
||
| user_id | int | 否 | 用户ID筛选 |
|
||
| action | string | 否 | 操作类型筛选 |
|
||
| start_date | string | 否 | 开始日期 |
|
||
| end_date | string | 否 | 结束日期 |
|
||
|
||
---
|
||
|
||
# 七、文件上传API (api/upload.php)
|
||
|
||
**接口地址**: `/api/upload.php`
|
||
|
||
**权限要求**: 需要用户登录
|
||
|
||
## 7.1 上传图片
|
||
|
||
**请求方式**: POST (multipart/form-data)
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| image | file | 是 | 图片文件 |
|
||
|
||
**支持的图片格式**: JPG, PNG, GIF, WEBP
|
||
|
||
**文件大小限制**: 最大10MB
|
||
|
||
**图片处理**: 宽度大于1280px的图片会自动调整为1024px宽度
|
||
|
||
**响应示例** (成功):
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "上传成功",
|
||
"data": {
|
||
"url": "uploads/img_123456789_20260329.jpg",
|
||
"width": 1024,
|
||
"height": 768
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码说明**:
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 1001 | 请先登录 |
|
||
| 1002 | 请求方法错误 |
|
||
| 1003 | 上传失败 |
|
||
| 1004 | 只允许上传JPG、PNG、GIF和WEBP格式的图片 |
|
||
| 1005 | 文件大小超过限制，最大允许10MB |
|
||
| 1006 | 无效的图片文件 |
|
||
| 1007 | 不支持的图片格式 |
|
||
| 1008 | 文件保存失败 |
|
||
|
||
---
|
||
|
||
# 八、跨域支持
|
||
|
||
本API已启用CORS，支持跨域请求。相关响应头：
|
||
|
||
```
|
||
Access-Control-Allow-Origin: *
|
||
Access-Control-Allow-Methods: GET, POST, OPTIONS
|
||
Access-Control-Allow-Headers: Content-Type, Authorization
|
||
```
|
||
|
||
对于OPTIONS预检请求，API会直接返回200状态码。
|
||
|
||
---
|
||
|
||
# 九、注意事项
|
||
|
||
1. **Session管理**: 登录成功后，服务器会创建session，后续请求需要携带session cookie
|
||
2. **密码安全**: 密码使用PHP的password_hash()函数加密存储
|
||
3. **参数验证**: 所有输入参数都经过安全过滤，防止SQL注入和XSS攻击
|
||
4. **错误处理**: 所有接口都有完善的错误处理机制，返回明确的错误信息
|
||
5. **日志记录**: 重要操作（登录、注册、登出、投票）都会记录到系统日志中
|
||
6. **投票限制**: 每个用户对每个投票只能投一次
|
||
7. **权限控制**: 管理员接口需要验证用户角色（irole=1）
|
||
|
||
---
|
||
|
||
# 十、使用示例
|
||
|
||
## JavaScript (Fetch API)
|
||
|
||
```javascript
|
||
// 登录示例
|
||
fetch('https://poe.vogov.cn/toupiao/tapi.php', {
|
||
method: 'POST',
|
||
headers: {
|
||
'Content-Type': 'application/json'
|
||
},
|
||
body: JSON.stringify({
|
||
act: 'login',
|
||
username: '13800138000',
|
||
password: '123456'
|
||
}),
|
||
credentials: 'include' // 携带cookie
|
||
})
|
||
.then(response => response.json())
|
||
.then(data => {
|
||
if (data.code === 0) {
|
||
console.log('登录成功', data.data);
|
||
} else {
|
||
console.error('登录失败', data.msg);
|
||
}
|
||
});
|
||
|
||
// 获取投票列表
|
||
fetch('https://poe.vogov.cn/toupiao/vote_api.php?act=getVoteList&page=1&pageSize=10', {
|
||
credentials: 'include'
|
||
})
|
||
.then(response => response.json())
|
||
.then(data => {
|
||
if (data.code === 0) {
|
||
console.log('投票列表', data.data.list);
|
||
}
|
||
});
|
||
|
||
// 提交投票
|
||
fetch('https://poe.vogov.cn/toupiao/vote_api.php', {
|
||
method: 'POST',
|
||
headers: {
|
||
'Content-Type': 'application/json'
|
||
},
|
||
body: JSON.stringify({
|
||
act: 'submitVote',
|
||
topic_id: 1,
|
||
options: [1, 2]
|
||
}),
|
||
credentials: 'include'
|
||
})
|
||
.then(response => response.json())
|
||
.then(data => {
|
||
if (data.code === 0) {
|
||
console.log('投票成功');
|
||
}
|
||
});
|
||
```
|
||
|
||
## Flutter (Dio)
|
||
|
||
```dart
|
||
import 'package:dio/dio.dart';
|
||
|
||
final dio = Dio(BaseOptions(
|
||
baseUrl: 'https://poe.vogov.cn/toupiao/',
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
},
|
||
));
|
||
|
||
// 登录
|
||
final response = await dio.post('tapi.php', data: {
|
||
'act': 'login',
|
||
'username': '13800138000',
|
||
'password': '123456',
|
||
});
|
||
|
||
if (response.data['code'] == 0) {
|
||
print('登录成功: ${response.data['data']}');
|
||
}
|
||
|
||
// 获取投票列表
|
||
final voteResponse = await dio.get('vote_api.php', queryParameters: {
|
||
'act': 'getVoteList',
|
||
'page': 1,
|
||
'pageSize': 10,
|
||
});
|
||
|
||
if (voteResponse.data['code'] == 0) {
|
||
final list = voteResponse.data['data']['list'];
|
||
print('投票列表: $list');
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
# 十一、版本历史
|
||
|
||
- **V1.3** (2026-03-29): 完善API文档，添加数据库结构说明，添加所有API接口详细文档
|
||
- **V1.2** (2026-03-27): 添加了更新用户标识接口，允许用户在登录后更新自己的用户标识
|
||
- **V1.1** (2026-03-27): 添加了用户标识字段(user_identifier)，允许用户在注册时提供可选的用户标识
|
||
- **V1.0** (2026-03-27): 初始版本，提供用户登录、注册、获取用户信息和登出功能
|
||
|
||
---
|
||
|
||
*最后更新时间: 2026-03-29*
|