docs: annotate Foundry source and deployment lifecycle in Chinese [skip ci]
This commit is contained in:
@@ -0,0 +1,115 @@
|
||||
-- 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,再次删除/恢复的新代则由生命周期检查单独处理。
|
||||
Reference in New Issue
Block a user