makelore/.project-docs/20-architecture/data-flow.md

Data Flow

Primary Flows

Flow	Source	Destination	Notes
登录续期	Renderer 活动信号	Main Works Session	连续 7 天未使用才清除会话
项目创建	新建项目对话框	Host API → Main 项目初始化	创建时固定 ProjectType；小游戏/小程序原子生成受控模板，自定义只生成项目空间
一键提交	ProjectPublishAction	Renderer capability → Host API → loopback preview preflight → Main packager → Works Square 版本上传	只对小游戏/小程序开放；本地预检只做 UX fail-fast，Main 随后打包、自动版本、幂等重试和脱敏，Renderer 轮询云构建
本地预览检查	当前项目内置浏览器 loopback URL	fresh Electron WebContents/CDP（桌面、移动）	检查错误、白屏和外域；不调用 Playwright/Vite，不产生 receipt/provenance，不替代服务端门禁
提交绑定	云端成功上传响应	Main → submission binding v2	只持久化成功的 app/version/review/hash；落盘失败返回固定告警但不反转提交
运营发布	Works Square 审核与交付	公共 play_url	客户端只消费服务端发布结果；真实 Builder → OSS/CDN 生产链仍待整链验收
可信发布门禁	上传源码	服务端受控构建 → 包体/不可变 Release 校验 → 人工审核	唯一不可绕过权威；若未来增加 runtime 强门禁，需可信 verifier 绑定精确构建产物
真机预览	项目空间	Main → Owner preview / play_url	核对 app、version、release 和同源 HTTPS；runtime_url 仅一版本兼容回退
设计会话创建/切换	AI 绘画页面或侧栏	Renderer API → Main → Workspace Conversation API	新会话属于现有 Workspace；读取独立消息、Brief、Quote 和 turnRevision
设计消息与确认	当前 Conversation	Main → 持久 Agent Gateway Session → Conversation 快照	请求和流式结果同时绑定 Workspace + Conversation
设计任务同步	任一 Conversation 的事件流 / REST	Renderer Workspace 任务列表	Task 和 Asset 按 Workspace 归并，切换 Conversation 后仍可见

State Ownership

• Main 持有刷新凭据、发布 Token、临时 ZIP、幂等键和 submission binding v2；Renderer 不持有归档路径或自动部署状态。
• 项目内 .niancode/project.json 保存 ProjectType；Main 在配置写入和目录复用时保持其不可变，并在打包时重新读取校验。
• Renderer 仅持有短效公开会话状态、提交展示状态和安全投影后的公共播放/短时预览 URL。
• 本地预检临时 WebContents/partition 只属于一次调用，不写 submission binding 或上传字段；其结果不具备 project/digest provenance，也不覆盖生产 opaque-origin。
• 旧 schema v1 submitted 记录迁移并保留；旧 armed、waiting_for_package、waiting_for_login、uploading、failed 归一为 legacy_retired，不再启动 watcher 或上传任务。
• AI 绘画 Conversation 持有消息、Brief、Quote、turnRevision 和服务端 Session 绑定；Workspace 持有 Conversation 列表、生成任务和资产。
• 本地开发适配器将旧单会话 schema v2 原子迁移为带默认 Conversation 的 schema v3；打包应用不使用该本地适配器作为云端失败回退。
• 注销和退出会关闭本地事件流并清除本机 Conversation Session-id 缓存；服务端持久 Session 保留，下一次访问从 Conversation API 重新读取。

External Interfaces

• Works Square 项目创建、版本上传、构建状态、Owner 状态与 Release preview API。
• 本机 Host API 的发布与真机预览路由；发布路由要求 Renderer capability。
• 服务端安全投影后的公共 play_url；只接受同源 HTTPS、精确 App 路径和可信版本状态。
• Works Square Workspace/Conversation API、每个 Conversation 的 Agent Gateway Session 与单次 WebSocket ticket。

Last Updated

2026-08-12