English

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

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

这一片为何存在

Slice 1 让房东的 API key 成为一个有效身份。但当时没有任何机制阻止同步任务把同一间房写入两次, 所以每晚跑一次就会让市场上堆满同一个房源的副本。Slice 2 让每一次写入都可重复执行: 同一个同步任务跑一百次,最后只留下一个 property 和一个 listing。

  • 范围 backend/go 加上面板的单元号字段
  • 承接自 Slice 1 — Foundation,已合并于 8942b456
  • 形态 3 张新表、6 个新字段、7 个新错误码
  • 体量 25 项决策、21 个任务、51 个测试

匹配流程

一个入口负责判断传入的 property 是新的还是已知的。每一步按顺序尝试,第一个命中的胜出。

property 写入的解析顺序。ref 查询和指纹查询都受到双重限定 —— 相同的 owner_user_id 与相同的 is_test —— 两个限定都不可省略。
property 写入的解析顺序。ref 查询和指纹查询都受到双重限定 —— 相同的 owner_user_id 与相同的 is_test —— 两个限定都不可省略。
步骤尝试结果审计动作
0此前见过的 Idempotency-Key重放,结束—
1refs 表中的 source + external_ref200,该 propertyupdate
2可计算时的地址指纹200,认领(adopt)adopt
3都没匹配上201,新建 propertycreate

D26 · 谁来跑这条流程?

只有 API,通过新的 PropertyUseCase.Sync。面板永远新建一行 —— 但仍然会计算并保存指纹。

认领的含义是「这是同一间房的另一个名字」,只有事后有 ref 能解释它时才成立。 人点击新增房源的意思是「造一个新的」。如果面板也跑第 2 步, 它会找到房东已有的房源并返回旧 id 和 200 —— 房东以为自己创建了房源, 实际却是编辑了旧的,而界面上没有任何提示。

已否决:在 Create 上加布尔开关(一个函数两种行为,现有测试会守错路径); 让面板也认领(改由 D33 阻止手工重复)。

D24 · 匹配成功的写入可以覆盖什么?

匹配成功的写入只做局部更新 —— 请求里没有的字段保持不变。 只有新建 property 才做整体替换。面板的 PUT 不受影响。

PropertyUseCase.Update 是 PUT 语义:缺省的可选字段会被重置为零值 (property.go:159)。用在匹配成功的写入上,就是悄悄删掉房东自己的成果。

已否决:坚持 PUT 整体替换、要求数据源发送完整记录 —— 那样只要漏掉一个字段就会造成静默数据丢失,而多数数据源只发送部分字段。

房东在面板建好的房源带有配套设施、楼盘名称和面积。整体替换会在同步认领时抹掉三者;局部合并只更新同步发来的字段,其余保留。 整体替换 地址 · 已发送 单元号 · 已发送 配套设施 · 被抹掉 楼盘名 · 被抹掉 面积 · 归零 丢失 3 个字段 局部合并 地址 · 已发送 单元号 · 已发送 配套设施 · 保留 楼盘名 · 保留 面积 · 保留 没有丢失
D24 · 同步认领了房东手工建立的房源,只发送了类型、地址、邮编和单元号。 左边是今天的 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_address unique (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。

D23 · 竞争的那个请求会在唯一索引上阻塞,直到第一个事务结束。 对方提交则它执行重放;对方回滚则它自己的插入成功,由它持有认领。
D23 · 竞争的那个请求会在唯一索引上阻塞,直到第一个事务结束。 对方提交则它执行重放;对方回滚则它自己的插入成功,由它持有认领。
  1. 先认领、再干活 —— 在同一个 BEGIN 内

    先 INSERT INTO rental_idempotency (…),此时 resource_id 仍为 NULL;接着跑解析流程;最后在 COMMIT 之前 UPDATE 填入 resource_id 和 status_code。

  2. 指纹不同即为冲突

    同一密钥、不同的规范化请求体 → 409 idempotency_conflict, 在唯一约束冲突后重新读取时判定。

  3. 请求体按规范化 JSON 哈希,而非逐字节

    解码成 any、重新编码、再哈希。encoding/json 本来就会给 map 的键排序,所以规范化只要三行代码。否则一次诚实的重试 只因为 JSON 键顺序变了就会收到 409 并中断同步。

  4. 资源已被清除时重新执行,而不是返回 404

    SELECT … FOR UPDATE、删掉过期行、重新插入一次新的认领并跑流程 —— 全部在同一个事务内,因此并发的重放仍然保持串行。

十条路由各自靠什么拦住盲目重试
写操作拦截它的机制
POST /propertiesref(第 1 步)、指纹(第 2 步),否则唯一索引(D33)→ 409 duplicate_address,或 409 unit_number_required(D29)
PUT /properties/:idid 明确;局部合并(D24)让重复请求变成空操作
POST /listings活跃 listing 规则做就地更新;终态则拒绝(D21)
PUT /listings/:idid 明确;相同数据不改变任何状态
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 已冻结的十条路由契约); 放着沙盒卡住不管(规格书会继续承诺一个并不存在的演练)。

