feat: 新增两个 OpenSpec 变更提案 — CMD Checker 增强与前端指标增强
This commit is contained in:
2
openspec/changes/cmd-checker-enhancement/.openspec.yaml
Normal file
2
openspec/changes/cmd-checker-enhancement/.openspec.yaml
Normal file
@@ -0,0 +1,2 @@
|
|||||||
|
schema: spec-driven
|
||||||
|
created: 2026-05-13
|
||||||
112
openspec/changes/cmd-checker-enhancement/design.md
Normal file
112
openspec/changes/cmd-checker-enhancement/design.md
Normal file
@@ -0,0 +1,112 @@
|
|||||||
|
## Context
|
||||||
|
|
||||||
|
当前 command checker 使用 `"command"` 作为 type 和 configKey，对应源码目录 `src/server/checker/runner/command/`、测试目录 `tests/server/checker/runner/command/`、spec 目录 `openspec/specs/command-checker/`。
|
||||||
|
|
||||||
|
测试中使用了 `true`、`false`、`sleep`、`bash`、`yes | head` 等 Unix 系统命令，在纯 Windows 环境（无 Git Bash）下无法运行。probes.example.yaml 中的示例命令（`uname -a`、`ls /tmp`、`date`）同样不跨平台。
|
||||||
|
|
||||||
|
项目未上线，无向前兼容负担。
|
||||||
|
|
||||||
|
## Goals / Non-Goals
|
||||||
|
|
||||||
|
**Goals:**
|
||||||
|
|
||||||
|
- 将 type/configKey 从 `"command"` 统一重命名为 `"cmd"`，包括源码目录、测试目录、spec 目录、YAML 配置键名
|
||||||
|
- 测试改用 `bun -e "..."` 替代系统命令，确保 Windows/macOS/Linux 三平台通过
|
||||||
|
- probes.example.yaml 提供跨平台示例
|
||||||
|
|
||||||
|
**Non-Goals:**
|
||||||
|
|
||||||
|
- 不加 shell 模式（现有 exec + args 已覆盖所有 shell 场景）
|
||||||
|
- 不加重试机制（失败是拨测指标）
|
||||||
|
- 不精简 resolve() 中 intervalMs/timeoutMs（收益小，接口改动大）
|
||||||
|
- 不加 successExitCodes 别名（已有 expect.exitCode）
|
||||||
|
|
||||||
|
## Decisions
|
||||||
|
|
||||||
|
### D1: type 与 configKey 统一为 `cmd`
|
||||||
|
|
||||||
|
YAML 配置形态变为：
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
defaults:
|
||||||
|
cmd:
|
||||||
|
maxOutputBytes: "100MB"
|
||||||
|
|
||||||
|
targets:
|
||||||
|
- name: "test"
|
||||||
|
type: cmd
|
||||||
|
cmd:
|
||||||
|
exec: "bun"
|
||||||
|
args: ["-e", "console.log('hello')"]
|
||||||
|
```
|
||||||
|
|
||||||
|
**理由：** `cmd` 简洁，且 type 与 configKey 保持一致（与 HTTP checker 的 `http`/`http` 对称）。
|
||||||
|
|
||||||
|
**替代方案：** 只改 type 不改 configKey → 会出现 `type: cmd` + `command: {...}` 的不一致，否决。
|
||||||
|
|
||||||
|
### D2: 内部属性名统一为 `cmd`
|
||||||
|
|
||||||
|
`ResolvedCommandTarget` 接口中的 `command` 属性名也改为 `cmd`：
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// Before
|
||||||
|
interface ResolvedCommandTarget {
|
||||||
|
command: ResolvedCommandConfig;
|
||||||
|
type: "command";
|
||||||
|
}
|
||||||
|
// t.command.exec
|
||||||
|
|
||||||
|
// After
|
||||||
|
interface ResolvedCommandTarget {
|
||||||
|
cmd: ResolvedCommandConfig;
|
||||||
|
type: "cmd";
|
||||||
|
}
|
||||||
|
// t.cmd.exec
|
||||||
|
```
|
||||||
|
|
||||||
|
**理由：** 内外一致，避免 configKey 是 `cmd` 但内部属性是 `command` 的割裂。
|
||||||
|
|
||||||
|
### D3: 源码目录重命名 `runner/command/` → `runner/cmd/`
|
||||||
|
|
||||||
|
所有 import 路径同步更新。测试目录 `tests/server/checker/runner/command/` → `tests/server/checker/runner/cmd/`。
|
||||||
|
|
||||||
|
**理由：** 目录名与 type/configKey 保持一致，降低认知负担。
|
||||||
|
|
||||||
|
### D3: 跨平台测试命令替换表
|
||||||
|
|
||||||
|
| 原命令 | 替换为 |
|
||||||
|
|---|---|
|
||||||
|
| `true` | `bun -e "process.exit(0)"` |
|
||||||
|
| `false` | `bun -e "process.exit(1)"` |
|
||||||
|
| `echo hello` | `bun -e "console.log('hello')"` |
|
||||||
|
| `sleep 10` | `bun -e "await Bun.sleep(10000)"` |
|
||||||
|
| `bash -c "echo error >&2"` | `bun -e "process.stderr.write('error\n')"` |
|
||||||
|
| `bash -c "yes \| head -1000"` | `bun -e "process.stdout.write('y\n'.repeat(1000))"` |
|
||||||
|
|
||||||
|
**理由：** `bun` 是项目唯一运行时依赖，三平台均可用，无需额外安装。
|
||||||
|
|
||||||
|
### D4: probes.example.yaml 示例策略
|
||||||
|
|
||||||
|
示例命令改用 `bun -e "..."` 或跨平台命令（如 `bun --version`），不再使用 `uname`、`ls /tmp` 等 Unix 专属命令。
|
||||||
|
|
||||||
|
### D5: spec 目录重命名
|
||||||
|
|
||||||
|
`openspec/specs/command-checker/` → `openspec/specs/cmd-checker/`，与 type 名称对齐。
|
||||||
|
|
||||||
|
### D6: 不加 shell 模式
|
||||||
|
|
||||||
|
用户需要管道/重定向时，用现有参数即可：
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
cmd:
|
||||||
|
exec: "/bin/bash"
|
||||||
|
args: ["-c", "df -h | grep /dev/sda1"]
|
||||||
|
```
|
||||||
|
|
||||||
|
shell 模式本质是语法糖——内部仍然是 `Bun.spawn([shell, "-c", exec])`。增加代码复杂度（shell 检测、参数推断、互斥校验）但收益有限。
|
||||||
|
|
||||||
|
## Risks / Trade-offs
|
||||||
|
|
||||||
|
- [全量重命名可能遗漏引用] → 通过全局搜索 `"command"` 字面量确保无遗漏，CI 类型检查兜底
|
||||||
|
- [测试中 `bun -e` 启动开销比原生命令大] → 拨测场景不敏感，测试可接受毫秒级差异
|
||||||
|
- [probes.example.yaml 示例不如 Unix 命令直观] → 加注释说明用途，保持可读性
|
||||||
34
openspec/changes/cmd-checker-enhancement/proposal.md
Normal file
34
openspec/changes/cmd-checker-enhancement/proposal.md
Normal file
@@ -0,0 +1,34 @@
|
|||||||
|
## Why
|
||||||
|
|
||||||
|
`command` 作为 checker type 名称过长，且测试依赖 Unix 系统命令导致 Windows 环境无法运行。需要统一重命名为 `cmd` 并实现跨平台测试适配。
|
||||||
|
|
||||||
|
## What Changes
|
||||||
|
|
||||||
|
- **BREAKING** type 字面量 `"command"` → `"cmd"`，configKey `"command"` → `"cmd"`
|
||||||
|
- **BREAKING** YAML 配置中 `type: command` → `type: cmd`，`command:` 块 → `cmd:` 块
|
||||||
|
- **BREAKING** `defaults.command` → `defaults.cmd`
|
||||||
|
- 源码目录 `runner/command/` → `runner/cmd/`
|
||||||
|
- spec 目录 `command-checker/` → `cmd-checker/`
|
||||||
|
- 测试全部改用 `bun -e "..."` 替代系统命令（true/false/sleep/bash）
|
||||||
|
- probes.example.yaml 更新为跨平台示例
|
||||||
|
|
||||||
|
## Capabilities
|
||||||
|
|
||||||
|
### New Capabilities
|
||||||
|
|
||||||
|
（无）
|
||||||
|
|
||||||
|
### Modified Capabilities
|
||||||
|
|
||||||
|
- `probe-config`: `type: command` → `type: cmd`，`command` 分组 → `cmd` 分组，`defaults.command` → `defaults.cmd`，所有校验中的 `"command"` 字面量更新
|
||||||
|
- `command-checker`: type/configKey 重命名为 `cmd`，spec 目录重命名为 `cmd-checker`
|
||||||
|
- `checker-runner-abstraction`: registry 注册的 type 从 `"command"` 变为 `"cmd"`，`supportedTypes` 返回 `["http", "cmd"]`
|
||||||
|
- `windows-test-compat`: 测试命令全面改用 `bun -e "..."`，probes.example.yaml 使用跨平台示例
|
||||||
|
|
||||||
|
## Impact
|
||||||
|
|
||||||
|
- 后端：`src/server/checker/runner/command/` 整个目录重命名及内部所有 `"command"` 字面量
|
||||||
|
- 配置：probes.example.yaml、probe-config.schema.json 中的 type 枚举和分组名
|
||||||
|
- 测试：`tests/server/checker/runner/command/` 目录重命名及测试命令替换
|
||||||
|
- 前端：无影响（动态显示 type 值）
|
||||||
|
- 数据库：stored_targets.type 列值变更（项目未上线，无迁移负担）
|
||||||
@@ -0,0 +1,43 @@
|
|||||||
|
## MODIFIED Requirements
|
||||||
|
|
||||||
|
### Requirement: CheckerRegistry 注册中心
|
||||||
|
系统 SHALL 在 `src/server/checker/runner/registry.ts` 中提供 `CheckerRegistry` 类，支持 `register(checker)`、`get(type)` 和 `supportedTypes`。重复注册同一 type SHALL 抛出错误。registry 内部 SHALL 存储 `CheckerDefinition`（使用默认泛型参数），对外提供类型擦除后的接口。
|
||||||
|
|
||||||
|
#### Scenario: 查询支持的 type 列表
|
||||||
|
- **WHEN** 注册了 "http" 和 "cmd" 两个 checker 后查询 `registry.supportedTypes`
|
||||||
|
- **THEN** 返回的数组 SHALL 包含 `["http", "cmd"]`（按注册顺序）
|
||||||
|
|
||||||
|
### Requirement: Command checker 提供契约片段
|
||||||
|
系统 SHALL 支持 checker 提供自身 TypeBox 配置契约片段，用于描述该 checker 的 defaults 分组、target 领域分组和 expect 分组。
|
||||||
|
|
||||||
|
#### Scenario: Cmd checker 提供契约片段
|
||||||
|
- **WHEN** Cmd checker 被注册
|
||||||
|
- **THEN** registry SHALL 能提供 Cmd defaults、Cmd target 和 Cmd expect 的 TypeBox 契约片段
|
||||||
|
|
||||||
|
### Requirement: 配置解析通过 registry 委托 checker
|
||||||
|
系统 SHALL 在 `config-loader.ts` 的配置加载流程中通过 `checkerRegistry` 发现已注册 checker，组合公共 TypeBox 契约与 checker 契约，并将 checker 专属语义校验和解析委托给对应 checker。
|
||||||
|
|
||||||
|
#### Scenario: 配置解析委托 checker
|
||||||
|
- **WHEN** config-loader 解析一个 type 为 "cmd" 的 target
|
||||||
|
- **THEN** config-loader SHALL 调用 `checkerRegistry.get("cmd")` 获取对应 checker，并委托该 checker 执行语义校验和 resolve
|
||||||
|
|
||||||
|
### Requirement: Command text 断言位于 Cmd 目录
|
||||||
|
系统 SHALL 在 checker 专用目录中提供 text 断言函数。
|
||||||
|
|
||||||
|
#### Scenario: Command text 断言位于 Cmd 目录
|
||||||
|
- **WHEN** Cmd checker 需要对 stdout/stderr 执行文本规则校验
|
||||||
|
- **THEN** SHALL 调用 `runner/cmd/text.ts` 中的 `checkTextRules(text, rules, phase)`
|
||||||
|
|
||||||
|
### Requirement: Command 专用 expect
|
||||||
|
系统 SHALL 在 checker 专用目录中提供 exitCode 断言函数。
|
||||||
|
|
||||||
|
#### Scenario: Command 专用 expect
|
||||||
|
- **WHEN** Cmd checker 需要校验退出码
|
||||||
|
- **THEN** SHALL 调用 `runner/cmd/expect.ts` 中的 `checkExitCode()`
|
||||||
|
|
||||||
|
### Requirement: Checker 接口定义
|
||||||
|
系统 SHALL 在 `src/server/checker/runner/types.ts` 中定义面向扩展的泛型 `CheckerDefinition<TResolved extends ResolvedTargetBase = ResolvedTargetBase>`，包含 `type`、`configKey`、TypeBox 配置契约、启动期语义校验、`resolve`、`execute`、`serialize` 成员。
|
||||||
|
|
||||||
|
#### Scenario: type 与 configKey 默认一致
|
||||||
|
- **WHEN** checker 定义 `type: "cmd"`
|
||||||
|
- **THEN** checker 的 `configKey` SHALL 默认使用 `"cmd"`，对应 target 的 `cmd` 分组和 defaults.cmd 分组
|
||||||
@@ -0,0 +1,33 @@
|
|||||||
|
## MODIFIED Requirements
|
||||||
|
|
||||||
|
### Requirement: command target 配置
|
||||||
|
系统 SHALL 支持 `type: cmd` 的 target 配置，通过 `cmd.exec` 和 `cmd.args` 描述本地命令，并使用 cmd 专用字段配置工作目录、环境变量和输出限制。
|
||||||
|
|
||||||
|
#### Scenario: 解析 cmd target
|
||||||
|
- **WHEN** YAML 中 target 配置 `type: cmd`、`cmd.exec: "pgrep"` 和 `cmd.args: ["nginx"]`
|
||||||
|
- **THEN** 系统 SHALL 将其解析为 cmd checker，并保留 exec、args、cwd、env、maxOutputBytes、interval、timeout 和 expect 配置
|
||||||
|
|
||||||
|
#### Scenario: cmd target 缺少 exec
|
||||||
|
- **WHEN** YAML 中 target 配置 `type: cmd` 但缺少 `cmd.exec`
|
||||||
|
- **THEN** 系统 SHALL 以配置错误退出，并提示该 target 缺少 cmd.exec 字段
|
||||||
|
|
||||||
|
#### Scenario: cwd 相对配置文件目录解析
|
||||||
|
- **WHEN** cmd target 配置 `cmd.cwd: "scripts"` 且配置文件位于 `/opt/checker/probes.yaml`
|
||||||
|
- **THEN** 系统 SHALL 将 cwd 解析为 `/opt/checker/scripts`
|
||||||
|
|
||||||
|
#### Scenario: cmd 不使用 shell
|
||||||
|
- **WHEN** cmd target 配置 `exec` 和 `args`
|
||||||
|
- **THEN** 系统 MUST 直接执行该程序和参数，不通过 shell 解释整段命令字符串
|
||||||
|
|
||||||
|
#### Scenario: env 默认继承并允许覆盖
|
||||||
|
- **WHEN** cmd target 配置 `cmd.env: {LANG: "C"}` 且当前进程环境包含 `PATH`
|
||||||
|
- **THEN** 系统 SHALL 继承当前进程的全部环境变量，并将 `LANG` 覆盖为 `"C"`
|
||||||
|
|
||||||
|
### Requirement: command checker 执行
|
||||||
|
系统 SHALL 按 cmd target 配置执行本地命令，记录执行耗时、退出码、stdout 和 stderr，并在执行失败时产生结构化错误信息。
|
||||||
|
|
||||||
|
### Requirement: command expect 校验
|
||||||
|
系统 SHALL 支持 cmd 专用 expect，包括 `exitCode`、`stdout` 和 `stderr`，并按 exitCode、duration、stdout、stderr 的阶段顺序快速失败。
|
||||||
|
|
||||||
|
### Requirement: command checker 启动期配置校验
|
||||||
|
系统 SHALL 在启动期对 cmd checker 的配置契约和语义执行严格校验。Cmd target 的 `cmd` 分组 SHALL 只允许 `exec`、`args`、`cwd`、`env`、`maxOutputBytes` 字段；Cmd expect SHALL 只允许 `exitCode`、`maxDurationMs`、`stdout`、`stderr` 字段。未知字段、非法类型和不可编译正则 MUST 导致启动期配置错误。`expect.exitCode` SHALL 保留原有有限整数数组语义，不限制到特定平台范围。
|
||||||
@@ -0,0 +1,25 @@
|
|||||||
|
## MODIFIED Requirements
|
||||||
|
|
||||||
|
### Requirement: YAML 配置文件格式
|
||||||
|
target MUST 使用 `type` 字段声明 checker 类型，HTTP 领域字段 MUST 放在 `http` 分组，cmd 领域字段 MUST 放在 `cmd` 分组。
|
||||||
|
|
||||||
|
#### Scenario: 最简 command 配置文件解析
|
||||||
|
- **WHEN** 系统读取只包含一个 `type: cmd` target 和 `cmd.exec` 的 YAML 配置文件
|
||||||
|
- **THEN** 系统 SHALL 使用内置默认值填充未指定的字段（interval=30s, timeout=10s, cmd.cwd 为配置文件所在目录, cmd.maxOutputBytes=100MB）
|
||||||
|
|
||||||
|
### Requirement: 配置校验
|
||||||
|
|
||||||
|
#### Scenario: command target 缺少 exec
|
||||||
|
- **WHEN** YAML 中某个 target 配置 `type: cmd` 但缺少 `cmd.exec`
|
||||||
|
- **THEN** 系统 SHALL 以错误退出，提示该 target 缺少 cmd.exec 字段
|
||||||
|
|
||||||
|
#### Scenario: 动态 env 字段允许
|
||||||
|
- **WHEN** YAML 中 `cmd.env` 包含任意环境变量名称，且对应值为字符串
|
||||||
|
- **THEN** 系统 SHALL 接受这些动态 env 名称
|
||||||
|
|
||||||
|
### Requirement: expect 配置增强
|
||||||
|
系统 SHALL 支持 typed target 的领域专用 expect 配置，包括 HTTP 的 `status`、`headers`、`body` 和 cmd 的 `exitCode`、`stdout`、`stderr`。
|
||||||
|
|
||||||
|
#### Scenario: 解析 command expect 配置
|
||||||
|
- **WHEN** YAML 配置文件中 cmd target 的 expect 包含 exitCode、stdout 和 stderr 规则数组
|
||||||
|
- **THEN** 系统 SHALL 正确解析并存储为 cmd target 的 expect 字段
|
||||||
@@ -0,0 +1,41 @@
|
|||||||
|
## MODIFIED Requirements
|
||||||
|
|
||||||
|
### Requirement: 命令检测器测试 SHALL 使用跨平台命令
|
||||||
|
命令检测器的测试 SHALL 使用 `bun -e` 脚本替代所有系统命令（包括 `true`、`false`、`sleep`、`bash`、`echo`、`yes | head`），确保测试在 Windows、macOS、Linux 三平台上行为一致。
|
||||||
|
|
||||||
|
#### Scenario: 进程退出码 0
|
||||||
|
- **WHEN** 测试需要一个正常退出的命令
|
||||||
|
- **THEN** 测试 SHALL 使用 `bun -e "process.exit(0)"` 替代 `true`
|
||||||
|
|
||||||
|
#### Scenario: 进程退出码非零
|
||||||
|
- **WHEN** 测试需要一个失败退出的命令
|
||||||
|
- **THEN** 测试 SHALL 使用 `bun -e "process.exit(1)"` 替代 `false`
|
||||||
|
|
||||||
|
#### Scenario: stdout 输出
|
||||||
|
- **WHEN** 测试需要一个输出文本到 stdout 的命令
|
||||||
|
- **THEN** 测试 SHALL 使用 `bun -e "console.log('text')"` 替代 `echo text`
|
||||||
|
|
||||||
|
#### Scenario: stderr 输出
|
||||||
|
- **WHEN** 测试需要一个输出文本到 stderr 的命令
|
||||||
|
- **THEN** 测试 SHALL 使用 `bun -e "process.stderr.write('error\n')"` 替代 `bash -c "echo error >&2"`
|
||||||
|
|
||||||
|
#### Scenario: 长时间运行命令
|
||||||
|
- **WHEN** 测试需要一个超时场景的长时间运行命令
|
||||||
|
- **THEN** 测试 SHALL 使用 `bun -e "await Bun.sleep(10000)"` 替代 `sleep 10`
|
||||||
|
|
||||||
|
#### Scenario: 大量输出
|
||||||
|
- **WHEN** 测试需要一个产生大量输出的命令
|
||||||
|
- **THEN** 测试 SHALL 使用 `bun -e "process.stdout.write('y\n'.repeat(N))"` 替代 `bash -c "yes | head -N"`
|
||||||
|
|
||||||
|
#### Scenario: 验证非 shell 模式下特殊字符不被展开
|
||||||
|
- **WHEN** 通过 `Bun.spawn` 执行 `bun -e "console.log('*')"` 并检查 stdout 包含 `*`
|
||||||
|
- **THEN** 测试 SHALL 在 Windows、macOS 和 Linux 上均返回 `matched: true`
|
||||||
|
|
||||||
|
## ADDED Requirements
|
||||||
|
|
||||||
|
### Requirement: probes.example.yaml 使用跨平台示例
|
||||||
|
probes.example.yaml 中的 cmd 类型示例 SHALL 使用跨平台命令（如 `bun -e "..."`、`bun --version`），不使用 Unix 专属命令（如 `uname`、`ls /tmp`、`date`）。
|
||||||
|
|
||||||
|
#### Scenario: 示例命令跨平台可执行
|
||||||
|
- **WHEN** 用户在 Windows、macOS 或 Linux 上直接使用 probes.example.yaml 中的 cmd 示例
|
||||||
|
- **THEN** 所有 cmd 示例 SHALL 能正常执行，不依赖平台特定命令
|
||||||
27
openspec/changes/cmd-checker-enhancement/tasks.md
Normal file
27
openspec/changes/cmd-checker-enhancement/tasks.md
Normal file
@@ -0,0 +1,27 @@
|
|||||||
|
## 1. 源码目录重命名
|
||||||
|
|
||||||
|
- [ ] 1.1 重命名 `src/server/checker/runner/command/` → `src/server/checker/runner/cmd/`，更新目录内所有文件的 type/configKey 字面量为 `"cmd"`
|
||||||
|
- [ ] 1.2 重命名 `tests/server/checker/runner/command/` → `tests/server/checker/runner/cmd/`
|
||||||
|
- [ ] 1.3 更新所有 import 路径中的 `runner/command` → `runner/cmd`（包括 runner/index.ts 等）
|
||||||
|
|
||||||
|
## 2. 类型与配置重命名
|
||||||
|
|
||||||
|
- [ ] 2.1 更新 `src/server/checker/runner/cmd/execute.ts` 中 `type = "cmd"`、`configKey = "cmd"`、`context.defaults["cmd"]`、所有 `t.command.xxx` → `t.cmd.xxx`
|
||||||
|
- [ ] 2.2 更新 `src/server/checker/runner/cmd/types.ts` 中 `ResolvedCommandTarget.command` 属性名改为 `cmd`、`type: "command"` 改为 `type: "cmd"`
|
||||||
|
- [ ] 2.3 更新 `src/server/checker/runner/cmd/validate.ts` 中所有 `"command"` → `"cmd"` 字面量
|
||||||
|
- [ ] 2.4 更新 `src/server/checker/runner/cmd/schema.ts` 中 TypeBox 契约的分组名（如有 `"command"` 字面量）
|
||||||
|
- [ ] 2.5 更新 `probes.example.yaml` 中 `type: command` → `type: cmd`、`command:` → `cmd:`，示例命令改为跨平台命令
|
||||||
|
- [ ] 2.6 更新 `tests/server/app.test.ts`、`tests/server/bootstrap.test.ts`、`tests/server/checker/config-loader.test.ts`、`tests/server/checker/engine.test.ts` 中所有 `"command"` 字面量为 `"cmd"`
|
||||||
|
- [ ] 2.7 重新生成 `probe-config.schema.json`（执行 schema 生成脚本或手动更新）
|
||||||
|
|
||||||
|
## 3. 跨平台测试改造
|
||||||
|
|
||||||
|
- [ ] 3.1 更新 `tests/server/checker/runner/cmd/runner.test.ts` 中所有系统命令为 `bun -e "..."` 形式
|
||||||
|
- [ ] 3.2 更新 `tests/server/checker/runner/cmd/expect.test.ts` 中所有系统命令为 `bun -e "..."` 形式
|
||||||
|
|
||||||
|
## 4. Spec 文档与质量保障
|
||||||
|
|
||||||
|
- [ ] 4.1 重命名 `openspec/specs/command-checker/` → `openspec/specs/cmd-checker/`，更新 spec 内容中的 `command` → `cmd`
|
||||||
|
- [ ] 4.2 执行完整测试套件 `bun test`，确保所有测试通过
|
||||||
|
- [ ] 4.3 执行类型检查 `bunx tsc --noEmit`，确保无类型错误
|
||||||
|
- [ ] 4.4 更新 README.md 中涉及 command checker 的描述和配置示例（包括 defaults.command 段、type 枚举、配置字段说明）
|
||||||
2
openspec/changes/enhance-frontend-metrics/.openspec.yaml
Normal file
2
openspec/changes/enhance-frontend-metrics/.openspec.yaml
Normal file
@@ -0,0 +1,2 @@
|
|||||||
|
schema: spec-driven
|
||||||
|
created: 2026-05-13
|
||||||
147
openspec/changes/enhance-frontend-metrics/design.md
Normal file
147
openspec/changes/enhance-frontend-metrics/design.md
Normal file
@@ -0,0 +1,147 @@
|
|||||||
|
## Context
|
||||||
|
|
||||||
|
DiAL 是一个基于 Bun 的全栈拨测监控系统，当前前端统计指标体系存在以下问题：
|
||||||
|
|
||||||
|
1. **计算逻辑缺陷**：可用率基于全量历史数据计算（`store.ts:getAllTargetStats` 无 WHERE 时间条件），随运行时间增长近期变化被稀释；`computeTrendStats` 从已截断的百分比反推整数有累积精度损失；`lastCheckTime` 已返回但前端未展示
|
||||||
|
2. **指标维度单一**：Summary 仅 3 个计数卡片；Drawer 统计区 4 个指标（总检查/正常/异常/可用率）本质是同一维度的冗余表达
|
||||||
|
3. **缺少关键运维指标**：无 P95 延迟、无 MTTR、无故障分析、无连续状态信息
|
||||||
|
|
||||||
|
当前技术栈：后端 Bun + SQLite（bun:sqlite），前端 React + TDesign + recharts + TanStack Query。
|
||||||
|
|
||||||
|
## Goals / Non-Goals
|
||||||
|
|
||||||
|
**Goals:**
|
||||||
|
- 修复可用率时间窗口、趋势数据精度损失、lastCheckTime 未展示三个计算逻辑问题
|
||||||
|
- Summary 增加「24h 异常事件数」卡片
|
||||||
|
- 表格增加「连续状态」列（Tag 样式，按次数）
|
||||||
|
- Drawer 统计区重构为 2×4 多维度布局（可用率/平均延迟/P95/检查总数 + MTTR/最长故障/故障次数/连续正常）
|
||||||
|
- 趋势图增加延迟范围面积（min/max），去掉可用率线改为异常时刻红色标记点
|
||||||
|
- 新增 `/api/targets/:id/stats` 端点，职责清晰（单目标非时序聚合指标）
|
||||||
|
- Drawer 统计区支持时间窗口切换（24h/7d/30d），联动统计+趋势
|
||||||
|
|
||||||
|
**Non-Goals:**
|
||||||
|
- 不做整体可用率（不同分组不同目的的 target 算到一起无意义）
|
||||||
|
- 不做延迟 sparkline（表格已有状态条，信息密度够了）
|
||||||
|
- 不做趋势对比（vs 上周）
|
||||||
|
- 不做连续状态按时长展示（不同间隔的目标无法统一）
|
||||||
|
|
||||||
|
## Decisions
|
||||||
|
|
||||||
|
### Decision 1：P95 在应用层计算，不在 SQL 层
|
||||||
|
|
||||||
|
**选择**：新增 `getTargetDurations(targetId, from, to)` 方法，一次性取出时间窗口内所有成功检查的 `duration_ms`，在 TypeScript 层排序取 P95/P99。
|
||||||
|
|
||||||
|
**理由**：SQLite 无原生 PERCENTILE 函数，用子查询模拟的 SQL 复杂且性能不可控。应用层排序对于单目标时间窗口内的数据量（24h × 每分钟 1 次 = 1440 条）完全可接受。
|
||||||
|
|
||||||
|
**替代方案**：SQLite 扩展函数 / 窗口函数模拟 — 复杂度高，可移植性差。
|
||||||
|
|
||||||
|
**命名**：方法名统一为 `getTargetDurations`（非 `getTargetPercentiles`），因为该方法职责是取原始数据，百分位计算在调用方完成。
|
||||||
|
|
||||||
|
### Decision 2：新增独立 `/api/targets/:id/stats` 端点
|
||||||
|
|
||||||
|
**选择**：创建新端点而非扩展现有 `/api/targets/:id/trend`。
|
||||||
|
|
||||||
|
**理由**：
|
||||||
|
- `/trend` 的职责是时序聚合数据（按小时分组），返回数组
|
||||||
|
- `/stats` 的职责是非时序聚合指标（P95、MTTR、故障分析），返回单个对象
|
||||||
|
- 两者语义清晰，避免一个大而全的端点
|
||||||
|
- `/stats` 只在 Drawer 打开时请求，不影响列表页性能
|
||||||
|
|
||||||
|
**替代方案**：扩展 `/trend` 在响应中附加 summary 字段 — 混淆了时序和聚合两种数据语义。
|
||||||
|
|
||||||
|
### Decision 3：异常事件数按「状态翻转」计数
|
||||||
|
|
||||||
|
**选择**：统计 `matched` 从 1→0 的转换次数（跨所有目标），而非每次 `matched=0` 的检查次数。
|
||||||
|
|
||||||
|
**理由**：一个目标连续异常 10 次只算 1 次事件，反映的是「发生了几次故障」而非「有多少次检查失败」。后者已经在可用率中体现。
|
||||||
|
|
||||||
|
**实现**：SQL 使用 LAG 窗口函数检测前后状态变化：
|
||||||
|
```sql
|
||||||
|
SELECT COUNT(*) FROM (
|
||||||
|
SELECT matched, LAG(matched) OVER (PARTITION BY target_id ORDER BY timestamp) as prev
|
||||||
|
FROM check_results WHERE timestamp >= ?
|
||||||
|
) WHERE matched = 0 AND (prev = 1 OR prev IS NULL)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Decision 4：连续状态从 recentSamples 前端计算
|
||||||
|
|
||||||
|
**选择**：不新增 API，从已有的 `recentSamples`（30 条）在前端计算连续状态次数。
|
||||||
|
|
||||||
|
**理由**：
|
||||||
|
- `recentSamples` 已经按时间倒序返回，遍历到第一个状态不同的即可
|
||||||
|
- 无需额外网络请求
|
||||||
|
- 30 条样本对于连续状态计数足够（超过 30 次连续正常/异常的场景下，显示 "30+" 即可）
|
||||||
|
|
||||||
|
### Decision 5：趋势图去掉可用率线，改为异常标记点
|
||||||
|
|
||||||
|
**选择**：移除 availability 折线和右侧 Y 轴（%），改为单 Y 轴（ms）。在 avgDurationMs 线上，对 availability < 100 的时间点渲染红色 dot 标记异常。
|
||||||
|
|
||||||
|
**理由**：可用率通常是 100% 或接近 100%，作为连续曲线信息量极低（大部分时间是一条直线）。改为离散标记点后，异常时刻一目了然，且不占用 Y 轴空间。
|
||||||
|
|
||||||
|
**实现**：使用 recharts `<Line>` 的 `dot` 回调函数，对 `availability < 100` 的点渲染红色圆点（`fill: var(--td-error-color)`），其余点不渲染 dot。移除右侧 Y 轴和 availability Line 组件。
|
||||||
|
|
||||||
|
### Decision 6：时间窗口切换联动机制
|
||||||
|
|
||||||
|
**选择**：Drawer 中的时间窗口切换同时影响统计区和趋势图，stats 和 trend 同时刷新。
|
||||||
|
|
||||||
|
**实现**：
|
||||||
|
- stats 请求直接复用 Drawer 现有的 `timeFrom`/`timeTo` 状态，不引入额外时间状态
|
||||||
|
- 统计区数据来自 `/api/targets/:id/stats?from=&to=`
|
||||||
|
- 趋势图数据来自 `/api/targets/:id/trend?from=&to=`
|
||||||
|
- 切换快捷按钮（1h/6h/24h/7d）时，`timeFrom`/`timeTo` 更新，stats 和 trend 的 queryKey 变化触发同时刷新
|
||||||
|
- 默认选中 24h
|
||||||
|
- 表格的可用率固定 24h 窗口：前端 `useTargets` 请求 `/api/targets?window=24h`，后端解析 `window` 查询参数并转换为时间范围传递给 `getAllTargetStats(from, to)`，列标题改为"可用率(24h)"
|
||||||
|
|
||||||
|
### Decision 7：Drawer 统计区 2×4 布局
|
||||||
|
|
||||||
|
**选择**：统计区和可靠性区合并为一个 2 行 × 4 列的 Statistic 网格。
|
||||||
|
|
||||||
|
```
|
||||||
|
┌────────────┬────────────┬────────────┬────────────┐
|
||||||
|
│ 可用率 │ 平均延迟 │ P95延迟 │ 检查总数 │
|
||||||
|
├────────────┼────────────┼────────────┼────────────┤
|
||||||
|
│ MTTR │ 最长故障 │ 故障次数 │ 连续正常 │
|
||||||
|
└────────────┴────────────┴────────────┴────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
**理由**：原来的「总检查/正常/异常/可用率」4 指标信息冗余，正常/异常计数已在环形图中展示。重构后每个格子都是独立维度，信息密度大幅提升。
|
||||||
|
|
||||||
|
### Decision 8：TrendPoint 增加 min/max 延迟字段
|
||||||
|
|
||||||
|
**选择**：在 SQL 聚合层直接计算 `MIN(duration_ms)` 和 `MAX(duration_ms)`，零额外成本。
|
||||||
|
|
||||||
|
**实现**：趋势图使用 recharts `<Area>` 组件渲染 min-max 范围（半透明品牌色填充），叠加 avg 实线。
|
||||||
|
|
||||||
|
### Decision 9：Summary lastCheckTime 展示为相对时间
|
||||||
|
|
||||||
|
**选择**：在 Summary 区域底部展示 "最后更新: X秒前" 文本，前端每秒更新。
|
||||||
|
|
||||||
|
**实现**：使用 `useState` + `setInterval` 每秒计算相对时间差。超过 60 秒时文字变为警告色（--td-warning-color），提示数据可能不新鲜。
|
||||||
|
|
||||||
|
### Decision 10：StatusDonut 数据来源改为 statsData
|
||||||
|
|
||||||
|
**选择**：StatusDonut 的 `up`/`down` 改为使用 `statsData.upChecks` / `statsData.downChecks`，不再从 trendData 反推。
|
||||||
|
|
||||||
|
**理由**：statsData 的 upChecks 是精确值（直接从 SQL COUNT 返回），与统计区的"检查总数"一致，消除了之前从百分比反推的精度损失。
|
||||||
|
|
||||||
|
**影响**：`computeTrendStats` 工具函数不再有调用方，直接删除。
|
||||||
|
|
||||||
|
### Decision 11：MTTR 窗口边界截断处理
|
||||||
|
|
||||||
|
**选择**：如果时间窗口内第一条记录即为 matched=0（故障跨越了 from 边界），该故障段不计入 MTTR 平均值，但计入 incidentCount。
|
||||||
|
|
||||||
|
**理由**：无法确定故障的真实开始时间，计入 MTTR 会低估实际恢复时间。incidentCount 计数是因为用户确实在窗口内经历了这次故障。
|
||||||
|
|
||||||
|
### Decision 12：getIncidents24h 作为独立方法
|
||||||
|
|
||||||
|
**选择**：`getIncidents24h()` 是 ProbeStore 的独立方法（单条 SQL），在 `handleSummary` 路由中调用并附加到响应。
|
||||||
|
|
||||||
|
**理由**：职责分离，getSummary() 保持原有的目标状态快照逻辑，incidents24h 是独立的时序分析查询。
|
||||||
|
|
||||||
|
## Risks / Trade-offs
|
||||||
|
|
||||||
|
- **[P95 数据量]** 30d 窗口下单目标可能有 ~43200 条记录需要排序 → 对于内存排序仍然可接受（<1MB），但如果未来数据量增长可考虑近似算法
|
||||||
|
- **[异常事件计数的 LAG 查询]** 窗口函数在大数据量下可能较慢 → 24h 窗口内数据量有限（所有目标 × 24h ÷ 间隔），可接受；如果性能不佳可改为应用层遍历
|
||||||
|
- **[前端连续状态上限 30]** recentSamples 固定 30 条，连续状态超过 30 次时显示 "30+" → 对于运维场景足够，真正需要精确值时可查看 Drawer 详情
|
||||||
|
- **[趋势图去掉可用率线]** 用户可能习惯看可用率曲线 → 异常标记点提供了等价信息且更直观，环形图仍展示可用率分布
|
||||||
|
- **[LAG 窗口边界误差]** 使用 LAG 窗口函数检测状态翻转时，若故障跨越时间窗口 from 边界（窗口内第一条即为 matched=0），会被计为一次新事件，实际可能是窗口外已开始的故障延续 → 对于 24h 窗口内的事件计数，该误差可接受且难以避免（需要额外查询窗口外数据才能消除）
|
||||||
33
openspec/changes/enhance-frontend-metrics/proposal.md
Normal file
33
openspec/changes/enhance-frontend-metrics/proposal.md
Normal file
@@ -0,0 +1,33 @@
|
|||||||
|
## Why
|
||||||
|
|
||||||
|
当前前端统计指标存在三个层面的问题：（1）计算逻辑缺陷——可用率无时间窗口导致历史数据稀释近期变化、`computeTrendStats` 从百分比反推整数有精度损失、`lastCheckTime` 返回但未展示；（2）指标维度单一——Summary 只有计数、Drawer 统计区 4 个指标本质是同一维度的重复表达、表格缺少连续状态等关键运维信息；（3）缺少性能和可靠性指标——无 P95 延迟、无 MTTR、无故障分析。
|
||||||
|
|
||||||
|
## What Changes
|
||||||
|
|
||||||
|
- **计算逻辑修复**：可用率查询增加时间窗口参数（默认 24h）；Trend API 直接返回 `upChecks` 消除前端反推精度损失；Summary 展示 `lastCheckTime` 相对时间
|
||||||
|
- **Summary 增强**：新增第 4 张卡片「24h 异常事件数」（状态翻转计数）
|
||||||
|
- **表格增强**：新增「连续状态」列，Tag 样式展示连续正常/异常次数
|
||||||
|
- **Drawer 统计区重构**：从冗余的 4 指标改为多维度布局（可用率 / 平均延迟 / P95 延迟 / 检查总数），支持时间窗口切换（24h/7d/30d）联动
|
||||||
|
- **Drawer 可靠性区块**：新增 MTTR / 最长故障 / 故障次数 / 连续正常 4 个指标，与统计区合并为 2×4 布局
|
||||||
|
- **趋势图增强**：增加延迟范围面积图（min/max），去掉可用率线改为异常时刻红色标记点
|
||||||
|
- **新增 Stats API**：`GET /api/targets/:id/stats` 端点，返回 P95（应用层排序计算）、MTTR、故障分析等深度统计
|
||||||
|
|
||||||
|
## Capabilities
|
||||||
|
|
||||||
|
### New Capabilities
|
||||||
|
- `target-stats-api`: 单目标深度统计 API 端点，提供 P95/P99 延迟、MTTR、故障分析等非时序聚合指标
|
||||||
|
|
||||||
|
### Modified Capabilities
|
||||||
|
- `probe-api`: Summary API 增加 `incidents24h` 字段；Targets API 可用率改为固定 24h 窗口；Trend API 增加 `upChecks`/`minDurationMs`/`maxDurationMs` 字段
|
||||||
|
- `probe-data-store`: `getAllTargetStats`/`getTargetStats` 增加时间窗口参数；`getTrend` 增加 min/max 聚合；新增异常事件计数和检查序列查询方法
|
||||||
|
- `probe-dashboard`: Summary Cards 从 3 张扩展为 4 张，增加 `lastCheckTime` 展示
|
||||||
|
- `target-table`: 新增「连续状态」列（Tag 样式），可用率列标题改为"可用率(24h)"
|
||||||
|
- `target-detail-drawer`: 概览面板统计区重构为 2×4 多维度布局，趋势图改为延迟范围面积图+异常标记点，删除 computeTrendStats，StatusDonut 数据来源改为 statsData
|
||||||
|
|
||||||
|
## Impact
|
||||||
|
|
||||||
|
- **后端**：`src/server/checker/store.ts` 增加带时间窗口的查询方法和新统计方法；新增 `src/server/routes/stats.ts` 路由
|
||||||
|
- **共享类型**：`src/shared/api.ts` 扩展 `SummaryResponse`、`TargetStatus`、`TrendPoint`，新增 `TargetStatsResponse` 类型
|
||||||
|
- **前端组件**：`SummaryCards`、`OverviewTab`、`TrendChart`、`target-table-columns` 均需修改；新增连续状态 Tag 组件
|
||||||
|
- **前端工具**：`utils/stats.ts` 的 `computeTrendStats` 删除（不再有调用方）
|
||||||
|
- **API 端点**：新增 `/api/targets/:id/stats`；修改 `/api/summary`、`/api/targets`、`/api/targets/:id/trend` 的响应结构
|
||||||
@@ -0,0 +1,53 @@
|
|||||||
|
## MODIFIED Requirements
|
||||||
|
|
||||||
|
### Requirement: 总览统计 API
|
||||||
|
系统 SHALL 提供 `GET /api/summary` 端点，返回所有目标的总体统计信息，包含异常事件计数。
|
||||||
|
|
||||||
|
#### Scenario: 获取总览统计
|
||||||
|
- **WHEN** 客户端请求 `GET /api/summary`
|
||||||
|
- **THEN** 系统 SHALL 返回 JSON 包含 total（总目标数）、up（正常数）、down（异常数）、lastCheckTime（最近一次检查时间）、incidents24h（过去 24 小时内的异常事件数，按状态翻转计数）
|
||||||
|
|
||||||
|
#### Scenario: 异常事件计数逻辑
|
||||||
|
- **WHEN** 计算 incidents24h
|
||||||
|
- **THEN** 系统 SHALL 统计过去 24 小时内所有目标中 matched 从 1 变为 0 的状态翻转次数；时间窗口起始即为 matched=0 且无前序记录的情况 SHALL 计为 1 次事件
|
||||||
|
|
||||||
|
### Requirement: 目标列表 API
|
||||||
|
系统 SHALL 提供 `GET /api/targets` 端点，返回所有 typed target 及其最新状态、分组信息和结构化采样数据，可用率基于 window 查询参数指定的时间窗口计算。
|
||||||
|
|
||||||
|
#### Scenario: 获取目标列表
|
||||||
|
- **WHEN** 客户端请求 `GET /api/targets?window=24h`
|
||||||
|
- **THEN** 系统 SHALL 解析 window 参数（支持格式如 "24h"、"7d"），将其转换为时间范围，返回 JSON 数组，每个元素的 stats.availability 和 stats.totalChecks SHALL 基于该时间窗口的数据计算
|
||||||
|
|
||||||
|
#### Scenario: window 参数缺失
|
||||||
|
- **WHEN** 客户端请求 `GET /api/targets` 未提供 window 参数
|
||||||
|
- **THEN** 系统 SHALL 默认使用 24h 时间窗口
|
||||||
|
|
||||||
|
#### Scenario: 目标无历史记录
|
||||||
|
- **WHEN** 某目标尚未执行过任何拨测
|
||||||
|
- **THEN** 其 latestCheck 为 null，recentSamples 为空数组，stats.availability 为 0
|
||||||
|
|
||||||
|
### Requirement: 趋势 API 支持时间范围
|
||||||
|
系统 SHALL 提供 `GET /api/targets/:id/trend` 端点，返回包含延迟范围和正常检查数的趋势数据。
|
||||||
|
|
||||||
|
#### Scenario: 指定时间范围查询趋势
|
||||||
|
- **WHEN** 客户端请求 `GET /api/targets/1/trend?from=ISO&to=ISO`
|
||||||
|
- **THEN** 系统 SHALL 返回指定时间范围内按小时分组的聚合数据，每个数据点包含 hour、avgDurationMs、minDurationMs、maxDurationMs、availability、totalChecks、upChecks
|
||||||
|
|
||||||
|
#### Scenario: from 或 to 参数缺失
|
||||||
|
- **WHEN** 客户端请求 `GET /api/targets/1/trend` 未提供 from 或 to 参数
|
||||||
|
- **THEN** 系统 SHALL 返回 400 状态码和错误信息
|
||||||
|
|
||||||
|
### Requirement: 新增共享类型
|
||||||
|
系统 SHALL 在 `src/shared/api.ts` 中定义扩展后的 `SummaryResponse`、`TrendPoint` 和 `TargetStats` 类型。
|
||||||
|
|
||||||
|
#### Scenario: SummaryResponse 类型
|
||||||
|
- **WHEN** 前后端共享 `SummaryResponse` 类型
|
||||||
|
- **THEN** 该类型 SHALL 包含 `total: number`、`up: number`、`down: number`、`lastCheckTime: string | null`、`incidents24h: number` 字段
|
||||||
|
|
||||||
|
#### Scenario: TrendPoint 类型
|
||||||
|
- **WHEN** 前后端共享 `TrendPoint` 类型
|
||||||
|
- **THEN** 该类型 SHALL 包含 `hour: string`、`avgDurationMs: number | null`、`minDurationMs: number | null`、`maxDurationMs: number | null`、`availability: number`、`totalChecks: number`、`upChecks: number` 字段
|
||||||
|
|
||||||
|
#### Scenario: TargetStats 类型
|
||||||
|
- **WHEN** 前后端共享 `TargetStats` 类型
|
||||||
|
- **THEN** 该类型 SHALL 包含 `availability: number`、`totalChecks: number` 字段（语义变更为基于时间窗口计算）
|
||||||
@@ -0,0 +1,20 @@
|
|||||||
|
## MODIFIED Requirements
|
||||||
|
|
||||||
|
### Requirement: 总览统计卡片
|
||||||
|
Dashboard SHALL 在页面顶部使用 TDesign Statistic 组件展示总览统计，包含总目标数、正常数、异常数和 24h 异常事件数，并展示数据新鲜度。
|
||||||
|
|
||||||
|
#### Scenario: 展示统计卡片
|
||||||
|
- **WHEN** 用户打开 Dashboard 页面
|
||||||
|
- **THEN** 页面顶部 SHALL 使用 TDesign Row/Col 布局展示 4 个 TDesign Card + Statistic 组合：全部目标数（color=blue）、正常目标数（color=green）、异常目标数（color=red）、24h 异常事件数（color=orange）
|
||||||
|
|
||||||
|
#### Scenario: 展示数据新鲜度
|
||||||
|
- **WHEN** Summary 数据包含 lastCheckTime
|
||||||
|
- **THEN** 统计卡片行底部 SHALL 展示相对时间文本（如"最后更新: 3秒前"），使用 TDesign Typography.Text（theme="secondary"）
|
||||||
|
|
||||||
|
#### Scenario: 数据新鲜度警告
|
||||||
|
- **WHEN** lastCheckTime 距当前时间超过 60 秒
|
||||||
|
- **THEN** 相对时间文本 SHALL 使用警告色（--td-warning-color）
|
||||||
|
|
||||||
|
#### Scenario: 统计数据自动刷新
|
||||||
|
- **WHEN** 页面处于打开状态
|
||||||
|
- **THEN** 统计卡片 SHALL 通过 TanStack Query 的 refetchInterval=8000 自动刷新数据
|
||||||
@@ -0,0 +1,80 @@
|
|||||||
|
## MODIFIED Requirements
|
||||||
|
|
||||||
|
### Requirement: 聚合查询支持
|
||||||
|
数据存储 SHALL 支持按时间段聚合查询，用于计算可用率、平均耗时、延迟范围等统计指标。所有聚合查询 SHALL 支持时间窗口参数。
|
||||||
|
|
||||||
|
#### Scenario: 计算目标可用率（带时间窗口）
|
||||||
|
- **WHEN** 查询某目标在指定时间范围内的可用率
|
||||||
|
- **THEN** 系统 SHALL 返回该时间范围内 matched=1 的记录数占总记录数的百分比
|
||||||
|
|
||||||
|
#### Scenario: 计算目标平均耗时
|
||||||
|
- **WHEN** 查询某目标在指定时间范围内的平均耗时
|
||||||
|
- **THEN** 系统 SHALL 返回 duration_ms 的平均值（仅计算 matched=1 的记录）
|
||||||
|
|
||||||
|
#### Scenario: 按小时聚合趋势数据（含延迟范围）
|
||||||
|
- **WHEN** 查询某目标在指定时间范围内的趋势数据
|
||||||
|
- **THEN** 系统 SHALL 返回按小时分组的聚合数据，包括每小时的 avgDurationMs、minDurationMs（成功检查的最小延迟）、maxDurationMs（成功检查的最大延迟）、availability、totalChecks、upChecks
|
||||||
|
|
||||||
|
#### Scenario: UP/DOWN 判定
|
||||||
|
- **THEN** 系统 SHALL 基于 latestCheck.matched 判定目标 UP 或 DOWN：matched=true 为 UP，matched=false 为 DOWN
|
||||||
|
|
||||||
|
### Requirement: 目标统计查询支持时间窗口
|
||||||
|
`getAllTargetStats` 和 `getTargetStats` SHALL 接受可选的时间窗口参数，限制聚合的数据范围。
|
||||||
|
|
||||||
|
#### Scenario: 带时间窗口的批量统计
|
||||||
|
- **WHEN** 调用 `getAllTargetStats(from, to)`
|
||||||
|
- **THEN** 系统 SHALL 仅聚合 timestamp 在 from 到 to 范围内的 check_results 记录
|
||||||
|
|
||||||
|
#### Scenario: 不传时间窗口
|
||||||
|
- **WHEN** 调用 `getAllTargetStats()` 不传时间参数
|
||||||
|
- **THEN** 系统 SHALL 默认使用过去 24 小时作为时间窗口
|
||||||
|
|
||||||
|
#### Scenario: 带时间窗口的单目标统计
|
||||||
|
- **WHEN** 调用 `getTargetStats(targetId, from, to)`
|
||||||
|
- **THEN** 系统 SHALL 仅聚合指定时间范围内的记录
|
||||||
|
|
||||||
|
### Requirement: 趋势数据时间范围查询
|
||||||
|
系统 SHALL 支持按任意时间范围查询趋势聚合数据，返回包含延迟范围和正常检查数的完整聚合。
|
||||||
|
|
||||||
|
#### Scenario: 按时间范围查询趋势（含延迟范围）
|
||||||
|
- **WHEN** 查询指定 target 在 from 到 to 时间范围内的趋势数据
|
||||||
|
- **THEN** 系统 SHALL 返回按小时分组的聚合数据，每个数据点包含 hour、avgDurationMs、minDurationMs、maxDurationMs、availability、totalChecks、upChecks
|
||||||
|
|
||||||
|
## ADDED Requirements
|
||||||
|
|
||||||
|
### Requirement: 异常事件计数查询
|
||||||
|
ProbeStore SHALL 提供 `getIncidents24h()` 方法，统计过去 24 小时内所有目标的异常事件数。
|
||||||
|
|
||||||
|
#### Scenario: 计算异常事件数
|
||||||
|
- **WHEN** 调用 `getIncidents24h()`
|
||||||
|
- **THEN** 系统 SHALL 统计过去 24 小时内所有目标中 matched 从 1 变为 0 的状态翻转次数
|
||||||
|
|
||||||
|
#### Scenario: 窗口起始即为故障
|
||||||
|
- **WHEN** 某目标在 24 小时窗口内第一条记录为 matched=0 且窗口前无记录
|
||||||
|
- **THEN** 该故障 SHALL 计为 1 次事件
|
||||||
|
|
||||||
|
#### Scenario: 连续异常只计一次
|
||||||
|
- **WHEN** 某目标连续 10 次 matched=0
|
||||||
|
- **THEN** 该连续异常段 SHALL 仅计为 1 次事件
|
||||||
|
|
||||||
|
### Requirement: 目标延迟百分位查询
|
||||||
|
ProbeStore SHALL 提供 `getTargetDurations(targetId, from, to)` 方法，返回时间窗口内所有成功检查的 duration_ms 数组。
|
||||||
|
|
||||||
|
#### Scenario: 获取延迟数据
|
||||||
|
- **WHEN** 调用 `getTargetDurations(targetId, from, to)`
|
||||||
|
- **THEN** 系统 SHALL 返回该目标在时间范围内所有 matched=1 的 duration_ms 值数组，按升序排列
|
||||||
|
|
||||||
|
#### Scenario: 无成功检查
|
||||||
|
- **WHEN** 时间窗口内无 matched=1 的记录
|
||||||
|
- **THEN** 系统 SHALL 返回空数组
|
||||||
|
|
||||||
|
### Requirement: 目标故障段查询
|
||||||
|
ProbeStore SHALL 提供 `getCheckSequence(targetId, from, to)` 方法，返回时间窗口内的检查序列用于故障分析。
|
||||||
|
|
||||||
|
#### Scenario: 获取检查序列
|
||||||
|
- **WHEN** 调用 `getCheckSequence(targetId, from, to)`
|
||||||
|
- **THEN** 系统 SHALL 返回该目标在时间范围内所有检查记录的 `{ timestamp: string, matched: number }` 数组，按 timestamp 升序排列
|
||||||
|
|
||||||
|
#### Scenario: 无检查记录
|
||||||
|
- **WHEN** 时间窗口内无记录
|
||||||
|
- **THEN** 系统 SHALL 返回空数组
|
||||||
@@ -0,0 +1,111 @@
|
|||||||
|
## MODIFIED Requirements
|
||||||
|
|
||||||
|
### Requirement: 概览面板组件化
|
||||||
|
概览 Tab SHALL 作为独立组件 `OverviewTab` 实现，展示多维度统计、趋势图、状态分布和基本信息。
|
||||||
|
|
||||||
|
#### Scenario: OverviewTab 组件职责
|
||||||
|
- **WHEN** 概览 Tab 渲染
|
||||||
|
- **THEN** `OverviewTab` 组件 SHALL 负责多维度统计卡片（2×4 布局）、趋势图（延迟范围面积图+异常标记点）、状态分布环形图和基本信息的渲染
|
||||||
|
|
||||||
|
#### Scenario: 统计计算不再使用 computeTrendStats
|
||||||
|
- **WHEN** OverviewTab 需要 totalChecks、upChecks、downChecks
|
||||||
|
- **THEN** SHALL 直接使用 statsData 中的 totalChecks、upChecks、downChecks 字段，`computeTrendStats` 工具函数 SHALL 被删除
|
||||||
|
|
||||||
|
#### Scenario: OverviewTab props
|
||||||
|
- **WHEN** OverviewTab 渲染
|
||||||
|
- **THEN** 组件 SHALL 接收 `target: TargetStatus`、`trendData: TrendPoint[]`、`trendLoading: boolean`、`statsData: TargetStatsResponse | null`、`statsLoading: boolean` 作为 props
|
||||||
|
|
||||||
|
### Requirement: 概览面板
|
||||||
|
概览 Tab SHALL 按区域展示多维度统计、趋势图、状态分布和基本信息。
|
||||||
|
|
||||||
|
#### Scenario: 区域排列顺序
|
||||||
|
- **WHEN** 概览面板渲染
|
||||||
|
- **THEN** 面板 SHALL 按以下顺序展示区域：统计 → 趋势 → 状态分布 → 基本信息，每个区域前 SHALL 显示 TDesign Divider（align="left"）作为小标题
|
||||||
|
|
||||||
|
#### Scenario: 统计区多维度布局
|
||||||
|
- **WHEN** 概览面板渲染
|
||||||
|
- **THEN** 面板 SHALL 在"统计"区域使用 2 行 × 4 列的 TDesign Row/Col + Statistic 布局：第一行为可用率（suffix="%"）、平均延迟（suffix="ms"）、P95 延迟（suffix="ms"）、检查总数；第二行为 MTTR（动态单位）、最长故障（动态单位）、故障次数（suffix="次"）、连续正常（suffix="次"，固定标题"连续正常"，当目标当前处于异常状态时值为 0）
|
||||||
|
|
||||||
|
#### Scenario: MTTR 和最长故障动态单位
|
||||||
|
- **WHEN** MTTR 或最长故障值小于 60000ms
|
||||||
|
- **THEN** SHALL 以秒为单位展示（suffix="秒"）
|
||||||
|
- **WHEN** 值大于等于 60000ms 且小于 3600000ms
|
||||||
|
- **THEN** SHALL 以分钟为单位展示（suffix="分钟"）
|
||||||
|
- **WHEN** 值大于等于 3600000ms
|
||||||
|
- **THEN** SHALL 以小时为单位展示（suffix="小时"）
|
||||||
|
|
||||||
|
#### Scenario: 统计区数据来源
|
||||||
|
- **WHEN** 统计区渲染
|
||||||
|
- **THEN** 第一行数据 SHALL 来自 statsData（TargetStatsResponse），第二行数据同样来自 statsData
|
||||||
|
|
||||||
|
#### Scenario: 统计区加载状态
|
||||||
|
- **WHEN** statsData 正在加载
|
||||||
|
- **THEN** 统计区 SHALL 显示 TDesign Skeleton 加载占位
|
||||||
|
|
||||||
|
#### Scenario: 趋势图延迟范围面积
|
||||||
|
- **WHEN** 概览面板渲染且趋势数据可用
|
||||||
|
- **THEN** 趋势图 SHALL 使用 recharts Area 组件渲染 minDurationMs 到 maxDurationMs 的延迟范围（半透明品牌色填充），叠加 avgDurationMs 实线
|
||||||
|
|
||||||
|
#### Scenario: 趋势图异常标记点
|
||||||
|
- **WHEN** 趋势数据中某小时的 availability < 100
|
||||||
|
- **THEN** 趋势图 SHALL 在 avgDurationMs 线上该时间点渲染红色圆点（fill: var(--td-error-color)），使用 recharts Line 的 dot 回调函数实现；图表 SHALL 仅保留左侧 Y 轴（ms），移除右侧 Y 轴（%）和 availability 折线
|
||||||
|
|
||||||
|
#### Scenario: 趋势数据加载中
|
||||||
|
- **WHEN** 概览面板渲染且趋势数据正在加载
|
||||||
|
- **THEN** "趋势"区域 SHALL 显示 TDesign Skeleton 加载占位
|
||||||
|
|
||||||
|
#### Scenario: 状态分布环形图
|
||||||
|
- **WHEN** 概览面板渲染且 statsData 可用
|
||||||
|
- **THEN** 面板 SHALL 在"状态分布"区域展示 recharts 环形图（StatusDonut），使用 statsData.upChecks 和 statsData.downChecks 作为数据源，外圈显示 UP/DOWN 比例，中间显示可用率百分比
|
||||||
|
|
||||||
|
#### Scenario: 状态分布加载状态
|
||||||
|
- **WHEN** statsData 正在加载
|
||||||
|
- **THEN** 状态分布区域 SHALL 显示 TDesign Skeleton 加载占位
|
||||||
|
|
||||||
|
#### Scenario: 元信息展示
|
||||||
|
- **WHEN** 概览面板渲染
|
||||||
|
- **THEN** 面板 SHALL 在"基本信息"区域使用 TDesign Descriptions 组件展示目标元信息：目标地址、检查间隔、最新检查时间、状态详情
|
||||||
|
|
||||||
|
### Requirement: 时间范围选择器
|
||||||
|
Drawer SHALL 在 Tabs 外层提供时间范围选择器，影响概览和记录两个面板的数据。时间选择器 SHALL 分两行显示：第一行为快捷按钮，第二行为日期时间范围选择器。
|
||||||
|
|
||||||
|
#### Scenario: 快捷时间按钮
|
||||||
|
- **WHEN** Drawer 渲染
|
||||||
|
- **THEN** 时间选择区第一行 SHALL 显示 TDesign RadioGroup（variant=default-filled）快捷按钮：1小时、6小时、24小时、7天
|
||||||
|
|
||||||
|
#### Scenario: 点击快捷按钮
|
||||||
|
- **WHEN** 用户点击快捷按钮（如 "24小时"）
|
||||||
|
- **THEN** 系统 SHALL 自动设置对应的起止时间，DateRangePicker 显示对应的时间范围，该按钮高亮
|
||||||
|
|
||||||
|
#### Scenario: 快捷按钮联动统计区
|
||||||
|
- **WHEN** 用户点击 1小时/6小时/24小时/7天 快捷按钮
|
||||||
|
- **THEN** 统计区和趋势图 SHALL 使用对应的时间窗口重新请求 `/api/targets/:id/stats` 和 `/api/targets/:id/trend` 数据
|
||||||
|
|
||||||
|
#### Scenario: 自定义日期时间范围
|
||||||
|
- **WHEN** 用户通过 TDesign DateRangePicker（mode=date, enableTimePicker, format="YYYY-MM-DD HH:mm"）修改时间范围
|
||||||
|
- **THEN** 快捷按钮 SHALL 取消高亮，系统重新请求对应时间范围的数据
|
||||||
|
|
||||||
|
#### Scenario: 默认时间范围
|
||||||
|
- **WHEN** Drawer 打开
|
||||||
|
- **THEN** 时间选择器 SHALL 默认选中 "24小时" 快捷按钮
|
||||||
|
|
||||||
|
## ADDED Requirements
|
||||||
|
|
||||||
|
### Requirement: Stats 数据查询 Hook
|
||||||
|
系统 SHALL 提供 `useTargetStats` hook 查询单目标深度统计数据。
|
||||||
|
|
||||||
|
#### Scenario: stats queryKey
|
||||||
|
- **WHEN** 查询某目标的统计数据
|
||||||
|
- **THEN** queryKey SHALL 为 ["stats", targetId, from, to]
|
||||||
|
|
||||||
|
#### Scenario: stats 条件查询
|
||||||
|
- **WHEN** 用户未选中任何目标
|
||||||
|
- **THEN** stats 的 useQuery SHALL enabled=false，不发起请求
|
||||||
|
|
||||||
|
#### Scenario: stats 数据返回
|
||||||
|
- **WHEN** stats 查询成功
|
||||||
|
- **THEN** hook SHALL 返回 `TargetStatsResponse` 类型数据
|
||||||
|
|
||||||
|
#### Scenario: 时间范围变化时重新请求
|
||||||
|
- **WHEN** 用户更改时间范围
|
||||||
|
- **THEN** stats 的 useQuery SHALL 因 queryKey 变化自动重新请求
|
||||||
@@ -0,0 +1,106 @@
|
|||||||
|
## ADDED Requirements
|
||||||
|
|
||||||
|
### Requirement: 单目标深度统计 API
|
||||||
|
系统 SHALL 提供 `GET /api/targets/:id/stats` 端点，返回单个目标在指定时间窗口内的非时序聚合统计指标。
|
||||||
|
|
||||||
|
#### Scenario: 获取目标统计
|
||||||
|
- **WHEN** 客户端请求 `GET /api/targets/1/stats?from=ISO&to=ISO`
|
||||||
|
- **THEN** 系统 SHALL 返回 JSON 对象包含 p95DurationMs、p99DurationMs、avgDurationMs、mttr、longestOutage、incidentCount、currentStreak、totalChecks、upChecks、downChecks、availability
|
||||||
|
|
||||||
|
#### Scenario: from 或 to 参数缺失
|
||||||
|
- **WHEN** 客户端请求 `GET /api/targets/1/stats` 未提供 from 或 to 参数
|
||||||
|
- **THEN** 系统 SHALL 返回 400 状态码和错误信息
|
||||||
|
|
||||||
|
#### Scenario: 目标不存在
|
||||||
|
- **WHEN** 客户端请求 `GET /api/targets/999/stats`
|
||||||
|
- **THEN** 系统 SHALL 返回 404 状态码和错误信息
|
||||||
|
|
||||||
|
#### Scenario: 无效的目标 ID
|
||||||
|
- **WHEN** 客户端请求 `GET /api/targets/abc/stats`
|
||||||
|
- **THEN** 系统 SHALL 返回 400 状态码和错误信息
|
||||||
|
|
||||||
|
### Requirement: P95/P99 延迟计算
|
||||||
|
系统 SHALL 在应用层计算 P95 和 P99 延迟百分位数。
|
||||||
|
|
||||||
|
#### Scenario: 正常计算 P95
|
||||||
|
- **WHEN** 时间窗口内存在成功检查记录（matched=1）
|
||||||
|
- **THEN** 系统 SHALL 取出所有成功检查的 duration_ms，在应用层排序后取第 95 百分位值返回为 p95DurationMs
|
||||||
|
|
||||||
|
#### Scenario: 正常计算 P99
|
||||||
|
- **WHEN** 时间窗口内存在成功检查记录
|
||||||
|
- **THEN** 系统 SHALL 取第 99 百分位值返回为 p99DurationMs
|
||||||
|
|
||||||
|
#### Scenario: 无成功检查记录
|
||||||
|
- **WHEN** 时间窗口内无 matched=1 的记录
|
||||||
|
- **THEN** p95DurationMs 和 p99DurationMs SHALL 返回 null
|
||||||
|
|
||||||
|
#### Scenario: 百分位计算方法
|
||||||
|
- **WHEN** 计算第 N 百分位
|
||||||
|
- **THEN** 系统 SHALL 将 duration_ms 升序排列，取 index = ceil(count * N / 100) - 1 位置的值
|
||||||
|
|
||||||
|
### Requirement: MTTR 计算
|
||||||
|
系统 SHALL 计算平均恢复时间（Mean Time To Recovery）。
|
||||||
|
|
||||||
|
#### Scenario: 存在已恢复的故障段
|
||||||
|
- **WHEN** 时间窗口内存在至少一个已恢复的故障段（连续 matched=0 后跟 matched=1）
|
||||||
|
- **THEN** 系统 SHALL 计算所有已恢复故障段的平均持续时间（从首个 matched=0 的 timestamp 到恢复后首个 matched=1 的 timestamp 之差），返回为 mttr（毫秒）
|
||||||
|
|
||||||
|
#### Scenario: 无已恢复的故障段
|
||||||
|
- **WHEN** 时间窗口内无已恢复的故障段（全部正常，或当前仍在故障中且无历史恢复）
|
||||||
|
- **THEN** mttr SHALL 返回 null
|
||||||
|
|
||||||
|
#### Scenario: 当前正在故障中
|
||||||
|
- **WHEN** 时间窗口内最后一段故障尚未恢复
|
||||||
|
- **THEN** 该未恢复的故障段 SHALL 不计入 MTTR 平均值
|
||||||
|
|
||||||
|
#### Scenario: 窗口起始即为故障且后续恢复
|
||||||
|
- **WHEN** 时间窗口内第一条记录即为 matched=0（故障跨越了 from 边界），且该故障段在窗口内恢复
|
||||||
|
- **THEN** 该故障段 SHALL 不计入 MTTR 平均值（因无法确定真实故障开始时间），但 SHALL 计入 incidentCount
|
||||||
|
|
||||||
|
### Requirement: 最长故障时长
|
||||||
|
系统 SHALL 计算时间窗口内最长的单次故障持续时间。
|
||||||
|
|
||||||
|
#### Scenario: 存在故障段
|
||||||
|
- **WHEN** 时间窗口内存在故障段
|
||||||
|
- **THEN** 系统 SHALL 返回最长故障段的持续时间为 longestOutage（毫秒）
|
||||||
|
|
||||||
|
#### Scenario: 无故障
|
||||||
|
- **WHEN** 时间窗口内无 matched=0 的记录
|
||||||
|
- **THEN** longestOutage SHALL 返回 null
|
||||||
|
|
||||||
|
#### Scenario: 当前正在故障中
|
||||||
|
- **WHEN** 最后一段故障尚未恢复
|
||||||
|
- **THEN** 该故障段的持续时间 SHALL 计算为从故障开始到时间窗口 to 参数的时间差
|
||||||
|
|
||||||
|
### Requirement: 故障事件计数
|
||||||
|
系统 SHALL 计算时间窗口内的故障事件次数。
|
||||||
|
|
||||||
|
#### Scenario: 计算故障事件数
|
||||||
|
- **WHEN** 时间窗口内存在状态翻转（matched 从 1 变为 0）
|
||||||
|
- **THEN** 系统 SHALL 返回翻转次数为 incidentCount
|
||||||
|
|
||||||
|
#### Scenario: 无故障事件
|
||||||
|
- **WHEN** 时间窗口内所有检查均为 matched=1
|
||||||
|
- **THEN** incidentCount SHALL 返回 0
|
||||||
|
|
||||||
|
#### Scenario: 窗口起始即为故障
|
||||||
|
- **WHEN** 时间窗口内第一条记录即为 matched=0 且无前序记录可判断翻转
|
||||||
|
- **THEN** 该故障 SHALL 计为 1 次事件
|
||||||
|
|
||||||
|
### Requirement: 当前连续状态
|
||||||
|
系统 SHALL 返回目标当前的连续状态信息。
|
||||||
|
|
||||||
|
#### Scenario: 当前连续正常
|
||||||
|
- **WHEN** 目标最近的检查记录连续为 matched=1
|
||||||
|
- **THEN** currentStreak SHALL 返回 `{ up: true, count: N }`，N 为连续正常的检查次数
|
||||||
|
|
||||||
|
#### Scenario: 当前连续异常
|
||||||
|
- **WHEN** 目标最近的检查记录连续为 matched=0
|
||||||
|
- **THEN** currentStreak SHALL 返回 `{ up: false, count: N }`，N 为连续异常的检查次数
|
||||||
|
|
||||||
|
### Requirement: TargetStatsResponse 共享类型
|
||||||
|
系统 SHALL 在 `src/shared/api.ts` 中定义 `TargetStatsResponse` 类型。
|
||||||
|
|
||||||
|
#### Scenario: 类型定义
|
||||||
|
- **WHEN** 前后端引用 `TargetStatsResponse` 类型
|
||||||
|
- **THEN** 该类型 SHALL 包含 p95DurationMs（number | null）、p99DurationMs（number | null）、avgDurationMs（number | null）、mttr（number | null）、longestOutage（number | null）、incidentCount（number）、currentStreak（{ up: boolean; count: number }）、totalChecks（number）、upChecks（number）、downChecks（number）、availability（number）
|
||||||
@@ -0,0 +1,28 @@
|
|||||||
|
## ADDED Requirements
|
||||||
|
|
||||||
|
### Requirement: 连续状态列
|
||||||
|
表格 SHALL 包含「连续状态」列，展示目标当前连续正常或异常的次数。
|
||||||
|
|
||||||
|
#### Scenario: 连续状态列渲染
|
||||||
|
- **WHEN** 表格渲染
|
||||||
|
- **THEN** 表格 SHALL 在「最近状态」列之后、「延迟」列之前展示「连续状态」列，标题为"连续"，宽度 100px
|
||||||
|
|
||||||
|
#### Scenario: 连续正常展示
|
||||||
|
- **WHEN** 目标当前连续正常
|
||||||
|
- **THEN** 列 SHALL 使用 TDesign Tag 组件（theme=success, variant=light, size=small）展示 "▲ N次"
|
||||||
|
|
||||||
|
#### Scenario: 连续异常展示
|
||||||
|
- **WHEN** 目标当前连续异常
|
||||||
|
- **THEN** 列 SHALL 使用 TDesign Tag 组件（theme=danger, variant=light, size=small）展示 "▼ N次"
|
||||||
|
|
||||||
|
#### Scenario: 连续状态计算
|
||||||
|
- **WHEN** 计算连续状态
|
||||||
|
- **THEN** 系统 SHALL 从 recentSamples（按时间倒序）遍历，统计从最新记录开始连续相同状态的次数
|
||||||
|
|
||||||
|
#### Scenario: 超过样本上限
|
||||||
|
- **WHEN** 连续状态次数等于 recentSamples 长度（30）
|
||||||
|
- **THEN** 列 SHALL 展示 "▲ 30+" 或 "▼ 30+"
|
||||||
|
|
||||||
|
#### Scenario: 无样本数据
|
||||||
|
- **WHEN** 目标的 recentSamples 为空数组
|
||||||
|
- **THEN** 列 SHALL 展示 "-"
|
||||||
55
openspec/changes/enhance-frontend-metrics/tasks.md
Normal file
55
openspec/changes/enhance-frontend-metrics/tasks.md
Normal file
@@ -0,0 +1,55 @@
|
|||||||
|
## 1. 共享类型与数据层
|
||||||
|
|
||||||
|
- [ ] 1.1 扩展 `src/shared/api.ts`：SummaryResponse 增加 incidents24h；TrendPoint 增加 upChecks/minDurationMs/maxDurationMs；新增 TargetStatsResponse 类型
|
||||||
|
- [ ] 1.2 ProbeStore 修改 `getAllTargetStats(from?, to?)` 和 `getTargetStats(targetId, from?, to?)` 增加时间窗口参数，默认 24h
|
||||||
|
- [ ] 1.3 ProbeStore 修改 `getTrend` SQL 增加 MIN/MAX duration_ms 和 upChecks 聚合字段
|
||||||
|
- [ ] 1.4 ProbeStore 新增 `getIncidents24h()` 独立方法，使用 LAG 窗口函数统计所有目标的状态翻转次数
|
||||||
|
- [ ] 1.5 ProbeStore 新增 `getTargetDurations(targetId, from, to)` 方法，返回成功检查的 duration_ms 升序数组
|
||||||
|
- [ ] 1.6 ProbeStore 新增 `getCheckSequence(targetId, from, to)` 方法，返回检查序列用于故障分析
|
||||||
|
- [ ] 1.7 编写 ProbeStore 新增/修改方法的单元测试
|
||||||
|
|
||||||
|
## 2. 后端 API 路由
|
||||||
|
|
||||||
|
- [ ] 2.1 修改 `src/server/routes/summary.ts`：调用 store.getIncidents24h()，响应增加 incidents24h 字段
|
||||||
|
- [ ] 2.2 修改 `src/server/routes/targets.ts`：解析 `?window=24h` 查询参数，转换为时间范围传递给 getAllTargetStats(from, to)，缺省默认 24h
|
||||||
|
- [ ] 2.3 修改 `src/server/routes/trend.ts`：响应增加 upChecks/minDurationMs/maxDurationMs 字段
|
||||||
|
- [ ] 2.4 新增 `src/server/routes/stats.ts`：实现 GET /api/targets/:id/stats?from=&to= 端点，应用层计算 P95/P99、MTTR、最长故障、故障次数、连续状态
|
||||||
|
- [ ] 2.5 在 `src/server/server.ts` 路由注册中挂载 stats 路由
|
||||||
|
- [ ] 2.6 编写 stats 路由的集成测试（含 P95 计算、MTTR 计算、窗口边界截断、无数据等边界情况）
|
||||||
|
- [ ] 2.7 编写 summary/targets/trend 路由修改的测试更新
|
||||||
|
|
||||||
|
## 3. 前端工具函数
|
||||||
|
|
||||||
|
- [ ] 3.1 删除 `src/web/utils/stats.ts` 中的 `computeTrendStats` 函数（不再有调用方）
|
||||||
|
- [ ] 3.2 新增连续状态计算工具函数 `getConsecutiveStatus(samples: RecentSample[]): { up: boolean; count: number }`
|
||||||
|
- [ ] 3.3 新增时间格式化工具函数：相对时间（X秒前/X分钟前）、动态单位（ms→秒/分钟/小时）
|
||||||
|
- [ ] 3.4 编写工具函数的单元测试
|
||||||
|
|
||||||
|
## 4. 前端数据层
|
||||||
|
|
||||||
|
- [ ] 4.1 修改 `src/web/hooks/use-queries.ts`：useTargets 请求改为 `/api/targets?window=24h`，后端解析 window 参数转换为时间范围
|
||||||
|
- [ ] 4.2 新增 useTargetStats hook（queryKey: ["stats", targetId, from, to]，enabled 依赖 targetId 存在）
|
||||||
|
- [ ] 4.3 修改 `use-target-detail.ts`：集成 useTargetStats 调用，复用现有 timeFrom/timeTo 状态
|
||||||
|
|
||||||
|
## 5. 前端组件 — Summary Cards
|
||||||
|
|
||||||
|
- [ ] 5.1 修改 `SummaryCards.tsx`：从 3 列（span=4）扩展为 4 列（span=3），新增 24h 异常事件数卡片（color=orange）
|
||||||
|
- [ ] 5.2 在 SummaryCards 底部增加 lastCheckTime 相对时间展示（useState + setInterval 每秒更新），超过 60 秒变警告色
|
||||||
|
|
||||||
|
## 6. 前端组件 — Target Table
|
||||||
|
|
||||||
|
- [ ] 6.1 修改 `target-table-columns.tsx`：可用率列标题改为"可用率(24h)"
|
||||||
|
- [ ] 6.2 修改 `target-table-columns.tsx`：在「最近状态」列后新增「连续」列（width=100），使用 TDesign Tag（theme=success/danger, variant=light, size=small）渲染 "▲ N次" / "▼ N次"
|
||||||
|
|
||||||
|
## 7. 前端组件 — Drawer 概览
|
||||||
|
|
||||||
|
- [ ] 7.1 修改 `OverviewTab.tsx`：props 增加 statsData/statsLoading；删除 computeTrendStats 调用；统计区重构为 2×4 Statistic 布局，数据来自 statsData
|
||||||
|
- [ ] 7.2 修改 `OverviewTab.tsx`：StatusDonut 数据来源改为 statsData.upChecks / statsData.downChecks
|
||||||
|
- [ ] 7.3 修改 `TrendChart.tsx`：移除右侧 Y 轴和 availability Line；增加 Area 组件渲染 min/max 延迟范围（半透明品牌色填充）；avgDurationMs Line 的 dot 回调对 availability < 100 的点渲染红色圆点
|
||||||
|
- [ ] 7.4 修改 `TargetDetailDrawer.tsx`：TIME_SHORTCUTS 保持 1h/6h/24h/7d 四个选项，默认选中 24h
|
||||||
|
- [ ] 7.5 修改 `TargetDetailDrawer.tsx`：集成 useTargetStats，传递 statsData/statsLoading 给 OverviewTab
|
||||||
|
|
||||||
|
## 8. 质量保障
|
||||||
|
|
||||||
|
- [ ] 8.1 运行完整测试套件，确保所有测试通过
|
||||||
|
- [ ] 8.2 运行 lint 和格式检查，修复所有问题
|
||||||
Reference in New Issue
Block a user