Fulfilled-Knowledge/wishfulfilled-wiki/05_需求文档/01-子系统-用户身份与上下文.md

子系统 01 — 用户身份与上下文 (identity) v1.0

子系统概述

维度	说明
代号	identity
核心职责	真实人识别与归并、身份线索关联、用户上下文卡生成
数据所有权	person_profiles, person_identity_links, contact_context_snapshots, device_records
启动依赖	无硬依赖（需 JOYHUB 数据同步到位）
外部系统依赖	JOYHUB（用户数据）、APP（设备数据）

---

1. 模块划分

整体模块图

┌─────────────────────────────────────────────────────────────┐
│                    identity 子系统                           │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │ M1: 身份线索  │  │ M2: 真实人   │  │ M3: 用户上下 │       │
│  │    采集与同步 │→│    归并引擎  │→│    文卡服务  │       │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘       │
│         │                 │                 │                │
│         ▼                 ▼                 ▼                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │ M4: 设备变化 │  │ M5: 身份管理 │  │ M6: 对外 API │       │
│  │    识别      │  │    Admin     │  │    Gateway   │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
│                                                             │
└─────────────────────────────────────────────────────────────┘

模块明细

#	模块	代号	职责
M1	身份线索采集与同步	identity-ingest	从 JOYHUB、APP 等外部系统拉取/接收身份线索（JOYHUB ID、邮箱、电话、设备号、订单关联）
M2	真实人归并引擎	person-merge	按标准姓名+地址、多线索交叉权重归并，生成/更新真实人 ID
M3	用户上下文卡服务	context-card	聚合身份+交易+服务+风险+设备+触达全量数据生成上下文快照
M4	设备变化识别	device-tracker	识别设备号变化、换机、多设备场景，记录设备变化日志
M5	身份管理 Admin	identity-admin	人工归并/拆分操作、归并冲突处理、身份数据校正
M6	对外 API Gateway	identity-api	向其他子系统提供真实人查询、上下文卡查询、归并请求等 API

---

2. 各模块内外说明

2.1 M1: 身份线索采集与同步

维度	说明
对内	管理外部系统的数据同步任务（定时拉取 JOYHUB 用户数据、设备数据）；解析和标准化各来源的身份线索（邮箱规范化、电话格式化、地址标准化）；写入 person_identity_links 表
对外接口	POST /internal/identity/ingest — 接收上游推送的身份线索；同步调度器可配置频率
数据写入	person_identity_links（线索类型 + 线索值 + 来源系统 + 采集时间）

2.2 M2: 真实人归并引擎

维度	说明
对内	执行归并规则：标准姓名+地址一致→同一真实人；多线索交叉（设备+电话+邮箱+收款信息）按权重打分；地址一致姓名不同→标记家庭关联但不合并；生成真实人 ID、归并证据、置信度
对外接口	POST /api/identity/merge — 触发归并；返回归并结果（真实人 ID + 置信度）
数据写入	person_profiles（真实人创建/更新）、person_identity_links（关联关系更新）
关键规则	邮箱不同+JOYHUB ID 不同不能单独否定「同一真实人」；订单号命中历史异常需拉出风险记录

2.3 M3: 用户上下文卡服务

维度	说明
对内	聚合 6 组字段（当前身份、真实人归并、历史交易、历史服务、历史风险、当前设备、触达历史）；生成上下文快照（含快照时间）；首次生成 vs 增量更新
对外接口	GET /api/identity/context/{person_id} — 获取用户上下文卡；返回聚合后的全量上下文
数据写入	contact_context_snapshots
依赖其他子系统	交易数据来自 planning；服务数据来自 support；风险数据来自 risk；触达数据来自 outreach（通过 API 聚合或事件）

2.4 M4: 设备变化识别

维度	说明
对内	监控同一 JOYHUB ID 下设备号变化；记录换机/多设备事件；关联设备型号、系统版本、APP 版本变化
对外接口	内部事件 device.changed 供其他模块消费
数据写入	device_records（设备变化时间、变化类型）
待确认	多久内的设备变化算「近期换机」？多设备同时活跃如何标记？

2.5 M5: 身份管理 Admin

维度	说明
对内	提供人工归并操作界面（两个真实人合并为一个）；归并拆分（合并错了如何回退）；冲突处理（系统自动归并 vs 人工判定不一致时）
对外接口	管理 API（不对其他子系统暴露）
数据写入	所有身份相关表（权限控制）

2.6 M6: 对外 API Gateway

维度	说明
对内	统一对外 API 认证、限流、日志
对外接口	GET /api/identity/person?线索类型=&线索值= — 按线索查真实人；GET /api/identity/context/{person_id} — 用户上下文卡；POST /api/identity/batch-check — 批量身份查询

---

3. 对外 API 契约（草案）

接口	方法	输入	输出	消费者
按线索查真实人	GET /api/identity/person	?type=email&value=xxx@yy.com 或 ?type=joyhub_id&value=123	{person_id, confidence, matched_clues[]}	所有子系统
获取用户上下文卡	GET /api/identity/context/{person_id}	person_id	{identity, transactions, services, risks, devices, outreach_history}	support, risk, outreach
批量身份查询	POST /api/identity/batch-check	[{type, value}, ...]	[{person_id, confidence}, ...]	planning, outreach
触发归并	POST /api/identity/merge	{clues: [{type, value}, ...]}	{person_id, is_new, confidence}	outreach（每次互动时调用）

---

4. 数据对象（本子系统写入）

