工作区数据驻留
产品能力与界面说明以用户表达为准。本文描述数据落在哪一层库，供实现与对接对照。
来源 docs/core-mechanisms/工作区数据驻留.md
表述：产品能力与界面说明以用户表达为准。本文描述数据落在哪一层库，供实现与对接对照。
1. 原则
| 落点 | 判定 |
|---|---|
主 schema（public / 主库） | 账号身份、登录、管理端、跨工作区目录与成员纽带、全局产品模板；删掉某个工作区后仍必须存在的数据 |
工作区 schema（workspacens：Postgres ws_* 或 SQLite workspaces/{id}/plugin_ns.db） | 只在该工作区有意义的业务内容；工作区删除即可一并销毁 |
用户账号不进工作区 schema（一人可属多区）。区内「成员 / 办理人」只存用户 ID 软引用。
2. 主 schema 保留
- 用户与认证：
users、refresh_tokens；管理端admin_* - 工作区目录与成员：
workspaces、workspace_members、邀请/加入申请等（登录后列出「我的工作区」不扇出全部分片） - 命名空间登记：
workspace_data_namespaces - 全局模板目录：如
agent_templates - 平台插件注册（多为配置，非租户业务表）
3. 迁入工作区 schema（分域）
| 域 | 内容 | 状态 |
|---|---|---|
| 插件业务 | HR 的 hr_* 等 | 已落地 |
| 工作流 | workflow_*（含工作票） | 已落地 |
| 应用桌面 | workspace_apps / suites / templates | 已落地 |
| 规范 / 资产 / 分类 | workspace_standards / assets / taxonomy* | 已落地 |
| 数据源 | sources / datasets / grants / mutations | 已落地 |
| 智能体 | user_agents、训练任务、embed token（区属） | 已落地（管理端扇出分片） |
| 区属技能 | user_conversation_skills 及版本/文件 | 已落地 |
| 会话 / 消息 | chat_sessions / chat_messages | 已落地（区属 agent/scheduled）；帮助 / 未选区仍主库 |
同区与 HR 共用同一 ws_* / plugin_ns.db；Go 侧由 wsdb.With 统一 migrate + 按域空库拷贝（ws_residency_meta）。
4. 灰区
- 上传文件：现按用户；多区引用需对象索引 + 区侧引用或按区桶，专项设计。
- 未选工作区 / 帮助智能体会话：留在主 schema（不进区分片）。
- 跨区待办 / 管理端总览：扇出分片；会话明细仍以主库帮助行为主，区属会话需扇出补齐。
- 定时任务表
agent_scheduled_tasks：仍在主库；智能体名称从分片解析。
4.1 会话双路径
- 新建：
session_kind=help或未带工作区 → 主库；区属agent/scheduled→ 区分片（依赖WorkspaceDataNS注入）。 - 按会话读写：先查注入分片，再回退主库（
resolveChatDB）。 - 空库拷贝：域
chat，仅workspace_id=? AND session_kind IN ('agent','scheduled','workflow')及其消息；help 不拷。 - 侧栏最近活动：有工作区时分片查区属会话 + 主库查帮助会话后合并。
5. 访问约定
Ensure(workspace) → 打开区分片 → wsdb migrate → 按域 copyIfNeeded → 主库按区 DELETE → 业务读写
启动时 FinalizeMainResidency：全工作区驻留后 DROP 已迁表（保留 chat_*）HTTP：WorkspaceDataNS 中间件对带工作区的请求注入分片（URL {id} 或登录态当前工作区）。Store 经 DBTXFromContext / BeginTx 优先写分片。跨区只读（管理端智能体列表等）经 WithWorkspaceShard 扇出。
后台任务（定时执行、记忆采纳等）无 HTTP 中间件时，须用 store.WithWorkspaceDBTX 打开目标工作区分片。流式/长任务脱离请求取消时，用 store.DetachContextKeepingDBTX 保留注入连接，勿用裸 context.Background()。
workspaces 等主库目录表始终查主库 *sql.DB，不要经分片 DBTX（SQLite 分片无该表）。
5.1 主库清理
- 按区清行：每域拷贝成功（或已标记拷贝）后
purgeMainDomain，从主库删除该工作区对应行。 - 会话例外：仅删除
session_kind IN ('agent','scheduled','workflow')；帮助会话行留在主库chat_*。 - DROP 表：
FinalizeMainResidency在全部工作区完成驻留后，从主 schemaDROP已迁业务表（user_agents、工作流、应用、规范、数据源、技能、embed/train 等）；不 DROPchat_sessions/chat_messages。 - Postgres 对 DROP 使用
CASCADE：卸掉主库留存表（如agent_scheduled_tasks、im_*）指向user_agents的外键，列保留为软引用；不会删除这些依赖表。 - Finalize 成功后写入
mindlink_schema_meta.main_resided_tables_dropped；之后主库Open跳过已迁表的 CREATE/ALTER，不再「建空壳再 DROP」。
6. 相关实现
backend/internal/workspacens/backend/internal/wsdb/backend/internal/middleware/workspace_ns.go- HR 样板：
plugins/hr/lib/db.ts、migrate.ts