Files
foundry-core/docs/database-comments.sql
T

116 lines
10 KiB
SQL
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
-- Foundry 数据库源码阅读注释索引(仅注释,不执行迁移)。
-- 历史 db/*.sql 的 SHA-256 由 deploy/migrate.py 原文计算并记录;即使只改注释,
-- 已部署库也会拒绝同名文件的新校验和。因此按迁移文件与对象名在此维护中文说明。
-- 顺序:001 认证 → 002 平台 → 003 快照 → 004 会话期限 → 005 子图事务 →
-- 006 资产 → 007 AI 队列 → 008 canonical 模型 → 009–011 AI 身份/回执/位置。
-- db/001-auth.sql:四张基础认证表在一个事务中安装。
-- project_accounts:账户身份以 (project,id) 为主键,Google subject 在项目内唯一。
-- 同一 Google 用户可在不同项目有不同账户,邮箱是可空资料,不作为跨提供方自动合并依据。
-- oauth_attempts:十分钟 OAuth 尝试;state/browser 保存摘要,frontend_challenge 绑定
-- 前端兑换证明,google_verifier 原文用于服务器向 Google 兑换 PKCE 授权码。
-- 回调通过 DELETE ... RETURNING 原子消费,外部兑换失败也不会恢复已消费尝试。
-- login_grants:一分钟一次性交换码只存 token_hash,复合外键保证账户属于同一项目。
-- project_sessions:bearer 明文只交客户端,数据库仅存摘要和期限;删除账户级联清会话。
-- 三个 expires_at 索引提供过期定位能力,本文件本身不创建定时清理任务。
-- db/002-platform.sql:扩展身份提供方与协作资源,保留旧 Google 账户/会话。
-- project_accounts:google_subject 放宽可空;username 在项目内按 lower 唯一,
-- display_name/avatar_url 是可由用户维护的资料,updated_at 由应用更新。
-- oauth_attempts.provider 默认 google 兼容已有行;Slack 增加 oidc_nonce 防止 ID token 重放。
-- account_identities:以项目/提供方/subject 唯一定位账户,迁入既有 Google subject;
-- 项目/提供方/account 唯一约束限定同一账户每提供方只有一个绑定。
-- email_credentials:已验证邮箱凭据,邮箱须小写,password_hash 是 bcrypt;
-- 项目/email 主键及项目/account 唯一性不允许多个凭据冒用同一邮箱或账户。
-- email_registrations:未验证注册单独保存密码摘要和验证码摘要,未确认前不建立账户;
-- 重发注册由应用在邮箱级事务锁下替换待验证记录及过期时间。
-- email_outbox:邮件与注册同事务写入,available_at/attempts 控制重试;lease_id/
-- lease_until 使后台 worker 可认领并在租约失效后恢复,sent_at 标成功。
-- 发送成功后应用清空 body;SMTP 成功与数据库标记不原子,不能宣称严格只投递一次。
-- auth_rate_limits:仅保存限频键摘要,固定窗口过期后由应用 upsert 重置次数。
-- onboarding_responses:项目/账户唯一完成记录,answers/result 必须 JSON 对象;
-- 配合账户行锁,使并发首次引导只能创建一次工作区并重放已存结果。
-- workspaces:所有者外键指向同项目账户;工作区行锁是角色/所有权变更共享的串行点。
-- workspace_members:每人每工作区一个角色,admin/editor/viewer 的写权限由应用解释;
-- owner 必须保留 admin 成员的规则由服务控制,表约束没有单独自动生成该成员。
-- materials:按项目/工作区隔离的可复用内容对象,kind 为受限类型;version 是素材
-- 内容/元数据的乐观版本,后续新增 canvas_version 与它分离。
-- material_modified/material_created/material_alphabetical:对应列表排序的复合索引。
-- material_opens:账户级最近打开时间,可反复 upsert,不修改素材正文;专用索引支持最近打开。
-- tags/material_tags:标签名在工作区内忽略大小写唯一;双复合外键阻止跨工作区关联,
-- 标签/素材删除级联清关联,应用负责让受影响素材版本递增。
-- board_layouts:旧布局引用可复用素材,位置/尺寸与内容独立;禁止引用自身,
-- “必须 board 且不可嵌套 board”及每板最多 2000 条由服务检查。
-- material_grants:显式 editor/viewer 素材权限,不存在素材级 admin 授予;
-- 根画布继承和归档祖先检查由 lockMaterial 的递归查询决定。
-- share_links:仅保存邀请摘要;可指工作区或单素材,单素材不允许 admin;
-- max_uses/use_count 是额度,expires_at/revoked_at 控制之后的兑换资格。
-- share_redemptions:同账户同链接只兑换一次;应用在持锁事务内插入成功后才加额度并提升角色。
-- link_clicks:公开点击独立于兑换计数,仅存 Referer origin,避免收集路径、查询和令牌。
-- bigint identity 支持递减 ID 分页;应用角色需单独授予序列 USAGE/SELECT。
-- db/003-canvas.sql:为 board 增加独立 canvas_version 和可空 canvas_document。
-- canvas_board_only 禁止非 board 保存快照;旧空文档在读取时投影为初始空 v1 图。
-- workspaces/materials 的 slug 先按名称/标题加 UUID 回填,再设 NOT NULL 和作用域唯一。
-- foundry_default_slug:仅 INSERT 且未给 slug 才派生值,名字更改不会隐式改 URL。
-- label 规范化并限长,空结果回退 canvas;触发器在两个表共享,因此区分 name/title。
-- db/004-session-lifetime.sql:加入 created_at 和九十天 absolute_expires_at 缺省。
-- 旧会话原始发行时间未知,绝对上限从迁移时开始,但原 expires_at 完全不变,
-- 已闲置过期的旧会话不会被此迁移复活。应用续期取 min(三十天后,绝对期限)。
-- db/005-canvas-subgraphs.sql:持久唯一所有权与多画布事务恢复信息。
-- canvas_subgraphs:Child 是主键中的唯一所有者身份,活跃 Parent/Frame 受部分唯一索引限制;
-- archived_at 保留恢复关系但从活跃树移除;migration_source 保存旧框迁移证据。
-- 父/子外键均 RESTRICT,不能删掉素材而留下无法解释的所有权记录。
-- foundry_check_subgraph:先锁工作区,确认两端是 board,再递归算祖先和后代,
-- 拒绝循环与深度超八;数据库触发器也保护绕过 HTTP 的维护写入。
-- canvas_transactions:账户/画布/动作/幂等键唯一,payload_hash 防止同键换体。
-- response_status/body 冻结重放结果;before_state、after_versions、relation_changes
-- 支持条件撤销;expires_at 七天及 undone_at 控制撤销有效性,不会自动倒退当前版本。
-- db/006-canvas-assets.sql:编码原图 bytea 与绑定同库事务提交,URL 与存储后端解耦。
-- canvas_assets:限制格式和二十 MiB 编码预算,上传者/工作区/幂等键唯一,digest 为原图摘要;
-- 完整像素预算与解码有效性由应用在写入前检查,不能只依赖 MIME 字符串。
-- canvas_asset_bindings:资产可被多个画布引用,主键去重;删除画布级联清绑定,
-- 有绑定资产不能直接删除。可读性按当前绑定画布授权判断,缓存字节不能作为权限证明。
-- db/007-canvas-ai.sql:run/step/event 与旧取消/显式应用回执。
-- canvas_ai_runs:冻结 plan/create_response,保存队列时间、取消位、租约与单调 last_seq;
-- pending 部分索引服务认领,active 索引服务活跃列表;expires_at 表示三十天保留期限。
-- canvas_ai_steps:每 run 的拓扑 ordinal、冻结输入、目标指纹、输出与应用版本;
-- 局部 board/node 活跃部分唯一索引防止同目标同时重复生成。
-- canvas_ai_events:以 run/seq 主键保证重放顺序;appendAIEvent 用同一 SQL 推进 last_seq。
-- canvas_ai_mutations:旧协议按 run/账户/动作/键冻结应用和取消结果;不同于 run 生成重试。
-- 租约过期不证明模型尚未执行,恢复把未知执行标为中断,只有明确 codex_busy 才允许回队。
-- db/008-canvas-model.sql:只安装 canonical schema,不自动迁移已有用户快照。
-- canvas_model_projects:每根显式迁移身份屏障,记录源版本表与 migration_id。
-- canvas_model_canvases:树关系、入口元素、独立版本及 archived;父/入口同时可空,
-- 无父只能是根;延迟外键允许入口元素与孩子关系在同批创建,提交时再验证。
-- canvas_model_active_entry 部分唯一索引防止一个活跃入口拥有多个子画布。
-- canvas_model_elements:主键 (project,element_id) 使身份跨工作区/树不可被抢占;
-- record 的 id/owner/incarnation 必须与索引列相符,删除记录保留 deleted_incarnation。
-- owner 外键延迟验证,支持同事务移动所有权;应用验证整个最终树和连接共同祖先。
-- canvas_model_identity_map:保留来源画布/结构/旧 ID 到稳定元素 ID 的完整一次性映射。
-- canvas_model_requests:账户作用域请求键、动作、摘要、状态与冻结回执,确定拒绝也可恢复。
-- canvas_model_operations:逻辑 ID 独立于传输 request_id 去重,外键延迟到同事务回执落库;
-- 只有应用成功才消费逻辑身份,拒绝前缀不能把其中操作标为已执行。
-- foundry_guard_canonical_canvas:已迁入树的 canvas_document/version 改写需事务内
-- foundry.canonical_writer=on,阻止旧写入路径覆盖权威身份。此标志是应用协作约定,不替代数据库角色权限。
-- db/009-canvas-ai-operations.sql:为 run 增加可空 logical_operation_id,旧行保持 NULL。
-- 部分唯一索引限定项目/工作区/账户下同逻辑操作只能准入一个 run,换传输键不能重复付费执行。
-- db/010-canvas-ai-receipts.sql:把传输回执从执行保留周期中分离。
-- canvas_ai_requests:允许 run.start/cancel/apply,保存 applied/not-applied 与原始请求身份;
-- 不以 run 外键级联删除,使 run 清理后仍可判定已知结果,工作区删除则整体清理。
-- applied 逻辑操作部分唯一:确定零效果拒绝可显式用新键重计划,已应用操作不能再次执行。
-- INSERT ... SELECT 从旧 canonical run 回填 accepted 回执,ON CONFLICT 保留已有记录。
-- 回执缺失只能回答 unknown,不能证明历史付费调用从未发生。
-- db/011-canvas-ai-target-location.sql:分离冻结来源与实际应用位置。
-- applied_board_id:结果写到 owner 移动后的目标画布,旧已应用行按原 board_id 回填。
-- canvas_ai_canonical_target_busy:按根/稳定节点/代数而非原 board 唯一限制活跃步骤,
-- owner-only 移动不能逃过 node_busy,再次删除/恢复的新代则由生命周期检查单独处理。