106 lines
5.5 KiB
Markdown
106 lines
5.5 KiB
Markdown
# AIOps 规格驱动开发规范
|
||
|
||
本目录保存会改变系统行为、接口、数据或运维方式的工程规格。规格的作用是让需求、实现、测试和发布使用同一套可验证契约。
|
||
|
||
## 1. 适用范围
|
||
|
||
按最高影响级别判定，不以改动行数判断：
|
||
|
||
| 级别 | 范围 | 必需产物 |
|
||
|------|------|----------|
|
||
| S0 | 文案、格式、注释、无行为变化的机械修改 | 验证记录 |
|
||
| S1 | 局部缺陷、内部重构、单模块小改动 | 任务计划中的问题、约束和验收标准 |
|
||
| S2 | 新功能、跨模块流程、API、配置、数据模型变更 | `docs/specs/<domain>/<slug>.md` |
|
||
| S3 | 权限、安全、账单、迁移、数据清理、生产部署 | S2 规格 + 风险、兼容、可观测、发布、回滚 |
|
||
|
||
连续开发同一能力时更新已有规格，不重复创建。纯探索或评估可以先输出调研结论；一旦进入实现，必须补齐对应级别的规格。
|
||
|
||
## 2. 事实与优先级
|
||
|
||
规格必须基于仓库和运行环境的真实证据。发生冲突时按以下顺序处理：
|
||
|
||
1. 用户当前明确需求与已确认决策。
|
||
2. 已接受规格中的验收标准和契约。
|
||
3. 安全、数据保护和生产变更规则。
|
||
4. 自动化测试表达的现有行为。
|
||
5. 当前实现与一般文档。
|
||
|
||
当前实现与规格不一致时不得自行选择其一：先确认这是缺陷、兼容要求还是规格过期，然后更新规格中的决策记录。
|
||
|
||
## 3. 生命周期
|
||
|
||
规格状态使用：`Draft`、`Accepted`、`Implemented`、`Verified`、`Superseded`。
|
||
|
||
1. **Discover**：定位入口、调用链、数据模型、权限、外部依赖、现有测试和工作区改动。
|
||
2. **Specify**：定义目标和非目标，用 `FR-*`、`NFR-*`、`AC-*` 编号描述行为与验收。
|
||
3. **Design**：明确模块边界、契约、失败路径、迁移、观测和回滚，记录关键取舍。
|
||
4. **Implement**：小步实现并保持范围受控；新增发现通过规格的决策记录显式吸收。
|
||
5. **Verify**：建立 `AC → 测试/检查 → 结果` 的可追踪关系，覆盖成功、失败和边界路径。
|
||
6. **Deliver**：更新状态、列出变更、验证证据、部署结果、遗留风险与后续工作。
|
||
|
||
用户需求已经足够明确时，维护者可将规格标记为 `Accepted` 并继续实现。只有未决选择会改变用户可见行为、数据安全、权限或部署风险时才需要等待确认。
|
||
|
||
## 4. 规格质量要求
|
||
|
||
### 4.1 需求必须可验证
|
||
|
||
- 使用“当……时，系统必须……”描述行为，避免“优化一下”“尽量”“支持更多”等不可验证表述。
|
||
- 每项功能需求使用 `FR-01` 编号，每项非功能需求使用 `NFR-01` 编号。
|
||
- 每条验收标准使用 `AC-01` 编号，并给出输入、动作和可观察结果。
|
||
- 非目标必须明确，防止实现阶段自然扩张范围。
|
||
|
||
### 4.2 契约必须先于实现
|
||
|
||
- HTTP/API：路径、方法、请求、响应、错误码、鉴权、幂等和分页口径。
|
||
- 数据：表/字段、约束、索引、默认值、迁移顺序、回填、兼容窗口和回滚限制。
|
||
- UI：入口、权限、加载/空/错误/禁用状态、响应式行为和中英文文案。
|
||
- 任务/事件：触发方式、重试、超时、去重、并发、状态机和审计记录。
|
||
- 外部系统：限流、超时、部分失败、降级、凭证边界和供应商差异。
|
||
|
||
### 4.3 AIOps 领域约束
|
||
|
||
- 金额：原币、报告币、汇率来源、生效时间、舍入精度和汇总维度必须明确。
|
||
- 时间：时区、采样区间、自然日/月边界、数据截止时间和缺失数据处理必须明确。
|
||
- 监控：指标单位、标签基数、采样频率、保留期、告警迟滞和恢复条件必须明确。
|
||
- 自动化：执行身份、目标范围、危险操作确认、超时、取消、重试和审计必须明确。
|
||
- AI：输入数据范围、提示上下文、置信度含义、不可用降级和结果免责声明必须明确。
|
||
|
||
## 5. 验证门禁
|
||
|
||
验证范围随风险扩大，但至少包括受影响模块：
|
||
|
||
| 变更 | 最低验证 |
|
||
|------|----------|
|
||
| Go 后端 | 相关 `go test`、`go vet`、`go build` |
|
||
| React 前端 | `tsc --noEmit`、目标 ESLint、生产构建、关键页面验证 |
|
||
| Agent | `go test ./...`、`CGO_ENABLED=0 go build`、协议兼容检查 |
|
||
| API/跨模块 | Handler/服务测试 + 前后端契约检查 + 关键流程验证 |
|
||
| 数据库 | 各支持方言迁移测试、幂等性、备份与回滚演练说明 |
|
||
| 生产部署 | `/version`、迁移状态、进程/日志、关键只读接口、回滚点 |
|
||
|
||
不能运行的检查必须记录具体原因和残余风险。既有失败要区分是否由本次变更引入，不能静默忽略。
|
||
|
||
## 6. 完成定义
|
||
|
||
只有同时满足以下条件，规格才可标记为 `Verified`：
|
||
|
||
- 所有 `FR-*` 已实现，所有 `AC-*` 都有通过证据。
|
||
- API、数据、权限、审计、错误状态和兼容行为与规格一致。
|
||
- 相关自动化测试、静态检查和构建通过。
|
||
- S3 已验证备份、发布、健康检查和回滚路径。
|
||
- 用户文档、运维文档、配置示例和规格状态已同步。
|
||
- 未完成项和已知风险已显式记录，不用模糊措辞掩盖。
|
||
|
||
## 7. 文件组织
|
||
|
||
```text
|
||
docs/specs/
|
||
├── README.md
|
||
├── _template.md
|
||
├── cloud/billing-normalization.md
|
||
├── monitor/site-probe-retention.md
|
||
└── deploy/pipeline-jenkins.md
|
||
```
|
||
|
||
文件名使用小写短横线。规格中引用代码、API、迁移和测试的实际路径。重大方向被替代时保留原规格并标记 `Superseded`，不要删除决策历史。
|