lanyuanxiaoyao/nex
1
0
Fork 0
Code Activity
Files
5655fc5560c65bc48c81fc81c60bce66cb272d0c
nex/openspec/specs/workspace-command-flows/spec.md
lanyuanxiaoyao c9c3a84b33 feat: 扩展发布打包支持多组件多架构多格式产物 
- 新增 web 组件独立发布为 nex-web_<version>.tar.gz
- server 新增 arm64 架构、macOS universal、Windows arm64 产物
- desktop 新增 arm64 架构支持（Linux/Windows）
- Linux desktop 新增 AppImage、deb、rpm 安装包格式
- macOS desktop 新增 unsigned DMG 安装包
- 统一发布资产命名为 {component}_{version}_{platform}_{arch}.{ext}
- 新增 SHA256SUMS 校验和清单覆盖全部发布资产
- versionctl 新增 asset-name CLI 支持按参数生成资产文件名
- Makefile release target 重构为组件/平台/架构参数化
- GitHub Actions release workflow 扩展多组件多架构构建矩阵
- 同步更新 openspec 主规范（desktop-app/release-pipeline/workspace-command-flows）
2026-05-05 12:36:33 +08:00

7.0 KiB
Raw Blame History

Workspace Command Flows

Purpose

定义根目录 Makefile 与 backend/Makefile 的公开命令边界，明确全仓命令、产品级命令和 backend 局部维护命令的职责分层。

Requirements

Requirement: 根目录公开命令分层

根目录 Makefile SHALL 仅暴露全局命令、版本命令、server 产品命令、desktop 产品命令和 release 命令，不再作为 backend 局部维护命令或内部打包步骤的公开入口。release 命令 SHALL 使用 release-assets 前缀，并 SHALL 通过清晰的目标名或变量参数表达 component、platform、arch 和 format。

Scenario: 查看根目录公开命令

  • WHEN 开发者查看根目录 Makefile 的公开 target
  • THEN SHALL 仅看到 lint、test、clean、version-sync、version-check、server-run、server-build、server-lint、server-test、server-clean、desktop-build-mac、desktop-build-win、desktop-build-linux、desktop-lint、desktop-test、desktop-clean 和 release-assets 前缀的 release 公共入口
  • AND release 公共入口 SHALL 能覆盖 server、web、desktop 的目标发布产物

Scenario: 根目录不暴露局部和内部命令

  • WHEN 开发者查看根目录 Makefile 的公开 target
  • THEN SHALL NOT 暴露 backend-*、frontend-*、数据库迁移命令、MySQL 专项测试命令或 desktop-prepare-* 之类内部步骤
  • THEN SHALL NOT 暴露 dev、build、all、desktop-dev、desktop-build 这类模糊或聚合式公共命令

Scenario: release 内部步骤保持内部化

  • WHEN 根目录 Makefile 需要复用 release 构建、打包、校验辅助步骤
  • THEN 内部辅助 target SHALL 使用 _ 前缀或 Make 变量参数化方式表达
  • AND 内部辅助 target SHALL NOT 成为文档化的公共入口

Requirement: 全局质量与清理命令

根目录 Makefile SHALL 提供 lint、test、clean 作为全仓默认入口。

Scenario: 执行全局 lint

  • WHEN 执行 make lint
  • THEN SHALL 运行 backend 的 Go lint 检查和 frontend 的 lint / format check
  • THEN SHALL 在任一检查失败时返回非零退出码

Scenario: 执行全局 test

  • WHEN 执行 make test
  • THEN SHALL 运行 backend 核心测试、frontend 的 Vitest 单元/组件测试和 desktop 专属测试
  • THEN SHALL NOT 运行 MySQL 专项测试和 frontend E2E 测试
  • THEN SHALL 在任一测试失败时返回非零退出码

Scenario: 执行全局 clean

  • WHEN 执行 make clean
  • THEN SHALL 清理 server 与 desktop 相关的构建产物、发布产物和测试报告
  • THEN SHALL NOT 删除 frontend/node_modules、Go module cache 或 bun cache 之类依赖目录和全局缓存

Requirement: Server 产品命令

根目录 Makefile SHALL 提供面向前后端分离 server 模式的产品级命令。

Scenario: 启动 server 模式联调环境

  • WHEN 执行 make server-run
  • THEN SHALL 并行启动 Go 后端服务和前端 Vite 开发服务器
  • THEN SHALL 使前端继续通过现有代理访问本地 backend 服务

