一本账 · API 设计

1
// 成功
2
{ "code": 0, "data": { /* 业务数据 */ } }
3
// 失败
4
{ "code": 40101, "message": "验证码错误或已过期", "request_id": "req_abc123" }

1
// 请求
2
{ "phone": "13800138000", "scene": "login" }   // scene: login | delete_account（登录未注册自动注册，无独立注册场景）
3
// 响应 data
4
{ "retry_after": 60 }

1
// 请求
2
{ "phone": "13800138000", "sms_code": "123456" }
3
// 响应 data
4
{ "access_token": "...", "refresh_token": "...", "expires_in": 7200, "user": { "id": 1, "phone": "138****8000", "nickname": "用户8000", "avatar_url": null } }

1
// 请求 { "refresh_token": "..." } → 响应同 login（轮换：旧 refreshToken 失效）

1
// 请求（均可选）
2
{ "nickname": "阿明", "avatar_url": "https://oss.../a.jpg" }

1
// 响应 data
2
{ "upload_url": "https://oss...?sig=...", "avatar_url": "https://oss.../a.jpg" }

1
// 响应 data.list[]
2
{ "id": 42, "name": "我们的家", "cover_color": "#4C7DFF", "owner_user_id": 1,
3
  "member_count": 3, "version": 1041, "my_role": 1, "last_txn_at": "2025-08-31T08:00:00Z" }

1
// 请求 { "name": "我们的家", "cover_color": "#4C7DFF" }
2
// 响应：创建者自动成为 owner 成员；返回完整账本对象

1
// 响应 data.list[]
2
{ "user_id": 2, "nickname": "老婆", "nickname_in_ledger": "老婆", "avatar_url": "...",
3
  "role": 2, "joined_at": "...", "txn_count_this_month": 45 }

1
// 响应 data
2
{ "code": "482913", "expires_at": "2025-09-01T00:00:00Z" }   // 24h 有效，6 位数字

1
// 请求 { "code": "482913" }
2
// 响应 data：账本对象 + 我的角色（member）；错误：40903 无效/过期，40904 已是成员

1
// 查询参数：page, page_size, start_date, end_date,
2
//           member_id(按付款人 payer), payee_id(为谁花，命中 payee_ids 数组), category_id, type(1/2/3)
3
// 响应 data
4
{ "list": [ {
5
    "id": 901, "client_txn_id": "u1-uuid-...", "type": 1, "amount": 3500,   // 35.00 元
6
    "category": { "id": 11, "name": "餐饮", "icon": "food" },
7
    "payer": { "user_id": 1, "nickname": "阿明" },
8
    "payee_ids": [1, 2], "txn_date": "2025-08-31", "note": "午饭",
9
    "created_by": 1, "updated_by": 1,
10
    "created_at": "2025-08-31T04:30:00Z", "updated_at": "2025-08-31T04:30:00Z" } ],
11
  "total": 128, "has_more": true }

1
// 请求
2
{ "client_txn_id": "u1-uuid-...", "type": 1, "amount": 3500, "category_id": 11,
3
  "payer_id": 1, "payee_ids": [1, 2], "txn_date": "2025-08-31", "note": "午饭" }
4
// 响应：完整账目对象（含服务端 id 与 updated_at）；client_txn_id 重复时返回已存在对象（幂等）

1
// 查询参数：period=2025-08
2
// 响应 data
3
{ "income": 2500000, "expense": 875000, "net": 1625000,        // 单位：分
4
  "prev_expense": 920000, "expense_change_pct": -4.9,
5
  "txn_count": 128, "member_count": 3 }

1
// 响应 data.list[]
2
{ "category_id": 11, "name": "餐饮", "icon": "food", "amount": 312000, "pct": 35.7, "txn_count": 45 }

1
// 响应 data.list[]
2
{ "user_id": 1, "nickname": "阿明", "expense_amount": 412000, "expense_pct": 47.1, "txn_count": 61 }

1
// 响应 data.list[]
2
{ "period": "2025-06", "income": 2500000, "expense": 920000 }

1
// 请求 { "amount": 500000 }   // 5000 元 → 500000 分
2
// 响应：预算对象 { "ledger_id": 42, "period": "2025-09", "amount": 500000, "usage": 87500, "pct": 17.5 }

1
// 响应 data
2
{ "period": "2025-08", "amount": 500000, "usage": 437500, "pct": 87.5, "alert_level": 1 }  // 0 正常 1 超80% 2 超100%

1
// 请求（单批上限 100 条）
2
{ "ledger_id": 42, "items": [ {
3
    "client_txn_id": "u1-uuid-...", "type": 1, "amount": 3500, "category_id": 11,
4
    "payer_id": 1, "payee_ids": [1], "txn_date": "2025-08-30", "note": "地铁",
5
    "client_created_at": "2025-08-30T22:00:00Z" } ] }
6
// 响应 data
7
{ "results": [ { "client_txn_id": "u1-uuid-...", "server_id": 902, "status": "created" } ],
8
  // status: created | duplicated(幂等命中) | failed + reason
9
  "ledger_version": 1042 }

1
// 查询参数：ledger_id, since_version, limit(默认 500，单次返回变更条数上限)
2
// 响应 data
3
{ "ledger_version": 1045, "has_more": false, "next_since": 1045,
4
  "ledgers":      { "upserts": [ /* 账本对象（改名/封面/转让）*/ ], "deletes": [ /* id 数组，含解散 */ ] },
5
  "transactions": { "upserts": [ /* 完整账目对象数组 */ ], "deletes": [ /* id 数组 */ ] },
6
  "members":    { "upserts": [], "deletes": [] },
7
  "budgets":    { "upserts": [], "deletes": [] },
8
  "categories": { "upserts": [], "deletes": [] } }

1
// 响应 data.list[]
2
{ "id": 12, "type": "budget_alert", "ledger_id": 42, "title": "预算提醒",
3
  "content": "「我们的家」本月支出已达预算的 80%", "is_read": false, "created_at": "2025-08-31T12:00:00Z" }

1
// ↑ 客户端 → 服务端
2
{ "event": "auth",     "data": { "token": "<accessToken>" } }
3
{ "event": "join_ledger",  "data": { "ledger_id": 42 } }
4
{ "event": "leave_ledger", "data": { "ledger_id": 42 } }
5
{ "event": "ping" }                                        // 30s 心跳
6

7
// ↓ 服务端 → 客户端
8
{ "event": "ledger_changed", "data": { "ledger_id": 42, "version": 1045, "scope": "transactions" } }
9
{ "event": "ledger_member_joined", "data": { "ledger_id": 42, "user": { /* 成员摘要 */ } } }
10
{ "event": "budget_alert", "data": { "ledger_id": 42, "alert_level": 1, "pct": 87.5 } }
11
{ "event": "pong" }