Add under-anything knowledge dashboard

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

@@ -0,0 +1,199 @@
+# 子系统 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 |