English

TypeSafe Jev — Rental Duplicate Property Check

Adds TypeSafe Jev as a judge for rental duplicate properties that the exact address fingerprint misses. Code narrows candidates by trimmed postcode and a shared word, Jev scores each cross-landlord pair, and a strong yes becomes a Duplicate Hint that an admin must confirm, choosing the suspect side, before it becomes a normal Duplicate Flag.

  • Predecessor Builds on the 2026-09-23 TypeSafe Jev listing check (shared client, J13 naming, J21 code contract)
  • ADRs 0066
  • New ADR 0067
  • Status Approved

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

摘要

两个房东可能发布同一套房子,而目前只有精确的地址指纹能发现这种情况。 本设计让 TypeSafe Jev 担任判断者:代码先按邮编和共同词语缩小候选范围, Jev 为每一对打分,高分的"是"会成为一条 Duplicate Hint(重复提示), 必须由管理员确认后才变成普通的 Duplicate Flag(重复标记)。Jev 自己从不标记或冻结任何东西。

  • 范围 backend/go、frontend/solidstart/apps/panel
  • 目标 发现被漏掉的跨房东重复房源(H1)
  • 产出 Duplicate Hint → 管理员确认 → Duplicate Flag
  • 开关 TYPESAFE_RENTAL_DUPLICATE_ENABLED + TYPESAFE_RENTAL_ENABLED + 密钥(默认关闭)
  • 队列 rental_properties.dup_check_due_at,每 5 分钟扫描一次,每次 20 条
  • 隐私 每次调用最多发送 11 个房东的地址 — ADR-0067
  • 管理界面 Panel /admin/rental/duplicates:Possible 和 Flags 两个标签页
  • 状态 Grill 评审已结束(2026-09-26),可以渲染

相关:Jev 房源检查(共享客户端、J13 命名、J21 代码契约);Jev 聊天消息检查; 房东 API 幂等同步(指纹 D18、发布冻结 D25、弱匹配 D29、开放风险 §13); ADR-0067(地址隐私取舍);CONTEXT.md — Duplicate Flag(被标记方)、Duplicate Hint。

为什么

地址指纹对清洗后的楼名或街名、单位号和邮编做哈希。 只有完全一致才会产生 Duplicate Flag。精确匹配会漏掉常见情况:

房东 A房东 B目前
Vista Komanwel, A-12-3Vista Komanwel Condo, A-12-3漏掉 — 名称不同
A-12-3A-12-03漏掉 — 单位号不同
单位号写在地址行里单位号在单位字段里漏掉
没有单位号的高楼任何从不检查 — 没有指纹(D18)

这是 TypeSafe 在租房业务中的第三个用途。它复用已合并的共享客户端 (internal/shared/infrastructure/typesafe/)及其调用日志。

交付内容

  • 每个有邮编的非测试房源都会被检查一次,寻找漏掉的跨房东重复;之后每次地址变更时再检查。已有房源通过一次性回填(backfill)检查。
  • 代码缩小候选范围。Jev 判断每一对:"是同一个房子吗?"。
  • 高分的"是"会成为一条 Duplicate Hint。它从不冻结任何东西。
  • 管理员获得一个 Duplicates 页面,有两个标签页:Possible(提示,"同一房子,提出标记" / "不是重复")和 Flags(未解决的 Duplicate Flag,"Cleared" / "Upheld" — 目前只能通过 API 处理)。
  • 确认后的提示变成普通的 Duplicate Flag。现有的冻结(D25)和处理流程原样接管。
端到端流程:入队、扫描、Jev 判断、管理员决定、现有标记流程。
端到端流程:入队、扫描、Jev 判断、管理员决定、现有标记流程。

决策

Jev 说"是"时会发生什么?

保存一条 Duplicate Hint。管理员确认后才变成 Duplicate Flag(H2、H8)。

标记会冻结发布。AI 的错误会挡住一个真实的房东。用单独的表,就不会有任何标记查询忘记跳过一个猜测。

已拒绝:Jev 直接提出标记;在 rental_duplicate_flags 上加 suggested 状态;把提示 JSON 存在房源行上。

新标记作用在哪一方?

