English

Rental Tenant Profile — Design

Tenants get an optional profile (photo plus twelve fields such as age, race, nationality, occupation, occupants and pets) that landlords see on viewing requests, offers and message threads from that tenant. Every field is optional and clearable, only the request's own landlord can read it, and the tenant sees exactly what landlords see.

  • Status Approved

View source markdown ↗ generated by claude-opus-5-5 · diagrams mermaid

概要

租客可以填写一份选填的个人资料——照片加上年龄、种族、职业、宠物等十二个字段——房东会在该租客发来的看房申请、报价和消息对话中看到它。所有字段都不是必填的,每个答案都可以清除,而且租客看到的内容与房东看到的完全一致。

  • 状态 草稿,待审阅
  • 范围 backend/go/internal/modules/rental、frontend/solidstart/apps/rental
  • 受众 租客(填写者)· 收到看房申请的房东(查看者)
  • 存储 新的 Go 数据表 rental_tenant_profiles
  • 界面 /tenant/profile · 房东的看房申请、报价、对话
  • 不在范围内 合作方 /v1 API、资料核验、筛选

目标

马来西亚房东在同意看房前会先了解租客。租客可以在个人资料页填写一份选填资料;房东会在该租客发来的看房申请、报价和消息对话中看到它。

成功标准

  • 租客可以填写、修改和清除任意资料字段及照片;没有任何字段是必填的,预约看房也从不依赖资料。
  • 房东在确认、还价或拒绝之前,可以看到向其发出看房申请的租客资料(因此也包括由该申请产生的报价和对话),无论申请处于何种状态。
  • 其他房东无法读取该资料。
  • 租客看到的内容与房东看到的完全一致。

头脑风暴中做出的决定

字段范围
照片、性别、年龄、种族、国籍、职业、就业类型、入住人数、计划入住时间、是否吸烟、宠物、语言、自我介绍。全部选填。
种族
在提出歧视/品牌风险后,按产品负责人的决定作为选填字段保留。
排除的字段
宗教(属于 PDPA 2010 敏感个人数据)和月收入(无法核实,且会引来索要工资单的要求)。
可见范围
拥有该租客看房申请的房东,任何状态均可见。不公开,不可浏览。
存储
新的、由 Go 拥有的数据表 rental_tenant_profiles;不改动 Better Auth 的 users 表。
合作方 / 房东 API(/v1)
不在范围内,仅限网页应用。
已选

1 · 由 Go 拥有的数据表

在 rental_tenant_profiles 中为每个字段设类型化的列。存储、校验和可见性检查都集中在租赁模块中,而该模块本来就负责租客与房东的关系。

已否决

2 · 在 Better Auth users 表加列

通过 additionalFields 实现。会把认证表结构与市场业务字段耦合;写入走 bun,而可见性却在 Go 中执行。

已否决

3 · 在 users 表加 JSONB 列

表结构改动最少,但没有数据库层面的类型和约束,同样耦合认证表,而且校验要用两种语言各写一遍。

数据模型

新数据表,加入 internal/shared/infrastructure/database/postgresql/migrations/migrator_rental.go 中 CreateRentalTables 系列的迁移:

CREATE TABLE IF NOT EXISTS rental_tenant_profiles (
  user_id          TEXT PRIMARY KEY,
  photo_key        TEXT,
  gender           TEXT,
  birth_year       SMALLINT,
  race             TEXT,
  nationality      TEXT,
  occupation       TEXT,
  employment_type  TEXT,
  occupants        SMALLINT,
  move_in_month    DATE,
  smoker           BOOLEAN,
  pets             TEXT[],
  languages        TEXT[],
  about            TEXT,
  created_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at       TIMESTAMPTZ NOT NULL DEFAULT now()
);

user_id 是 Better Auth 的用户 id,类型与 rental_viewing_requests.tenant_user_id 相同。该行在首次保存时创建(upsert)。

字段规则

校验位于领域实体 entity/tenant_profile.go 中;数据库不设枚举 CHECK(与 rental_viewing_requests.status 处理不断演变的取值集合的方式一致)。每一列都可为空;NULL 表示“未回答”。

字段允许的值说明
gendermale、female
birth_year当前年份 − 100 ≤ y ≤ 当前年份 − 18永不发送给房东。
racemalay、chinese、indian、bumiputera_sabah_sarawak、others
nationality两个大写字母(^[A-Z]{2}$);MY = 马来西亚人界面:马来西亚人 / 非马来西亚人 → 从固定的 ISO 3166-1 alpha-2 列表中选择国家;服务端只检查格式。
occupation去除首尾空白后 1–60 个字符去除空白后为空 → NULL。
employment_typeemployed、self_employed、student、other
occupants1–10
move_in_month某月的第一天;保存时不得早于当前月份(Asia/Kuala_Lumpur)已存的过去日期在读取时仍然有效;只在保存时拒绝。
smokertrue / falsefalse = 明确表示不吸烟。
petscat、dog、other 的子集,不可重复{} = 明确表示“无宠物”;NULL = 未回答。
languagesms、en、zh、ta、yue、other 的非空子集,不可重复空选择 → NULL。
about去除首尾空白后 1–300 个字符去除空白后为空 → NULL。

