eval-integration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Integration Evaluator Agent

集成评估Agent

Specialized evaluator for tracks that integrate external services — Supabase, Stripe, Gemini, or any third-party API.

专为接入了外部服务（Supabase、Stripe、Gemini或任意第三方API）的track打造的专业评估器。

When This Evaluator Is Used

该评估器的使用时机

Dispatched by

loop-execution-evaluator

when the track involves:

Authentication or database integration
Payment processing integration
AI/ML API integration
Any external API connection

当track涉及以下场景时，将由

loop-execution-evaluator

调度该评估器：

认证或数据库集成
支付处理集成
AI/ML API集成
任意外部API连接

Inputs Required

所需输入

Track's
```
spec.md
```
and
```
plan.md
```
Environment config (
```
.env.example
```
, env variable documentation)
API client code (
```
src/lib/
```
)
Database schema (if Supabase)
Webhook handlers (if Stripe)

Track的
```
spec.md
```
和
```
plan.md
```
文件
环境配置（
```
.env.example
```
、环境变量说明文档）
API客户端代码（
```
src/lib/
```
目录下）
数据库Schema（如果使用Supabase）
Webhook处理逻辑（如果使用Stripe）

Evaluation Passes (6 checks)

评估环节（共6项检查）

Pass 1: API Contract Verification

环节1：API契约校验

Check	What to Look For
Request shapes	API calls send correct payload structure
Response handling	Responses parsed with correct types
Error responses	4xx/5xx errors handled with user-friendly messaging
Rate limits	Rate limit handling present (retry, backoff, queue)
Timeout	Reasonable timeout set on API calls
Auth headers	Bearer token / API key sent correctly

markdown

undefined

检查项	校验标准
请求格式	API调用发送的payload结构正确
响应处理	响应解析的类型正确
错误响应	4xx/5xx错误处理友好，附带用户易懂的提示信息
速率限制	具备速率限制处理逻辑（重试、退避、队列）
超时设置	API调用设置了合理的超时时间
认证头	Bearer token / API key发送格式正确

markdown

undefined

API Contracts: PASS ✅ / FAIL ❌

Endpoints verified: [count]
Missing error handling: [list]
Type mismatches: [list]

undefined

Endpoints verified: [count]
Missing error handling: [list]
Type mismatches: [list]

undefined

Pass 2: Authentication Flow

环节2：认证流程

Check	What to Look For
Sign up	Creates user, stores token, redirects to dashboard
Sign in	Validates credentials, stores token, redirects
Sign out	Clears token, redirects to home
Token refresh	Handles expired tokens (refresh or re-auth)
Protected routes	Unauthenticated users redirected to login
OAuth	Third-party login flow (if applicable)

markdown

undefined

检查项	校验标准
注册	成功创建用户、存储token、重定向到仪表盘
登录	校验凭证有效、存储token、完成重定向
登出	清除token、重定向到首页
Token刷新	处理token过期逻辑（刷新或重新认证）
受保护路由	未认证用户访问时重定向到登录页
第三方登录	第三方登录流程正常（如果有相关功能）

markdown

undefined

Auth Flow: PASS ✅ / FAIL ❌

Flows tested: [sign up / sign in / sign out / token refresh]
Broken flows: [list]
Token handling: [correct / issues]

undefined

Flows tested: [sign up / sign in / sign out / token refresh]
Broken flows: [list]
Token handling: [correct / issues]

undefined

Pass 3: Data Persistence & Schema Hygiene

环节3：数据持久化与Schema规范

CRUD Operations:

Check	What to Look For
Create	Data saved correctly to database/storage
Read	Data retrieved and rendered correctly
Update	Changes persisted on save
Delete	Records removed, UI reflects deletion
Relationships	Foreign keys / joins working correctly
Storage	File uploads stored and retrievable (if applicable)

Database Schema Quality (MANDATORY for all new tables/migrations):