管理员必须选出嫌疑房源。不预选任何一方。它保存为 property_id,即 "Upheld" 所作用的被标记方(H12)。

对 Jev 的配对来说,created_at 不是证据。回填的配对可能相隔多年;真正的房主可能是较新的一方,而 Upheld 会暂停他们。指纹标记保持"新来者"方向不变。

已拒绝:较新的房源成为被标记方;预选一方(默认值会推动管理员做出惩罚房东的选择)。

如何挡住过期的 Jev 答案?

按 id 升序锁住主体行和命中行,然后只有当两者仍然有效、非测试、房东不同、且 8 个被判断的地址字段未变时,才插入提示(H16、H17)。

只有地址变更才会让 Jev 的答案过期。在 READ COMMITTED(读已提交)下,普通的条件插入会在编辑事务仍未提交时读到上一次提交的行;行锁(row lock)让它等待编辑完成。

已拒绝:按候选的到期时间控制提示(排名不对称,配对会永久丢失);不加行锁的条件插入。

#决策选择
H1目标发现漏掉的跨房东重复。不是"减少错误的指纹标记"(很少见)
H2说"是"时保存 Duplicate Hint。管理员确认 → Duplicate Flag。Jev 自己从不标记或冻结
H3配对只比较不同房东。同一房东的重复不在范围内
H4候选搜索相同的去空格邮编 + 一个共同的关键词,按单位号词元排名,取前 10。纯 SQL + Go,不加新扩展。SQL 上限 500 行(H18)
H5覆盖范围所有写入路径上的创建和地址编辑(panel、API 创建、API 按引用匹配的更新、API 接管),加上对所有现有非测试房源的一次性回填。空邮编不检查(H19)
H6管理界面一个 "Duplicates" 页面,两个标签页:Possible(提示)和 Flags
H7开关新的 TYPESAFE_RENTAL_DUPLICATE_ENABLED;只有它和 TYPESAFE_RENTAL_ENABLED 都打开且设置了密钥时才运行
H8存储新表 rental_duplicate_hints,每对一行。不是在 rental_duplicate_flags 上加新状态
H9队列rental_properties.dup_check_due_at。回填只运行一次,在添加该列的同一个迁移 DO 块中,由事务级咨询锁(advisory lock)保护。之后或并发的启动从不重新入队已检查的行
H10隐私发送主体和最多 10 个候选的地址字段。不发送姓名、邮箱或 id。见 ADR-0067
H11标记来源新列 rental_duplicate_flags.source:fingerprint(默认)或 jev。fingerprint 列改为可空
H12标记方向确认时,管理员必须选出嫌疑房源。不预选任何一方。保存为 property_id,即 "Upheld" 所作用的一方。指纹标记保持"新来者"方向
H13驳回被驳回的配对不会再被询问
H14命名Duplicate Hint — 新的术语表条目。在界面或代码中绝不把提示叫作 "flag"。文字可以说确认提示会提出或关联一个 Duplicate Flag。property_id 是被标记方
H15配对已被标记显示最早的未解决标记及其被标记方。只有当 suspect_property_id 等于它的 property_id 时,确认才关联它,否则返回 409 pair_already_flagged。现有标记的方向从不改变。有多个时显示 open_flag_count
H16提示新鲜度只有在按 id 升序锁住主体行和命中行、并确认两者仍有效、非测试、房东不同、8 个被判断的地址字段未变之后,才保存提示。到期时间只用于控制是否清除主体
H17编辑顺序地址编辑在一个事务中,先更新房源行(获得行锁),再删除它的未决提示
H18候选上限ORDER BY updated_at DESC, id LIMIT 501。501 行 = 溢出:不调用 Jev,不清除,单独告警,24 小时后重试。启用前,SQL 计数超过 500 则保持开关关闭
H19空邮编去空格后为空的邮编不符合条件:清除到期时间,不调用 Jev。补上邮编会重新入队
H20已删除 vs 已决定对被地址编辑删除的提示进行确认或驳回 → 404;对已决定的提示 → 409 hint_already_decided
已拒绝的方案(18 个)
方案拒绝原因
让 Jev 审查现有指纹标记以减少误报误报很少;漏掉的重复才是真正的缺口
Jev 说"是"时直接提出 Duplicate Flag标记会冻结发布。AI 的错误会挡住真实的房东
同时匹配同一房东同一房东内从不产生 Duplicate Flag。需要自己的结果("合并?")和界面
pg_trgm 模糊文本搜索需要加扩展和索引。如果管理员反馈拼写错误被漏掉再考虑
pgvector 地址向量对单位号效果差;生产环境需要 Ollama embedder、回填和向量扫描;pgvector 在每个数据库中是可选的
只按相同邮编,不要求共同词语繁忙的邮编有超过 10 个候选;真正的匹配会被截掉
在 rental_duplicate_flags 上加 suggested 状态每个标记查询都要记得跳过它。忘记一次过滤,猜测就会冻结房东
把提示 JSON 存在房源行上一对存在两行上,必须保持同步
只复用 TYPESAFE_RENTAL_ENABLED回填会一次性把整个房源表入队,每个有候选的主体会发送最多 11 个房东的地址;需要单独的隐私许可
每月重新检查所有房源任何地址变更都已经会重新入队
较新的房源成为被标记方对 Jev 配对来说 created_at 不是证据。回填的配对可能相隔多年;真正的房主可能是较新的一方,而 Upheld 会暂停他们
在确认步骤中预选一方默认值会推动管理员做出惩罚房东的选择
复用现有未决标记,忽略管理员的选择Upheld 可能作用在管理员没有选的一方
按候选的到期时间控制提示候选自己的轮次结束时,到期时间也会变。排名不对称,所以配对会永久丢失
不加行锁的条件插入在 READ COMMITTED 下,它会在地址编辑仍未提交时读到上一次提交的行
用普通的 UPDATE ... WHERE dup_check_due_at IS NULL 回填迁移器每次启动都会重跑所有语句,所以每次部署都会重新入队所有已检查的房源,并重新发送有候选者的地址
把溢出的主体视为已检查超过 500 行之外的真正匹配会被静默丢掉
原始邮编相等比较所有空邮编会互相匹配;"57000 " 会漏掉 "57000"

