# 财务看板助教分析按区域细化 — 执行文档

> 日期：2026-03-29 | 状态：待实施

## 背景

财务看板已完成区域维度重构（`board-finance-dws-area-refactor`），overview/revenue 支持 9 区域过滤。助教分析板块（coachAnalysis）当前 area≠all 时隐藏，需要支持按区域过滤。

## 需求确认

- 展示方式：A — area≠all 时自动按区域过滤，前端零改动（取消隐藏即可）
- 数据源：新建轻量 DWS 表，不改造现有 salary_calc 链路
- 跨区域：按区域拆分（同一助教在不同区域独立统计 hours）
- 前端：取消隐藏，显示按区域过滤后的数据

## 数据链路

现有链路（不改动）：
```
dwd_assistant_service_log → dws_assistant_daily_detail → dws_assistant_monthly_summary → dws_assistant_salary_calc
```
唯一键 `(site_id, assistant_id, stat_date/month)` 无区域维度，改造代价过大。

新增链路：
```
dwd_assistant_service_log + dim_table(area_name)
  → [CoachAreaHoursTask] → dws_coach_area_hours (新表)
                                ↓
                    后端 fdw_queries (area≠all 时 JOIN salary_calc 获取定价)
```

## 实施步骤

### 1. DDL — 创建 dws_coach_area_hours

```sql
CREATE TABLE dws.dws_coach_area_hours (
    id BIGSERIAL PRIMARY KEY,
    site_id BIGINT NOT NULL,
    tenant_id BIGINT NOT NULL,
    stat_month DATE NOT NULL,
    assistant_id BIGINT NOT NULL,
    area_code VARCHAR(20) NOT NULL,
    base_hours NUMERIC(10,2) NOT NULL DEFAULT 0,
    bonus_hours NUMERIC(10,2) NOT NULL DEFAULT 0,
    room_hours NUMERIC(10,2) NOT NULL DEFAULT 0,
    effective_hours NUMERIC(10,2) NOT NULL DEFAULT 0,
    trashed_hours NUMERIC(10,2) NOT NULL DEFAULT 0,
    base_service_count INTEGER NOT NULL DEFAULT 0,
    bonus_service_count INTEGER NOT NULL DEFAULT 0,
    room_service_count INTEGER NOT NULL DEFAULT 0,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    UNIQUE (site_id, stat_month, assistant_id, area_code)
);

CREATE OR REPLACE VIEW dws.v_dws_coach_area_hours AS
SELECT * FROM dws.dws_coach_area_hours
WHERE site_id = current_setting('app.current_site_id')::bigint;

GRANT SELECT ON dws.v_dws_coach_area_hours TO app_reader;
```

### 2. ETL 任务 — CoachAreaHoursTask

文件：`apps/etl/connectors/feiqiu/tasks/dws/coach_area_hours_task.py`

- extract：从 `dwd_assistant_service_log` + `dwd_assistant_service_log_ex`(is_trash) + `dim_table`(scd2_is_current=1) 提取当月服务记录
- transform（纯函数）：`resolve_area_code(area_name)` 映射区域，按 `(assistant_id, area_code)` 聚合 hours，构建 hall/all 汇总行
- load：delete-before-insert（按 site_id + stat_month）
- 注册到调度器

### 3. 后端改造

- `fdw_queries.py`：新增 `get_finance_coach_analysis_area(conn, site_id, start_date, end_date, area_code)`
  - 从 `v_dws_coach_area_hours` JOIN `v_dws_assistant_salary_calc` 按区域聚合
  - SQL 层计算 pay = hours × course_price, share = hours × (price - deduction)
- `board_service.py`：`_build_coach_analysis` 接收 area_code
  - area=all → 现有逻辑不变
  - area≠all → 调用新查询
  - 取消 `coach_analysis = None` 隐藏逻辑

### 4. 回填 + 联调

- 回填脚本：`scripts/ops/backfill_coach_area_hours.py`
- 联调验证：area=all 回归 + area≠all 数据正确

### 5. 收尾

- DDL 合并到基线
- BD 手册
- 审计

## 风险

1. 助教跨区域：按区域独立统计，area≠all 只显示该区域 hours
2. NULL table_id：计入 hall + all，不计入具体区域
3. area=all 回归：必须与现有完全一致
4. salary_calc 同一助教同月可能多等级（月中升级）：JOIN 时需注意