# 画像层 v2(实现版)

> **版本**:W7 · 2026-06 · 反映**已实现的 13 个画像标签** + 架构 + 算法审查发现。
> **单一真理源**:每个标签的 标签值/数据源/释义/算法/时间语义 在代码注册表
> [`packages/types/src/persona-feature-specs.ts`](../../packages/types/src/persona-feature-specs.ts)(`PERSONA_FEATURE_SPECS`);
> extractor 在 `apps/pac-service/src/modules/persona/features/*.feature.ts`。本文是**人读总览 + 决策记录**,不复制每字段。
> **关联**:[`db-design-v2.md`](../db-design-v2.md)(personas/persona_features 表)· [`pac-algorithms-overview.md`](./pac-algorithms-overview.md)。
>
> **一句话**:画像 = 对全历史的「压缩当前态」,每标签声明自己的时间语义;13 标签按业务 CDP 标签卡口径实现,口径沉淀在代码注册表;过程中审出并修了多处上游/spec 问题。

---

## 一、画像在三层模型的位置
事实层(`patient_facts`)→ **画像层(`personas`/`persona_features`)** → 召回层(`followup_plans`)。
画像是**对全历史 fact 的压缩**(facts=raw context,persona=hidden state),回答「现在这个人是什么样」。历史明细留 fact 层,**画像不存明细**;要看历史时点画像 → 读 `personas` 版本流(`version + computedAt + eventWatermark` = point-in-time)。

## 二、persona schema(怎么存)
`persona_features` 每行 = 一个标签:
- `key` — 标签 key(注册表闭集)
- `description` — 自然语言(给 LLM / 详情页展示)
- `data` (JSONB) — **结构化值**(机器消费:打分 / 圈人群 / 筛选)。这是"是什么"。
- `evidence` — 证据(factIds/ruleIds…)。这是"为什么"。
- `score` — **已弃用语义**(分值是消费场景的事,不在特征层;消费方从 `data` 自算)。
父 `personas`:`version` 版本流 + `eventWatermark`(算到哪个事件,判 stale)。

## 三、4 种数据范式(标签从哪来)
| 范式 | 说明 | 标签 | 部署成本 |
|---|---|---|---|
| **① 已摄入直接算** | 读现有 fact / 主档 | rfm / lifecycle_stage / treatment_history / time_preference / age_bracket / gender / do_not_contact | 仅 `--force` 重算 |
| **② 副表立柱新摄** | fact_client_out 字段 → `patient_profiles` 新列(enum_mapping 归一,多宿主标准) | acquisition_channel / referral_champion | migration + 重摄 |
| **③ fact.content 新字段** | 结算字段 → `payment_record.content`(JSONB,无迁移) | entitlement_status(卡券名)/ discount_anchor(折扣额) | 重摄 |
| **④ 衍生表 / ctx 加载** | 复用 PAC 已有派生数据,注入 persona ctx | family_structure(PatientRelation)/ special_attention(appointmentsAll) | 仅 `--force` |

## 四、时间语义模型
每标签在注册表声明 `timeSemantics`:`snapshot`(当前态,如年龄/性别)/ `window`(近 N 期,如时间偏好近2年)/ `lifetime`(全史,如治疗史/折扣锚点)/ `trend`/`mixed`(如 RFM:R 当前态、F/M 全史)。
**TZ**:PAC 全 UTC 存储(DW 北京,摄入时转换);算"星期/时段"等本地概念时 `AT TIME ZONE 'Asia/Shanghai'` / +8(试点硬编北京,多宿主应读 host TZ — follow-up)。

## 五、Feature Registry + recompute
- **Registry** = `PERSONA_FEATURE_SPECS`(代码常量,git/PR review),每标签一张"标签卡"(标签值/数据源/数据字段/释义/算法/时间语义/owner)。OneModel 单一收口。
- **extractor** 实现在 `features/*.feature.ts`,由 `FeatureRegistry` 收集,`PersonaService.recompute` 遍历。
- **重算**:`pnpm recompute-persona -- --host=jvs-dw --force`。⚠️ `--force` 必需 —— 算法/特征变更但数据没变时,水位幂等闸会全 noop;`--force` 跳过闸强制重算(部署也用)。

