tyapi-server/docs/发票API接口文档.md

# 发票API接口文档

## 概述

本文档描述了发票管理相关的API接口，包括用户申请开票和管理员处理开票申请的功能。

## 基础信息

- **Base URL**: `http://localhost:8080`
- **认证方式**: Bearer Token (JWT)
- **Content-Type**: `application/json`

## 用户接口

### 1. 申请开票

**接口地址**: `POST /api/v1/invoices/apply`

**请求参数**:
```json
{
  "invoice_type": "general",  // 发票类型: general(普票) | special(专票)
  "amount": "1000.00",        // 开票金额
  "invoice_info": {
    "company_name": "海南省学宇思网络科技有限公司",
    "taxpayer_id": "91460108MADNY3F43W",
    "bank_name": "中国银行海口分行",           // 专票必填
    "bank_account": "1234567890123456",      // 专票必填
    "company_address": "海南省海口市",        // 专票必填
    "company_phone": "0898-12345678",        // 专票必填
    "receiving_email": "ilirnax@gmail.com"
  }
}
```

**响应示例**:
```json
{
  "success": true,
  "message": "申请开票成功",
  "data": {
    "id": "uuid",
    "user_id": "user_uuid",
    "invoice_type": "general",
    "amount": "1000.00",
    "status": "pending",
    "invoice_info": {
      "company_name": "海南省学宇思网络科技有限公司",
      "taxpayer_id": "91460108MADNY3F43W",
      "receiving_email": "ilirnax@gmail.com"
    },
    "created_at": "2024-01-01T12:00:00Z"
  }
}
```

### 2. 获取用户发票信息

**接口地址**: `GET /api/v1/invoices/info`

**响应示例**:
```json
{
  "success": true,
  "message": "获取发票信息成功",
  "data": {
    "company_name": "海南省学宇思网络科技有限公司",
    "taxpayer_id": "91460108MADNY3F43W",
    "bank_name": "",
    "bank_account": "",
    "company_address": "",
    "company_phone": "",
    "receiving_email": "ilirnax@gmail.com",
    "is_complete": false,
    "missing_fields": ["基本开户银行", "基本开户账号", "企业注册地址", "企业注册电话"]
  }
}
```

### 3. 更新用户发票信息

**接口地址**: `PUT /api/v1/invoices/info`

**请求参数**:
```json
{
  "company_name": "海南省学宇思网络科技有限公司",
  "taxpayer_id": "91460108MADNY3F43W",
  "bank_name": "中国银行海口分行",
  "bank_account": "1234567890123456",
  "company_address": "海南省海口市",
  "company_phone": "0898-12345678",
  "receiving_email": "ilirnax@gmail.com"
}
```

### 4. 获取用户开票记录

**接口地址**: `GET /api/v1/invoices/records?page=1&page_size=10&status=completed`

**查询参数**:
- `page`: 页码 (默认: 1)
- `page_size`: 每页数量 (默认: 10, 最大: 100)
- `status`: 状态筛选 (可选: pending, completed, rejected)

**响应示例**:
```json
{
  "success": true,
  "message": "获取开票记录成功",
  "data": {
    "records": [
      {
        "id": "uuid",
        "user_id": "user_uuid",
        "invoice_type": "general",
        "amount": "1000.00",
        "status": "completed",
        "company_name": "海南省学宇思网络科技有限公司",
        "file_name": "invoice_20240101.pdf",
        "file_size": 1024000,
        "file_url": "https://example.com/invoice.pdf",
        "processed_at": "2024-01-01T14:00:00Z",
        "created_at": "2024-01-01T12:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 10,
    "total_pages": 1
  }
}
```

### 5. 获取可开票金额

**接口地址**: `GET /api/v1/invoices/available-amount`

**响应示例**:
```json
{
  "success": true,
  "message": "获取可开票金额成功",
  "data": {
    "available_amount": "5000.00",
    "total_recharged": "10000.00",
    "total_gifted": "1000.00",
    "total_invoiced": "4000.00"
  }
}
```

### 6. 下载发票文件

**接口地址**: `GET /api/v1/invoices/{application_id}/download`

**响应示例**:
```json
{
  "success": true,
  "message": "获取下载信息成功",
  "data": {
    "file_id": "file_uuid",
    "file_name": "invoice_20240101.pdf",
    "file_size": 1024000,
    "file_url": "https://example.com/invoice.pdf"
  }
}
```

## 管理员接口

### 1. 获取待处理的发票申请列表

**接口地址**: `GET /api/v1/admin/invoices/pending?page=1&page_size=10`

**响应示例**:
```json
{
  "success": true,
  "message": "获取待处理申请列表成功",
  "data": {
    "applications": [
      {
        "id": "uuid",
        "user_id": "user_uuid",
        "invoice_type": "general",
        "amount": "1000.00",
        "status": "pending",
        "company_name": "海南省学宇思网络科技有限公司",
        "receiving_email": "ilirnax@gmail.com",
        "created_at": "2024-01-01T12:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 10,
    "total_pages": 1
  }
}
```

### 2. 通过发票申请（上传发票）

**接口地址**: `POST /api/v1/admin/invoices/{application_id}/approve`

**请求方式**: `multipart/form-data`

**请求参数**:
- `file`: 发票文件 (PDF格式)
- `admin_notes`: 管理员备注 (可选)

**响应示例**:
```json
{
  "success": true,
  "message": "通过发票申请成功",
  "data": null
}
```

### 3. 拒绝发票申请

**接口地址**: `POST /api/v1/admin/invoices/{application_id}/reject`

**请求参数**:
```json
{
  "reason": "发票信息不完整，请补充企业注册地址和电话"
}
```

**响应示例**:
```json
{
  "success": true,
  "message": "拒绝发票申请成功",
  "data": null
}
```

## 错误码说明

| 状态码 | 说明 |
|--------|------|
| 200 | 请求成功 |
| 400 | 请求参数错误 |
| 401 | 用户未登录或认证已过期 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

## 业务规则

### 开票金额限制
- 用户只能申请充值金额（除去赠送）减去已开票金额
- 开票金额必须大于0

### 发票信息验证
- **普票**: 至少需要公司名称、纳税人识别号、接收邮箱
- **专票**: 需要完整的企业信息（包括银行信息、地址、电话）

### 状态流转
- `pending` (待处理) → `completed` (已完成) 或 `rejected` (已拒绝)

### 文件要求
- 发票文件格式：PDF
- 文件大小限制：10MB
- 文件命名：`invoice_{application_id}.pdf`

## 注意事项

1. 所有接口都需要JWT认证
2. 管理员接口需要管理员权限
3. 文件上传接口使用 `multipart/form-data` 格式
4. 金额字段使用字符串格式，精确到分
5. 时间字段使用ISO 8601格式