# 后端架构文档 — FastAPI 服务层

> 更新日期：2026-03-19（RNS1.3 三看板接口 + CONFIG-1 技能类型）
> 位置：`apps/backend/`
> 框架：FastAPI + psycopg2（同步连接池）
> 数据库：`zqyy_app`（业务库）+ `etl_feiqiu`（ETL 库，直连只读访问）

---

## 1. 模块交互总览

```mermaid
graph TB
    subgraph "微信小程序"
        MP[miniprogram pages]
    end

    subgraph "管理后台"
        ADMIN[admin-web]
    end

    subgraph "FastAPI 后端"
        subgraph "路由层 (routers/)"
            R_AUTH[xcx_auth]
            R_TASKS[xcx_tasks]
            R_NOTES[xcx_notes]
            R_PERF[xcx_performance]
            R_CUST[xcx_customers<br/>CUST-1, CUST-2]
            R_COACH[xcx_coaches<br/>COACH-1]
            R_CHAT[xcx_ai_chat]
            R_CACHE[xcx_ai_cache]
            R_ADMIN[admin_*]
        end

        subgraph "服务层 (services/)"
            S_TM[task_manager<br/>任务 CRUD + 列表扩展]
            S_PS[performance_service<br/>绩效概览 + 明细]
            S_NS[note_service<br/>备注 CRUD + 评分]
            S_CS[customer_service<br/>客户详情 + 服务记录]
            S_CO[coach_service<br/>助教详情]
            S_FDW[fdw_queries<br/>FDW 查询集中封装]
            S_TG[task_generator<br/>任务自动生成]
            S_TE[task_expiry<br/>过期检测]
            S_RD[recall_detector<br/>召回完成检测]
            S_WX[wechat<br/>微信登录/Token]
        end

        subgraph "中间件 + 认证"
            MW[ResponseWrapperMiddleware]
            AUTH[JWT + require_approved]
        end
    end

    subgraph "数据库"
        BIZ[(zqyy_app<br/>biz / auth / public)]
        ETL[(etl_feiqiu<br/>直连 app.v_*)]
    end

    MP --> R_AUTH & R_TASKS & R_NOTES & R_PERF & R_CUST & R_COACH & R_CHAT
    ADMIN --> R_ADMIN

    R_TASKS --> S_TM
    R_PERF --> S_PS
    R_NOTES --> S_NS
    R_CUST --> S_CS
    R_COACH --> S_CO
    R_CHAT --> S_TM

    S_TM --> S_FDW
    S_PS --> S_FDW
    S_CS --> S_FDW
    S_CO --> S_FDW
    S_TM --> BIZ
    S_PS --> BIZ
    S_NS --> BIZ
    S_CS --> BIZ
    S_CO --> BIZ
    S_FDW --> ETL

    style S_FDW fill:#9f9,stroke:#333
    style S_PS fill:#9f9,stroke:#333
    style R_PERF fill:#9f9,stroke:#333
    style S_CS fill:#9f9,stroke:#333
    style S_CO fill:#9f9,stroke:#333
    style R_CUST fill:#9f9,stroke:#333
    style R_COACH fill:#9f9,stroke:#333
```

## 2. 路由模块清单

