DIY Rental Platform — Public Marketplace (Astro)

摘要

这是马来西亚租房市场对外公开的门面：一个部署在 rent.gremlin.my 的全新 Astro 7 应用，匿名访问、以 SEO 为核心，所有页面都在服务端渲染，公开数据直接读取 Go，并且完全不引入任何 island 框架。切片 1 证明房东愿意挂牌，切片 2 证明双方愿意成交；没有这个应用，两者都只是内部工具。

• 域名 rent.gremlin.my → panel.gremlin.my
• 技术栈 Astro 7 + Cloudflare 适配器，零集成
• 受众 Seeker（寻租者）——未登录，来自 Google 或 WhatsApp
• 覆盖范围 切片 1 第 8 步、切片 2 第 9 步——无 OpenSpec 变更
• 新增 ADR 0056（产品边界）、0057（slug 不可变）
• 硬依赖 四项契约必须赶在切片 1 的 fixture 冻结前落地

一位 Seeker——没有账号的人——通过 Google 找到一条马来西亚租房信息，浏览并筛选 而页面不刷新，然后点击进入预约看房。

成功标准

• 房源详情页可被索引，分享到 WhatsApp 时能正确渲染卡片
• 筛选不刷新页面，且每个结果集都有可分享的 URL
• 任何公开页面都不会渲染房东姓名、电话、邮箱或详细街道地址
• 即使 API 挂掉，站点仍能提供可用的页面
• 曾被索引或分享过的 URL 永远有效——slug 永不改变（ADR-0057）
• 点击"Arrange Viewing"会进入该条房源的预约表单，即使 Seeker 中途必须注册账号

架构概览

flowchart TD
    seeker["Seeker · signed out"] --> edge["Cloudflare edge · cached HTML"]
    edge --> ssr["Astro SSR on Workers"]
    ssr --> api["rental-api.ts · the only fetch caller"]
    api --> go["Go · GET /api/public/rental/listings"]
    ssr --> img["/cdn-cgi/image · edge resize"]
    img --> r2["R2 public photo prefix"]
    edge -.->|"Arrange Viewing"| panel["panel.gremlin.my/tenant/book/{slug}"]
    panel --> auth["Better Auth sign-up · slug preserved"]
    auth --> book["Booking form · Seeker becomes Tenant"]
    

数据流

browser ──► Cloudflare edge (cached HTML)
              └─► Astro SSR on Workers
                    └─► GET {RENTAL_API_URL}/api/public/rental/listings?…
                        RENTAL_API_URL = https://api.kokweng.net   (origin only)

只有一个模块 src/lib/rental-api.ts，导出 searchListings(params) 和 getListing(slug)。它负责路径常量、查询串拼装、请求超时和响应类型。任何页面都不直接 调用 fetch。

应用结构

apps/rental/
  astro.config.mjs            ASTRO_ADAPTER pattern, copied from quiz; no integrations
  src/
    layouts/Layout.astro      ClientRouter + prefetch
    pages/
      index.astro
      property/[slug].astro
      sitemap.xml.ts
      404.astro
      unavailable.astro       rendered for the 503 degraded state
    components/
      FilterForm.astro        <form method="GET"> + inline requestSubmit() on change
      ListingCard.astro
      PhotoGallery.astro      CSS scroll-snap + anchors, no JavaScript
    lib/
      rental-api.ts           the only module that calls fetch
      areas.ts                allowlist of indexable areas
      image.ts                /cdn-cgi/image URL builder

页面包括 /（筛选表单 + 结果）、/property/{slug}（房源详情）、 /sitemap.xml，以及静态的 /robots.txt。筛选条件完全存放在查询串中： ?area=&min_rent=&max_rent=&type=&furnishing=&page=

关键决策

仓库中既有的结论

从探查 frontend/astro 和切片 1 的 schema 得到五项发现，其中三项修正了切片 1 的设计。

范围

范围之内

