# Finance API Specification

> **定位**：财务管理 API 规范 - 包含财务结算、税务、汇率对冲、利润对账等接口。
> **更新日期**: 2026-03-18
> **版本**: v1.0
> **最高优先级参考**: [Business_ClosedLoops.md](../../00_Business/Business_ClosedLoops.md)

---

## 1. 接口概览

| 方法 | 路径 | 功能 | 权限 |
|------|------|------|------|
| POST | `/api/v1/finance/orders/:id/record` | 记录订单财务 | finance:create |
| POST | `/api/v1/finance/transactions` | 记录交易流水 | finance:create |
| GET | `/api/v1/finance/reconciliation` | 执行利润对账 | finance:reconcile |
| GET | `/api/v1/finance/bills/:orderId` | 账单回放 | finance:read |
| GET | `/api/v1/finance/stats` | 财务统计 | finance:read |
| POST | `/api/v1/finance/hedge` | 汇率对冲 | finance:hedge |
| GET | `/api/v1/finance/tax/:orderId` | 税务信息 | finance:read |

---

## 2. 接口详情

### 2.1 记录订单财务 [BIZ_FIN_01]

**请求**
```http
POST /api/v1/finance/orders/:id/record
```

**请求体**
```json
{
  "platform": "AMAZON",
  "productId": "product-uuid",
  "sellingPrice": 59.99,
  "purchasePrice": 25.00,
  "countryCode": "US",
  "logisticsCost": 8.00,
  "adBudget": 5.00,
  "status": "COMPLETED"
}
```

**业务逻辑**
1. 插入订单主表 (`cf_orders`)
2. 实时税务计提 (`BIZ_FIN_02`)
3. 汇率自动对冲 (`BIZ_FIN_03`)

**响应**
```json
{
  "success": true,
  "data": {
    "orderId": "order-uuid",
    "taxAccrued": 5.40,
    "hedgeApplied": true
  }
}
```

---

### 2.2 记录交易流水 [BIZ_FIN_04]

**请求**
```http
POST /api/v1/finance/transactions
```

**请求体**
```json
{
  "amount": 59.99,
  "currency": "USD",
  "type": "ORDER_REVENUE",
  "category": "SALES",
  "orderId": "order-uuid",
  "metadata": {
    "platform": "AMAZON",
    "productId": "product-uuid"
  }
}
```

**交易类型**

| 类型 | 说明 |
|------|------|
| ORDER_REVENUE | 订单收入 |
| LOGISTICS_COST | 物流成本 |
| PLATFORM_FEE | 平台费用 |
| REFUND | 退款 |
| COMMISSION | 佣金 |
| INCOME | 其他收入 |

**响应**
```json
{
  "success": true,
  "data": {
    "transactionId": 12345,
    "recordedAt": "2026-03-18T10:00:00Z"
  }
}
```

---

### 2.3 执行利润对账 [BIZ_FIN_06]

**请求**
```http
GET /api/v1/finance/reconciliation?shopId=shop-uuid
```

**查询参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| shopId | string | 是 | 店铺ID |

**业务逻辑**
1. 获取所有已完成且未对账的订单
2. 聚合各项成本（采购、物流、税务）
3. 计算净利润
4. 更新对账状态

**响应**
```json
{
  "success": true,
  "data": {
    "totalReconciled": 50,
    "details": [
      {
        "orderId": "order-1",
        "sellingPrice": 59.99,
        "purchaseCost": 25.00,
        "logisticsCost": 8.00,
        "taxAmount": 5.40,
        "netProfit": 21.59,
        "profitMargin": 36.0
      }
    ]
  }
}
```

---

### 2.4 账单回放

**请求**
```http
GET /api/v1/finance/bills/:orderId
```

**响应**
```json
{
  "success": true,
  "data": {
    "orderId": "order-uuid",
    "timeline": [
      {
        "event": "ORDER_CREATED",
        "time": "2026-03-18T10:00:00Z",
        "amount": 59.99,
        "description": "订单创建"
      },
      {
        "event": "PURCHASE_COMPLETED",
        "time": "2026-03-18T11:00:00Z",
        "amount": -25.00,
        "description": "采购完成"
      },
      {
        "event": "LOGISTICS_DEDUCTED",
        "time": "2026-03-18T12:00:00Z",
        "amount": -8.00,
        "description": "物流扣款"
      },
      {
        "event": "TAX_ACCRUED",
        "time": "2026-03-18T12:00:00Z",
        "amount": -5.40,
        "description": "税务计提"
      }
    ],
    "finalProfit": 21.59,
    "profitMargin": 36.0
  }
}
```

---

### 2.5 财务统计

**请求**
```http
GET /api/v1/finance/stats?startDate=2026-03-01&endDate=2026-03-31
```

