- 对比页主栏对齐 1240,桌面 sticky 工具栏/表头,移动端修复与快捷条重叠 - 对比度自动化采样并修复 18 个 FAIL,ui_invariants 扩到 340 项(336 PASS / 0 FAIL / 4 SKIP) - 页面级 <10px 声明清零;IDE 仍保留 189 条静态欠账,文档明示 - 新增 ide-stream.js:SSE 游标续传/去重/退避与提交幂等键;9 条单测 - 同步 UI/UX/品牌/验证/API 文档与 docs/evidence/sprint3 本地证据
46 KiB
CloudLab API 契约(API-CONTRACT)
文档状态(与 2026-11-18 源码同步):本文依据 2026-11-18 工作区 app/ide.js、app/bench.js 与 ../cloudlab-platform/server.py(1601 行)实测整理;行号为当日文件行号。服务端未实现或前端未使用的端点均显式标注"未实现/未验证",不作推测性描述。
适用范围:CloudLab IDE(app/ide.html + ide.js)及其依赖的控制面 API;实验台/资料浏览/生信数据库/对比页的静态数据读取单列 §9。认证、运行提交与生命周期、SSE、上传、项目/成员/配额、错误结构与 UI 状态映射。页面与视觉分别见 UX-AUDIT.md、UI-SYSTEM.md、BRAND-GUIDE.md;改动前基线见 UI-OPTIMIZATION-PLAN.md。
最后核对命令:见 §16(grep 调用点、路由与常量)。
1. 部署前提与约定
| 项 | 约定 | 证据 |
|---|---|---|
| 同源 | 前端全部用相对路径 /api/...,依赖同源部署;代码中无 API base URL、无 CORS 头 |
app/ide.js:477 起 |
| 凭据 | credentials: 'same-origin',认证 Cookie cl_session |
ide.js:337 |
| 服务端 | Python 3.11 标准库、SQLite 控制面;默认监听 0.0.0.0:8000,可用 CLOUDLAB_API_HOST/PORT 覆盖 |
server.py:1592-1594 |
| 站点 | CLOUDLAB_SITE 默认 /opt/cloudlab/site;前端页面与 /app/data 静态数据由站点服务承载 |
common.py:17 |
| 编码 | JSON UTF-8;JSON 响应 Content-Type: application/json; charset=utf-8、Cache-Control: no-store |
server.py:800-805 |
| 时间 | 字符串 ISO-8601(UTC),由 now_iso() 生成 |
common.py now_iso |
| 版本 | APP_VERSION = "3.0.0";Server 头 CloudLabAPI/3.0;/api/health 返回 version: "3.0.0" |
common.py:14、server.py:766、server.py:888-889 |
| 反向代理 | 未在代码中配置;若经 Nginx 等代理,SSE 需关闭缓冲(服务端已发 X-Accel-Buffering: no)。代理层行为未验证 |
server.py:1547-1560 |
请求头约定:
- 所有写请求(
POST/PUT/PATCH/DELETE)必须带X-CloudLab-Client: ide,否则 403csrf。/api/auth/login、/api/auth/logout在鉴权之前处理,不受此限制。 Content-Type: application/json用于 JSON;上传用application/octet-stream。- 可选
Idempotency-Key:服务端已支持;IDE 前端自 S3-4 起在POST /api/runs自动生成并发送(同一提交重试复用,见 §4.1、§17.6)。
2. 客户端请求层(ide.js)
2.1 常量与函数
| 名称 | 行号 | 行为 |
|---|---|---|
REQ_TIMEOUT |
ide.js:307 |
15000 ms,普通请求默认超时 |
UPLOAD_TIMEOUT |
ide.js:308 |
60000 ms,上传专用 |
reqError(message, status, code, retryable) |
ide.js:310-316 |
构造带 status/code/retryable 的 Error;code 缺省为 http_<status> 或 network |
errMessage(status, serverMsg) |
ide.js:318-328 |
服务端有 error 文本时优先使用;否则按状态给中文兜底 |
fetchTimeout(url, opt, ms) |
ide.js:332-347 |
AbortController 超时;credentials: same-origin;超时 code='timeout'、网络失败 code='network',均 retryable=true |
api(path, opt) |
ide.js:350-377 |
统一封装:非 GET 自动加 X-CloudLab-Client;对象 body 自动 JSON 序列化;先 res.text() 再解析 |
getJson(url) |
ide.js:586-591 |
读取 /app/data/*.json,非 2xx 抛 static_<status> |
fetchTimeout 直传(上传) |
ide.js:2014-2019 |
手动构造 60s 上传请求,不经过 api() |
2.2 错误对象
err.status // 0 = 网络/超时;否则 HTTP 状态码
err.code // 'timeout' | 'network' | 'unauthorized' | 服务端 code | 'http_<n>'
err.retryable // 无 status、408、429、>=500 时为 true;401 显式 false
err.payload // 非 2xx 时附带的解析后响应体
err.message // 可直接展示的中文
api() 读取响应体的降级规则(ide.js:359-376):
- 空 body →
null; - 非 JSON 文本 →
{ error: text.slice(0, 300) },避免抛解析异常; - 读 body 失败 →
reqError('响应读取失败,请重试', 0, 'network', true)。
2.3 401 特殊处理
api() 遇到 401 时执行(ide.js:363-367):
showAuth()切回登录界面;hideAlert()清空应用内错误条;- 抛出
code = (响应.code || 'unauthorized')、retryable=false的错误。
因此 401 不会进入普通的 showAlert 重试路径,也不会在应用内弹 toast;登录页承担提示。/api/auth/status 未登录返回 200 {user:null},不触发 401 分支。
2.4 前端未使用的封装能力
- 未设置
Accept、未使用AbortSignal取消用户主动取消; - 未统一处理 429 的
Retry-After(仅queue_full响应带该头,前端未读取); - 无请求 ID / trace 透传。
3. 认证
3.1 端点
| 方法 | 路径 | 鉴权 | 请求 | 成功响应 |
|---|---|---|---|---|
| GET | /api/health |
无 | — | {ok:true, app:"CloudLab API", version:"3.0.0", time} |
| POST | /api/auth/login |
无 | {username,password} |
200 {user, projects} + Set-Cookie: cl_session |
| POST | /api/auth/logout |
无(读 Cookie) | — | {ok:true} + 清除 Cookie |
| GET | /api/auth/status |
可选 | — | 已登录 {user, projects, version};未登录 {user:null, projects:[]} |
| GET | /api/me |
必须 | — | {user, projects, version} |
| GET | /api/meta |
必须 | — | 平台计数与限额(见 §8.1) |
user 字段(server.py:71-73):{id, username, role, disabled, createdAt},role 为全局 user|admin。
projects 字段(server.py:85-99):{id, name, description, createdAt, role, quota};管理员返回全部项目且 role="owner",普通用户只返回自己加入的项目。quota 为 {maxActiveRuns, maxRunning, usage:{active,running,queued}}。
3.2 登录
POST /api/auth/login
Content-Type: application/json
{"username":"alice","password":"********"}
服务端行为(server.py:924-946):
- 读取 JSON;同 IP 失败计数保留 600 秒,达到 10 次直接 429
rate_limited「登录尝试过多,请 10 分钟后再试」; - 用户名或密码错误 → 401
bad_credentials「用户名或密码错误」,并记一次失败; disabled=1→ 403disabled「账号已禁用」;- 成功:生成 32 字节随机 token,写
sessions(7 天过期),写审计login; - 返回
{user, projects},并Set-Cookie。
Cookie 属性(server.py:793-798):
cl_session=<token>; Path=/; HttpOnly; SameSite=Lax; Max-Age=604800
# X-Forwarded-Proto: https 或 CLOUDLAB_COOKIE_SECURE=1 时追加 ; Secure
- 无
Domain,默认 host-only;无Secure时仅适合 HTTPS 终止在代理的场景,生产是否强制 Secure 需部署确认。 - 也接受
Authorization: Bearer <token>(server.py:857-862),前端未使用。
3.3 状态、登出与 401
GET /api/auth/status:从未登录返回 200 而非 401,前端据此显示登录页;- 会话不存在/过期 → 401
unauthorized「登录已过期,请重新登录」; - 账号被禁用 → 403
disabled(即使会话存在); POST /api/auth/logout:删除该 token 对应会话,返回{ok:true},并设cl_session=; Path=/; Max-Age=0; HttpOnly; SameSite=Lax;前端失败也静默(ide.js:578-583)。
3.4 CSRF
require_csrf 只校验请求头 X-CloudLab-Client 是否等于 ide(server.py:878-880),不是随机 token,也不校验 Origin/Referer。它依赖同源策略与自定义头不可被简单跨站表单伪造。所有 /api/ 下写请求在鉴权后执行该检查(server.py:900-903)。
3.5 未实现/未验证
- 无注册、找回密码、修改密码(自助)、刷新 token、会话列表端点;
- 无 OAuth/SSO;
- 无 CSRF token 端点;
- 登录失败计数为进程内字典(
LOGIN_FAILS),多进程/重启后失效——未验证多实例部署行为; /api/me前端未调用(用/api/auth/status替代),仅服务端实现。
4. 运行生命周期
运行状态枚举(server.py:31、common.py:482-483):
queued → running → succeeded | failed | cancelled | timeout
cancelled 可在 queued 阶段直接产生;running 阶段取消先置 cancel_requested=1,由 worker 终止后落终态。
4.1 提交运行
POST /api/runs
Content-Type: application/json
X-CloudLab-Client: ide
Idempotency-Key: <可选,1-128 个可打印 ASCII>
{
"projectId": "proj-...",
"experimentId": "exp-...",
"params": { "...": "..." },
"inputs": {
"inputId": {"kind": "builtin", "path": "data/..."} |
{"kind": "upload", "uploadId": "up-..."}
},
"priority": "normal" | "batch"
}
服务端校验(server.py:1310-1382):
| 检查 | 失败响应 |
|---|---|
projectId、experimentId 必填 |
400 invalid |
项目角色至少 runner |
403 forbidden |
| 实验存在 | 404 not_found |
| 参数按 manifest 校验(数字范围/select/required) | 400 invalid_input |
| 输入按 manifest 校验(builtin 路径必须位于站点内;upload 必须属于当前用户) | 400 invalid_input |
priority 仅 `normal |
batch` |
| 全局队列满(默认上限 1000) | 429 queue_full + Retry-After |
当前用户活跃运行(queued+running)达 MAX_RUNS_PER_USER(默认 2) |
429 quota_exceeded |
项目 active 达 max_active_runs |
429 project_quota_exceeded |
| 同 key 但项目/实验/参数/输入/优先级不同 | 409 idempotency_conflict |
成功:
- 首次提交 201
{"run": {...}}; - 幂等重放 200
{"run": {...}, "idempotentReplay": true},响应头Idempotent-Replayed: true; - 新运行初始
status="queued",并写一条 system 日志「运行已进入队列,等待 worker 领取。」; timeoutSec取 manifestruntime.resources.timeout,夹在 10–1800 秒。
run 基础字段(server.py:117-141):
id, projectId, experimentId, experimentVersion, userId, status,
createdAt, startedAt, finishedAt, exitCode, cancelRequested,
timeoutSec, attempt, priority, requeuedFrom, reproducedFrom,
params, inputs, error, note, quality
full=true(提交、详情)额外含:manifest, result, provenance。列表/详情还会补充 experimentCode/experimentTitle/experimentType/username;详情再加 artifacts/logCount/queue/timeline/reproduction。
幂等性说明:服务端在 BEGIN IMMEDIATE 内先查同用户同 key 的运行,冲突返回 409;同一 key 重放返回原 run。S3-4 起 IDE 对每次提交生成 Idempotency-Key(app/ide-stream.js 的 idempotencyKey()):以 {projectId,experimentId,params,inputs,priority} 指纹判断是否同一次提交,同指纹的重试复用同一个键,成功后清理;超时/网络/5xx 保留键供用户重试,401/400/403/404/409 清理。前端不自动重试提交;409 idempotency_conflict 显示中文提示并清理当前键。
4.2 运行列表
GET /api/runs?projectId=<可选>&experimentId=<可选>&limit=100
limit夹在 1–200,默认 50;无 projectId 时最多取limit*3后再按项目权限过滤;- 必须至少是目标项目
viewer;按created_at DESC; - 返回
{runs:[...]},每项为基础字段 + 实验标题/代码/类型 + 用户名; - 无分页游标、无 total;未实现更早记录翻页。
4.3 运行详情
GET /api/runs/{id}
返回 {run: {...}},包含:
manifest:提交时冻结的实验定义;result:worker 产出的 result.json 内容(无则null);provenance:溯源快照;artifacts[]:{id,name,size,mime,sha256,url},url已 URL 编码;logCount、queue(队列位置/预估)、timeline(见 §4.6);- 若
reproducedFrom存在,附reproduction报告。
权限:项目 viewer 及以上;非成员 403(不泄露运行是否存在之外的信息;不存在则 404)。
4.4 日志流(SSE)
GET /api/runs/{id}/events?since=<最后已见日志 id,初始 0>
Accept: text/event-stream
Cookie: cl_session=...
前端 ensureStream 在 ide.js:763:
new EventSource(CLStream.streamUrl(id, S.logCursors[id] || 0))
服务端(server.py:1547-1591):
- 先鉴权(
viewer),后写 SSE 头:Content-Type: text/event-stream; charset=utf-8、Cache-Control: no-store、Connection: close、X-Accel-Buffering: no; - 首帧
retry: 3000; - 日志帧:
id: 123
event: log
data: {"id":123,"ts":"2026-11-18T...","stream":"stdout","line":"..."}
- 终态帧:
event: status
data: {"status":"succeeded","error":null,"exitCode":0,"finishedAt":"..."}
- 终态帧后关闭连接;空闲每 15 次循环写
: ping; - 游标:显式
?since=优先,否则Last-Event-ID,非法值回退 0。
前端行为(S3-4 起,见 app/ide-stream.js 与 §17.6):
- 打开运行/重连时 URL 带当前游标
since=S.logCursors[id](初始 0),优先于浏览器的Last-Event-ID; log事件取ev.lastEventId || item.id,仅接受严格大于游标的事件(CLStream.shouldAccept),接受后用nextCursor单调推进;浏览器自动重连重放旧日志时被丢弃,不会重复 push;log事件 push 到S.logs[id],超过 2500 条裁到最近 1800 条;当前打开的运行实时 append;status事件关闭 EventSource、清理 stream/重连 timer(保留游标防止重开重放)、更新详情、refreshRuns(true)、按状态 toast(完成/失败/取消/超时);es.onerror:CONNECTING交给浏览器自动重连;仅在readyState === CLOSED时按CLStream.nextRetry(attempt)(1/2/4/8/16/30 秒封顶)手动重连,最多 6 次并同步aria-live播报。
未验证:反向代理下 SSE 是否被缓冲、是否 60s 超时;服务端依赖 Connection: close 而非分块保活。
4.5 运行操作
| 方法 | 路径 | 权限 | 请求 | 成功响应 | 前端入口 |
|---|---|---|---|---|---|
| POST | /api/runs/{id}/cancel |
项目 runner;非本人提交需 editor |
— | 200 {ok:true};终态时 {ok:true,status,alreadyTerminal:true} |
详情「取消运行」+ confirm |
| POST | /api/runs/{id}/note |
runner |
{note}(截断 8000 字) |
{ok:true,note} |
详情备注保存 |
| POST | /api/runs/{id}/requeue |
未逐行核对(按新运行创建) | — | 201 {run} |
failed/timeout 的「重新提交」 |
| POST | /api/runs/{id}/reproduce |
同上 | — | 201 {run}(新运行 reproducedFrom 指向源) |
succeeded 的「复现校验」 |
取消语义:
- queued:立即置
cancelled,写 system 日志与cancelled事件; - running:置
cancel_requested=1,写日志「收到取消请求,正在终止容器。」,不立即改状态; - 终态:幂等返回,不改数据。
requeue/reproduce 的具体创建逻辑在 create_requeued_run/create_reproduced_run(未逐行展开);响应均为新运行,不修改原运行。配额不足时与提交相同 429。
4.6 只读导出与溯源
| 方法 | 路径 | 响应 | 前端用法 |
|---|---|---|---|
| GET | /api/runs/{id}/timeline |
{schema:"cloudlab.run-timeline.v1", runId, count, events:[{id,ts,type,workerId,detail}]} |
详情已内嵌 run.timeline,该独立端点前端未调用 |
| GET | /api/runs/{id}/reproduction |
复现报告(见下) | 详情内嵌;独立端点由「校验 JSON」新窗口打开 |
| GET | /api/runs/{id}/provenance |
{runId, provenance, integrity} |
「溯源 JSON」新窗口打开 |
| GET | /api/runs/{id}/package |
ZIP(application/zip,文件名 cloudlab-run-{id}.zip) |
「下载复现包」 |
| GET | /api/runs/{id}/export |
{envelope:{schema:"cloudlab.run.v2", exportedAt, run, appVersion}} |
JSON 导出;记录批量导出 |
| GET | /api/runs/{id}/artifacts/{name} |
产物字节;默认 inline,?download=1 为 attachment |
产物预览/下载 |
复现报告字段(server.py:368-465):
schema:"cloudlab.reproduction.v1", targetRunId, sourceRunId, checkedAt, method, limitations[],
state: not_a_reproduction | unavailable | pending | target_failed | completed,
match, sourceStatus, targetStatus, sourceExperimentVersion, targetExperimentVersion,
byteIdentical, contentEqual, metricsEqual, tablesEqual, seriesEqual, artifactsEqual,
sourceResultSha256, targetResultSha256, sourceResultSize, targetResultSize,
sourceArtifactCount, targetArtifactCount, differences[]
报告明确声明:验证的是"同一实现与快照下的可复现性",不是科学结论或湿实验验证。
溯源完整性(server.py:525-600):integrity.ok 在 schema 存在且无 critical 非 ok 检查时为 true;checks[] 含 id/label/status(ok|mismatch|missing|unknown)/critical/expected/actual,并给出 summary{ok,mismatch,missing,unknown}。
产物下载安全:解析后必须位于 DATA/runs/{id} 目录下,否则 403 forbidden「非法产物路径」;文件丢失 404;响应带 Cache-Control: private, max-age=60。
4.7 未实现
- 无
DELETE /api/runs/{id};运行记录不可删除; - 无批量取消/批量重跑;
- 无运行搜索/按状态过滤(
runFilter为前端过滤); - 无 WebSocket;仅有 SSE + 轮询。
5. 上传
5.1 上传文件
POST /api/uploads?name=<URL 编码文件名>
X-CloudLab-Client: ide
Content-Type: application/octet-stream
Content-Length: <字节数>
<原始字节>
服务端(server.py:1130-1147):
- 文件名经
os.path.basename取基名、反斜杠归一、截断 160 字符; - 空文件 → 400
invalid「文件为空」; - 缺失
Content-Length→ 411length_required; - 超过
MAX_UPLOAD=50MB→ 413too_large「文件超过上限(50 MB)」; - 存储到
DATA/uploads/{upload_id}_{safe_name},权限 0644; - 写
uploads表(含sha256)与审计; - 201
{"upload":{"id","name","size","sha256"}}。
前端(ide.js:2010-2030):fetchTimeout(..., UPLOAD_TIMEOUT),成功取 data.upload.id 写入表单输入,toast「已上传 」;失败 toast 错误文本。上传中只显示 toast,无进度条。
5.2 我的上传列表
GET /api/uploads → {uploads:[{id,name,size,sha256,createdAt}]},最近 100 条,仅当前用户。前端未调用(上传后直接用返回值)。
5.3 约束
- 仅支持单文件、整包 body;未实现分片/断点续传/多文件;
- 无 MIME 白名单、无病毒扫描(服务端不校验内容类型);
- 50MB 在 60s 超时下需要至少约 0.84MB/s 上行;弱网可能超时,前端无重试按钮,需重新选择文件;
- 上传 ID 与运行输入绑定,
validate_run_inputs校验归属,防止引用他人上传。
6. 项目、成员与配额
| 方法 | 路径 | 权限 | 说明 |
|---|---|---|---|
| GET | /api/projects |
登录 | {projects:[...]};管理员看全部 |
| POST | /api/projects |
平台 admin | {name,description},201 {project};创建者自动 owner |
| PATCH | /api/projects/{pid} |
项目 owner | 可改 name、description |
| GET | /api/projects/{pid}/members |
项目 viewer | {members:[{id,username,globalRole,role,createdAt}]} |
| POST | /api/projects/{pid}/members |
项目 owner | {username,role};用户不存在 404;角色非法 400;已存在则更新角色 |
| PATCH | /api/projects/{pid}/members/{uid} |
项目 owner | {role} |
| DELETE | /api/projects/{pid}/members/{uid} |
项目 owner | 最后一个 owner 不可删,400 invalid |
| GET | /api/projects/{pid}/quota |
项目 viewer | {quota:{maxActiveRuns,maxRunning,usage}} |
| PATCH | /api/projects/{pid}/quota |
项目 owner | {maxActiveRuns,maxRunning},1–100 整数,maxRunning<=maxActiveRuns |
角色顺序:viewer < runner < editor < owner(common.py:33)。写操作的最小角色按各端点实现:成员管理要求 owner;项目修改要求 owner;配额修改要求 owner;运行提交要求 runner。
前端实际使用:GET members、POST members、PATCH members/{uid}、DELETE members/{uid}、PATCH quota(ide.js:635/2096/2102/2126/2113)。GET/POST /api/projects、PATCH /api/projects/{pid} 前端未调用(项目列表来自登录/状态响应)。
6.1 未实现/未验证
- 无邀请链接/邮件邀请;
- 无成员转让 owner 的专用端点;只能用 PATCH 改角色。服务端仅对 DELETE 校验“至少保留一名 owner”,PATCH 降级最后一名 owner 未校验(潜在缺口,未验证后果);
- 无项目删除;
- 管理员创建用户时可选
projectId/projectRole,但仅当管理员是该项目的成员才会加入(server.py:1272-1275)——语义较隐蔽,未在 UI 验证。
7. 实验、模型卡与记录
7.1 实验
| 方法 | 路径 | 权限 | 说明 |
|---|---|---|---|
| GET | /api/experiments |
登录 | 可选 `?type=bio |
| GET | /api/experiments/{eid} |
登录 | {experiment: manifest} |
| PUT | /api/experiments/{eid} |
平台 admin 或任一项目 editor/owner | {manifest};不可改 id/type/code/op/runtime/inputs/outputs;版本自增;校验 manifest |
| GET | /api/model-cards |
登录 | {modelCards:[{id,code,type,title,version,modelCard,quality}]} |
PUT 的不可变字段返回 400 immutable「字段不可修改: 」;校验失败由 validate_manifest 抛 400。前端用于"实验定义"编辑(ide.js:2084),不涉及运行提交。
/api/model-cards 服务端已实现,IDE 前端未调用,不在现有 UI 验证范围内。
7.2 记录
GET /api/records?projectId=<可选>(server.py:1194-1208):
- 仅取终态运行(
succeeded/failed/cancelled/timeout),最多 200 条,按创建时间倒序; - 必须对每个运行所属项目有角色,否则跳过;
- 字段:
id, projectId, experimentId, experimentCode, experimentTitle, type, status, createdAt, note, summary; - 无分页、无时间过滤、无全文搜索。
重要区分:records.html 使用 record-store.js 的 localStorage(cloudlab_room_records_v2),完全不调用 /api/records;两套"记录"不共享数据。详见 UX-AUDIT.md。
8. 容量、统计、Worker 与管理
8.1 平台元信息
GET /api/meta → {version, experiments:{type:n}, runs:{status:n}, maxRuns, maxRunsPerUser, maxQueuedRuns, projects}。前端未调用。
8.2 容量
GET /api/capacity(common.py:783-850):
capacity, active, queued, queueLimit, queueFull, acceptingRuns,
retryAfterSeconds, availableSlots, perUserLimit,
user:{active,queued,remaining,canSubmit},
workerOnline, workerCount, workers[], averageRuntimeSeconds,
estimatedWaitSeconds, estimateBasis, queuedRuns[], time
estimatedWaitSeconds基于最近 20 次成功运行平均耗时与队列波次,服务端明确标注"不保证开始时间";- worker 离线或历史不足时
estimatedWaitSeconds=null,estimateBasis给出原因; queuedRuns[]含每个排队运行的队列位置摘要。
前端每 10 秒 loadStats(其中会取 /api/capacity,ide.js:660),并渲染状态栏。
8.3 统计
GET /api/stats:
active, queued, capacity, perUserLimit, workerOnline, workerCount,
workers[], queue{}, time,
research:{experiments,validated,modelTier,unvalidated}
queue 为队列快照(见下)。前端每 10 秒刷新。
8.4 Worker
GET /api/workers → {workers:[...], queue:{...}, time}。
worker 字段(common.py:622-694):id,hostname,node,version,capacity,status(online|draining|offline),online,claiming,startedAt,lastSeen,currentRuns,runs[],legacy;在线窗口 20 秒。
管理员操作:
POST /api/admin/workers/{wid}/drain|resume,body {};仅平台 admin;未注册 404;成功 {ok:true,worker,queue}。
8.5 管理端点
| 方法 | 路径 | 权限 | 说明 |
|---|---|---|---|
| GET | /api/admin/users |
admin | {users:[public_user]} |
| POST | /api/admin/users |
admin | {username,password,role,projectId?,projectRole?};用户名 ^[A-Za-z0-9_.-]{3,32}$,密码 ≥8,role `user |
| PATCH | /api/admin/users/{uid} |
admin | {password?} 或 {disabled?};密码 ≥8;返回 {ok:true};未校验 uid 是否存在,也不阻止管理员禁用自己(未测试) |
| GET | /api/admin/audit |
admin | {audit:[...]},最近 200 条,倒序 |
上述四个端点前端均使用(ide.js:668/2135/2363/2368/2154)。
9. 静态数据与无 API 页面
以下路径不是 /api 契约,但属于前端数据依赖,列出避免误判为后端接口:
| 页面/模块 | 路径 | 方式 | 失败表现 |
|---|---|---|---|
| 实验台 bench | /app/data/mol/{key}.json |
fetchJSONTimed,15s |
3D 面板空态 + 「重试」;toast |
| 实验台 bench | /{编码后的资料路径} |
fetchTextTimed,15s |
序列/数据集读取失败 toast |
| 资料浏览 browse | /app/data/files.json |
原生 fetch(无超时) |
两栏分别显示失败 + 「重新加载」 |
| 生信数据库 | /生信数据库资料库/catalog.json |
原生 fetch(cache:no-store) |
.cl-error + 「重试」 |
| 对比-数据 | meta.path 指向的静态文件 |
fetch(..., {cache:'force-cache'}) |
需看页面实现,未逐页验证 |
| 资料库 shell | /app/data/*、/{资料路径} |
原生 fetch |
各面板自定义 |
结论:browse/bio-databases/bench/compare 均不依赖控制面 API;只有 IDE 走 /api。因此 API 故障不影响"实验楼"页面浏览,但影响 IDE 登录与运行。
10. 错误结构
10.1 服务端响应
统一错误(server.py:907-911):
{"error": "人类可读中文", "code": "machine_code"}
未捕获异常(server.py:912-918):
{"error": "服务器内部错误", "detail": "<异常字符串>"}
注意:500 响应没有 code,且 detail 可能包含内部路径/异常信息,生产环境应视为信息泄露风险(当前实现如此,未做脱敏)。
10.2 错误码表
| HTTP | code | 典型触发 | 前端可重试 |
|---|---|---|---|
| 400 | invalid |
参数缺失/非法、项目名空、配额非整数 | 否 |
| 400 | invalid_input |
缺参数/输入、数字越界、上传不存在 | 否 |
| 400 | bad_json |
JSON 解析失败 | 否 |
| 400 | immutable |
修改实验不可变字段 | 否 |
| 400 | bad_request |
Content-Length 非法 | 否 |
| 401 | unauthorized |
未登录/会话过期 | 否(转登录) |
| 401 | bad_credentials |
登录用户名或密码错误 | 否 |
| 403 | disabled |
账号禁用 | 否 |
| 403 | csrf |
写请求缺 X-CloudLab-Client: ide |
否 |
| 403 | forbidden |
角色不足/非项目成员/非法产物路径 | 否 |
| 404 | not_found |
运行/实验/用户/产物/接口不存在 | 否 |
| 405 | method_not_allowed |
路径存在但方法不支持 | 否 |
| 409 | conflict |
用户名已存在 | 否 |
| 409 | idempotency_conflict |
同 key 不同载荷 | 否 |
| 411 | length_required |
上传缺 Content-Length | 否 |
| 413 | too_large |
上传 >50MB | 否 |
| 429 | rate_limited |
登录失败过多 | 稍后 |
| 429 | quota_exceeded |
用户活跃运行达上限 | 稍后/取消 |
| 429 | project_quota_exceeded |
项目活跃运行达上限 | 稍后/取消/调额 |
| 429 | queue_full |
全局队列满(带 Retry-After) | 是 |
| 500 | (无 code) | 未捕获异常 | 是 |
前端 retryable 默认规则:无 status、408、429、≥500 → true;401 显式 false。因此 queue_full、quota_exceeded 等 429 在 UI 上会显示重试按钮,但 quota_exceeded 立即重试通常仍失败——文案未区分"稍后重试"与"需取消/调额"。
10.3 客户端兜底文案(无服务端 error 时)
| 状态 | 文案 |
|---|---|
| 400 | 请求参数有误,请检查后重试 |
| 403 | 没有权限执行此操作,请联系项目管理员 |
| 404 | 请求的资源不存在或已被删除 |
| 409 | 请求冲突,请刷新后重试 |
| 413 | 文件超出大小限制 |
| 429 | 请求过于频繁,请稍后再试 |
| ≥500 | 服务器暂时不可用,请稍后重试 |
| 其他 | 请求失败(HTTP n) |
11. 加载 / 空 / 错误 / 重试 UI 映射
| 场景 | 触发 | UI | 可访问性 | 重试 |
|---|---|---|---|---|
| 启动检查会话 | checkAuth |
#boot-loading |
— | 自动 |
| 服务不可达/5xx | checkAuth catch |
#auth-offline + 文案(超时 15 秒 / 无法连接 / HTTP n) |
文本 | 「重试连接」#login-retry 调 recheckAuth |
| 登录失败 | api('/api/auth/login') |
#login-error 文本;按钮恢复 |
按钮 aria-busy 期间禁用 |
err.retryable 时显示重试 |
| 初始化加载 | afterLogin |
showAppLoading 在 #editor 内渲染 .req-loading[role=status][aria-live=polite] + spinner |
live region | 失败 showAlert(err, afterLogin) + toast |
| 应用内错误 | showAlert |
#app-alert,含 <code>code</code>、关闭按钮;`data-kind=warn |
error` | announce 写 #req-announce |
| 提交运行 | submitRun |
按钮「提交中…」禁用;成功 toast「已提交:xxxxxx」;失败 toast | — | 无内联重试,需再点提交 |
| 上传 | uploadFor |
toast「上传 …」→ 成功/失败 toast | — | 无重试按钮,需重新选择 |
| 取消 | cancelRun |
confirm → toast「已发送取消请求」 |
— | — |
| 运行结束 | SSE status |
toast(完成/失败/取消/超时)+ 刷新详情 | — | — |
| 空记录 | loadRecords |
空态(前端渲染) | — | — |
| 空运行列表 | refreshRuns |
空态 | — | — |
| 静态资料缺失 | getJson(...).catch(null) |
静默降级,不阻塞 IDE | — | 无 |
| 3D 分子缺失 | bench openMolecule |
面板 .cl-empty + 「重试」按钮 |
面板 aria-live=polite |
是 |
12. SSE 与轮询
| 机制 | 频率/触发 | 用途 | 证据 |
|---|---|---|---|
| SSE | 打开运行详情时 | 实时日志 + 终态通知 | ide.js:763 |
loadStats |
10 秒 | /api/stats + /api/capacity,状态栏/队列 |
ide.js:531 |
refreshRuns(true) |
20 秒且页面可见 | 运行列表兜底刷新 | ide.js:532-534 |
| 详情手动刷新 | 「刷新」按钮 | GET /api/runs/{id} |
ide.js |
设计意图:SSE 为主,轮询兜底。缺口:
- SSE 断线由浏览器自动重连;致命关闭时客户端按 1→30 秒退避手动重连,最多 6 次,事件按 id 去重(§4.4、§17.6);
- 轮询固定 20 秒,后台标签页暂停(
visibilityState==='visible'),恢复可见后需等下一次; - 无"最后更新时间"提示,用户可能不知道数据已陈旧。
13. 契约兼容与变更流程
13.1 当前版本标识
- HTTP
Server: CloudLabAPI/3.0; - JSON 内
version/appVersion: "3.0.0"; - 导出信封 schema:
cloudlab.run.v2、cloudlab.records.v2; - 溯源:
cloudlab.provenance.v1; - 时间线:
cloudlab.run-timeline.v1; - 复现:
cloudlab.reproduction.v1。
未实现:OpenAPI/Swagger、JSON Schema 文件、契约测试、版本协商头。本文即当前唯一契约说明。
13.2 兼容规则
- 加法优先:新增响应字段不视为破坏;前端应忽略未知字段(现有代码多为按名取用,兼容)。
- 不改语义:已有字段的类型/含义不变;需要改语义时新增字段并双写一段时间。
- 不改状态枚举:新增运行状态必须同步前端
statusLabel/样式/SSE 处理,否则会显示未知状态。 - 错误码稳定:新增 code 可以,但不要把已有 code 改义;前端仅对 401 做特殊分支。
- URL 版本化未实现:
/api/无/v1前缀;破坏性变更只能靠部署协调。
13.3 变更流程(建议,尚未强制)
- 先改
server.py并保持旧字段;在本文更新端点/字段/错误码; - 再改
ide.js,所有请求仍走api()/fetchTimeout; - 若涉及写请求,确认
X-CloudLab-Client: ide仍发送; - 若涉及运行/导出,校验 schema 字符串是否需要升版;
- 跑 §14 回归;UI 侧对照 UX-AUDIT.md 的验收项;
- 部署时同步前端缓存版本(
?v=)与 API 版本。
14. 回归检查点
14.1 接口冒烟(curl,替换 host/cookie)
BASE=http://127.0.0.1:8000
# 1. 健康检查
curl -sS $BASE/api/health
# 2. 未登录状态应 200 + user:null
curl -sS $BASE/api/auth/status
# 3. 未登录访问受保护接口应 401
curl -sS -i $BASE/api/runs
# 4. 登录失败应 401 bad_credentials
curl -sS -i -X POST $BASE/api/auth/login \
-H 'Content-Type: application/json' \
-d '{"username":"nobody","password":"wrong"}'
# 5. 登录成功并保存 Cookie
curl -sS -c /tmp/cl.cookie -X POST $BASE/api/auth/login \
-H 'Content-Type: application/json' \
-d '{"username":"<user>","password":"<pass>"}'
# 6. 写请求缺客户端头应 403 csrf
curl -sS -b /tmp/cl.cookie -i -X POST $BASE/api/runs \
-H 'Content-Type: application/json' -d '{}'
# 7. 带客户端头后应进入业务校验(非 403 csrf)
curl -sS -b /tmp/cl.cookie -i -X POST $BASE/api/runs \
-H 'X-CloudLab-Client: ide' -H 'Content-Type: application/json' -d '{}'
# 8. 列表与详情
curl -sS -b /tmp/cl.cookie "$BASE/api/runs?limit=5"
curl -sS -b /tmp/cl.cookie "$BASE/api/runs/<run-id>"
# 9. SSE(应看到 retry: 3000 与 event: log)
curl -sS -N -b /tmp/cl.cookie "$BASE/api/runs/<run-id>/events?since=0"
# 10. 导出信封
curl -sS -b /tmp/cl.cookie "$BASE/api/runs/<run-id>/export"
# 11. 上传超限(应 413 too_large)
head -c 52428801 /dev/zero > /tmp/big.bin
curl -sS -b /tmp/cl.cookie -i -X POST "$BASE/api/uploads?name=big.bin" \
-H 'X-CloudLab-Client: ide' -H 'Content-Type: application/octet-stream' \
--data-binary @/tmp/big.bin
# 12. 退出
curl -sS -b /tmp/cl.cookie -X POST $BASE/api/auth/logout
14.2 前端回归
- 未登录打开 IDE → 登录页,无控制台异常;
- 错误密码 →
#login-error中文文案,按钮恢复可用; - 断网打开 →
#auth-offline+ 「重试连接」; - 登录成功 → 初始化 loading → 三栏数据渲染;
- 提交运行 → 按钮「提交中…」→ toast → 列表出现 queued;
- 打开运行 → SSE 日志增长;结束收到 status toast;
- 取消 queued/running → 状态变化符合预期;
- 上传 >50MB → 413 文案;上传正常文件 → 输入绑定成功;
- 列表空态/记录空态不报错;
- 401(手动清 Cookie 后点操作)→ 回登录页;
- 429 配额 → toast 文案可理解(当前无专门引导)。
14.3 契约静态检查
cd /root/dsh_workspace/cloudlab-app
# 所有 API 调用点
grep -nE "\b(api|fetch|EventSource)\(|/api/" app/ide.js | sed -n '1,120p'
# 服务端路由
grep -nE 'path == "/api/|re\.match\(r"\^/api/' ../cloudlab-platform/server.py
# CSRF / 超时 / 状态机
grep -nE "REQ_TIMEOUT|UPLOAD_TIMEOUT|X-CloudLab-Client|Idempotency-Key|TERMINAL" app/ide.js app/ide-stream.js ../cloudlab-platform/server.py
15. 未实现 / 未验证清单
15.1 未实现(代码中不存在)
- OpenAPI/Swagger、JSON Schema、契约版本协商;
- 注册、找回密码、自助改密、刷新 token、会话管理;
- CSRF token(只有自定义头标记);
DELETE /api/runs/{id}、运行批量操作、运行搜索分页;- 分片/断点续传、多文件上传、上传进度;
- 项目删除、邀请链接、owner 转让专用接口;
- CORS 配置(当前仅同源可用);
- 请求 ID/审计追踪 ID 透传;
- 429
Retry-After的前端消费; - 500
detail脱敏。
15.2 服务端已实现但前端未调用(未在 UI 验证)
| 端点 | 说明 |
|---|---|
GET /api/me |
前端用 /api/auth/status |
GET /api/meta |
无调用 |
GET /api/model-cards |
无调用 |
GET /api/runs/{id}/timeline |
详情已内嵌 timeline,独立端点未调用 |
GET /api/uploads |
上传后直接用响应,不拉列表 |
GET/POST /api/projects |
项目来自登录响应;无创建 UI |
PATCH /api/projects/{pid} |
无编辑项目 UI |
GET /api/projects/{pid}/quota |
只 PATCH,不单独 GET |
15.3 未验证(需环境/代理/人工确认)
- 反向代理对 SSE 的缓冲与超时;
X-Accel-Buffering是否生效; SecureCookie 在生产 HTTPS 下是否强制(依赖X-Forwarded-Proto或环境变量);- 多进程/多实例下的登录失败计数与 SQLite 写并发;
- 上传 50MB 在真实弱网下是否触及 60 秒超时;
PATCH /api/admin/users/{uid}对不存在 uid 的行为(当前返回 ok,未测试);- 管理员禁用自己后的会话行为;
requeue/reproduce的完整创建逻辑与配额边界(未逐行展开);- 运行详情
queue字段的具体形状(run_queue_summary未逐字段核对); - 各浏览器 EventSource 对
Connection: close的重连表现; /api/records与本地记录的产品语义是否应合并(当前是两套系统)。
16. 最后核对命令
cd /root/dsh_workspace/cloudlab-app
# 1. 前端所有请求点
grep -nE "\b(api|fetch|fetchTimeout|EventSource|window\.open)\(" app/ide.js
grep -nE "\b(fetch|fetchJSONTimed|fetchTextTimed|fetchTimed)\(" app/bench.js
grep -rnE "fetch\(|EventSource\(" app/*.js | grep -vE 'ide.js|bench.js'
# 2. 请求层常量/错误
sed -n '300,380p' app/ide.js
sed -n '1,60p' app/bench.js
# 3. 服务端路由与鉴权
grep -nE '^ def (dispatch|login|logout|route|create_run|list_runs|get_run|cancel_run|note_run|run_events|read_raw)' ../cloudlab-platform/server.py
sed -n '878,955p' ../cloudlab-platform/server.py
sed -n '1130,1320p' ../cloudlab-platform/server.py
sed -n '1547,1601p' ../cloudlab-platform/server.py
# 4. 常量与 schema
grep -nE '^(VERSION|MAX_RUNS|MAX_RUNS_PER_USER|MAX_UPLOAD|MAX_QUEUE_RUNS|QUEUE_RETRY_AFTER|ROLE_ORDER)' ../cloudlab-platform/common.py
grep -n 'schema' ../cloudlab-platform/server.py | head -20
# 5. 前端是否使用可选端点
grep -nE '/api/(me|meta|model-cards|uploads|projects)' app/ide.js
grep -n 'Idempotency-Key' app/ide.js ../cloudlab-platform/server.py
17. IDE 页面规格(S2-5:标题栏 64/58 与登录文案下限,非接口)
本节记录纯前端视觉规格,不改变任何
/api/*接口。S2-5 仅修改app/ide.css;app/ide.js、app/ide.html、server.py未改动。
17.1 规格与选择器(app/ide.css,行号为 2026-11-18 修改后)
| 选择器 | 属性 | 桌面 | 移动端(≤900px / ≤560px) | 当前行号 |
|---|---|---|---|---|
.ide |
grid-template-rows 首行 |
64px | 58px(≤900px) | 62 / 427 |
.ide.panel-closed |
grid-template-rows 首行 |
64px | 58px(≤900px) | 63 / 428 |
.ide-titlebar |
min-height |
64px | 58px(≤560px) | 73 / 466 |
.ide-sidebar |
top / bottom |
由 grid 决定 | 固定 top:58px、bottom:54px(≤900px) |
436 |
.side-backdrop |
inset |
— | 58px 0 54px 0(≤900px) |
438 |
.brand-mark |
width/height |
32×32 | 同左(登录页 .auth-brand .brand-mark 32×32,行 353) |
76 |
.brand-name |
font-size |
15.5px | 12.5px(≤560px,行 467) | 77 / 467 |
.brand-sub |
font-size |
12px | ≤1050px 隐藏(行 422、443) | 78 |
.icon-btn |
width/height |
34×34 | 32×32(≤560px) | 90 / 470 |
.user-chip |
font-size |
11.5px | 同左,用户名 ≤900px 隐藏(行 451) | 94 |
.worker-pill |
font-size |
11.5px | 同左,文字 ≤900px 隐藏(行 449) | 87 |
.auth-kicker |
font-size |
11px | 同左 | 355 |
.auth-note / .auth-note code |
font-size |
11px / 11px | 同左 | 372 / 373 |
未改动(保持不变):底部 activity 栏 height:54px(行 431)、移动端面板 bottom:54px(行 452)、.ide-status 26px 等。
17.2 实测(Chromium 130.0.6723.31,静态服务 http://127.0.0.1:8099)
验证方式:headless Chromium + CDP,加载 /app/ide.html 后隐藏 #boot-loading/#auth/#app-alert、移除 #app 的 hidden(静态服务无 API 后端时 /api/auth/status 返回 404,属预期环境限制),再读取 getBoundingClientRect()。
| 视口 | .ide-titlebar 高度 |
主区 top→bottom | 横向溢出 | #editor 溢出 |
标题栏子元素越界/文字截断 | JS 控制台错误 |
|---|---|---|---|---|---|---|
| 1440×1000 | 64.00px | 65 → 750px(状态栏 26px) | 0(scrollWidth 1440) | 0 / 0 | 无(最右 1424 ≤ 1440) | 0 |
| 390×844 | 58.00px | 58 → 790px(底部 54px activity 栏) | 0(scrollWidth 390) | 0 / 0 | 无(最右 380 ≤ 390) | 0 |
- 390×844 下
.ide-sidebar计算样式为position:fixed; top:58px,与标题栏底部对齐。 - 唯一失败请求:
GET /api/auth/status404(静态服务无 API 后端,非本次样式改动引入)。 - 截图:
/tmp/cloudlab-s2-task14/ide-1440.png、/tmp/cloudlab-s2-task14/ide-390.png;测量原始数据/tmp/cloudlab-s2-task14/measure.json(临时文件,不入库)。
17.3 登录页文案下限
#auth 内最小字号为 11px(.auth-kicker、.auth-note、.auth-note code、.auth-brand em),表单标签/错误/重试/离线提示 12–13px,输入 15px;本次将原 10px 的 .auth-kicker 与 10.5px 的 .auth-note code 提升到 11px。
工作台内部仍有 8.5–10.5px 的密集信息文本(状态栏、表格工具等),属于 IDE 密排界面的既有例外,不在 S2-5 范围,后续如需统一另行立项。
17.4 回滚方式
纯 CSS 改动,无 JS/HTML/接口依赖。按选择器回退即可(行号为当前文件位置,插入其他规则后以选择器为准):
.ide(行 62)与.ide.panel-closed(行 63)首行64px→54px;.ide-titlebar(行 73)删除min-height:64px;- ≤900px 的
.ide/.ide.panel-closed首行58px→54px(行 427/428),.ide-sidebartop:58px→54px(行 436),.side-backdropinset首值58px→54px(行 438),≤560px 的.ide-titlebar删除min-height:58px(行 466); - 尺寸回退(可选):
.brand-mark32→29、.brand-name15.5→15、.brand-sub12→11、.icon-btn34→31(≤560px 32→29)、.user-chip11.5→11、.worker-pill11.5→10.5、.auth-kicker11→10、.auth-note code11→10.5。
也可在文件末尾追加覆盖块(如 .ide{grid-template-rows:54px minmax(0,1fr) 224px 26px} 等)快速回滚,但 64/58 是 Sprint 2 目标规格,不建议回滚。
17.5 兼容性
- 不涉及 API:端点、方法、请求/响应字段、
X-CloudLab-Client头、15s 超时与重试逻辑均未变,本文件第 1–16 节继续有效。 - 未改
app.css、shell.js或其他页面;IDE 仍使用独立 CSS,不引入全局样式表。
17.6 S3-4 SSE 续传与提交幂等(客户端行为;服务端未改)
新增
app/ide-stream.js纯函数模块(UMD:浏览器window.CLStream、Nodemodule.exports),ide.html在ide.js之前以<script src="/app/ide-stream.js" defer>引入。ide.js通过CLStream调用,helper 缺失时保留最小回退;/api/*路径、方法、请求体语义均未变,仅POST /api/runs新增可选Idempotency-Key请求头(使用服务端既有能力)。
| 项 | 状态 | 实现与行为 | 证据 |
|---|---|---|---|
| SSE 续传 | 已实现 | ensureStream 读取 S.logCursors[id] 生成 ?since=;log 帧以 ev.lastEventId || item.id 推进游标;手动重连沿用同一游标 |
ide.js:763 ensureStream;app/ide-stream.js streamUrl/nextCursor |
| SSE 去重 | 已实现 | shouldAccept 只接受严格大于游标的事件;浏览器自动重连重放旧日志时丢弃,S.logs 不重复 |
app/ide-stream.js shouldAccept |
| 断线退避 | 已实现 | CONNECTING 交给浏览器;CLOSED 时 nextRetry 1/2/4/8/16/30 秒封顶,最多 6 次;status 终态清理 stream/timer,保留游标 |
app/ide-stream.js nextRetry/canRetry;ide.js:760 clearStreamTimer |
| 提交幂等键 | 已实现 | submitRun 按请求体指纹生成/复用键;成功或 4xx 清理;超时/网络/5xx 保留供重试;参数变化生成新键 |
ide.js:2026 submitRun;app/ide-stream.js idempotencyKey |
| 409 处理 | 已实现 | idempotency_conflict 中文提示、不自动重试、清理当前键 |
ide.js submitRun catch |
| PATCH 最后 owner 校验 | 仍遗留 | 服务端未拦截「最后一个 owner 被降级」;本轮不改服务端,仅记录 | server.py 成员 PATCH |
验证(2026-11-18):
cd /root/dsh_workspace/cloudlab-app
node --check app/ide.js && node --check app/ide-stream.js
node tests/ide-stream.test.js # 9 passed, 0 failed
浏览器端 mock 验证(Chromium 130 headless + CDP 注入假 API/EventSource,静态服务 http://127.0.0.1:8099):首次 POST /api/runs 返回 503、用户再次提交复用同一 Idempotency-Key(cl-mwmfq4ml-c366d8db2f089bdba926facf,36 字符、可打印)且请求体一致;SSE 首连 ?since=0,日志 id 11/12/13 后重放 id 12 未重复渲染,模拟 CLOSED 后 1.3s 重连为 ?since=13 并补 id 14(共 4 行),status succeeded 后 stream 关闭、toast「运行完成:abc123」;console 异常 0、横向溢出 0。证据:/tmp/cloudlab-s3-task19/functional.json、functional-1440.png。
回滚方式:删除 app/ide-stream.js 与 tests/ide-stream.test.js,移除 ide.html 中 helper <script>,并将 ide.js 的 ensureStream/submitRun 恢复为改动前版本(?since=0、无 Idempotency-Key);接口契约本身未变化,无服务端回滚。
18. 交叉引用
- 页面信息架构、逐页改动与验收:UX-AUDIT.md
- 令牌、组件、状态样式与命名:UI-SYSTEM.md
- 品牌资产、色板与变更审批:BRAND-GUIDE.md
- 冲刺基线与角色分工:UI-OPTIMIZATION-PLAN.md
- 自动化检查与最终 190 项结果:UI-VERIFICATION.md