@gong-ym/ai-spec-auto 0.2.14 → 0.2.15

package/.agents/skills/common/branch-code-reviewer/references/business-risk-guide.md

@@ -1,293 +1,293 @@
-# 业务风险评估指南
-
-## 概述
-
-本指南帮助 AI 评审专家系统性地识别业务类风险,确保代码实现与需求文档一致。
-
-## 评估维度
-
-### 1. 需求覆盖度检查
-
-#### 检查清单
-
-- [ ] **功能完整性**: 需求文档中的所有功能点是否都已实现
-- [ ] **验收标准**: 是否满足需求文档中的验收标准
-- [ ] **业务规则**: 代码实现是否符合业务规则
-- [ ] **边界场景**: 需求文档中提到的边界场景是否都处理了
-- [ ] **异常流程**: 异常场景是否有对应处理逻辑
-
-#### 示例
-
-**需求文档**:
-> 用户下单时必须校验库存,库存不足时显示"暂时缺货"并禁止提交订单。
-
-**代码检查**:
-```javascript
-// ✅ 正确实现
-if (stock <= 0) {
-  showError('暂时缺货');
-  disableSubmit();
-}
-
-// ❌ 风险实现 - 缺少库存校验
-submitOrder(); // 直接提交,未检查库存
-```
-
-### 2. 业务流程完整性
-
-#### 常见业务流程
-
-**电商订单流程**:
-```
-浏览商品 → 加入购物车 → 确认订单 → 支付 → 发货 → 完成
-                ↓
-              取消订单 → 退款
-```
-
-**检查要点**:
-- 流程是否完整,有无缺失环节
-- 流程跳转是否正确
-- 异常流程是否处理(如支付失败、库存不足)
-
-#### 示例
-
-**风险场景**:
-```
-✅ 正常流程: 创建订单 → 支付 → 更新库存
-❌ 缺失流程: 支付失败 → 无处理逻辑
-```
-
-### 3. 状态流转一致性
-
-#### 常见状态机
-
-**订单状态流转**:
-```
-待支付 → 已支付 → 待发货 → 已发货 → 已完成
-  ↓                        ↓
-取消                     退款中 → 已退款
-```
-
-**检查要点**:
-- 状态流转是否符合需求文档
-- 是否存在非法状态跳转
-- 状态变更是否有对应业务逻辑
-
-#### 示例
-
-**风险场景**:
-```javascript
-// ❌ 风险: 状态从"待支付"直接跳到"已完成"
-order.status = 'completed'; // 缺少"已支付"状态
-
-// ✅ 正确: 按流程流转
-if (order.status === 'pending_payment' && payment.success) {
-  order.status = 'paid';
-  // 后续流程...
-}
-```
-
-### 4. 数据一致性
-
-#### 检查要点
-
-- **事务性**: 多个数据操作是否在同一事务中
-- **并发控制**: 是否存在并发安全问题
-- **数据校验**: 输入数据是否符合业务约束
-- **数据关联**: 关联数据是否同步更新
-
-#### 示例
-
-**风险场景**:
-```javascript
-// ❌ 风险: 库存扣减与订单创建不在同一事务
-await createOrder(orderData);
-await deductStock(productId, quantity);
-// 如果 createOrder 成功但 deductStock 失败,数据不一致
-
-// ✅ 正确: 使用事务
-await db.transaction(async (tx) => {
-  await createOrder(tx, orderData);
-  await deductStock(tx, productId, quantity);
-});
-```
-
-### 5. 权限与合规
-
-#### 检查要点
-
-- **身份认证**: 操作前是否校验用户身份
-- **权限控制**: 用户是否有权限执行该操作
-- **数据权限**: 用户只能访问自己的数据
-- **合规要求**: 是否符合法律法规(如隐私保护)
-
-#### 示例
-
-**风险场景**:
-```javascript
-// ❌ 风险: 未校验权限即可删除订单
-async function deleteOrder(orderId) {
-  await api.delete(`/orders/${orderId}`);
-}
-
-// ✅ 正确: 校验权限
-async function deleteOrder(orderId) {
-  const order = await getOrder(orderId);
-  if (order.userId !== currentUser.id) {
-    throw new Error('无权限操作');
-  }
-  await api.delete(`/orders/${orderId}`);
-}
-```
-
-### 6. 异常场景处理
-
-#### 常见异常场景
-
-- **网络异常**: 请求失败、超时、重试
-- **业务异常**: 库存不足、余额不足、状态不符
-- **系统异常**: 服务不可用、数据库连接失败
-- **用户异常**: 用户取消、用户退出
-
-#### 检查要点
-
-- 是否有错误提示
-- 是否有降级方案
-- 是否有重试机制
-- 是否有回滚逻辑
-
-#### 示例
-
-**风险场景**:
-```javascript
-// ❌ 风险: 支付失败无处理
-async function handlePayment() {
-  const result = await pay();
-  // 如果支付失败,无任何提示
-}
-
-// ✅ 正确: 完整的异常处理
-async function handlePayment() {
-  try {
-    const result = await pay();
-    if (result.success) {
-      showSuccess('支付成功');
-      navigateToOrderDetail();
-    } else {
-      showError(result.message);
-      enableRetry();
-    }
-  } catch (error) {
-    showError('支付失败,请重试');
-    enableRetry();
-    logError(error);
-  }
-}
-```
-
-## 风险等级判定标准
-
-### 🔴 严重(Critical)
-
-**判定标准**:
-- 缺失核心功能点
-- 业务流程错误
-- 数据一致性问题
-- 安全合规问题
-
-**处理建议**: 必须修复后才能上线
-
-### 🟡 警告(Warning)
-
-**判定标准**:
-- 缺少异常场景处理
-- 边界条件遗漏
-- 状态流转不完整
-- 用户体验问题
-
-**处理建议**: 建议修复后上线
-
-### 🔵 建议(Suggestion)
-
-**判定标准**:
-- 体验优化
-- 流程改进
-- 性能优化
-- 代码重构
-
-**处理建议**: 可在后续迭代中处理
-
-## 需求文档解析要点
-
-### 提取关键信息
-
-1. **业务目标**: 为什么要做这个功能
-2. **功能清单**: 需要实现哪些功能
-3. **业务规则**: 有什么约束条件
-4. **验收标准**: 怎样算完成
-5. **边界场景**: 有哪些特殊情况
-6. **异常流程**: 出错时怎么处理
-
-### 映射到代码
-
-| 需求文档内容 | 代码检查点 |
-|-------------|-----------|
-| "必须校验库存" | 库存校验逻辑 |
-| "支付失败显示错误提示" | 支付异常处理 |
-| "仅管理员可删除" | 权限校验 |
-| "3秒无响应显示loading" | loading 状态管理 |
-| "支持批量操作" | 批量处理逻辑 |
-
-## 输出格式要求
-
-每个业务风险必须包含:
-
-```markdown
-### [风险标题]
-
-**风险等级**: 🔴 严重 / 🟡 警告 / 🔵 建议
-**需求来源**: 需求文档章节引用
-**影响范围**: 影响的业务场景
-**问题描述**: 详细说明风险
-**修复建议**: 具体的修复方案
-**示例代码**: 修复后的代码示例(可选)
-```
-
-## 常见业务风险模式
-
-### 1. 缺失功能
-
-- 需求文档要求的功能未实现
-- 只实现了正常流程,缺少异常流程
-- 只实现了主流程,缺少分支流程
-
-### 2. 流程错误
-
-- 流程顺序错误
-- 缺少必要的流程环节
-- 流程跳转逻辑错误
-
-### 3. 状态管理混乱
-
-- 状态定义不完整
-- 状态流转不合法
-- 状态变更无业务逻辑支撑
-
-### 4. 数据不一致
-
-- 关联数据未同步
-- 操作非原子性
-- 缺少数据校验
-
-### 5. 权限漏洞
-
-- 未校验用户身份
-- 权限控制缺失
-- 数据权限泄露
-
-### 6. 异常处理不足
-
-- 无错误提示
-- 无降级方案
-- 无重试机制
-- 无回滚逻辑
+# 业务风险评估指南
+
+## 概述
+
+本指南帮助 AI 评审专家系统性地识别业务类风险,确保代码实现与需求文档一致。
+
+## 评估维度
+
+### 1. 需求覆盖度检查
+
+#### 检查清单
+
+- [ ] **功能完整性**: 需求文档中的所有功能点是否都已实现
+- [ ] **验收标准**: 是否满足需求文档中的验收标准
+- [ ] **业务规则**: 代码实现是否符合业务规则
+- [ ] **边界场景**: 需求文档中提到的边界场景是否都处理了
+- [ ] **异常流程**: 异常场景是否有对应处理逻辑
+
+#### 示例
+
+**需求文档**:
+> 用户下单时必须校验库存,库存不足时显示"暂时缺货"并禁止提交订单。
+
+**代码检查**:
+```javascript
+// ✅ 正确实现
+if (stock <= 0) {
+  showError('暂时缺货');
+  disableSubmit();
+}
+
+// ❌ 风险实现 - 缺少库存校验
+submitOrder(); // 直接提交,未检查库存
+```
+
+### 2. 业务流程完整性
+
+#### 常见业务流程
+
+**电商订单流程**:
+```
+浏览商品 → 加入购物车 → 确认订单 → 支付 → 发货 → 完成
+                ↓
+              取消订单 → 退款
+```
+
+**检查要点**:
+- 流程是否完整,有无缺失环节
+- 流程跳转是否正确
+- 异常流程是否处理(如支付失败、库存不足)
+
+#### 示例
+
+**风险场景**:
+```
+✅ 正常流程: 创建订单 → 支付 → 更新库存
+❌ 缺失流程: 支付失败 → 无处理逻辑
+```
+
+### 3. 状态流转一致性
+
+#### 常见状态机
+
+**订单状态流转**:
+```
+待支付 → 已支付 → 待发货 → 已发货 → 已完成
+  ↓                        ↓
+取消                     退款中 → 已退款
+```
+
+**检查要点**:
+- 状态流转是否符合需求文档
+- 是否存在非法状态跳转
+- 状态变更是否有对应业务逻辑
+
+#### 示例
+
+**风险场景**:
+```javascript
+// ❌ 风险: 状态从"待支付"直接跳到"已完成"
+order.status = 'completed'; // 缺少"已支付"状态
+
+// ✅ 正确: 按流程流转
+if (order.status === 'pending_payment' && payment.success) {
+  order.status = 'paid';
+  // 后续流程...
+}
+```
+
+### 4. 数据一致性
+
+#### 检查要点
+
+- **事务性**: 多个数据操作是否在同一事务中
+- **并发控制**: 是否存在并发安全问题
+- **数据校验**: 输入数据是否符合业务约束
+- **数据关联**: 关联数据是否同步更新
+
+#### 示例
+
+**风险场景**:
+```javascript
+// ❌ 风险: 库存扣减与订单创建不在同一事务
+await createOrder(orderData);
+await deductStock(productId, quantity);
+// 如果 createOrder 成功但 deductStock 失败,数据不一致
+
+// ✅ 正确: 使用事务
+await db.transaction(async (tx) => {
+  await createOrder(tx, orderData);
+  await deductStock(tx, productId, quantity);
+});
+```
+
+### 5. 权限与合规
+
+#### 检查要点
+
+- **身份认证**: 操作前是否校验用户身份
+- **权限控制**: 用户是否有权限执行该操作
+- **数据权限**: 用户只能访问自己的数据
+- **合规要求**: 是否符合法律法规(如隐私保护)
+
+#### 示例
+
+**风险场景**:
+```javascript
+// ❌ 风险: 未校验权限即可删除订单
+async function deleteOrder(orderId) {
+  await api.delete(`/orders/${orderId}`);
+}
+
+// ✅ 正确: 校验权限
+async function deleteOrder(orderId) {
+  const order = await getOrder(orderId);
+  if (order.userId !== currentUser.id) {
+    throw new Error('无权限操作');
+  }
+  await api.delete(`/orders/${orderId}`);
+}
+```
+
+### 6. 异常场景处理
+
+#### 常见异常场景
+
+- **网络异常**: 请求失败、超时、重试
+- **业务异常**: 库存不足、余额不足、状态不符
+- **系统异常**: 服务不可用、数据库连接失败
+- **用户异常**: 用户取消、用户退出
+
+#### 检查要点
+
+- 是否有错误提示
+- 是否有降级方案
+- 是否有重试机制
+- 是否有回滚逻辑
+
+#### 示例
+
+**风险场景**:
+```javascript
+// ❌ 风险: 支付失败无处理
+async function handlePayment() {
+  const result = await pay();
+  // 如果支付失败,无任何提示
+}
+
+// ✅ 正确: 完整的异常处理
+async function handlePayment() {
+  try {
+    const result = await pay();
+    if (result.success) {
+      showSuccess('支付成功');
+      navigateToOrderDetail();
+    } else {
+      showError(result.message);
+      enableRetry();
+    }
+  } catch (error) {
+    showError('支付失败,请重试');
+    enableRetry();
+    logError(error);
+  }
+}
+```
+
+## 风险等级判定标准
+
+### 🔴 严重(Critical)
+
+**判定标准**:
+- 缺失核心功能点
+- 业务流程错误
+- 数据一致性问题
+- 安全合规问题
+
+**处理建议**: 必须修复后才能上线
+
+### 🟡 警告(Warning)
+
+**判定标准**:
+- 缺少异常场景处理
+- 边界条件遗漏
+- 状态流转不完整
+- 用户体验问题
+
+**处理建议**: 建议修复后上线
+
+### 🔵 建议(Suggestion)
+
+**判定标准**:
+- 体验优化
+- 流程改进
+- 性能优化
+- 代码重构
+
+**处理建议**: 可在后续迭代中处理
+
+## 需求文档解析要点
+
+### 提取关键信息
+
+1. **业务目标**: 为什么要做这个功能
+2. **功能清单**: 需要实现哪些功能
+3. **业务规则**: 有什么约束条件
+4. **验收标准**: 怎样算完成
+5. **边界场景**: 有哪些特殊情况
+6. **异常流程**: 出错时怎么处理
+
+### 映射到代码
+
+| 需求文档内容 | 代码检查点 |
+|-------------|-----------|
+| "必须校验库存" | 库存校验逻辑 |
+| "支付失败显示错误提示" | 支付异常处理 |
+| "仅管理员可删除" | 权限校验 |
+| "3秒无响应显示loading" | loading 状态管理 |
+| "支持批量操作" | 批量处理逻辑 |
+
+## 输出格式要求
+
+每个业务风险必须包含:
+
+```markdown
+### [风险标题]
+
+**风险等级**: 🔴 严重 / 🟡 警告 / 🔵 建议
+**需求来源**: 需求文档章节引用
+**影响范围**: 影响的业务场景
+**问题描述**: 详细说明风险
+**修复建议**: 具体的修复方案
+**示例代码**: 修复后的代码示例(可选)
+```
+
+## 常见业务风险模式
+
+### 1. 缺失功能
+
+- 需求文档要求的功能未实现
+- 只实现了正常流程,缺少异常流程
+- 只实现了主流程,缺少分支流程
+
+### 2. 流程错误
+
+- 流程顺序错误
+- 缺少必要的流程环节
+- 流程跳转逻辑错误
+
+### 3. 状态管理混乱
+
+- 状态定义不完整
+- 状态流转不合法
+- 状态变更无业务逻辑支撑
+
+### 4. 数据不一致
+
+- 关联数据未同步
+- 操作非原子性
+- 缺少数据校验
+
+### 5. 权限漏洞
+
+- 未校验用户身份
+- 权限控制缺失
+- 数据权限泄露
+
+### 6. 异常处理不足
+
+- 无错误提示
+- 无降级方案
+- 无重试机制
+- 无回滚逻辑