---
name: handout-property-records
description: 把房主或物业经理（PO/PM）的日常叙述、照片和文件转换为正确的 Handout 房产、Lease、租客资料、Asset、Service、Task、Reminder、Document 及关联修改。复用已有记录，只问关键缺失事实，展示预览后确认写入。不服务 Tenant/SP 自助角色。
metadata:
  version: 1.2.1
---

# Handout 房产记录

## 业务编号

业务记录返回后台分配的 `public_id`，例如 `PRP-00000001`、`LSE-0000000A`。序号为固定 8 位 Base32，每类独立递增，允许跳号，已发编号永不回收；原有 `id` 和关联字段继续有效。支持的 MCP 引用字段可在权限核验后接受业务编号，其他情况先从可访问列表定位。不得自行编造编号、把 `public_id` 当作可编辑字段、擅自替换外键，或因知道编号就推断有访问权限。预览和未保存的草稿不预留正式编号，以提交成功后的返回为准；历史记录补号前可能没有编号。归档或删除的编号不能用于创建另一对象，恢复只能走原对象的授权恢复流程。

## 检查 Skill 更新

每次启用时读取 `https://handout.us/oauth/agent-setup`，将本包的 `metadata.version` 与 `skill_release.versions` 中同名版本比较。发现新版时，用用户的对话语言提示更新，提供更新已安装 Skill 及同语言完整声明文件的操作。保留现有成功连接、凭据和权限，继续当前业务任务，无需等待更新。MCP 返回的 `handout_notice` 也触发相同检查，同一对话、同一版本避免重复提醒。只有宿主确认后才报告安装完成；版本查询失败时继续工作，不把版本未知说成已过期或已是最新。

仅供 PO/PM。Tenant 是由 PO/PM 管理的资料，不是租客登录账号；暂不开放 Tenant/SP Skill。所有操作使用用户本人的权限，共用 App 业务规则。

## 先理解发生了什么

用户不必指定模块或字段。提取事件、房产、人物、时间、进展、付款和附件，区分明确事实、待确认默认值和未知信息。先找已有记录，再决定追加、更新还是创建。把必须追问的信息合并成一个简短问题。

| 用户叙述 | 正确业务含义 |
| --- | --- |
| 水槽漏水 | 查已有维修 Task，否则提议创建；没有发生付款的证据。 |
| 水管工来看过/修好了 | 追加 Comment；只有明确修好才提议完成状态，进展不应生成重复 Task。 |
| 那次维修付了 280 | 找原 Task，按财务 Skill 准备关联实际支出；报价/未付发票只作为工作上下文。 |
| 新冰箱和两张照片 | 提取外观/铭牌，确认位置和看不清的型号序列号；不按照片数量建资产，也不自动认定已付款。 |
| 租客续约了 | 找原 Lease，按新日期租金生成新 Draft，不覆盖旧合同。 |
| 同一服务商管两套房 | 一个 Service 加授权覆盖范围，不因切换房产复制两份。 |
| 下个月提醒我 | Reminder，不是费用已付；只追问不明确的日期或周期。 |
| 保存这张发票/照片 | 确定房产和目标记录或 Document；发票不自动成为 Transaction。 |