## 六、13 标签总览(本地 928 样本)
| 标签 | 类 | 标签值 | 数据源 | 时间语义 | 覆盖 |
|---|---|---|---|---|---|
| `rfm` 价值分群 | B | 8 分群(重要价值..低活跃) | 付款/就诊 fact | mixed | 928 |
| `lifecycle_stage` 生命周期 | B | 潜客/新客/成长/成熟/待激活/沉睡/流失 | 付款/就诊/预约 fact(自算) | window+trend | 928 |
| `treatment_history` 治疗史 | C | 种植/正畸/修复/牙周(多标签) | treatment_record.category | lifetime | 773 |
| `time_preference` 时间偏好 | D | 工作日/周末/上午/下午/晚间(多) | appointment.planned_for(北京) | window(2y) | 601 |
| `discount_anchor` 折扣锚点 | D | 最低折扣率+日期/项目 | payment.content(应收/折扣额) | lifetime | 338 |
| `special_attention` 特别关注 | D | 屡次爽约/经常迟到/免打扰/不可等候(多) | appointmentsAll + profile + emr | window(1y) | 88 |
| `acquisition_channel` 获客渠道 | A | 走入/口碑/集团营销/地区/电商/自媒体… | fact_client_out.primary_category(副表立柱) | snapshot | 928 |
| `entitlement_status` 权益身份 | B | 高端保险/银行私行/储值/儿牙/医保(多) | payment 卡券名关键词 + 充值 | lifetime | 274 |
| `age_bracket` 年龄段 | A | 婴幼儿..老年(9 档) | patient.birthDate | snapshot | 928 |
| `gender` 性别 | A | 男/女/未知 | patient.gender | snapshot | 928 |
| `family_structure` 家庭构成 | A | 单身/两口/多口/多代 | PatientRelation 直系 | snapshot | 85 |
| `referral_champion` 转介绍达人 | B | 家庭型/社交型 | recommend_num/amount(副表)+ 关系 | snapshot | 26 |
| `do_not_contact_status` 勿扰 | — | 可触达/勿扰 | profile + 投诉 | snapshot | 928 |

> 多标签(允许并列):treatment_history / time_preference / entitlement_status / special_attention。
> 稀疏(依赖数据完整性,全量更准):family_structure / referral_champion(关系边稀疏)、special_attention 的免打扰/不可等候(本地无数据)。

## 七、算法审查发现 + 口径决策(这轮核心 —— 不是照搬 spec)
1. **RFM**:采业务图 B.1.1 口径(M 按**租户分位** p20/40/60/80,非绝对¥;8 段**决策树**非几何八象限)。补全 spec 缺口:`F<3` 也归 develop(近期单次新客不误落"低活跃")。RFM 与生命周期解耦(RFM 管价值,lifecycle 管阶段)。
2. **lifecycle 顺序 bug**:spec 原顺序「沉睡(末诊>540)」在「流失(末诊>730)」前 → 流失永不触发(被沉睡遮蔽)。**修:流失提前**。另:源表无 `net_receipts_total/total_visit_times` → PAC 自算(同 RFM)。
3. **discount_anchor**:DW 无 `original_amount`;`discount_*_rate` **实为折扣金额非比率**(应收3−dept0.45=实收2.55)→ 折扣率=1−Σ折扣/应收。修 spec naive 点:① 免费洁牙/检查促销(0折)霸占锚点 → 只看原价≥¥500+ratio>0;② 保险方付款非诊所折扣 → 排除 `discount_insurance_rate`。
4. **time_preference**:`occurred_at` 钟点被搞乱(摄入 TZ/解析),`planned_for`+8 才是干净营业钟形 → 用 planned_for。
5. **special_attention**:① `no_show`/`cancelled` 预约 `patient_facts.status≠active/fulfilled` → 不在 persona ctx → 新增 `ctx.appointmentsAll`(全状态单独加载);② `arrived_at`(in_time)摄入 TZ bug 一致早 8h → +8h 补偿。
6. **referral_champion**:逐个被推荐人「均有效转化」需跨患者 + 全量 → v1 用 DW 预聚合 `recommend_num/recommend_amount`(数仓已替我们算)。
7. **acquisition_channel**:DW 实际一级渠道比图多(走入最大、集团销售渠道、瑞尔员工);按数仓实际值,enum_mapping 归一 PAC 立柱标准。
8. **score 弃用**:特征"马上量化"是伪命题,分值是消费场景的事 → 特征只产 `data`,场景自算分。
9. **treatment_chain_status 移除**:它是 episode 级状态非人级属性 → 移出画像,降级为详情页 episode 视图(人级在治信号并入 lifecycle)。

## 八、follow-up / 未实现
- **appointment 时间 TZ 根治**:`occurred_at` 乱 + `arrived_at` 早 8h(+8h 是 band-aid)→ 修 `in_time` 摄入时区。
- **recommend_num 增量游标**:fact_client_out 无 updated_date,游标=`last_visit_time` → 推荐人不来诊则 recommend_num 更新滞后;改 `greatest(last_visit_time, recommend_last_visit_time)`。
- **转介绍 v2**:逐人有效转化(跨患者图谱 + 全量)。
- **discount_anchor 口径**:近免费(>90%off)comp/全保 是否算锚点(现 ≥¥500+ratio>0,未加 floor);¥500 阈值可调。
- **TZ 多宿主**:硬编北京 → 读 host 时区。
- **圈人群 campaign**:未实现;`data` 带 segment + GIN 可查,schema 已 ready(`plan_reasons.campaignId` 预留)。
- **LLM 层标签**:沟通偏好/治疗意向/家庭社交关系等(从自由文本抽,走 AiCall),预留。
- **清理**:`score` 列后续 migration 删;`persona-design-v2.md`(本文)随标签增改维护。

## 九、部署清单(累积)
- **2 migration**:`patient_profiles` 加 acquisition_channel/sub + referral_count/amount_cents。
- **需重摄**(`sync --full`):acquisition/referral(主档)+ entitlement(payment 卡券名)+ discount(payment 折扣额)。
- **重算**:`recompute-persona:prod --force` → `recompute-plans:prod`。
- 其余范式①④标签仅需 `--force` 重算。
