refactor: 移除 success 字段，简化为 matched 单层判定模型
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-05-09
|
||||
@@ -0,0 +1,52 @@
|
||||
## Context
|
||||
|
||||
当前项目根目录存在三项冗余：
|
||||
|
||||
1. `index.ts` — 仅包含 `import "./src/server/dev.ts"`，与 `package.json` 的 `"start"` 脚本功能完全重复，无任何其他文件或脚本引用它
|
||||
2. `"module": "src/server/dev.ts"` — `private: true` 项目不会被发布，ESM 入口字段无消费者；且指向一个启动服务器的副作用文件本身就不合理
|
||||
3. `.build/` 目录 — 由 `scripts/build.ts` 在每次构建时生成，包含 `server-entry.ts` 和 `static-assets.ts` 两个中间文件。构建完成后这些文件残留在磁盘上，虽已被 `.gitignore` 忽略但不必要地占用空间
|
||||
|
||||
项目构建流程为：`vite build` → 生成 `.build/` 中间文件 → `Bun.build()` 编译为单可执行文件 → 输出到 `dist/gateway-checker`。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- 移除无实际作用的文件和配置，减少项目结构噪音
|
||||
- 构建成功后自动清理中间产物，保持项目目录整洁
|
||||
- 构建失败时保留中间产物以便排查问题
|
||||
|
||||
**Non-Goals:**
|
||||
- 不改变构建产物本身（输出路径、可执行文件行为不变）
|
||||
- 不引入新的构建步骤或依赖
|
||||
- 不调整 RuntimeMode 或开发/生产模式的区分逻辑
|
||||
|
||||
## Decisions
|
||||
|
||||
### Decision 1: 直接删除 `index.ts`
|
||||
|
||||
**选择**：删除文件
|
||||
**备选**：保留但添加注释说明用途
|
||||
**理由**：无任何脚本、文件或构建流程引用它，保留只会增加困惑。`package.json` 的 `"start"` 脚本已直接指向 `src/server/dev.ts`。
|
||||
|
||||
### Decision 2: 移除 `"module"` 字段
|
||||
|
||||
**选择**：从 `package.json` 中删除 `"module"` 字段
|
||||
**备选**：改为 `"main"` 字段
|
||||
**理由**：`private: true` 意味着不会被 npm 发布，任何入口字段都没有消费者。改为 `"main"` 同样无意义，因为这不是一个库。完全移除最简洁。
|
||||
|
||||
### Decision 3: 构建成功后清理 `.build/`
|
||||
|
||||
**选择**：在 `Bun.build()` 成功后调用 `await rm(buildDir, { recursive: true, force: true })`
|
||||
**备选**：
|
||||
- 始终保留 `.build/`（当前行为）
|
||||
- 使用临时目录（`os.tmpdir()`）
|
||||
|
||||
**理由**：`build.ts` 开头已导入 `rm` 且已在构建开始时执行清理，只需在成功路径末尾复用同一行代码。构建失败时 `.build/` 自然保留，兼顾排查需求。不使用临时目录是因为 `Bun.build()` 的 `import ... with { type: "file" }` 需要相对路径引用 `dist/web/` 下的实际文件，临时目录增加路径复杂度。
|
||||
|
||||
具体修改位置：`scripts/build.ts` 第 53 行 `console.log(...)` 之后。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **[极低风险] 删除 `index.ts` 影响外部工具**：如果 CI/CD 或其他自动化流程通过 `bun index.ts` 启动，会中断。→ 检查确认无此类用法。`package.json` 中 `"start": "bun src/server/dev.ts"` 是标准入口。
|
||||
- **[极低风险] 移除 `module` 字段影响 IDE 解析**：某些 IDE 可能依赖 `module` 字段进行跳转。→ 实际指向 `dev.ts`，对代码导航无帮助。
|
||||
- **[低风险] 清理 `.build/` 后无法排查偶现构建问题**：→ 构建失败时 `.build/` 保留，只有成功时才清理，排查路径完整。
|
||||
@@ -0,0 +1,25 @@
|
||||
## Why
|
||||
|
||||
项目根目录存在冗余文件和无效配置：`index.ts` 与 `start` 脚本功能完全重复，`package.json` 的 `module` 字段在 `private` 项目中无实际作用，`.build/` 中间产物在构建成功后未清理导致磁盘残留。这些虽不影响运行，但增加了维护负担和项目结构的困惑。
|
||||
|
||||
## What Changes
|
||||
|
||||
- 删除根目录 `index.ts`，它是 `src/server/dev.ts` 的无意义包装，无任何脚本或文件引用它
|
||||
- 移除 `package.json` 中的 `"module": "src/server/dev.ts"` 字段，`private: true` 的应用项目不需要此字段，且指向副作用文件作为 ESM 入口本身就不合理
|
||||
- 在 `scripts/build.ts` 中，`Bun.build()` 成功后自动清理 `.build/` 目录，构建失败时保留以便排查
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
（无新增能力）
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `single-executable-packaging`: 构建流程新增成功后清理 `.build/` 中间产物目录的步骤
|
||||
|
||||
## Impact
|
||||
|
||||
- 删除文件：`index.ts`
|
||||
- 修改文件：`package.json`（移除 1 行）、`scripts/build.ts`（新增 1 行）
|
||||
- 不影响任何现有功能、API 或开发工作流
|
||||
@@ -0,0 +1,24 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 单 executable 输出
|
||||
生产构建 SHALL 输出一个 standalone executable，其中包含 Bun 后端、必要 server 依赖和构建后的前端资源。构建成功后 SHALL 自动清理中间产物目录（`.build/`），构建失败时 SHALL 保留中间产物以便排查。
|
||||
|
||||
#### Scenario: 在目标机器运行 executable
|
||||
- **WHEN** 生成的 executable 在兼容目标平台上运行
|
||||
- **THEN** 它 SHALL 启动全栈应用，且不要求目标机器安装 Node.js、Bun、Vite 或 `node_modules`
|
||||
|
||||
#### Scenario: 服务嵌入的前端
|
||||
- **WHEN** executable 收到前端根路径请求
|
||||
- **THEN** 它 SHALL 从 executable 内包含的资源服务前端，且不需要外部 `dist/` 目录
|
||||
|
||||
#### Scenario: 服务嵌入 demo API 和页面
|
||||
- **WHEN** 生成的 executable 启动，且浏览器打开前端根路径
|
||||
- **THEN** 页面 SHALL 展示同一个 executable 进程中 `/api/demo` 返回的数据
|
||||
|
||||
#### Scenario: 构建成功后清理中间产物
|
||||
- **WHEN** 生产构建成功完成并输出 executable
|
||||
- **THEN** 系统 SHALL 自动删除 `.build/` 目录及其所有内容
|
||||
|
||||
#### Scenario: 构建失败时保留中间产物
|
||||
- **WHEN** 生产构建在任意步骤失败（前端构建、中间产物生成、Bun 编译）
|
||||
- **THEN** `.build/` 目录 SHALL 保留在磁盘上以供排查
|
||||
@@ -0,0 +1,13 @@
|
||||
## 1. 移除冗余文件和配置
|
||||
|
||||
- [x] 1.1 删除根目录 `index.ts` 文件
|
||||
- [x] 1.2 从 `package.json` 中移除 `"module": "src/server/dev.ts"` 字段
|
||||
|
||||
## 2. 构建后清理中间产物
|
||||
|
||||
- [x] 2.1 在 `scripts/build.ts` 的 `Bun.build()` 成功后添加清理 `.build/` 目录的代码
|
||||
|
||||
## 3. 验证
|
||||
|
||||
- [x] 3.1 运行 `bun run check` 确认类型检查、lint、格式化、测试全部通过
|
||||
- [x] 3.2 运行 `bun run verify` 确认完整构建和 smoke test 通过
|
||||
Reference in New Issue
Block a user