makelore/.project-docs/20-architecture/system-overview.md

System Overview

Current Architecture

Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展示；Electron Main 持有认证、文件系统、安全打包、Works Square 网络访问和预览 URL 校验。

Main Components

Component	Responsibility	Notes
Renderer	项目配置、一键提交状态、真机二维码	不接触账号 Token、ZIP、幂等键或本地绝对路径
Host API	校验本地项目请求并投影安全响应	发布 mutation 还必须通过 Renderer capability；Host token/base 不能单独触发发布
Project Configuration & Template	保存不可变 ProjectType，原子生成新项目骨架	小游戏/小程序生成受控 Vite 模板；自定义保持最小项目空间
Project Packager	确定性扫描、敏感文件排除与 ZIP 生成	限制文件数、包体和目录替换
Works Session	七天真实活动滑动续期	刷新凭据由 Main 安全持有
Submission Binding	保存云端已接受的精确 app/version/review/hash 绑定	schema v2 只记录成功提交；旧中间态迁移为 legacy_retired，不恢复后台任务
Play URL Projection	校验服务端公共播放地址	只接受同源 HTTPS 和精确 /apps/{app_id}/；优先 play_url，runtime_url 仅一版本回退
Device Preview	核对本地绑定、远端版本和 Release	待审使用短时 Owner preview；已发布使用安全投影后的 play_url
AI Design Workspace	保存项目身份、Conversation 列表、生成任务和资产	任务和资产在切换 Conversation 后继续可见
AI Design Conversation	保存消息、Brief、Quote、turnRevision 与服务端 Agent Session 绑定	同一 Workspace 内互相隔离；Session 由服务端持久化
AI Design Event Routing	Main 云端适配器 → Host API/SSE → Renderer store	Conversation 更新按 Workspace + Conversation 路由；任务更新按 Workspace 归并

Important Boundaries

• 发布只有现有项目配置底部的一个入口，不新增发布工作台、侧栏或资源卡。
• 创建者发布唯一调用链是 ProjectPublishAction → publishWorksProjectSource → createStaticProjectPackage → 版本上传 → 状态轮询；客户端不再提供 Compose runner、deploy-check、watcher/arm/upload 协调或手工 ZIP 上传入口。
• ProjectType 由创建请求写入项目配置，UI 与 Host API 不提供类型变更；缺少类型的旧配置归一为 custom。
• 本地 projectType 只选择产品路径和内部构建 preset，不是可信授权声明；Main 仍需安全打包，服务端仍需独立校验清单和包体。
• 云端确认上传成功后，本机 submission binding 失败只能产生固定、无路径的 binding_warning，不能把请求改判为失败；Renderer 仍继续轮询云构建。
• 公共播放投影只有在上游 playable === true、版本名非空且 URL 通过同源 HTTPS、无 userinfo/loopback、长度、精确路径和无 query/fragment 校验时才可播放；不可信数据 fail closed。
• Renderer 只能获得安全状态字段和可展示的播放/短时预览 URL，不得持有发布凭据、归档路径或自动部署状态。
• 落盘文件名 works-cloud-deploy.json 仅为已安装客户端的数据兼容；领域模型和代码接口是 submission binding，不表示仍存在 cloud deployment coordinator。
• AI 绘画中，一个 Workspace 可包含多条 Conversation；消息、Brief、Quote 和 turnRevision 属于 Conversation，生成任务和资产属于 Workspace。新建 Conversation 不得隐式创建新 Workspace。
• 每条 Conversation 复用服务端持久 Agent Gateway Session。客户端不得在注销或退出时 DELETE 该 Session；只关闭本地事件流并清除本机 Session-id 缓存，重新访问时从 Conversation API 刷新。
• Renderer 的异步与流式状态必须同时校验 Workspace + Conversation 身份；项目任务事件只按 Workspace 归并，避免切换会话时丢失任务或接收迟到消息。

Related Decisions

• 当前长期边界记录于 README、ADR-001、集成任务 20260807-integrate-login-client-a4f8、源任务 20260810-static-release-only-a91c 及本次 Integration Gate；后续如改变唯一入口、凭据所有权、Conversation 状态归属或重新引入客户端部署协调器，应新增 ADR。

Last Updated

2026-08-11