Neo-ZQYY/docs/guides/FRONTEND-BACKEND-INTEGRATION.md

前后端联调规范手册

最后更新：2026-04-01 适用范围：小程序（apps/miniprogram/）与 FastAPI 后端（apps/backend/）的联调 约束力：高度建议参考。特殊需求可偏离但需注明原因。 速查索引：.kiro/steering/frontend-backend-integration.md（fileMatch 自动加载）

---

一、数据契约

1.1 ResponseWrapper

后端 ResponseWrapperMiddleware 自动包装所有 2xx JSON 响应为 {"code": 0, "data": <原始body>}。脚本/测试调用 API 时必须从 resp.json()["data"] 取实际数据，不能直接用 resp.json()（踩坑记录 2026-03-28）。

1.2 字段命名与 CamelCase 转换

• 后端统一 snake_case，Pydantic CamelModel 自动转 camelCase 输出
• 前端用 camelCase 读取，兼容写法：rec.memberId ?? rec.member_id ?? 0
• 踩坑：me.avatar 应为 me.avatarUrl（avatar_url 转换后）

1.3 条件显示放后端

字段需要根据业务条件决定显示/隐藏时，后端满足条件返回值、不满足返回 null。前端只判 wx:if="{{field}}"，禁止做数值比较。

组件 property 收到 null 不走默认值，传入前必须清洗：r.durationRaw ?? 0、r.drinks ?? ''。

1.4 Schema 与 Service 同步规则

Pydantic response schema 必须与 service 返回字段严格一致，否则 500。排查 500 优先检查：

1. 数据库迁移是否已执行
2. Schema 字段是否与 service 一致
3. 环境变量是否缺失
4. 鉴权依赖是否匹配

踩坑记录汇总（Pydantic 系列）

