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.
摘要
两个房东可能发布同一套房子,而目前只有精确的地址指纹能发现这种情况。 本设计让 TypeSafe Jev 担任判断者:代码先按邮编和共同词语缩小候选范围, Jev 为每一对打分,高分的"是"会成为一条 Duplicate Hint(重复提示), 必须由管理员确认后才变成普通的 Duplicate Flag(重复标记)。Jev 自己从不标记或冻结任何东西。
相关: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-3 | Vista Komanwel Condo, A-12-3 | 漏掉 — 名称不同 |
| A-12-3 | A-12-03 | 漏掉 — 单位号不同 |
| 单位号写在地址行里 | 单位号在单位字段里 | 漏掉 |
| 没有单位号的高楼 | 任何 | 从不检查 — 没有指纹(D18) |
这是 TypeSafe 在租房业务中的第三个用途。它复用已合并的共享客户端
(internal/shared/infrastructure/typesafe/)及其调用日志。
交付内容
- 每个有邮编的非测试房源都会被检查一次,寻找漏掉的跨房东重复;之后每次地址变更时再检查。已有房源通过一次性回填(backfill)检查。
- 代码缩小候选范围。Jev 判断每一对:"是同一个房子吗?"。
- 高分的"是"会成为一条 Duplicate Hint。它从不冻结任何东西。
- 管理员获得一个 Duplicates 页面,有两个标签页:Possible(提示,"同一房子,提出标记" / "不是重复")和 Flags(未解决的 Duplicate Flag,"Cleared" / "Upheld" — 目前只能通过 API 处理)。
- 确认后的提示变成普通的 Duplicate Flag。现有的冻结(D25)和处理流程原样接管。
决策
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_ENABLED | false | 已有 |
TYPESAFE_RENTAL_DUPLICATE_ENABLED | false | 新增。只有三者都设置时重复扫描才运行 |
开关在每次扫描时读取,和房源检查一样。入队(§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)
UPDATE rental_properties— 新地址和dup_check_due_at。这会获得行锁。DeleteOpenByProperty。
入队不看开关。它没有成本,开关打开后会处理积压。
后端:扫描 — DuplicateCheckSweepUseCase
在 scheduler.RunPeriodic 上每 5 分钟运行一次。每次运行时,除非密钥和两个开关都已设置且 judge 不为 nil,否则提前返回;然后加载 dup_check_due_at <= now() 最早的 20 个未删除、非测试的房源。逐个处理:
-
0 · 空邮编
trim(postcode) = ''→ 不符合条件。清除到期时间(条件更新,同步骤 6.5)。不执行 SQL,不调用 Jev。之后补上邮编属于地址编辑,所以会重新入队(§5.3)。 -
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 相同的条件更新),这样溢出的主体不会一直停在队首饿死其他项。它保持在队列中,直到检索设计被修改。 -
2 · Go 过滤
相同楼型:有地房(landed)与非有地房(指纹的规则)。至少共享一个关键词 — 词语来自双方的
Norm(building_name)和Norm(address_line)。去掉停用词:jalan、lorong、taman、bandar、kampung、persiaran、block、residensi、residence、condo、kondominium、apartment、pangsapuri,以及纯数字词元。去掉已有任何提示(任何状态)或任何 Duplicate Flag(任何状态)的配对。 -
3 · Go 按单位号词元重叠排名
词元来自
unit_number加上address_line中的数字/字母组。去掉前导零:A-12-03→a、12、3。共享词元越多排名越高。并列时取updated_at最新的。保留前 10。 -
4 · 没有候选
清除到期时间(条件更新,同步骤 6.5)。不调用 Jev。
-
5 · 判断
使用 30 秒的
context.WithTimeout。 -
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>。 -
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 之前检查。
-
把提示标为已确认
Confirm(... WHERE status='open')。没有行被修改 → 重新读取提示:不存在 →404(地址编辑删除了它);已决定 →409 hint_already_decided。 -
检查未决标记 —
FindOpenByPair存在未决标记且其
property_id等于suspect_property_id→ 关联它的 id。否则 →409 pair_already_flagged,不写入任何东西。这覆盖了页面加载后才出现的标记,或过期的选择。现有标记的方向从不改变。 -
否则创建标记
source='jev'、fingerprint=NULL、状态open、property_id= 请求中的suspect_property_id、matched_property_id= 另一方。 -
记录决定
在提示上保存
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/dismiss | 204;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",然后重新获取 |
| 409 | hint_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。
房东应用不变。房东永远看不到提示。
测试
| 范围 | 测试 |
|---|---|
| 候选过滤 | 邮编去空格比较("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 的前提条件:
- Gremlin 确认面向房东的披露内容涵盖:从未提交的房源地址会被发送给 TypeSafe 做重复检查。
- 校准默认只使用合成配对;真实地址需要显式的启用标志,并以同一确认为前提。
- 启用前的候选数量检查返回 500 或更少(不是隐私门槛 — 它防止在任何邮编溢出上限时启动回填)。
不在范围内
| 事项 | 原因 |
|---|---|
| 同一房东的重复 | H3 |
pg_trgm 或 pgvector 搜索 | H4;有漏报反馈时再考虑 |
| 不同邮编 | H4 |
| 告诉房东有提示 | 仅限管理员 |
| Jev 自动标记或自动冻结 | H2 |
| 撤销驳回 | 很少见;有需要时再加 |
| 管理员查看审计日志 | 同 ADR-0066 |
| 重复的 API 接管每次都插入新的指纹标记 | 已有 bug,单独跟踪。本设计只读取最早的未决标记 |