• 新应用 frontend/astro/apps/rental，开发用 node 适配器、构建用 Cloudflare，沿用 quiz 和 platform 已有的 ASTRO_ADAPTER 模式
• ADR-0056，记录产品边界与直连 Go 的例外
• 搜索页：地区、价格区间、房产类型、家具配置
• 房源详情页 /property/{slug}，含照片、租赁条款、房屋规则和"Direct from Owner"标识
• "Arrange Viewing"链接进入切片 2 在 panel 中的预约入口路由
• SEO：每条房源的标题与描述、Open Graph、canonical URL、JSON-LD、sitemap.xml、robots.txt
• 缓存头，让 Cloudflare 承接重复流量，包含 stale-if-error
• API 不可用时的降级状态
• 通过 /cdn-cgi/image 做边缘图片压缩，避免 5MB 的房东照片原样下发
• 一份精选的可索引地区白名单，同时用于生成筛选下拉框
• Cloudflare Web Analytics，外加一个"Arrange Viewing"点击事件

明确排除在外

任何需要登录的页面、Seeker 账号体系、收藏与心愿单、地图视图、房贷计算器、中介房源、手工撰写的 地区落地页、评价或评分展示、英语以外的语言、GA4 或任何基于 cookie 的分析，以及任何 Bun 代理。

刻意不处理

缓存清除

下架一条房源后，其公开页面最多还会保持热缓存五分钟。不实现任何 purge 调用。

slug 枚举接口

sitemap 通过现有的分页 API 逐页翻取。

升级已有的三个 Astro 应用

在有人主动升级之前，它们继续留在 6。

把 area 规范化

白名单在不改动切片 1 schema 的前提下控制住了影响范围。引用表是后续的升级路径。

slug 重定向

slug 不可变（ADR-0057），所以既没有历史表也没有 301 处理。正因如此，不做才是安全的。

缓存

搜索结果的窗口更短，因为筛选组合会让缓存条目成倍增长，而每一条重新生成的成本都很低。真正值得长期 保留的是详情页。

SEO 与索引规则

• 每条房源的标题与描述由房源数据拼装——例如"3-bedroom condo for rent in Petaling Jaya — RM2,000/month"——描述取自房东填写的文本并截断。
• Open Graph 标签携带封面照片，让 WhatsApp 分享能渲染成卡片。在这个市场，这是实实在在的流量来源。
• 每个详情页加上 JSON-LD RealEstateListing。
• sitemap.xml 由在架房源生成，缓存一小时。
• robots.txt 全部允许，并指向 sitemap。

切片 1 的公开 API 是分页的，且无法一次性取出全部在架 slug，因此 sitemap 路由会逐页翻取直到取尽， 并设一个硬上限。以当前的数据量而言，那就是一次请求。如果房源数量真的涨到几千条，升级路径是在 Go 侧提供一个专门的 slug 接口。

图片

在边缘压缩

lib/image.ts 在 R2 公开照片 URL 之上拼出 /cdn-cgi/image/width=…,format=auto,…。没有构建步骤、没有图片流水线、没有依赖。

显式尺寸

每个 <img> 都带 width 和 height，取自新增的照片尺寸字段，让浏览器预留正确的位置，把 CLS 保持为零。

srcset

一小组固定宽度，避免手机下载桌面尺寸的图片。

懒加载

除 LCP 图片外，其余一律 loading="lazy"——/ 上第一张卡片的照片，以及详情页的封面照片除外。对 LCP 图片做懒加载，恰恰会拖慢被测量的那一次绘制。

退路

如果该 zone 上 /cdn-cgi/image 实际不可用（交付第 1 步验证）：改为在切片 1 的上传环节限制图片尺寸，其余保持不变。

本设计对切片 1 的要求

Arrange Viewing 的交接

这是整个产品唯一的转化时刻，也是 Seeker 变成 Tenant 的地方。按定义每个 Seeker 都未登录， 所以这一次点击必然会撞上注册墙。

sequenceDiagram
    participant S as Seeker
    participant M as "rent.gremlin.my"
    participant P as "panel.gremlin.my"
    participant A as Better Auth
    S->>M: Views /property/{slug}
    S->>P: Clicks "Arrange Viewing" → /tenant/book/{slug}
    P->>P: Store {slug} before redirect
    P->>A: Redirect to sign-in / sign-up
    A-->>P: Session created
    P->>P: Return to /tenant/book/{slug}
    P->>P: Resolve slug
    alt Slug resolves
        P-->>S: Booking form → viewing request created → Seeker becomes Tenant
    else Slug is gone (suspended within cache window)
        P-->>S: "This property is no longer available" + link back
    end
    

