UNICUS · 团队测试

一期测试说明

# 方仔团队一期测试说明

这是部署后给方仔团队成员使用的隔离测试流程。入口、组织 ID、测试邮箱和 API 地址必须由部署负责人填入受控交付单;仓库不包含真实凭据或客户数据。

## 人仔与说明书试用

真实生成表单发布并开放后,使用原邮箱账户登录,打开 `/playground#real-generation`。先在组织选择框中选测试组织;网页直接使用当前登录状态,无需创建 API Key。

1. 在“生成真实人仔与说明书”填写可公开读取的 HTTPS 人物参考图,选择脸型和肤色,提交一次人仔任务。价格、余额和权限由服务端核验。
2. 页面按原任务 ID 查询状态。完成后核对“真实上游”来源标记,下载 IO 和 GLB;文件保留 7 天。失败时查看原因,受理结果未知时保留原请求,从 Dashboard 找回原 ID 后点击“读取同一任务”。
3. 人仔成功后,页面带入同组织的本地人仔任务 ID;也可填写之前的成功任务 ID 并点击“读取并核对人仔任务”。选择说明书模式后只提交一次,完成后打开原始网页说明书。
4. 刷新页面不会重新创建任务。只有原任务已结束、点击“开始下一任务”并完成核对后,才准备新的请求。网络中断时不要清理浏览器记录或换幂等键重提。

模拟入口单独标为“安全模拟人仔”;渲染保持暂停。若真实能力尚未开放或 Credits 不足,先按页面提示处理。实际可用版本及试用额度以交付通知为准。

Playground 顶部的 “Figure API” 区域会列出 FigureGeneration、FigurePreview、FigureEstimate 的请求路径、输入项、结果类型和当前交付状态。Preview/Estimate 在组合 worker、CI、发布和线上回读完成前显示“线上待发布”,不会在页面中伪造请求或扣除 Credits。当前图片输入要求不含凭据的公开 HTTPS 地址;受控上传入口与 GLB 在线查看器需等对应版本交付。

已收到的任务结果可展开“查看结果原始 payload”,用于核对服务端返回的状态、任务 ID、来源标记和受控资产元数据。原始 payload 只作为当前任务的只读结果,不应把供应商地址、对象存储地址或模拟结果当作客户可下载产物。

## 人仔固定组合接口

目标版本的契约提供 `/v1/figures/estimate`(人仔生成 + 参考估价)和 `/v1/figures/preview`(人仔生成 + 渲染 + 参考估价);请以交付通知确认目标版本已发布后再调用。两者都要求 `tasks:write`,沿用同一个 `Idempotency-Key` 回读组合任务;预览可选 `angle`、`resolution` 和 `packaging`,估价不接受渲染参数。参考价不含运费、无有效期,不能用于下单。服务端按固定组合步骤预占 Credits,确认失败整体释放,成功整体结算;组合 worker 未配置时返回 `figure_composition_disabled`,不会创建任务或扣款。

成功结果中的 IO、GLB 和渲染图链接均为当前组织认证的 `/v1/assets/{id}/content?organizationId=...` 路径;供应商地址和对象存储地址会被服务端拒绝,不应作为客户端可下载链接保存。

## API Key 自助使用与权限验收

已验证的普通成员无需升级管理员:邮箱登录后进入“团队与凭据”,填写名称,选择权限范围,点击“创建自己的 Key”。默认仅选读取权限;提交模拟任务需额外选择 `tasks:write`,查询该任务需 `tasks:read`,下载需 `assets:read`。密钥只在创建时显示一次,立即保存到受控密码管理器;勿粘贴到群、日志或浏览器代码。列表仅包含掩码、创建者、范围及活动信息,不能再次领取明文。切换组织会清空页面密钥。

