social-app/docs/runtime/runtime-database.md

Database Schema

Status: Active Reference: Plan: social-app 数据模型重设计

---

枚举约定

所有枚举使用字符串存储，不使用整数值：

• Database: VARCHAR(20) + CHECK 约束
• Code: Python Enum 继承 str

---

表清单

表名	说明
profiles	用户资料（含 settings JSONB）
user_agents	用户专属 Agent
memories	用户/工作记忆
friendships	好友关系
groups	群组
group_members	群组成员
schedule_items	日程事项
schedule_subscriptions	日程订阅与权限
inbox_messages	待处理消息
todos	待办
todo_sources	待办与日程来源关联
automation_jobs	定时任务
sessions	Agent 对话会话
messages	会话消息记录
llm_factory	LLM 工厂配置
llms	LLM 模型实例
user_agent_catalog	Agent 类型目录
invite_codes	邀请码

---

表结构

profiles

用户资料表，含内置设置。

字段	类型	说明
id	UUID	PK，auth.users.id
username	VARCHAR(30)	用户名
avatar_url	TEXT	头像 URL
bio	VARCHAR(200)	个人简介
settings	JSONB	用户设置
referred_by	UUID	邀请人 ID
created_at	TIMESTAMPTZ	创建时间
updated_at	TIMESTAMPTZ	更新时间
deleted_at	TIMESTAMPTZ	软删时间

约束： username 唯一

settings JSONB 默认结构：

{
  "version": 1,
  "preferences": {
    "interface_language": "zh-CN",
    "ai_language": "zh-CN",
    "timezone": "Asia/Shanghai"
  },
  "privacy": {},
  "notification": {}
}

---

user_agents

用户专属 Agent 配置。

字段	类型	说明
id	UUID	PK
user_id	UUID	用户 ID
llm_id	UUID	关联的 LLM 模型
agent_type	VARCHAR(20)	枚举：INTENT_RECOGNITION, TASK_EXECUTION, RESULT_REPORTING
config	JSONB	Agent 配置参数
status	VARCHAR(20)	状态：active, paused, migrating
created_by	UUID	创建者
updated_by	UUID	更新者
created_at	TIMESTAMPTZ	创建时间
updated_at	TIMESTAMPTZ	更新时间
deleted_at	TIMESTAMPTZ	软删时间

约束： (user_id, agent_type) 唯一

---

memories

用户与工作记忆。

字段	类型	说明
id	UUID	PK
owner_id	UUID	用户 ID
agent_id	UUID	Agent ID（work 类型必填）
memory_type	VARCHAR(20)	枚举：user, work
title	VARCHAR(255)	标题
content	JSONB	记忆内容
source	VARCHAR(20)	来源：manual, agent, imported
status	VARCHAR(20)	状态：active, disabled
created_at	TIMESTAMPTZ	创建时间
updated_at	TIMESTAMPTZ	更新时间

约束： work 类型必须有 agent_id，user 类型必须无 agent_id

content JSONB 示例：

// 用户记忆
{"type": "preference", "data": {"style": "concise", "language": "zh-CN"}}

// 工作记忆
{"type": "workflow_summary", "data": {"task": "代码审查", "learnings": ["优先检查安全漏洞"], "improvements": []}}

---

friendships

好友关系（双向规范化）。

字段	类型	说明
id	UUID	PK
user_low_id	UUID	较小 UUID
user_high_id	UUID	较大 UUID
initiator_id	UUID	发起方用户 ID
status	VARCHAR(20)	状态：pending, accepted, blocked, declined, canceled
requested_at	TIMESTAMPTZ	请求时间
accepted_at	TIMESTAMPTZ	接受时间
blocked_by	UUID	阻止者用户 ID
created_by	UUID	创建者
updated_by	UUID	更新者
created_at	TIMESTAMPTZ	创建时间
updated_at	TIMESTAMPTZ	更新时间
deleted_at	TIMESTAMPTZ	软删时间

约束： user_low_id < user_high_id，(user_low_id, user_high_id) 唯一

---

groups

群组。

字段	类型	说明
id	UUID	PK
name	VARCHAR(100)	群组名称
description	TEXT	群组描述
owner_id	UUID	创建者 ID
status	VARCHAR(20)	状态：active, archived
created_by	UUID	创建者
updated_by	UUID	更新者
created_at	TIMESTAMPTZ	创建时间
updated_at	TIMESTAMPTZ	更新时间
deleted_at	TIMESTAMPTZ	软删时间

---

group_members

群组成员。

