# 投票系统 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*