404 lines
7.8 KiB
Markdown
404 lines
7.8 KiB
Markdown
# 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*
|