字段	类型	说明
id	UUID	PK
group_id	UUID	群组 ID
user_id	UUID	用户 ID
role	VARCHAR(20)	角色：owner, admin, member
join_source	VARCHAR(20)	加入方式：invited, joined
invited_by	UUID	邀请人 ID
joined_at	TIMESTAMPTZ	加入时间
removed_at	TIMESTAMPTZ	移除时间
status	VARCHAR(20)	状态：active, muted, removed
created_by	UUID	创建者
updated_by	UUID	更新者
created_at	TIMESTAMPTZ	创建时间
updated_at	TIMESTAMPTZ	更新时间
deleted_at	TIMESTAMPTZ	软删时间

约束： (group_id, user_id) 唯一

---

schedule_items

日程事项。

字段	类型	说明
id	UUID	PK
owner_id	UUID	所有者 ID
title	VARCHAR(255)	标题
description	TEXT	描述
start_at	TIMESTAMPTZ	开始时间
end_at	TIMESTAMPTZ	结束时间
timezone	VARCHAR(50)	时区
metadata	JSONB	扩展字段
recurrence_rule	VARCHAR(255)	循环规则
source_type	VARCHAR(20)	来源：manual, imported, agent_generated
status	VARCHAR(20)	状态：active, completed, canceled, archived
created_by	UUID	创建者
created_at	TIMESTAMPTZ	创建时间
updated_at	TIMESTAMPTZ	更新时间
deleted_at	TIMESTAMPTZ	软删时间

metadata JSONB 默认结构：

{
  "color": "#FF6B6B",
  "location": "会议室A",
  "notes": "记得提前准备投影仪",
  "attachments": [
    {
      "name": "会议纪要.pdf",
      "url": "https://...",
      "visible_to": [],
      "type": "document"
    },
    {
      "name": "投影仪提醒",
      "visible_to": ["uuid1"],
      "type": "reminder",
      "content": "记得带投影仪"
    }
  ],
  "version": 1
}

---

schedule_subscriptions

日程订阅与权限。

字段	类型	说明
id	UUID	PK
item_id	UUID	日程事项 ID
subscriber_id	UUID	订阅者 ID
permission	INTEGER	权限位图（view=1, invite=2, edit=4），默认 1
notify_level	VARCHAR(20)	通知级别：all, mentions, none，默认 all
status	VARCHAR(20)	状态：active, paused, unsubscribed，默认 active
created_by	UUID	创建者
created_at	TIMESTAMPTZ	创建时间
updated_at	TIMESTAMPTZ	更新时间

约束： (item_id, subscriber_id) 唯一，permission BETWEEN 0 AND 7

---

inbox_messages

待处理消息（接收者视角）。

字段	类型	说明
id	UUID	PK
recipient_id	UUID	接收者 ID
sender_id	UUID	发送者 ID（系统消息可为 NULL）
message_type	VARCHAR(20)	类型：friend_request, calendar, system, group
friendship_id	UUID	好友请求关联（friend_request 时必填）
schedule_item_id	UUID	日程关联（calendar 时必填）
group_id	UUID	群组关联（group 时必填）
content	TEXT	消息内容（system 用）
is_read	BOOLEAN	是否已读，默认 false
status	VARCHAR(20)	状态：pending, accepted, rejected, dismissed
created_by	UUID	创建者
created_at	TIMESTAMPTZ	创建时间
updated_at	TIMESTAMPTZ	更新时间

message_type 与业务字段对应：

message_type	必填字段
friend_request	friendship_id
calendar	schedule_item_id
system	全部可空
group	group_id

sender 约束： system 类型 sender_id 为空，其他类型 sender_id 必填

---

todos

待办事项。

字段	类型	说明
id	UUID	PK
owner_id	UUID	所有者 ID
title	VARCHAR(255)	标题
description	VARCHAR(1000)	描述
due_at	TIMESTAMPTZ	截止时间
priority	INTEGER	优先级（1-4，1=重要且紧急）
status	VARCHAR(20)	状态：pending, done, canceled
completed_at	TIMESTAMPTZ	完成时间
created_by	UUID	创建者
created_at	TIMESTAMPTZ	创建时间
updated_at	TIMESTAMPTZ	更新时间
deleted_at	TIMESTAMPTZ	软删时间

约束： priority BETWEEN 1 AND 4

---

todo_sources

待办与日程来源关联。

字段	类型	说明
id	UUID	PK
todo_id	UUID	待办 ID
schedule_item_id	UUID	日程事项 ID
created_at	TIMESTAMPTZ	创建时间
updated_at	TIMESTAMPTZ	更新时间

约束： (todo_id, schedule_item_id) 唯一

---

automation_jobs

自动化定时任务。

