达人三层库新模型设计（P0-2.3）

版本：v1 草案 ｜ 2026-08-17 ｜ 作者：backend-dev ｜ 状态：待主会话评审（评审通过后才出 Alembic 迁移，本文只出设计）

上游输入：口径基线 v2.1 §0/§2/§5/§8（唯一口径源）｜ docs/dev/schema-notes.md（P0-2.2 旧库摸底：8 张达人域旧表逐字段、21 条迁移地雷、8 个开放问题）｜ docs/dev/jixing-api-notes.md（集星 API 字段与三坑）｜ docs/dev/msgbridge-contract.md §2.5/§3（binding_mirror 形状）｜ docs/dev-charter.md v1.3 §4（三分法 + 独立新库）｜ server/app/models/（现有模型风格）

下游：P0-2.4（influencers 域实现）、P0-2.6（集星富化）、P0-2.7（console 列表页）、P0-3.1（建联匹配/wcid 回流）、P0-5.1（商单模型，回写履约事实）、P1-6（推荐子系统）

---

0. 设计前提（定案，不重议）

1. 全新库新口径：所有表建在 xijian / xijian_test（charter §4），旧 lynoxi 表只是一次性导入源，导入后不再依赖；跨库只读仅用于历史成交价/旧订单等（charter §4 三分法「历史旧表」）。
2. 唯一识别键 = 抖音号 + 手机号（基线 §0）；企微加好友只能搜手机号（基线 §0/§6.11）。
3. jixing_* 100+ 历史快照字段不搬：集星走 API 实时拉（dls.lynoxi.com），本设计只保留「档案级消费字段 + 一份最新指标快照」；P1-6 的特征快照库是另一张表，不在本设计范围。
4. quality_douyin_account 弃用不迁：新「优质」= 系统按 cfg 阈值自动判定（基线 §2），不设人工优质池。人工重点名单概念留讨论位（§7 S5），本期不建表。
5. 三层 + 旁类是状态判定，不是分表（基线 §2）：一套判定字段 + 一个推导函数，落一个 layer 列。
6. 判定数字零硬编码：全部走 cfg()（app/domains/config_center/cache.py），表里只存判定结果 + 判定时间，绝不存阈值。
7. 写库前判值是否真变（工程铁律 3）：指标同步用 fingerprint 比对，层级/分级值未变不写。

命名与类型约定（全表统一）

---

1. 表清单总览（7 张，全部新建）

明确不建的表（各有理由，避免评审时误以为遗漏）：

---

2. 逐表设计

列格式：字段 / 类型 / 口径出处 / 导入映射（旧表.旧字段 → 转换规则；—=旧库无此概念，新增）

2.1 influencer（达人主档，人维度）

不迁的旧字段：influencer.id_card（移到表 5，涉税场景才用，R6 权限收敛）、influencer.inviter_id（旧 invite_record 已判死表，邀请关系无消费场景）、influencer.age（改存 birth_year）。

2.2 douyin_account（抖音账号 / 三层落点）

不迁：全部 jixing_*（约 100 列，走 API）、work_count（地雷 7：字段已不存在）、旧 GMV 类字段（基线 §8 单位存疑，只放行已验证的 → 一律从集星重拉，见 2.3）。

2.3 douyin_account_metric（近 30 天指标最新快照，与账号 1:1）

为什么单独一张表：档案字段稳定、指标字段日更；分表后同步任务只写这一张，主表不被高频 UPDATE 污染（旧仓 binlog 日增 5G 的教训，铁律 3）。

2.4 influencer_binding（企微绑定镜像，收编契约 binding_mirror）

契约 §2.5 要求的字段 (influencer_id, guid, peer_user_id, conv_id, source, synced_at) 全部包含，本表是其超集实现（表名差异见 §7 S6）。

唯一约束 uq(guid, peer_user_id)：一个企微身份在一个我方账号下只绑一个达人（与消息台 peer_binding 同语义）。一个达人可有多条（多个我方账号加过他）。

2.5 influencer_payment_info（收款信息，1:N）