临时假设

这些没有经过测量。如果某条被证明是错的,重新审视对应的决策。

范围

检查

范围内
  • 来自 panel 和 API 的正式模式房源
  • owner_user_id 不同的配对
  • 去空格后邮编相同的配对
  • 有邮编的房源
  • 还没有 Duplicate Flag 也没有提示的配对

不检查

范围外
  • 测试行(is_test)
  • 同一房东的配对
  • 邮编不同的配对(例如一方打错字)
  • 去空格后邮编为空的房源(保存时邮编是可选的)
  • 已被标记、已有提示或已驳回的配对

后端:配置

环境变量默认值效果
TYPESAFE_API_KEY空已有
TYPESAFE_RENTAL_ENABLEDfalse已有
TYPESAFE_RENTAL_DUPLICATE_ENABLEDfalse新增。只有三者都设置时重复扫描才运行

开关在每次扫描时读取,和房源检查一样。入队(§5.3)不读取开关。

SELECT max(n) FROM (
  SELECT s.id, count(c.id) AS n
  FROM rental_properties s
  JOIN rental_properties c
    ON trim(c.postcode) = trim(s.postcode) AND c.owner_user_id <> s.owner_user_id
   AND c.is_test = false AND c.deleted_at IS NULL
  WHERE s.is_test = false AND s.deleted_at IS NULL AND trim(s.postcode) <> ''
  GROUP BY s.id
) t;

后端:端口和适配器

// DuplicateJudge asks Jev whether each candidate is the same home as the subject.
type DuplicateJudge interface {
    Judge(ctx context.Context, in DuplicateJudgeInput) ([]float64, error) // p per candidate, same order
}

type DuplicateJudgeInput struct {
    SubjectID  string // Caller.RefID only; never sent
    Subject    JudgedAddress
    Candidates []JudgedAddress // 1..10
}

type JudgedAddress struct {
    PropertyType string // landed | condo | ...
    BuildingName string
    AddressLine  string
    UnitNumber   string
    Area, City, State, Postcode string
}
适配器
adapter/outbound/typesafe/duplicate_judge.go
Caller
Caller{App:"rental", Feature:"duplicate_check", RefID: SubjectID}
调用形式
一次调用,每个候选一个 Noul 问题(并行运行)
装配
在 module.go 中通过 WithDuplicateJudge 选项注入。judge 为 nil 时扫描什么都不做

