#Store-Level 数据隔离

终态设计:store_id(UUID) 是唯一隔离键。所有 Neon 表查询统一用 WHERE store_id = ?。

retaintive 平台
│
├── Brand: "orangeTheory"                    ← franchise_id（硬编码，所有店一样，不做隔离）
│   │
│   ├── Account: "193365026"                 ← account_id（原 site_id，来自 RC OAuth owner_id）
│   │   │                                       一个账号可以有多家店
│   │   ├── 🏪 Store: Devon                  ← store_id = UUID（我们 randomUUID() 生成）
│   │   │   └── 📞 ×6 phones                    一个店有 4-9 个电话
│   │   ├── 🏪 Store: White Plains           ← store_id = UUID
│   │   │   └── 📞 ×7 phones
│   │   ├── 🏪 Store: Scarsdale             ← store_id = UUID
│   │   │   └── 📞 ×5 phones
│   │   ├── 🏪 Store: Marlboro              ← store_id = UUID
│   │   │   └── 📞 ×7 phones
│   │   ├── 🏪 Store: Woburn                ← store_id = UUID
│   │   │   └── 📞 ×5 phones
│   │   └── 🏪 Store: Ardmore               ← store_id = UUID
│   │       └── 📞 ×5 phones
│   │
│   ├── Account: "809646016"                 ← 另一个 RC 账号，只有 1 家店
│   │   └── 🏪 Store: Auburn
│   │       └── 📞 ×4 phones
│   │
│   └── ... (共 8 个 RC 账号，13 家店，78 个电话号码)
│
└── (未来) Brand: "Rinse & Shine"
    └── Account (RC / Zoom / Vonage)
        ├── 🏪 Store: Downtown
        └── 🏪 Store: Uptown

PK       = "这条记录的唯一身份是什么"  → 决定数据怎么存
store_id = "谁能看到这条记录"          → 决定数据怎么查（WHERE store_id = ?）

-- 所有表统一
WHERE store_id = :storeId

-- 不再需要：
-- ❌ WHERE franchise_id = ? AND site_id = ?
-- ❌ WHERE store_phone IN (?, ?, ?) OR store_id = ?
-- ❌ WHERE site_id = ? AND (store_phone IN (...) OR store_id = ?)

#终态写入规则

每条数据写入 Neon 时，必须同时带 store_id 和 store_phone（如适用）。不同数据来源的解析方式：

#概念词典

#2. 场景验证

#新客户 Onboarding

代码分布在 3 个 repo：studio-website-monorepo（主）、ringcentralSubscriptionService、callytics-infrastructure。

Phase 1: 连接 RingCentral（用户点 "Connect RingCentral"）

用户浏览器                studio-api                       RingCentral
──────────               ──────────                       ────────────
点击 Connect  → POST /v2/auth/initiate
                         生成 stateId, 存 OAuthStates DDB
              ← 返回 RC 授权 URL ──────────────→
                                                         用户登录授权
              ← RC redirect ──── callback?code=xxx

                GET /v2/auth/callback
                  ① code 换 tokens
                  ② providerAccountId = tokens.ownerId   ← 这就是 account_id
                  ③ 并行写 3 个 DDB 表：
                     ├─ UserConnections（加密 tokens）
                     ├─ PhoneNumbers（从 RC API 拉所有电话，storeId=null）
                     └─ CallAnalysisConfiguration（callytics 配置）

✅ 结果：RC 账号已连接，电话号码已导入。但还没有"店"。

Phase 2: 创建门店（用户点 "New Store"，手动操作）

POST /v2/stores
  ① 验证电话属于该用户
  ② storeId = randomUUID()              ← ★ store_id 在这里诞生
  ③ 并行写 3 个 DDB 表：
     ├─ StoresV2（PK=storeId，存店名/配置/providerAccountId）
     ├─ PhoneStoreAssignments（每个电话一条，PK=storeId SK=phoneNumber）
     └─ UserStore（userId+storeId, role=OWNER）

✅ 结果：门店存在了，电话号码已绑定。

Phase 3: 开启实时分析（用户开 "Realtime Analysis" 开关）

studio-api → invoke ringcentralSubscriptionService Lambda
  ① 用加密 tokens 调 RC API 拿所有分机
  ② 每 19 个分机一组，创建 RC webhook 订阅
  ③ RC 每通电话/短信 → webhook → WebhookReceiver → SQS → pipeline

✅ 结果：电话录音开始自动转录和 AI 分析。

Phase 4: Historical Backfill（新店激活后的内部 operator step）

新店刚接入时，用户真正想看的通常不是“从现在开始才有数据”，而是“先把过去两周的电话和消息补进系统”。这个步骤应该由内部运营/工程在 control-plane 或 operator tool 里触发，不是客户自助随便点的按钮。