年龄段

在房东读取时根据 birth_year 和当前年份推算(年龄 = 当前年份 − 出生年份):

房东看到的年龄段,条宽与覆盖的年数成比例:18–24 覆盖七年,25–29 至 55–59 为五年一档,60+ 不设上限。 18–24 25–29 30–34 35–39 40–44 45–49 50–54 55–59 60+
房东看到的年龄段,条宽与每档覆盖的年数成比例:18–24 覆盖七年,其余各五年,60+ 不设上限。

后端

端口与适配器

port.TenantProfileRepository
Get(ctx, userID) (*entity.TenantProfile, error)(没有记录时返回 nil, nil)、Upsert(ctx, *entity.TenantProfile) error、SetPhotoKey(ctx, userID string, key *string) (previous *string, err error)。
port.TenantPhotoStore
新的窄端口:PutTenantProfilePhoto(ctx, userID, contentType string, data []byte) (key string, err error);PublicURL(key string) string;Remove(ctx, key string) error。由现有的存储适配器 PhotoStore 实现。键存放在 rental/tenant-profiles/{userID}/{uuid}.{ext} 下,扩展名 .jpg / .png / .webp 由内容类型决定。port.PhotoStore 及其测试替身保持不变;模块通过对已配置的照片存储做类型断言来取得租客照片存储。
Postgres 适配器
tenant_profile_repository.go,与其他租赁仓储放在一起。

用例 TenantProfileUseCase

  • GetOwn 读取自己的资料;没有记录时返回全为空的值。 本人
  • Save 经实体校验、upsert,返回已保存的资料。 本人
  • UploadPhoto 类型须为 image/jpeg|png|webp(否则 port.ErrUnsupportedProfilePhotoType),大小 ≤ port.MaxPhotoBytes(否则 port.ErrPhotoTooLarge),调用 PutTenantProfilePhoto、SetPhotoKey,再尽力 Remove 旧键(失败只记录日志,不返回错误)。存储为空 → port.ErrMediaUnavailable。 本人
  • DeletePhoto SetPhotoKey(nil),再尽力 Remove。 本人
  • GetForOwner 通过 ViewingRequestRepository.GetByID 加载看房申请;若 req.OwnerUserID != ownerID 则返回 port.ErrRequestNotFound;否则加载租客资料并映射为房东视图。 房东

正方形裁剪在上传前于客户端完成;服务端按原样存储字节。

HTTP(受保护路由组,与 /me/offers 相同)

方法路径响应
GET/me/tenant-profiletenantProfileSelfJSON(所有字段,包括 birth_year、photo_url;未回答时为 null)
PUT/me/tenant-profile请求体:所有非照片字段;200 tenantProfileSelfJSON;400 ValidationError{Fields}
POST/me/tenant-profile/photomultipart 字段名 photo(与房产照片相同);200 tenantProfileSelfJSON;400 类型/大小错误;503 ErrMediaUnavailable
DELETE/me/tenant-profile/photo200 tenantProfileSelfJSON
GET/requests/:id/tenant-profile200 tenantProfileOwnerJSON;调用者不是该申请的房东或申请不存在时返回 404

房东路由挂在现有的 /requests 路由组上(ViewingRequestHandler 的路由,module.go 中的 reqGroup),因此网页路径为 /api/rental/requests/:id/tenant-profile,与前端现有访问看房申请的方式一致。

房东访问校验:“不是你的”和“不存在”无法区分(都返回 404)。
房东访问校验:“不是你的”和“不存在”无法区分(都返回 404)。
tenantProfileSelfJSON — 租客
  • 每个键都存在,未回答时为 null
  • 包含确切的 birth_year
  • 包含 photo_url
tenantProfileOwnerJSON — 房东
  • 省略未回答的字段(omitempty;smoker、occupants 用指针);空资料为 {}
  • 用 age_range 代替 birth_year
  • 没有用户 id、姓名或邮箱

已知限制

前端(apps/rental)

数据访问