后端:入队

在以下写入的同一事务中设置 dup_check_due_at = now():

事件入队
Panel Create是
Panel Update 且地址字段有变更是
API Sync 创建,或任何匹配的更新(按外部引用或接管)且地址字段有变更是
对测试行的任何写入从不

"地址字段"指 PropertyType、BuildingName、AddressLine、UnitNumber、 Area、City、State、Postcode。这比现有的 addressChanged(只看地址行)更宽,所以是一个新的辅助函数。

地址变更时,同一事务还会删除该房源的未决提示(配对中的任一方)。 如果配对仍然匹配,下一次扫描会创建新的提示。已确认和已驳回的提示保留。

编辑事务内的顺序(H17)

  1. UPDATE rental_properties — 新地址和 dup_check_due_at。这会获得行锁。
  2. DeleteOpenByProperty。

入队不看开关。它没有成本,开关打开后会处理积压。

后端:扫描 — DuplicateCheckSweepUseCase

在 scheduler.RunPeriodic 上每 5 分钟运行一次。每次运行时,除非密钥和两个开关都已设置且 judge 不为 nil,否则提前返回;然后加载 dup_check_due_at <= now() 最早的 20 个未删除、非测试的房源。逐个处理:

候选逐层缩小:相同去空格邮编、其他房东、SQL 上限 500 行;然后 Go 按楼型和共同词语过滤,并排除已有配对;然后按单位号词元取前 10;最后是 p 至少为 0.7 的命中。 相同邮编 SQL ≤ 500 行 楼型 + 共同词语 Go 过滤 单位号排名 前 10 Jev 命中 p ≥ 0.7
候选缩小:每一层都是外层的子集。只有最内层会成为提示。
  1. 0 · 空邮编

    trim(postcode) = '' → 不符合条件。清除到期时间(条件更新,同步骤 6.5)。不执行 SQL,不调用 Jev。之后补上邮编属于地址编辑,所以会重新入队(§5.3)。

  2. 1 · SQL — FindDuplicateCandidates(subject)

    其他 owner_user_id、trim(postcode) = trim(subject.postcode)、is_test = false、deleted_at IS NULL、ORDER BY updated_at DESC, id LIMIT 501。排序只让结果可重复,不让它完整:超过 500 行时,真正的匹配仍可能被截掉。

    溢出(501 行):不调用 Jev,也不清除到期时间。记录一条单独的 zap 告警 duplicate_check_candidate_overflow,带上主体 id 和邮编。把到期时间推到 now() + 24h(和步骤 7 相同的条件更新),这样溢出的主体不会一直停在队首饿死其他项。它保持在队列中,直到检索设计被修改。

  3. 2 · Go 过滤

    相同楼型:有地房(landed)与非有地房(指纹的规则)。至少共享一个关键词 — 词语来自双方的 Norm(building_name) 和 Norm(address_line)。去掉停用词:jalan、lorong、taman、bandar、kampung、persiaran、block、residensi、residence、condo、kondominium、apartment、pangsapuri,以及纯数字词元。去掉已有任何提示(任何状态)或任何 Duplicate Flag(任何状态)的配对。

  4. 3 · Go 按单位号词元重叠排名

    词元来自 unit_number 加上 address_line 中的数字/字母组。去掉前导零:A-12-03 → a、12、3。共享词元越多排名越高。并列时取 updated_at 最新的。保留前 10。

  5. 4 · 没有候选

    清除到期时间(条件更新,同步骤 6.5)。不调用 Jev。

  6. 5 · 判断

    使用 30 秒的 context.WithTimeout。

  7. 6 · 成功 — 一个短事务

    6.1 命中 = p ≥ 0.7 的候选。没有命中 → 跳到 6.5。

    6.2 按 id 升序锁住主体行和命中行。主体取 FOR UPDATE;命中取 FOR SHARE。固定顺序意味着两个副本不会死锁(deadlock)。

    6.3 主体:必须仍然有效(deleted_at IS NULL)、非测试,且 8 个被判断的地址字段必须等于 Jev 看到的值。否则不插入任何提示并保持在队列中(它的编辑已经重新入队)。转到 6.5。

    6.4 每个命中:必须有效、非测试、owner_user_id 不同,且 8 个被判断的地址字段必须等于 Jev 看到的值。否则跳过它(它的编辑已重新入队)。插入其余的(ON CONFLICT (property_a_id, property_b_id) DO NOTHING)。

    6.5 UPDATE ... SET dup_check_due_at = NULL WHERE id = ? AND dup_check_due_at = <value read in step 2>。

  8. 7 · 出错

    记录 zap 告警,然后在相同条件下 SET dup_check_due_at = now() + 1h。