权限：本表读取挂新权限码 influencer.payment.read；列表接口一律掩码（卡号/身份证只回后 4 位）。依据基线 §9.3 R6「底价/达人库字段权限收敛」。

2.6 influencer_service_region（接单地区，1:N）

唯一约束 uq(influencer_id, province, city, district) 防重复录入。

2.7 influencer_blacklist（人工拉黑记录，可逆）

约束：应用层校验 influencer_id 与 douyin_account_id 至少一个非空（两列都可空，DB 级 CHECK 可选加 ck_influencer_blacklist_target）。生效中的黑名单 = revoked_at IS NULL；influencer.blacklisted 是它的冗余当前态，值真变才写。

---

3. 三层判定规则（基线 §2 表的落地）

3.1 判定落点：layer 唯一挂在 douyin_account

理由：池层（有信息、未建联）的实体只有账号没有人（influencer_id IS NULL），层级若挂人维度则池层无处安放。人维度不存 layer，避免两份真相；需要「人属于哪层」时由服务层函数实时算（见 3.3）。

3.2 推导规则（纯函数，输入全是事实字段）

def resolve_layer(acc, inf) -> str:
    # 优先级自上而下，命中即返回
    if acc.is_leader_reported and acc.influencer_id is None:
        return "side_partner"      # 旁类：已合作未建联（基线 §2 旁类行）
    if acc.first_settled_order_at is not None:
        return "fulfilled"         # 已履约：至少一个商单走到已结算
    if inf is not None and is_contactable(inf):
        return "contacted"         # 已建联：企微或小程序可触达
    return "pool"                  # 达人广场池：有信息、未建联

def is_contactable(inf) -> bool:
    return bool(inf.wx_open_id) or EXISTS(influencer_binding
                                          WHERE influencer_id=inf.id AND active=1)

关键说明： - 旁类不会与 fulfilled 打架：旁类走团长线、不产生犀见商单，first_settled_order_at 天然为 NULL；且一旦补齐联系方式并建了人（influencer_id 非空），判定自动升级，不需要人工改标。 - 有手机号 ≠ 已建联：手机号只是可发好友申请的前提（基线 §6.11），未加上企微仍是 pool——这正是「每周新增 500 名进企微」KPI 的目标池：layer='pool' AND influencer.phone IS NOT NULL。 - 无手机号也可能已建联：企微不给外部联系人手机号（契约 §2.5 实测），wcid 回流绑定的达人可能永远没有 phone。所以 phone 必须可空，见 §5。

3.3 人维度层级（不落库）

def layer_of_influencer(inf) -> str:
    accs = 其名下未软删账号
    if accs: return max(acc.layer, key=层级序)        # 序：fulfilled > contacted > side_partner > pool
    return "contacted" if is_contactable(inf) else "pool"   # 孤儿达人（有人无号，旧库存在）

3.4 重算触发时机（写前判值真变）

纪律：layer 值未变则整行不 UPDATE（连 layer_at 也不动）；layer_at 语义 = 层级变更时间，不是「上次计算时间」。计算过程走结构化日志，不落库。

3.5 旁类隔离（不占建联流程）

统一由一个查询 helper 收口，不散落在各处 where 里：

# app/domains/influencers/scope.py
def outreach_scope(q):      # 建联/邀约/加好友/催发类名单一律先过这个过滤器
    return q.where(DouyinAccount.layer != "side_partner",
                   DouyinAccount.deleted_at.is_(None))

覆盖场景：②A 定向邀约名单（基线 §6.9）、批量好友申请（§6.11）、一键催发（§6.10）、推荐清单候选（§5.3）。旁类账号仅出现在「数据归档/对账」类视图，并在 console 三层 tab 中独立成一个 tab（不混入已建联）。

---

4. 分级与推荐指数

4.1 分级判定（基线 §2 + §7.4，全部阈值走 cfg）

roi  = (成交GMV_fen - 达人费用_fen) / 达人费用_fen          # 基线 §7.4，绝不用旧库存的 roi 列（地雷 15）
cpm_fen = 达人费用_fen / 曝光数 * 1000                      # 基线 §7.4

