wishforge-ide/docs/product/risk-levels.md

14 KiB
Raw Permalink Blame History

风险分级规则(Risk Levels)

本文档定义 WishForge 面向客户场景的改动风险分级标准、工程判定信号、审批流转与发布后回滚策略。所有规则的目标是避免平台崩溃与客户数据丢失,同时让小修改快速、准确地上线。


一、三级风险定义与典型示例

1. 低风险(Low Risk)

定义:仅涉及界面展示层文案、样式微调或静态说明,不改变接口协议、不修改业务逻辑分支、不触碰数据库与部署配置。即使存在瑕疵,也仅影响单处视觉展示,不会阻断业务操作或污染数据。

客户能看懂的例子:

  1. 改按钮文案(例如:把「提交审核」改成「完成并送审」)。
  2. 调表格列宽或标签颜色(例如:把「已超时」标签从灰色改成红色,调整列表筛选项间距)。
  3. 改空状态或报错提示语(例如:把「暂无数据」改成「当前没有可领取的任务」)。
  4. 调整只读展示字段顺序(例如:任务详情卡片里把「创建时间」挪到「创建人」下方)。
  5. 更新项目 Wiki 或内置帮助文档。

2. 中风险(Medium Risk)

定义:涉及前端交互逻辑、状态流转或经限定范围的常规业务接口修改,但不涉及数据结构变更、历史数据批量改写、权限扩大、认证机制调整或基础设施改动。若出现问题,可能影响单个页面的操作体验或单个功能的局部流程,但不会造成全站不可用或数据损毁。

客户能看懂的例子:

  1. 增加列表筛选条件或排序方式(例如:在审核池增加按「批次号」筛选或按「更新时间」排序)。
  2. 修改表单前端校验规则(例如:新建字典时限制名称不超过 30 个字符,必填项未填时高亮提示)。
  3. 调整单个业务按钮的二次确认弹窗逻辑(例如:点击「驳回」时必须填写驳回原因才能提交)。
  4. 修复特定页面的查询超时或列表卡顿(仅优化只读查询条件或前端分页加载,不改动底层写入逻辑)。
  5. 在现有接口返回中增加一个已有字段用于前端展示(不改表结构、不改写库逻辑)。

3. 高风险(High Risk)

定义:任何可能引发平台级故障、数据丢失或错乱、越权访问、验证失真或集群资源枯竭的修改。包括但不限于:数据库迁移、删除或批量修改数据、权限和认证、部署配置、测试基线和验证配置、副本缩到 0、资源请求超过节点余量。

客户能看懂的例子:

  1. 删除或批量修改历史数据(例如:「把上个月所有驳回的任务全部删掉」或「批量把 1000 条旧数据的状态改成已完成」)。
  2. 修改谁能看、谁能改的权限规则(例如:「让普通标注员也能释放别人领取的任务」或「允许免登录直接访问导出接口」)。
  3. 修改数据库表结构或做数据迁移(例如:拆分或合并存量业务表、删除已有字段、修改唯一索引)。
  4. 修改服务器部署配置、服务副本数或硬件资源配额(例如:把某个后台服务停掉缩到 0、把单服务内存上限调高到超出服务器剩余空间)。
  5. 修改自动化测试的放行标准或已知失败清单(例如:为了让发布通过,把报错的测试用例加进忽略名单)。

二、每级工程判定信号(开发实现依据)

判定器按 「高风险优先拦截 → 中风险特征匹配 → 其余归入低风险(须满足低风险白名单)」 的顺序执行。只要命中任意一条高等级信号,立即按高等级定级。

1. 高风险判定信号(命中任一即判高风险)