control-plane / operator
  -> enqueue onboarding_historical_backfill job
       storeId
       providerAccountId / connectionId
       startTime = now - 14 days
       endTime = now
       mode = execute

Calls path:
  reconciliation-worker
    -> RingCentral call-log
    -> compare with Neon calls
    -> missing call becomes synthetic webhook
    -> existing transcribe-queue
    -> transcribe-processor
    -> ai-analysis-processor
    -> contacts-analyzer
    -> calls / contacts / contact_timeline / tasks

Messages path:
  message historical backfill job（待补）
    -> RingCentral message-store
    -> existing message-processor write path
    -> messages / contacts / contact_timeline

设计原则：

• Calls 不重写 pipeline：reconciliation-worker 已支持 reconciliation_window.startTime/endTime，并把 missing calls 注入现有 transcribe-queue。Onboarding 只需要一个更清晰的 trigger / job wrapper。
• Messages 现在是 gap：studio-api 可以按 storeId/dateFrom/dateTo 从 RingCentral message-store 读取，message-processor 也能把 message-store webhook 写进 Neon；但还缺一个和 call reconciliation 同级的 historical message backfill job（跟踪：retaintive/callytics-infrastructure#1156）。
• Backfill 仍必须走 store-level isolation：任何导入都要先 resolve / verify store_id，不能只按 franchise_id 或 provider account 粗粒度写库。
• ⚠️ Backfill window 必须尊重 phone→store 分配的生效时间（DEFERRED）：本节上文《电话移动》明确要求 phone move / 号码 recycle 时旧数据留在旧店（TCPA + 行业标准）。但这个保证靠的是 event 在发生当时写库定格 store_id；backfill 是事后回放，会用执行时的 phone→store 映射解析归属。而当前 resolvePhoneIdentity 查的 rc_store_phones 是 current-state 表（只有 store_id + phone_number，无 assignedAt / 生效时间），无法做 point-in-time 解析。后果：若某电话在不足 14 天前才分配 / 移入本店，startTime = now - 14d 会把分配之前的 call/message 按今天的归属误写到新 store/tenant，违反上面的隔离承诺。正确做法是把 window 上限 cap 在该电话对本店的分配生效时间，但当前 schema 不支持，故标 DEFERRED。恢复条件：rc_store_phones（或新映射表）加 time-aware 字段（assigned_at / valid_from / valid_to）后，backfill 改为按 event 时间做 point-in-time 解析。
• Idempotent by default：重复触发同一个 14 天 window 不应该重复写 task / message / timeline；writer 入口需要用 provider message/call id 做 UPSERT 或 duplicate guard。

关键点：storeId 是我们自己 randomUUID() 生成的，不来自 RingCentral。换任何电话平台都不影响 store_id。

#电话移动（A 店 → B 店）

用户在 UI 里编辑门店电话列表，代码算 diff：

操作前：Devon 有 📞A B C D E F，White Plains 有 📞G H I
用户把 📞F 从 Devon 移到 White Plains

PUT /v2/stores/devon-id     → DELETE PhoneStoreAssignments (devon-id, 📞F)
PUT /v2/stores/wp-id        → PUT PhoneStoreAssignments (wp-id, 📞F)

操作后：Devon 有 📞A B C D E，White Plains 有 📞G H I F

对历史数据的影响：

这就是 store_id 比 store_phone 安全的核心原因。

#换平台（RC → Zoom / Vonage）

变的部分（接入层）：
  新增一个 Zoom webhook adapter Lambda
  PhoneStoreAssignments 加 Zoom 的电话号码

不变的部分（核心）：
  resolvePhoneIdentity() → 照样查 PhoneStoreAssignments → 返回 storeId
  所有 Neon 表的 store_id → 不变
  所有 API 的 WHERE store_id = ? → 不变

store_id 和电话平台完全解耦。换平台 = 加一个 webhook adapter + 绑电话号码，核心 pipeline 零改动。

#✅ 已覆盖场景

#🔴 Critical Bug + 必须堵的 Gap

Bug: 电话可以同时属于多家店，代码没处理 (🔴 Still UNFIXED as of 2026-04-26)

代码确认（studio-api/routes/stores/create.ts:67）：

// Note: phones can be assigned to multiple stores (no restriction on already-assigned)

resolvePhoneIdentity() 用 Limit: 1 查 GSI — 一个电话在两个店里时随机返回一个。

后果：

• Task 写到错的 store
• AI analysis 混合两个店的 staff list
• 跨店数据泄漏

修复：建店/改店时验证：同一 providerAccountId 下，一个电话只能绑一个 store 类型的店。（group 类型不受此限）

Tracked: studio-website-monorepo#228 (P0 as of 2026-04-26)

#📋 Known Limitations（OTF 目前不涉及）

#3. 落地状态(2026-04-26 verified)