Files

wurenzhi 72cd7f6f45 chore: 清理归档文件和文档模板

删除不再需要的归档文件和过时的文档模板，包括多个README、安全策略、前端集成蓝图等文件，同时移除了未使用的业务文档和项目结构文件。

优化项目结构，移除冗余文件，保持代码库整洁。主要删除archive/handover目录下的多个文件及doc目录下的部分文档模板。

2026-03-18 01:21:15 +08:00

7.8 KiB

Raw Blame History

Finance API Specification

定位：财务管理 API 规范 - 包含财务结算、税务、汇率对冲、利润对账等接口。 更新日期: 2026-03-18 版本: v1.0 最高优先级参考: 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]

请求

POST /api/v1/finance/orders/:id/record

请求体

{
  "platform": "AMAZON",
  "productId": "product-uuid",
  "sellingPrice": 59.99,
  "purchasePrice": 25.00,
  "countryCode": "US",
  "logisticsCost": 8.00,
  "adBudget": 5.00,
  "status": "COMPLETED"
}

业务逻辑

插入订单主表 (cf_orders)
实时税务计提 (BIZ_FIN_02)
汇率自动对冲 (BIZ_FIN_03)

响应

{
  "success": true,
  "data": {
    "orderId": "order-uuid",
    "taxAccrued": 5.40,
    "hedgeApplied": true
  }
}

2.2 记录交易流水 [BIZ_FIN_04]

请求

POST /api/v1/finance/transactions

请求体

{
  "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	其他收入

响应

{
  "success": true,
  "data": {
    "transactionId": 12345,
    "recordedAt": "2026-03-18T10:00:00Z"
  }
}

2.3 执行利润对账 [BIZ_FIN_06]

请求

GET /api/v1/finance/reconciliation?shopId=shop-uuid

查询参数

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

业务逻辑

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

响应

{
  "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 账单回放

请求

GET /api/v1/finance/bills/:orderId

响应

{
  "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 财务统计

请求

GET /api/v1/finance/stats?startDate=2026-03-01&endDate=2026-03-31

查询参数

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

响应

{
  "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]

请求

POST /api/v1/finance/hedge

请求体

{
  "pair": "USD/CNY",
  "amount": 59980.00,
  "strategy": "AUTO"
}

响应

{
  "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]

请求

GET /api/v1/finance/tax/:orderId

响应

{
  "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. 相关文档

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

7.8 KiB Raw Blame History Unescape Escape

Finance API Specification

1. 接口概览

2. 接口详情

2.1 记录订单财务 [BIZ_FIN_01]

2.2 记录交易流水 [BIZ_FIN_04]

2.3 执行利润对账 [BIZ_FIN_06]

2.4 账单回放

2.5 财务统计

2.6 汇率对冲 [BIZ_FIN_03]

2.7 税务信息 [BIZ_FIN_02]

3. 数据模型

3.1 OrderRecord (订单财务记录)

3.2 Transaction (交易流水)

3.3 TaxAccrual (税务计提)

4. 利润计算公式

4.1 净利润

4.2 利润率

4.3 利润红线

5. 错误码

6. 相关文档

7.8 KiB

Raw Blame History