Landlord API — Slice 2: Idempotent Sync
Slice 1 made a landlord's API key a valid identity; nothing yet stopped a nightly sync writing the same flat twice. Slice 2 makes every write repeatable through per-source external refs, an address fingerprint that refuses to guess, a single-transaction idempotency claim, and a test-mode sandbox that never touches the public marketplace. Twenty-five decisions (D12–D36), each with its rejected alternatives recorded.
- Predecessor Slice 1 — Foundation (2026-09-19), merged in 8942b456 (PR #139)
- ADRs 0002
- Status Approved
这一片为何存在
Slice 1 让房东的 API key 成为一个有效身份。但当时没有任何机制阻止同步任务把同一间房写入两次, 所以每晚跑一次就会让市场上堆满同一个房源的副本。Slice 2 让每一次写入都可重复执行: 同一个同步任务跑一百次,最后只留下一个 property 和一个 listing。
匹配流程
一个入口负责判断传入的 property 是新的还是已知的。每一步按顺序尝试,第一个命中的胜出。
owner_user_id 与相同的 is_test —— 两个限定都不可省略。
| 步骤 | 尝试 | 结果 | 审计动作 |
|---|---|---|---|
| 0 | 此前见过的 Idempotency-Key | 重放,结束 | — |
| 1 | refs 表中的 source + external_ref | 200,该 property | update |
| 2 | 可计算时的地址指纹 | 200,认领(adopt) | adopt |
| 3 | 都没匹配上 | 201,新建 property | create |
D26 · 谁来跑这条流程?
只有 API,通过新的 PropertyUseCase.Sync。面板永远新建一行 ——
但仍然会计算并保存指纹。
认领的含义是「这是同一间房的另一个名字」,只有事后有 ref 能解释它时才成立。 人点击新增房源的意思是「造一个新的」。如果面板也跑第 2 步, 它会找到房东已有的房源并返回旧 id 和 200 —— 房东以为自己创建了房源, 实际却是编辑了旧的,而界面上没有任何提示。
已否决:在 Create 上加布尔开关(一个函数两种行为,现有测试会守错路径);
让面板也认领(改由 D33 阻止手工重复)。
D24 · 匹配成功的写入可以覆盖什么?
匹配成功的写入只做局部更新 —— 请求里没有的字段保持不变。
只有新建 property 才做整体替换。面板的 PUT 不受影响。
PropertyUseCase.Update 是 PUT 语义:缺省的可选字段会被重置为零值
(property.go:159)。用在匹配成功的写入上,就是悄悄删掉房东自己的成果。
已否决:坚持 PUT 整体替换、要求数据源发送完整记录 —— 那样只要漏掉一个字段就会造成静默数据丢失,而多数数据源只发送部分字段。
source 是什么(D22)
source 是 ref 的命名空间。它决定两个同步任务是共用一个 ref 还是各自独立,
所以它必须是标识符,不能是随意的文字。
- 格式
^[a-z0-9][a-z0-9_-]{0,31}$—— 1 到 32 个字符- 规范化
- 存储前和查询前都转成小写
- 配对
- 与
external_ref要么都给、要么都不给;只给一个返回400 - 面板写入
- 两个都不发送,也不写 ref 行
规范化器(D19)
转小写、去标点、合并空白,然后展开马来西亚常见的道路类型缩写。 没有模糊匹配,没有相似度阈值 —— 每一次匹配都能解释清楚。
jln -> jalan lrg -> lorong
tmn -> taman bdr -> bandar
kg -> kampung psn -> persiaran
blok -> block no. -> (丢弃)
fingerprint = sha256(
norm(building_name or address_line)
+ '|' + norm(unit_number)
+ '|' + postcode )
单元号写法也会规范化:#12-3、Unit 12-3 和
12 - 3 都变成 12-3。有地房产(landed)本来就没有单元号,
所以空单元号在那里是合法的,指纹照样计算。只有缺少单元号的高层住宅才会得到 NULL。
同步拒绝而非猜测的四种情况
D18 确立了原则 —— 猜测比漏掉更糟 —— 有四项决策在执行它。 每一项都返回一个点明真正问题的 409,而不是写入一个看起来合理的结果。
-
ambiguous_match第 2 步为同一房东找到 2 个以上候选D27 409 -
unit_number_required楼盘与邮编相同,任一侧缺少单元号D29 409 -
duplicate_addressunique (owner_user_id, is_test, address_fingerprint)D33 409 -
listing_not_reopenable该 property 上所有 listing 都已进入终态D21 409
D33 · 每位房东一个地址,由数据库把关
在 (owner_user_id, is_test, address_fingerprint) 上建
唯一部分索引,取代原来的普通查询索引。
写入时必须重新计算指纹,否则改了地址的 property 会永远沿用旧的哈希。
但重新计算会让一次错误的 PUT 使两行拥有相同指纹,
此后第 2 步每晚都会抛出 409 ambiguous_match,直到有人发现为止。
同一房东、同一楼盘、同一单元、同一邮编就是同一间房 ——
这是真实的不变量(invariant),所以交给数据库把关,而不是应用代码。
已否决:把指纹当作仅供参考、由应用代码检查冲突 —— 那样一次错误的 PUT 就会卡住房东的同步,直到有人去排查。
D21 · 同步永远不会重新上架一间房
当 property 上所有 listing 都处于终态时,API 的 upsert 返回
409 listing_not_reopenable,什么都不动。
uq_rental_listings_active_property 只覆盖 draft、
pending_review 和 live。一行 rented
会让该 property 没有活跃 listing,于是天真的 upsert 每晚都会新建一个草稿 ——
把已出租的房子重新上架,或者推翻管理员的驳回。
没有 listing 级别的 ref,同步无法区分旧报价的陈旧重放和一次有意的重新出租。
已否决:只允许从 withdrawn 重新创建 —— 在这一点上
withdrawn 并不比 rented 更清楚。
面板规则保持不变:entity.AllowsNewListing
(listing.go:140)仍然允许人工重新出租。
幂等性:一个事务,不需要额外记账
先干活、后记录密钥会输掉竞态。一个卡住的请求用同一个密钥重试,就会跑两遍: 两边都查密钥、都没查到、都去创建。结果要么出现两个 property, 要么唯一索引报错、其中一个调用方收到 500。
-
先认领、再干活 —— 在同一个 BEGIN 内
先
INSERT INTO rental_idempotency (…),此时resource_id仍为 NULL;接着跑解析流程;最后在COMMIT之前UPDATE填入resource_id和status_code。 -
指纹不同即为冲突
同一密钥、不同的规范化请求体 →
409 idempotency_conflict, 在唯一约束冲突后重新读取时判定。 -
请求体按规范化 JSON 哈希,而非逐字节
解码成
any、重新编码、再哈希。encoding/json本来就会给 map 的键排序,所以规范化只要三行代码。否则一次诚实的重试 只因为 JSON 键顺序变了就会收到 409 并中断同步。 -
资源已被清除时重新执行,而不是返回 404
SELECT … FOR UPDATE、删掉过期行、重新插入一次新的认领并跑流程 —— 全部在同一个事务内,因此并发的重放仍然保持串行。
十条路由各自靠什么拦住盲目重试
| 写操作 | 拦截它的机制 |
|---|---|
POST /properties | ref(第 1 步)、指纹(第 2 步),否则唯一索引(D33)→ 409 duplicate_address,或 409 unit_number_required(D29) |
PUT /properties/:id | id 明确;局部合并(D24)让重复请求变成空操作 |
POST /listings | 活跃 listing 规则做就地更新;终态则拒绝(D21) |
PUT /listings/:id | id 明确;相同数据不改变任何状态 |
POST /listings/:id/submit | 状态机 —— 已经是 pending_review → 409 |
POST /listings/:id/withdraw | 状态机 |
测试模式:一个真实的沙盒,对租客完全不可见
Slice 1 的 BlockTestKeyWrites() 让测试密钥只读。这里把它移除,
改为给数据行打标记:is_test 在创建时取自 key_mode,
listing 则从它的 property 继承。
公开市场
隐藏publicScope加一行l.is_test = FALSE- 同时保护
PublicSearch、PublicGetBySlug、PublicAreas、PublicPropertyTypes - 集成测试会走遍每一条公开读取路径
管理员审核队列
隐藏- 真人不必花时间审批假房源
- 这正是测试模式提交要自动通过的原因(D32)
房东自己的列表
可见- 在面板中标注「test」徽章
- 否则这个沙盒对他们毫无用处
D32 · 测试模式下 pending_review 不是停留状态
任何落到 pending_review 的状态转移,都会在同一事务内继续走到
live —— 同时覆盖 Submit 和租金变更导致的降级。
有两扇门通向 pending_review,而 listingTransitions
在没有管理员的情况下不给任何一扇门提供出口。租金变更正是同步任务每晚
都要走的那扇门,所以只修 Submit 会让沙盒在第二步就走不下去。
安全护栏本来就存在:publicScope 过滤 is_test = FALSE,
所以一条 live 的测试 listing 在所有公开位置依然不可见。
已否决:为测试数据单开一个管理员队列页签(真人审批假房源); 增加一条仅供测试的审批路由(为一步演练破坏 Slice 1 已冻结的十条路由契约); 放着沙盒卡住不管(规格书会继续承诺一个并不存在的演练)。
清理(D28)
清理任务会硬删除 30 天内没有写入的测试 property —— 以
updated_at 而不是 created_at 计龄,
因为连续两个月每晚同步的沙盒是在天天使用的。
-
筛选候选
is_test、updated_at < now() - 30 天, 并且从该 property 的任何 listing 都触及不到 tenancy。 -
每一个都在自己的事务里删除
CASCADE 会清掉照片、产权证明、listing、ref 和标记。
-
失败就记日志、继续循环
一行坏数据只损失一行,而不是整次清理。
跨房东的重复标记
在 property 创建或认领时,如果指纹匹配到别人名下的 property, 就会提出一个标记。创建永远不会被阻止。测试数据行不会产生标记 —— 它们不是真实房源。
D25 · 发布拦截在提交时才判定
什么都不存。标记只记录这一对关系,由 Submit
检查这个 property 位于任意一侧的所有未关闭标记,
并读取当前已核验的产权证明。
在标记产生时冻结的布尔值,记录的只是那一天碰巧谁被核验过。
产权核验是管理员按自己节奏做的动作,而标记行是有方向的 ——
只看新来者那一侧的检查,会让两个主张者纯粹因为先后顺序而双双上线。
复用 Submit 本来就在调用的 ProofRepo.CountByProperty,
只多一次同样形状的调用。
已否决:保留存储的 blocks_publication 布尔值 ——
那样拦截取决于核验时机,而不是提交那一刻的事实。
| 情形 | 结果 |
|---|---|
| 两边都没有已核验的产权证明 | 都可以发布,标记仅供参考 |
| 只有对方有产权证明 | 我等待 —— 409 duplicate_under_review |
| 只有我有产权证明 | 对方等待 |
| 两边都有 | 都等待 —— 这是真正的纠纷,交给管理员 |
管理员把标记处理为 cleared(listing 可以继续)或
upheld(驳回或下架)。审核队列的每一行会新增:
origin_channel = 'api' 时显示 API 徽章,
任意一侧存在未关闭标记时显示重复告警。
数据结构
改动的字段
rental_properties 新增六个字段;rental_listings
新增同样的四个来源与测试字段。每一个都有默认值,所以现有数据行和调用方都不会受影响。
| 字段 | 类型 | 为什么 |
|---|---|---|
unit_number | TEXT NOT NULL DEFAULT '' | D18 —— 此前并不存在的指纹输入 |
address_fingerprint | TEXT 可空 | NULL 表示不够确定,永不参与匹配 |
is_test | BOOLEAN NOT NULL DEFAULT FALSE | D16 |
origin_channel | TEXT NOT NULL DEFAULT 'panel' | panel | api | cli(D34) |
origin_key_id、origin_key_name | TEXT | 由哪个密钥创建 |
新表 · rental_property_external_refs
CREATE TABLE rental_property_external_refs (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
property_id UUID NOT NULL REFERENCES rental_properties(id) ON DELETE CASCADE,
owner_user_id TEXT NOT NULL,
source TEXT NOT NULL,
external_ref TEXT NOT NULL,
is_test BOOLEAN NOT NULL DEFAULT FALSE,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE UNIQUE INDEX uq_property_refs
ON rental_property_external_refs (owner_user_id, source, external_ref, is_test);
CREATE INDEX idx_property_refs_property
ON rental_property_external_refs (property_id);
owner_user_id 是冗余存进来的,而不是靠 join:查询永远限定在调用方范围内,
而规则是「对这位房东唯一」,这是 join 无法强制的。is_test
进入唯一索引也是有意为之 —— 房东如果要先用测试模式跑一遍将来要正式发送的载荷,
就必须能在两种模式下重用同一个 external_ref。
新表 · rental_idempotency
CREATE TABLE rental_idempotency (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
api_key_id TEXT NOT NULL,
idempotency_key TEXT NOT NULL,
request_fingerprint TEXT NOT NULL, -- sha256(method|path|canonical(body))
resource_type TEXT NOT NULL,
resource_id TEXT, -- 提交前、结果已知时才填入
status_code INT NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE UNIQUE INDEX uq_idempotency ON rental_idempotency (api_key_id, idempotency_key);
CREATE INDEX idx_idempotency_sweep ON rental_idempotency (created_at);
数据行在 24 小时后清除。存结果 id 而不是响应体(D15)意味着重放永远不会返回过期内容,
也不会保留任何响应体。所有十条 v1 路由都要求 APIKeyAuthMiddleware,
所以 api_key_id 一定存在 —— 面板写入永远到不了这张表。
新表 · rental_duplicate_flags
CREATE TABLE rental_duplicate_flags (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
property_id UUID NOT NULL REFERENCES rental_properties(id) ON DELETE CASCADE,
matched_property_id UUID NOT NULL REFERENCES rental_properties(id) ON DELETE CASCADE,
fingerprint TEXT NOT NULL,
status TEXT NOT NULL DEFAULT 'open'
CHECK (status IN ('open','cleared','upheld')),
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
resolved_at TIMESTAMPTZ,
resolved_by_user_id TEXT,
resolution_note TEXT
);
CREATE INDEX idx_dup_flags_open
ON rental_duplicate_flags (property_id) WHERE status = 'open';
CREATE INDEX idx_dup_flags_open_matched
ON rental_duplicate_flags (matched_property_id) WHERE status = 'open';
匹配用的索引
-- 第 2 步,同一房东 —— 唯一索引,不只是查询索引(D33)
CREATE UNIQUE INDEX uq_props_fingerprint_owner
ON rental_properties (owner_user_id, is_test, address_fingerprint)
WHERE address_fingerprint IS NOT NULL AND deleted_at IS NULL;
-- 跨房东标记
CREATE INDEX idx_props_fingerprint_global
ON rental_properties (address_fingerprint)
WHERE address_fingerprint IS NOT NULL AND deleted_at IS NULL;
-- 低成本地把测试数据挡在公开路径之外
CREATE INDEX idx_listings_public
ON rental_listings (status) WHERE is_test = FALSE;
契约变更
property 的创建和更新接受三个新的可选字段。面板的调用一个都不发送,行为与今天完全一致。
{ "source": "propertyguru",
"external_ref": "PG-88213",
"unit_number": "12-3",
"address_line": "...", ... }
响应新增 unit_number、origin_channel、
is_test,以及作为 {source, external_ref} 列表的
external_refs。PUT /properties/:id
已经明确指定了 property,所以它永不匹配 ——
只把 ref 记在那个 id 上,别的什么都不做。
唯一一个需要大声说明的行为变更
| 情形 | 此前 | 现在 |
|---|---|---|
| POST,全新 | 201 | 201 |
| POST,ref 或指纹匹配上 | 201,一个重复项 | 200 |
| POST,重放的幂等密钥 | 201,一个重复项 | 200,带 Idempotent-Replay: true |
新的错误码
追加到 Slice 1 §8.2 已冻结的表中。全部为 409。
idempotency_conflict- 同一密钥,规范化请求体不同
duplicate_under_review- 存在未关闭的跨房东标记,且对方有已核验的产权证明
listing_not_reopenable- 该 property 上所有 listing 都已进入终态(D21)
ambiguous_match- 第 2 步找到 2 个以上候选(D27)
unit_number_required- 缺少单元号的高层住宅触发弱匹配(D29)
duplicate_address- 该指纹在这位房东名下已被占用(D33)
duplicate_external_ref- 该 ref 已绑定到这位房东的另一个 property
全部决策,以及各自否决了什么
延续 Slice 1 的编号。D17 已被 D25 取代。D20 被直接放弃 ——
uq_rental_listings_active_property 已经能标识一个 listing,
再加一个 listing ref 只是给同一样东西取第二个名字。
D12–D36 · 完整决策表
| # | 决策 | 选择 |
|---|---|---|
| D12 | 用已知 external_ref 重复 POST | 就地更新,返回 200 |
| D13 | 同一房东名下的指纹命中 | 总是认领 |
| D14 | ref 的存储方式 | 每个 source 一条 ref,放在旁表 |
| D15 | 幂等记录 | Postgres,存结果 id,重放时重新读取 |
| D16 | 测试数据行 | is_test 字段,在仓储层过滤 |
| D17 | 发布拦截 | 已被 D25 取代 |
| D18 | 指纹的输入 | 增加 unit_number;不确定时不生成指纹 |
| D19 | 规范化器 | 保守处理,加上马来西亚缩写 |
| D20 | listing 的外部 ref | 放弃。listing 的身份就是它的 property |
| D21 | 所有 listing 都为终态时的同步 upsert | 拒绝:409 listing_not_reopenable。面板不变 |
| D22 | 谁定义 source | 客户端声明的受校验标识符。无枚举,不由密钥推导 |
| D23 | 幂等的写入顺序 | 一个事务。唯一 INSERT 自己阻塞竞争者 |
| D24 | 匹配成功的写入可覆盖什么 | 合并:缺省的键保持字段不变 |
| D25 | 发布拦截 | 在 Submit 时实时判定,检查两侧 |
| D26 | 谁来跑这条流程 | 只有 API,通过 PropertyUseCase.Sync |
| D27 | 第 2 步找到两个以上候选 | 409 ambiguous_match,不做任何改动 |
| D28 | 测试数据清理 | 每个 property 一个事务,按 updated_at 计龄 |
| D29 | 两侧都缺单元号的高层住宅 | 弱匹配:409 unit_number_required,绝不认领 |
| D30 | 存量数据行 | 只为有地房产回填指纹 |
| D31 | 重放的哈希与过期结果 | 规范化 JSON;资源缺失时在同一事务内重新执行 |
| D32 | 测试模式与 pending_review | 不是停留状态,会继续走到 live |
| D33 | 每位房东一个地址 | 部分唯一索引;409 duplicate_address |
| D34 | 命名 | origin_source → origin_channel |
| D35 | 认领的审计 | 独立的 adopt 动作。不加表、不加界面 |
| D36 | Idempotency-Key | 可选。它买到的是干净的重放,不是防重复 |
已否决的方案 · 记录下来,免得有人再提一遍
| # | 否决的方案 | 原因 |
|---|---|---|
| D21 | 只允许从 withdrawn 重新创建 | 没有 listing 级 ref,API 无法区分陈旧重放与有意的重新出租 |
| D22 | 固定的 source 名称枚举 | 那是产品策略,仓库里并不存在 |
| D22 | 从 api_key_id 推导 source | 密钥轮换会让每一条 ref 失去归属,下次同步会把整批重建成重复项 |
| D23 | 写入成功之后再记录密钥 | 输掉竞态:两个请求都没查到,都去创建 |
| D23 | 独立的预留事务,带 in_progress、过期与接管 | 为一个普通回滚就能处理的场景,增加状态字段、过期规则和清理任务 |
| D24 | 坚持 PUT 整体替换、要求完整记录 | 漏掉一个字段就会静默丢数据,而多数数据源只发部分字段 |
| D25 | 保留存储的 blocks_publication 布尔值 | 拦截取决于标记产生那天碰巧谁被核验过 |
| D26 | 在 Create 上加布尔开关 | 一个函数两种行为;现有测试会守错路径 |
| D26 | 让面板也认领 | 人点「新增」却悄悄编辑了旧行。改由 D33 阻止手工重复 |
| D27 | 取最早的那个候选 | 在两行完全相同之间做猜测。D18 说猜测比漏掉更糟 |
| D28 | 用单条带 NOT EXISTS 的批量 DELETE | 意外的 RESTRICT 仍会中止整次清理,此后每晚失败且无声无息 |
| D29 | 放宽 D18,仅用楼盘 + 邮编为高层住宅生成指纹 | 重新打开 D18 本就要堵上的覆盖漏洞 |
| D30 | 通过解析 address_line 提取单元号来回填公寓 | 解析自由文本正是本设计禁止的模糊匹配 |
| D31 | 保留逐字节的请求体哈希 | 一次诚实的重试只要改变 JSON 键顺序就会收到 409 并中断同步 |
| D31 | 资源被清除时返回 410 Gone | 理论上正确,但对无人值守的同步毫无用处 —— 没人会去读它 |
| D32 | 给管理员单开一个测试数据队列页签 | 真人花时间审批假房源 |
| D32 | 增加一条仅供测试的审批路由 | 为一步演练破坏 Slice 1 已冻结的十条路由契约 |
| D32 | 放着沙盒卡住,只覆盖写入 | 规格书会继续承诺一个并不存在的演练 |
| D33 | 指纹仅供参考,由应用代码检查冲突 | 一次错误的 PUT 就会让房东的同步每晚卡住,直到有人去排查 |
| D34 | 保留 origin_source,只在文档里说明差别 | 同一个 JSON 对象里两个都叫「source」的字段会永远让人困惑 |
| D35 | 依赖 update 加 actor_type = api_key | 只能证明是密钥写的,不能证明发生了匹配 —— 而匹配才是会出错的那一步 |
| D36 | 要求每次写入都带 Idempotency-Key | 有了 D33 之后它买不到任何正确性,还破坏随手 curl 的用法 |
决策所依据的证据
2026-09-22 从仓库中读取。每一行都是上面某项决策依赖的事实 —— 其中有几条推翻了规格书的初稿。
| 事实 | 证据 | 被谁使用 |
|---|---|---|
活跃 listing 唯一索引只覆盖 draft、pending_review、live —— 有四个状态无人把关 | migrator_rental.go:180-182 | D21 |
只剩终态时,AllowsNewListing 允许人工重新上架 | listing.go:140 | D21 |
十条 v1 路由全部要求 APIKeyAuthMiddleware,因此 api_key_id 必定存在 | v1_routes.go:44-72 | D23 |
PropertyUseCase.Update 是整体替换,而且地址变更会强制重新审核 | property.go:159-183 | D24 |
Submit 已经在调用 CountByProperty,它只统计已核验且未删除的证明 | listing.go、ports.go:154-159 | D25 |
listingTransitions 没有从 pending_review 出去的 EventSubmit | listing.go | D32 |
| property 之下有两条 RESTRICT 边:付款记录与交接报告 | migrator_rental.go:619、:829 | D28 |
审计的 action 字段是普通 TEXT NOT NULL,没有 CHECK 约束 | migrator.go:2864 | D35 |
请求上下文带有 api_key_id、api_key_name、actor_type、key_mode —— 但没有 source 概念 | api_key_auth_middleware.go:152-156 | D22、D34 |
复用而非重建的基础设施
- 每个 property 一个活跃 listing
- 已有唯一部分索引强制执行,所以 listing 不需要 ref
publicScope(ctx)- 所有公开读取的唯一收口点 —— 一行代码就能过滤测试数据
ProofRepo.CountByProperty- 本来就统计已核验的证明;发布拦截没有引入新概念
- 跨房东数据读作 404
application.EnsureOwner的规则;模式隔离完全照搬- ADR-0002 审计触发器
- 即便测试数据被硬删除,审计行依然保留
任务
任务 4–8 是主干。任务 9–12b 是沙盒与重放路径。任务 13–15 是防欺诈。 任务 16 是本片唯一的前端工作。
全部 21 个任务及其验证方式
| # | 任务 | 验证 |
|---|---|---|
| 1 | 重新记录 rental 测试基线 | 写下数字 |
| 2 | 迁移:property 与 listing 字段,有地房产指纹回填(D30) | 迁移测试 |
| 3 | 迁移:refs、幂等、标记表,唯一指纹索引(D33) | 迁移测试 |
| 4 | PropertyInput、实体、仓储上的 unit_number | 单元测试 |
| 5 | 地址规范化器与 ComputeAddressFingerprint | 单元测试 |
| 6 | refs 仓储、source 校验(D22)与查询 | 单元测试 |
| 7 | 新建 PropertyUseCase.Sync 中的解析流程(D26、D27、D29)、匹配合并(D24)、adopt 审计动作(D35) | 单元测试 |
| 8 | 基于活跃 listing 规则的 listing upsert,终态拒绝(D21) | 单元测试 |
| 9 | 写入事务内的幂等认领(D23)与清理 | 单元、集成 |
| 9b | 测试数据清理,每个 property 一个事务(D28) | 集成 |
| 9c | origin_source → origin_channel 改名,去掉顶层 source(D34) | golden |
| 10 | is_test 传播与模式隔离 | 单元测试 |
| 11 | publicScope 与管理员队列过滤 | 集成 |
| 12 | 移除 BlockTestKeyWrites;测试模式下 pending_review 继续走到 live(D32) | 集成 |
| 12b | 规范化 JSON 指纹与过期重放的重新执行(D31) | 单元、集成 |
| 13 | 重复标记的创建(只存关系对,不存判定) | 单元测试 |
| 14 | Submit 两侧的实时拦截检查(D25) | 集成 |
| 15 | 管理员处理接口与队列徽章 | 集成 |
| 16 | 面板:单元号字段,并在缺少单元号的高层住宅上提示;test 徽章;重复告警 | 渲染测试 |
| 17 | rental-v1.yaml 与 golden 重新固定;把 Idempotency-Key 记为重放易用性(D36) | golden |
| 18 | 端到端双数据源同步 | 集成 |
测试预期
共 51 个测试,覆盖单元、集成、迁移与 golden。集成测试沿用现有配方:
pg-test 在 :55432,迁移从一个没有 .env
的目录执行,因为 backend/go/.env 指向的是 UAT。
| 测什么 | 类型 | 什么情况下失败 |
|---|---|---|
| 规范化器 | 单元、表驱动 | Jln 与 Jalan 产生不同哈希 |
| 没有单元号时指纹为 NULL | 单元 | 缺单元号的高层住宅拿到了哈希 |
| 解析顺序 | 单元 | 指纹跑在 ref 查询之前 |
| 同密钥并发请求(D23) | 集成 | 出现两个 property,或某个调用方收到 500 |
| 回滚的写入释放密钥(D23) | 集成 | 一次失败的写入永远占住同一个密钥 |
| 键顺序不改变指纹(D31) | 单元 | 重排序后的重试返回 409 |
| 资源被清除后的重放(D31) | 集成 | 一个成功的请求重放成 404 |
| 匹配合并保住面板数据(D24) | 集成 | 认领抹掉了配套设施、楼盘名或面积 |
| 面板创建永不认领(D26) | 单元 | 面板创建返回了已有 property 的 id |
| 两个候选则拒绝(D27) | 单元 | 挑了其中一个,或又建了第三行 |
| 弱匹配拒绝、绝不认领(D29) | 单元 | 缺单元号的公寓被认领或被重复创建 |
| 回填跳过冲突指纹(D33) | 迁移 | 唯一索引在真实数据上建不起来 |
| 终态 listing 不会被重建(D21) | 集成 | rented 的 property 被同步创建出新草稿 |
测试模式租金变更回到 live(D32) | 集成 | 沙盒在一次降级之后走不下去 |
| live 的测试 listing 依然不可见 | 集成 | 任何公开读取路径返回了它 |
| 拦截在被匹配一侧同样生效(D25) | 集成 | 新来者被拦住时,较早的 property 却发布了 |
| 清理清掉每一行从属数据(D28) | 集成 | 照片、证明、listing、ref 或标记比 property 活得更久 |
| 一个失败的 property 不会中止整次清理 | 集成 | 一行 RESTRICT 卡死整个任务 |
| 不带密钥时每条写入路由仍防重复(D36) | 集成 | 任何路由在盲目重试时建出第二行 |
| 公开 JSON 结构 | golden | 新字段缺失或被改名 |
风险与已知限制
| 风险 | 缓解措施 |
|---|---|
一次错误的 PUT 让房东的同步永久卡在歧义上 | 指纹在数据库层面对每位房东唯一(D33),因此这种歧义根本无法产生 |
| 指纹误配覆盖掉真实 property | 不确定时指纹为 NULL(D18);按 source 存 ref 让第 2 步很少触发;没有模糊匹配 |
| 第一次同步把存量房源整批复制一遍 | 有地房产已回填(D30);缺单元号的公寓以 409 unit_number_required 拒绝(D29) |
| 指纹漏配造成重复 | 按 source 存 ref 意味着重复同步根本走不到指纹这一步;跨房东的情况由管理员标记兜住 |
| 清理任务卡在一行坏数据上并永久停摆 | 每个 property 一个事务,失败记日志并跳过(D28) |
| 测试数据出现在公开市场 | publicScope 单一收口点;集成测试走遍每一条公开读取路径 |
| 发布拦截卡住了真实房东 | 只在对方拥有已核验证明时才生效,且在提交时重新读取(D25);管理员可以解除 |
| 两个写入方对地址意见不一致,每晚来回打架 | 本片不解决。匹配合并(D24)挡住幻影变更;真正的分歧需要字段归属规则 |
| 规范化器变更悄悄改变存量数据的分桶 | 指纹只在写入时重算;规范化器变更需要一次有意的回填,不在本片范围内 |
| POST 从 201 改成 200 会影响早期接入方 | v1 目前没有外部使用者;在任何人接入之前写进 rental-v1.yaml |
不在范围内
任何形式的照片与媒体同步、通过 API 上传产权证明、出站 webhook,以及 CLI。
这些属于 Slice 3 到 5。面向房东的认领历史界面同样被排除 ——
adopt 审计行(D35)已经足够事后追查,
而任务 16 已经是本片唯一的前端工作。