English

Partner API — Test Mode Foundation (Sub-project 1)

Partner API keys gain a fixed test or live mode on the same host, Stripe-style, so partners can build and verify their supply-side integration against isolated, partner-scoped test data before switching to a live key. Synthetic test landlords, simulated claim, consent and listing review, and a full reset replace the old 'integrate against UAT' rule without changing live-key or landlord grm_ key behaviour.

  • Predecessor Partner API P1 design (replaces decision D8)
  • ADRs 0072
  • Status Approved

View source markdown ↗ generated by claude-opus-5-5 · diagrams mermaid

摘要

合作方 API 密钥获得固定的 test 或 live 模式(Stripe 风格),使用同一主机。测试密钥只操作隔离的、按合作方划分的测试数据:合成测试房东、模拟认领与授权同意、模拟房源审核以及完整重置。live 密钥与房东 grm_ 密钥的行为不变。

  • 状态已于 2026-10-10 在 grill-with-docs 评审后批准;未实现
  • 范围三个子项目中的第 1 个:测试模式基础
  • 取代P1 决策 D8(“没有测试/沙箱模式;合作方对接 UAT”)
  • 相关 ADRADR-0072(本次评审新增测试模式例外)
Go
合作方 API 位于 backend/go/internal/modules/rental
Bun
合作方密钥、密钥校验与测试房东身份位于 backend/bun
契约
backend/go/openapi/partner-v1.yaml
前端
授权同意页位于 frontend/solidstart/apps/rental;合作方密钥表单位于 frontend/solidstart/apps/panel
前置设计
P1 设计(取代其决策 D8)

意图与成功标准

每个合作方都需要两个环境:Testing,用于构建和验证集成;Production,测试通过后迁移到这里。Production 目前尚不存在,但环境模型应在它出现之前就位。

选定的模型是在每个平台部署内部提供 Stripe 风格的测试模式。合作方在同一 API 主机上持有 test 和 live 密钥。测试密钥永远只能看到隔离的测试数据。该模型今天在 UAT 中可用,并可原样延续到生产环境。

前后对比:现在合作方密钥被固定为 live,测试行被隐藏;之后按密钥的固定模式写入,只能读取同模式的行。 现在 合作方密钥 固定为 live 测试行被隐藏 之后 grp_test_ 密钥 模式来自密钥 只读同模式数据
合作方模式处理的前后对比:在每个写入方和读取方中,已认证密钥的固定模式取代硬编码的“合作方即 live”规则。

拆分

完整的 Testing 环境拆分为三个子项目,各自拥有独立的规格、计划和实现。子项目 1 的内部顺序由其实现计划决定。拆分方式与批准关卡保持已批准的状态。

子项目依赖关系。
子项目依赖关系。
#子项目依赖
1测试模式基础(本规格):密钥模式、模式传递、按合作方隔离、带模拟认领/同意的测试房东、模拟房源审核、重置。—
2需求侧模拟:测试看房请求、消息、报价、租约、付款、交接;测试 webhook 端点与事件。1
3自助与文档:自助门户中的 test/live 密钥选择;开发者文档中的 Testing 与 Production。1,以及进行中的门户和文档工作

已批准的对话决策

环境模型

每个部署内部的测试模式;同一主机,由密钥决定环境。

已否决:独立的沙箱部署(第二套技术栈、单独注册、配置漂移)以及把 UAT 当作 Testing(不稳定、共享、发送真实邮件)。

测试房东与人工步骤

测试密钥使用常规端点,这些端点创建或指向合成的、不可交互的测试房东。认领与授权同意通过仅限测试的模拟端点完成。

已否决:预置固定数据(无法覆盖入驻代码)以及真人测试账户(慢、真实邮件、无法自动化)。

房源审核

测试提交返回 pending_review;由模拟端点批准或拒绝。

已否决:自动批准(无法测试审核状态)以及定时自动决定(不确定,且无法拒绝)。

凭证

每个密钥都有固定模式,并在前缀中体现:grp_test_… 或 grp_live_…。

已否决:单个密钥加模式请求头(一个凭证可访问两个环境;缺少请求头即为 live)以及每种模式单独的合作方记录(需要同步两个身份)。

清空重来

仅限测试的 POST /test/reset 删除该合作方的全部测试数据。

已否决:仅靠常规清理(数据堆积;部分内容无法删除)以及自动过期(数据在测试中途消失)。

