diff --git a/.project-docs/20-architecture/data-flow.md b/.project-docs/20-architecture/data-flow.md index 3c19ec8..b561745 100644 --- a/.project-docs/20-architecture/data-flow.md +++ b/.project-docs/20-architecture/data-flow.md @@ -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 diff --git a/.project-docs/20-architecture/module-map.md b/.project-docs/20-architecture/module-map.md index f3af847..ab9aab9 100644 --- a/.project-docs/20-architecture/module-map.md +++ b/.project-docs/20-architecture/module-map.md @@ -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 diff --git a/.project-docs/20-architecture/system-overview.md b/.project-docs/20-architecture/system-overview.md index 0b9b51b..66167f6 100644 --- a/.project-docs/20-architecture/system-overview.md +++ b/.project-docs/20-architecture/system-overview.md @@ -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 diff --git a/.project-docs/30-worklog/current-state.md b/.project-docs/30-worklog/current-state.md index f7396a3..08392bf 100644 --- a/.project-docs/30-worklog/current-state.md +++ b/.project-docs/30-worklog/current-state.md @@ -8,38 +8,43 @@ This file is the integrated default-branch snapshot. Feature tasks record progre - `724290e` / `dcc92fc`：Main-owned 一键打包提交审核及集成提交。 - `1a19ad9` / `f02e99e`：项目真机预览、待审 Release Owner preview 及集成提交。 - `493b31c`：客户端三类 `ProjectType`、小游戏/小程序受控发布模板与自定义项目发布隔离。 +- `4df0477` / `8dd99c1`：客户端静态发布唯一链路、旧 Compose 协调链退役及安全边界补强。 ## Current Focus -客户端面向非专业用户提供“创建小游戏或小程序 → 项目配置中一键提交 → 运营审核通过即发布”的单入口链路，并以项目级真机预览完成待审版本扫码验收；自定义和缺少类型字段的旧项目不提供该入口。 +客户端面向非专业用户提供“创建小游戏或小程序 → 项目配置中一键提交 → Main 安全打包上传 → 轮询云端构建 → 运营审核”的唯一创建者链路，并以项目级真机预览完成待审版本扫码验收；自定义和缺少类型字段的旧项目不提供该入口。已发布作品优先使用安全投影后的 `play_url`，`runtime_url` 仅保留一个客户端版本的兼容回退。 ## Recently Completed - 2026-08-08：合并登录续期、一键发布和真机预览；发布成功后保存精确 app/version/review 映射，Renderer 不接触 Token、ZIP 或本地路径。 - 2026-08-08：补齐跨平台 Electron E2E fixture、Windows ZIP 预检和异常成功响应安全投影。 - 2026-08-09：新建项目支持小游戏、小程序和自定义三类不可变产品类型；前两类生成固定 Vite 发布模板，自定义及缺少类型字段的旧项目不显示一键提交入口。 +- 2026-08-10：删除客户端旧 Compose deploy-check、watcher/arm/upload 协调和手工 ZIP 路由；submission binding v2 保留旧 `submitted` 绑定并把旧中间态归一为 `legacy_retired`，同时补齐 Renderer capability、`play_url` 安全投影和本机绑定失败告警。 ## In Progress -- 成组集成 Works Square 的 `project_type` 接收/校验后，使用真实 Builder 与 Static Gateway 环境执行客户端提交到运营发布的生产整链验收。 +- 成组集成服务端 Builder、OSS immutable Release、CDN/Edge 与 App 消费链后，使用真实账号和生产配置执行客户端提交到作品播放的整链验收。 ## Next Recommended Steps -1. 确认服务端只接受可发布的 `mini_game` / `mini_program`，并继续映射到平台受控构建 preset。 -2. 配置真实生产环境，分别执行“小游戏/小程序创建 → 客户端提交 → 构建与浏览器门禁 → 运营批准 → 公共访问”。 -3. 核对待审 Owner preview 的到期刷新、生产监控和告警证据。 +1. 成组核对服务端 Builder → OSS immutable Release → CDN/Edge 的发布契约与客户端 `play_url` 消费契约。 +2. 配置真实生产环境，分别执行“小游戏/小程序创建 → 客户端提交 → 构建与浏览器门禁 → 运营批准 → App 播放”。 +3. 核对待审 Owner preview 到期刷新、CDN 发布/撤回、生产监控和告警证据。 +4. 在一个客户端兼容版本且服务端与存量数据稳定提供 `play_url` 后，删除 `runtime_url` 回退。 ## Open Questions / Blockers -- 客户端与模拟上游回归已完成；服务端类型契约的成组集成、生产账号和环境变量仍待部署环境确认。 +- 客户端与模拟上游回归已完成；真实 Builder、OSS/CDN、运营审核、App 播放、生产账号和环境变量仍待部署环境确认，不能据此宣称生产发布链已经验收。 ## Risky Areas -- 一键提交已成功但本地预览映射落盘失败时必须保持提交成功，避免用户重复提交；真机预览会明确显示尚不可用。 -- 预览 URL 必须绑定当前项目、精确版本和 Release，并保持 Works Square 同源 HTTPS。 +- 一键提交已成功但本机 submission binding 落盘失败时必须保持提交成功、显示固定 `binding_warning` 并继续轮询，避免用户误判上传失败。 +- 公共 `play_url` 必须满足 Works Square 同源 HTTPS、无 userinfo/loopback、精确 `/apps/{app_id}/` 路径、无 query/fragment、版本非空且上游标记可播放；待审预览仍需绑定当前项目、精确版本和 Release。 +- `/api/works/projects/publish-source` 必须在读取凭据和项目文件前校验 Renderer capability；Host token/base 不能替代该 UI 边界。 +- `works-cloud-deploy.json` 仅是已安装数据的兼容文件名，不代表客户端仍拥有自动部署协调器；旧中间态不得恢复为后台任务。 - 刷新凭据、发布 Token、ZIP、幂等键和重试只能由 Electron Main 持有。 - 本地 `projectType` 只决定产品分流和模板选择，不得作为授权依据或替代 Main/服务端的包体校验。 ## Last Updated -2026-08-09 +2026-08-10 diff --git a/.project-docs/30-worklog/task-history.md b/.project-docs/30-worklog/task-history.md index 5d513db..45a9bee 100644 --- a/.project-docs/30-worklog/task-history.md +++ b/.project-docs/30-worklog/task-history.md @@ -8,6 +8,7 @@ | 2026-08-08 | Makelore 一键提交审核 | 项目配置单入口，Main 安全打包与幂等提交 | README、architecture、domain | | 2026-08-08 | 项目真机预览 | 待审 Owner preview 与精确已发布 Runtime | README、architecture、domain | | 2026-08-09 | 客户端项目类型 | 创建时固定小游戏/小程序/自定义类型；前两类生成受控发布模板 | current-state、architecture、domain | +| 2026-08-10 | 客户端静态发布链路收敛 | 唯一一键静态提交、旧 Compose 协调链退役、submission binding v2 与 `play_url` 安全边界 | current-state、architecture、domain、evidence、commitments | ## Notes diff --git a/.project-docs/30-worklog/tasks/20260810-integrate-static-release-client-7b4d.md b/.project-docs/30-worklog/tasks/20260810-integrate-static-release-client-7b4d.md new file mode 100644 index 0000000..b64f19a --- /dev/null +++ b/.project-docs/30-worklog/tasks/20260810-integrate-static-release-client-7b4d.md @@ -0,0 +1,108 @@ +# Task: 集成客户端静态发布链路收敛 + +## Identity + +- Task ID: 20260810-integrate-static-release-client-7b4d +- Mode: Integration +- Branch: codex/20260810-integrate-static-release-client-7b4d-integrate-static-release-client +- Worktree: D:\Datas\OthersProjects\makelore-integrate-static-release-client-7b4d +- Base commit: 8dd99c1855b4e29b9af8088011785d6524404fb2 +- Owner: codex +- Status: Completed + +## Scope + +- 对已经进入本集成分支的客户端静态发布提交 `4df0477`、安全补强提交 `8dd99c1` 执行正式 Integration Gate。 +- 将源任务 `20260810-static-release-only-a91c` 中经用户确认、已由回归验证且会影响后续维护的发布边界晋升到 canonical 项目记忆。 +- 只更新 canonical `.project-docs` 与本集成任务记录；不修改已验证生产代码，不合并或推送 `main`。 + +## Intent And Constraints + +- 创建者唯一发布路径是项目配置一键提交 → Main 安全打包 → 服务端版本上传 → 客户端轮询云构建；不得恢复 Compose/deploy-check、watcher/arm/upload、手工 ZIP 或独立部署工作台。 +- submission binding v2 只持久化成功提交；旧 `submitted` 绑定保留，旧中间/失败态迁移为 `legacy_retired`，兼容文件名不等于仍有 cloud deployment coordinator。 +- 已发布作品优先使用安全投影后的 `play_url`，`runtime_url` 仅保留一个客户端版本；不可信 URL 必须 fail closed。 +- 发布路由必须在读取凭据、项目文件或开始打包前要求 Renderer capability；Host token/base 不足以绕过 UI。 +- 云端上传成功后的本机绑定失败只能产生安全 `binding_warning`，不能反转提交，Renderer 必须继续轮询。 +- 不把客户端本地/Electron 验证写成真实 Builder、OSS/CDN、运营发布或 App 播放整链已经完成。 + +## Project Context Loaded + +Task context: +- Task ID: `20260810-integrate-static-release-client-7b4d` +- Mode: Integration +- Branch: `codex/20260810-integrate-static-release-client-7b4d-integrate-static-release-client` +- Worktree: `D:\Datas\OthersProjects\makelore-integrate-static-release-client-7b4d` +- Base commit: `8dd99c1855b4e29b9af8088011785d6524404fb2` +- Other active local tasks: `20260807-makelore-release-client-8c4e`、`20260807-client-login-sliding-7d2a`、源任务 `20260810-static-release-only-a91c`、`20260809-cloud-build-diag-client-4a7c`、`20260806-design-multisession-ui-4e7d`、`20260806-design-enter-send-b83f`。 +- Overlap or semantic-conflict assessment: 无语义冲突；旧一键发布任务与本次唯一入口/Main-owned 边界一致，构建诊断只记录上游证据，登录和 AI 设计任务不改变静态发布领域语义。 + +Read: +- `.project-docs/05-agent-entry/memory-index.md` +- `.project-docs/05-agent-entry/integration-gate.md` +- `.project-docs/00-brief/project-positioning.md` +- `.project-docs/00-brief/success-criteria.md` +- `.project-docs/30-worklog/current-state.md` +- `.project-docs/30-worklog/task-history.md` +- `.project-docs/10-decisions/decision-index.md` +- `.project-docs/20-architecture/system-overview.md` +- `.project-docs/20-architecture/module-map.md` +- `.project-docs/20-architecture/data-flow.md` +- `.project-docs/40-domain/business-rules.md` +- `.project-docs/40-domain/glossary.md` +- `.project-docs/50-evidence/evidence-index.md` +- `.project-docs/60-reflection/reflection-index.md` +- `.project-docs/60-reflection/skill-candidates.md` +- `.project-docs/80-commitments/commitments.md` +- `.project-docs/90-maintenance/stale-items.md` +- `.project-docs/90-maintenance/doc-update-policy.md` +- 源任务与全部活跃 peer 的任务记录。 + +Relevant understanding: +- Project goal: 为非专业用户提供项目配置中的一键提交审核链路，由 Main 持有文件、凭据、安全打包和网络访问。 +- Current integrated focus: 小游戏/小程序进入单一提交与项目级真机预览；服务端 OSS/CDN 和生产整链仍未验收。 +- Active task scope: 只晋升客户端静态发布唯一化和相应安全/迁移边界。 +- Active constraints: 不改生产代码；不恢复旧协调链；不泄漏敏感信息；不虚构真实生产部署结论。 +- Decisions affecting this task: 用户已明确确认 Builder → OSS immutable Release → CDN/Edge → App 方向，并要求客户端一步到位移除旧 runner/runtime-cleaner 协调语义；无相反 accepted ADR。 +- Evidence, reflections, or commitments affecting this task: 源任务记录 227 项聚焦回归、typecheck、Vite/Electron build、实际 Electron E2E 和 E2E 收集；真实账号生产整链仍为明确 follow-up。 +- Files or modules likely involved: `current-state.md`、architecture、domain、evidence、commitments、stale-items、task-history 与本任务记录。 +- Unknowns, stale docs, or conflicts: `project-positioning.md`、`success-criteria.md` 仍为模板占位但不影响本次局部晋升；真实 Builder/OSS/CDN/运营/App 环境未验证。 + +Gate result: +- Passed + +## Plan + +1. 以 `4df0477`、`8dd99c1` 和源任务 Outcome/Verification/Promotion Candidates 为证据，筛选最小长期事实。 +2. 更新当前状态、架构/数据流、领域规则/术语、任务历史、证据、承诺和缺失上下文；不创建无必要 ADR，不修改产品代码。 +3. 运行文档结构与 task-aware drift 检查，并复跑静态发布关键门禁、typecheck、Vite/Electron build 和 E2E 收集。 +4. 完成本集成任务记录并提交中文 integration commit，保持独立分支等待 root 最终 fast-forward。 + +## Outcome + +- 已在 `current-state.md` 登记源提交 `4df0477` / `8dd99c1`，并把当前客户端发布焦点更新为项目配置一键提交、Main 打包上传、云构建轮询与运营审核；真实 OSS/CDN/App 生产链继续保持未完成状态。 +- 已在系统概览、模块图和数据流固定唯一静态发布路径、submission binding v2、旧状态 `legacy_retired`、Renderer capability、`binding_warning` 以及 `play_url`/`runtime_url` 迁移边界。 +- 已在领域规则和术语表明确旧 Compose/deploy-check/watcher/arm/upload/手工 ZIP 入口不得恢复，兼容文件名不代表自动部署协调器仍存在。 +- 已将源任务验证加入证据索引，将真实生产整链和后续删除 `runtime_url` 记录为共享承诺，并在 stale items 明确客户端本地验证不能替代生产部署结论。 +- 未创建 ADR：本次晋升落实用户已确认且与现有单入口/Main-owned 边界一致的实现事实，没有反转 accepted decision 或改变产品方向。 + +## Verification + +- `git merge-base --is-ancestor`：`4df047708b40011a2c68dbfaa23ac214360e481e` 与 `8dd99c1855b4e29b9af8088011785d6524404fb2` 均已进入当前集成基线。 +- `check_project_docs.py --target .`：通过。 +- `check_doc_drift.py --target . --task-id 20260810-integrate-static-release-client-7b4d`：通过，canonical 写入符合 integration ownership 边界。 +- `pnpm exec vitest run tests/unit/works-play-url.test.ts tests/unit/works-submission-binding.test.ts tests/unit/device-preview-routes.test.ts tests/unit/project-progress-sync.test.ts tests/unit/works-routes.test.ts tests/unit/works-square.test.ts tests/unit/project-publish-action.test.tsx tests/unit/works-project-publish.test.ts tests/unit/project-packager.test.ts tests/unit/opencode-routes.test.ts`：10 files / 227 tests passed。 +- `pnpm run typecheck`：通过。 +- `pnpm run build:vite`：Renderer、Electron Main、Preload 均构建成功；仅有仓库既有 chunk-size 提示。 +- `pnpm exec playwright test --list --reporter=line`：成功收集 13 个 Electron E2E 文件、21 条用例；实际 Electron 一键入口用例沿用源任务已通过证据。 +- `git diff --check`：通过；仅有 Windows 工作区的 LF/CRLF 提示。 +- 变更路径复核：除本 integration task record 外全部位于 canonical `.project-docs`，未修改任何生产代码、测试、README 或构建配置。 + +## Follow-ups + +- 完成服务端 Builder、OSS immutable Release、CDN/Edge 与 App 消费链成组集成后，执行真实小游戏和小程序生产整链验收。 +- 一个客户端兼容版本结束且服务端/存量数据稳定提供 `play_url` 后，删除 `runtime_url` 类型、读取回退和测试。 +- 仓库级 lint 的既有错误继续由独立维护任务处理，避免混入本次文档集成。 + +## Promotion Candidates + +- None；本次已完成源任务中经确认且适用于客户端的 canonical 晋升。 diff --git a/.project-docs/40-domain/business-rules.md b/.project-docs/40-domain/business-rules.md index 7e4e92d..a6fd325 100644 --- a/.project-docs/40-domain/business-rules.md +++ b/.project-docs/40-domain/business-rules.md @@ -6,15 +6,21 @@ - 新建小游戏和小程序会生成平台固定版本的受控 Vite 发布模板，并可使用项目配置中的单一“提交审核”入口；`custom` 和缺少类型字段的旧项目不提供一键发布。 - `ProjectType` 不等于 `BuildPreset`：第一期两个可发布产品类型都映射到内部受控 Vite preset；本地 `projectType` 不是授权边界，Main-owned 安全打包、Host API 和服务端包体校验仍必须执行。 - 非专业用户只执行一次“提交审核”；构建通过后由运营审核，审核通过即直接发布。 -- 不恢复独立发布上传页或云部署工作台；入口只位于现有项目配置操作区。 +- 创建者发布唯一链路是项目配置“一键提交审核” → Main 安全打包 → 服务端版本上传 → 客户端轮询云构建；不恢复独立发布上传页、云部署工作台、Compose/deploy-check、自动 watcher/arm/upload 或手工 ZIP 入口。 - 待审版本只能通过绑定精确 Release 的短时 Owner preview 验收；旧版本、构建中或失败状态不能生成可扫码假象。 - 发布和预览安全边界由 Electron Main 持有，Renderer 不接触账号 Token、ZIP、幂等键和本地绝对路径。 +- 发布 Host API 必须在读取凭据、查询项目和打包前校验 Renderer capability；仅持有 Host token/base 的非 UI 调用方不得发起发布。 +- 客户端只持久化服务端已接受的 submission binding v2。旧 `submitted` 绑定必须保留；旧 `armed`、`waiting_for_package`、`waiting_for_login`、`uploading`、`failed` 必须迁移为可理解的 `legacy_retired`，不得恢复后台任务。 +- 云端上传成功但本机 submission binding 保存失败时，提交仍视为成功；客户端显示固定、无本地路径的告警并继续轮询云构建，避免诱导重复提交。 +- 已发布作品优先读取 `play_url`，只有字段缺失时才使用一个客户端版本的 `runtime_url` 回退。公共播放 URL 必须是 Works Square 同源 HTTPS、无 userinfo/loopback、精确 `/apps/{encodeURIComponent(app_id)}/`、无 query/fragment，且上游明确 `playable === true` 并提供非空版本名；否则按不可播放处理。 +- `works-cloud-deploy.json` 仅是已安装客户端的数据兼容文件名，不表示客户端仍提供 cloud deployment coordinator。 - Works Square 会话按真实键盘、鼠标或触摸活动滑动续期，连续 7 天未使用才要求重新授权。 ## Open Questions -- 生产整链需要真实账号、Builder、Static Gateway 与监控环境完成最终验收。 +- 生产整链需要真实账号、Builder、OSS immutable Release、CDN/Edge、运营审核、App 播放与监控环境完成最终验收；当前客户端验证不能替代该验收。 +- 在一个客户端兼容版本且服务端与存量数据稳定提供 `play_url` 后，移除 `runtime_url` 回退。 ## Last Reviewed -2026-08-09 +2026-08-10 diff --git a/.project-docs/40-domain/glossary.md b/.project-docs/40-domain/glossary.md index a5a61df..fe60c37 100644 --- a/.project-docs/40-domain/glossary.md +++ b/.project-docs/40-domain/glossary.md @@ -5,3 +5,7 @@ | `ProjectType` | 创建项目时选择且之后不可变的产品类型 | 当前值为 `mini_game`、`mini_program`、`custom`；缺少字段的旧配置按 `custom` 处理 | | `BuildPreset` | 平台内部用于构建和验收项目包的受控实现 | 不等于 `ProjectType`；第一期小游戏和小程序都使用 Vite preset | | 受控发布模板 | Main 在新建可发布项目时生成的固定依赖、锁文件和可运行示例 | 保障一键提交的结构基线，但本地模板和 `projectType` 本身都不是授权边界 | +| Submission Binding | 客户端在云端接受上传后保存的精确 app/version/review/hash 绑定 | schema v2 只记录成功提交；落盘文件名暂保留 `works-cloud-deploy.json` 以兼容已安装数据 | +| `legacy_retired` | 旧自动部署中间态迁移后的终止状态 | 不恢复 watcher、登录等待或自动上传；提示用户从项目配置重新提交 | +| `play_url` | 服务端为已发布作品提供的公共播放地址 | 客户端优先使用并执行同源 HTTPS、精确 App 路径和版本状态校验 | +| `runtime_url` | `play_url` 上线期间的旧公共播放字段 | 仅保留一个客户端版本的兼容回退，稳定迁移后删除 | diff --git a/.project-docs/50-evidence/evidence-index.md b/.project-docs/50-evidence/evidence-index.md index 15b8e71..ecda99d 100644 --- a/.project-docs/50-evidence/evidence-index.md +++ b/.project-docs/50-evidence/evidence-index.md @@ -4,6 +4,7 @@ Use this index for searchable, traceable evidence records. | Date | Topic | Status | Source | Detail | |---|---|---|---|---| +| 2026-08-10 | 客户端静态发布唯一链路 | 本地验证通过 | `30-worklog/tasks/20260810-static-release-only-a91c.md`、`4df0477`、`8dd99c1` | 227 项聚焦回归、typecheck、Vite/Electron build、实际 Electron E2E 与 13 files / 21 tests 收集通过；不等同于真实生产部署验收 | ## When To Add Evidence diff --git a/.project-docs/80-commitments/commitments.md b/.project-docs/80-commitments/commitments.md index ae3d12c..cf61dd0 100644 --- a/.project-docs/80-commitments/commitments.md +++ b/.project-docs/80-commitments/commitments.md @@ -4,6 +4,8 @@ Track future-facing memory: promised follow-ups, unfinished loops, timed checks, | Date | Commitment | Trigger / Due | Owner | Status | Next Action | |---|---|---|---|---|---| +| 2026-08-10 | 完成客户端提交到 App `play_url` 播放的真实生产整链验收 | 服务端 Builder、OSS immutable Release、CDN/Edge 与 App 消费链成组集成后 | 客户端/服务端集成 | Pending | 使用真实账号执行小游戏和小程序创建、提交、浏览器门禁、运营批准、CDN 发布、App 播放与监控核对 | +| 2026-08-10 | 删除客户端 `runtime_url` 兼容回退 | 一个客户端兼容版本结束，且服务端与存量数据稳定提供 `play_url` | 客户端 | Pending | 删除类型字段、读取分支和对应回归测试 | ## Use diff --git a/.project-docs/90-maintenance/stale-items.md b/.project-docs/90-maintenance/stale-items.md index bad04bd..2b5eb39 100644 --- a/.project-docs/90-maintenance/stale-items.md +++ b/.project-docs/90-maintenance/stale-items.md @@ -9,7 +9,7 @@ This is the integrated registry of stale or conflicting canonical memory. Update ## Missing Context -- {missing information that affects future planning} +- 尚未验证真实生产环境是否已部署 Builder → OSS immutable Release → CDN/Edge，也未完成运营审核到 App `play_url` 播放的真实整链证据；客户端本地与模拟上游验证不能替代该结论。 ## Feature Task Routing