# SKILL.md - vala-order-amortization-stat 订单均摊结算统计技能
## 技能描述
用于统计指定账期内的订单均摊收入、退费冲销，按天计算均摊金额，支持部分退费场景的剩余金额和周期自动计算。
## 触发场景
当用户提到以下关键词组合时激活本技能：
1. 订单均摊、按天均摊、收入均摊
2. 账期结算、月度结算、季度结算
3. 退费冲销、部分退款均摊
## 前置依赖
1. 已连接线上PostgreSQL数据库 vala_bi 库
2. 依赖表：
   - bi_vala_order：订单主表
   - bi_refund_order：退费订单表
   - bi_vala_seasonal_ticket：季卡周期表
   - bi_vala_app_account：用户账户表（用于剔除测试账号）
3. 表关联规则：
   - bi_vala_order.trade_no ↔ bi_refund_order.trade_no 关联
   - bi_vala_order.out_trade_no ↔ bi_refund_order.out_trade_no 关联
## 操作流程
### 步骤1：确认核心参数
执行前必须向用户确认以下参数：
- 账期起始日期（格式：YYYY-MM-DD）
- 账期结束日期（格式：YYYY-MM-DD）
- 默认输出维度：账期整体汇总，无需按天/周/月拆分，无需分渠道统计
### 步骤2：数据过滤规则
1. 订单范围：
   - 2025-09-01 至 账期结束日 内创建的所有订单
   - bi_vala_order.status IN (3,4)（已完成、已退款订单）
   - 订单实际支付金额≥10元：bi_vala_order.pay_amount_int ≥ 1000（单位：分）
   - 关联bi_vala_app_account表，仅保留bi_vala_app_account.status = 1的非测试账号订单
2. 退费范围：
   - 退费完成时间落在账期内的所有退款成功记录，判定条件：bi_refund_order.updated_at（退款处理完成时间）在账期起止时间范围内
   - bi_refund_order.status = 3（退款处理完成）
3. 账期前退费订单处理规则：
   - 退费完成时间在账期起始日之前的订单，不会纳入本账期的冲销逻辑：
     - 全额退费订单：冲销动作已在退费发生的对应账期执行完毕，本账期完全不统计该订单的任何数据
     - 部分退费订单：冲销动作、剩余金额/剩余周期调整已在退费发生的对应账期完成，本账期仅按调整后的剩余金额计算均摊，不产生额外冲销金额
### 步骤3：核心计算逻辑
#### 3.1 周期计算
- 每个订单的总均摊周期 = bi_vala_seasonal_ticket中同一order_no下status != -1的不同id数量 × 90天
- 转正日期规则：试用期7天，包含下单日：
  - 均摊起始日（转正日期）= 订单下单日 + 7天，下单日取bi_vala_order.created_at的日期部分
  - 示例：4月22日下单，4月29日00:00:00为转正日，即均摊起始日
- 税率规则：
  - 订单下单时间在2026年5月1日之前：税率1%
  - 订单下单时间在2026年5月1日及之后：税率6%
  - 订单税后金额 = (bi_vala_order.pay_amount_int / 100) × (1 - 税率)（单位：元）
  - 订单税费金额 = (bi_vala_order.pay_amount_int / 100) × 税率（单位：元）
- **均摊规则更新**：所有均摊计算均基于税后金额进行，含税金额和税费单独统计
  - 日均摊金额（税后）= 订单税后金额 / 总均摊周期
  - 🔹 周期最后一天补差规则：订单均摊周期的最后一天，均摊金额不按日均摊计算，采用补差方式确保总额完全匹配：
    - 正常订单：最后一天均摊金额 = 订单税后总金额 - 前（总均摊周期-1）天累计已均摊金额
    - 部分退费订单：最后一天均摊金额 = 订单剩余税后金额 - 剩余均摊周期前（剩余天数-1）天累计已均摊金额
    避免浮点精度导致的金额尾差
#### 3.2 退费场景计算
所有退费冲销金额均为税后金额，税费同步对应冲销
1. **所有退费订单（全额/部分）通用计算**：
   - 历史退费订单冲销均摊金额：从2026年9月1日起至账期起始日之前，该订单已产生的全部税后均摊金额（统一显示为负数，用于冲销）
   - 历史退费订单冲销税费金额：上述历史均摊金额对应的税费（统一显示为负数，用于冲销）
2. **全额退费（bi_refund_order.refund_type = 2）**：无需额外计算补充均摊，仅执行上述通用冲销逻辑
3. **部分退费（bi_refund_order.refund_type = 3）**：在通用冲销逻辑基础上，额外计算：
   - 历史部分退费订单补充均摊金额：部分退费后剩余的待均摊税后金额，在本账期内产生的均摊收入
   - 历史部分退费订单补充税费金额：上述补充均摊金额对应的税费