| 路由文件 | 前缀 | 说明 |
|----------|------|------|
| `xcx_auth.py` | `/api/xcx/auth` | 微信登录、Token 刷新、入驻申请 |
| `xcx_tasks.py` | `/api/xcx/tasks` | 任务列表(TASK-1)、详情(TASK-2)、pin/unpin、abandon/restore |
| `xcx_notes.py` | `/api/xcx/notes` | 备注 CRUD（含 score 评分） |
| `xcx_performance.py` | `/api/xcx/performance` | 绩效概览(PERF-1)、明细(PERF-2) |
| `xcx_customers.py` | `/api/xcx/customers` | 客户详情(CUST-1)、客户服务记录(CUST-2)（RNS1.2 新增） |
| `xcx_coaches.py` | `/api/xcx/coaches` | 助教详情(COACH-1)（RNS1.2 新增） |
| `xcx_board.py` | `/api/xcx/board` | 助教看板(BOARD-1)、客户看板(BOARD-2)、财务看板(BOARD-3)（RNS1.3 新增） |
| `xcx_config.py` | `/api/xcx/config` | 技能类型配置(CONFIG-1)（RNS1.3 新增） |
| `xcx_ai_chat.py` | `/api/xcx/ai` | AI 对话（SSE 流式） |
| `xcx_ai_cache.py` | `/api/xcx/ai-cache` | AI 缓存查询 |
| `admin_applications.py` | `/api/admin/applications` | 入驻审核 |
| `auth.py` | `/api/auth` | 管理后台登录 |
| `member_retention_clue.py` | `/api/member-retention-clue` | 维客线索 |
| `ops_panel.py` | `/api/ops` | 运维面板 |
| `business_day.py` | `/api/business-day` | 营业日配置 |


## 3. 服务层模块清单

| 服务文件 | 职责 | 数据源 |
|----------|------|--------|
| `task_manager.py` | 任务 CRUD、`get_task_list_v2()`、`get_task_detail()` | biz.coach_tasks + FDW |
| `performance_service.py` | `get_overview()`、`get_records()`，绩效汇总与明细 | FDW |
| `note_service.py` | 备注创建（含 score）、AI 占位、回访触发 | biz.notes |
| `customer_service.py` | 客户详情(CUST-1)、客户服务记录(CUST-2)（RNS1.2 新增） | biz.coach_tasks + biz.ai_cache + biz.notes + public.member_retention_clue + FDW |
| `coach_service.py` | 助教详情(COACH-1)：绩效/收入/任务分组/TOP客户/历史月份（RNS1.2 新增） | biz.coach_tasks + biz.notes + FDW |
| `fdw_queries.py` | ETL RLS 视图查询集中封装，直连 ETL 库 + `SET LOCAL app.current_site_id` 门店隔离 | app.v_* (ETL 直连) |
| `task_generator.py` | 定时任务：基于 WBI/NCI/RS 指数自动生成助教任务 | biz + FDW |
| `task_expiry.py` | 定时任务：检测过期任务并标记 inactive | biz.coach_tasks |
| `recall_detector.py` | 事件驱动：ETL 数据更新后检测召回完成 | biz + FDW |
| `note_reclassifier.py` | 事件驱动：召回完成后回溯重分类备注 | biz.notes |
| `wechat.py` | 微信 code2session、Token 管理 | 外部 API |
| `role.py` | 角色权限查询 | auth.* |
| `scheduler.py` | 触发器调度引擎 | biz.trigger_jobs |
| `board_service.py` | 三看板编排：`get_coach_board()`、`get_customer_board()`、`get_finance_board()`，含日期范围/环比/排序/分页/降级（RNS1.3 新增） | FDW + biz.coach_tasks |
| `application.py` | 入驻申请处理 | auth.applications |

## 4. FDW 查询封装（fdw_queries.py）

所有跨库查询集中在此模块，确保 DWD-DOC 强制规则统一实施。

⚠️ 架构变更（2026-03-18）：不再使用 zqyy_app 的 `fdw_etl.*` foreign table，改为通过 `get_etl_readonly_connection(site_id)` 直连 ETL 库查询 `app.v_*` RLS 视图。原因：`postgres_fdw` 不传递自定义 GUC 参数到远端连接，导致 RLS 视图的 `current_setting('app.current_site_id')` 在远端未设置而报错。

所有函数通过 `_fdw_context()` 上下文管理器：创建 ETL 直连 → `SET LOCAL app.current_site_id` → 执行查询 → 关闭连接。

