账务模块

账务模块面向财务人员，提供收支报表、总账流水、对账管理和增值税发票审核功能。

7.1 收支报表

月度收支报表

GET /api/v1/accounting/statements

查询参数	说明
`year`	年份，如 `2024`
`month`	月份，如 `1`（可选，不传则返回全年）

{
  "code": 0,
  "data": {
    "items": [
      {
        "period": "2024-01",
        "income": {
          "recharge": "5000.00",
          "gift": "200.00",
          "total": "5200.00"
        },
        "expense": {
          "consume": "4200.00",
          "refund_out": "50.00",
          "total": "4250.00"
        },
        "net": "950.00",
        "currency": "CNY"
      }
    ]
  }
}

导出收支报表

GET /api/v1/accounting/statements/export

查询参数	说明
`year`	年份
`format`	`csv` / `xlsx`

7.2 总账流水

GET /api/v1/accounting/ledger

查询参数	说明
`start_date`	开始日期
`end_date`	结束日期
`type`	资金变动类型
`page`	页码
`page_size`	每页条数

{
  "code": 0,
  "data": {
    "items": [
      {
        "ledger_id": "ldg_001",
        "type": "recharge",
        "amount": "+100.00",
        "user_id": "u_01HX...",
        "description": "用户充值 - 支付宝",
        "created_at": "2024-01-01T12:05:00Z"
      }
    ],
    "total": 15234
  }
}

7.3 对账管理（管理员）

对账记录列表

GET /admin/v1/accounting/reconciliation

{
  "code": 0,
  "data": {
    "items": [
      {
        "recon_id": "recon_20240101",
        "period": "2024-01-01",
        "channel": "alipay",
        "status": "matched",
        "platform_count": 125,
        "channel_count": 125,
        "diff_count": 0,
        "initiated_at": "2024-01-02T02:00:00Z",
        "completed_at": "2024-01-02T02:05:00Z"
      }
    ]
  }
}

发起对账

POST /admin/v1/accounting/reconciliation

{
  "period": "2024-01-01",
  "channel": "alipay"
}

channel 枚举：alipay / wechat / baofoo

响应：

{
  "code": 0,
  "data": {
    "recon_id": "recon_20240101",
    "status": "processing",
    "estimated_seconds": 60
  }
}

对账详情

GET /admin/v1/accounting/reconciliation/{recon_id}

{
  "code": 0,
  "data": {
    "recon_id": "recon_20240101",
    "period": "2024-01-01",
    "channel": "alipay",
    "status": "diff_found",
    "platform_count": 125,
    "channel_count": 124,
    "diff_count": 1,
    "diffs": [
      {
        "order_id": "rch_20240101099",
        "platform_status": "paid",
        "channel_status": "not_found",
        "amount": "200.00",
        "diff_type": "platform_only"
      }
    ]
  }
}

确认对账结果

PUT /admin/v1/accounting/reconciliation/{recon_id}/confirm

{
  "action": "accept",
  "note": "已核实，支付平台数据延迟"
}

7.4 增值税发票管理（管理员）

开票申请列表

GET /admin/v1/accounting/vat-invoices

查询参数	说明
`status`	`pending` / `processing` / `completed` / `rejected`
`start_date`	开始日期

{
  "code": 0,
  "data": {
    "items": [
      {
        "invoice_id": "inv_req_01HX...",
        "user_id": "u_01HX...",
        "enterprise_name": "XX 科技有限公司",
        "invoice_type": "vat_special",
        "total_amount": "500.00",
        "status": "pending",
        "submitted_at": "2024-01-05T10:00:00Z"
      }
    ]
  }
}

处理开票申请（通过）

PUT /admin/v1/accounting/vat-invoices/{invoice_id}/process

{
  "invoice_number": "1234567890",
  "invoice_file_url": "https://oss.example.com/invoices/xxx.pdf"
}

拒绝开票申请

PUT /admin/v1/accounting/vat-invoices/{invoice_id}/reject

{
  "reason": "税号填写有误，请重新提交"
}

07-accounting-api.md