feat: 添加货币和汇率管理功能

refactor: 重构前端路由和登录逻辑 docs: 更新业务闭环、任务和架构文档 style: 调整代码格式和文件结构 chore: 更新依赖项和配置文件
2026-03-19 19:08:15 +08:00
parent 8de9ea0aaa
commit eafa1bbe94
203 changed files with 20240 additions and 39580 deletions
--- a/docs/02_Backend/api/02_Finance_API.md
+++ b/docs/02_Backend/api/02_Finance_API.md
@@ -0,0 +1,403 @@
+# 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*