billai/server

BillAI 服务器 API 文档

概述

BillAI 服务器是一个基于 Go 的后端服务，用于处理账单的上传、清洗、分析和存储。提供 REST API 接口供前端调用。

服务地址: http://localhost:8080

---

API 接口列表

1. 健康检查

端点: GET /health

功能: 检查服务器健康状态

参数: 无

响应示例:

{
  "status": "ok",
  "version": "1.0.0"
}

---

账单管理 API

2. 上传账单文件

端点: POST /api/upload

功能: 上传支付宝或微信账单文件进行清洗和分析

请求方式: multipart/form-data

请求参数:

参数名	类型	必需	说明
file	File	✓	账单文件（CSV格式）
type	string	✓	账单类型：alipay 或 wechat
format	string	-	输出格式：csv 或 json（默认: csv）
year	number	-	账单年份（用于数据验证）
month	number	-	账单月份（用于数据验证）

响应示例 (成功):

{
  "result": true,
  "message": "账单处理完成",
  "data": {
    "bill_type": "alipay",
    "raw_count": 50,
    "cleaned_count": 48,
    "duplicate_count": 2,
    "needs_review_count": 5,
    "file_name": "20260110_150405_alipay_1.csv"
  }
}

响应示例 (全部重复):

{
  "result": true,
  "message": "文件中的 50 条记录全部已存在，无需重复导入",
  "data": {
    "bill_type": "alipay",
    "raw_count": 0,
    "cleaned_count": 0,
    "duplicate_count": 50
  }
}

响应示例 (失败):

{
  "result": false,
  "message": "账单类型无效，仅支持 alipay 或 wechat"
}

---

3. 获取账单列表

端点: GET /api/bills

功能: 获取清洗后的账单数据，支持分页、筛选和排序

请求参数 (Query):

参数名	类型	必需	说明
page	number	-	页码（从1开始，默认: 1）
page_size	number	-	每页数量（默认: 20，最大: 100）
start_date	string	-	开始日期（YYYY-MM-DD 格式）
end_date	string	-	结束日期（YYYY-MM-DD 格式）
category	string	-	交易分类筛选
type	string	-	账单来源：alipay、wechat 或 manual
income_expense	string	-	收支类型：收入 或 支出

响应示例:

{
  "result": true,
  "data": {
    "total": 150,
    "page": 1,
    "page_size": 20,
    "pages": 8,
    "total_expense": 5250.50,
    "total_income": 8000.00,
    "bills": [
      {
        "_id": "507f1f77bcf86cd799439011",
        "bill_type": "alipay",
        "transaction_id": "2021123456789",
        "merchant_order_no": "2021123456",
        "time": "2026-01-10T10:30:00Z",
        "category": "餐饮美食",
        "merchant": "星巴克",
        "description": "咖啡",
        "income_expense": "支出",
        "amount": 28.00,
        "pay_method": "支付宝",
        "status": "交易成功",
        "remark": "员工补贴",
        "review_level": "",
        "created_at": "2026-01-10T10:30:00Z",
        "updated_at": "2026-01-10T10:30:00Z",
        "source_file": "20260110_150405_alipay_1.csv",
        "upload_batch": "20260110_150405"
      }
    ]
  }
}

错误响应:

{
  "result": false,
  "message": "数据库未连接"
}

---

4. 手动创建账单

端点: POST /api/bills/manual

功能: 手动添加单条或批量账单，支持去重

请求方式: application/json

请求体:

{
  "bills": [
    {
      "time": "2026-01-10 14:30:00",
      "category": "餐饮美食",
      "merchant": "测试餐厅",
      "description": "午餐",
      "income_expense": "支出",
      "amount": 50.00,
      "pay_method": "支付宝",
      "status": "交易成功",
      "remark": "测试账单"
    }
  ]
}

请求参数说明:

参数名	类型	必需	说明
bills	Array	✓	账单数组
bills[].time	string	✓	交易时间（格式: YYYY-MM-DD HH:mm:ss）
bills[].category	string	✓	交易分类
bills[].income_expense	string	✓	收支类型：收入 或 支出
bills[].amount	number	✓	金额（>0）
bills[].merchant	string	-	交易对方（可选）
bills[].description	string	-	商品说明
bills[].pay_method	string	-	支付方式
bills[].status	string	-	交易状态（默认: 交易成功）
bills[].remark	string	-	备注

响应示例 (成功):

{
  "result": true,
  "message": "创建成功",
  "data": {
    "success": 1,
    "failed": 0,
    "duplicates": 0
  }
}

响应示例 (部分失败):

{
  "result": true,
  "message": "创建成功",
  "data": {
    "success": 3,
    "failed": 1,
    "duplicates": 0
  }
}

错误响应:

{
  "result": false,
  "message": "时间格式错误: 2026-01-10"
}

---

5. 获取需要复核的记录

端点: GET /api/review

功能: 获取清洗过程中标记为需要人工复核的记录

请求参数 (Query):

参数名	类型	必需	说明
file	string	✓	输出文件名（来自上传接口返回值）
page	number	-	页码（默认: 1）
page_size	number	-	每页数量（默认: 20）

响应示例:

{
  "result": true,
  "data": {
    "total": 5,
    "page": 1,
    "page_size": 20,
    "high_count": 2,
    "low_count": 3,
    "records": [
      {
        "row": 15,
        "time": "2026-01-10 10:30:00",
        "merchant": "未知商户",
        "amount": 100.00,
        "category": "未分类",
        "review_level": "HIGH",
        "issue": "无法识别的商户名称",
        "suggestion": "请手动确认或修改商户名称"
      }
    ]
  }
}

---

6. 获取月度统计数据

端点: GET /api/monthly-stats

功能: 获取每个月的收入、支出统计（不受日期筛选影响，返回全部月份数据）

请求参数: 无

响应示例:

{
  "result": true,
  "data": [
    {
      "month": "2025-12",
      "expense": 8234.50,
      "income": 15000.00
    },
    {
      "month": "2026-01",
      "expense": 5250.50,
      "income": 8000.00
    }
  ]
}

错误响应:

{
  "result": false,
  "message": "数据库未连接"
}

---

数据模型

账单数据 (CleanedBill)

type CleanedBill struct {
    ID                primitive.ObjectID `bson:"_id,omitempty" json:"_id"`
    BillType          string             `bson:"bill_type" json:"bill_type"`           // alipay/wechat/manual
    TransactionID     string             `bson:"transaction_id" json:"transaction_id"`
    MerchantOrderNo   string             `bson:"merchant_order_no" json:"merchant_order_no"`
    Time              time.Time          `bson:"time" json:"time"`
    Category          string             `bson:"category" json:"category"`
    Merchant          string             `bson:"merchant" json:"merchant"`
    Description       string             `bson:"description" json:"description"`
    IncomeExpense     string             `bson:"income_expense" json:"income_expense"`   // 收入/支出
    Amount            float64            `bson:"amount" json:"amount"`
    PayMethod         string             `bson:"pay_method" json:"pay_method"`
    Status            string             `bson:"status" json:"status"`
    Remark            string             `bson:"remark" json:"remark"`
    ReviewLevel       string             `bson:"review_level" json:"review_level"`       // HIGH/LOW/""
    CreatedAt         time.Time          `bson:"created_at" json:"created_at"`
    UpdatedAt         time.Time          `bson:"updated_at" json:"updated_at"`
    SourceFile        string             `bson:"source_file" json:"source_file"`
    UploadBatch       string             `bson:"upload_batch" json:"upload_batch"`
}

月度统计 (MonthlyStat)

type MonthlyStat struct {
    Month   string  `bson:"month" json:"month"`       // YYYY-MM
    Expense float64 `bson:"expense" json:"expense"`   // 支出总额
    Income  float64 `bson:"income" json:"income"`     // 收入总额
}

---

错误处理

所有 API 响应都遵循以下格式：

{
  "result": boolean,
  "message": "错误或成功消息",
  "data": {}
}

常见错误码

HTTP 状态码	result	说明
200	true	请求成功
200	false	业务逻辑错误（如参数不合法）
400	false	请求参数错误
404	false	资源不存在
500	false	服务器内部错误

---

时区说明

• 存储: 所有时间在数据库中按 UTC 时区 存储（ISO 8601 格式）
• 输入: 手动添加账单时，时间按 本地时区 解析（使用 time.ParseInLocation）
• 输出: API 返回的时间均为 ISO 8601 UTC 格式

时间格式

• 手动创建账单时: YYYY-MM-DD HH:mm:ss（本地时间）
• 日期筛选参数: YYYY-MM-DD（本地日期）
• API 返回时间: ISO 8601 UTC 格式（如 2026-01-10T10:30:00Z）

---

使用示例

上传账单文件

curl -X POST http://localhost:8080/api/upload \
  -F "file=@statement.csv" \
  -F "type=alipay" \
  -F "format=csv"

查询账单列表

curl "http://localhost:8080/api/bills?page=1&page_size=20&start_date=2026-01-01&end_date=2026-01-10&type=alipay"

手动添加账单

curl -X POST http://localhost:8080/api/bills/manual \
  -H "Content-Type: application/json" \
  -d '{
    "bills": [
      {
        "time": "2026-01-10 14:30:00",
        "category": "餐饮美食",
        "merchant": "星巴克",
        "income_expense": "支出",
        "amount": 28.00,
        "pay_method": "支付宝"
      }
    ]
  }'

获取月度统计

curl http://localhost:8080/api/monthly-stats

---

配置

服务器配置文件位于 config.yaml，主要配置项：

server:
  port: "8080"

mongodb:
  uri: "mongodb://admin:password@localhost:27017"
  database: "billai"
  collections:
    raw: "bills_raw"
    cleaned: "bills_cleaned"

analyzer:
  mode: "http"  # http 或 process
  url: "http://analyzer:8001"

---

开发信息

目录结构

server/
├── main.go              # 程序入口
├── router/              # 路由配置
├── handler/             # 请求处理器
├── service/             # 业务逻辑
├── repository/          # 数据访问层
├── database/            # 数据库连接
├── model/               # 数据模型
├── adapter/             # 外部服务适配器
├── config/              # 配置管理
└── README.md            # 本文件

主要依赖

• Gin: Web 框架
• MongoDB Driver: 数据库驱动
• Go 1.21: 运行环境

---

版本历史

版本	日期	说明
1.0.0	2026-01-10	初始版本，支持账单上传、查询、手动添加和统计