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
摘要
合作方 API 密钥获得固定的 test 或 live 模式(Stripe 风格),使用同一主机。测试密钥只操作隔离的、按合作方划分的测试数据:合成测试房东、模拟认领与授权同意、模拟房源审核以及完整重置。live 密钥与房东 grm_ 密钥的行为不变。
- 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 中可用,并可原样延续到生产环境。
拆分
完整的 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 |
| Q10 | Bun 校验在合作方密钥模式/前缀不符时失败即拒绝;PartnerKeyAuth 在每条路由上设置模式;删除 PartnerLandlordScope。 | 默认为 live;保留固定。 | 4.1, 4.2 |
| Q11 | 测试创建跳过全局邮箱预留;预留查询与清理只看到 live 行。 | 跨模式共享邮箱索引。 | 4.3 |
| Q12 | 现在修改管理员路由和面板调用方;进行中的所有者路由必须复用共享校验器。 | 在此实现所有者路由。 | 4.1, 7.2 |
| Q13 | 100 个房东上限在 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 |
| C6 | live 密钥访问 /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.goinsertReservation)。- “已认领”的含义是用户拥有任意
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 合作方请求的行为与现在完全相同。
测试房东、认领与授权同意
测试房东身份(Bun)
测试房东是真实的 users 行,因此所有房东代码路径都可用。一次 Bun Drizzle SQL 迁移新增:
test_landlordBOOLEAN NOT NULL DEFAULT FALSEtest_partner_idTEXT NULL,创建它的合作方,附带CHECK (test_landlord = (test_partner_id IS NOT NULL))test_email_labelTEXT NULL,仅在test_landlord时存在,并在(test_partner_id, test_email_label) WHERE test_landlord上建唯一部分索引
- 保留邮箱
landlord+<uuid>@sandbox.invalid。它从不来源于合作方输入,也永远收不到邮件。 - 没有可用凭证。测试房东从不拥有密码、OAuth 关联或令牌。认领后它有一条
accounts行,provider 为sandbox。sandbox不是已注册的 Better Auth provider,因此无法用它登录。 - 每条认证路径都设防。Bun 在所有登录方式(一个会话创建保护覆盖邮箱、OAuth 及以后的任何方式)、密码重置与忘记密码、以及真实凭证关联路由(
/api/internal/partner/landlords/:id/credential)上拒绝测试房东。Go 的真实认领路径也会拒绝它们(claimEligible)。 - Go 读取
test_landlord和test_partner_id,复用已有的身份读取(ClaimTokens.LockIdentity、ConsentUsers.LockConsentIdentity)。
用测试密钥创建新房东
POST /landlords的请求、响应、201/200以及partner_landlord_ref幂等性与生产环境相同。- Bun 的内部房东路由接收
test标志和合作方 ID。测试模式下,它创建测试房东,并把规范化后的email(与生产相同的规范化)存为test_email_label。它从不用合作方输入设置users.email,也从不查询真实账户。 - 触发
landlord_exists。测试模式下,如果该标签已被同一合作方的另一个测试房东占用,Bun 报告已有用户,Go 返回409 landlord_exists,与生产环境对已注册邮箱的处理一致。同引用重放会先被检查,永远不会到达标签检查。provisioning-ID 标记匹配属于崩溃恢复,与生产一致。 - 标签命名空间按合作方划分且仅限测试。它无法泄露真实账户或其他合作方的数据。
- 合作方提供的真实
email也作为requested_email保存在授权上,仅作信息用途。
模拟认领
POST /api/partner/v1/test/landlords/{landlord_id}/claim请求 Bun 添加sandboxaccounts 行。Bun 获取与真实凭证关联相同的按房东锁(ADR-0072)。- 此后在所有读取
claimed的地方,该房东都显示为已认领。在此之前,提交返回409 landlord_unclaimed,与生产一致。重复调用返回409 already_claimed。
已有房东与授权同意
POST /api/partner/v1/test/landlords创建一个独立的、已认领的测试房东(带sandbox行),不创建授权。可选的email设置其test_email_label。它代表“已经拥有账户的房东”。POST /connect-requests的行为与生产一致,并返回approve_url。- 真实授权同意拒绝测试请求。真实的
Get、Decide(批准和拒绝)以及SetupEmail对测试连接请求返回类型化错误,且在任何状态变更、邮件或授权之前返回。授权同意页(routes/connect/[token].tsx)显示“这是一个测试请求。请使用模拟端点。”真实登录用户永远无法批准或拒绝测试请求。 - 模拟端点:
POST /test/connect-requests/{id}/approve,请求体{landlord_id}。该房东必须是同一合作方的测试房东。授权获得全部请求的权限范围,与生产一致。POST /test/connect-requests/{id}/decline。POST /test/connect-requests/{id}/expire设置status = 'expired',并把expires_at设为数据库时间。
- 批准和拒绝要求请求处于待处理且未过期状态。任何终态请求——已批准、已拒绝或已过期,包括对同一操作的重放——都返回
409 connect_request_status_conflict。 - 批准和拒绝返回
redirect_uri,附带生产查询参数(connect_request_id、status),但仅当该 URI 位于合作方当前白名单中,与生产一致。否则不返回重定向。 - 重新批准会替换授权的完整权限范围集合,与生产一致。它从不改变授权的模式。
无邮件、无可兑换认领令牌
测试房东永远不会收到邮件或可兑换的认领令牌。该规则在每条发送路径上按房东类型强制执行,而不是依赖邮件退信:
| 路径 | 测试模式行为 |
|---|---|
POST /landlords → claims.issueInTx + deliver | 记录一条模拟签发行;无密钥,无邮件。 |
POST /landlords/{id}/claim-email → ResendClaim | 响应和限流与生产相同;记录一条模拟签发行;无密钥,无邮件。 |
授权同意批准 → NotifyPartnerConnected | 测试请求无法到达;模拟批准不发送任何内容。 |
授权同意 SetupEmail | 对测试请求拒绝。 |
| 任何通用认证邮件(验证、重置、魔法链接) | 对测试房东拒绝。 |
模拟端点的保护
- Better Auth 的
verifyApiKey仍会记录 live 密钥的请求,与任何已认证调用一样;只有 Go 的每小时限流器被跳过。 - 这些路由在契约中有文档。它们不是秘密,只是无法用 live 密钥使用。
- 模拟只作用于调用方合作方的测试房东、测试授权和测试连接请求;其他任何资源都返回该资源的隐藏式
404。 - 权限和授权链与真实对应操作一致:
| 端点 | 密钥权限 | 授权 |
|---|---|---|
POST /test/landlords/{landlord_id}/claim | landlords:write | 任意有效的测试授权(与 claim-email 相同的链) |
POST /test/landlords | landlords:write | — |
POST /test/connect-requests/{id}/approve|decline|expire | landlords:write | — |
POST /test/landlords/{landlord_id}/listings/{id}/review | listings:write | listings:write |
POST /test/reset | landlords:write | — |
房源审核模拟与重置
房源提交与审核
- 合作方渠道的测试房源在提交时进入
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 行不受影响:房产照片和证明不使用它们。
- 获取排他锁。
- 读取存储键
读取该合作方测试照片和证明的存储键。
- 删除对象
PhotoStore.Remove、ProofStore.Delete。对象不存在也算成功。任何其他存储故障返回503 media_unavailable;行和键保留,重试时仍能找到。 - 删除租赁数据行
一个 Go 事务删除上面列出的租赁数据行。
- 删除测试房东
Bun 通过一个内部路由删除它们,该路由只删除
test_landlord = true且属于指定test_partner_id的用户。 - 释放锁。
第 4 步的 Go 失败或第 5 步的 Bun 失败返回 503。每一步都可安全重试。成功时返回 200 及删除数量,表示所列内容已全部删除。
上限
-
test_landlord_capcount(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_reached | 409 | 新增。POST /landlords、POST /test/landlords |
connect_request_status_conflict | 409 | 新增。模拟批准、拒绝、过期 |
route_not_found | 404 | 已有。live 密钥访问 /test/* |
already_claimed, landlord_unclaimed, landlord_exists, listing_status_conflict, rate_limited | 409/429 | 已有。在会返回它们的测试操作上注明 |
invalid_api_key | 401 | 已有。现在也适用于模式缺失/无效或前缀不匹配的合作方密钥 |
auth_unavailable, media_unavailable | 503 | 已有。重置时 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.go | is_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_*.sql | test_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)
- 对每个合作方资源族验证跨模式隐藏:房东、授权、连接请求、房产、房源、照片、证明、外部引用、联系人。租约、协议、付款记录、交接、看房请求和报价使用由测试模式房产拥有的预置固定数据;不新增需求侧 API。
- 每一处管线反转:合作方测试密钥创建并读取
is_test行;live 密钥读取它们得到404;房东/api/v1和面板行为不变。 - 按模式的
partner_landlord_ref唯一性;Grants.Connect拒绝模式变更,包括对已撤销行。 - 用邮箱 X 的测试创建不影响用邮箱 X 的 live 创建或预留,也绝不删除 live 预留。
/test/*:无密钥401;live 密钥404 route_not_found且不计入 Go 限流器;停用合作方403;模拟拒绝 live 房东、live 授权、其他合作方的测试资源以及已撤销的测试授权。- 测试创建:响应与生产相同;标签冲突
409 landlord_exists;同引用重放优先于标签;无邮件;写入模拟签发行;紧接着的claim-email返回与 live 相同时机的429;模拟行永远无法被认领。 - 模拟认领:之前提交
409 landlord_unclaimed,之后成功;重复调用409 already_claimed;emailVerified保持 false。 - 连接:模拟批准授予全部请求的权限范围;拒绝;过期写入状态和过期时间;每个终态重放
409 connect_request_status_conflict;仅对当前白名单内 URI 重定向;重新批准替换权限范围。真实会话Get/Decide/SetupEmail拒绝测试请求,且无状态变更或邮件。 - 审核:测试提交进入
pending_review且不排队房源检查(重新提交和强制重新审核的编辑也一样);批准设置为带 slug 的live,操作者为合作方,无通知/outbox/webhook;拒绝存储review_reason;非待审核409 listing_status_conflict;grm_test提交仍进入live并仍排队检查。 - 重置:只删除调用方的测试数据,包括已撤销的测试授权和残留房东;live 数据、审计历史和其他合作方的数据保留。第 3 步存储失败时保留行并返回
503;Go 或 Bun 失败返回503;重试可完成。测试写入会等待正在进行的重置。 - 幂等标记:合作方测试请求在认领/进行中和已完成的行上写入
partner_id和is_test = true;live 合作方行写入is_test = false;房东/api/v1行的partner_id为 null。重置删除调用方的测试行,包括已撤销(已删除)密钥的行,并保留 live 行、其他合作方的行和房东行。live 和/api/v1的重放与冲突行为不变。 - 清理:过期的合作方测试房产在
PurgeTestProperties后保留;过期的grm_test房产仍被清理。 - 并发创建下的 100 房东上限;残留房东在重置前计入。
- 测试活动不触发 webhook 捕获。
- 合作方测试联系人:有有效测试授权时,
PUT …/contact/phone成功,GET …/contact只对合成房东读回;真实用户的联系人不变;live 密钥无法读取;没有有效同模式授权时请求返回隐藏式404。房东grm_test_密钥仍得到409 test_key_read_only。
Bun 测试
- 缺少
mode或前缀不匹配时,合作方密钥创建失败即拒绝;前缀为grp_${mode}_。 - 对模式缺失/无效或前缀不匹配的合作方密钥,校验返回
401 invalid_api_key。 - 测试房东无法通过任何方式登录、重置密码、触发认证邮件或关联真实凭证。
sandbox行不是可用的 provider。 - 上限按合作方原子计数;标签在同一合作方的测试房东中唯一。
- 内部删除路由只删除指定合作方的测试房东。
前端测试
面板密钥表单发送 mode;授权同意页显示测试请求提示。
UAT 冒烟运行
使用真实密钥,并在确认 GO_ENV=development 及 UAT 数据库主机之后:
- 测试密钥流程
使用
grp_test_密钥:GET /me显示test→ 创建房东 → 模拟认领 → 房产、产权证明、房源 → 提交(pending_review)→ 模拟批准(live,不出现在公开网站)→ 创建独立测试房东 → 连接请求 → 模拟批准 → 重置。 - live 密钥隔离
使用
grp_live_密钥:/test/*返回404;看不到任何测试数据。 - 清理
之后撤销冒烟运行使用的密钥。
非目标
- 需求侧模拟和测试 webhook 端点(子项目 2)。
- 自助测试密钥界面、所有者密钥路由和文档(子项目 3 及进行中的工作)。
- 独立的沙箱部署。
- 重复地址暂扣的模拟。
- 修改房东
grm_test行为。 - 超出现有测试标签之外的合作方测试数据管理工具。
批准关卡
用户已批准环境模型(每个部署内的测试模式)、三方拆分、测试房东方案、模拟审核、固定模式密钥、重置以及全部四个对话设计章节。该批准允许编写本书面规格,而非实现。