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 认证：

```http
Authorization: Bearer <token>
```

### 2.3 请求/响应格式

**请求头**：
```http
Content-Type: application/json
Accept: application/json
```

**统一响应格式**：
```json
{
  "code": 200,
  "message": "success",
  "data": { ... }
}
```

**错误响应格式**：
```json
{
  "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 创建实体账户

**请求**：
```http
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"
}
```

**响应**：
```json
{
  "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 获取实体账户列表

**请求**：
```http
GET /api/v1/physical-accounts?page=1&page_size=10&status=active&keyword=测试
```

**查询参数**：

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

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

### 4.3 冻结账户资金

**请求**：
```http
POST /api/v1/physical-accounts/1/freeze
Content-Type: application/json

{
  "amount": "100.00"
}
```

**响应**：
```json
{
  "code": 200,
  "message": "success",
  "data": "账户资金已冻结"
}
```

### 4.4 解冻账户资金

**请求**：
```http
POST /api/v1/physical-accounts/1/unfreeze
Content-Type: application/json

{
  "amount": "50.00"
}
```

**响应**：
```json
{
  "code": 200,
  "message": "success",
  "data": "账户资金已解冻"
}
```

## 五、交易 API 详细文档

### 5.1 发起转账

**请求**：
```http
POST /api/v1/transactions/transfer
Content-Type: application/json

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

**响应**：
```json
{
  "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 获取交易详情

**请求**：
```http
GET /api/v1/transactions/1
```

**响应**：
```json
{
  "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 获取交易列表

**请求**：
```http
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 执行对账

**请求**：
```http
POST /api/v1/reconciliation/run
Content-Type: application/json

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

**响应**：
```json
{
  "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 三账校验

**请求**：
```http
GET /api/v1/reconciliation/three-account/1
```

**响应**：
```json
{
  "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 创建手工补录

**请求**：
```http
POST /api/v1/reconciliation/adjustments
Content-Type: application/json

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

**响应**：
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "adjustment_no": "ADJ20240101001",
    "status": "pending"
  }
}
```

## 七、积分 API 详细文档

### 7.1 获取积分账户

**请求**：
```http
GET /api/v1/points/accounts/1
```

**响应**：
```json
{
  "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 获取积分

**请求**：
```http
POST /api/v1/points/earn
Content-Type: application/json

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

**响应**：
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "txn_no": "PTS20240101001",
    "txn_type": "earn",
    "amount": "100.00",
    "balance_after": "1100.00"
  }
}
```

### 7.3 消费积分

**请求**：
```http
POST /api/v1/points/spend
Content-Type: application/json

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

### 7.4 转移积分

**请求**：
```http
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

```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

```bash
# 创建账户
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
```