1
0

refactor: 规范审查与重组,合并细粒度规范,清理过时内容

- 合并 20+ 细粒度 spec 为粗粒度主题规范:dashboard、data-store、probe-engine、probe-api、probe-config 等
- 删除完全冗余规范:data-retention(被 probe-engine+data-store 覆盖)、backend-code-quality(DEVELOPMENT.md 已记录)
- 补充 http-checker 规范至完整标准(配置+执行+expect+校验+observation),匹配代码 440 行实现
- 清理 tcp/udp/llm checker 规范中已废弃 defaults 配置段的残留 Scenario
- 清理 checker-cohesion-structure 中的实现路径引用(src/server/...)
- 统一所有 spec 格式(## Purpose 开头,去除 # Capability/Title 形式)
- 更新 prompt-spec-review.md 审查提示文档
This commit is contained in:
2026-05-22 18:55:18 +08:00
parent cf847ccd7a
commit cfca03b4d6
40 changed files with 1368 additions and 2134 deletions

View File

@@ -1,6 +1,6 @@
## Purpose
定义将 Vite 构建的前端资源通过 code generation 嵌入 Bun 后端打包为单个 standalone executable 的生产构建、运行配置和验证要求。
定义将 Vite 构建的前端资源通过 code generation 嵌入 Bun 后端、静态资源服务与 Content-Type 处理、打包为单个 standalone executable 的生产构建、运行配置和验证要求。
## Requirements
@@ -89,3 +89,63 @@ executable MUST 将环境相关运行时配置保留在嵌入的前端和 server
#### Scenario: 升迁后重新构建
- **WHEN** 开发者先升迁 `package.json.version` 再运行生产构建命令
- **THEN** 新生成的 standalone executable SHALL 返回升迁后的版本号
### Requirement: 构建时资源扫描与 Code Generation
构建脚本 SHALL 在 Vite build 完成后扫描 `dist/web/` 目录,自动生成 TypeScript 文件,为每个静态资源创建 `import ... with { type: "file" }` 声明。
#### Scenario: 生成资源导入文件
- **WHEN** 构建脚本扫描 `dist/web/` 目录
- **THEN** 系统 SHALL 在 `.build/static-assets.ts` 中为每个文件生成 `import fN from "<path>" with { type: "file" }` 语句,并导出 `StaticAssets` 对象
#### Scenario: StaticAssets 对象结构
- **WHEN** `static-assets.ts` 被生成
- **THEN** 导出的对象 SHALL 包含 `indexHtml: Blob``files: Record<string, Blob>` 两个字段,其中 files 的 key 为 URL 路径(如 `/assets/index-a1b2c3.js`
#### Scenario: 生成 production server entry
- **WHEN** 构建脚本生成资源导入文件后
- **THEN** 系统 SHALL 在 `.build/server-entry.ts` 中生成 production 入口import bootstrap、config 和 staticAssets 并调用 bootstrap
### Requirement: 运行时静态资源服务
系统 SHALL 提供 `serveStaticAsset` 函数,根据请求路径从 StaticAssets 中查找并返回对应资源。
#### Scenario: 请求根路径
- **WHEN** 请求路径为 `/`
- **THEN** 系统 SHALL 返回 `indexHtml`Content-Type 为 `text/html; charset=utf-8`Cache-Control 为 `no-cache`
#### Scenario: 请求已知静态资源
- **WHEN** 请求路径匹配 `files` 中的某个 key
- **THEN** 系统 SHALL 返回对应 BlobContent-Type 根据文件扩展名推断Cache-Control 为 `public, max-age=31536000, immutable`
#### Scenario: 请求未知带扩展名路径
- **WHEN** 请求路径包含文件扩展名但未匹配任何已知资源
- **THEN** 系统 SHALL 返回 404 响应
#### Scenario: SPA Fallback
- **WHEN** 请求路径不包含文件扩展名且不以 `/api/` 开头
- **THEN** 系统 SHALL 返回 `indexHtml`SPA fallback
### Requirement: Content-Type 推断
系统 SHALL 根据文件扩展名推断正确的 Content-Type header。
#### Scenario: JavaScript 文件
- **WHEN** 请求路径以 `.js``.mjs` 结尾
- **THEN** Content-Type SHALL 为 `text/javascript; charset=utf-8`
#### Scenario: CSS 文件
- **WHEN** 请求路径以 `.css` 结尾
- **THEN** Content-Type SHALL 为 `text/css; charset=utf-8`
#### Scenario: SVG 文件
- **WHEN** 请求路径以 `.svg` 结尾
- **THEN** Content-Type SHALL 为 `image/svg+xml`
### Requirement: 静态资源 import specifier SHALL 使用平台无关分隔符
构建时静态资源 code generation SHALL 将文件系统相对路径转换为 ESM import specifier并确保生成的 import 路径在 Windows、macOS、Linux 开发环境下都使用 `/` 作为分隔符。
#### Scenario: Windows 相对路径转换为 import specifier
- **WHEN** code generation 将 Windows 文件系统相对路径 `..\\dist\\web\\assets\\app.js` 转换为静态资源 import specifier
- **THEN** 生成的 import specifier SHALL 为 `../dist/web/assets/app.js`,且 MUST NOT 包含 `\\`
#### Scenario: POSIX 相对路径保持 import specifier 形式
- **WHEN** code generation 将 POSIX 文件系统相对路径 `../dist/web/assets/app.js` 转换为静态资源 import specifier
- **THEN** 生成的 import specifier SHALL 保持为 `../dist/web/assets/app.js`