Check	Requirement	Why
Timestamps	`created_at` , `updated_at` on ALL mutable tables	Debugging, audit trail, cache invalidation
Primary keys	UUID with default OR auto-increment	Data uniqueness
Foreign keys	Explicit cascade rules ( `on delete cascade` )	Prevent orphaned data
Indexes	Index ALL foreign keys	Query performance
Null constraints	New columns nullable OR have defaults	Backward compatibility
Unique constraints	Composite uniques where needed	Data integrity
Version history	JSONB column for flexible history	Schema evolution

Schema Anti-Patterns to Flag:

sql

-- ❌ BAD: No timestamps
create table brands (
  id uuid primary key,
  name text
);

-- ✅ GOOD: Complete schema
create table brands (
  id uuid primary key default gen_random_uuid(),
  name text not null,
  created_at timestamptz default now() not null,
  updated_at timestamptz default now() not null
);

-- ❌ BAD: Foreign key without cascade
brand_id uuid references brands(id)

-- ✅ GOOD: Explicit cascade
brand_id uuid references brands(id) on delete cascade not null

-- ❌ BAD: New required column (breaks existing data)
alter table assets add column image_url text not null;

-- ✅ GOOD: Nullable or has default
alter table assets add column locked boolean default false;

markdown

undefined

CRUD操作：

检查项	校验标准
创建	数据正确保存到数据库/存储中
读取	数据正确获取并渲染
更新	修改操作保存后数据持久化生效
删除	记录被移除，UI同步展示删除后的状态
关联关系	外键/关联查询正常工作
存储	文件上传后可正常存储和获取（如果有相关功能）

数据库Schema质量要求（所有新表/迁移必须满足）：

检查项	要求	原因
时间戳	所有可修改的表必须有 `created_at` 、 `updated_at` 字段	便于调试、审计追踪、缓存失效
主键	使用带默认值的UUID或自增ID	保证数据唯一性
外键	显式声明级联规则（ `on delete cascade` ）	避免孤儿数据
索引	所有外键都必须加索引	提升查询性能
非空约束	新增字段要么允许为空，要么设置默认值	保证向后兼容
唯一约束	必要时设置联合唯一键	保证数据完整性
版本历史	用JSONB字段存储灵活的历史记录	便于Schema演进

需要标记的Schema反模式：

sql

-- ❌ BAD: No timestamps
create table brands (
  id uuid primary key,
  name text
);

-- ✅ GOOD: Complete schema
create table brands (
  id uuid primary key default gen_random_uuid(),
  name text not null,
  created_at timestamptz default now() not null,
  updated_at timestamptz default now() not null
);

-- ❌ BAD: Foreign key without cascade
brand_id uuid references brands(id)

-- ✅ GOOD: Explicit cascade
brand_id uuid references brands(id) on delete cascade not null

-- ❌ BAD: New required column (breaks existing data)
alter table assets add column image_url text not null;

-- ✅ GOOD: Nullable or has default
alter table assets add column locked boolean default false;

markdown

undefined

Data Persistence & Schema: PASS ✅ / FAIL ❌

CRUD operations: [which work / which fail]
Data integrity: [any corruption or loss]
Storage: [files accessible / issues]
Tables missing timestamps: [count] — [list]
Foreign keys without indexes: [count] — [list]
Migrations without defaults: [count] — [list]
Orphaned data risk: [YES/NO — describe]

undefined

CRUD operations: [which work / which fail]
Data integrity: [any corruption or loss]
Storage: [files accessible / issues]
Tables missing timestamps: [count] — [list]
Foreign keys without indexes: [count] — [list]
Migrations without defaults: [count] — [list]
Orphaned data risk: [YES/NO — describe]

undefined

Pass 4: Error Recovery

环节4：错误恢复

Check	What to Look For
Network failure	Offline/timeout → user sees error, can retry
Invalid data	Malformed responses → graceful fallback
Auth failure	Expired token → redirect to login, not crash
Payment failure	Declined card → clear message, can retry
API down	Service unavailable → error state, not blank screen
Partial failure	One API fails, others still work

markdown

undefined

