@tinkcarlos/skillora 0.2.0

package/.claude/skills/code-review/references/logic-completeness.md

@@ -0,0 +1,535 @@
+# 逻辑完整性检查清单 (Logic Completeness Checklist)
+
+> **核心原则**: 每个功能必须形成完整闭环，不能有逻辑断点或死路。
+
+---
+
+## 🔴 什么是逻辑闭环
+
+### 定义
+
+逻辑闭环指：**从用户发起操作到获得最终反馈的完整路径，每个分支都有明确的处理和响应。**
+
+```
+用户操作 → 输入验证 → 业务处理 → 结果反馈
+    ↓           ↓           ↓           ↓
+  有响应     有错误提示   有异常处理   有成功/失败提示
+```
+
+### 逻辑不闭环的典型表现
+
+| 问题 | 表现 | 用户体验 |
+|------|------|----------|
+| 无响应 | 点击按钮没反应 | 不知道发生了什么 |
+| 无错误提示 | 操作失败但没提示 | 以为成功了 |
+| 无加载状态 | 等待时页面空白 | 以为卡死了 |
+| 无边界处理 | 空数据时报错 | 看到错误页面 |
+| 无异常恢复 | 出错后无法继续 | 只能刷新页面 |
+
+---
+
+## 📋 Phase 1: 条件分支完整性检查
+
+### 1.1 if-else 完整性
+
+```typescript
+// ❌ 不完整：缺少 else 分支
+function getStatus(code: number): string {
+  if (code === 200) {
+    return 'success';
+  }
+  if (code === 404) {
+    return 'not found';
+  }
+  // code 是其他值时返回 undefined！
+}
+
+// ✅ 完整：所有情况都处理
+function getStatus(code: number): string {
+  if (code === 200) {
+    return 'success';
+  }
+  if (code === 404) {
+    return 'not found';
+  }
+  return 'unknown';  // 默认情况
+}
+
+// ✅ 更好：使用 switch + default
+function getStatus(code: number): string {
+  switch (code) {
+    case 200: return 'success';
+    case 404: return 'not found';
+    case 500: return 'server error';
+    default: return 'unknown';
+  }
+}
+```
+
+**检查清单**:
+| # | 检查项 | 通过标准 | 结果 |
+|---|--------|----------|------|
+| 1.1.1 | 每个 if 是否有对应处理 | 所有分支都有返回值或副作用 | ⬜ |
+| 1.1.2 | 是否有 else/default | 处理了所有可能情况 | ⬜ |
+| 1.1.3 | 条件是否互斥完备 | 不会遗漏任何情况 | ⬜ |
+
+### 1.2 switch-case 完整性
+
+```typescript
+// ❌ 不完整：缺少 default
+function handleAction(action: string) {
+  switch (action) {
+    case 'create':
+      return createItem();
+    case 'update':
+      return updateItem();
+    // 其他 action 会静默失败！
+  }
+}
+
+// ✅ 完整：有 default 处理
+function handleAction(action: string) {
+  switch (action) {
+    case 'create':
+      return createItem();
+    case 'update':
+      return updateItem();
+    case 'delete':
+      return deleteItem();
+    default:
+      throw new Error(`Unknown action: ${action}`);
+      // 或 return { error: 'Unknown action' };
+  }
+}
+```
+
+**检查清单**:
+| # | 检查项 | 通过标准 | 结果 |
+|---|--------|----------|------|
+| 1.2.1 | switch 是否有 default | 必须有 default 分支 | ⬜ |
+| 1.2.2 | default 是否有意义 | 不是空的或只有 break | ⬜ |
+| 1.2.3 | 是否处理了所有枚举值 | 枚举类型全覆盖 | ⬜ |
+
+### 1.3 三元运算符完整性
+
+```typescript
+// ❌ 不完整：嵌套三元难以理解
+const result = a ? b ? c : d : e ? f : g;  // 什么鬼？
+
+// ✅ 完整：简单的三元
+const status = isLoading ? 'loading' : 'ready';
+
+// ✅ 复杂情况用 if-else 或 switch
+function getStatus(state: State): string {
+  if (state.isLoading) return 'loading';
+  if (state.isError) return 'error';
+  if (state.isEmpty) return 'empty';
+  return 'ready';
+}
+```
+
+---
+
+## 📋 Phase 2: 异常处理完整性检查
+
+### 2.1 try-catch 完整性
+
+```typescript
+// ❌ 不完整：catch 后没有处理
+async function fetchData() {
+  try {
+    const data = await api.getData();
+    return data;
+  } catch (error) {
+    console.log(error);  // 只打印，没有处理！
+    // 返回 undefined，调用方不知道失败了
+  }
+}
+
+// ✅ 完整：catch 有明确处理
+async function fetchData() {
+  try {
+    const data = await api.getData();
+    return { success: true, data };
+  } catch (error) {
+    logger.error('Failed to fetch data', error);
+    return { success: false, error: error.message };
+    // 或 throw new CustomError('Failed to fetch data', error);
+  }
+}
+```
+
+**检查清单**:
+| # | 检查项 | 通过标准 | 结果 |
+|---|--------|----------|------|
+| 2.1.1 | catch 是否有实际处理 | 不只是 console.log | ⬜ |
+| 2.1.2 | 错误是否向上传递 | 调用方能知道失败 | ⬜ |
+| 2.1.3 | 是否有 finally 清理 | 资源正确释放 | ⬜ |
+
+### 2.2 Promise 错误处理
+
+```typescript
+// ❌ 不完整：Promise 错误未处理
+function loadData() {
+  api.getData().then(data => {
+    setData(data);
+  });
+  // 如果失败，错误被吞掉！
+}
+
+// ✅ 完整：有 catch 处理
+function loadData() {
+  api.getData()
+    .then(data => {
+      setData(data);
+    })
+    .catch(error => {
+      setError(error.message);
+      toast.error('加载失败');
+    });
+}
+
+// ✅ 使用 async/await
+async function loadData() {
+  try {
+    const data = await api.getData();
+    setData(data);
+  } catch (error) {
+    setError(error.message);
+    toast.error('加载失败');
+  }
+}
+```
+
+**检查清单**:
+| # | 检查项 | 通过标准 | 结果 |
+|---|--------|----------|------|
+| 2.2.1 | Promise 是否有 .catch() | 所有 Promise 都处理错误 | ⬜ |
+| 2.2.2 | async 函数是否有 try-catch | 异步错误被捕获 | ⬜ |
+| 2.2.3 | 错误是否有用户提示 | 用户知道发生了什么 | ⬜ |
+
+---
+
+## 📋 Phase 3: 状态流转完整性检查
+
+### 3.1 状态机完整性
+
+```typescript
+// ❌ 不完整：状态转换不完整
+type OrderStatus = 'pending' | 'paid' | 'shipped' | 'delivered' | 'cancelled';
+
+function updateStatus(current: OrderStatus, action: string): OrderStatus {
+  if (action === 'pay' && current === 'pending') {
+    return 'paid';
+  }
+  if (action === 'ship' && current === 'paid') {
+    return 'shipped';
+  }
+  // 其他情况返回 undefined！
+  // cancelled 状态无法处理！
+}
+
+// ✅ 完整：所有状态转换都定义
+const transitions: Record<OrderStatus, Record<string, OrderStatus>> = {
+  pending: { pay: 'paid', cancel: 'cancelled' },
+  paid: { ship: 'shipped', refund: 'cancelled' },
+  shipped: { deliver: 'delivered', return: 'cancelled' },
+  delivered: { return: 'cancelled' },
+  cancelled: {},  // 终态，无法转换
+};
+
+function updateStatus(current: OrderStatus, action: string): OrderStatus {
+  const nextStatus = transitions[current]?.[action];
+  if (!nextStatus) {
+    throw new Error(`Invalid transition: ${current} -> ${action}`);
+  }
+  return nextStatus;
+}
+```
+
+**检查清单**:
+| # | 检查项 | 通过标准 | 结果 |
+|---|--------|----------|------|
+| 3.1.1 | 是否定义了所有状态 | 状态枚举完整 | ⬜ |
+| 3.1.2 | 是否定义了所有转换 | 每个状态的出边完整 | ⬜ |
+| 3.1.3 | 是否有非法转换处理 | 非法转换有错误提示 | ⬜ |
+| 3.1.4 | 是否有终态 | 流程能正常结束 | ⬜ |
+
+### 3.2 UI 状态完整性
+
+```typescript
+// ❌ 不完整：缺少状态
+function UserList() {
+  const [users, setUsers] = useState([]);
+
+  useEffect(() => {
+    api.getUsers().then(setUsers);
+  }, []);
+
+  return (
+    <ul>
+      {users.map(user => <li key={user.id}>{user.name}</li>)}
+    </ul>
+  );
+  // 加载中显示空白！
+  // 加载失败显示空白！
+  // 空数据显示空白！
+}
+
+// ✅ 完整：所有状态都处理
+function UserList() {
+  const [users, setUsers] = useState<User[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    setLoading(true);
+    setError(null);
+    api.getUsers()
+      .then(setUsers)
+      .catch(e => setError(e.message))
+      .finally(() => setLoading(false));
+  }, []);
+
+  if (loading) return <Spinner />;
+  if (error) return <ErrorMessage message={error} onRetry={refetch} />;
+  if (users.length === 0) return <EmptyState message="暂无用户" />;
+
+  return (
+    <ul>
+      {users.map(user => <li key={user.id}>{user.name}</li>)}
+    </ul>
+  );
+}
+```
+
+**检查清单**:
+| # | 检查项 | 通过标准 | 结果 |
+|---|--------|----------|------|
+| 3.2.1 | 是否有 loading 状态 | 加载时有提示 | ⬜ |
+| 3.2.2 | 是否有 error 状态 | 错误时有提示 | ⬜ |
+| 3.2.3 | 是否有 empty 状态 | 空数据时有提示 | ⬜ |
+| 3.2.4 | 是否有 success 状态 | 成功时有反馈 | ⬜ |
+
+---
+
+## 📋 Phase 4: 数据流完整性检查
+
+### 4.1 输入验证完整性
+
+```typescript
+// ❌ 不完整：没有验证
+function createUser(data: any) {
+  return db.insert('users', data);  // 任何数据都能插入！
+}
+
+// ✅ 完整：全面验证
+function createUser(data: CreateUserInput) {
+  // 必填验证
+  if (!data.email) throw new ValidationError('Email is required');
+  if (!data.password) throw new ValidationError('Password is required');
+
+  // 格式验证
+  if (!isValidEmail(data.email)) throw new ValidationError('Invalid email format');
+  if (data.password.length < 8) throw new ValidationError('Password too short');
+
+  // 业务验证
+  const existing = await db.findByEmail(data.email);
+  if (existing) throw new ValidationError('Email already exists');
+
+  // 数据清理
+  const cleanData = {
+    email: data.email.toLowerCase().trim(),
+    password: hashPassword(data.password),
+    name: sanitize(data.name),
+  };
+
+  return db.insert('users', cleanData);
+}
+```
+
+**检查清单**:
+| # | 检查项 | 通过标准 | 结果 |
+|---|--------|----------|------|
+| 4.1.1 | 必填字段是否验证 | 所有必填都检查 | ⬜ |
+| 4.1.2 | 格式是否验证 | 邮箱/手机等格式正确 | ⬜ |
+| 4.1.3 | 边界是否验证 | 长度/范围限制 | ⬜ |
+| 4.1.4 | 业务规则是否验证 | 唯一性等业务约束 | ⬜ |
+
+### 4.2 空值处理完整性
+
+```typescript
+// ❌ 不完整：没有空值处理
+function getUserName(user: User | null): string {
+  return user.name;  // user 为 null 时报错！
+}
+
+// ✅ 完整：处理空值
+function getUserName(user: User | null): string {
+  if (!user) return 'Unknown';
+  return user.name || 'Anonymous';
+}
+
+// ✅ 使用可选链
+function getUserName(user: User | null): string {
+  return user?.name ?? 'Unknown';
+}
+```
+
+**检查清单**:
+| # | 检查项 | 通过标准 | 结果 |
+|---|--------|----------|------|
+| 4.2.1 | null 是否处理 | 不会因 null 报错 | ⬜ |
+| 4.2.2 | undefined 是否处理 | 不会因 undefined 报错 | ⬜ |
+| 4.2.3 | 空字符串是否处理 | 空字符串有默认值 | ⬜ |
+| 4.2.4 | 空数组是否处理 | 空数组不会报错 | ⬜ |
+
+### 4.3 边界值处理完整性
+
+```typescript
+// ❌ 不完整：没有边界处理
+function getPage(items: Item[], page: number, pageSize: number): Item[] {
+  const start = page * pageSize;
+  return items.slice(start, start + pageSize);
+  // page 为负数时？
+  // page 超出范围时？
+  // pageSize 为 0 时？
+}
+
+// ✅ 完整：处理边界
+function getPage(items: Item[], page: number, pageSize: number): Item[] {
+  // 参数验证
+  if (page < 0) page = 0;
+  if (pageSize <= 0) pageSize = 10;
+  if (pageSize > 100) pageSize = 100;  // 最大限制
+
+  const totalPages = Math.ceil(items.length / pageSize);
+  if (page >= totalPages) page = Math.max(0, totalPages - 1);
+
+  const start = page * pageSize;
+  return items.slice(start, start + pageSize);
+}
+```
+
+**检查清单**:
+| # | 检查项 | 通过标准 | 结果 |
+|---|--------|----------|------|
+| 4.3.1 | 负数是否处理 | 负数有合理处理 | ⬜ |
+| 4.3.2 | 零是否处理 | 零值有合理处理 | ⬜ |
+| 4.3.3 | 最大值是否处理 | 超大值有限制 | ⬜ |
+| 4.3.4 | 越界是否处理 | 数组越界不报错 | ⬜ |
+
+---
+
+## 📋 Phase 5: 用户反馈完整性检查
+
+### 5.1 操作反馈完整性
+
+```typescript
+// ❌ 不完整：没有反馈
+async function deleteItem(id: string) {
+  await api.delete(id);
+  // 用户不知道删除成功了没有
+}
+
+// ✅ 完整：有明确反馈
+async function deleteItem(id: string) {
+  try {
+    setDeleting(true);
+    await api.delete(id);
+    toast.success('删除成功');
+    refreshList();
+  } catch (error) {
+    toast.error(`删除失败: ${error.message}`);
+  } finally {
+    setDeleting(false);
+  }
+}
+```
+
+**检查清单**:
+| # | 检查项 | 通过标准 | 结果 |
+|---|--------|----------|------|
+| 5.1.1 | 操作中是否有提示 | loading/进度条 | ⬜ |
+| 5.1.2 | 成功是否有提示 | toast/消息/跳转 | ⬜ |
+| 5.1.3 | 失败是否有提示 | 错误信息清晰 | ⬜ |
+| 5.1.4 | 是否可以重试 | 失败后能重试 | ⬜ |
+
+### 5.2 确认操作完整性
+
+```typescript
+// ❌ 不完整：危险操作没有确认
+<button onClick={() => deleteAccount()}>删除账户</button>
+
+// ✅ 完整：有确认步骤
+<button onClick={() => setShowConfirm(true)}>删除账户</button>
+
+{showConfirm && (
+  <ConfirmDialog
+    title="确认删除账户？"
+    message="此操作不可恢复，所有数据将被永久删除。"
+    confirmText="确认删除"
+    cancelText="取消"
+    onConfirm={deleteAccount}
+    onCancel={() => setShowConfirm(false)}
+  />
+)}
+```
+
+**检查清单**:
+| # | 检查项 | 通过标准 | 结果 |
+|---|--------|----------|------|
+| 5.2.1 | 删除操作是否有确认 | 有二次确认 | ⬜ |
+| 5.2.2 | 不可逆操作是否有警告 | 明确告知后果 | ⬜ |
+| 5.2.3 | 批量操作是否有确认 | 显示影响范围 | ⬜ |
+
+---
+
+## 📊 逻辑完整性检查汇总
+
+```markdown
+## 逻辑完整性审查结果
+
+### 条件分支检查
+| 检查项 | 数量 | 通过 | 问题 |
+|--------|------|------|------|
+| if-else 完整性 | | | |
+| switch-default | | | |
+| 三元运算符 | | | |
+
+### 异常处理检查
+| 检查项 | 数量 | 通过 | 问题 |
+|--------|------|------|------|
+| try-catch 完整性 | | | |
+| Promise 错误处理 | | | |
+| 错误用户提示 | | | |
+
+### 状态流转检查
+| 检查项 | 数量 | 通过 | 问题 |
+|--------|------|------|------|
+| 状态机完整性 | | | |
+| UI 状态完整性 | | | |
+
+### 数据流检查
+| 检查项 | 数量 | 通过 | 问题 |
+|--------|------|------|------|
+| 输入验证 | | | |
+| 空值处理 | | | |
+| 边界值处理 | | | |
+
+### 用户反馈检查
+| 检查项 | 数量 | 通过 | 问题 |
+|--------|------|------|------|
+| 操作反馈 | | | |
+| 确认操作 | | | |
+
+### 问题列表
+| # | 文件:行号 | 问题类型 | 描述 | 严重级别 |
+|---|-----------|----------|------|----------|
+| 1 | | | | |
+| 2 | | | | |
+
+### 判定
+- [ ] **通过** - 逻辑完整闭环
+- [ ] **不通过** - 存在逻辑断点，需修复
+```