编辑与扫描的竞争:编辑先拿到行锁,所以扫描会等待,并看到新地址。
编辑与扫描的竞争:编辑先拿到行锁,所以扫描会等待,并看到新地址。

后端:数据表

rental_properties

-- Column add and backfill together: the backfill runs once, on the boot that adds
-- the column, never again.
DO $$
BEGIN
  -- The migrator has no lock, so two replicas may boot together. Without this lock
  -- both could pass the check below before either commits, and both would backfill.
  -- The loser waits here until the winner commits, then sees the column and skips.
  PERFORM pg_advisory_xact_lock(hashtext('rental_properties.dup_check_due_at_backfill'));
  IF NOT EXISTS (
    SELECT 1 FROM information_schema.columns
    WHERE table_schema = current_schema()
      AND table_name = 'rental_properties' AND column_name = 'dup_check_due_at'
  ) THEN
    ALTER TABLE rental_properties ADD COLUMN dup_check_due_at TIMESTAMPTZ;
    UPDATE rental_properties SET dup_check_due_at = now()
      WHERE is_test = false AND deleted_at IS NULL;
  END IF;
END $$;
CREATE INDEX IF NOT EXISTS idx_props_dup_check_due
  ON rental_properties (dup_check_due_at)
  WHERE dup_check_due_at IS NOT NULL AND deleted_at IS NULL AND is_test = false;

rental_duplicate_hints(新表)

CREATE TABLE IF NOT EXISTS rental_duplicate_hints (
  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  property_a_id UUID NOT NULL REFERENCES rental_properties(id) ON DELETE CASCADE,
  property_b_id UUID NOT NULL REFERENCES rental_properties(id) ON DELETE CASCADE,
  p             DOUBLE PRECISION NOT NULL,
  status        TEXT NOT NULL DEFAULT 'open'
                CHECK (status IN ('open','confirmed','dismissed')),
  flag_id       UUID REFERENCES rental_duplicate_flags(id) ON DELETE SET NULL,
  decided_by    TEXT,
  decided_at    TIMESTAMPTZ,
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
  CHECK (property_a_id < property_b_id)
);
CREATE UNIQUE INDEX IF NOT EXISTS uq_dup_hints_pair
  ON rental_duplicate_hints (property_a_id, property_b_id);
CREATE INDEX IF NOT EXISTS idx_dup_hints_open
  ON rental_duplicate_hints (created_at) WHERE status = 'open';

配对按排序顺序存储(a < b),所以无论从哪一方判断,一对只有一行。

rental_duplicate_flags

ALTER TABLE rental_duplicate_flags
  ADD COLUMN IF NOT EXISTS source TEXT NOT NULL DEFAULT 'fingerprint'
    CHECK (source IN ('fingerprint','jev'));
ALTER TABLE rental_duplicate_flags ALTER COLUMN fingerprint DROP NOT NULL;

现有标记代码继续工作:它从不读取 source,并且总是写入指纹。 entity.DuplicateFlag.Fingerprint 改为 *string。 以上全部放在 migrator_rental.go 中一个新的 Create... 函数里,由 RunMigrations 调用。

仓储方法

DuplicateHintRepository:

方法说明
SaveHints(ctx, subjectID string, hits []HintHit)对每对排序;ON CONFLICT DO NOTHING
DeleteOpenByProperty(ctx, propertyID)地址变更时使用(§5.3)
ExistingPairs(ctx, subjectID, candidateIDs)用于 §5.4 过滤
List(ctx, status, limit, offset)管理员列表
Confirm(ctx, id, adminID, flagID) (bool, error)WHERE status='open'
Dismiss(ctx, id, adminID) (bool, error)WHERE status='open'