信号类别 路径 / 文件类型匹配 代码 / 配置特征模式(AST / 正则 / 结构对比) 范围与上下文信号
数据库迁移与 Schema **/migrations/**
**/schema/**
**/*migration*.{ts,js,go,py,sql}
**/indexes/**
createIndex, dropIndex, dropCollection, dropDatabase, renameCollection, ALTER TABLE, DROP TABLE, TRUNCATE, DROBOTICFLOW_DATABASE_BOOTSTRAP 新增或修改任何数据库初始化/迁移脚本
删除或批量修改数据 任何后端业务代码(**/*.{ts,js,go,py}) MongoDB / SQL 破坏性或批量写操作:
deleteMany, deleteOne(非草稿/非临时会话), updateMany, bulkWrite, replaceOne, findOneAndDelete, drop, $unset, $rename, remove(
包含无严格单文档主键约束的写操作,或循环调用写接口
权限与认证 **/permissions.{ts,js,go}
**/auth/**, **/rbac/**
**/middleware/auth*
packages/contracts/src/permissions.ts
packages/contracts/src/path-rules.ts
packages/contracts/src/release-risk.ts
Permissions., accountTypes, normalizePermissions, role, jwt, session, cookie, token, oauth, allowBackend, pathsNeedingReview, protectedChange releaseRisk 标记 permissionsExpanded;修改角色权限映射或接口鉴权中间件
部署配置与容器构建 Dockerfile*, docker-compose*
k8s/**, infra/**, helm/**
scripts/deploy*, scripts/release*
scripts/poc-release.ts
**/*.env*, **/poc.env
replicas:, resources:, requests:, limits:, nodeAffinity, nodeSelector, tolerations, hostPath, local-storage, secretKeyRef, image: 修改容器镜像构建、启动命令、环境变量注入或 K8s 清单
副本缩到 0 k8s/**/*.yaml, infra/**/*.yaml
或任何扩缩容补丁
replicas:\s*0(除本来即为按需冷备且未发生变更的静态声明外,任何将在线服务 replicas 改为 0 的 diff) 导致在线常驻服务实例数为 0
资源请求超过节点余量 k8s/**/*.yaml, infra/**/*.yaml
docs/capacity/*.json
计算变更后 replicas × resources.requests(CPU / Memory / nvidia.com/gpu / PVC 存储)与集群目标节点可用余量对比 变更后总请求超过节点可分配余量(或触发节点 CPU/内存水位红线、GPU 超配、不可扩容 PVC 超限)
测试基线与验证配置 tests/known-failures.json
scripts/verification-scopes.json
packages/runtime/src/verify.ts
packages/runtime/src/sandbox.ts
**/fanyu-policy.json
新增 known-failures 条目、缩减 verification-scopes 映射范围、使用 .skip / xit / t.skip 跳过既有断言、修改 core.hooksPath 或沙箱隔离参数 削弱验证门禁或篡改测试通过基线
依赖清单与构建工具链 package.json, pnpm-lock.yaml, package-lock.json, go.mod, go.sum, requirements.txt 新增、升级或移除第三方依赖包,修改 scripts 中的构建/测试入口 命中 dependencyManifest 受保护路径

2. 中风险判定信号(未命中高风险,且命中以下任一)

信号类别 路径 / 文件类型匹配 代码 / 配置特征模式 范围与上下文信号
前端交互与状态逻辑 apps/web/src/**/*.{ts,tsx,js,jsx}
src/**/*.{ts,tsx,js,jsx}(非纯样式/文案)
修改 React hooks(useState, useEffect, useMemo)、表单提交处理、路由跳转、接口调用参数组装、前端分页与状态机 改动文件数 2–5 个,且总变更行数(增+删)51–300 行
受限的后端/契约常规调整 apps/api/src/**/*.{ts,js}
packages/contracts/src/**/*.{ts,js}
internal/**/*.go(非权限/非迁移/非批量写)
只读查询优化(如增加游标分页、maxTimeMS、查询过滤条件)、单记录非破坏性字段校验、新增非敏感展示字段 未超出 Copilot 定位文件及其直接引用模块;包含对应单测更新
超出低风险白名单的微小修改 任何非高风险文件 虽未触碰高风险特征,但包含条件分支(if/else、switch)或函数签名变更 改动行数 ≤ 50 行但涉及逻辑分支变化

3. 低风险判定信号(必须同时满足以下全部条件)

信号类别 判定要求
路径与文件类型白名单 仅限前端视图/样式/文案/文档文件:
- 样式文件:**/*.css, **/*.module.css, **/*.scss
- 文案/常量/页面展示组件:apps/web/src/**/*.{tsx,ts} 或 src/**/*.{ jsx,js,tsx,ts } 中仅涉及 JSX 文本节点、文案字典、样式类名
- 文档:wiki/**/*.md, docs/**/*.md
代码特征要求 - 无任何后端、数据库、权限、配置、依赖、测试基线文件改动
- 无新增或修改网络请求调用(fetch, axios, API Client 方法)
- 无数据写操作或状态机流转分支变更
改动规模与范围 - 改动文件数 ≤ 2 个
- 总变更行数(增+删)≤ 50 行
- 100% 在 Copilot 定位的目标文件范围内(未波及定位范围外的文件)

三、审批权限、发布前证据与发布后观察/回滚

维度 低风险(Low) 中风险(Medium) 高风险(High)
谁批准发布 客户自己批准(具备发布权限的客户业务责任人) 客户自己批准(具备发布权限的客户业务责任人) 必须平台方审批(客户确认需求意向后,转交平台方技术/运维负责人审批)
发布前必须具备的证据 1. G1 代码与分支新鲜度检查通过
2. 前端构建与类型检查通过(build:web / typecheck)
3. 修改前后的界面对比截图或文案 diff 预览
4. G9 客户版交付报告(「通过 / 失败 / 待验证 / 没做」四栏完整,且「失败」栏为 0)
1. 包含低风险全部证据
2. G2 分层验证通过(verify:quick 及改动映射的 verify:task 全部退出码为 0)
3. G3 基线保护通过(未新增 known-failures,无绕过测试)
4. 涉及的角色与页面状态(加载/空态/报错/只读)实测记录
1. 包含中风险全部证据 + 完整集成验证(verify:integration)
2. 平台方专项审查记录:
- 数据类:备份快照确认、影响行数预估、只读演练结果
- 权限类:全角色权限矩阵回归测试报告
- 资源/部署类:集群节点余量核算单(R1–R3)与回滚补丁(.rollback.patch.yaml)
发布后怎么观察 1. 自动核对 /api/health 的 buildCommit 与发布版本一致
2. 观察 5 分钟内前端页面加载与接口 5xx 错误率
1. 自动核对 /api/health 的 buildCommit 与服务 Ready 状态
2. 观察 15 分钟内目标接口耗时(p95)、5xx 错误率及脱敏线上错误日志
3. 客户在页面执行 1 次真实业务动作确认
1. 按 Coordinator → Worker/Processor → API 顺序分步观察健康检查
2. 持续观察 30 分钟集群 CPU/内存/GPU 水位、慢查询日志与业务核心指标
3. 平台方值班人员在线盯屏确认
怎么回滚 - 客户可在界面一键点击「回滚到上一版本」或「撤销本次修改」
- 若健康检查连续失败,系统自动回滚至上一稳定镜像/提交
- 客户可在界面一键触发版本回滚(拥有独立回滚权限的客户负责人可直接操作,无需等待平台方)
- 健康检查失败或核心接口 5xx 激增时自动回滚
- 优先使用预先准备的对偶回滚补丁(如 *.rollback.patch.yaml)或镜像 digest 条件回滚
- 涉及数据库迁移或数据的,按平台方审批的专项回滚预案执行(严禁盲目回退代码导致新旧数据结构不兼容)

四、拿不准时的兜底规则(默认升档原则)

当系统或 Copilot 遇到以下任一情况,视为**「拿不准(Uncertain)」**:

  1. 超出定位范围:实际修改的文件超出了与客户对话时 Copilot 定位的文件列表。
  2. 信号混合或无法解析:改动同时包含低风险样式修改与未明确分类的脚本/配置,或 AST/Diff 解析器无法100%确认某次数据库调用是否为只读。
  3. 验证结果不完整:验证命令返回超时/跳过/未映射(如退出码 2),或存在「待验证」项无法在沙箱内自动完成。
  4. 缺少明确规则匹配:命中了新的文件目录或未知文件后缀(既不在低风险白名单,也未明确写入中/高风险特征库,即 unclassified)。

处理方式:

  1. 默认判到更高一级:
    • 原本像低风险但拿不准(例如改文案时顺手改了旁边的条件判断,或改动超出了定位文件) → 一律升为中风险。
    • 原本像中风险但拿不准(例如改查询接口时碰到了权限校验函数、公共中间件或未知后端路径) → 一律升为高风险,转交平台方审批。
  2. 向客户透明告知原因(禁止隐瞒或使用内部黑话):
    • 必须在界面与交付报告中用一句话告诉客户为什么升档以及接下来谁来处理。
    • 低升中话术示例:「这次修改除了改文字,还调整了按钮的显示条件,为了稳妥已按『中风险』为您补充了功能测试,您可以查看测试结果后决定是否发布。」
    • 中升高话术示例:「这次修改涉及后台权限检查(或超出了原本定位的页面范围),为保护平台和您的数据安全,已自动转为『高风险』并提交平台技术团队审核,审核通过后会第一时间通知您。」