问题	日期	表现	规则
静默丢弃未声明字段	2026-03-28	新增字段（desc、discount_total）前端收不到	新增后端返回字段时必须同步更新 Schema
list[dict] 不转换内部 key	2026-03-28	前端拿到 snake_case key	用 CamelModel 子类替代 dict，或 service 层手动递归转换
Optional 与 None 不同步	2026-03-29	service 返回 None 但 Schema 非 Optional → 500	修改 service 返回 None 时必须同步 Schema 为 `XxxModel
response_model 类型不匹配	2026-03-29	Schema 期望 list[CoachSkillItem] 但返回 list[str] → 500	修改 service 返回字段时必须同步检查 Schema 类型
嵌套 CamelModel 字段名不匹配	2026-03-29	dict key 与 Schema 字段名不一致 → 500	_build_* 方法必须逐字段对照 Schema
含数字字段名转换	2026-03-29	consumption_60d → consumption60D（大写 D）	前端用 d.consumption60D ?? d.consumption60d 兼容

1.5 接口返回结构

// 列表：{ "records": [...], "total_count": 42, "has_more": true }
// 概览：{ "coach_name": "...", "income_items": [...], "this_month_records": [...] }

收入明细始终返回所有项（即使为 0），前端不做过滤。

---

二、展示映射

2.1 头像颜色

后端只传 member_id + avatar_char，前端 nameToAvatarColor(String(memberId)) 计算颜色 key。散客（member_id ≤ 0）→ 'default'（灰色），avatar_char 返回 "?"。

2.2 课程标签

后端返回数据库原始 skill_name（中文），WXSS 不支持中文类名，前端映射：

const COURSE_TAG_MAP: Record<string, string> = {
  '陪打': 'basic', '基础课': 'basic',
  '包厢': 'room', '包厢课': 'room',
  '超休': 'incentive', '激励课': 'incentive', '打赏课': 'incentive',
}

2.3 角色标签

后端返回英文 code（coach/staff/head_coach/manager），前端 ROLE_LABELS 映射中文。助教拼接等级：${coachLevel}助教。

2.4 助教姓名显示规则（2026-03-28）

所有助教必须使用昵称/花名（nickname），不得显示真实姓名（real_name）。SQL 中统一用 COALESCE(da.nickname, da.real_name, '')，nickname 优先。

2.5 助教离职过滤（2026-03-29）

所有查询助教的 SQL 必须加 da.leave_status = 0 过滤离职助教。LEFT JOIN 场景用 (da.leave_status IS NULL OR da.leave_status = 0) 兼容无匹配行。dim_assistant 中 leave_status=1 为离职（占 74%），不过滤会展示大量已离职助教。

2.6 预估规则（全小程序统一）

当月且当前日期 ≤ 5号时显示"预估"标签。业务含义：每月 1-5 日为工资审核期。

2.7 WXSS 类名拼接

后端值用于 class="xxx-{{value}}" 时必须是合法 CSS 标识符（纯英文），禁止中文/hex/特殊字符。

2.8 前端筛选枚举同步（踩坑记录 2026-03-28）

前端下拉/筛选组件的 value 必须与后端 Enum 值完全一致（大小写、命名）。修改后端枚举时，必须全局搜索所有使用该枚举的前端页面同步更新。

2.9 WXS 格式化规范

• WXS 数值方法防护：format.wxs 中所有调用 .toFixed() 的函数必须先 parseFloat 转数字
• TS 与 WXS 格式化互斥（2026-03-27）：WXML 用 {{fmt.money(field)}} 时，TS 层 setData 必须传原始数字（?? 0），禁止 formatMoney() 预格式化
• 后端 service 层同理（2026-03-29）：前端用 WXS 格式化的字段，后端必须返回原始数字（float/int），禁止预格式化为字符串。Schema 类型需同步从 str 改为 float/int
• 环比显示统一规范（2026-03-28）：所有环比文本必须使用 fmt.compareText(compare, isDown) + fmt.compareClass(compare, isDown, size) WXS 函数
• WXS 零值语义（2026-03-27）：value === 0 不一定是空值。days(0) 表示"今天到店"是有效值。新增 WXS 函数时必须区分"零值有业务含义"和"零值等同空值"

---

三、SQL 查询规范

3.1 ETL 连接复用（必须）

同一 service 方法内创建一个 etl_conn 传给所有 fdw_queries.*。

3.2 多页面复用组件时 SQL 统一

后端为同一组件提供数据的查询必须同口径（共享 JOIN/聚合），各页面只负责过滤和分页。

3.3 一对多明细用 LATERAL 避免行膨胀

LEFT JOIN LATERAL (
    SELECT string_agg(gs.ledger_name || '×' || gs.total_count, '、') AS drinks
    FROM (...GROUP BY ledger_name) gs
) gs_agg ON true

3.4 助教收入口径

• sl.ledger_amount：行级毛收入，不是到手
• 到手：hours × (base_course_price - base_deduction)
• sh.assistant_pd_money + cx_money：整单级汇总，禁止 JOIN 到行级

3.5 快照值 vs 流量值（2026-03-27）

• 流量值（充值/消费/收入）：可以 SUM
• 快照值（卡余额 cash_card_balance/gift_card_balance/total_card_balance）：日末快照，多天聚合取最后一天的值，禁止 SUM

3.6 dim_member_card_account 多卡膨胀（2026-03-29）

同一 tenant_member_id 在 scd2_is_current=1 下可能有多条记录（多张卡），必须先 GROUP BY tenant_member_id + SUM(balance) 聚合后再 JOIN。

3.7 台费原价推算（2026-03-29）

台费正价 = table_charge_money + adjust_amount。adjust_amount > 0 时显示原价删除线。

3.8 环比同期对比规则（2026-03-28）

当前周期 end_date cap 到今天，上期取同类周期的同期天数。已完成周期取完整周期对比再上一个完整周期。

3.9 优惠拆分恒等式（2026-03-28）

discount_total = discount_groupbuy + discount_manual + discount_other + discount_vip + discount_gift_card + discount_rounding。拆分展示必须包含全部 6 个子字段。

3.10 团购金额双口径（2026-03-28）

DWS groupbuy_pay_amount 是团购交易金额，daily_revenue_report.py 用 sale_price × 0.75 估算回款。财务看板用 DWS 口径，经营报告用估算回款口径。

3.11 助教财务三列口径（2026-03-28）

pay/share/hourly 全部从 DWS dws_assistant_salary_calc 计算。禁止从 DWD ledger_amount 取客户支付再 JOIN DWS 等级（同一助教同月可有多等级记录导致行膨胀）。

3.12 客源储值口径（纠正 2026-03-29）

客源储值 = 该助教关联客户的卡余额合计，不是充值提成。数据源：v_dws_member_assistant_relation_index（session_count > 0）+ v_dim_member_card_account（先 GROUP BY 聚合）。

3.13 DATE_TRUNC 返回 timestamp 不是 date（2026-03-29）

用作 dict key 时必须先 .date() 转换。

3.14 关系指数表字段名（2026-03-29）

dws_member_assistant_relation_index 的字段是 session_count（非 service_count）、total_duration_minutes（非 total_hours）、ml_allocated_amount（非 total_income）。

3.15 dim_table 主键列名（2026-03-29）

主键是 table_id（不是 site_table_id）。JOIN 时用 ON s.site_table_id = dt.table_id。

---

四、数据库操作陷阱

4.1 psycopg2 Windows GBK 编码（2026-03-29）

psycopg2.connect() 用关键字参数时，libpq 拼接系统 locale 信息触发 UnicodeDecodeError。解决：用显式 DSN 字符串 + client_encoding=UTF8 + os.environ.setdefault("PGCLIENTENCODING", "UTF8")。

4.2 软删除 + ON CONFLICT

ON CONFLICT DO UPDATE SET is_removed=false，禁止 DO NOTHING。

4.3 ON CONFLICT 精确匹配 partial unique index

列列表和 WHERE 条件必须与索引定义完全对应。

4.4 跨库过滤分页

先构建排除列表，SQL 层统一过滤，禁止内存过滤修正 total。

4.5 共享连接子流程

需事务隔离时用独立连接，避免异常被外层 except 吞掉。

4.6 FDW 查询禁止 N+1 串行（2026-03-29）

必须改为 WHERE assistant_id = ANY(%s) 批量查询 + Python 层 dict 映射。

4.7 FDW 查询必须传 etl_conn（2026-03-29）

所有 _build_* 子函数都应接收并传递 etl_conn，否则 _fdw_context 在业务库连接上设置 RLS 导致空结果。

---

五、前端交互规范

5.1 页面加载态（2026-03-29）

统一用 wx.showLoading / wx.hideLoading 原生遮罩，禁止自定义加载组件。

5.2 跨页面跳转

URL 参数必须包含可查询 ID（memberId/taskId），不能只传展示字段。

5.3 dataset 同步

TS e.currentTarget.dataset.xxx 必须与 WXML data-xxx 属性同步。

5.4 自定义组件静默不渲染（2026-03-29）

未在页面 JSON usingComponents 中注册的组件不报错但完全不渲染。

5.5 多状态列表页

后端按 status 过滤，前端需并行请求所有需要展示的状态并合并。

5.6 微信头像

chooseAvatar 组件 + wx.uploadFile 上传服务器，临时路径会过期。

5.7 Vite 代理

跨前缀接口必须在 vite.config.ts proxy 中添加规则。

5.8 权限守卫

fallback 目标页必须对当前用户无条件可访问，避免跳转死循环。

5.9 前后端权限一致性

后端 /api/xcx/me 返回 permissions[]，前端根据权限码动态控制可见性。新增权限码只需更新数据库 auth.role_permissions。

5.10 custom-tab-bar 异步刷新

更新 globalData.visibleTabs 后必须主动调用 tabBar._refreshTabs()。看板 boardTabs 刷新必须放在 checkPageAccess().then() 回调中。

5.11 禁止页面滚动（2026-03-28）

wx.setPageScrollEnabled 不存在。用 <page-meta page-style="overflow:hidden" /> 控制。

5.12 登录与 /me 接口字段差异（2026-03-28）

/api/xcx/login 返回 WxLoginResponse（不含 permissions），/api/xcx/me 返回 UserStatusResponse（含 permissions）。登录后需权限码时必须额外请求 /me。

5.13 分页接口 API 函数必须返回完整响应（2026-03-29）

必须返回完整 data（含 items/total/page/pageSize），禁止只返回 data.items。

5.14 懒加载分页追加必须去重 + 双条件判底（2026-03-29）

① 追加数据按 id 去重（Set 过滤）；② hasMore 用双条件：items.length >= pageSize && merged.length < total。

---

六、事件驱动触发器

• biz.trigger_jobs 中 trigger_condition='event' 的任务必须有明确的 fire_event(event_name) 发射端
• 任务引擎全流程由 ETL 任务 DWS_TASK_ENGINE 编排，通过 HTTP 调用后端 POST /api/internal/run-job
• task_expiry_check 的 interval 触发器保留（每小时），DWS_TASK_ENGINE 是补充而非替代
• recall_detector 直接生成回访任务（CHANGE 2026-03-31）
• 任务生成器使用客户级别升级/转移（CHANGE 2026-03-31）：基于 t_v / ideal_interval ratio 决定分配范围
• 任务统计写入（CHANGE 2026-03-31）：task_generator.run() 末尾调用 _update_task_stats()

---

七、ETL 调用后端 API 注意事项

• ETL 的 AppConfig 不设置 os.environ，ETL 任务中用 os.environ.get() 前必须先 load_dotenv
• 后端 ResponseWrapperMiddleware 包装响应，ETL 调用时需从 resp.json()["data"] 取数据

---

八、列表与分页

• 客户列表：默认 5 条，展开最多 20 条
• 服务记录：按日期分组（DateGroup），默认 2 组，可展开
• 新客：本月有服务但之前无历史
• 常客：本月服务 ≥ 2 次，展示近 90 天聚合