nex/openspec/specs/workspace-command-flows/spec.md

Workspace Command Flows

Purpose

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

Requirements

Requirement: 根目录公开命令分层

根目录 Makefile SHALL 仅暴露全局命令、版本命令、server 产品命令、desktop 产品命令和 release 命令，不再作为 backend 局部维护命令或内部打包步骤的公开入口。

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-linux、release-assets-windows、release-assets-macos 这类公共入口

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

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

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-* 作为发布资产入口，并与新的版本校验规则保持一致。

Scenario: 执行 release 资产命令

• WHEN 执行 make release-assets-linux、make release-assets-windows 或 make release-assets-macos
• THEN SHALL 在构建发布资产前执行版本一致性校验
• THEN SHALL NOT 隐式执行 version-sync 或修改版本镜像文件

Requirement: Backend 局部命令下沉

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

Scenario: 执行 backend 局部维护命令

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