TypeSafe Jev — Handover Dispute Sorting and Escalation
Jev helps with move-in handover disputes without grading damage: it matches a tenant's missing-item report to an existing report item for the landlord, and checks every thread comment for four fixed escalation reasons that only admins see. The original severity score is replaced because slice 5 bans AI severity grading toward the parties.
摘要
Jev 用两种不涉及损坏评级的方式协助入住交接争议:把租客的"漏报"与报告中已有的物品匹配(仅房东可见),并对每条线程留言检查四个固定的升级原因(仅管理员可见)。原构想中的严重度评分被替换,因为第 5 期设计禁止 AI 向双方给出严重度评级。
- 状态
- 设计已在对话中批准(2026-10-02),等待书面规格评审
- 相关
- 第 5 期入住交接 §4.7 与 §5.1(AI 不得评定严重度);Jev 聊天消息检查(管理员发现列表、邮件提醒、重试扫描);ADR-0066(原始文本发送至 TypeSafe);决策模型提供方(提供方开关、按提供方设定阈值);ADR-0068(调用日志与重放)
为什么
在入住交接报告的租客审阅阶段,租客可以开启两种线程,之后双方轮流回复。
| 动作 | 目标 | 示例 |
|---|---|---|
dispute_entry(争议) | 一个物品(HandoverEntry) | "沙发:干净",但实际有污渍 |
report_omission(漏报) | 一个房间(HandoverArea) | "空调遥控器不见了" |
- 漏报只指向房间。房东必须自己判断它是真正的新问题,还是与报告中已有物品相同("空调遥控器"对应物品"遥控器 x2")。普通代码无法匹配这类情况。
- 平台上没有人看到严重问题。线程中可能提到煤气味、停水、黑色霉菌或威胁,但只有双方会读到。
交付内容
房东
分类- 每条线程显示类型标签,由普通代码设定
- 按类型筛选
- 漏报线程:Jev 找到匹配时显示"可能与已有物品相关:沙发(客厅)"
管理员
升级- 任一方每条带留言的事件都检查四个原因
- 任一"是" → 进入新的 panel 列表"交接升级"
- 每条线程向所有管理员发一封邮件
租客
不变- 只新增类型标签
- 永远看不到匹配提示或任何升级
决策
H1 · 用什么取代严重度评分?
四个固定的是/否升级原因,仅管理员可见。
保留第 5 期对双方的禁令。每条提醒都说明原因,管理员可以据此行动。
否决:仅管理员可见的 1–5 分(更接近被禁止的评级,且不说明原因);管理员和房东都可见的 1–5 分(违反第 5 期对一方的规则)。
H2 · 线程类型从哪里来?
普通代码:目标物品的 EntryType,report_omission 则为"报告漏项"。
类型永远正确且不需调用。留言本身已说明是哪种分歧。
否决:由 Jev 从固定列表中选择分歧种类(多一个需调校的 AI 字段,有时会错)。
H4 · Jev 检查哪些事件?
匹配只在开启 report_omission 的事件上运行。升级检查在租客或房东的每条带留言的事件上运行。
线程主题不会变。威胁或危险可能出现在任何回复中。
否决:仅开启事件(会漏掉之后的威胁);每个事件两项检查都跑(每次回复都重新分类同一线程)。
H6 · 谁能看到匹配提示?
房东和管理员。租客看不到。
它帮助负责回复的一方。若展示给租客,会像是平台在否定其主张。
否决:双方都可见(像在偏袒);仅管理员(房东得不到帮助)。
H7 · 管理员能做什么?
标记 reviewed 或 false_alarm。其他处理在应用外进行。
沿用已测试的 #1 模式。管理员操作不会改变报告。
延后:延长审阅期限。否决:通知双方(会让他们知道被 AI 标记)。
| # | 决策 | 原因 |
|---|---|---|
| H3 | Jev 只做 (a) 将漏报匹配到已有物品,(b) 回答四个原因 | 这是普通代码做不到的两件事 |
| H5 | 只用文字,不用照片 | Jev 是文本判定器。照片需要视觉模型,有其自身的成本和同意规则。 |
| H8 | 结果存放在新表中,而不是 rental_handover_responses | 回复是只追加的证据,会进入最终快照 |
| H9 | 检查与事件在同一事务中排队,由扫描任务执行 | 用户无需等待 Jev,进程中断也不会丢失检查 |
| H10 | 每份报告最多 100 次检查 | 回复需双方轮流,因此这是安全上限,而非常态限制 |
| H11 | 新 ADR 同时说明将留言文本发送给 TypeSafe 的隐私问题,以及为何仅管理员可见的升级不属于第 5 期禁止的评级 | 与聊天功能需要 ADR-0066 的原因相同 |
升级原因
提到安全风险
safety_hazard
对人有危险:煤气味、电线外露、火花、栏杆或阳台松动、天花板开裂、玻璃破碎。
"卧室插座一插电就冒火花"
提到无法居住
not_livable
缺少基本需求:没水、没电、马桶无法使用、严重漏水或积水、门锁不上。
"入住以来整个单位都没水"
提到健康风险
health_risk
大面积霉菌、虫害(蟑螂、老鼠、臭虫)、污水。
"浴室天花板布满黑色霉菌"
提到威胁或辱骂
threat_or_abuse
一方威胁、骚扰或辱骂另一方。
"你不修的话我就去你家"
数据
一个迁移。新表 rental_handover_response_checks:
| 列 | 类型 | 含义 |
|---|---|---|
response_id | uuid PRIMARY KEY REFERENCES rental_handover_responses(id) | 被检查的事件 |
report_id | uuid NOT NULL | 用于每份报告上限和管理员链接 |
thread_id | uuid NOT NULL | 用于每条线程只发一封邮件 |
status | text NOT NULL | pending、done、skipped、failed(CHECK) |
ask_match | boolean NOT NULL | 仅对开启 report_omission 的事件为真 |
escalation_reasons | text[] NOT NULL DEFAULT '{}' | 四个代码的子集 |
match_entry_id | uuid NULL | 匹配到的物品;"无匹配"时为 null |
attempts | int NOT NULL DEFAULT 0 | 目前失败的 Jev 调用次数 |
checked_at | timestamptz NULL | 保存为 done 的时间 |
alerted_at | timestamptz NULL | 为此线程发送管理员邮件的时间 |
review_status | text NOT NULL DEFAULT 'open' | open、reviewed、false_alarm(CHECK) |
reviewed_by、reviewed_at | text NULL、timestamptz NULL | 管理员审阅 |
created_at | timestamptz NOT NULL | 事件时间 |
索引:
(created_at) WHERE status = 'pending',供扫描任务使用。(created_at DESC) WHERE escalation_reasons <> '{}',供管理员列表使用。
review_status(open → reviewed / false_alarm)只适用于带原因的 done 行。后端
在 AppendResponse 中排队
文件:backend/go/internal/modules/rental/application/usecase/handover.go。在现有事务中、回复插入之后,当以下条件全部成立时插入一条 pending 检查行:
IsRentalHandoverCheckEnabled()已开启;- 该事件有非空留言;
- 该报告的检查行少于 100 条,否则该行保存为
skipped。
仅当 Action == report_omission 且线程是新开时,ask_match 为真。事务回滚则不留下任何行。
扫描任务
HandoverCheckSweepUseCase,在共享的 scheduler.RunPeriodic 上每分钟运行一次,与消息检查扫描一起启动。
- 检查开关
两个开关都关闭 → 不做任何事。
- 认领
最多 20 条
pending行,最旧的优先(FOR UPDATE SKIP LOCKED)。 - 加载上下文
回复本身、其目标(物品名称与状况备注,或房间名)、房间名、作者角色;当
ask_match时,还有报告中每个物品,格式为"房间 – 物品"并附 id。 - 判定
在 10 秒超时内调用判定器一次。
- 成功则保存
done、原因、match_entry_id和checked_at。 - 失败则重试
attempts + 1。达到 5 次,或created_at超过 24 小时 →failed。单行失败不会中断本轮。 - 提醒
原因非空,且同一
thread_id中没有行设置了alerted_at→ 给所有管理员发邮件并设置alerted_at。邮件失败会记录日志;该行仍显示在管理员列表中。
即使报告在某行仍为 pending 时已定稿,该行仍会被检查。
Jev 判定器
- 端口
port.HandoverCheckJudge,方法Judge(ctx, HandoverCheckInput) (HandoverCheckResult, error)。 - 适配器
backend/go/internal/modules/rental/adapter/outbound/typesafe/handover_check_judge.go,结构仿照duplicate_judge.go。 - 状态:
comment、author_role、target_label、target_condition_note、room;匹配时还有items,格式为[{key, label}]。key 是生成的短标签(i1、i2、…),在代码中映射回物品 id。不含用户 id、姓名、地址或租约数据。 - 问题:四个 Noul 问题(每个原因一个),匹配时再加一个 Choice 问题
matched_entry,选项为物品 key 和none。 - 留言只作为状态数据传入,绝不放进问题里。
Caller{rental, handover_check, <response id>};每次调用都记录在typesafe_calls。cmd/replay-typesafe支持handover_check。- 判定器把四个概率和匹配结果返回给用例。只存储代码和物品 id,不存储概率。
-
EscalationThresholdsreason = yes when p ≥ threshold按提供方 0.7 -
MatchThresholdsmatch when top choice ≠ none AND p ≥ threshold按提供方 0.7 -
per-report capcheck rows per report100 -
sweep batchpending rows per 1-minute run20 -
give upattempts ≥ 5 OR created_at older than 24h → failed5
配置与装配
TYPESAFE_RENTAL_HANDOVER_ENABLED(默认false)、TYPESAFE_HANDOVER_PROVIDER(默认jev),在config.go中与其他 TypeSafe 配置一起读取。IsRentalHandoverCheckEnabled()= rental 开关与 handover 开关同时开启。module.go解析提供方并构建判定器,方式与重复判定器相同。开关开启时,未知提供方或任一阈值表中缺少该提供方,都会导致模块启动失败。开关关闭时,不启动判定器和扫描任务。.env.example列出这两个变量。
API
| 路由 | 调用者 | 变更 |
|---|---|---|
| 交接报告详情(已有) | 房东 | 每条线程新增 matched_entry_id(无匹配或未检查时为 null) |
| 交接报告详情(已有) | 租客 | 不变:从不返回 matched_entry_id |
GET /api/rental/admin/handover-escalations?status=open|all | 管理员 | 升级事件,按时间倒序:id、时间、房产、报告 id、线程 id、作者角色、原因、留言、目标名称、审阅状态 |
GET /api/rental/admin/handover-escalations/:id | 管理员 | 整条线程,按时间正序,附目标和该线程的照片 id |
POST /api/rental/admin/handover-escalations/:id/review | 管理员 | 请求体 {"status": "reviewed"|"false_alarm"};记录操作人和时间 |
GET /api/rental/admin/handover-escalations/:id/media/:media_id | 管理员 | 返回该线程的一张照片。目前 GET /handover-media/:id/content 只对双方开放。不属于该升级线程的照片 → 404。 |
前端
Rental 应用(frontend/solidstart/apps/rental)
| 位置 | 变更 |
|---|---|
HandoverThreadList | 每条线程显示类型标签:"状况"、"物品清单"、"门禁设备"、"仪表读数"、"报告漏项"。双方都能看到。 |
HandoverThreadList,仅房东 | 按类型筛选(默认"全部") |
HandoverThreadList,仅房东 | 带 matched_entry_id 的漏报线程:"可能与已有物品相关:{item}({room})",链接到该物品。绝不使用"重复"或"已覆盖"等字眼。 |
| 检查进行中 | 不显示任何内容;下次刷新时出现提示 |
HandoverThreadList 中房东看到的漏报线程:类型筛选、类型标签和匹配提示。租客只看到标签。Panel 应用(frontend/solidstart/apps/panel)
| 位置 | 变更 |
|---|---|
| 侧边栏 | "交接升级",位于"聊天发现"旁边 |
/admin/rental/handover-escalations | 列表:时间、房产、报告、作者角色、原因标签、留言、状态。筛选 Open(默认)/ All。 |
| 行详情 | 整条线程,附目标和照片;标记已审阅与标记误报 |
邮件
主题"Rental handover escalation"。正文包含原因标签和指向 panel 行的链接,不含留言文本,与聊天提醒相同。幂等键 rental:handover-escalation:<thread id>。
措辞
错误处理
| 情况 | 结果 |
|---|---|
| Jev 失败、超时或返回无效输出 | 保持 pending;下一轮重试;5 次或 24 小时 → failed。无提示,无升级。 |
| 开关关闭 | 不产生新行。已有的 pending 行等待。重新开启不会补检旧事件。 |
无留言的事件(resolve、withdraw) | 不产生行 |
| 单份报告已有 100 次检查 | 后续事件 → skipped |
| 匹配到的物品之后被删除 | 不会发生:提交后房间与物品不可更改(第 5 期) |
| 管理员邮件发送失败 | 记录日志;该行仍在管理员列表中;不重试 |
| 同一线程两次升级 | 只发一封邮件(alerted_at) |
| 留言中的提示注入 | 留言只作为状态数据;校准集包含注入用例 |
| 检查进行中报告已定稿 | 仍会检查 |
测试
TDD:先写失败的测试,再写代码。Go 测试在 pg-test(:55432)上运行,绝不在 UAT 上运行。
| 层级 | 内容 | 位置 |
|---|---|---|
| Go 单元 | 状态只含所列 key;物品 key 映射回物品 id;阈值按提供方;恰好等于阈值 → 是 / 匹配;首选为 none 或低于阈值 → 无匹配;未知提供方或缺少阈值会失败 | typesafe/handover_check_judge_test.go、pin_test.go、模块测试 |
| Go 用例 | 仅在有留言且开关开启时创建行;同一事务(回滚 → 无行);ask_match 只用于开启 report_omission;第 101 次检查 → skipped | usecase 交接测试 |
| Go 扫描 | 每轮 20 条;SKIP LOCKED 认领;失败 → 重试;第 5 次失败或 24 小时 → failed;单个坏行不会中断本轮;两次升级只发一封邮件;开关关闭 → 不做事 | usecase 扫描测试 |
| Go handler | 房东详情带 matched_entry_id;租客详情永远不带;任何一方响应或最终快照都不含原因;管理员列表与审阅的 401 / 403 / 404 / 400 情况;审阅记录操作人和时间 | http/ 测试 |
| 迁移 | 表、status 与 review_status 上的 CHECK、索引;重复运行不产生变化 | migrations/ 测试 |
| 前端单元 | 每种类型都有标签;匹配提示与筛选仅房东可见;panel 列表、筛选、审阅按钮;黄金测试确保每个原因代码在两个应用中都有 en / ms / zh 文本 | Vitest |
| 校准(非 CI) | 已标注的马来西亚英语、马来语和 Manglish 留言,含陷阱("safety pin missing"、"kill the bugs")和注入用例。在 UAT 以外开启开关前设定阈值 | cmd/ 脚本,同 #1 |
| 浏览器冒烟 | 在 UAT 用 /ego-browser:租客开启一条漏报和一条"插座冒火花"争议;房东看到标签和匹配提示;管理员看到升级、收到邮件并标记已审阅 | 手动运行 |
范围之外
- 管理员延长审阅期限(
review_due_on)。计划后续实现;需要为最终快照制定专门规则。 - 通知双方有管理员在跟进。
- 以照片作为输入。
- 退租报告与押金决定。
- 任何形式的严重度评分。
- 检查聊天消息(构想 #1 已经覆盖)。
上线门槛
在以下条件满足前,TYPESAFE_RENTAL_HANDOVER_ENABLED 在 UAT 以外保持关闭:
- ADR 通过
H11 中的 ADR 已撰写并通过。
- 校准
校准运行确定两个阈值。
- 告知
用户告知内容涵盖交接留言发送至 TypeSafe,以及管理员审阅升级线程。