Neo
6f8f12314f
包含多个会话的累积代码变更： - backend: AI 聊天服务、触发器调度、认证增强、WebSocket、调度器最小间隔 - admin-web: ETL 状态页、任务管理、调度配置、登录优化 - miniprogram: 看板页面、聊天集成、UI 组件、导航更新 - etl: DWS 新任务（finance_area_daily/board_cache）、连接器增强 - tenant-admin: 项目初始化 - db: 19 个迁移脚本（etl_feiqiu 11 + zqyy_app 8） - packages/shared: 枚举和工具函数更新 - tools: 数据库工具、报表生成、健康检查 - docs: PRD/架构/部署/合约文档更新 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
120 lines
4.8 KiB
Markdown
120 lines
4.8 KiB
Markdown
# SPEC: 财务看板前后端联调（board-finance-integration）
|
||
|
||
> 创建日期：2026-03-27
|
||
> 状态：进行中
|
||
> 优先级：P0
|
||
|
||
## 背景
|
||
|
||
财务看板页面（`pages/board-finance/board-finance`）当前数据全为空——前端只绑定了赠送卡矩阵，其余 5 个板块的 API 返回数据未做 `setData`。同时走查发现多个数据层问题需要修复。
|
||
|
||
## 目标
|
||
|
||
1. 前端完整绑定 API 返回的 6 个板块数据
|
||
2. 筛选变更（时间/区域/环比）触发重新加载
|
||
3. 修复已确认的数据层问题
|
||
4. 优化加载效率
|
||
|
||
## 任务清单
|
||
|
||
### 阶段 1：DWS 层改造（ETL）
|
||
|
||
#### T1.1 DWS 财务日报新增支付方式拆分字段
|
||
- 目标表：`dws.dws_finance_daily_summary`
|
||
- 新增字段：`cash_paper_amount`（纸币现金）、`scan_pay_amount`（扫码收款）
|
||
- 数据来源：`dwd_payment` 表按 `payment_method` 拆分（2=现金，4=离线/扫码）
|
||
- 恒等式：`cash_paper_amount + scan_pay_amount = cash_pay_amount`
|
||
- 涉及文件：
|
||
- `db/etl_feiqiu/migrations/2026-03-27__add_payment_split_to_finance_daily.sql`（DDL）
|
||
- `apps/etl/connectors/feiqiu/tasks/dws/finance_base_task.py`（新增 extract 方法）
|
||
- `apps/etl/connectors/feiqiu/tasks/dws/finance_daily_task.py`（transform 使用新字段）
|
||
- `docs/database/ddl/etl_feiqiu__dws.sql`（DDL 基线更新）
|
||
|
||
#### T1.2 RLS 视图更新
|
||
- 更新 `app.v_dws_finance_daily_summary` 暴露新字段
|
||
- 涉及文件：`db/etl_feiqiu/migrations/2026-03-27__update_finance_daily_view.sql`
|
||
|
||
### 阶段 2：后端 API 修复
|
||
|
||
#### T2.1 修复预收资产卡余额聚合（快照值 SUM → 取最后一天）
|
||
- 文件：`apps/backend/app/services/fdw_queries.py` → `get_finance_recharge()`
|
||
- 改动：卡余额字段（cash_card_balance/gift_card_balance/total_card_balance 及 gift 细分）改为取时间范围内最后一天的值
|
||
- 同时填充 `consumed` 字段（从 `dws_finance_daily_summary.card_consume_total` SUM 聚合）
|
||
|
||
#### T2.2 修复现金流入板块
|
||
- 文件：`apps/backend/app/services/fdw_queries.py` → `get_finance_cashflow()`
|
||
- 改动：
|
||
- 移除"储值卡消费"项
|
||
- 新增"纸币现金"和"扫码收款"两项（从新字段读取）
|
||
- 保留"团购平台回款"和"会员充值到账"
|
||
|
||
#### T2.3 修复助教分析小时均价 + 补充三列数据
|
||
- 文件：`apps/backend/app/services/fdw_queries.py` → `get_finance_coach_analysis()`
|
||
- 改动：
|
||
- 基础课用 `base_hours`，激励课用 `bonus_hours`
|
||
- 新增 `total_pay`（对客收费 = hours × course_price）
|
||
- 新增 `total_share`（球房分成 = hours × deduction）
|
||
- SQL 新增 `SUM(base_hours)`、`SUM(bonus_hours)`、`SUM(base_course_price)`、`SUM(bonus_course_price)`、`SUM(base_deduction)`、`SUM(bonus_deduction_ratio)` 的加权计算
|
||
|
||
#### T2.4 区域筛选枚举重建
|
||
- 文件：`apps/backend/app/schemas/xcx_board.py` → `AreaFilterEnum`
|
||
- 改动：从 7 项改为 9 项（all/hall/hallA/hallB/hallC/vip/snooker/mahjong/ktv）
|
||
- 后端 service 层传递 area 参数到 FDW 查询（本次不实现 SQL 过滤，仅传参预留）
|
||
|
||
#### T2.5 Pydantic Schema 同步
|
||
- 文件：`apps/backend/app/schemas/xcx_board.py`
|
||
- 确保 FinanceBoardResponse 及子 Panel 的字段与 service 返回一致
|
||
|
||
### 阶段 3：前端联调
|
||
|
||
#### T3.1 重写数据加载函数
|
||
- 文件：`apps/miniprogram/miniprogram/pages/board-finance/board-finance.ts`
|
||
- 改动：
|
||
- `_loadGiftRows()` → `_loadData()`，绑定全部 6 个板块
|
||
- 金额用 `formatMoney()`，百分比用 `toFixed(1) + '%'`
|
||
- 后端返回原始数字，前端按位置格式化
|
||
|
||
#### T3.2 筛选联动
|
||
- `onTimeChange`/`onAreaChange`/`toggleCompare` 变更后调用 `_loadData()`
|
||
- 添加 loading 态管理
|
||
|
||
#### T3.3 区域筛选选项更新
|
||
- 前端 `areaOptions` 从 7 项改为 9 项
|
||
- 非"全部"时隐藏：预收资产、现金流出、助教分析
|
||
|
||
#### T3.4 微信开发者工具验证
|
||
- 截图对比各板块数据
|
||
- 验证筛选切换、环比开关
|
||
|
||
## 区域筛选对照表
|
||
|
||
| code | 前端显示 | 包含的物理区域 |
|
||
|------|---------|-------------|
|
||
| all | 全部区域 | 所有 |
|
||
| hall | 大厅 | A区+B区+C区+TV台+美洲豹赛台 |
|
||
| hallA | A区 | A区 |
|
||
| hallB | B区 | B区 |
|
||
| hallC | C区 | C区+TV台+美洲豹赛台 |
|
||
| vip | 台球包厢 | VIP包厢 |
|
||
| snooker | 斯诺克 | 斯诺克区 |
|
||
| mahjong | 麻将房 | 麻将房+M7+M8+666+发财 |
|
||
| ktv | 团建房 | K包+k包活动区+幸会158 |
|
||
|
||
## 区域筛选影响板块
|
||
|
||
| 板块 | 非"全部"时 |
|
||
|------|-----------|
|
||
| 经营一览 | 按区域过滤 |
|
||
| 预收资产 | 隐藏 |
|
||
| 应计收入确认 | 按区域过滤 |
|
||
| 现金流入 | 按区域过滤 |
|
||
| 现金流出 | 隐藏 |
|
||
| 助教分析 | 隐藏 |
|
||
|
||
## 不做
|
||
|
||
- 区域级 SQL 过滤（DWS 视图改造，后续迭代）
|
||
- 助教分析按区域统计（已记入 BACKLOG）
|
||
- 各区域各收费项目对比（已记入 BACKLOG）
|
||
- 支出数据 Excel 导入功能
|