点击“复制只读示例”,可使用默认含 `tasks:read` 的 Key 验证鉴权:在服务端通过 `UNICUS_API_KEY` 环境变量提供密钥,命令访问打开控制台时使用的同一地址,只读取当前组织最近一条任务。有权限且尚无任务时,成功响应的任务列表为空。

Key 的范围包括任务、资产、报价、订单、组合的 `read`/`write` 和 `billing:read`。范围仅授予当前创建者已有的普通业务权限,不能绕过生产审核、余额或业务校验;不能管理 Key、成员、组织、财务入账/兑换/退款/策略,也不能提交上游事件。Key 缺少所需范围返回 `403 api_key_scope_required`,失效 Key 或非所属组织鉴权返回 `401`。

普通成员列表只显示自己的 Key,撤销其他成员或其他组织 Key 返回 `404`。管理员可查看和撤销组织全部 Key,新 Key 仍归管理员本人。撤销立即生效且可重复确认。移除成员、删除用户、邮箱验证状态失效或角色不再为 member/admin/owner 后,Key 的下一次请求即被拒绝;当前无独立账号停用开关,停用使用移除成员。重新加入组织需创建新 Key,旧 Key 不自动复活。

旧 Key 不批量更换:迁移时仅按已保存的精确创建者绑定其当时唯一有效成员身份,保留原业务读写范围;未知/已失效创建者的 Key 不猜归属、不自动认领,管理员列表可见并可撤销,鉴权关闭。迁移先于新版部署;迁移与切换期间暂停创建 Key,避免旧版写入未绑定凭据。迁移会给摘要加版本标记,因此旧 API 程序拒绝已迁移及新版 Key,避免旧实例忽略权限范围。失败时保留数据库兼容列、摘要标记、绑定与撤销记录;若回滚旧 API,Bearer 调用将暂时不可用,不能去掉标记恢复旧鉴权。

隔离验收用两个 member 和一个 admin/owner,各自真实邮箱 OTP 登录:验证 member 自建、自己的列表/撤销、跨成员及跨组织拒绝、只读 Key 拒绝写入、显式写范围仅创建安全模拟任务、撤销/移除后即时失效、管理员撤他人、旧 Key 兼容与未知归属关闭。所有账号和 Key 使用隔离数据;不代真实客户创建 Key,不触发真实渲染、付款或生产。

## Dashboard 六页导航与切换验证

六页候选发布后,在左侧导航进入以下独立地址;当前线上版本以交付通知为准:

| 页面 | 地址 | 主要用途 |
| --- | --- | --- |
| 工作台 | `/console` | 组织概览与快捷入口 |
| 任务与回调 | `/console/tasks` | 任务提交、查询与状态 |
| 资产 | `/console/assets` | 文件登记、到期与受控下载 |
| 报价与订单 | `/console/commerce` | 参考估价、生产报价、订单与固定组合 |
| 账务 | `/console/billing` | 独立余额/Credits、账本与授权财务操作 |
| 团队与凭据 | `/console/team` | 成员、邀请与自己的 scoped Key |

每页保留组织选择器。确认直达链接、刷新、浏览器前进/后退及手机导航均能进入对应功能;切页保留所选组织,但仍需当前登录身份在该组织的有效成员资格。切换组织后,上一组织的数据应立即清空,再读取新组织数据。

Key 的一次性明文只在创建页短暂展示,离开页面、切换组织或退出后应清除;返回该页不能再次显示。请使用获准的隔离身份验证,勿在验收中创建真实客户生产 Key、改变客户角色或提交真实渲染/生产订单。

## 登录和控制台