| 函数 | 用途 | DWD-DOC 规则 |
|------|------|-------------|
| `get_member_info()` | 批量查询会员姓名/手机号 | DQ-6：JOIN v_dim_member |
| `get_member_balance()` | 批量查询储值卡余额 | DQ-7：JOIN v_dim_member_card_account |
| `get_last_visit_days()` | 批量查询距上次到店天数 | 废单排除：is_delete = 0 |
| `get_salary_calc()` | 助教绩效/档位/收入 | 收入用 gross_salary；费用用 base_income + bonus_income |
| `get_service_records()` | 服务记录明细（分页） | 收入用 ledger_amount + DQ-6 + 废单排除 |
| `get_service_records_for_task()` | 特定客户服务记录 | 同上 |
| `get_consumption_60d()` | 客户近 60 天消费金额（RNS1.2 新增） | 收入用 ledger_amount（items_sum）+ 废单排除 |
| `get_relation_index()` | 客户与助教关系指数列表（RNS1.2 新增） | 来源 v_dws_member_assistant_relation_index |
| `get_consumption_records()` | 客户消费记录嵌套查询（RNS1.2 新增） | items_sum + DWD-DOC 规则 2 + 废单排除 |
| `get_total_service_count()` | 客户累计服务总次数（RNS1.2 新增） | 废单排除：is_delete = 0 |
| `get_coach_60d_stats()` | 助教对客户近 60 天统计（RNS1.2 新增） | 废单排除：is_delete = 0 |
| `get_assistant_info()` | 助教基本信息（RNS1.2 新增） | 来源 v_dim_assistant |
| `get_salary_calc_multi_months()` | 批量多月绩效数据（RNS1.2 新增） | 来源 v_dws_assistant_salary_calc |
| `get_monthly_customer_count()` | 各月不重复客户数（RNS1.2 新增） | 废单排除：is_delete = 0 |
| `get_coach_top_customers()` | 助教 TOP 客户（RNS1.2 新增） | DQ-6 + DQ-7 + items_sum + 废单排除 |
| `get_customer_service_records()` | 客户按月服务记录（RNS1.2 新增） | DQ-6 + items_sum + 废单排除 |
| `get_all_assistants()` | BOARD-1：按技能筛选助教列表（RNS1.3 新增） | v_dim_assistant |
| `get_salary_calc_batch()` | BOARD-1：批量查询当期/上期绩效（RNS1.3 新增） | items_sum + assistant_pd/cx_money |
| `get_top_customers_for_coaches()` | BOARD-1：按亲密度 Top3 客户 + 四级 emoji（RNS1.3 新增） | DQ-6 + v_dws_member_assistant_relation_index |
| `get_coach_sv_data()` | BOARD-1：助教客源储值数据（RNS1.3 新增） | v_dws_assistant_monthly_summary |
| `get_customer_board_recall()` | BOARD-2：召回维度（WBI 降序）（RNS1.3 新增） | v_dws_member_winback_index + DQ-6 |
| `get_customer_board_potential()` | BOARD-2：潜力维度（SPI 降序）（RNS1.3 新增） | v_dws_member_spending_power_index |
| `get_customer_board_balance()` | BOARD-2：余额维度（RNS1.3 新增） | v_dim_member_card_account + DQ-7 |
| `get_customer_board_recharge()` | BOARD-2：充值维度（RNS1.3 新增） | v_dwd_recharge_order |
| `get_customer_board_recent()` | BOARD-2：最近到店维度（RNS1.3 新增） | v_dws_member_visit_detail |
| `get_customer_board_spend60()` | BOARD-2：60 天消费维度（RNS1.3 新增） | items_sum 口径 |
| `get_customer_board_freq60()` | BOARD-2：60 天频次维度 + weeklyVisits（RNS1.3 新增） | v_dws_member_consumption_summary |
| `get_customer_board_loyal()` | BOARD-2：忠诚度维度（RS 降序）（RNS1.3 新增） | v_dws_member_assistant_relation_index |
| `get_customer_assistants()` | BOARD-2：批量查询客户关联助教（RNS1.3 新增） | 含亲密度 + 当前跟进置顶 |
| `get_finance_overview()` | BOARD-3：经营一览 8 项指标（RNS1.3 新增） | v_dws_finance_daily_summary + items_sum |
| `get_finance_recharge()` | BOARD-3：预收资产（储值卡 + 赠送卡矩阵）（RNS1.3 新增） | v_dws_finance_recharge_summary |
| `get_finance_revenue()` | BOARD-3：应计收入结构（RNS1.3 新增） | v_dws_finance_income_structure + discount_detail |
| `get_finance_cashflow()` | BOARD-3：现金流入（RNS1.3 新增） | v_dws_finance_daily_summary + 互斥规则 7 |
| `get_finance_expense()` | BOARD-3：现金流出 4 子分组（RNS1.3 新增） | v_dws_finance_expense_summary + platform_settlement |
| `get_finance_coach_analysis()` | BOARD-3：助教分析（basic + incentive）（RNS1.3 新增） | v_dws_assistant_salary_calc |
| `get_skill_types()` | CONFIG-1：技能类型配置（RNS1.3 新增） | ETL cfg 表 |

