520kiss/wushu
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9175ff99051739fbd0bc47deeb317c263da01573
wushu/ht/API_投票.md
Developer 9175ff9905 Initial commit: Flutter 无书应用项目
2026-03-30 02:35:31 +08:00

28 KiB
Raw Blame History

投票系统 API 接口文档

概述

本文档描述了投票系统的所有API接口，包括用户管理、投票操作、投票主题管理、管理员功能和文件上传等功能。该API支持GET和POST两种请求方式，并支持JSON格式的请求体。

基础信息

  • 基础URL: https://poe.vogov.cn/toupiao/
  • 请求方式: GET / POST
  • 数据格式: JSON
  • 字符编码: UTF-8
  • 跨域支持: 已启用CORS

通用响应格式

所有接口返回统一的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"
}

响应示例 (成功):

{
  "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"
}

响应示例 (成功):

{
  "code": 0,
  "msg": "注册成功",
  "data": {}
}

错误码说明:

错误码 说明
1 账号和密码不能为空
1 请输入正确的手机号、邮箱或微信号
1 密码长度不能少于6位
1 该账号已被注册
1 注册失败，请稍后重试

1.3 获取用户信息

接口描述: 获取当前登录用户的详细信息

请求方式: GET / POST

请求参数:

参数名 类型 必填 说明
act string 是 操作类型，固定值：getUserInfo

请求示例:

GET /tapi.php?act=getUserInfo

响应示例 (成功):

{
  "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

响应示例 (成功):

{
  "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"
}

响应示例 (成功):

{
  "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

响应示例 (成功):

{
  "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

响应示例 (成功):

{
  "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]
}

响应示例 (成功):

{
  "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

响应示例 (成功):

{
  "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

响应示例 (成功):

{
  "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

响应示例:

{
  "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，不传则返回所有投票统计

响应示例 (指定投票):

{
  "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宽度

响应示例 (成功):

{
  "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)

// 登录示例
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)

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

Reference in New Issue View Git Blame Copy Permalink