1. 打开部署后的 Web 地址 `/login`,输入已加入测试组织的邮箱。
2. 在隔离收件器或受控邮件中取得一次性验证码,或使用 Magic Link;密码和 OAuth 未启用。登录回跳只接受站内单斜杠路径,邀请和 Playground 的登录链接不会把浏览器带到外部站点。
3. 进入 `/console`,页面会读取当前账户所属组织并提供选择器,也可手动填写管理员提供的组织 ID;切换或修改组织后,上一组织的余额、账本、任务、报价、订单、组合、资产、成员和 API Key 展示以及旧对象表单 ID 会立即清空,需重新读取工作区。余额读取失败或返回非 JSON 错误时,旧余额也会清空并显示可解释状态。默认 Credits、法币和最低余额均为 0。

   OpenAPI 中的客户业务读写默认接受当前 Better Auth 会话 Cookie 或该组织的 Bearer API Key;API Key 只适合服务端调用,不能放进浏览器代码。账务入账、兑换、退款、策略写操作强制要求 owner/admin 会话;API Key 管理要求成员本人会话,普通 member 可创建、查看和撤销自己的 Key,admin/owner 可查看和撤销本组织所有 Key。Bearer Key 不能执行上述管理操作。回调重投与生产能力开关属于部署控制面,使用单独的 operator token 和 `X-UNICUS-Operator-ID`,不会向团队成员或客户开放。

   新组织在首次入账前可以没有 `unicus_balances` 行;成员执行只读余额 GET 仍返回组织范围内的零余额,并不会因为查看页面创建账务记录。只有明确的运营入账、兑换、退款或策略写操作才会初始化/修改余额行。
4. 在“账务”区域,组织 admin/owner 可用已审批的操作号记录隔离线下充值,并按已审批比例执行法币兑换 Credits;也可提交最低余额/授信策略、按原流水记录退款。每项写操作都会先要求确认其为隔离测试账务且已获得对应审批;写操作均要求审批引用或退款原因,重复操作号只会产生一次流水。页面不会连接支付渠道,普通 member 提交会被服务端拒绝。完成后重新读取余额和账本核对结果;账本行会显示操作号、创建时间、关联对象、币种、审批引用和操作人(服务端未返回的审计字段会留空);后付在未获商业批准时保持关闭。
5. 在“团队成员”中读取成员、邀请邮箱并调整 `member`/`admin` 角色;角色变更和移除成员前页面都会要求确认,owner 在控制台只读保护,不提供自助转移或移除。Better Auth 会在服务端检查 owner/admin 权限,移除或降权会立即影响后续业务请求。打开“团队与凭据”区域后,成员和待处理邀请也会每 30 秒按当前组织回读一次;外部接受、取消、重发或权限变更会反映到页面,瞬时失败不会清空手动读取结果。邀请创建后可读取待处理邀请列表,核对邮箱、角色和到期时间;列表会把已过 `expiresAt` 的 `pending` 邀请显示为 `expired`,邀请页也会展示有效期并隐藏已过期邀请的接受操作,避免把已失效链接误认为仍可接受;可点击“重发”刷新有效期后重新投递,或点击“取消”使原邀请链接立即失效。两项操作都由服务端再次检查组织权限。缺失或非法的邀请失效时间会显示为不可用状态,不会伪造有效日期。API Key 列表会区分“从未使用”“不可用”和最近一次成功使用时间;默认回读最新 100 条,同一区域每 30 秒自动回读最新 Key 列表,以便显示外部调用或撤销后的最新状态;超过一页时可点击“加载更早的 Key”,旧 Key 仍可查看和撤销。浏览更早记录期间暂停自动替换,点击“刷新最新列表”恢复最新一页和自动回读;状态筛选作用于已加载记录;服务端只保存摘要和活动时间,不会再次返回密钥。
6. 使用“任务”创建 `simulate:figure` 测试任务。重复提交同一幂等键和相同 JSON 应返回同一任务;修改 payload 应得到 `409`。`upstream:*` 类型由服务端拒绝;真实生成与说明书使用专用 typed 接口,报价/订单写操作从受控业务记录派生;不能通过通用任务接口绕过授权、生产审核或余额预占。点击“读取任务历史”可按创建时间倒序读取当前组织的任务列表;该只读查询不会创建、重试或推进任务,也不会显示其他组织的任务。选择一条任务后,queued/running/reconciling 状态会每 15 秒自动回读,进入终态后自动停止;摘要会明确显示“隔离模拟”或“上游返回”;失败任务会单独显示服务端记录的失败原因,避免把模拟产物或失败响应误读为真实交付。
   Playground 还提供“读取方仔沙盒(只读)”探针:它固定查询 `00000000-0000-4000-8000-000000000000`,只用于验证 Worker 的受控鉴权和沙盒路由;该路径不会创建订单、扣款或触发生产。方仔返回应用层 404 时,内部任务会标记失败但可据任务结果确认请求已到达沙盒。
   如需接收任务事件,可在创建请求中提供隔离测试用的 `callbackUrl`。每个事件只产生一个持久 outbox 事件,Worker 以 `X-UNICUS-Event-ID` 和版本化 JSON 投递;配置 `UNICUS_CALLBACK_SECRET` 时还会带时间戳 HMAC。该 envelope 是 UNICUS 临时协议,方仔最终 callback schema/签名确认前不要用于真实客户接入。
   任务执行后可调用 `/v1/tasks/{id}/attempts?organizationId=...` 查看每次 Worker 尝试、失败原因和完成时间;恢复扫描会把超时运行任务标记为 `reconciling`,供查询补偿,不会创建第二个任务。
   回调投递状态可通过 `/v1/tasks/{id}/callbacks?organizationId=...` 只读回读;其中的 attempts、lastError、nextAttemptAt 和 deliveredAt 用于区分已投递、退避和待人工处理。