PropertyRepository 新增:

方法说明
ListDupCheckDue(ctx, limit)§5.4 步骤 2;dup_check_due_at 最早的优先
FindDuplicateCandidates(ctx, subject, limit)步骤 3.1;去空格邮编,ORDER BY updated_at DESC, id
LockForDuplicateHints(ctx, subjectID, hitIDs)步骤 6.2;id 升序,主体 FOR UPDATE,命中 FOR SHARE;返回当前行供 6.3 / 6.4 检查。必须在步骤 6 的事务内运行
SetDupCheckDue(ctx, id, readDue, next) (bool, error)步骤 3.0、3.1 溢出、3.4、6.5 和 7;WHERE dup_check_due_at = readDue;next 为 nil 时清除

地址编辑的写入按顺序使用 UPDATE rental_properties 然后 DeleteOpenByProperty(H17、§5.3)。

DuplicateFlagRepository 新增 List(ctx, status, limit, offset) 和 FindOpenByPair(ctx, a, b) (oldest *DuplicateFlag, openCount int, err error)。 它匹配任一方向,并选出最早的未决标记(先按 created_at,再按 id),所以选择是稳定的。

后端:确认和驳回

确认,在一个事务中完成。suspect_property_id 必须是提示中两个房源之一,否则返回 400 invalid_suspect_property;这在步骤 1 之前检查。

  1. 把提示标为已确认

    Confirm(... WHERE status='open')。没有行被修改 → 重新读取提示:不存在 → 404(地址编辑删除了它);已决定 → 409 hint_already_decided。

  2. 检查未决标记 — FindOpenByPair

    存在未决标记且其 property_id 等于 suspect_property_id → 关联它的 id。否则 → 409 pair_already_flagged,不写入任何东西。这覆盖了页面加载后才出现的标记,或过期的选择。现有标记的方向从不改变。

  3. 否则创建标记

    source='jev'、fingerprint=NULL、状态 open、property_id = 请求中的 suspect_property_id、matched_property_id = 另一方。

  4. 记录决定

    在提示上保存 flag_id、decided_by、decided_at。

之后现有的 D25 冻结和 ResolveDuplicateFlag 原样适用。"Upheld" 只作用于 property_id(review.go ResolveDuplicateFlag)。

驳回:同样的 WHERE status='open' 保护和同样的 404 / 409 区分,然后保存 decided_by、decided_at。

边界情况

情况结果
提示未决时地址变更未决提示被删除;房源重新入队(§5.3)
驳回后地址变更配对保持已驳回(H13)。可接受:很少见,且精确指纹检查仍在运行
一个房源被删除提示被 ON DELETE CASCADE 删除
对已有未决提示的配对产生了指纹标记提示保持未决。Panel 显示现有标记;确认会关联它(§5.6 步骤 2)。发生在 API 接管时和 Jev 调用期间
配对有多个未决标记关联最早的。open_flag_count > 1 提示管理员在 Flags 标签页检查其余的
扫描中途关闭开关当前房源处理完;下一次运行提前返回。到期时间保留
Jev 返回的 p 值少于候选数视为错误(§5.4 步骤 7)
房源改到另一个邮编因地址变更入队;旧的未决提示被删除
Jev 调用期间主体地址被编辑编辑等待行锁,或扫描看到新地址。不保存提示;主体保持在队列中(H16)
Jev 调用期间命中方地址被编辑跳过该命中;它的编辑已重新入队(H16)
命中方到期时间变了,地址没变保存提示(H16)
两个副本锁住重叠的配对id 升序加锁;不会死锁(H16)
管理员确认时提示被地址编辑删除404;panel 重新获取(H20)
空邮编不检查;清除到期时间(H19)
超过 500 个候选溢出告警;保持在队列中,24 小时后重试(H18)

问题和阈值

发送给 Jev 的状态