对象	核心字段	说明
person_profiles	person_id, status, created_at, updated_at, merge_evidence	真实人主表
person_identity_links	person_id, clue_type (JOYHUB_ID/EMAIL/PHONE/DEVICE/ORDER_NAME_ADDRESS), clue_value, source, confidence, linked_at	身份线索关联表
contact_context_snapshots	person_id, snapshot_time, identity_snapshot, transaction_snapshot, service_snapshot, risk_snapshot, device_snapshot, outreach_snapshot	上下文快照
device_records	person_id, joyhub_id, device_id, device_model, os_version, app_version, change_type (NEW/SWITCH/MULTI), recorded_at	设备变化记录

---

5. 业务澄清问题清单 — identity

5.1 真实人归并规则（4 项）

#	问题	优先级
I-01	标准姓名+地址的「标准化」规则是什么？（大小写、空格、缩写如 St./Street、middle name 处理？）标准化在哪个模块做？	P0
I-02	归并是多线索交叉权重打分——各维度的权重如何设定？（邮箱=0.3、设备=0.4、电话=0.2、收款=0.5？由谁定义？可否动态调整？）	P0
I-03	归并是完全自动执行还是部分需要人工审核？触发人工审核的条件是什么？（置信度 < 多少？涉及风险用户？）	P0
I-04	自动归并错误后如何拆分？拆分时如何处理已关联的历史评价和额度数据？（评价归属、额度扣减是否回滚？）	P0

5.2 非 APP 用户处理（3 项）

#	问题	优先级
I-05	非 APP 用户的邮箱从哪里来？（Amazon 订单中的买家邮箱？EDM 列表？客服录入？）邮箱质量/有效性如何保证？	P0
I-06	只有邮箱没有设备号的非 APP 用户，归并置信度是否单独设置较低阈值？这种情况下如何确定是同一真实人？	P1
I-07	EDM 引导用户注册 APP 后——如何识别「这个新 APP 用户就是之前那个 EDM 邮箱用户」？（注册时要求填同一邮箱？设备号关联？）	P1

5.3 设备与多账号（3 项）

#	问题	优先级
I-08	「同设备多账号」的风险判断——同一个设备号关联了多个 JOYHUB ID，哪些情况正常（家庭共用）哪些算风险信号？	P1
I-09	设备号变化的识别窗口——同一个 JOYHUB ID 下，设备号变化间隔多久内算「近期换机」？	P1
I-10	APP 卸载重装导致设备号变化怎么处理？（卸载重装可能生成新设备号）	P2

5.4 用户上下文卡（3 项）

#	问题	优先级
I-11	上下文卡的「快照」保留几份？每次互动生成新快照（保留历史）还是覆盖（只保留最新一份）？保留历史的话保留多久？	P1
I-12	上下文卡中的历史交易、历史服务等数据是从其他子系统实时拉取还是从本地冗余存储读取？（涉及跨子系统数据一致性）	P1
I-13	上下文卡是否需要在某个条件触发时预生成（如用户接入前），还是每次实时生成？	P2

5.5 数据同步（2 项）

#	问题	优先级
I-14	JOYHUB 数据同步频率？（实时/每小时/每天？）同步方式？（API 拉取 / 消息队列 / 数据库直连？）	P0
I-15	JOYHUB 和 APP 端的数据字段完整清单是否已有？（注册邮箱、设备号、设备型号、APP 版本、系统版本、绑定玩具、活跃行为——文档已列出但需确认是否有遗漏）	P0

5.6 身份数据生命周期（4 项）

#	问题	优先级
I-16	用户数据保留策略——身份线索和历史快照保留多久？（6个月？1年？永久？）超出保留期后是归档还是删除？	P1
I-17	用户注销/数据删除请求如何处理？（用户要求删除所有个人数据——如何标记而不是物理删除以保持额度/风险记录的完整性？）	P1
I-18	「被遗忘权」实操——删除真实人记录后，与之关联的额度、风险、评价如何处理？（匿名化保留？还是级联删除？）	P1
I-19	用户主动修改关键身份信息（换邮箱、换电话）——系统如何感知和响应？（自动触发重新归并？还是保持原关联？）	P1

5.7 多站点与跨平台身份（3 项）

#	问题	优先级
I-20	同一个自然人在 Amazon.com 和 Amazon.co.uk 用不同邮箱和地址——是否跨站点归并为同一个「真实人」？	P1
I-21	未来扩展到非 Amazon 平台（eBay/Walmart/独立站）——真实人体系是否需要跨平台？架构预留？	P2
I-22	不同国家站点的地址标准化规则不同（US→州/邮编、UK→郡/邮编、DE→邮编/城市）——标准化引擎如何处理？	P2

5.8 归并冲突与人工干预（3 项）

#	问题	优先级
I-23	系统自动归并和人工判定冲突时，以谁为准？（人工优先？系统告警→人工确认？）冲突记录保留多久？	P1
I-24	人工拆分归并的操作是否需要审批？（谁来审批？审批流程？）拆分的审计记录保留什么字段？	P1
I-25	是否存在「不确定」状态的真实人？（置信度太低无法归并，标记为「待定」——如何流转到人工审核？）	P1

5.9 实施层面（3 项）

#	问题	优先级
I-26	身份归并是实时还是异步？（用户接入时实时归并→阻塞用户体验 vs 异步归并→可能用旧数据？）	P1
I-27	上下文卡聚合的性能要求——单次查询需要在多少 ms 内返回？（涉及跨子系统调用时的超时和降级）	P2
I-28	如果 JOYHUB 数据同步中断，identity 子系统如何降级？（用缓存数据？标记为「数据可能过期」？）	P1