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 提供等价的公共命令别名