晋升客户端静态发布边界
This commit is contained in:
@@ -6,21 +6,24 @@
|
||||
|---|---|---|---|
|
||||
| 登录续期 | Renderer 活动信号 | Main Works Session | 连续 7 天未使用才清除会话 |
|
||||
| 项目创建 | 新建项目对话框 | Host API → Main 项目初始化 | 创建时固定 `ProjectType`；小游戏/小程序原子生成受控模板，自定义只生成项目空间 |
|
||||
| 一键提交 | 可发布项目配置 | Main → Works Square | 只对小游戏/小程序开放；Main 打包、自动版本、幂等重试和脱敏 |
|
||||
| 运营发布 | Works Square 审核 | 公共 Runtime | 审核通过后服务端直接发布 |
|
||||
| 真机预览 | 项目空间 | Main → Owner preview / Runtime | 核对 app、version、release 和同源 HTTPS |
|
||||
| 一键提交 | `ProjectPublishAction` | Renderer capability → Host API → Main packager → Works Square 版本上传 | 只对小游戏/小程序开放；Main 打包、自动版本、幂等重试和脱敏，Renderer 随后轮询云构建 |
|
||||
| 提交绑定 | 云端成功上传响应 | Main → submission binding v2 | 只持久化成功的 app/version/review/hash；落盘失败返回固定告警但不反转提交 |
|
||||
| 运营发布 | Works Square 审核与交付 | 公共 `play_url` | 客户端只消费服务端发布结果；真实 Builder → OSS/CDN 生产链仍待整链验收 |
|
||||
| 真机预览 | 项目空间 | Main → Owner preview / `play_url` | 核对 app、version、release 和同源 HTTPS；`runtime_url` 仅一版本兼容回退 |
|
||||
|
||||
## State Ownership
|
||||
|
||||
- Main 持有刷新凭据、发布 Token、临时 ZIP、幂等键和本地 app/version/review 映射。
|
||||
- Main 持有刷新凭据、发布 Token、临时 ZIP、幂等键和 submission binding v2；Renderer 不持有归档路径或自动部署状态。
|
||||
- 项目内 `.niancode/project.json` 保存 `ProjectType`；Main 在配置写入和目录复用时保持其不可变，并在打包时重新读取校验。
|
||||
- Renderer 仅持有短效公开会话状态、提交展示状态和短时预览 URL。
|
||||
- Renderer 仅持有短效公开会话状态、提交展示状态和安全投影后的公共播放/短时预览 URL。
|
||||
- 旧 schema v1 `submitted` 记录迁移并保留；旧 `armed`、`waiting_for_package`、`waiting_for_login`、`uploading`、`failed` 归一为 `legacy_retired`，不再启动 watcher 或上传任务。
|
||||
|
||||
## External Interfaces
|
||||
|
||||
- Works Square 项目创建、版本上传、Owner 状态与 Release preview API。
|
||||
- 本机 Host API 的发布与真机预览路由。
|
||||
- Works Square 项目创建、版本上传、构建状态、Owner 状态与 Release preview API。
|
||||
- 本机 Host API 的发布与真机预览路由；发布路由要求 Renderer capability。
|
||||
- 服务端安全投影后的公共 `play_url`；只接受同源 HTTPS、精确 App 路径和可信版本状态。
|
||||
|
||||
## Last Updated
|
||||
|
||||
2026-08-09
|
||||
2026-08-10
|
||||
|
||||
@@ -4,15 +4,25 @@
|
||||
|
||||
| Path | Responsibility | Owner Notes |
|
||||
|---|---|---|
|
||||
| `src/components/works/ProjectPublishAction.tsx` | 可发布项目的一键提交、云构建轮询与用户可理解状态 | 只通过 Renderer API 提交非敏感元数据；绑定告警不终止轮询 |
|
||||
| `src/lib/works-square.ts` | Renderer 侧 Works Square Host API 契约与安全错误映射 | 不接触 Token、ZIP、本地绝对路径或自动部署状态 |
|
||||
| `electron/api/routes/works.ts` | Works Host API、Renderer capability 门禁、上游安全投影 | 发布凭据、打包、上传与本地绑定均在 Main 内完成 |
|
||||
| `electron/services/project-packager.ts` | 受控项目扫描、静态 ZIP 生成和敏感/历史控制文件排除 | 只允许可发布 `ProjectType`，不提供 Compose 或手工 ZIP 路径 |
|
||||
| `electron/services/works-submission-binding.ts` | submission binding v2 持久化与旧 schema 迁移 | 旧中间态终止为 `legacy_retired`；文件名暂作安装兼容 |
|
||||
| `electron/api/works-play-url.ts` | 公共播放与 Owner preview URL 的共享安全校验 | 公共 `play_url` 必须同源 HTTPS 且精确匹配 App 路径 |
|
||||
| `electron/api/routes/device-preview.ts` | 精确提交版本的待审/已发布真机预览解析 | 待审使用短时 Release preview，已发布优先 `play_url` |
|
||||
|
||||
## Dependency Direction
|
||||
|
||||
- {dependency direction rule}
|
||||
- Renderer UI → Renderer API contract → Main Host routes → Main services → Works Square；Renderer 不反向读取 Main 凭据、文件系统或归档。
|
||||
- Project configuration 决定产品分流，Main packager 与服务端独立校验决定发布安全；本地 `ProjectType` 不是授权结论。
|
||||
|
||||
## Risky Or Sensitive Areas
|
||||
|
||||
- {module or path that needs extra care}
|
||||
- `electron/api/routes/works.ts` 同时承担发布 capability、上游安全投影和错误脱敏，变更时必须验证未在拒绝前读取凭据或项目文件。
|
||||
- `works-cloud-deploy.json` 是兼容文件名；不得因名称重新引入自动部署协调语义。
|
||||
- `runtime_url` 是一个客户端版本的迁移回退；删除前必须确认服务端和存量数据稳定提供 `play_url`。
|
||||
|
||||
## Last Updated
|
||||
|
||||
{YYYY-MM-DD}
|
||||
2026-08-10
|
||||
|
||||
@@ -9,24 +9,29 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展
|
||||
| Component | Responsibility | Notes |
|
||||
|---|---|---|
|
||||
| Renderer | 项目配置、一键提交状态、真机二维码 | 不接触账号 Token、ZIP、幂等键或本地绝对路径 |
|
||||
| Host API | 校验本地项目请求并投影安全响应 | 只接受回环来源和 JSON mutation |
|
||||
| Host API | 校验本地项目请求并投影安全响应 | 发布 mutation 还必须通过 Renderer capability；Host token/base 不能单独触发发布 |
|
||||
| Project Configuration & Template | 保存不可变 `ProjectType`，原子生成新项目骨架 | 小游戏/小程序生成受控 Vite 模板；自定义保持最小项目空间 |
|
||||
| Project Packager | 确定性扫描、敏感文件排除与 ZIP 生成 | 限制文件数、包体和目录替换 |
|
||||
| Works Session | 七天真实活动滑动续期 | 刷新凭据由 Main 安全持有 |
|
||||
| Device Preview | 核对本地映射、远端版本和 Release | 待审使用短时 Owner preview；已发布使用精确 Runtime |
|
||||
| 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` |
|
||||
|
||||
## Important Boundaries
|
||||
|
||||
- 发布只有现有项目配置底部的一个入口，不新增发布工作台、侧栏或资源卡。
|
||||
- 创建者发布唯一调用链是 `ProjectPublishAction → publishWorksProjectSource → createStaticProjectPackage → 版本上传 → 状态轮询`；客户端不再提供 Compose runner、deploy-check、watcher/arm/upload 协调或手工 ZIP 上传入口。
|
||||
- `ProjectType` 由创建请求写入项目配置，UI 与 Host API 不提供类型变更；缺少类型的旧配置归一为 `custom`。
|
||||
- 本地 `projectType` 只选择产品路径和内部构建 preset，不是可信授权声明；Main 仍需安全打包，服务端仍需独立校验清单和包体。
|
||||
- 云端确认上传成功后，本地映射失败不能把请求改判为失败；否则会诱导重复提交。
|
||||
- Renderer 只能获得安全状态字段和可展示的短时预览 URL。
|
||||
- 云端确认上传成功后，本机 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。
|
||||
|
||||
## Related Decisions
|
||||
|
||||
- 当前长期边界记录于 README 与集成任务 `20260807-integrate-login-client-a4f8`；后续如改变入口或凭据所有权，应新增 ADR。
|
||||
- 当前长期边界记录于 README、集成任务 `20260807-integrate-login-client-a4f8`、源任务 `20260810-static-release-only-a91c` 及本次 Integration Gate；后续如改变唯一入口、凭据所有权或重新引入客户端部署协调器，应新增 ADR。
|
||||
|
||||
## Last Updated
|
||||
|
||||
2026-08-09
|
||||
2026-08-10
|
||||
|
||||
Reference in New Issue
Block a user