税率计算流程

税率计算流程（买家与平台运营 / 海外前台与管理后台）

根据目的地匹配税率规则，从平台税率配置表按地区链路逐级回退获取税率，按价外税方式计算并展示税费明细。管理端按地区维度配置税率；POS 收银台不参与税率计算。

参与角色：平台管理员、买家/消费者

flowchart TD
    Start([买家浏览/下单]) --> EnterCheckout[进入结算页]
    EnterCheckout --> IdentifyDestination[识别目的地信息]
    IdentifyDestination --> DestSource{目的地来源优先级}
    DestSource -->|1. 前端传入 regionIds| FromRegionIds[直接使用前端传入的地区ID列表]
    DestSource -->|2. 前端传入 addressId| FromAddressId[从收货地址获取地区ID列表]
    DestSource -->|3. 用户已选地址| FromSelectedAddr[从用户系统选中地址获取地区ID列表]

    FromRegionIds --> CheckPOS
    FromAddressId --> CheckPOS
    FromSelectedAddr --> CheckPOS

    CheckPOS{是否POS收银台}
    CheckPOS -->|是| POSZero["POS场景：\n税率 = 0\n税额 = 0\n不参与税率计算"]
    CheckPOS -->|否| MatchTaxRule[匹配税率规则]

    MatchTaxRule --> QueryTaxRate["单次IN查询平台税率配置表：\n查询所有地区ID对应的生效税率\n仅查 is_active = 1\n按 update_time / create_time / id 降序"]
    QueryTaxRate --> RegionFallback["地区链路逐级回退匹配：\n区/县 → 市 → 省 → 国家\n从最细粒度优先命中"]

    RegionFallback --> CheckMatch{是否匹配到税率}
    CheckMatch -->|是| LoadRate[加载匹配到的税率]
    CheckMatch -->|否| NoTax["税率 = 0，税额 = 0"]

    LoadRate --> CalcTax["计算税额"]
    NoTax --> CalcTax

    CalcTax --> TaxFormula["价外税计算：\n税基 = 商品金额 + 运费 + 服务费 - 营销优惠\n（不扣除优惠券、余额、礼品卡等支付抵扣）\n积分兑换场景额外扣除积分抵扣金额\n税额 = 税基 × 税率%\n保留2位小数，向上取整（CEILING）"]
    TaxFormula --> TotalCalc["订单总额计算：\n商品金额 + 运费 + 服务费\n+ 发票费 + 税额\n- 积分抵扣 - 抹零\n- 营销优惠 - 优惠券\n- 礼品卡\n= 应付总额"]

    TotalCalc --> ShowTaxBreakdown["结算页展示税费明细：\n税率（百分比）\n税额"]

    ShowTaxBreakdown --> SubmitOrder["提交订单"]
    SubmitOrder --> PersistTax["落库固化：\n后端重新调用 getTotalFee 计算\n将 taxRate / taxRateAmount 写入订单表\n后续详情、售后、打印均读取订单快照"]

    POSZero --> POSSubmit["POS提交订单\n总额不叠加税额"]

    %% 订单详情与售后
    PersistTax --> OrderDetail["订单详情返回：\ntaxRate / taxRateAmount\n无值时兜底返回 0"]
    OrderDetail --> AfterSales["售后/退款：\n部分退款 → 含税单价 × 退款数量\n整单退款 → 订单总税费\n返回 refundTaxAmount"]

    %% 拆单
    PersistTax --> SplitOrder["拆单场景：\n子订单继承父订单税率\n按子订单口径独立算税额\n最终与父订单税额对齐"]

    %% 运营配置视角
    AdminConfig([平台管理员配置]) --> TaxConfig[税率配置管理]
    TaxConfig --> ConfigActions{配置操作}
    ConfigActions -->|新增税率| CreateTax["选择地区 → 设置税率（%）\n设置是否生效\n添加备注"]
    ConfigActions -->|更新税率| UpdateTax["修改税率/地区/生效状态\n地区变更时自动刷新地区名称"]
    ConfigActions -->|删除税率| DeleteTax["删除税率配置"]
    ConfigActions -->|查询税率| ListTax["税率列表/详情查询"]
    CreateTax --> SaveConfig[保存税率配置到 tax_rate 表]
    UpdateTax --> SaveConfig
    DeleteTax --> SaveConfig

    PersistTax --> End1([订单创建完成])
    POSSubmit --> End1
    AfterSales --> End2([售后流程])
    SplitOrder --> End3([拆单完成])

步骤说明

买家进入结算页后，系统识别目的地信息。地区来源按优先级依次为：前端直接传入的 regionIds、前端传入的 addressId 对应地址的地区ID列表、用户系统已选地址的地区ID列表。
判断是否为 POS 收银台场景：若是 POS，税率与税额直接置零，订单总额不叠加税额，流程结束。
非 POS 场景下进入税率匹配：对所有地区ID执行单次 IN 查询平台税率配置表（tax_rate），仅查询 is_active = 1 的生效记录，按 update_time、create_time、tax_rate_id 降序排列。
按地区链路从最细粒度逐级向上回退匹配：区/县 → 市 → 省 → 国家。命中第一个有效税率后停止回退；若所有层级均未命中，则税率为 0、税额为 0。
匹配到税率后计算税额（价外税方式）：税基 = 商品金额 + 运费 + 服务费 - 营销/会员优惠（不扣除优惠券、余额、礼品卡等支付抵扣）；积分兑换场景下额外扣除积分抵扣金额；税额 = 税基 × (税率 / 100)，保留 2 位小数并向上取整（RoundingMode.CEILING）。
结算页展示税率（百分比）与税额，并计算订单应付总额：商品金额 + 运费 + 服务费 + 发票费 + 税额 - 积分抵扣 - 抹零 - 营销优惠 - 优惠券 - 礼品卡 = 应付总额。
提交订单时，后端重新调用 getTotalFee 计算税额（防止前端金额篡改），将 taxRate 与 taxRateAmount 固化写入订单表，后续订单详情、售后、打印等均读取订单快照字段。
订单详情接口返回 taxRate 与 taxRateAmount，无值时兜底返回 0，兼容历史订单。
售后退款场景：部分退款按含税单价（原单价 + 单件税费）× 退款数量计算，整单退款直接使用订单总税费，接口返回 refundTaxAmount 供前端回显。
拆单场景：子订单继承父订单税率，按子订单口径独立计算税额（税基 = 商品金额 + 运费 - 营销优惠），最终通过差值对齐确保子订单税额之和等于父订单税额。
平台管理员侧可独立进入税率配置管理，支持按地区新增、更新、删除和查询税率配置，更新地区时自动刷新冗余的地区名称字段。
权限控制：查看需要 taxRateManage 权限，写操作需要 taxRateUpdateManage 或 taxRateModifyManage 权限。
流程结束。