src/features/rental/api/tenantProfile.ts,沿用 api/requests 的写法(普通 async 函数加 tenantProfileQueryKeys;hooks 仍内联在组件中):getOwnTenantProfile、saveTenantProfile、uploadTenantProfilePhoto、deleteTenantProfilePhoto、getRequestTenantProfile(requestId)。ApiErrorEnvelope 新增 fields?: string[],以便表单读取服务端返回的字段错误。

TenantProfileCard

features/rental/TenantProfileCard.tsx 纯粹展示房东视图的数据形状,有两种变体:

  • full:照片(无照片时显示首字母头像)、名字(属性传入)、一行已回答的信息(25–29 · Chinese · Malaysian · Software engineer)、标签(不吸烟 / 吸烟、入住人数、入住月份、宠物或“无宠物”、就业类型、语言)、自我介绍。
  • compact:照片、名字(属性传入)、年龄段和职业;点击后展开为 full。

空资料时显示:“该租客尚未填写资料。”

M

Mei

25–29 · 华人 · 马来西亚人 · 软件工程师

不吸烟 2 人入住 2026年11月 入住 无宠物 受雇 英语, 华语

安静整洁,平日在办公室上班。

房东看到的 TenantProfileCard(full 变体)——同一张卡片也作为租客的“房东看到的内容”预览。

租客页面 /tenant/profile

  • 在 TENANT_RENTAL_NAVIGATION(rentalNavigation.ts)末尾加入 { id: 'profile', href: '/tenant/profile' }。
  • 引导文案:“这里的所有内容都是选填的。你申请看房的房东可以看到你填写的内容。”
  • 一个表单,分四组:关于你(照片、性别、出生年份、种族、国籍)、工作(职业、就业类型)、入住计划(入住人数、入住月份、是否吸烟、宠物)、更多(语言、自我介绍)。每个下拉框默认为“未填写”;文本框显示字数;只有一个保存按钮。照片上传/移除立即生效。
  • “房东看到的内容”预览用 TenantProfileCard(full)渲染已保存的本人资料,并在 TypeScript 中经过同样的房东视图映射(年龄段使用相同的分档)。
  • 服务端返回的 400 fields 会高亮对应输入框;已输入的内容会保留。

房东界面

看房申请

full
  • routes/landlord/viewings/[id].tsx
  • 卡片位于 LandlordRequestActions 上方

报价

full
  • routes/landlord/offers/[id].tsx
  • 通过报价的 request_id

消息对话

compact
  • InboxView,仅当 userRole === 'landlord'
  • 位于对话标题下方,名字取自 counterparty_name

预约后的提示

在 routes/tenant/requests/[id] 上,仅当本人资料没有任何已回答字段且没有照片时,显示一条可关闭的提示:“房东更快回复他们有所了解的租客 → 完善资料”。关闭状态保存在 localStorage 中。预约从不等待或检查资料。

国际化

所有文案和每个枚举标签(性别、种族、国籍分组、就业类型、宠物、语言、年龄段)都作为 paraglide 消息写入 i18n/en.json、ms.json、zh.json。国家名称通过 Intl.DisplayNames 按当前语言显示。

测试

Go

  • 实体:各字段的边界(出生年份在 18 岁和 100 岁时、入住人数 0/1/10/11、去除空白后的文本长度、拒绝过去的入住月份、拒绝未知枚举值和重复值);smoker=false 和 pets={} 与 NULL 区分保存。
  • 处理器集成测试(pg-test,:55432):申请所属房东在 pending、declined 和 withdrawn 状态下都能拿到资料;其他房东和租客本人调用房东接口得到 404;房东返回数据含 age_range 且不含 birth_year;PUT 传 null 会清除字段;没有记录时 GET 返回全 null;替换照片会删除旧对象。
  • OpenAPI 漂移测试无需改动:openapi_drift_test.go 只覆盖 /api/v1/rental 路由。

前端(vitest)

  • 资料表单可以保存、清除字段,并显示服务端字段错误。
  • 相同数据下,预览与房东卡片渲染一致。
  • 房东申请页面在 {} 时显示空资料提示,资料请求失败时仍渲染操作按钮。
  • 提示只在资料为空时显示,关闭后保持关闭。
  • 为新的导航项更新 rentalNavigation.test.ts。

冒烟测试(UAT,GO_ENV=development)

  1. 注册一个租客,填写部分字段并上传照片。
  2. 预约看房。
  3. 以房东身份在看房申请、报价和对话中看到卡片。
  4. 以第二个房东身份确认该接口返回 404。

不在范围内

合作方 API

不开放

通过合作方 / 房东 /v1 API 开放资料。

核验

无

核验任何字段(身份、工作、收入)。

筛选

无

房东按资料字段筛选或排序看房申请。

删除清理

所有租赁数据表

跨租赁数据表的账户删除清理。