if cpm > cfg("grade.cpm_low_recommend_threshold"):   grade = "low_recommend"
     recommend_penalty_reason = "cpm_over_low_recommend_threshold"     # 降推荐指数、沉底，不拉黑
elif roi > cfg("grade.roi_excellent_min") \
     and cpm < cfg("grade.cpm_excellent_max") \
     and primary_category ∈ cfg("grade.travel_category_whitelist"):    grade = "excellent"
else: grade = "normal"

• 判定顺序：低推荐先判（基线 §2 里 low_recommend 与 excellent 的条件互斥，CPM>80 不可能同时 CPM<20，先判哪个都一样；写死顺序是为了可测边界）。
• 取数窗口：只用满 cfg("data.ramp_protection_days") 天的视频数据（基线 §8 爬坡保护）。
• 阈值比较严格按基线的开闭区间：ROI > 10（恰等于 10 不算优质）、CPM < 20、CPM > 80——P0-2.8 契约测试逐个边界值验。
• 未履约（settled_order_count = 0）→ grade='ungraded'，不参与优质/低推荐判定。

4.2 计算触发时机

判值真变：grade 未变 → 不写 grade/grade_at；但 grade_evidence 内的 roi/cpm 变化属正常刷新，允许更新（它是证据不是判定结果）——若怕高频写，evidence 也用 fingerprint 比对（与 2.3 同一手法），建议采纳。

4.3 推荐指数（P1-6 占位）

本期只建字段不算值：recommend_index、recommend_index_at、recommend_penalty_reason。P0 期 recommend_index 恒 NULL，console 显示「—」。recommend_penalty_reason 在 P0 就写（分级顺带产出），供 P1-6 沉底排序直接消费。

4.4 本设计需要的 cfg 键

两个新键都不进本次迁移的判定路径（占位即可），确认后由配置中心补种子迁移。

---

5. 索引与唯一约束

5.1 唯一键落地（基线 §0「抖音号 + 手机号」）

组合键在关系模型里自然分解为两个可空唯一键，靠 influencer_id 关联：

中间态一览（都是合法状态，不能用 NOT NULL 堵）：

应用层校验（DB 无法表达）：influencer 至少要有 phone/wx_open_id/有效 binding 三者之一才允许创建；否则拒绝（否则会造出永远匹配不上的幽灵档案）。

匹配与冲突（P0-2.4/P0-3.1 共用）： 1. 先按手机号查 influencer，再按抖音号查 douyin_account； 2. 两边都命中且 account.influencer_id != influencer.id → 冲突：返回 envelope code=409（HTTP 200，先例 app/domains/system/roles_service.py:20；P0-2.8 所写「唯一键冲突 409」即此 code，非 HTTP 状态码），并给出双方 id 供人工合并； 3. 只命中一边 → 建联即补齐另一边（不新建重复档案）； 4. 都没命中 → 新建（P0-3.1 的「未命中建档进已建联」）。

软删与唯一键：软删行仍占用唯一号（deleted_at 不参与唯一索引，MySQL 无部分索引）。重新入库 = 复活原行（deleted_at=NULL），导入脚本按 legacy_id/douyin_id upsert 天然满足。

5.2 索引清单

模糊搜索（昵称/姓名 kw）：本量级（万级）用 LIKE 'kw%' 前缀索引即可，不引全文索引（YAGNI）；LIKE '%kw%' 走全表在万级可接受，超 10 万行再议。

---

6. 导入映射与地雷规避

6.1 导入步骤（一次性、可重跑、有对账）