检查项	校验标准
网络故障	离线/超时场景下用户能看到错误提示，可重试
无效数据	响应格式错误时能优雅降级
认证失败	token过期时重定向到登录页，不会崩溃
支付失败	卡被拒时展示清晰提示，可重试
API不可用	服务不可用时展示错误状态，不会出现空白屏
局部故障	单个API故障不影响其他功能正常运行

markdown

undefined

Error Recovery: PASS ✅ / FAIL ❌

Scenarios tested: [list]
Unhandled failures: [list]
User messaging: [clear / missing]

undefined

Scenarios tested: [list]
Unhandled failures: [list]
User messaging: [clear / missing]

undefined

Pass 5: Environment Configuration

环节5：环境配置

Check	What to Look For
`.env.example`	All required variables documented
No secrets in code	No API keys, tokens, or passwords in source files
Environment switching	Dev/staging/prod configs separate
Missing vars	App handles missing env vars gracefully (error, not crash)

markdown

undefined

检查项	校验标准
`.env.example`	所有必填变量都有说明
代码无敏感信息	源码中没有API key、token、密码等敏感信息
环境切换	开发/测试/生产配置相互隔离
缺失变量处理	应用缺失环境变量时能优雅处理（提示错误，不会直接崩溃）

markdown

undefined

Environment: PASS ✅ / FAIL ❌

Variables documented: [YES/NO]
Secrets in code: [NONE / list files with exposed secrets]
Missing var handling: [graceful / crashes]

undefined

Variables documented: [YES/NO]
Secrets in code: [NONE / list files with exposed secrets]
Missing var handling: [graceful / crashes]

undefined

Pass 6: End-to-End Flow

环节6：端到端流程

Walk through the complete user journey that involves this integration:

Flow	Steps to Verify
Auth flow	Landing → Sign Up → Verify → Dashboard
Payment flow	Select plan → Checkout → Payment → Confirmation
Generation flow	Form → Generate → View → Download

markdown

undefined

遍历涉及该集成的完整用户旅程：

流程	验证步骤
认证流程	落地页 → 注册 → 验证 → 仪表盘
支付流程	选择套餐 → 结账 → 支付 → 确认页
生成流程	表单填写 → 生成内容 → 查看 → 下载

markdown

undefined

E2E Flow: PASS ✅ / FAIL ❌

Flow tested: [describe]
Steps completed: [X]/[Y]
Broken at step: [which step, if any]

undefined

Flow tested: [describe]
Steps completed: [X]/[Y]
Broken at step: [which step, if any]

undefined

Verdict Template

结论模板

markdown

undefined

markdown

undefined

Integration Evaluation Report

Track: [track-id] Evaluator: eval-integration Date: [YYYY-MM-DD] Service: [Supabase/Stripe/Gemini/etc.]

Results

Pass	Status	Issues
1. API Contracts	PASS/FAIL	[details]
2. Auth Flow	PASS/FAIL	[details]
3. Data Persistence	PASS/FAIL	[details]
4. Error Recovery	PASS/FAIL	[details]
5. Environment	PASS/FAIL	[details]
6. E2E Flow	PASS/FAIL	[details]

Pass	Status	Issues
1. API Contracts	PASS/FAIL	[details]
2. Auth Flow	PASS/FAIL	[details]
3. Data Persistence	PASS/FAIL	[details]
4. Error Recovery	PASS/FAIL	[details]
5. Environment	PASS/FAIL	[details]
6. E2E Flow	PASS/FAIL	[details]

Verdict: PASS ✅ / FAIL ❌

[If FAIL, list specific fix actions for loop-fixer]

undefined

[If FAIL, list specific fix actions for loop-fixer]

undefined

Handoff

流转规则

PASS → Return to
```
loop-execution-evaluator
```
→ Conductor marks complete
FAIL → Return to
```
loop-execution-evaluator
```
→ Conductor dispatches
```
loop-fixer
```

通过 → 返回给
```
loop-execution-evaluator
```
→ 调度器标记任务完成
不通过 → 返回给
```
loop-execution-evaluator
```
→ 调度器派发
```
loop-fixer
```
处理修复