字段	类型	说明
id	UUID	PK
owner_id	UUID	所有者 ID
title	VARCHAR(255)	任务标题
prompt	TEXT	AI 执行 prompt
schedule_type	VARCHAR(20)	调度类型：daily, weekly
run_at	TIMESTAMPTZ	首次运行时间
next_run_at	TIMESTAMPTZ	下次运行时间
timezone	VARCHAR(50)	时区
last_run_at	TIMESTAMPTZ	最近运行时间
status	VARCHAR(20)	状态：active, disabled
created_by	UUID	创建者
created_at	TIMESTAMPTZ	创建时间
updated_at	TIMESTAMPTZ	更新时间
deleted_at	TIMESTAMPTZ	软删时间

约束： (id, owner_id) 唯一

---

sessions

Agent 对话会话。

字段	类型	说明
id	UUID	PK
user_id	UUID	用户 ID
session_type	VARCHAR(20)	会话类型：chat, automation
job_id	UUID	自动化任务 ID（automation 时必填）
title	VARCHAR(255)	会话标题
status	VARCHAR(20)	状态：pending, running, completed, failed
last_activity_at	TIMESTAMPTZ	最后活跃时间
message_count	INTEGER	消息计数，默认 0
total_tokens	INTEGER	总 token 数，默认 0
total_cost	NUMERIC(12,6)	总费用，默认 0
created_at	TIMESTAMPTZ	创建时间
updated_at	TIMESTAMPTZ	更新时间
deleted_at	TIMESTAMPTZ	软删时间

约束： session_type='chat' → job_id IS NULL, session_type='automation' → job_id IS NOT NULL

---

messages

会话消息记录。

字段	类型	说明
id	UUID	PK
session_id	UUID	会话 ID
seq	INTEGER	消息序号
role	VARCHAR(20)	角色：user, assistant, system, tool
content	TEXT	消息内容
model_code	VARCHAR(50)	模型标识
tool_name	VARCHAR(100)	工具名称
input_tokens	INTEGER	输入 token 数，默认 0
output_tokens	INTEGER	输出 token 数，默认 0
cost	NUMERIC(12,6)	费用，默认 0
currency	VARCHAR(3)	货币，默认 USD
latency_ms	INTEGER	延迟（毫秒）
metadata	JSONB	扩展字段
created_at	TIMESTAMPTZ	创建时间
updated_at	TIMESTAMPTZ	更新时间
deleted_at	TIMESTAMPTZ	软删时间

约束： (session_id, seq) 唯一

---

llm_factory

LLM 工厂配置。

字段	类型	说明
id	UUID	PK
name	VARCHAR(50)	工厂名称
request_url	VARCHAR(255)	API 请求 URL
avatar	TEXT	头像 URL
created_at	TIMESTAMPTZ	创建时间
updated_at	TIMESTAMPTZ	更新时间
deleted_at	TIMESTAMPTZ	软删时间

约束： name 唯一

---

llms

LLM 模型实例。

字段	类型	说明
id	UUID	PK
factory_id	UUID	工厂 ID
model_code	VARCHAR(50)	模型标识
created_at	TIMESTAMPTZ	创建时间
updated_at	TIMESTAMPTZ	更新时间
deleted_at	TIMESTAMPTZ	软删时间

约束： model_code 唯一

---

user_agent_catalog

Agent 类型目录。

字段	类型	说明
agent_type	VARCHAR(20)	PK，Agent 类型
llm_id	UUID	关联的 LLM 模型
status	VARCHAR(20)	状态：active, paused, migrating
config	JSONB	Agent 配置参数
created_at	TIMESTAMPTZ	创建时间
updated_at	TIMESTAMPTZ	更新时间

---

invite_codes

邀请码。

字段	类型	说明
id	UUID	PK
code	VARCHAR(8)	邀请码（8 位大写字母数字）
owner_id	UUID	拥有者 ID
status	VARCHAR(20)	状态：active, disabled, expired
used_count	INTEGER	已使用次数，默认 0
max_uses	INTEGER	最大使用次数
expires_at	TIMESTAMPTZ	过期时间
reward_config	JSONB	奖励配置
created_at	TIMESTAMPTZ	创建时间
updated_at	TIMESTAMPTZ	更新时间

约束： code 唯一，code 符合 [ABCDEFGHJKMNPQRSTUVWXYZ23456789]{8}，used_count >= 0

---

外键删除策略

外键	删除策略
sessions.job_id	RESTRICT
todo_sources.todo_id	CASCADE
todo_sources.schedule_item_id	CASCADE
inbox_messages.friendship_id	CASCADE
inbox_messages.schedule_item_id	CASCADE
inbox_messages.group_id	CASCADE

---

RLS 策略

所有 public 业务表默认启用 RLS：

• anon: 全部 DENY
• authenticated: 全部 DENY
• service_role: 由后端服务连接，不依赖 RLS