docs: describe workspace signing boundaries

docs/frontend.md

@@ -4,6 +4,14 @@
 
 ## 1. 技术栈
 
+### 数据来源与契约
+
+HTTP 请求和响应类型由后端 DTO 生成到 `core-bridge/generated/api.ts`，不手写第二份接口模型。
+运行 `dotnet run --project tools/ContractGenerator -- <仓库目录>` 更新；`scripts/check-api-contract.mjs` 检查生成物是否与后端来源一致。
+`/info` 下发创建默认值、可选设置和部署限制，创建与设置页面通过 store 读取，不在组件里定义业务默认值。
+在线空间与分享列表从服务端刷新元数据；IndexedDB 作为离线缓存、凭据与发送队列。网络故障可显示缓存，认证或契约错误不能当作离线成功。
+账户资料、频道、分组、目录和资源归属通过后端接口加载及修改。加密资源元数据使用独立协议模型，不序列化 UI 的进度、预览、选中或历史版本状态。Worker 解密资源，store 保存服务端结构和资源投影，组件渲染。
+
 | 项 | 选择 | 说明 |
 |---|---|---|
 | 构建 | Vite | 纯客户端 SPA,不做 SSR |
@@ -93,8 +101,8 @@ type ItemState =
 | 降级防御 | 链接含 `k` 就只接受 enc 且认证通过的帧 |
 | 不把密钥、令牌、明文写入 `console`、错误上报、URL、`localStorage` | 「我的频道」只存 IndexedDB |
 | 便捷分享草稿预览 | 原始文件只缓存在创建者本机 IndexedDB,不会随文件帧上传;移除条目或封存时清理,用于刷新后继续预览草稿 |
-| 账号资源保险库 | Worker 派生登录凭据与 AES-GCM 密钥；仅同步 link/ownerLink、草稿清单、邀请私钥和移除墓碑；不含终端 S、设备名、缓存或文件 Blob。按账号/访客分库，会话在 Worker 中使用，通过本机 IndexedDB 恢复 |
-| thread 与虚拟文件夹 | `@webdrop/core` 用共享结构编码 `thread_id`/`folder_id` 和 CONTROL；mode 只切换是否加密；worker 解析控制正文，store 保留最新位置以防旧条目更新回退 |
+| 账号资源保险库 | Worker 派生登录凭据与 AES-GCM 密钥；同步资源访问凭据、邀请私钥和移除墓碑；不含个人资料、草稿内容、终端 S、设备名或 Blob。按账号/访客分库，会话通过本机 IndexedDB 恢复 |
+| 频道与文件夹 | 后端持久化结构和资源归属，Worker 读取结构快照；加密文件元数据中的原始位置用于内容校验，UI 使用后端当前归属 |
 | 条目预览在沙箱 iframe 渲染;raw 内容只当纯文本显示或下载 | 无内联渲染,不使用 `dangerouslySetInnerHTML` |
 | 严格 CSP,所有脚本样式带 SRI,不使用内联脚本 | 与 architecture §5 一致 |
 | 不引入任何第三方脚本、统计、字体 CDN | 字体自托管 |
@@ -159,15 +167,15 @@ type ItemState =
 | 4 | 文件:流式上传下载、GATED 拉取、下载计数、预览、粘贴与拖放 |
 | 6 | PWA、Web Share Target、二维码与短配对码 |
 
-在 `@webdrop/core` 未就绪前,`core-bridge/` 按 protocol.md 定义的接口先放适配层和假实现,真实实现就绪后替换,组件与 store 不改。
+`@webdrop/core` 与真实 Worker 已接入，原型假数据与模拟连接实现已移除。接口测试使用测试替身，不保留第二套业务实现。
 
 ## 12. 实际边界与会话
 
-core-bridge/instance.ts 使用真实 Worker 实现，mock 仅用于原型和测试。账号与设备由 worker/account.ts 编排；账号密钥包通过 accountChannels.ts 与 channelGrant.ts 领取和核对；频道成员/设置/设备席位通过 channelResources.ts 调用 API；thread/folder/file.published 共用 channelThreads.ts 的加密 CONTROL 日志。
+core-bridge/instance.ts 使用真实 Worker 实现。账号、设备和个人资料由 worker/account.ts 与 accountProfile.ts 编排；账号密钥包通过 accountChannels.ts 与 channelGrant.ts 领取和核对；空间成员/设置/设备席位通过 channelResources.ts 调用 API；频道、分组和目录由 channelThreads.ts 调用后端。workspaceRecords.ts 只读取加密文件元数据，不处理账户或结构操作。
 
 @webdrop/core 仅实现纯密码学与帧协议，不访问数据库或网络。sessions.ts 管本机已解锁会话。transfer.ts 管持久化密文发送队列，队列按资源/创建顺序索引，确保文件密文帧先于目录记录上传。downloadStorage.ts 优先使用 OPFS 逐块写入临时文件，认证结束后交付；不支持时最多 64 MiB 的 Blob 回退。
 
-频道和 Share 各有独立领域 API 与生命周期；Share 封存由服务端事务清除 owner_hash，不能再写。账号保险库同步个人资料、邀请私钥、资源凭据和移除墓碑；设备 S、文件缓存与 outbox 保留本机。
+空间和 Share 各有独立领域 API 与生命周期；Share 封存由服务端事务清除 owner_hash，不能再写。账号保险库同步邀请私钥、资源凭据和移除墓碑；个人资料从后端读取，设备 S、文件缓存与 outbox 保留本机。
 
 ## 13. 账号会话恢复与频道密钥领取
 
@@ -177,7 +185,7 @@ core-bridge/instance.ts 使用真实 Worker 实现，mock 仅用于原型和测
 
 ## 14. 用户概念映射与分组
 
-界面 Space 对应既有顶层 ChannelInfo 与 /c/:id；界面频道对应 ThreadInfo 和 thread_id。ChannelGroupInfo 属于当前空间，ThreadInfo.groupId 可选。store 从 group-created/group-renamed/thread-grouped 事件重建分组；threadGroups 保留最新归属，避免延迟的创建事件将频道移回旧分组。分组不是文件夹，也不是成员/密钥边界。
+界面 Space 对应既有顶层 ChannelInfo 与 /c/:id；界面频道对应后端 WorkspaceChannel 和帧协议 threadId。store 直接渲染服务端结构快照，不重放创建/重命名/分组事件。ThreadInfo 与 FolderInfo 只将后端可空字段转成 UI 的可选字段。分组不是成员或密钥边界。
 
 ## 15. 文件交互边界
 
@@ -187,7 +195,7 @@ ContextMenu 是无业务 UI，负责 portal、视口限制、键盘焦点和关
 
 ## 16. 文件聊天消息与身份快照
 
-ItemBase.author 为可选发送者快照 {username,displayName,avatar?}。文件的快照放入已有 file.published 加密目录记录，文本通过 item.author CONTROL 记录关联。store 的 authors 索引支持身份记录先于条目到达，并在晚到的下载/进度更新中保留身份，避免取文件内容后丢失头像。该快照用于展示，不代表逐账号数字签名。
+ItemBase.author 由服务端资源作者和账号资料投影得到，晚到的解密内容不能覆盖服务器提供的作者与位置。客户端提供的作者声明不能覆盖服务端资料。这是服务端身份归属，不是端对端逐账号签名。
 
 ChatPane 订阅当前频道的条目 ID，ChatMessage 单独订阅条目状态和上传进度；文件目录变成文件消息，不重复创建独立文本通知。预览/下载继续经已有 store action，移动文件不会重新上传。GATED 内容只有明确操作后才读取。