feat: 新增应用全局常量 APP,消除硬编码散落
- 新增 src/shared/app.ts,定义应用元信息(name、title、subtitle、description、version) - 后端 3 处硬编码改为引用 APP.name - 前端 3 处硬编码改为引用 APP.title/APP.description - localStorage key 从 my-app.theme.preference 改为 theme.preference - 构建脚本可执行文件名改为引用 APP.name - 更新 README.md 和 DEVELOPMENT.md 文档 - 新增 openspec/specs/app-constants/spec.md 规范文档
This commit is contained in:
61
openspec/specs/app-constants/spec.md
Normal file
61
openspec/specs/app-constants/spec.md
Normal file
@@ -0,0 +1,61 @@
|
||||
## Purpose
|
||||
|
||||
定义应用全局常量,作为应用元信息(name、title、subtitle、description、version)的唯一真实来源,供前后端及构建脚本统一引用,消除硬编码散落。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 应用元信息唯一来源
|
||||
|
||||
系统 SHALL 在 `src/shared/app.ts` 中定义应用全局常量 `APP`,包含以下字段:
|
||||
- `name`:机器标识(kebab-case 格式)
|
||||
- `title`:人类可读标题
|
||||
- `subtitle`:副标题
|
||||
- `description`:应用描述(用于 SEO meta)
|
||||
- `version`:语义版本号
|
||||
|
||||
`APP` SHALL 使用 `as const` 声明,保证字面量类型推断。
|
||||
|
||||
#### Scenario: 后端引用应用名称
|
||||
|
||||
- **WHEN** 后端代码需要应用名称(如 CLI 帮助文本、health 响应、启动日志)
|
||||
- **THEN** 系统 SHALL 从 `src/shared/app.ts` 导入 `APP.name`
|
||||
|
||||
#### Scenario: 前端引用应用标题
|
||||
|
||||
- **WHEN** 前端代码需要应用标题(如 Header logo、欢迎文本)
|
||||
- **THEN** 系统 SHALL 从 `src/shared/app.ts` 导入 `APP.title`
|
||||
|
||||
#### Scenario: 构建脚本引用应用名称
|
||||
|
||||
- **WHEN** 构建脚本需要确定可执行文件名
|
||||
- **THEN** 系统 SHALL 从 `src/shared/app.ts` 导入 `APP.name`
|
||||
|
||||
### Requirement: 前端 HTML 元信息动态设置
|
||||
|
||||
系统 SHALL 在 React 应用挂载时动态设置 HTML 元信息:
|
||||
- `document.title` SHALL 设置为 `APP.title`
|
||||
- `<meta name="description">` 内容 SHALL 设置为 `APP.description`
|
||||
|
||||
#### Scenario: 页面标题显示应用名称
|
||||
|
||||
- **WHEN** 用户访问应用
|
||||
- **THEN** 浏览器标签页标题 SHALL 显示 `APP.title`
|
||||
|
||||
#### Scenario: meta description 设置
|
||||
|
||||
- **WHEN** 搜索引擎爬取页面
|
||||
- **THEN** meta description SHALL 包含 `APP.description`
|
||||
|
||||
### Requirement: localStorage key 语义化命名
|
||||
|
||||
主题偏好存储 key SHALL 为 `"theme.preference"`,不包含应用名前缀。
|
||||
|
||||
#### Scenario: 主题偏好持久化
|
||||
|
||||
- **WHEN** 用户选择主题偏好(system/light/dark)
|
||||
- **THEN** 系统 SHALL 将偏好值存储到 localStorage key `"theme.preference"`
|
||||
|
||||
#### Scenario: 主题偏好读取
|
||||
|
||||
- **WHEN** 应用初始化时读取用户主题偏好
|
||||
- **THEN** 系统 SHALL 从 localStorage key `"theme.preference"` 读取
|
||||
Reference in New Issue
Block a user