rustjr-account-management/docs/api/README.md

API 参考文档

一、API 概览

RustJR 账户管理系统提供 RESTful API 接口，支持账户管理、交易处理、账务查询、对账管理和积分操作等功能。

二、基础信息

2.1 基础 URL

环境	URL
开发	http://localhost:8080/api/v1
测试	http://test-api.example.com/api/v1
生产	https://api.example.com/api/v1

2.2 认证方式

目前系统内部使用，暂未启用认证。生产环境建议添加 JWT 认证：

Authorization: Bearer <token>

2.3 请求/响应格式

请求头：

Content-Type: application/json
Accept: application/json

统一响应格式：

{
  "code": 200,
  "message": "success",
  "data": { ... }
}

错误响应格式：

{
  "code": 400,
  "message": "参数错误",
  "error": "具体错误描述"
}

2.4 HTTP 状态码

状态码	说明
200	成功
201	创建成功
400	请求参数错误
404	资源不存在
409	资源冲突
500	服务器内部错误

三、API 端点汇总

3.1 账户 API (11个端点)

方法	端点	说明	前端对接
POST	/physical-accounts	创建实体账户	✅
GET	/physical-accounts	获取实体账户列表	✅
GET	/physical-accounts/:id	获取实体账户详情	✅
POST	/physical-accounts/:id/freeze	冻结实体账户资金	✅
POST	/physical-accounts/:id/unfreeze	解冻实体账户资金	✅
POST	/sub-accounts	创建虚拟子账户	✅
GET	/sub-accounts/:id	获取子账户详情	✅
GET	/sub-accounts/:id/balance	获取子账户余额	✅
POST	/sub-accounts/:id/freeze	冻结子账户资金	✅
POST	/sub-accounts/:id/unfreeze	解冻子账户资金	✅
POST	/sub-accounts/:id/close	关闭子账户	✅

3.2 交易 API (5个端点)

方法	端点	说明	前端对接
POST	/transactions/transfer	发起转账	⚠️ 部分
POST	/transactions/deposit	发起充值	❌
POST	/transactions/withdraw	发起提现	❌
GET	/transactions/:id	获取交易详情	✅
GET	/transactions	获取交易列表	✅

3.3 账务 API (3个端点)

方法	端点	说明	前端对接
GET	/ledger/subjects	获取会计科目列表	❌
GET	/ledger/entries/:id	获取分录详情	❌
GET	/ledger/accounts/:id/entries	获取账户分录列表	❌

3.4 对账 API (8个端点)

方法	端点	说明	前端对接
POST	/reconciliation/run	执行对账	⚠️ 部分
GET	/reconciliation/batches/:id	获取对账批次	✅
GET	/reconciliation/batches/:id/items	获取对账明细	✅
GET	/reconciliation/three-account/:id	三账校验	✅
POST	/reconciliation/adjustments	创建手工补录	✅
POST	/reconciliation/adjustments/:id/approve	审批补录	❌
POST	/reconciliation/adjustments/:id/reject	拒绝补录	❌
GET	/reconciliation/adjustments/pending	获取待审批补录	❌

3.5 积分 API (5个端点)

方法	端点	说明	前端对接
GET	/points/accounts/:sub_account_id	获取积分账户	❌
POST	/points/earn	获取积分	❌
POST	/points/spend	消费积分	❌
POST	/points/transfer	转移积分	❌
GET	/points/transactions	查询积分交易	❌

3.6 健康检查

方法	端点	说明
GET	/health	服务健康状态

四、账户 API 详细文档

4.1 创建实体账户

请求：

POST /api/v1/physical-accounts
Content-Type: application/json

{
  "account_no": "6222021234567890123",
  "account_name": "测试账户",
  "bank_code": "ICBC",
  "bank_name": "中国工商银行",
  "consistency_mode": "eventual",
  "outbound_control": "online_bank"
}

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "account_no": "6222021234567890123",
    "account_name": "测试账户",
    "bank_code": "ICBC",
    "bank_name": "中国工商银行",
    "consistency_mode": "eventual",
    "outbound_control": "online_bank",
    "status": "active",
    "personal_balance": "0.00",
    "labor_balance": "0.00",
    "frozen_balance": "0.00",
    "bank_balance": "0.00",
    "transit_amount": "0.00",
    "available_balance": "0.00",
    "version": 0,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

4.2 获取实体账户列表

请求：

GET /api/v1/physical-accounts?page=1&page_size=10&status=active&keyword=测试

查询参数：

参数	类型	必填	说明
page	int	否	页码，默认1
page_size	int	否	每页数量，默认10
status	string	否	状态筛选
keyword	string	否	关键词搜索

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "id": 1,
        "account_no": "6222021234567890123",
        "account_name": "测试账户",
        ...
      }
    ],
    "total": 100,
    "page": 1,
    "page_size": 10
  }
}

4.3 冻结账户资金

请求：

POST /api/v1/physical-accounts/1/freeze
Content-Type: application/json

{
  "amount": "100.00"
}

响应：

{
  "code": 200,
  "message": "success",
  "data": "账户资金已冻结"
}

4.4 解冻账户资金

请求：

POST /api/v1/physical-accounts/1/unfreeze
Content-Type: application/json

{
  "amount": "50.00"
}

