mirror of
https://github.com/NoFxAiOS/nofx.git
synced 2025-12-06 13:54:41 +08:00
chore: remove .claude directory
This commit is contained in:
tinkle-community
@@ -1,329 +0,0 @@
|
||||
---
|
||||
name: code-review
|
||||
description: 通用代码审查命令，基于业务需求进行白盒逻辑正确性审查和技术架构评估
|
||||
---
|
||||
|
||||
# 代码审查命令
|
||||
|
||||
## 审查任务
|
||||
|
||||
请对当前工作区的代码修改进行全面审查，重点关注业务逻辑的正确性和技术架构的合理性。
|
||||
|
||||
## 审查维度
|
||||
|
||||
### 1. 业务层面审查（BLOCKING级别）
|
||||
- **需求来源验证**：寻找并验证业务需求来源（不能基于代码反推需求）
|
||||
- **需求实现完整性**：验证代码是否100%满足业务需求
|
||||
- **业务流程逻辑正确性**：检查状态转换、数据流、条件判断的逻辑
|
||||
- **数据结构正确性**：验证模型定义、字段约束、业务规则映射
|
||||
- **Edge Case处理**：评估边界条件和异常场景的处理合理性
|
||||
|
||||
### 2. 技术层面审查
|
||||
- **架构合理性**：模块化、职责分离、依赖关系
|
||||
- **KISS原则遵循**：避免过度工程化
|
||||
- **扩展性评估**：未来功能添加的容易程度
|
||||
- **非Adhoc修改验证**：是否遵循现有代码模式
|
||||
- **性能问题检测**：查找明显的性能问题（如N+1查询等）
|
||||
- **单元测试完备性**：核心逻辑90%覆盖率要求
|
||||
|
||||
### 3. 契约与连通性专项检查（BLOCKING）
|
||||
- 端点一致性：前端端点集中配置；路径/动态段/大小写/末尾分隔符与后端路由完全一致；HTTP 方法语义匹配（幂等/副作用）。
|
||||
- 认证与跨域：统一的认证机制（会话/令牌）；前端传递方式与后端期望一致（Cookie/Authorization 等）；跨域与 CSRF 策略匹配。
|
||||
- 请求/响应 Schema：字段名、类型、必选/可选一致；时间/数值/布尔的编码一致；分页/排序参数与响应元信息对齐。
|
||||
- 错误与状态码：4xx/5xx 使用合理；错误负载结构稳定且可解析；前端根据错误类型提供可恢复提示。
|
||||
- 异步/事件（如有）：事件类型与载荷字段与文档一致；开始/结束/错误/心跳等语义完整；增量合并无丢失/重复；存在降级路径。
|
||||
- 端到端透传：API→Service→下游（存储/第三方）参数（上下文/会话/区域/幂等键）无遗漏；写操作具备幂等/去重策略。
|
||||
- 日志与隐私：日志含必要上下文（追踪/用户/会话），敏感信息脱敏；UI 默认不展示内部实现细节。
|
||||
|
||||
#### 全链路 Contract Crosswalk（必做）
|
||||
- 选取关键用户流，建立“参数对齐矩阵”：
|
||||
- 前端请求 → 后端路由/处理 → 服务层 → 下游（存储/第三方）→ 持久化字段。
|
||||
- 列出每个参数：`name | type | required | default | source-of-truth(文件:行)`。
|
||||
- 如存在事件/流式契约，补充事件类型与载荷字段，以及必要的状态回写。
|
||||
- 输出差异点与最小修复建议（谁改、改哪、如何不破坏现有行为）。
|
||||
|
||||
### 4. 高发问题清单（优先排查）
|
||||
- 命名错位：不同层对同一概念使用了不同命名风格或名称（例如 `camelCase` ↔ `snake_case`、标识符命名不一致）。
|
||||
- 路径错位：端点路径或动态段命名不一致；末尾分隔符导致重定向或方法失败。
|
||||
- 类型漂移：数字/字符串/布尔/时间类型在层间编码不一致或未正确转换。
|
||||
- 认证混用：请求在不同处使用了不同认证方式；跨域请求未按需携带凭证；CSRF 保护缺失。
|
||||
- 事件缺口：后端新增事件类型或字段未在前端解析；增量合并逻辑导致重复/丢失。
|
||||
- 可见性/状态：后端状态位或可见性字段被忽略，导致 UI 展示与真实状态不一致。
|
||||
|
||||
### 5. 零假设验证（VERIFY-FIRST Gate，BLOCKING）
|
||||
- 禁止基于“猜测的字段/API/事件”写逻辑。每个关键元素必须给出证据：
|
||||
- 模型/字段定义位置（文件:行）
|
||||
- 路由/处理方法签名（文件:行）
|
||||
- 前端类型/解析/调用代码（文件:行）
|
||||
- 无证据的假设一律不通过。
|
||||
|
||||
### 6. 用户视角 E2E 可见性审计（BLOCKING）
|
||||
⚠️ **这是最关键的检查** - "代码完美但功能不工作"的主要原因就是跳过了这一步！
|
||||
|
||||
**MANDATORY USER FLOW VERIFICATION (必须执行):**
|
||||
- **完整点击路径追踪**：从用户点击开始，逐步追踪到最终状态
|
||||
- 用户点击X → 调用函数Y → 导航到页面Z → 显示内容W
|
||||
- **必须验证每个步骤都正确执行**
|
||||
- **URL路由验证**：所有导航路径在路由配置中存在且正确处理参数
|
||||
- **状态传递验证**：点击后的状态变化是否正确反映在UI中
|
||||
- **错误场景测试**：参数缺失、网络错误、权限不足等场景的处理
|
||||
|
||||
**具体检查项目:**
|
||||
- 入口可见：对应功能的入口（按钮/导航/控件）在默认场景与目标设备上可达；不被误判条件隐藏。
|
||||
- **链接落地（核心）**：页面路由/回跳/深链接一致；从入口到完成形成闭环。
|
||||
- 点击通知 → 是否真的跳转到预期页面？
|
||||
- 分享链接 → 是否真的加载预期内容？
|
||||
- 所有导航路径都必须实际追踪验证！
|
||||
- 状态完整：加载/空数据/错误/权限不足 均有清晰呈现与可恢复路径。
|
||||
- 角色/开关：与权限/Feature Flag 的可见性符合预期；默认值不阻断主流程。
|
||||
|
||||
**⛔ 禁止行为:**
|
||||
- ❌ 只看代码结构，不追踪实际执行流程
|
||||
- ❌ 假设navigate()调用就等于用户到达了目标页面
|
||||
- ❌ 不验证URL参数处理逻辑
|
||||
- ❌ 说"看起来正确"而不验证"实际正确"
|
||||
|
||||
### 7. Web3 AI 交易系统安全审查（BLOCKING 级别）
|
||||
🔐 **资金安全是生死线** - 一个安全漏洞可能导致所有资金损失！
|
||||
|
||||
#### 7.1 私钥与密钥管理（CRITICAL）
|
||||
- **零泄露原则**：
|
||||
- ❌ 禁止：私钥/助记词出现在日志、错误消息、前端代码、Git 历史中
|
||||
- ❌ 禁止：明文存储私钥（环境变量、配置文件、数据库）
|
||||
- ✅ 必需：使用硬件钱包、HSM、或加密密钥管理服务（AWS KMS/Vault）
|
||||
- ✅ 必需：API Key、密钥材料必须加密存储，运行时解密
|
||||
- **最小权限原则**：
|
||||
- 交易签名密钥与只读查询密钥分离
|
||||
- 每个功能使用独立的子账户/权限
|
||||
- 定期轮换 API Key 和访问令牌
|
||||
- **验证检查**：
|
||||
- [ ] grep 搜索 `private_key`、`mnemonic`、`seed` 等关键词，确保无硬编码
|
||||
- [ ] 检查所有密钥存储位置的加密状态
|
||||
- [ ] 验证密钥访问日志和审计追踪
|
||||
|
||||
#### 7.2 交易安全（CRITICAL）
|
||||
- **签名验证**：
|
||||
- ✅ 必需：所有交易必须经过签名验证
|
||||
- ✅ 必需：验证交易发起者身份（防止伪造）
|
||||
- ✅ 必需：使用 nonce/序列号防止重放攻击
|
||||
- **交易参数验证**：
|
||||
- ✅ 必需：验证接收地址合法性（checksum、白名单）
|
||||
- ✅ 必需：金额/价格/滑点限制（防止异常大额交易）
|
||||
- ✅ 必需：Gas Price/Gas Limit 上限保护（防止 Gas 耗尽攻击）
|
||||
- ✅ 必需：Deadline/超时保护（防止过期交易执行）
|
||||
- **滑点与价格保护**：
|
||||
- ✅ 必需：设置合理的滑点容忍度（如 0.5%-2%）
|
||||
- ✅ 必需：价格预言机验证（多源对比、时间戳检查）
|
||||
- ✅ 必需：异常价格波动拒绝交易
|
||||
- **验证检查**：
|
||||
- [ ] 所有交易调用都有 nonce 或幂等键
|
||||
- [ ] 金额/价格参数都有上下限验证
|
||||
- [ ] Gas 费用有最大限制
|
||||
- [ ] 滑点保护代码存在且正确
|
||||
|
||||
#### 7.3 AI 决策安全（CRITICAL）
|
||||
- **提示注入防护**：
|
||||
- ❌ 禁止：直接将用户输入拼接到 AI prompt 中
|
||||
- ✅ 必需：用户输入消毒/转义（防止 prompt injection）
|
||||
- ✅ 必需：系统提示与用户输入明确分离（使用角色隔离）
|
||||
- ✅ 必需：敏感操作需要用户明确确认，AI 不能自主决定大额交易
|
||||
- **决策审计**：
|
||||
- ✅ 必需：记录所有 AI 决策的完整上下文（输入、输出、时间戳、模型版本）
|
||||
- ✅ 必需：决策可追溯、可回放、可审计
|
||||
- ✅ 必需：异常决策告警（如突然的大额交易建议）
|
||||
- **模型安全**：
|
||||
- ✅ 必需：使用官方 API，避免第三方代理（防止中间人攻击）
|
||||
- ✅ 必需：API 响应验证（检测异常输出、格式错误）
|
||||
- ✅ 必需：模型输出不直接执行，必须经过参数验证
|
||||
- **验证检查**：
|
||||
- [ ] 搜索用户输入拼接点，确保有消毒处理
|
||||
- [ ] 检查决策日志是否完整（包含所有关键参数）
|
||||
- [ ] 验证大额交易需要额外确认机制
|
||||
|
||||
#### 7.4 智能合约交互安全（CRITICAL）
|
||||
- **授权范围控制**：
|
||||
- ❌ 禁止：无限授权（`approve(spender, type(uint256).max)`）
|
||||
- ✅ 必需：按需授权，每次交易前计算精确授权额度
|
||||
- ✅ 必需：定期清理过期授权
|
||||
- ✅ 必需：监控授权事件，异常授权告警
|
||||
- **合约调用验证**：
|
||||
- ✅ 必需：合约地址白名单（只与已审计合约交互）
|
||||
- ✅ 必需：函数选择器验证（防止调用错误函数）
|
||||
- ✅ 必需：调用参数类型/范围验证
|
||||
- ✅ 必需：模拟执行（dry-run）后再真实执行
|
||||
- **重入与异常处理**：
|
||||
- ✅ 必需：处理合约调用失败情况（revert、out of gas）
|
||||
- ✅ 必需：检查返回值，不假设调用成功
|
||||
- ✅ 必需：避免在外部调用后修改关键状态（防重入）
|
||||
- **验证检查**：
|
||||
- [ ] grep `approve` 确保无无限授权
|
||||
- [ ] 所有合约地址来自配置/白名单，无硬编码
|
||||
- [ ] 调用失败有完整的错误处理和回退逻辑
|
||||
|
||||
#### 7.5 资金保护机制（BLOCKING）
|
||||
- **限额控制**：
|
||||
- ✅ 必需：单笔交易金额上限（如 $1000）
|
||||
- ✅ 必需：日/周/月累计限额
|
||||
- ✅ 必需：异常交易频率限制（防止快速耗尽资金）
|
||||
- ✅ 必需：大额交易需要多重签名或延迟执行
|
||||
- **紧急暂停**：
|
||||
- ✅ 必需：全局紧急停止按钮（kill switch）
|
||||
- ✅ 必需：异常检测自动暂停（如价格异常、Gas 费暴涨）
|
||||
- ✅ 必需：暂停后资金安全提取机制
|
||||
- **余额监控**：
|
||||
- ✅ 必需：实时余额监控，低于阈值告警
|
||||
- ✅ 必需：异常资金流出告警（大额转出、未知接收方）
|
||||
- ✅ 必需：定期对账（链上余额 vs 系统记录）
|
||||
- **验证检查**：
|
||||
- [ ] 限额配置存在且合理
|
||||
- [ ] 紧急暂停功能可测试且有权限控制
|
||||
- [ ] 余额监控代码存在且接入告警系统
|
||||
|
||||
#### 7.6 链上数据验证（CRITICAL）
|
||||
- **预言机安全**：
|
||||
- ❌ 禁止：单一数据源（可被操纵）
|
||||
- ✅ 必需：多预言机对比（Chainlink、Band、UMA 等）
|
||||
- ✅ 必需：价格偏差检测（多源价格差异超阈值拒绝）
|
||||
- ✅ 必需：时间戳验证（数据新鲜度检查，拒绝过期数据）
|
||||
- **区块确认**：
|
||||
- ✅ 必需：等待足够的区块确认（主网建议 ≥12 块，L2 根据实际情况）
|
||||
- ✅ 必需：处理链重组可能（pending → confirmed → finalized）
|
||||
- ✅ 必需：交易回执验证（status=1 成功）
|
||||
- **数据完整性**：
|
||||
- ✅ 必需：事件日志完整性检查（topic、参数匹配）
|
||||
- ✅ 必需：合约状态一致性验证（链上 vs 本地缓存）
|
||||
- ✅ 必需：MEV 保护（使用私有内存池或 Flashbots）
|
||||
- **验证检查**：
|
||||
- [ ] 价格数据来自多个预言机
|
||||
- [ ] 区块确认数配置合理
|
||||
- [ ] 交易状态检查包含 finalized 状态
|
||||
|
||||
## 审查结果
|
||||
|
||||
请给出以下三种结果之一：
|
||||
- ✅ **通过**：可以直接提交
|
||||
- ❌ **不通过**：存在BLOCKING问题，必须修复
|
||||
- ⚠️ **需要修复**：有改进空间，建议修复
|
||||
|
||||
## 核心原则
|
||||
|
||||
1. **白盒逻辑正确性是根本**：业务逻辑错误是生死线
|
||||
2. **需求驱动**：必须找到真实需求来源
|
||||
3. **客观分析**：基于实际代码和需求，不自我欺骗
|
||||
4. **actionable建议**：提供具体的修复指导
|
||||
|
||||
## 评审交付物（必须包含）
|
||||
- **问题清单**：逐条指出"谁与谁不一致"（路径/参数/字段/事件/状态码），附最小复现样本。
|
||||
- **最小修复建议**：明确"谁改、改哪里、如何不破坏现有调用"（可附 1-3 行级 diff 建议）。
|
||||
- **兼容/过渡策略**：必要时说明双解析/版本前缀/灰度开关/降级方案。
|
||||
- **🚨 E2E验证报告**：对每个用户交互流程的完整追踪验证（MANDATORY）
|
||||
|
||||
## 强制性E2E验证清单（必须逐项检查）
|
||||
在给出审查结果前，必须完成以下验证：
|
||||
|
||||
### ✅ 用户点击验证
|
||||
- [ ] 所有onClick处理器都能正确执行
|
||||
- [ ] 处理器中的navigate()调用指向正确的路径
|
||||
- [ ] 目标路径在路由配置中存在
|
||||
- [ ] 目标页面能正确处理URL参数
|
||||
|
||||
### ✅ 导航流程验证
|
||||
- [ ] 从点击到页面加载的完整路径畅通
|
||||
- [ ] URL参数正确传递和解析
|
||||
- [ ] 页面状态正确初始化
|
||||
- [ ] 用户看到预期的内容和界面
|
||||
|
||||
### ✅ 状态一致性验证
|
||||
- [ ] 点击后应用状态正确更新
|
||||
- [ ] UI界面反映状态变化
|
||||
- [ ] 没有状态不同步的问题
|
||||
|
||||
### ✅ 安全验证（Web3 AI 交易系统 - MANDATORY）
|
||||
- [ ] **密钥安全**：无私钥泄露（日志/错误/前端/Git）
|
||||
- [ ] **密钥管理**：私钥加密存储，无明文环境变量
|
||||
- [ ] **交易验证**：所有交易有签名验证、nonce、金额限制
|
||||
- [ ] **滑点保护**：价格/滑点验证存在且合理
|
||||
- [ ] **AI 安全**：用户输入有消毒处理，无直接拼接到 prompt
|
||||
- [ ] **决策审计**：AI 决策有完整日志（输入/输出/时间戳）
|
||||
- [ ] **合约安全**：无无限授权，合约地址来自白名单
|
||||
- [ ] **限额保护**：存在单笔/累计交易限额
|
||||
- [ ] **紧急机制**：有 kill switch 或暂停功能
|
||||
- [ ] **预言机安全**：价格数据来自多源，有偏差检测
|
||||
- [ ] **确认机制**：大额交易需要用户明确确认
|
||||
|
||||
### ⛔ 审查失败条件
|
||||
如果以下任一项为真，审查必须标记为❌不通过：
|
||||
|
||||
**功能性问题：**
|
||||
- 存在navigate()指向不存在或错误的路径
|
||||
- 用户点击后无法到达预期页面
|
||||
- 状态更新不完整导致UI不一致
|
||||
- 关键用户流程无法完成
|
||||
|
||||
**安全性问题（Web3 AI 系统）：**
|
||||
- 私钥/助记词出现在日志、错误消息、前端代码、Git 历史中
|
||||
- 私钥明文存储（环境变量/配置文件/数据库）
|
||||
- 交易缺少签名验证、nonce、或金额限制
|
||||
- 存在无限授权（`approve(spender, type(uint256).max)`）
|
||||
- 用户输入直接拼接到 AI prompt（prompt injection 风险）
|
||||
- AI 可以自主决定大额交易（无用户确认）
|
||||
- 缺少紧急暂停机制
|
||||
- 单一预言机数据源（可被操纵）
|
||||
- 大额交易无多重签名或延迟执行
|
||||
|
||||
**记住：代码编译通过 ≠ 功能正确工作 ≠ 资金安全**
|
||||
|
||||
## 技术验证方法（MANDATORY）
|
||||
|
||||
### 🔍 导航路径验证脚本
|
||||
执行以下检查来验证导航逻辑：
|
||||
```bash
|
||||
# 1. 找出所有navigate()调用
|
||||
grep -r "navigate(" frontend/src --include="*.tsx" --include="*.ts" -n
|
||||
|
||||
# 2. 找出所有路由定义
|
||||
grep -r "path=" frontend/src --include="*.tsx" --include="*.ts" -n
|
||||
|
||||
# 3. 检查URL参数处理
|
||||
grep -r "useSearchParams\|URLSearchParams" frontend/src --include="*.tsx" --include="*.ts" -n
|
||||
```
|
||||
|
||||
### 🔍 状态管理验证
|
||||
```bash
|
||||
# 检查状态更新逻辑
|
||||
grep -r "useState\|useEffect.*navigate" frontend/src --include="*.tsx" --include="*.ts" -n
|
||||
|
||||
# 检查onClick处理器
|
||||
grep -r "onClick.*=>" frontend/src --include="*.tsx" --include="*.ts" -n
|
||||
```
|
||||
|
||||
### 🚨 必须回答的验证问题
|
||||
对于每个用户交互，审查者必须回答：
|
||||
|
||||
1. **点击发生什么？**
|
||||
- onClick处理器具体做了什么操作？
|
||||
- 调用了哪些函数？传递了什么参数？
|
||||
|
||||
2. **导航去哪里？**
|
||||
- navigate()的目标路径是什么？
|
||||
- 这个路径在路由配置中存在吗？
|
||||
- 路径参数格式正确吗？
|
||||
|
||||
3. **目标页面做什么？**
|
||||
- 目标页面/组件如何处理URL参数？
|
||||
- 是否正确提取和使用参数？
|
||||
- 用户最终看到什么内容？
|
||||
|
||||
4. **状态是否一致？**
|
||||
- 点击后应用状态如何变化？
|
||||
- UI是否正确反映状态变化？
|
||||
- 有没有状态不同步问题？
|
||||
|
||||
**如果审查者无法回答这些问题，审查必须标记为❌不通过**
|
||||
|
||||
## 快速验证提示
|
||||
- 端点集中来源：前端禁止硬编码 URL；新增/变更端点已同步到常量/SDK。
|
||||
- 认证一致：跨域/跨端口请求按需携带凭证（Cookie/Token），不依赖未声明的自定义头。
|
||||
- 异步降级：在不支持事件/流式或网络异常时具备降级路径与用户提示。
|
||||
- 可见性扫描：关键入口在默认态与目标设备上可见；空/错误/加载可复现且可恢复。
|
||||
- 自动化检查：加入简单脚本/CI 规则检查硬编码端点、路径格式、必需认证头/凭证的使用一致性。
|
||||
Reference in New Issue
Block a user