评审结论

每一行都是书面规格评审中的一项决策;所列章节包含细节。W1 和 W2 是回写验证时的更正。它们恢复了已接受的重置不变量和集成一致性不变量,并未缩小范围。

ID结论已否决的替代方案§
Q1“合作方即 live”在每个写入方和读取方中都被反转,而不只是中间件的固定。依赖现有用例(它们把合作方行硬编码为 live)。4.2
Q2已认领的测试房东拥有一条无密码的 sandbox accounts 行:已认领,但没有可用凭证。所有登录、重置和凭证关联路径都拒绝测试房东。“没有 accounts 行”(无法认领);随机隐藏密码(仍是凭证)。5.1, 5.3
Q3模拟批准授予全部请求的权限范围。请求体只有 {landlord_id}。权限子集(生产环境无法产生)。5.4
Q4测试房东在任何发送路径上都收不到邮件,也不会获得可兑换的认领令牌。依赖 .invalid 邮件退信。5.5
Q5同一合作方的测试邮箱标签让合作方可以触发 409 landlord_exists。忽略邮箱(回退分支无法测试);查询真实账户(可被探测)。5.2
Q6/test/* 在契约中公开,不是秘密。live 密钥在认证之后、Go 限流器之前得到 404。“不可见”的接口面。5.6
Q7模拟审核只改变状态。合作方测试数据不产生通知、outbox、webhook 或 AI 房源检查。复用管理员审核的副作用。6.1
Q8 / C1 / W1重置在按合作方的排他锁下先删对象,再删行,最后删用户。幂等行通过持久化的 partner_id + is_test 标记查找。成功意味着完全清理;任何失败都返回 503 且可安全重试。尽力删除媒体;接受孤儿对象;新的 saga 框架;从 Bun 预取密钥 ID(已撤销密钥被物理删除);把行留给按时间的清扫。3, 6.2
Q9真实的授权同意端点在服务端拒绝测试连接请求。仅在页面上提示。5.4
Q10Bun 校验在合作方密钥模式/前缀不符时失败即拒绝;PartnerKeyAuth 在每条路由上设置模式;删除 PartnerLandlordScope。默认为 live;保留固定。4.1, 4.2
Q11测试创建跳过全局邮箱预留;预留查询与清理只看到 live 行。跨模式共享邮箱索引。4.3
Q12现在修改管理员路由和面板调用方;进行中的所有者路由必须复用共享校验器。在此实现所有者路由。4.1, 7.2
Q13100 个房东上限在 Bun 中按合作方加锁原子计数。在 Go 中统计授权(漏掉独立房东;有竞态)。6.3
C2自动测试清理跳过合作方来源的房产。让合作方测试数据过期。4.4
C3引用索引按模式区分;连接 upsert 永不改变授权的模式;重置删除已撤销的测试授权。不区分模式的 upsert。4.3, 6.2
C4模拟批准/拒绝使用当前的重定向白名单;过期操作同时写入状态和过期时间;终态请求返回 409 connect_request_status_conflict。无条件重定向;重放时 200 空操作。5.4
C5模拟认领和审核使用与其真实对应操作相同的授权链。仅要求“属于调用方”。5.6
C6live 密钥访问 /test/* 时只跳过 Go 的限流器;Better Auth 仍记录使用量。“完全不计用量”。5.6
W2联系电话保护只作用于房东测试密钥;合作方测试密钥可写入合成房东的联系人。把保护扩展到合作方测试密钥(供给侧代码会因模式而不同);推迟到子项目 2。4.2
C7需求侧隐藏只用预置的 pg-test 固定数据测试。现在就加入需求侧测试 API。10
R1认领限流计数使用现有令牌表中的模拟签发行。单独的尝试表(第二次查询);不计数(429 时机不同)。5.5

现有基础

基于仓库中的观察。第二张卡片列出本设计必须修改现有代码的原因(源文档中标记为 ⚠)。

可直接复用

已存在
  • 房东 API 密钥已带有必填的 metadata.mode,前缀为 grm_live_/grm_test_;缺失或无效模式会失败即拒绝(landlord-keys.routes.ts);Bun 校验会检查模式与精确前缀(internal.routes.ts:669-677)。
  • Go 的 API 密钥中间件设置 key_mode,取值来自 metadata.mode(api_key_auth_middleware.go:158-163);用例把它与 is_test 比较(例如 usecase/listing.go:94)。
  • is_test 已存在于 rental_properties、rental_listings、rental_property_external_refs 上;下游读取方通过 landlord_scope.go:18 跟随房产的模式。
  • 房源状态机把测试提交直接送到 live(entity/listing.go:151-152)。
  • 管理员审核队列已排除测试房源(listing_repository.go:292);重复地址清扫跳过测试房产(usecase/duplicate_check_sweep.go:233-243);webhook 捕获跳过测试房源(usecase/webhook_capture.go:117)。
  • 合作方房东是 Bun 的 users 行;Bun 会写入 partner_provisioning_id(internal.routes.ts:244-310、packages/auth-adapter/drizzle/0008_add_partner_provisioning_id.sql)。

必须修改

⚠
  • 合作方密钥不带模式:admin-partner-keys.routes.ts:170-175 删除了 metadata.mode;Bun 校验只检查 grp_ 前缀(internal.routes.ts:679-683);PartnerKeyAuth 从不设置 key_mode(partner_key_auth.go:80-89);PartnerLandlordScope 只在按房东的路由上固定为 live(partner_scope.go:60-69)。
  • 合作方行被硬编码为 live:usecase/property.go:144-145(IsTest = !origin.IsPartner && …)、hiddenFromPartner(usecase/origin.go:75-80,7 个调用方)、|| prop.IsTest(位于 usecase/property_lifecycle.go:106,324,495),以及 PropertyRepository.ListByOwner 和 ProofUseCase 中仅针对合作方的 live 过滤。
  • rental_partner_grants 和 rental_partner_connect_requests 没有模式。uq_rental_partner_grants_partner_ref 为 (partner_id, partner_landlord_ref) WHERE status <> 'revoked';uq_rental_partner_grants_requested_email_provisioning 跨合作方全局生效;其他合作方被放弃的预留可能被删除(partner_provisioning.go insertReservation)。
  • “已认领”的含义是用户拥有任意 accounts 行(landlord_claim_checker.go:22)。
  • 真实授权同意授予全部请求的权限范围(partner_consent.go:157),仅对当前白名单内的 URI 返回重定向(partner_consent.go:183),并发送 NotifyPartnerConnected。
  • 认领限流按 rental_partner_claim_tokens 行计数(partner_claim_token_repository.go:53-54);token_hash 为 NOT NULL UNIQUE。
  • 照片和证明直接保存 storage_key,位于 rental_property_photos / rental_ownership_proofs 上(photo.go:292、proof.go:125),随房产级联删除,并且不使用共享的 uploads 表。删除 API:PhotoStore.Remove(application/port/ports.go:277-278)、ProofStore.Delete(proof_store.go:97)。
  • ListTestPurgeCandidates 会清理所有过期的 is_test 房产(property_repository.go:489-507)。
  • 提交和强制重新审核的房产编辑会排队 AI 房源检查,且没有测试过滤(usecase/listing.go:349、usecase/lifecycle.go:89)。
  • 合作方密钥撤销会物理删除 Better Auth 的 apikey 行(admin-partner-keys.routes.ts:354-368)。rental_idempotency 只按 (api_key_id, idempotency_key) 建键,没有合作方或模式,且只由 usecase/idempotent_executor.go 写入。
  • PUT …/contact/phone 对所有测试密钥返回 409 test_key_read_only(v1_contact_handler.go:46);它为房东 grm_test_ 密钥编写,合作方因被固定为 live 而从未触达。

模式模型与请求流程

密钥(Bun)

  • 创建合作方密钥时必须提供 mode,取值为 test 或 live,存为 metadata.mode。前缀按每次调用计算为 grp_${mode}_,与房东密钥一致。缺失或无效模式以 400 失败即拒绝。删除去除模式的那一行代码。
  • 校验逻辑放在一个共享的 Bun 辅助函数中。目前只有管理员路由签发合作方密钥(admin-partner-keys.routes.ts);进行中的所有者路由(§7.2)必须调用同一辅助函数。
  • 密钥签发后模式永不改变。
  • 面板管理员密钥表单及其客户端发送 mode。自助测试密钥属于子项目 3。
  • 每个密钥的每小时额度不变;test 和 live 密钥各自独立。

处理管线(Go)

  • PartnerKeyAuth 在 Echo 上下文和请求上下文中设置 key_mode,覆盖每一条合作方路由,取值来自已校验密钥的模式。没有默认值。
  • PartnerLandlordScope 变为空并被删除。其调用方和测试迁移到新行为。
  • 需要反转的位置,均在范围内:
    • usecase/property.go:144-145:合作方房产的 is_test 取自密钥模式。
    • hiddenFromPartner(usecase/origin.go)变为“房产模式与密钥模式不同”。7 个调用方继续调用它。
    • usecase/property_lifecycle.go:106,324,495:用模式比较替换 || prop.IsTest。
    • PropertyRepository.ListByOwner 和 ProofUseCase 的合作方过滤:按密钥模式过滤,而不是“仅 live”。
    • 实现时还需审查外部引用、图库同步、照片、房源 upsert、房源检查表单以及下游读取方(租约、协议、付款记录、交接、联系人、咨询、报价),查找其他“合作方 ⇒ live”的假设。
  • 跨模式的 ID 返回该资源通常的隐藏式 404。
  • 认证、停用(403 partner_suspended)、权限、密钥上限、授权检查和限流在两种模式下完全相同。
  • GET /me 新增 mode: "test" | "live"。

按合作方划分的数据

  • rental_partner_grants 和 rental_partner_connect_requests 新增 is_test BOOLEAN NOT NULL DEFAULT FALSE,创建时由密钥模式设置。
  • uq_rental_partner_grants_partner_ref 改为 (partner_id, is_test, partner_landlord_ref) WHERE status <> 'revoked'。
  • 授权解析(RequireGrant)、房东列表和连接请求读取按调用方模式过滤。测试密钥永远看不到 live 授权、房东或连接请求,反之亦然。
  • 授权模式等于房东类型。测试授权只引用同一合作方的测试房东;live 授权只引用非测试用户。在授权激活和连接时强制执行。
  • 模式不可变。Grants.Connect 的 ON CONFLICT (partner_id, landlord_user_id) DO UPDATE(partner_grant_repository.go:393)只在 is_test 匹配时更新,包括重新激活已撤销行的情况。不匹配是错误,绝不翻转模式。
  • 邮箱预留仅限 live。uq_rental_partner_grants_requested_email_provisioning 增加 AND is_test = FALSE。GetProvisioningByEmail 和 DeleteAbandonedReservation 只读取和删除 live 行。测试创建跳过全局邮箱预留步骤,但保留合作方/模式/引用的预留以及 provisioning-ID 标记,因此崩溃恢复和同引用重试与生产环境一致。
  • 测试授权保留合作方提供的真实 requested_email,仅作信息用途。它从不参与预留、查询、账户创建或邮件。

合作方 API 之外的隔离

  • 测试数据永远不会进入公开网站、搜索、租客应用、通知或 webhook 管线。
  • 管理员审核队列已隐藏测试房源。管理面板仅在已显示房东测试数据的地方显示测试数据,并标注为测试。
  • 自动清理排除合作方数据。ListTestPurgeCandidates 增加 AND p.origin_partner_id IS NULL。房东 grm_test 行保留 30 天过期规则。合作方测试数据只能通过重置删除。
  • live 合作方请求的行为与现在完全相同。

房源审核模拟与重置

房源提交与审核

  • 合作方渠道的测试房源在提交时进入 pending_review,并经过与生产相同的检查:声明、产权证明和已认领房东。房东 grm_test_ 的提交仍直接进入 live。
  • 合作方测试数据不做 AI 房源检查。每条入队路径都跳过合作方拥有的测试房源:提交、重新提交以及强制重新审核的房产编辑(usecase/listing.go:349、usecase/lifecycle.go:89)。房东 grm_test 行为不变。契约注明房源检查在 Testing 中不运行。
  • 模拟:POST /test/landlords/{landlord_id}/listings/{id}/review,请求体 {decision: "approve" | "reject", reason?}。
    • approve 设置为 live,并像生产一样分配 slug。房源对合作方可见,但从不公开。
    • reject 设置为 rejected,并把 reason 存为 review_reason(拒绝时 reason 必填)。
    • 审核元数据(审核时间、审核人)和审计行记录合作方服务用户为操作者。不虚构管理员审核人。
    • 不创建批准通知、outbox 行或 webhook。
    • 除 pending_review 外的任何状态都返回 409 listing_status_conflict。
  • 测试房产继续排除在重复地址清扫之外,因此测试密钥无法探测真实地址。duplicate_under_review 无法在 Testing 中触发;契约会说明这一点。
合作方测试房源的模拟审核。
合作方测试房源的模拟审核。

重置

POST /api/partner/v1/test/reset 删除调用方合作方的全部测试数据:

  • test_partner_id 为该合作方的测试房东,包括独立房东和残留房东;
  • 该合作方的测试授权(所有状态,包括已撤销)和测试连接请求;
  • 这些房东拥有的测试房产,及其级联的房源、照片、证明、外部引用、重复提示/标记和房源检查;
  • 已存储的照片和证明对象;
  • 这些房东的 rental_contacts 和认领令牌行(真实或模拟);
  • 所有 rental_idempotency 行中标记为 partner_id = caller AND is_test = true 的行,包括认领/进行中的行以及已撤销并被物理删除的密钥的行。

测试密钥、live 数据、审计历史和其他合作方的数据不受影响。共享的 uploads 行不受影响:房产照片和证明不使用它们。

  1. 获取排他锁。
  2. 读取存储键

    读取该合作方测试照片和证明的存储键。

  3. 删除对象

    PhotoStore.Remove、ProofStore.Delete。对象不存在也算成功。任何其他存储故障返回 503 media_unavailable;行和键保留,重试时仍能找到。

  4. 删除租赁数据行

    一个 Go 事务删除上面列出的租赁数据行。

  5. 删除测试房东

    Bun 通过一个内部路由删除它们,该路由只删除 test_landlord = true 且属于指定 test_partner_id 的用户。

  6. 释放锁。

第 4 步的 Go 失败或第 5 步的 Bun 失败返回 503。每一步都可安全重试。成功时返回 200 及删除数量,表示所列内容已全部删除。

上限

  • test_landlord_cap count(users WHERE test_landlord AND test_partner_id = $partner),在按合作方的咨询锁下,与创建处于同一事务 100
  • 计数包括独立房东和未完成重置留下的残留房东,直到重置成功为止。
  • 同引用重放或标签冲突不会创建用户,也不会被上限拒绝。
  • 此后通过 POST /landlords 或 POST /test/landlords 的创建返回 409 test_landlord_limit_reached,直到合作方执行重置。
  • 其他所有限制与生产一致。

契约与依赖

契约(backend/go/openapi/partner-v1.yaml)

  • 新增七个仅限测试的操作(认领、创建测试房东、连接批准/拒绝/过期、房源审核、重置),每个都标记 x-test-only: true,并注明 live 密钥的 404 route_not_found 以及上述权限。
  • 记录密钥 mode、grp_test_/grp_live_ 前缀以及按模式隔离;新增 mode 字段到 GET /me。
  • 说明:测试房产跳过重复检查;房源检查在 Testing 中不运行;合作方测试数据从不自动清理,只能通过重置删除;测试房东不接收邮件。
错误码状态码出现位置
test_landlord_limit_reached409新增。POST /landlords、POST /test/landlords
connect_request_status_conflict409新增。模拟批准、拒绝、过期
route_not_found404已有。live 密钥访问 /test/*
already_claimed, landlord_unclaimed, landlord_exists, listing_status_conflict, rate_limited409/429已有。在会返回它们的测试操作上注明
invalid_api_key401已有。现在也适用于模式缺失/无效或前缀不匹配的合作方密钥
auth_unavailable, media_unavailable503已有。重置时 Bun 或存储失败

新错误码加入 x-error-codes 和 ErrorCode 枚举。后端契约漂移测试覆盖新操作。仅浏览器使用的授权同意错误属于租赁会话 API,而非合作方契约。房东 API 契约和文档保持不变。

对进行中工作的依赖

  • 自助所有者密钥。所有者签发方计划在 backend/bun/openspec/changes/partner-self-serve-keys 中实现;门户设计规划了 POST /api/partner-portal/keys,目前未包含 mode(frontend/solidstart/openspec/changes/partner-self-serve-portal/design.md:27-29,39)。前提条件:该工作必须调用共享的模式校验器,并在子项目 3 加入选择器之前发送 mode: "live"。本规格不实现它。
  • 开发者文档。已批准的开发者集成规格说明合作方在 UAT 中测试,没有 test/live 密钥模式。子项目 3 会在本项目上线后修订它;本规格不修改它。
  • Webhooks。保持仅限 live。捕获已跳过测试房源;本子项目新增回归检查,确保测试活动不会被捕获。测试 webhook 端点属于子项目 2。

整体设计中否决的方案

  • 独立沙箱部署、模式请求头、按模式分离的合作方记录、自动批准、定时决定、合作方测试数据自动过期。
  • 用于重置的通用 saga 或清理框架。
  • 在此实现自助所有者密钥路由或需求侧模拟。

受影响的文件

Go(backend/go/internal/…)
文件变更
api/http/middleware/partner_key_auth.go在每条合作方路由上设置 key_mode;无默认值。
modules/rental/adapter/inbound/http/partner_scope.go删除 PartnerLandlordScope。
modules/rental/adapter/inbound/http/partner_routes.go移除该作用域;按保护顺序添加模式保护和 /test/* 路由。
modules/rental/adapter/inbound/http/partner_landlord_handler.go, partner_connect_handler.go,新的测试模拟处理器模拟端点;GET /me 模式。
modules/rental/adapter/inbound/http/partner_consent_handler.go类型化的测试请求拒绝。
modules/rental/adapter/inbound/http/v1_contact_handler.go将只读保护限定为房东 API 测试密钥。
modules/rental/application/usecase/property.go, origin.go, property_lifecycle.go, proof.go, listing.go, lifecycle.go, listing_check_queue.go(或其调用方), review.go(仅状态辅助函数)模式反转;跳过房源检查;模拟审核。
modules/rental/application/usecase/partner_provisioning.go, partner_claim.go, partner_consent.go, partner_connect.go, partner_grants.go测试创建、模拟签发、授权同意拒绝、白名单重定向、过期。
modules/rental/adapter/outbound/persistence/postgresql/partner_grant_repository.go, partner_connect_request_repository.go, partner_claim_token_repository.go, property_repository.go, idempotency_repository.go模式过滤、不可变 upsert、仅 live 预留、模拟行、清理排除、幂等标记列、重置删除。
modules/rental/application/usecase/idempotent_executor.go, domain/entity/idempotency.go在每个创建的行上写入 partner_id 和 is_test。
modules/rental/adapter/outbound/client/bun_partner_client.go测试标志、模拟认领、删除测试房东。
shared/infrastructure/database/postgresql/migrations/migrator_rental.gois_test 列、索引变更、认领令牌 simulated、rental_idempotency.partner_id + is_test。
modules/rental/module.go依赖装配。
Bun(backend/bun/…)
文件变更
apps/monolith/src/api-gateway/routes/admin-partner-keys.routes.ts + 共享校验器必填模式,grp_${mode}_ 前缀。
apps/monolith/src/api-gateway/routes/internal.routes.ts校验失败即拒绝;带标签和上限锁的测试房东创建;sandbox 认领;删除测试房东;拒绝凭证关联。
apps/monolith/src/config/di-container.ts新用户字段;会话创建与重置保护。
packages/auth-adapter/schema.ts, packages/auth-adapter/drizzle/0009_*.sqltest_landlord、test_partner_id、test_email_label。
前端与契约
文件变更
frontend/solidstart/apps/panel/src/features/rental-admin/partnerKeys.ts, routes/admin/rental/partners/[id].tsx发送 mode(管理员签发 test 和 live 密钥)。
frontend/solidstart/apps/rental/src/routes/connect/[token].tsx, features/rental/api/connect.ts, routes/api/rental/connect/[...path].ts显示测试请求提示。
backend/go/openapi/partner-v1.yaml契约及其漂移测试。

验证

Go 集成测试(一次性 pg-test,:55432)

  1. 对每个合作方资源族验证跨模式隐藏:房东、授权、连接请求、房产、房源、照片、证明、外部引用、联系人。租约、协议、付款记录、交接、看房请求和报价使用由测试模式房产拥有的预置固定数据;不新增需求侧 API。
  2. 每一处管线反转:合作方测试密钥创建并读取 is_test 行;live 密钥读取它们得到 404;房东 /api/v1 和面板行为不变。
  3. 按模式的 partner_landlord_ref 唯一性;Grants.Connect 拒绝模式变更,包括对已撤销行。
  4. 用邮箱 X 的测试创建不影响用邮箱 X 的 live 创建或预留,也绝不删除 live 预留。
  5. /test/*:无密钥 401;live 密钥 404 route_not_found 且不计入 Go 限流器;停用合作方 403;模拟拒绝 live 房东、live 授权、其他合作方的测试资源以及已撤销的测试授权。
  6. 测试创建:响应与生产相同;标签冲突 409 landlord_exists;同引用重放优先于标签;无邮件;写入模拟签发行;紧接着的 claim-email 返回与 live 相同时机的 429;模拟行永远无法被认领。
  7. 模拟认领:之前提交 409 landlord_unclaimed,之后成功;重复调用 409 already_claimed;emailVerified 保持 false。
  8. 连接:模拟批准授予全部请求的权限范围;拒绝;过期写入状态和过期时间;每个终态重放 409 connect_request_status_conflict;仅对当前白名单内 URI 重定向;重新批准替换权限范围。真实会话 Get/Decide/SetupEmail 拒绝测试请求,且无状态变更或邮件。
  9. 审核:测试提交进入 pending_review 且不排队房源检查(重新提交和强制重新审核的编辑也一样);批准设置为带 slug 的 live,操作者为合作方,无通知/outbox/webhook;拒绝存储 review_reason;非待审核 409 listing_status_conflict;grm_test 提交仍进入 live 并仍排队检查。
  10. 重置:只删除调用方的测试数据,包括已撤销的测试授权和残留房东;live 数据、审计历史和其他合作方的数据保留。第 3 步存储失败时保留行并返回 503;Go 或 Bun 失败返回 503;重试可完成。测试写入会等待正在进行的重置。
  11. 幂等标记:合作方测试请求在认领/进行中和已完成的行上写入 partner_id 和 is_test = true;live 合作方行写入 is_test = false;房东 /api/v1 行的 partner_id 为 null。重置删除调用方的测试行,包括已撤销(已删除)密钥的行,并保留 live 行、其他合作方的行和房东行。live 和 /api/v1 的重放与冲突行为不变。
  12. 清理:过期的合作方测试房产在 PurgeTestProperties 后保留;过期的 grm_test 房产仍被清理。
  13. 并发创建下的 100 房东上限;残留房东在重置前计入。
  14. 测试活动不触发 webhook 捕获。
  15. 合作方测试联系人:有有效测试授权时,PUT …/contact/phone 成功,GET …/contact 只对合成房东读回;真实用户的联系人不变;live 密钥无法读取;没有有效同模式授权时请求返回隐藏式 404。房东 grm_test_ 密钥仍得到 409 test_key_read_only。

Bun 测试

  1. 缺少 mode 或前缀不匹配时,合作方密钥创建失败即拒绝;前缀为 grp_${mode}_。
  2. 对模式缺失/无效或前缀不匹配的合作方密钥,校验返回 401 invalid_api_key。
  3. 测试房东无法通过任何方式登录、重置密码、触发认证邮件或关联真实凭证。sandbox 行不是可用的 provider。
  4. 上限按合作方原子计数;标签在同一合作方的测试房东中唯一。
  5. 内部删除路由只删除指定合作方的测试房东。

前端测试

面板密钥表单发送 mode;授权同意页显示测试请求提示。

UAT 冒烟运行

使用真实密钥,并在确认 GO_ENV=development 及 UAT 数据库主机之后:

  1. 测试密钥流程

    使用 grp_test_ 密钥:GET /me 显示 test → 创建房东 → 模拟认领 → 房产、产权证明、房源 → 提交(pending_review)→ 模拟批准(live,不出现在公开网站)→ 创建独立测试房东 → 连接请求 → 模拟批准 → 重置。

  2. live 密钥隔离

    使用 grp_live_ 密钥:/test/* 返回 404;看不到任何测试数据。

  3. 清理

    之后撤销冒烟运行使用的密钥。

非目标

  • 需求侧模拟和测试 webhook 端点(子项目 2)。
  • 自助测试密钥界面、所有者密钥路由和文档(子项目 3 及进行中的工作)。
  • 独立的沙箱部署。
  • 重复地址暂扣的模拟。
  • 修改房东 grm_test 行为。
  • 超出现有测试标签之外的合作方测试数据管理工具。

批准关卡

用户已批准环境模型(每个部署内的测试模式)、三方拆分、测试房东方案、模拟审核、固定模式密钥、重置以及全部四个对话设计章节。该批准允许编写本书面规格,而非实现。