**查询参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| startDate | string | 否 | 开始日期 |
| endDate | string | 否 | 结束日期 |
| shopId | string | 否 | 店铺筛选 |

**响应**
```json
{
  "success": true,
  "data": {
    "period": "2026-03-01 ~ 2026-03-31",
    "totalRevenue": 59980.00,
    "totalCost": 35988.00,
    "totalProfit": 23992.00,
    "averageMargin": 40.0,
    "byType": {
      "ORDER_REVENUE": 59980.00,
      "LOGISTICS_COST": -8000.00,
      "PLATFORM_FEE": -3998.00,
      "TAX": -5400.00,
      "PURCHASE": -25000.00
    },
    "byPlatform": {
      "AMAZON": { "revenue": 29990.00, "profit": 11996.00 },
      "SHOPIFY": { "revenue": 19993.00, "profit": 7997.00 },
      "TIKTOK": { "revenue": 9997.00, "profit": 3999.00 }
    }
  }
}
```

---

### 2.6 汇率对冲 [BIZ_FIN_03]

**请求**
```http
POST /api/v1/finance/hedge
```

**请求体**
```json
{
  "pair": "USD/CNY",
  "amount": 59980.00,
  "strategy": "AUTO"
}
```

**响应**
```json
{
  "success": true,
  "data": {
    "hedgeId": "hedge-uuid",
    "pair": "USD/CNY",
    "amount": 59980.00,
    "rate": 7.25,
    "hedgedAmount": 434855.00,
    "status": "EXECUTED"
  }
}
```

---

### 2.7 税务信息 [BIZ_FIN_02]

**请求**
```http
GET /api/v1/finance/tax/:orderId
```

**响应**
```json
{
  "success": true,
  "data": {
    "orderId": "order-uuid",
    "countryCode": "US",
    "baseAmount": 59.99,
    "taxRate": 9.0,
    "totalTax": 5.40,
    "isIOSS": false,
    "taxType": "STANDARD_VAT",
    "status": "ACCRUED",
    "accruedAt": "2026-03-18T10:00:00Z"
  }
}
```

---

## 3. 数据模型

### 3.1 OrderRecord (订单财务记录)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | string | 主键 |
| tenantId | string | 租户ID |
| shopId | string | 店铺ID |
| taskId | string | 任务ID |
| traceId | string | 追踪ID |
| platform | string | 平台 |
| productId | string | 商品ID |
| sellingPrice | number | 售价 |
| purchasePrice | number | 采购价 |
| countryCode | string | 国家代码 |
| logisticsCost | number | 物流成本 |
| adBudget | number | 广告预算 |
| status | string | 状态 |
| netProfit | number | 净利润 |
| reconciledAt | string | 对账时间 |

### 3.2 Transaction (交易流水)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | number | 自增ID |
| tenantId | string | 租户ID |
| orderId | string | 订单ID |
| amount | decimal(10,2) | 金额 |
| currency | string | 币种 |
| transactionType | string | 交易类型 |
| traceId | string | 追踪ID |
| metadata | object | 元数据 |
| createdAt | string | 创建时间 |

### 3.3 TaxAccrual (税务计提)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | number | 自增ID |
| orderId | string | 订单ID |
| tenantId | string | 租户ID |
| amount | decimal(10,2) | 税额 |
| currency | string | 币种 |
| taxType | string | 税务类型 |
| status | string | 状态 |
| traceId | string | 追踪ID |
| createdAt | string | 创建时间 |
| updatedAt | string | 更新时间 |

---

## 4. 利润计算公式

### 4.1 净利润

```
净利润 = 售价 - 采购成本 - 物流成本 - 税费 - 平台费用 - 广告费用
```

### 4.2 利润率

```
利润率 = (净利润 / 售价) × 100%
```

### 4.3 利润红线

| 模式 | 红线 | 处理 |
|------|------|------|
| B2B | < 15% | 禁止报价 |
| B2C | < 20% | 触发风控预警 |

---

## 5. 错误码

| 错误码 | 说明 | HTTP状态 |
|--------|------|----------|
| ORDER_NOT_FOUND | 订单不存在 | 404 |
| INSUFFICIENT_FUNDS | 资金不足 | 400 |
| INVALID_CURRENCY | 无效币种 | 400 |
| HEDGE_FAILED | 对冲失败 | 500 |
| RECONCILIATION_FAILED | 对账失败 | 500 |
| UNAUTHORIZED | 未授权 | 401 |
| FORBIDDEN | 无权限 | 403 |

---

## 6. 相关文档

- [Backend Design](../Backend_Design.md)
- [Product API](./Product_API.md)
- [Order API](./Order_API.md)
- [Business ClosedLoops](../../00_Business/Business_ClosedLoops.md) - 财务结算闭环

---

*本文档基于代码自动生成，最后更新: 2026-03-18*