DIY Rental Platform — Slice 1: Listings and Owner Onboarding

本文档存在的原因

plan.md 描述了一整家 PropTech 公司——无中介市场、法律文件自动化、电子签署、 租赁执行、水电费监控,以及带外勤人员的物业管理业务。即便是其中的"MVP"也包含六个子系统。 这对一份文档来说太大了,因此本文档只涵盖第 1 阶段;后续阶段会有各自的 文档、计划和开发周期。

plan.md 中的其余部分——物业管理运营、TNB 与水务 API、维修工单、律师事务所 升级、忠诚度计划、中介行为检测——都属于第 2 阶段或更晚,本文档不涉及设计。

第 1 阶段要证明什么

一位马来西亚业主能够创建账号、发布一个真实房源、通过所有权审核并看到它上线——而租客 能够找到它。仅此而已。如果业主都不愿意做这件事,后续阶段就不值得投入建设。

• 业主无需帮助即可完成房源提交
• 管理员能在面板中以业主能读懂的理由批准或拒绝
• 租客无需账号即可通过搜索和筛选找到房源
• 任何公开响应都绝不包含业主联系方式或所有权文件

范围

范围内

• 房东注册与登录:一个公开的 /owner/sign-up 页面(使用 Better Auth 的 signUp.email,无需邀请),外加一个精简的 rental 端点,将新账号提升为全局 landlord 角色——面板目前不存在自助注册路径,因此这是新工作,而非复用
• 创建和编辑房源:类型、地址、区域、租金、押金条款、装修状况、房屋规则、可入住日期、照片
• 所有权声明勾选框加证明文件上传(水电费账单、地税单,或买卖合同首页)
• 管理员审核队列:批准、附理由拒绝、暂停已上线房源、恢复被暂停房源
• 公开市场:按区域/价格/类型/装修状况浏览与筛选,房源详情页,"业主直发"标识
• 业主联系方式从不公开显示。详情页显示一个禁用状态、标注为"即将推出"的"预约看房"按钮

范围外(经决策排除)

看房预约、消息、要约、租赁协议、电子签署、付款、可退还的房源押金、租客账号、评分、中介 行为检测、物业管理运营、公用事业 API。第 1 阶段租客无需账号即可浏览—— 租客登录随第 2 阶段一起推出,那是第一个需要它的阶段。

架构

语言

上线时仅支持英文,通过与其他应用相同的 Paraglide 配置接入,以便日后无需重构即可加入马来文和中文。业主撰写的房源描述保持自由文本,使用业主输入时的原语言。

数据模型

四张表,通过新的 migrator_rental.go 中的 GORM AutoMigrate 创建。

房东档案

无独立表——第 1 阶段沿用现有的 users 记录已经足够

管理员操作

无独立表——审核字段保存在挂牌记录上;共用的 audit 基础设施记录是谁做了什么

挂牌状态机

stateDiagram-v2
    [*] --> draft
    draft --> pending_review
    pending_review --> live
    pending_review --> rejected
    rejected --> pending_review : owner edits
    live --> withdrawn
    live --> suspended : admin action
    suspended --> live : admin restore
    withdrawn --> [*]
    

withdrawn 和 suspended 并非都是死胡同:暂停可以由管理员直接 恢复回 live。一旦某条挂牌到达 withdrawn,业主就可以为同一处 房产创建一条全新的挂牌(重新从 draft 开始)(参见第 5 节的基数规则)。这是 第 1 阶段唯一的真实业务逻辑——由覆盖每一种合法与非法状态迁移的表驱动测试来保证,包括 "恢复"以及"撤回后新建挂牌"这两种情形。

流程

A——业主发布房源

1. 注册

   新房东在公开的 /owner/sign-up 页面注册(使用 Better Auth 的 signUp.email,无需邀请);随后一个精简的 rental 端点将该账号提升为全局 landlord 角色。

2. 填写房产表单

   在 /owner/properties/new 页面。

3. 上传照片

   使用公开存储前缀,通过一个直接调用共用存储接口的 rental 专属上传端点——而不是走组织范围的共用附件流程,因为房东没有所属组织。

4. 上传所有权证明

   使用私有前缀,通过 rental 专属上传端点;存储层永远不会为它返回公开 URL。

5. 声明所有权

   勾选所有权声明;declared_owner_at 和 declared_ip 在本次提交时被(重新)盖章。

6. 提交

   状态变为 pending_review。

7. 管理员发现该房源

   通过访问已筛选的审核队列——第 1 阶段不会发送任何通知(共用的 notifications 模块要求有所属组织,而房东没有)。

8. 批准或拒绝

   管理员批准——状态变为 live,生成 slug,业主收到邮件通知。或拒绝——写入 review_reason,业主看到理由并修改后重新提交(重新盖章声明)。

B——公开浏览,无需登录

GET /api/public/rental/listings?area=&min_rent=&max_rent=&type=&furnishing=&page=
GET /api/public/rental/listings/{slug}

仅返回 live 状态的挂牌。响应中不含业主姓名、电话、邮箱、精确的 address_line 或证明文件——绝不包含(只提供 area/city/postcode,以避免租客在预约看房之前就 直接上门)。Astro 会在服务端渲染 /property/{slug},并带上缓存头,让 Cloudflare 承接重复流量。

C——管理员审核

面板中的 /admin/rental/listings?status=pending_review,使用既有的审核队列 表格模式。可批准、附理由拒绝、暂停已上线房源,或将已暂停的房源恢复为 live。所有权证明文件通过一个经过身份验证的仅限管理员端点以流式方式查看—— 绝不会是公开或签名 URL。如果另一条 rental_properties 记录与之共享同一个 规范化地址,审核界面会显示一条普通的警告横幅(一次读取时查询,无需新增表或通知)。

两个关键边界

存储隔离

不同的前缀,不同的访问路径,绝不混用。

鉴权

internal/api/http/middleware/better_auth_rbac.go 中的 RequireOrgRole 是组织范围的,需要上下文中存在组织 ID。B2C 房东没有所属组织, 因此rental 绝不能使用它。

错误处理

测试

交付顺序

每一步都以某个可观察的结果收尾。先完成后端到第 5 步,意味着前端工作永远不会被 API 结构卡住。

1. 后端骨架

   模块骨架、配置 profile、迁移 → 表已存在,健康检查通过。

2. 房产 + 挂牌 CRUD

   带鉴权测试的房东 CRUD → API 可通过 curl 验证。

3. 上传

   照片与证明文件上传,两种存储前缀 → 文件落在正确的存储桶中。

4. 生命周期

   提交、状态机、管理员批准/拒绝/暂停/恢复 → 通过 API 走通完整生命周期。

5. 公开读取 API

   公开读取 API 与黄金测试 → 已上线的挂牌可查询,且不泄露任何信息。

6. 房东界面

   面板 /owner/* 路由与布局 → 业主可在浏览器中发布房源。

7. 管理员界面

   面板 /admin/rental/* 审核队列 → 管理员可在浏览器中批准。

8. 公开站点

   Astro 搜索、筛选、详情页、SEO 标签 → 租客能找到房源。

9. 端到端与部署

   Playwright 主路径测试,部署两个前端。

法律说明

本平台是一个工具提供方,而非房地产中介,也不是法律顾问。条款中必须声明:房源发布仅限 业主发布其自有房产。这一点从第 3 阶段起变得更加重要,届时系统会生成租赁协议,但相关 定位从上线之初就应写入条款中。