Scenario: 构建 server 模式产物

  • WHEN 执行 make server-build
  • THEN SHALL 生成 backend/bin/server
  • AND SHALL 生成 frontend/dist
  • AND SHALL 在构建前校验版本一致性
  • AND SHALL NOT 隐式执行 version-sync 或修改版本镜像文件

Scenario: 执行 server lint

  • WHEN 执行 make server-lint
  • THEN SHALL 运行 backend 的 Go lint 检查和 frontend 的 lint / format check

Scenario: 执行 server test

  • WHEN 执行 make server-test
  • THEN SHALL 运行 backend 核心测试和 frontend 的 Vitest 单元/组件测试
  • THEN SHALL NOT 运行 MySQL 专项测试、frontend E2E 测试或 desktop 专属测试

Scenario: 执行 server clean

  • WHEN 执行 make server-clean
  • THEN SHALL 清理 backend/bin/server、frontend/dist 以及 server 模式相关测试报告与临时产物

Requirement: Desktop 产品命令

根目录 Makefile SHALL 提供按平台拆分的 desktop 构建命令，以及 desktop 产品级 lint、test、clean 命令。

Scenario: 执行按平台拆分的 desktop 构建

  • WHEN 执行 make desktop-build-mac、make desktop-build-win 或 make desktop-build-linux
  • THEN SHALL 分别构建对应平台的 desktop 产物
  • THEN SHALL 在构建前执行版本一致性校验
  • THEN SHALL NOT 隐式执行 version-sync 或修改版本镜像文件
  • THEN SHALL NOT 要求通过额外的 desktop-build 聚合命令触发构建

Scenario: 根目录不提供 desktop 开发聚合入口

  • WHEN 开发者查看根目录 Makefile
  • THEN SHALL NOT 提供 desktop-dev 作为公共命令

Scenario: 执行 desktop lint

  • WHEN 执行 make desktop-lint
  • THEN SHALL 运行 backend 的 Go lint 检查和 frontend 的 lint / format check

Scenario: 执行 desktop test

  • WHEN 执行 make desktop-test
  • THEN SHALL 运行 desktop 专属测试

Scenario: 执行 desktop clean

  • WHEN 执行 make desktop-clean
  • THEN SHALL 清理 desktop 构建目录、嵌入资源目录和 desktop 相关测试/打包产物

Requirement: Release 命令沿用根目录入口

根目录 Makefile SHALL 继续提供 release-assets 前缀 target 作为发布资产入口，并与版本校验、发布资产预检和多组件打包规则保持一致。

Scenario: 执行 release 资产命令

  • WHEN 执行任一 release-assets 前缀的公共 release target
  • THEN SHALL 在构建发布资产前执行版本一致性校验
  • AND SHALL 在需要图标或桌面资源的构建前执行发布资产预检
  • AND SHALL NOT 隐式执行 version-sync 或修改版本镜像文件

Scenario: release target 职责清晰

  • WHEN GitHub Actions 调用根目录 Makefile 生成 release 产物
  • THEN 对应 release target SHALL 明确生成的 component、platform、arch 或 format 范围
  • AND GitHub Actions SHALL NOT 以内联脚本替代 Makefile 中已有的核心构建和打包逻辑

Scenario: web release 产物生成

  • WHEN 执行 web release 资产命令
  • THEN SHALL 使用 Bun 构建 frontend/dist
  • AND SHALL 打包生成 nex-web_<version>.tar.gz
  • AND SHALL NOT 修改前端版本镜像文件

Scenario: checksum release 产物生成

  • WHEN 执行 release 汇总或 Draft Release 组装相关命令
  • THEN SHALL 能基于当前 release 产物目录生成 SHA256SUMS
  • AND SHA256SUMS SHALL 覆盖除自身以外的全部 release 资产

Requirement: Backend 局部命令下沉

数据库迁移、MySQL 专项测试以及其他 backend 局部维护命令 SHALL 由 backend/Makefile 提供，而不是由根目录 Makefile 公开。

Scenario: 执行 backend 局部维护命令

  • WHEN 开发者需要执行数据库迁移或 MySQL 专项测试
  • THEN SHALL 在 backend/ 目录使用 backend 局部 make 命令完成操作
  • THEN 根目录 Makefile SHALL NOT 提供等价的公共命令别名
View Git Blame Copy Permalink