root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
master
Neo-ZQYY/docs/prd/specs/board-finance-integration.md
Neo 6f8f12314f feat: 累积功能变更 — 聊天集成、租户管理、小程序更新、ETL 增强、迁移脚本 
包含多个会话的累积代码变更：
- 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>
2026-04-06 00:03:48 +08:00

4.8 KiB
Raw Permalink Blame History

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 导入功能
Reference in New Issue View Git Blame Copy Permalink