{
  "subject": { "property_type": "condo", "building_name": "Vista Komanwel Condo",
               "address_line": "Jalan 1/62A, Bukit Komanwel", "unit_number": "A-12-03",
               "area": "Bukit Jalil", "city": "Kuala Lumpur", "state": "WP Kuala Lumpur",
               "postcode": "57000" },
  "candidates": [
    { "property_type": "condo", "building_name": "Vista Komanwel", "...": "..." }
  ]
}

不含 id、房东姓名或邮箱。候选按位置引用。

问题(Noul,每个候选一个)

"subject 和 candidates[i] 描述的是同一个可出租的房子吗 — 同一栋楼里的同一个单位,或同一栋有地房?"
应答"是"的情况
  • A-12-03 对 A-12-3
  • "Vista Komanwel" 对 "Vista Komanwel Condo"
  • 单位号在单位字段里 对 在地址行里
  • Jln 对 Jalan,马来语对英语的楼名用词
陷阱情况(应答"否")
  • 同一栋楼,不同单位
  • 同一条街,不同门牌号
  • "Taman Desa" 对 "Taman Desa Jaya"
  • 单位号相同,但同一邮编下的不同楼

阈值和校准

阈值
0.7,放在适配器旁的 Go 常量。校准会在打开开关之前设定真实值
评估工具
cmd/eval-duplicate-check,参照 cmd/eval-listing-check
数据集
约 30 对合成数据,覆盖"是"和陷阱情况,包含英语和马来语地址风格
真实地址
需要显式的启用标志,并以 ADR-0067 为前提

API

所有端点都在租房管理组(admin、superadmin)中。

端点说明
GET /api/rental/admin/duplicate-hints?status=open|all最新的在前,pagination.Wrap
POST /api/rental/admin/duplicate-hints/:id/confirm请求体 {suspect_property_id}(必填)。200 {flag_id};400 invalid_suspect_property;404;409 hint_already_decided;409 pair_already_flagged
POST /api/rental/admin/duplicate-hints/:id/dismiss204;404;409 hint_already_decided
GET /api/rental/admin/duplicate-flags?status=open|all新列表。最新的在前,分页
POST /api/rental/admin/duplicate-flags/:id/resolve已有,不变

行结构(提示和标记共用):

{
  "id": "...",
  "p": 0.94,                   // hints only
  "source": "jev",             // flags only
  "status": "open",
  "created_at": "...",
  "a": { "property": { ...address fields, "id", "created_at" },
         "owner": { "user_id", "name", "email" },
         "listing_status": "live",     // null when no active listing
         "has_verified_proof": true },
  "b": { ...same },
  "open_flag": { "id": "...", "property_id": "...", "open_flag_count": 2 }  // hints only; null when none
}
  • open_flag 是该配对最早的未决标记(FindOpenByPair)。
  • 对标记来说,a 是 property_id,b 是 matched_property_id。
  • has_verified_proof 使用 CountByProperty,与 D25 相同的检查,让管理员看到是否会冻结。

Panel — /admin/rental/duplicates

文件:apps/panel/src/routes/admin/rental/duplicates/index.tsx。

部分细节
侧边栏在 apps/panel/src/app.tsx 中 Listings 旁边加 "Duplicates",显示未决提示 + 未决标记的数量
标签页 "Possible"未决提示的表格。点击一行打开侧边面板:两个房源并排显示,高亮不同字段,显示房东、房源状态、证明。按钮:Same home, raise flag、Not a duplicate。"Same home" 打开确认步骤:管理员必须选择哪个房源是嫌疑方。不预选任何一方,选好之前提交按钮保持禁用。文字写着 "If this flag is later Upheld, this property's listings are suspended or rejected"
标签页 "Flags"未决标记的表格,带 source 徽章("Exact match" / "Jev")。按钮:Cleared、Upheld,可选备注
配对已被标记提示有 open_flag 时,确认步骤不显示选择器。它写出被标记方并说明 "Upheld will suspend or reject this property's listings"。按钮是 Link to existing flag,发送那个 property_id。如果 open_flag_count > 1,显示 "This pair has N open flags" 并链接到 Flags 标签页
确认 / 驳回返回 404提示 "This pair changed and will be checked again",然后重新获取
409hint_already_decided:提示 "Another admin already decided this"。pair_already_flagged:提示 "This pair was flagged meanwhile"。两者都重新获取
用词Possible 标签页从不把提示叫作标记(H14)。可以写 "Confirming raises or links a Duplicate Flag"。"Flagged side(被标记方)"指 Upheld 作用的一方
i18n与聊天检查结果页面相同的规则(聊天规格 §8.2)

