DiAL/openspec/changes/archive/2026-05-09-harden-fullstack-packaging-foundation/proposal.md

Why

当前项目已经具备 Bun 后端、Vite React 前端、生产静态资源嵌入和单 executable 打包链路，但仍处于 demo 基础设施阶段。真实业务开发开始前，需要先收紧前后端开发、运行时 HTTP 契约、代码质量门禁和生产验证闭环，避免后续业务变更建立在不稳定或不可重复验证的基础上。

What Changes

• 增加 ESLint 作为代码质量、React Hooks 和前后端边界审查工具。
• 增加 Prettier 作为代码风格格式化工具，并排除 openspec/、构建产物和依赖目录。
• 增加快速 check 命令和完整 verify 命令，其中 verify SHALL 覆盖类型检查、lint、格式检查、单元测试、生产构建和 executable smoke test。
• 明确开发期 Bun server 与 Vite proxy 的端口配置一致性，避免前端代理端口和后端监听端口分叉。
• 补充运行配置校验要求，包括默认值、CLI 与环境变量优先级、无效端口拒绝和端口边界行为。
• 强化 HTTP 运行时契约，包括 method 语义、JSON 404/405 错误、静态资源缓存策略和低风险安全响应头。
• 强化单 executable 构建验证，包括确定性资源生成、生产模式验证、静态资源响应头、未知 API、未知 asset 和 SPA fallback 检查。
• 修正 OpenSpec tasks artifact 规则键名，避免 CLI 状态命令产生无效规则警告。
• 同步更新 README，说明质量门禁、验证命令、构建中间产物和运行配置边界。

Capabilities

New Capabilities

• code-quality-gates: 定义 ESLint、Prettier、check 和 verify 的质量门禁行为要求。

Modified Capabilities

• fullstack-app-runtime: 补充运行配置校验、HTTP method、JSON 错误、静态资源缓存和低风险安全响应头等运行时契约。
• frontend-development-workflow: 补充开发期 Bun server 与 Vite proxy 配置一致性的要求。
• single-executable-packaging: 补充确定性构建、完整验证命令和 smoke 覆盖增强要求。

Impact

• 影响 package.json scripts 和开发依赖，新增 lint、format、check、verify 相关命令。
• 影响 ESLint、Prettier 配置文件和忽略规则。
• 影响 src/server/* 的 HTTP method、错误响应、静态资源响应头和配置处理。
• 影响 scripts/build.ts、scripts/dev.ts、scripts/smoke.ts 的构建、开发联调和验证逻辑。
• 影响 tests/，需要补充配置解析、HTTP 语义、静态资源响应和验证行为相关测试。
• 影响 openspec/config.yaml，修正 tasks artifact 规则键名。
• 影响 README.md，需要同步开发命令、验证命令、构建流程和边界说明。