响应：

{
  "code": 200,
  "message": "success",
  "data": "账户资金已解冻"
}

五、交易 API 详细文档

5.1 发起转账

请求：

POST /api/v1/transactions/transfer
Content-Type: application/json

{
  "from_account_id": 1,
  "to_account_id": 2,
  "amount": "1000.00",
  "remark": "转账测试"
}

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "txn_no": "TXN20240101000001",
    "txn_type": "transfer",
    "from_account_id": 1,
    "to_account_id": 2,
    "amount": "1000.00",
    "status": "pending",
    "created_at": "2024-01-01T00:00:00Z"
  }
}

5.2 获取交易详情

请求：

GET /api/v1/transactions/1

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "txn_no": "TXN20240101000001",
    "txn_type": "transfer",
    "from_account_id": 1,
    "to_account_id": 2,
    "amount": "1000.00",
    "status": "success",
    "bank_ref_no": "BANK123456",
    "created_at": "2024-01-01T00:00:00Z",
    "confirmed_at": "2024-01-01T00:01:00Z"
  }
}

5.3 获取交易列表

请求：

GET /api/v1/transactions?page=1&page_size=10&status=success&from_account_id=1

查询参数：

参数	类型	必填	说明
page	int	否	页码
page_size	int	否	每页数量
status	string	否	状态筛选
from_account_id	int	否	转出账户
to_account_id	int	否	转入账户
start_date	date	否	开始日期
end_date	date	否	结束日期

六、对账 API 详细文档

6.1 执行对账

请求：

POST /api/v1/reconciliation/run
Content-Type: application/json

{
  "physical_account_id": 1,
  "recon_date": "2024-01-01"
}

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "batch_no": "RECON20240101001",
    "physical_account_id": 1,
    "recon_date": "2024-01-01",
    "total_count": 100,
    "matched_count": 98,
    "mismatch_count": 2,
    "status": "completed"
  }
}

6.2 三账校验

请求：

GET /api/v1/reconciliation/three-account/1

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "physical_account_id": 1,
    "bank_balance": "100000.00",
    "transit_net": "5000.00",
    "ledger_total": "105000.00",
    "expected_total": "105000.00",
    "difference": "0.00",
    "is_balanced": true,
    "verified_at": "2024-01-01T00:00:00Z"
  }
}

6.3 创建手工补录

请求：

POST /api/v1/reconciliation/adjustments
Content-Type: application/json

{
  "related_txn_no": "TXN20240101000001",
  "adjustment_type": "add",
  "account_id": 1,
  "amount": "100.00",
  "reason": "银行入账补录"
}

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "adjustment_no": "ADJ20240101001",
    "status": "pending"
  }
}

七、积分 API 详细文档

7.1 获取积分账户

请求：

GET /api/v1/points/accounts/1

响应：

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "sub_account_id": 1,
      "points_type": "production",
      "balance": "1000.00",
      "total_earned": "5000.00",
      "total_spent": "4000.00",
      "total_expired": "0.00"
    }
  ]
}

7.2 获取积分

请求：

POST /api/v1/points/earn
Content-Type: application/json

{
  "points_account_id": 1,
  "amount": "100.00",
  "related_business_id": "WORK20240101001",
  "remark": "生产任务完成奖励"
}

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "txn_no": "PTS20240101001",
    "txn_type": "earn",
    "amount": "100.00",
    "balance_after": "1100.00"
  }
}

7.3 消费积分

请求：

POST /api/v1/points/spend
Content-Type: application/json

{
  "points_account_id": 1,
  "amount": "50.00",
  "related_business_id": "ORDER20240101001",
  "remark": "商品兑换"
}

7.4 转移积分

请求：

POST /api/v1/points/transfer
Content-Type: application/json

{
  "from_account_id": 1,
  "to_account_id": 2,
  "amount": "100.00",
  "remark": "积分转赠"
}

八、错误码说明

错误码	说明
400001	参数验证失败
400002	余额不足
400003	账户状态异常
404001	账户不存在
404002	交易不存在
409001	资源已存在
500001	数据库错误
500002	银行接口错误

九、数据类型说明

9.1 金额类型

• 使用字符串格式的十进制数
• 保留2位小数
• 示例："1000.00", "0.50"

9.2 时间类型

• 使用 ISO 8601 格式
• 时区为 UTC
• 示例："2024-01-01T00:00:00Z"

9.3 日期类型

• 使用 YYYY-MM-DD 格式
• 示例："2024-01-01"

十、SDK 使用示例

10.1 JavaScript/TypeScript

import { AccountAPI, TransactionAPI } from '@/api';

// 创建账户
const account = await AccountAPI.createPhysicalAccount({
  account_no: '6222021234567890123',
  bank_code: 'ICBC',
});

// 发起转账
const transaction = await TransactionAPI.createTransfer({
  from_account_id: 1,
  to_account_id: 2,
  amount: '1000.00',
});

10.2 cURL

# 创建账户
curl -X POST http://localhost:8080/api/v1/physical-accounts \
  -H "Content-Type: application/json" \
  -d '{"account_no":"6222021234567890123","bank_code":"ICBC"}'

# 获取账户列表
curl http://localhost:8080/api/v1/physical-accounts?page=1&page_size=10