同一个房子 — 哪个房源是嫌疑方?

确认会提出或关联一个 Duplicate Flag。Jev p = 0.94。

Vista Komanwel Condo, A-12-03, 57000
房东 A · 房源已上线 · 已验证证明
Vista Komanwel, A-12-3, 57000
房东 B · 无活跃房源 · 无证明
如果这个标记之后被 Upheld,这个房源的上架信息会被暂停或拒绝。
取消 提出标记
Panel 确认步骤示意图 — 不预选任何一方;管理员选出嫌疑方之前提交按钮禁用。

房东应用不变。房东永远看不到提示。

测试

范围测试
候选过滤邮编去空格比较("57000 " 匹配 "57000");空邮编候选从不匹配;停用词;忽略纯数字词元;有地房与高楼;去掉已有提示/标记的配对
单位号排名前导零;address_line 中的单位号;按 updated_at 打破并列;前 10
扫描假 judge。p ≥ 0.7 保存提示,低于则不保存。没有候选 → 不调用,清除到期时间。出错 → +1h。去空格后邮编为空 → 不执行 SQL,不调用,清除到期时间。调用中途到期时间变了 → 保持在队列中。501 个候选 → 不调用,记录告警,到期时间推后 +24h,不清除。调用中途主体地址变了 → 不保存提示,保持在队列中。命中方地址变了 → 跳过该命中,保存其他。命中方到期时间变了但地址相同 → 保存提示。命中方已删除、变成测试或同一房东 → 跳过。编辑事务被扫描锁阻塞后删除新提示(pg-test,两个连接)。开关关闭 → 不做任何事。p 数量错误 → 走错误路径
入队在 panel 更新、API 按引用匹配的更新和 API 接管中,每个地址字段变更都会入队;非地址编辑不会;给空邮编补上邮编会入队;测试行从不入队;地址变更只删除未决提示
配对顺序从任一方产生的提示都落在同一行
确认 / 驳回第二次操作 409;提示被地址编辑删除 → 404;只有 property_id 匹配时才复用现有标记,否则 409 pair_already_flagged 且不写入;多个未决标记时选最早的;suspect_property_id 成为 property_id,缺失或外来 id → 400,较旧的一方也可以是嫌疑方;确认后,Submit 按 D25 返回 duplicate_under_review
迁移回填只为正式模式、未删除的行设置到期时间;第二次运行迁移不会重新入队已检查的行;并发启动(pg-test,两个连接同时运行 DO 块)→ 列只添加一次,回填 UPDATE 只运行一次,没有错误;旧标记得到 source='fingerprint'
处理器需要管理员角色;状态过滤;分页
适配器构建不含 id 的状态;按位置映射 p;Caller 字段
Panel(vitest)两个标签页都能渲染;按钮调用正确的端点;409 提示;选出嫌疑方之前确认按钮禁用,不预选任何一方

租房 Go 测试使用 -p 1 在 pg-test 上运行。

隐私 — ADR-0067

打开 TYPESAFE_RENTAL_DUPLICATE_ENABLED 的前提条件:

  1. Gremlin 确认面向房东的披露内容涵盖:从未提交的房源地址会被发送给 TypeSafe 做重复检查。
  2. 校准默认只使用合成配对;真实地址需要显式的启用标志,并以同一确认为前提。
  3. 启用前的候选数量检查返回 500 或更少(不是隐私门槛 — 它防止在任何邮编溢出上限时启动回填)。

不在范围内

事项原因
同一房东的重复H3
pg_trgm 或 pgvector 搜索H4;有漏报反馈时再考虑
不同邮编H4
告诉房东有提示仅限管理员
Jev 自动标记或自动冻结H2
撤销驳回很少见;有需要时再加
管理员查看审计日志同 ADR-0066
重复的 API 接管每次都插入新的指纹标记已有 bug,单独跟踪。本设计只读取最早的未决标记