makemd/docs/blueprints/frontend-integration/tax-routing-optimizer.md

前端集成蓝图：跨主权税务路由优化引擎 (Tax Routing Optimizer)

[AI-3 @ 2026-03-14]：由后端 Agent 在完成 BIZ_FIN_60 逻辑后产出。

1. 业务意图 (Business Intent)

• 核心价值：在多个目的国发货时，自动选择税务成本最低（如 IOSS vs OSS）的路由，保护商户资金。
• 关联后端 Service：TaxRoutingOptimizerService.ts

2. UI/UX 布局方案 (Layout Design)

• 页面入口：Console -> 财务中心 -> 税务路由管理
• 展示组件：
  • 多国税务政策对比图：展示 IOSS, OSS, DDP, DDU 在不同国家的成本差异。
  • 税务路由建议表：展示已生成的路由建议（Method, Tax, Cost）。
  • 合规风险雷达图：展示不同方法的风险评估（Risk Level）。
• 交互草图：

  +-----------------------------------------------------------+
  | [Icon] 税务路由优化管理 (Tax Routing)                    |
  +-----------------------------------------------------------+
  | [ 目的国: 德国 (DE) ] [ 订单金额: €120 ] [ 路由建议: IOSS ] |
  +-----------------------------------------------------------+
  | 预估税额: €24.00 | 合规费用: €1.50 | 总成本: €25.50      |
  +-----------------------------------------------------------+
  | [ AGI 路由洞察 (Tax Insight) ]                            |
  | "该订单金额低于 €150，使用 IOSS 路由可享受极低合规成本。|
  | 相比 DDP 节省：€3.50。风险等级：低 (LOW)。"               |
  +-----------------------------------------------------------+
  | [ 忽略建议 ]                      [ 应用 IOSS 路由策略 ]   |
  +-----------------------------------------------------------+
  

3. API 交互契约 (API Integration)

• 数据获取：GET /api/v1/finance/tax/routing/optimize?country=DE&value=120
• 关键字段映射
  • chosen_method -> 建议税务方法
  • estimated_tax -> 预估税额
  • total_cost -> 总合规成本
• 状态流转：
  • 切换目的国 -> 调用 TaxRoutingOptimizerService.optimizeTaxRoute -> 重新渲染成本对比。

4. 生产校验项 (FE Readiness)

• 各国税率数据的实时性核对（< 24 hour 延迟）。
• 货币转换的实时汇率应用。
• 导出包含税务路径选择理由的财务报表。