#### 3.3 账期内收入计算
账期内总收入 = 账期内所有正常订单的日均摊金额总和 + 账期内所有退费冲销金额总和
## 核心SQL模板
```sql
-- 步骤1：获取所有符合条件的订单基础信息
WITH order_base AS (
  SELECT 
    o.id AS order_id,
    o.order_no,
    o.pay_amount_int / 100 AS pay_amount,
    -- 计算税率、税费、税后金额
    CASE WHEN DATE(o.created_at) < '2026-05-01' THEN 0.01 ELSE 0.06 END AS tax_rate,
    (o.pay_amount_int / 100) * CASE WHEN DATE(o.created_at) < '2026-05-01' THEN 0.01 ELSE 0.06 END AS tax_amount,
    (o.pay_amount_int / 100) * (1 - CASE WHEN DATE(o.created_at) < '2026-05-01' THEN 0.01 ELSE 0.06 END) AS after_tax_amount,
    DATE_ADD(DATE(o.created_at), INTERVAL 7 DAY) AS amortization_start_date,
    o.status AS order_status,
    a.id AS account_id,
    o.key_from,
    o.sale_channel
  FROM bi_vala_order o
  JOIN bi_vala_app_account a ON o.account_id = a.id
  WHERE 
    o.created_at >= '2025-09-01'
    AND o.status IN (3,4)
    AND o.pay_amount_int >= 1000
    AND a.status = 1
),
-- 步骤2：计算每个订单的总均摊周期
order_cycle AS (
  SELECT 
    order_no,
    COUNT(DISTINCT id) * 90 AS total_cycle_days
  FROM bi_vala_seasonal_ticket
  WHERE status != -1
  GROUP BY order_no
),
-- 步骤3：获取账期内的退费记录
refund_records AS (
  SELECT 
    r.out_trade_no AS order_no,
    CAST(r.refund_amount AS NUMERIC) / 100 AS refund_amount,
    r.refund_type,
    DATE(r.updated_at) AS refund_date
  FROM bi_refund_order r
  JOIN order_base o ON r.out_trade_no = o.order_no
  WHERE 
    r.status = 3
    AND r.updated_at BETWEEN '${账期起始日}' AND '${账期结束日}'
)
-- 后续按需求聚合维度计算日均摊金额和冲销金额
```
## 输出格式
1. 优先输出Excel报表，存放于output/目录下，命名格式：`订单均摊结算报表_${账期起始日}_${账期结束日}.xlsx`
2. 报表包含以下Sheet：
   - 汇总表：订单数、正式订单数、试用订单数、冲销前税费、冲销税费、补充税费、冲销后税费、冲销前均摊金额、冲销均摊金额、补充均摊金额、冲销后均摊金额
   - 订单明细：订单号、订单金额、税率、税额、税后金额、总均摊周期、已均摊天数、历史均摊金额、账期均摊金额、未确认收入、剩余周期
3. 文字回复核心指标：
   > 📊 账期${账期起始日}至${账期结束日}均摊结算结果：
   > 总订单数：XXX单
   > 正式订单数：XXX单
   > 试用订单数：XXX单
   > 冲销后税费：XXX元
   > 冲销后均摊金额（税后净收入）：XXX元
## 汇总指标计算逻辑（所有均摊金额均为税后金额）
1. **订单数**：账期内（下单日落在账期起止时间范围内）新增的所有符合条件的订单总数量
2. **正式订单数**：账期内新增的订单中，截止账期结束日已过7天试用期（下单日+7天 ≤ 账期结束日）的订单数量，仅正式订单开始参与均摊计算
3. **试用订单数**：账期内新增的订单中，截止账期结束日仍处于7天试用期内（下单日+7天 > 账期结束日）的订单数量，试用订单未开始均摊，不参与金额计算
4. **冲销前税费**：账期内所有正式订单的含税订单总金额 × 各订单对应税率 的总和
5. **冲销税费**：本账期内发生退费的所有订单的含税订单总金额 × 各订单对应税率 的总和（正数展示，计算时扣除）
6. **补充税费**：本账期内发生部分退费的订单，退费后剩余的含税订单金额 × 各订单对应税率 的总和，其中：部分退费订单剩余含税金额 = 原订单含税金额 - 退费含税金额
7. **冲销后税费**：账期内最终确认的总税费，计算公式：`冲销后税费 = 冲销前税费 - 冲销税费 + 补充税费`
8. **冲销前均摊金额（税后）**：历史未退费订单 + 账期内正式订单 在本账期内产生的税后均摊收入总和
9. **冲销均摊金额（税后）**：本账期内发生退费的所有订单，需要冲销的历史均摊金额总和（正数展示，计算时扣除）
10. **补充均摊金额（税后）**：本账期内发生部分退费的订单，从转正日起至账期最后一日产生的税后均摊金额总和
11. **冲销后均摊金额（税后）**：账期内最终确认的税后净收入，计算公式：`冲销后均摊金额 = 冲销前均摊金额 - 冲销均摊金额 + 补充均摊金额`
## 注意事项
1. 所有金额保留2位小数，百分比保留1位小数
2. 部分退费场景需确保bi_vala_seasonal_ticket中对应退费部分的status已更新为-1
3. 自动剔除测试账号，无需额外过滤
4. 冲销金额统一显示为负数