7. Playground 的“安全模拟人仔”只运行隔离模拟,结果标记 `simulated=true`。方仔沙盒渲染保持暂停,不能新建或重提 `sandbox:render-example`;已有任务仅按原 ID 查询及读取有效期内受控文件。真实人仔与说明书使用上方独立表单,按“人仔与说明书试用”一节操作。
   以下重试说明仅适用于隔离 `simulate:figure`;真实 Figure/Instruction 的 UNKNOWN 不可重 POST,只能找回原 ID 后 GET。自动读取每两秒一次、有次数及请求超时上限;达到上限仍显示未完成,可点击“继续读取同一任务”只做 GET,不重复提交。提交响应丢失或入库后队列返回 503 时,按钮改为“重试同一请求”,保留原组织、payload 和幂等键;切换组织会立即清空旧结果并取消旧请求,切回原组织可继续未确认的原请求。同一标签页刷新或返回 Playground 后,按当前账户和组织恢复原幂等请求或已确认任务 ID,但不会自动 POST:未确认请求点击“重试同一请求”,已确认任务点击“读取原任务”只做 GET。恢复记录只保存在此标签页的临时存储,不保存登录凭据或结果图片;关闭标签页、清除站点数据或换设备后请到 Dashboard 查询。临时存储不可用或记录损坏时会禁止新提交,先核对 Dashboard 原任务,再清理恢复记录;清理不会取消服务端任务。

8. 使用“报价”分别创建参考估价和可生产报价。控制台报价表单会把合成客户 ID/名称、收件人、电话和地址一起写入报价 source,供后台订单任务从持久记录派生方仔请求;可替换为获准的隔离测试值。参考估价不能下单;可生产报价还要求该测试组织已由运营显式开通生产能力,且必须有有效期并受余额最低值约束。未开通时应返回 `production_not_enabled`。
9. 只有在隔离测试余额已由负责人准备后,才使用“订单”验证预占;订单创建或读取后,`repairing`、`in-production`、`shipped` 状态会每 15 秒自动回读,进入 `delivered` 或 `failed` 终态后停止;也可在“订单状态事件”卡片提交 `repairing`、`in-production`、`shipped`、`delivered` 或 `failed` 事件,重复事件只回放原结果,状态不会倒退;不要把订单创建或模拟事件当作真实生产履约。
   订单状态回调使用 `/v1/orders/{id}/events`,必须带组织范围的 `eventId`/`fingerprint`;重复事件只返回原订单,状态按 repairing → in-production → shipped → delivered 单调推进,受理不明时先查询,不要盲目重下。
   创建订单时可提供隔离测试用的 `callbackUrl`;订单状态事件会进入同一持久 callback outbox,状态可通过 `/v1/orders/{id}/callbacks?organizationId=...` 只读回读。该 envelope 与签名仍是临时协议,方仔最终 callback 规则确认前不要用于真实客户接入。