本应用这一侧

• 按钮文案保持为 "Arrange Viewing"。曾考虑过："Sign up to arrange viewing"——已否决， 它等于在一个本该激发兴趣的页面上预先张贴阻力。点击事件才能告诉我们，这份阻力究竟有没有真的损害转化。
• 它链接到 https://panel.gremlin.my/tenant/book/{slug}——指向具体那条房源，而不是一个列表。

切片 2 必须补上的部分

1. 一个 /tenant/book/{slug} 路由

   切片 2 目前只有 /tenant/requests，那是一个列表——把一个匿名访客丢在那里，就等于弄丢了他专程而来的那套房子。

2. slug 要熬过注册往返

   注册完成后，Seeker 必须回到那个确切的路由。共享同一个可注册域名，所以这属于同站状态，不是跨域问题。

3. 一个"已不可用"状态

   该路由在加载时解析 slug；当它已无法解析时，显示"This property is no longer available"并给出返回 rent.gremlin.my 的链接——绝不能是裸的 404。这正是"不做缓存清除"这一取舍的可见症状；设计接受了这种滞后，而这里就是处理它的地方。

隐私边界与错误处理

度量

本设计中没有任何其他部分能告诉你它是否奏效，而缺了这一点，你就无法区分是房源供给的问题，还是租客 需求的问题。

• Cloudflare Web Analytics——一个 script 标签，免费，不使用 cookie，因此不产生 PDPA 同意义务，也不需要同意横幅。
• 在"Arrange Viewing"点击上加一个自定义事件，这才是真正关键的数字：它能区分"没人来"和"有人来但不愿注册"，也决定了"先渲染预约表单、之后再要求注册"这个方案是否值得去做。
• GA4 按决策排除在外。它会引入这个站点本来没有的 cookie 同意义务。

如果 Cloudflare Web Analytics 实际上不支持自定义事件，退路是把这项缺失的度量记为已知缺口， 而不是为了一个数字引入更重的分析栈。

测试

• rental-api.ts 单元测试——查询串拼装、响应解析、超时行为和错误结构，针对一个 stub 服务。沿用既有的 apps/quiz/src/middleware.test.ts 先例。
• 泄露测试——渲染一个房源详情页，断言 HTML 中不出现电话、邮箱、房东姓名或详细 address_line。
• 契约漂移测试——把 rental-api.ts 加入切片 1 公开 golden fixture 的客户端清单，断言 client ⊆ Go（ADR-0052 模式）。
• 索引规则单元测试——针对判定 index 还是 noindex, follow 的那个函数，覆盖：裸 /、仅白名单地区、仅非白名单地区、地区加任意第二个筛选，以及 page=2。这条规则在渲染结果中看不出来，很容易被悄悄改坏，正因如此才值得一个测试。
• 一条 Playwright 主流程——进入 /、按地区筛选、打开一条房源，确认"Arrange Viewing"指向 panel.gremlin.my/tenant/book/{slug}。

刻意不做：视觉回归、Lighthouse CI、跨浏览器矩阵。

交付顺序

1. 搭建 apps/rental

   Astro 7 + Cloudflare 适配器，部署到 rent.gremlin.my。同时充当上述四合一探路。

2. ADR-0056 与 ADR-0057

   已完成——两份都写在实现之前，而不是实现过程中。

3. rental-api.ts 及其单元测试

   基于 stub 构建。

4. 搜索页

   筛选表单、结果列表、空状态。

5. 带 ClientRouter 与 prefetch 的布局

   实现无刷新导航。

6. 房源详情页

   照片相册、泄露测试。

7. SEO

   标题、Open Graph、canonical 规则、对非白名单筛选加 noindex、JSON-LD、robots.txt、sitemap.xml。

8. 缓存头与降级状态
9. "Arrange Viewing"链接进入 panel
10. Playwright 主流程，部署

待验证项与开放问题

本设计提出的全部 22 个问题，已在 2026-08-26 的一次拷问（grilling）中全部敲定，结论都已并入上面 各章节。剩下的不是问题，而是一份交付第 1 步需要验证的清单，每一项都已写明退路。