lanyuanxiaoyao/nex
1
0
Fork 0
Code Activity
Files
8eea30ea11fbe318019d29dc49621ddf0c3f3a64
nex/openspec/specs/repository-versioning/spec.md
lanyuanxiaoyao 8eea30ea11 feat: 统一品牌标识、关于页面三卡片布局与版本诊断功能 
- 统一品牌为 Nex：侧边栏、托盘 tooltip、HTML 标题、favicon (PNG 替代 SVG)
- 重构关于页面为三卡片布局（品牌/版本/链接），版本状态 Tag 绝对定位右上角
- 新增 GET /api/version 后端接口，返回 version/commit/build_time
- 新增前端版本一致性诊断：匹配/不匹配/不可判断三种状态
- 同步 delta specs 到主 specs 并归档变更
2026-05-05 03:28:22 +08:00

4.5 KiB
Raw Blame History

仓库版本管理

Purpose

定义仓库统一版本源、镜像同步、发布一致性校验与构建版本注入规则，确保所有构建消费者使用同一版本语义。

Requirements

Requirement: 统一版本源

系统 SHALL 使用仓库根目录 VERSION 文件作为全仓唯一版本源，文件内容 SHALL 仅包含一行 x.y.z 格式的语义版本号。

Scenario: 读取有效版本号

  • WHEN 仓库中的 VERSION 文件内容为 1.2.3
  • THEN 本地工具和 CI SHALL 将 1.2.3 视为当前仓库版本
  • AND 其他版本消费者 SHALL NOT 覆盖该值作为权威来源

Scenario: 拒绝非法版本格式

  • WHEN VERSION 文件内容不是 x.y.z 格式
  • THEN 版本同步与发布校验流程 SHALL 失败
  • AND 系统 SHALL 输出格式错误信息

Requirement: 版本镜像同步

系统 SHALL 提供仓库内的版本同步入口，将 VERSION 中的版本值写入需要镜像版本号的构建消费者。

Scenario: 同步前端镜像字段

  • WHEN 执行版本同步流程且 VERSION 为 1.2.3
  • THEN frontend/package.json 中的 version 字段 SHALL 被同步为 1.2.3

Scenario: 同步构建模板值

  • WHEN 执行版本同步流程且存在依赖版本号的构建模板或元数据模板
  • THEN 这些模板消费的版本值 SHALL 与 VERSION 保持一致
  • AND 系统 SHALL NOT 要求用户手工修改多个版本文件

Requirement: 发布版本一致性校验

系统 SHALL 在发布前校验仓库版本与 Git tag 一致，确保发布锚点与仓库状态不漂移。

Scenario: tag 与 VERSION 一致

  • WHEN 发布使用的 Git tag 为 v1.2.3 且 VERSION 为 1.2.3
  • THEN 发布校验 SHALL 通过

Scenario: tag 与 VERSION 不一致

  • WHEN 发布使用的 Git tag 为 v1.2.4 但 VERSION 为 1.2.3
  • THEN 发布校验 SHALL 失败
  • AND 系统 SHALL 阻止后续发布步骤继续执行

Requirement: 统一构建版本注入

系统 SHALL 在构建阶段把统一版本信息注入 frontend、server 和 desktop，而不是在运行时依赖外部发布平台查询版本。

Scenario: Go 二进制注入版本元数据

  • WHEN 构建 server 或 desktop 二进制
  • THEN 构建流程 SHALL 注入 version、commit 和 buildTime 元数据

Scenario: 前端注入构建版本

  • WHEN 执行前端生产构建
  • THEN 构建流程 SHALL 注入 VITE_APP_VERSION
  • AND 该值 SHALL 等于 VERSION 中的版本号

Requirement: 后端运行时版本查询

系统 SHALL 通过管理接口暴露后端运行时构建版本信息，供前端和用户诊断前后端版本一致性。

Scenario: 查询后端版本信息

  • WHEN 客户端请求 GET /api/version
  • THEN 后端 SHALL 返回 HTTP 200
  • THEN 响应 JSON SHALL 包含 version 字段
  • THEN 响应 JSON SHALL 包含 commit 字段
  • THEN 响应 JSON SHALL 包含 build_time 字段

Scenario: 版本信息来源于构建注入

  • WHEN 后端返回版本信息
  • THEN version SHALL 来源于 buildinfo.Version()
  • THEN commit SHALL 来源于 buildinfo.Commit()
  • THEN build_time SHALL 来源于 buildinfo.BuildTime()
  • THEN 后端 SHALL NOT 在运行时读取仓库 VERSION 文件作为接口响应来源

Scenario: 本地开发构建降级值

  • WHEN 后端未通过构建参数注入版本元数据
  • THEN 后端版本接口 SHALL 返回 buildinfo 的默认降级值
  • THEN 前端 SHALL 能够展示该降级值而不崩溃

Requirement: 前后端版本一致性诊断

系统 SHALL 支持前端使用自身构建版本和后端运行时版本进行一致性诊断。

Scenario: 前端读取构建版本

  • WHEN 前端渲染版本信息
  • THEN 前端 SHALL 使用 VITE_APP_VERSION 作为前端版本号
  • THEN VITE_APP_VERSION SHALL 继续由版本同步流程保持与 VERSION 一致

Scenario: 诊断版本匹配

  • WHEN 前端版本号和后端版本号均可判断且完全相同
  • THEN 前端 SHALL 将版本状态判定为一致

Scenario: 诊断版本不匹配

  • WHEN 前端版本号和后端版本号均可判断且不相同
  • THEN 前端 SHALL 将版本状态判定为不一致
  • THEN 前端 SHALL 将该状态作为诊断提示展示

Scenario: 诊断版本不可判断

  • WHEN 任一版本号为空、dev 或 unknown
  • THEN 前端 SHALL 将版本状态判定为无法判断
  • THEN 前端 SHALL NOT 将该状态判定为版本不一致
View Git Blame Copy Permalink