#Activity Timeline Schema

Live code verified：2026-07-15

Source of truth： callytics-infrastructure/packages/common/src/db/schema/contact-timeline.ts 表名： contact_timeline；主键 id bigserial

Task domain boundary： Task V3 Product / Domain Contract 是 selected Target；Task V3 Rollout 状态快照 记录 source、deployment、TEST、UAT 与 PROD readiness。下文的 V2 名称只描述 compatibility vocabulary，不定义当前 rollout 状态。

#1. 当前职责

contact_timeline 是 Contact 维度的 append-only factual/audit ledger，集中记录 Lead、Message、Call pipeline、Contact 变化和 Task history。

对 Task 而言，当前正确边界是：

tasks                    = 当前 Task snapshot
contact_timeline         = Activity + status/assignment/schedule history
task_suggestions         = 行动建议

当前没有 task_progress_events 表。新的真实工作记录写：

event_type  = task.activity_recorded
entity_type = task
entity_id   = task_id

task.progress_recorded 仅保留给历史记录和兼容读取；不应再作为新写入的标准 event。

V3 Target 继续复用这份 ledger 记录 Activity、Next Action、status、Outcome correction 和 audit；不引入 rigid Step。目标语义见 Task V3 Product / Domain Contract；Task V2+ audit 只保留历史工程背景。

#2. Live fields

#Contact 与 isolation

新写入路径必须有 storeId；历史 NULL 不能被当成安全的跨店合并依据。

#Event 与 entity reference

#Payload

JSONB 不代表“随便写”。每个 canonical event 应有 versioned typed payload contract；API 不应要求客户端自行猜 JSON shape。

#Actor 与 business attribution

actorSubjectId 与 staffId 不应合并：系统可以代写一条 Activity，但业务工作仍归属给实际执行员工。

#AI forensic

这些字段解释“AI 为什么产生这条 proposal/mutation”；它们不能把 AI inference 自动升级为 externally verified fact。

#幂等和时间

排序客户历史默认用 occurredAt，但必须保留 createdAt 以识别延迟写入、backfill 和 import。

#3. Live TIMELINE_EVENT_TYPE

当前 const 有 22 个 values：

关闭和 reopen 复用 task.status_changed，不另造 task.closed / task.reopened。

#4. Task Activity contract

Activity payload vocabulary 由 packages/common/src/db/schema/task-progress.ts 定义：

TASK_ACTIVITY_CONTRACT 进一步限制 channel/action/outcome 的合法组合，例如 message_sent + no_answer 不是同一时刻的有效事实。

provider_confirmed 是 current schema 中的 future-facing scaffolding；当前产品没有可依赖的 booking/membership/billing provider writer。V3 Target evidence vocabulary 和 migration boundary 见 Task V3 Product / Domain Contract §3.3。

Activity 与其他层的边界：

no_answer / voicemail_left    → Activity outcome
follow_up_agreed              → conversation disposition + possible Next Action
booked / upgraded             → Task-specific Outcome + verification/evidence
DNC                           → Contact restriction

#5. 关键完整性约束

• actor_source_type 必须属于 live 6-value vocabulary。
• event_category 必须属于 live 7-value vocabulary。
• actor_type='staff' 时 actor_subject_id 必填。
• staff_id 非空时 store_id 必填。
• staff_id + store_id 通过复合 FK 指向同一门店的 staff。
• non-null idempotency_key 必须唯一。

#6. 关键索引

这些索引支持当前 Task history 和 Activity query。Target 新增 event 时应根据真实 Workbench/reporting query 补索引，不预先引入 Step linkage。

#7. Target boundary

• Task row 保存 current snapshot。
• contact_timeline 保存 Activity 与所有重要变化的 append-only history。
• 一次真实 interaction 只计一次 interaction/staff credit；它可以通过 evidence refs 支撑多个 Tasks 的判断。
• MVP 不新建 task_activities、actions 或 task_steps table。
• 是否最终抽独立 activities table，应由 query、FK 和 scale 证据决定；不应同时维护两份 Activity source of truth。

#8. Cross-references

• Task V3 Product / Domain Contract
• Task V3 Rollout 状态快照
• Historical Task V2+ audit
• Lead Funnel 与状态