### 列名映射（design.md 理想名 → 实际 FDW 视图列名）

RLS 视图直接暴露 DWD/DWS 原始列名，后端代码在 SQL 中使用 AS 别名转换。

**v_dwd_assistant_service_log**（基于 `dwd.dwd_assistant_service_log`，非 _ex 表）：

| 代码语义 | 实际列名 | 说明 |
|----------|----------|------|
| id | `assistant_service_id` | 服务记录主键 |
| assistant_id (WHERE) | `site_assistant_id` | 与 salary_calc.assistant_id 同源 |
| member_id | `tenant_member_id` | 会员 ID |
| is_trash = false | `is_delete = 0` | 整数类型，0=正常 |
| settle_time | `create_time` | 结算时间 |
| start_time | `start_use_time` | 开始使用时间 |
| end_time | `last_use_time` | 最后使用时间 |
| service_hours | `income_seconds / 3600.0` | 折算工时（计算字段） |
| service_hours_raw | `real_use_seconds / 3600.0` | 原始工时（计算字段） |
| income (items_sum) | `ledger_amount` | 收入金额 |
| course_type | `skill_name` | 课程类型 |
| table_name | `site_table_id` | 仅有台桌 ID，无名称 |

**v_dws_assistant_salary_calc**：

| 代码语义 | 实际列名 | 说明 |
|----------|----------|------|
| calc_month | `salary_month` | date 类型，存储为 YYYY-MM-01 |
| coach_level | `assistant_level_name` | 档位名称 |
| tier_index | `tier_id` | 档位 ID |
| basic_hours | `base_hours` | 基础课时 |
| total_hours | `effective_hours` | 有效总工时 |
| total_income | `gross_salary` | 总收入 |
| basic_rate | `base_course_price` | 基础课单价 |
| incentive_rate | `bonus_course_price` | 激励课单价 |
| bonus_money | `sprint_bonus` | 冲刺奖金 |
| assistant_pd_money_total | `base_income` | 基础课总收入 |
| assistant_cx_money_total | `bonus_income` | 激励课总收入 |

> 注意：`tier_nodes`、`total_customers`、`next_tier_*`、`tier_completed` 在视图中不存在，后端使用默认值或从其他数据源推算。

## 5. 数据流向

```
小程序请求
  → JWT 认证 (require_approved)
  → 路由层 (routers/)
  → 服务层 (services/)
  → 业务库 (zqyy_app) 直连
  → ETL 库 (etl_feiqiu) 直连只读（app.v_* RLS 视图）
  → 响应包装 (ResponseWrapperMiddleware)
  → { code: 0, data: ..., message: "ok" }
```

## 6. 关键设计决策

- **ETL 直连**：所有 ETL 查询封装在 `fdw_queries.py`，通过 `_fdw_context()` 直连 ETL 库查询 `app.v_*` RLS 视图（不使用 FDW foreign table，因 postgres_fdw 不传递自定义 GUC）
- **优雅降级**：扩展字段（lastVisitDays/balance/aiSuggestion）查询失败返回 null，不影响核心响应
- **camelCase 转换**：所有小程序端响应通过 `CamelModel` 自动转换为 camelCase
- **门店隔离**：业务库通过 `site_id` 参数过滤，ETL 查询通过 `SET LOCAL app.current_site_id` + RLS 视图隔离