listing 的状态。测试模式下 approve 这条边自动触发(D32); 正式模式下必须由管理员来走。终态会拒绝 API 的重新上架(D21), 但仍允许人工在面板中创建新的 listing。
listing 的状态。测试模式下 approve 这条边自动触发(D32); 正式模式下必须由管理员来走。终态会拒绝 API 的重新上架(D21), 但仍允许人工在面板中创建新的 listing。

清理(D28)

清理任务会硬删除 30 天内没有写入的测试 property —— 以 updated_at 而不是 created_at 计龄, 因为连续两个月每晚同步的沙盒是在天天使用的。

property 之下的删除链。底部两条 RESTRICT 边会抛出错误, 在单条批量语句里就会中止整次清理 —— 当晚如此,之后每晚都如此,而且毫无声响。
property 之下的删除链。底部两条 RESTRICT 边会抛出错误, 在单条批量语句里就会中止整次清理 —— 当晚如此,之后每晚都如此,而且毫无声响。
  1. 筛选候选

    is_test、updated_at < now() - 30 天, 并且从该 property 的任何 listing 都触及不到 tenancy。

  2. 每一个都在自己的事务里删除

    CASCADE 会清掉照片、产权证明、listing、ref 和标记。

  3. 失败就记日志、继续循环

    一行坏数据只损失一行,而不是整次清理。

跨房东的重复标记

在 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_numberTEXT NOT NULL DEFAULT ''D18 —— 此前并不存在的指纹输入
address_fingerprintTEXT 可空NULL 表示不够确定,永不参与匹配
is_testBOOLEAN NOT NULL DEFAULT FALSED16
origin_channelTEXT NOT NULL DEFAULT 'panel'panel | api | cli(D34)
origin_key_id、origin_key_nameTEXT由哪个密钥创建

新表 · 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,全新201201
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同一房东名下的指纹命中总是认领
D14ref 的存储方式每个 source 一条 ref,放在旁表
D15幂等记录Postgres,存结果 id,重放时重新读取
D16测试数据行is_test 字段,在仓储层过滤
D17发布拦截已被 D25 取代
D18指纹的输入增加 unit_number;不确定时不生成指纹
D19规范化器保守处理,加上马来西亚缩写
D20listing 的外部 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 动作。不加表、不加界面
D36Idempotency-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-182D21
只剩终态时,AllowsNewListing 允许人工重新上架listing.go:140D21
十条 v1 路由全部要求 APIKeyAuthMiddleware,因此 api_key_id 必定存在v1_routes.go:44-72D23
PropertyUseCase.Update 是整体替换,而且地址变更会强制重新审核property.go:159-183D24
Submit 已经在调用 CountByProperty,它只统计已核验且未删除的证明listing.go、ports.go:154-159D25
listingTransitions 没有从 pending_review 出去的 EventSubmitlisting.goD32
property 之下有两条 RESTRICT 边:付款记录与交接报告migrator_rental.go:619、:829D28
审计的 action 字段是普通 TEXT NOT NULL,没有 CHECK 约束migrator.go:2864D35
请求上下文带有 api_key_id、api_key_name、actor_type、key_mode —— 但没有 source 概念api_key_auth_middleware.go:152-156D22、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)迁移测试
4PropertyInput、实体、仓储上的 unit_number单元测试
5地址规范化器与 ComputeAddressFingerprint单元测试
6refs 仓储、source 校验(D22)与查询单元测试
7新建 PropertyUseCase.Sync 中的解析流程(D26、D27、D29)、匹配合并(D24)、adopt 审计动作(D35)单元测试
8基于活跃 listing 规则的 listing upsert,终态拒绝(D21)单元测试
9写入事务内的幂等认领(D23)与清理单元、集成
9b测试数据清理,每个 property 一个事务(D28)集成
9corigin_source → origin_channel 改名,去掉顶层 source(D34)golden
10is_test 传播与模式隔离单元测试
11publicScope 与管理员队列过滤集成
12移除 BlockTestKeyWrites;测试模式下 pending_review 继续走到 live(D32)集成
12b规范化 JSON 指纹与过期重放的重新执行(D31)单元、集成
13重复标记的创建(只存关系对,不存判定)单元测试
14Submit 两侧的实时拦截检查(D25)集成
15管理员处理接口与队列徽章集成
16面板:单元号字段,并在缺少单元号的高层住宅上提示;test 徽章;重复告警渲染测试
17rental-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 已经是本片唯一的前端工作。