跨模块事件参考[事件转业务数据](https://handout.us/skills/tobby-landlord/zh-CN/references/event-to-record.md)。先解释最小关联方案；叙述足够准备草稿，但不是自动保存授权。

## 准备与确认

1. 未连接时使用[连接指引](https://handout.us/skills/handout-connect/zh-CN/SKILL.md)，凭据留在宿主安全设置。
2. 读取实时工具、`me.get` 和 `app_schema.get(tool:...)`，包含 input_schema、data_schema、update_data_schema、action_data_schemas。查询专用连接不能准备写入；应解释权限需求，不能自动升级。
3. 操作需要房产时匹配真实房产，并复用记录；个人独立 Reminder 不需要房产或关联对象；不明确才让用户选择，用名字展示，ID 仅内部调用。不能假装知道 App 当前筛选状态。
4. 新增非英文描述时，沿用本次对话已确认的存储语言，否则问是否转为英文。由用户 Agent 翻译；名字、地址、金额、日期、型号序列号和源文件保持准确。
5. 按实时字段准备。ready:false 或必填 missing_inputs 阻止确认；可选图片不阻止完整提案。读取 error.data.input_feedback.issues，提取证据或只问缺失事实，再准备。
6. 展示真实预览：对象/房产、最终文本或前后变化、默认值、附件、依赖和影响；用户明确同意后提交 action、preview_id、user_confirmed:true。房产删除额外需要明确的 confirmation:"DELETE"。内容或依赖改变必须重新预览。

## 依赖和字段映射

字段参考供 Agent 构造数据，不是让用户填的表。实时 schema 优先；未知可选字段留空，不填假日期/金额/邮箱。

| 记录 | 准备方式 |
| --- | --- |
| Property 创建 | 顶层 address、property_usage:rental/personal_use、用户已确认 ownership；基础资料在 spec。创建者不必是 Owner，不强制 APN，不传虚构 property_id。地址查询不证明产权。 |
| Property 修改 | property_id 和 data 内普通名称/地址/spec/HOA；用途、权限和 ownership 交接另走各自流程。 |
| Lease 创建/续约 | 授权 Rental 房产的 property_id 及 data；期限按月，合同日期、租金频率/金额须有事实依据。只有 Active/Expired 原 Lease 可续约，新日期在旧合同之后，结果为新 Draft，并保留押金/Inventory 延续。 |
| Tenant profile | property_id、可选同房产 lease_id、data.personal_info.first_name/last_name/email；合同日期属于 Lease。已有资料只能按已开放的关联操作处理，不为改 Lease 重复建租客。 |
| Task | 顶层 title/description、task_category（financial category）、task_priority、status；due_date/report_date 可选，不凭空加到期日。mx/task ID 不向用户展示。 |
| Task Comment | 已有 property_id/task_id、comment、可选 image_reservation_ids。评论不自动改状态，完成状态另准备修改。 |
| Asset 创建 | 顶层 nickname/type/location/brand/model/serial/mfg_date/acquired_date/notes。推荐外观、铭牌各一张；Agent 识别，原样保留标识，不清晰则问或留空。photos 使用真实 reservation_id 和 appearance/nameplate kind。 |
| Service | property_id 是源房产；data 包含 service_type（支持 Other）、company_name、agent 联系信息、notes、property_ids 覆盖。写入使用返回的 source_property_id，每个覆盖房产都需授权。 |
| Reminder | 可独立/关联、个人/共享；顶层 title/note、due_date、category、周期、lead_days，可选 property_id/source。list/get/link_options 只读，状态走 prepare_state/confirm_state。准备前阅读[统一提醒流程](references/reminders.md)。 |
| Document | 创建用顶层 name/category/note/reservation_id；元数据更新用 data.name/description/category；文件字节走 Storage，不放进元数据字段。 |

普通 Lease 编辑、状态、归档分别使用 update/status/archive。Lease 状态和房产 leased/vacant 不同；Tenant 联系方式修改不改变合同。Asset/Service 等新编辑操作使用 data，旧 Property/Asset 创建及 Task/Transaction/Reminder 仍用顶层字段，不能假定统一形状。

财务与报告用[房主/房管工作流](https://handout.us/skills/tobby-landlord/zh-CN/SKILL.md)；批量旧资料用[迁移 Skill](https://handout.us/skills/handout-data-migration/zh-CN/SKILL.md)。维修记录不是付款证据。

## 图片、文件和补挂

- 同时提交的文字和照片默认属于同一业务事件。有冲突先问，确需多事件拆分时展示关联方案，不能为每张图再造 Task/付款。
- 先通过 storage.create_upload_url 并按返回 upload_headers 传真实字节，或使用支持的小文件 upload。get_upload 用于检查未知结果；reservation 不是已保存/已关联业务数据。
- 新 Task/Comment 最多五张；Asset 创建支持外观/铭牌；Transaction 主收据接受一个 reservation_id 或已 committed picture_url，不能同时传。额外图片用 record_images。
- record_images 的 get/prepare_attach/confirm_attach 支持 property/task/transaction/asset/document/reminder/lease/tenant/service/receivable/settlement；保留旧文字与图片。财务目标仍需财务权限。新建房产照片必须等实际 property_id。
- 普通 PDF/收据挂 Task/Transaction 用 record_files.get，再 prepare_attach；传 reservation_id 或已有 document_id 二选一，展示文件、目标及旧关联，再确认。prepare_detach/confirm_detach 只解除该关联，源文件和其他关联保留。
- 保存成功但关联失败，应说“记录已保存，附件尚未关联”，按原 ID 修复。未知结果先读，不重新建业务记录，也不伪造 URL、路径或上传。
- Inventory 必须使用清单版本/参与者流程及 item 绑定上传；续约时使用返回的源 Lease 上下文，不能另造清单绕过签名规则。

## 取消、纠错、移除

确认前取消，不调用 confirm。保存后按真实 edit/status/delete/archive/reversal 处理，不假造通用撤销。Lease 终止/归档、Task 取消、Reminder 停用、文件解除关联与永久删除是不同操作。

Task/Transaction/Document 删除走 record_delete；Property/Asset/Service/Reminder/Tenant profile 使用自己的 delete。展示依赖、文件影响及不可逆性；工作流保护的财务记录不能强删。

超时或预览被消费先查记录/历史；版本冲突重新读取并准备。确定的字段错误最多修正两次，仍失败保留安全错误/支持编号。403 不能通过换身份或新建替代对象“修复”。尚未开放的所有 Lease 文件操作、通用图片删除替换、官方报告导出应回到 App，不虚构接口。