10. 使用“文件资产”登记公开 HTTP(S) 测试文件,可填写关联任务 ID;登记后页面会自动刷新当前组织的生命周期列表,并显示关联任务、创建时间、大小和失效时间。复制成功前状态为 `pending`,Worker 负责受控复制和七天清理;列表可按 `pending`、`available`、`expired` 筛选,过滤会立即按失效时间判断,Worker 尚未运行时已到期记录也不会继续出现在可用筛选中;列表打开后每 30 秒重新计算当前时间并回读当前组织的资产列表,Worker 完成转存或清理后无需手动刷新即可看到状态变化;跨过失效边界会自动显示为过期并收起下载入口;缺失或非法失效时间的资产会显示为不可下载,避免异常数据绕过界面保留边界;不要提交带凭据、内网或客户真实文件的 URL。
    对已复制的资产,列表还显示服务端校验的 SHA-256 前缀,悬停可查看完整摘要;摘要缺失时显示 `—`,不会把未校验内容误标为完整。下载仍由组织权限、有效期、对象状态和服务端完整性校验共同决定。 控制台同一时间只进行一个文件下载,可点击“取消下载”;切换组织、退出登录或离开页面会中止未完成下载,迟到响应不会保存文件或覆盖新组织的状态。下载完成前再次核对保留期,期间到期的文件不会保存。
11. 固定说明书+生产组合通过 `/v1/combinations` 创建,生产路径设置 `reserve=true`;随后按 `instruction` 成功、`production` 成功/失败调用 `/events`。前置修复和最终模型确认仍由上游材料决定,模拟事件不得当作真实生产订单。
12. 已验证成员可在“团队与凭据”的“API Key”创建、列出和撤销自己的测试 Key;owner/admin 还可管理本组织其他 Key。列表会显示前缀、末四位、创建时间、最近成功使用时间和创建人,撤销后还会显示撤销时间,便于审计和轮换;可用“有效 / 已撤销 / 全部”筛选快速核对轮换结果,从未使用的 Key 显示“从未使用”,已撤销或异常的审计值显示“不可用”,不会伪造日期。密钥只显示一次,应立即保存到本地受控密码管理器,不要发群或写入 Issue。页面提供“清除”按钮,并会在 60 秒后自动清除一次性密钥。撤销前会要求确认,撤销后立即失效且不可恢复。

运营回调故障可通过受控 operator token 调用 `POST /v1/internal/organizations/{organizationId}/callbacks/{id}/redeliver` 重置单条未成功投递;这只影响通知,不会重跑任务或再次结算。

## 反馈和证据

请反馈:时间、组织 ID(可脱敏)、请求路径、幂等键、返回的业务 ID、HTTP 状态和脱敏错误码。不要发送验证码、Bearer Key、Cookie、上游密钥、客户原始图片或生产地址。

当前模拟闭环明确标记 `simulated: true`,不代表方仔上游真实联调。固定说明书+生产的业务顺序是 `ModelRepair → instruction → production via PlaceOrder`;真实联调还需要最终字段/路径、受控测试地址、鉴权方式、回调签名/查询/幂等规则和脱敏请求响应样例。这些材料到位后由集成负责人逐项回读。公网 HTTPS、邮件投递、对象存储和回滚证据未完成前,不把临时入口称为一期上线。

返回 API 文档