lanyuanxiaoyao/DiAL
1
0
Fork 0
Code Activity
Files
cfca03b4d68886794e3c17b969195a575676b8ac
DiAL/openspec/specs/frontend-development-workflow/spec.md
lanyuanxiaoyao cfca03b4d6 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 审查提示文档
2026-05-22 18:55:18 +08:00

6.4 KiB
Raw Blame History

Purpose

定义基于 Vite dev server + Bun API server 的前端开发工作流、生产前端构建与 code splitting 策略、开发期 API 访问和共享契约的行为要求。

Requirements

Requirement: Vite React 开发服务器

系统 SHALL 提供基于 Vite dev server 的前端开发工作流，支持热模块替换和 React Fast Refresh。

Scenario: 启动前端开发服务器

  • WHEN 开发者启动开发命令
  • THEN 前端 SHALL 由 Vite dev server 提供服务，支持 HMR 和 React Fast Refresh，监听 :5173 端口

Scenario: 构建前端静态资源

  • WHEN 开发者运行前端生产构建命令
  • THEN 系统 SHALL 通过 Vite build（Rolldown）产出优化的前端静态资源到 dist/web/

Requirement: Vite 前端构建配置

系统 SHALL 使用 Vite 作为前端构建工具，配置文件位于项目根目录 vite.config.ts，以 src/web 为 root，产出到 dist/web/。

Scenario: 运行 Vite 生产构建

  • WHEN 构建脚本执行 bunx --bun vite build
  • THEN Vite SHALL 将 src/web/index.html 及其引用的所有模块构建到 dist/web/ 目录，包含 index.html 和 assets/ 子目录

Scenario: 产出文件名包含 content hash

  • WHEN Vite 构建完成
  • THEN assets/ 目录下的 JS 和 CSS 文件名 SHALL 包含 content hash（如 index-a1b2c3.js）

Requirement: Code Splitting 策略

系统 SHALL 配置 Vite 的 Rolldown code splitting，将 vendor 库分离为独立 chunks，并通过 React.lazy() 动态导入实现按需加载。

Scenario: React 相关库分离

  • WHEN Vite 构建完成
  • THEN react、react-dom、scheduler SHALL 被打包到名为 vendor-react 的独立 chunk

Scenario: TDesign 相关库分离

  • WHEN Vite 构建完成
  • THEN tdesign-react、tdesign-icons-react 相关模块 SHALL 被打包到名为 vendor-tdesign 的独立 chunk

Scenario: 图表库分离

  • WHEN Vite 构建完成
  • THEN recharts 和 d3-* 相关模块 SHALL 被打包到名为 vendor-chart 的独立 chunk

Scenario: TargetDetailDrawer 延迟加载

  • WHEN Vite 构建完成
  • THEN TargetDetailDrawer 及其依赖（recharts、D3、DateRangePicker 等）SHALL 通过 React.lazy() 动态导入，被 Rolldown 自动拆分为异步 chunk，不包含在初始加载的 JS 中

Scenario: Drawer 首次渲染无闪烁

  • WHEN 用户首次点击目标触发 Drawer 渲染
  • THEN Drawer SHALL 通过 <Suspense fallback={null}> 包裹，利用其默认 visible=false 状态避免加载期间的视觉闪烁

Requirement: CSS 处理

系统 SHALL 通过 Vite 处理 CSS 导入，产出独立的 CSS 文件。TDesign 组件样式 SHALL 保持全量导入方式。

Scenario: CSS 文件产出

  • WHEN Vite 构建完成
  • THEN 所有 CSS 导入 SHALL 被提取为独立的 .css 文件到 assets/ 目录

Scenario: CSS 压缩

  • WHEN Vite 执行生产构建
  • THEN 产出的 CSS 文件 SHALL 经过压缩处理

Scenario: TDesign CSS 全量导入

  • WHEN 前端入口文件初始化样式
  • THEN 系统 SHALL 通过 tdesign-react/dist/reset.css 和 tdesign-react/dist/tdesign.min.css 全量导入 TDesign 组件样式

Requirement: 前端构建产物拆分

前端生产构建 SHALL 将 vendor 依赖拆分为独立 chunk，利用浏览器并行加载和长期缓存。

Scenario: vendor chunk 拆分

  • WHEN 执行前端生产构建
  • THEN 构建产物 SHALL 包含独立的 vendor chunk（react、tdesign、recharts 各自独立），而非单个 bundle

Scenario: 业务代码变更不影响 vendor 缓存

  • WHEN 仅修改业务代码（src/web/ 下非 node_modules 文件）并重新构建
  • THEN vendor chunk 的文件名（含 hash）SHALL 保持不变，浏览器缓存 SHALL 继续有效

Requirement: 前端开发期 API 代理

前端开发服务器 SHALL 通过 Vite proxy 配置将 API 请求转发到后端 server。

Scenario: 前端开发期调用拨测 API

  • WHEN 浏览器从 Vite dev server 请求 /api/* 路径
  • THEN Vite SHALL 通过 proxy 将请求转发到 Bun API server（默认 :3000）

Scenario: 前端开发期访问健康检查

  • WHEN 浏览器从 Vite dev server 请求 /health
  • THEN Vite SHALL 通过 proxy 将请求转发到 Bun API server

Scenario: 开发期访问非 API 前端路由

  • WHEN 浏览器从 Vite dev server 请求非 API 前端路由
  • THEN Vite SHALL 将该请求作为前端应用流量处理（SPA fallback 返回 HTML）

Requirement: 开发期双进程运行

项目 SHALL 在开发命令中同时启动 Vite dev server 和 Bun API server 两个进程。

Scenario: 使用默认开发端口

  • WHEN 开发者运行开发命令
  • THEN Vite dev server SHALL 监听 :5173，Bun API server SHALL 监听配置文件指定的端口（默认 :3000）

Scenario: 开发者访问前端

  • WHEN 开发者打开浏览器
  • THEN 开发者 SHALL 访问 Vite dev server 地址（:5173）获取前端页面

Requirement: 前端使用相对 API 路径

除非有文档化的部署配置覆盖该行为，前端代码 MUST 通过相对 /api/* URL 调用后端 API。

Scenario: 前端获取后端数据

  • WHEN 前端代码调用后端 API
  • THEN 请求 URL 默认 MUST 使用相对 /api/* 路径

Scenario: 运行环境变化

  • WHEN host 或 port 在开发环境和生产环境之间变化
  • THEN 前端 API 调用 SHALL 无需修改源码即可继续工作（开发期通过 Vite proxy，生产期通过同源请求）

Requirement: 集成开发命令

项目 SHALL 提供一个文档化命令，用于在开发期间同时运行 Vite dev server 和 Bun API server。

Scenario: 启动全栈开发

  • WHEN 开发者运行文档化的全栈开发命令
  • THEN 系统 SHALL 同时启动 Vite dev server 和 Bun API server，任一进程异常退出时终止另一个

Requirement: 共享 TypeScript 契约

项目 SHALL 为前端和后端共同使用的请求与响应类型提供共享 TypeScript 边界。

Scenario: 定义 API 响应结构

  • WHEN 前端和后端都需要某个 API 响应类型
  • THEN 该类型 SHALL 定义在 shared 模块中，而不是在两端重复定义

Scenario: 前端导入共享类型

  • WHEN 前端代码导入共享 API 类型
  • THEN 该导入 SHALL 不要求将后端运行时实现打包进前端
View Git Blame Copy Permalink