1
0

docs: 重构文档体系

- 合并 DEVELOPMENT.md 至 docs/development/README.md
- 合并 CONTRIBUTING.md 至 docs/development/checker.md
- 合并 build-release.md 至 release.md
- 合并 testing-quality.md 内容至各专题文档
- 合并 status-model.md 至 expectations.md
- 新增 docs/user/README.md 用户入口
- 简化 docs/README.md 文档路由
- 各专题文档新增适用场景和更新触发条件
- 更新 openspec/config.yaml 文档规则
This commit is contained in:
2026-05-25 10:47:52 +08:00
parent a6504d5a62
commit 714b635aef
18 changed files with 428 additions and 542 deletions

View File

@@ -1,5 +1,9 @@
# 后端开发
本文档说明 DiAL 后端的 API、配置加载、存储、拨测引擎、日志、expect 和错误模型开发约定。
适用场景:修改 `src/server/``src/shared/api.ts`、后端测试、配置契约、API 响应、store、engine、logger 或 expect 基础设施。
## 库使用优先级
| 优先级 | 来源 | 典型用途 |
@@ -111,13 +115,28 @@ Ajv 保持严格拒绝模式:`allErrors: true`、不启用类型强制转换
| `ContentExpectations` | 返回内容或半结构化内容 | body、stdout、stderr、banner、response、output、result |
| `KeyedExpectations` | 动态键值断言 | headers、DB rows 列值 |
详细 checker 开发流程见 [Checker 开发](checker-development.md)。
详细 checker 开发流程见 [Checker 开发](checker.md)。
## 错误模型
| 类型 | 结构 |
| ------------ | ----------------------------------- | ------------------------------------------------------- |
| API 错误 | `{ error: "描述", status: <code> }` |
| CheckFailure | `{ kind: "error" | "mismatch", phase, path, expected?, actual?, message }` |
- API 错误:`{ error: "描述", status: <code> }`
- CheckFailure`{ kind: "error" | "mismatch", phase, path, expected?, actual?, message }`
expect 校验失败记录首个失败原因;网络、超时、进程崩溃统一为 `kind: "error"`
## 后端测试与验证
| 变更类型 | 测试重点 |
| ---------------------- | ---------------------------------------- |
| API 路由 | `tests/server/app.test.ts` 集成行为 |
| 配置 schema 或语义校验 | schema 导出、合法配置、非法配置 |
| store | SQLite 写入、查询、分页、聚合和清理 |
| engine | 调度、并发、超时、结果写入和状态变化日志 |
| expect 基础设施 | matcher 语义、快速失败、错误信息 |
| checker runner | 见 [Checker 开发](checker.md#测试要求) |
后端运行时代码统一通过注入的 Logger 输出日志,禁止直接使用 `console.*`。新增或修改后端逻辑通常需要运行 `bun run check`;影响构建产物或前后端集成时运行 `bun run verify`
## 更新触发条件
修改后端 API、共享类型、配置契约、store、engine、logger、expect 基础设施、错误模型或后端测试规范时,必须更新本文档。