1. 前置核对（解 schema-notes §5#1/#2）：连 lynoxi_test 跑 information_schema.columns 导出达人域 8 表真实列清单，与 schema-notes 的源码推导逐列比对，差异先记录再导入；同时确认「达人广场 19,299 行采集数据是否就在 douyin_account」。
2. 只读跨库：独立只读 engine + 只读账号，SQL 一律全限定名 lynoxi.xxx；分页按主键游标（WHERE id > ? ORDER BY id LIMIT n），禁 OFFSET 深分页（schema-notes §4-20）。
3. 顺序：influencer → douyin_account（补 influencer 映射）→ payment_info/region/blacklist → 计算 layer → 重算 ROI/CPM → 计算 grade。
4. 幂等：全部按 legacy_id upsert；逐字段比对，值未变不写（铁律 3）。
5. 对账产出（脚本必打印，qa 验收看这个）：各表源行数/成功/跳过/reject 数、字段级空值率、influencer_id 悬空数、抖音号缺失数、重复手机号数、layer 分布、grade 分布。
6. reject 清单落文件不静默丢：空抖音号、脏 UTF-8、重复唯一键、age=-1 等异常各成一节。
7. 集星富化独立于导入（P0-2.6）：导入只搬旧库有的、已验证的；指标一律事后从集星 API 拉。

6.2 地雷逐条对应（schema-notes §4 全 21 条）

6.3 ROI/CPM 重算的数据来源（导入期）

旧库已结算订单仅 13 条（schema-notes §2.2 实测）——历史 ROI/CPM 样本极稀，导入后绝大多数达人 grade='ungraded' 是预期结果，不是 bug；qa 验收按此口径核对。

---

7. 开放问题与裁决建议

主会话评审结论（2026-08-16）：设计通过，S1–S11 全部按建议倾向裁决采纳。其中 S2/S5 已获用户定案（2026-08-16 二批确认）：S2 白名单=酒店宾馆/景点票券/游玩项目（可配，excellent 短路解除）；S5 建 influencer_watchlist 表（用户：可以做且有必要，命名禁用「优质」）；S7（credit_score 新口径）仍待业务；S6 契约加注已批准执行；S11 权限码扩充已批准。放行后半段：出 Alembic 迁移与模型代码。 状态原图例：待裁决=需主会话拍板 ｜ 待业务=口径缺口需产品/业务确认 ｜ 已自决=本设计已定

---

8. 给 P0-2.4 的接口预告（域接口草签名）

模块布局（单模块 ≤200 行，路由/服务/模型分层）：

app/domains/influencers/
├── router.py        # 达人档案 CRUD 路由
├── accounts_router.py  # 抖音账号路由
├── service.py       # 档案读写（唯一键匹配/冲突 409）
├── layer.py         # 三层判定纯函数（§3.2）+ 重算入口
├── grade.py         # 分级计算（cfg 取阈值，§4.1）
├── scope.py         # outreach_scope 等共享查询过滤器（§3.5）
└── schemas.py       # pydantic 模型即文档

REST 草签名（全部走 envelope，业务错误 HTTP 200 + success:false）：

域内函数签名（供 P0-3.1/P0-5 调用，不走 HTTP）：

layer.resolve(account, influencer) -> str                  # §3.2 纯函数
layer.recompute_for_influencer(session, influencer_id) -> int   # 返回真正变更的行数
layer.mark_settled(session, account_id, settled_at) -> bool     # 商单域回写履约事实，值真变才写
grade.evaluate(session, influencer_id) -> GradeResult      # cfg 取阈值，返回 grade+evidence
match.find_by_unique_key(session, phone=None, douyin_id=None) -> MatchResult  # 命中/冲突/未命中

---

附：信息来源

• docs/business/xijian-business-baseline.md v2.1 §0/§2/§5/§7.4/§7.6/§8/§9.3/§12A
• docs/dev/schema-notes.md（P0-2.2）§1.1/§2.1/§2.2/§4（21 条地雷）/§5（8 个开放问题）
• docs/dev/jixing-api-notes.md（字段清单 + 三坑；digit_value 单位=分为本次由样本 44.21万↔44214338 反推核实）
• docs/dev/msgbridge-contract.md §2.1/§2.5/§3.1/§3.2/§4.3
• docs/dev-charter.md v1.3 §4（独立新库 xijian + Schema 三分法 + 表名前缀定案）
• server/app/models/{base,config,msgbridge}.py（命名约定、注释风格、无前缀先例）、server/app/envelope.py、server/app/domains/system/roles_service.py:20（409 先例）、server/app/domains/config_center/{cache,seed}.py（cfg 与占位行先例）

变更记录