aiops/docs/specs/README.md

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. 文件组织

docs/specs/
├── README.md
├── _template.md
├── cloud/billing-normalization.md
├── monitor/site-probe-retention.md
└── deploy/pipeline-jenkins.md

文件名使用小写短横线。规格中引用代码、API、迁移和测试的实际路径。重大方向被替代时保留原规格并标记 Superseded，不要删除决策历史。