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
概要
租客可以填写一份选填的个人资料——照片加上年龄、种族、职业、宠物等十二个字段——房东会在该租客发来的看房申请、报价和消息对话中看到它。所有字段都不是必填的,每个答案都可以清除,而且租客看到的内容与房东看到的完全一致。
目标
马来西亚房东在同意看房前会先了解租客。租客可以在个人资料页填写一份选填资料;房东会在该租客发来的看房申请、报价和消息对话中看到它。
成功标准
- 租客可以填写、修改和清除任意资料字段及照片;没有任何字段是必填的,预约看房也从不依赖资料。
- 房东在确认、还价或拒绝之前,可以看到向其发出看房申请的租客资料(因此也包括由该申请产生的报价和对话),无论申请处于何种状态。
- 其他房东无法读取该资料。
- 租客看到的内容与房东看到的完全一致。
头脑风暴中做出的决定
- 字段范围
- 照片、性别、年龄、种族、国籍、职业、就业类型、入住人数、计划入住时间、是否吸烟、宠物、语言、自我介绍。全部选填。
- 种族
- 在提出歧视/品牌风险后,按产品负责人的决定作为选填字段保留。
- 排除的字段
- 宗教(属于 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 表示“未回答”。
| 字段 | 允许的值 | 说明 |
|---|---|---|
gender | male、female | |
birth_year | 当前年份 − 100 ≤ y ≤ 当前年份 − 18 | 永不发送给房东。 |
race | malay、chinese、indian、bumiputera_sabah_sarawak、others | |
nationality | 两个大写字母(^[A-Z]{2}$);MY = 马来西亚人 | 界面:马来西亚人 / 非马来西亚人 → 从固定的 ISO 3166-1 alpha-2 列表中选择国家;服务端只检查格式。 |
occupation | 去除首尾空白后 1–60 个字符 | 去除空白后为空 → NULL。 |
employment_type | employed、self_employed、student、other | |
occupants | 1–10 | |
move_in_month | 某月的第一天;保存时不得早于当前月份(Asia/Kuala_Lumpur) | 已存的过去日期在读取时仍然有效;只在保存时拒绝。 |
smoker | true / false | false = 明确表示不吸烟。 |
pets | cat、dog、other 的子集,不可重复 | {} = 明确表示“无宠物”;NULL = 未回答。 |
languages | ms、en、zh、ta、yue、other 的非空子集,不可重复 | 空选择 → NULL。 |
about | 去除首尾空白后 1–300 个字符 | 去除空白后为空 → NULL。 |
年龄段
在房东读取时根据 birth_year 和当前年份推算(年龄 = 当前年份 − 出生年份):
18–24 覆盖七年,其余各五年,60+ 不设上限。后端
端口与适配器
port.TenantProfileRepositoryGet(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。 本人 -
DeletePhotoSetPhotoKey(nil),再尽力Remove。 本人 -
GetForOwner通过ViewingRequestRepository.GetByID加载看房申请;若req.OwnerUserID != ownerID则返回port.ErrRequestNotFound;否则加载租客资料并映射为房东视图。 房东
正方形裁剪在上传前于客户端完成;服务端按原样存储字节。
HTTP(受保护路由组,与 /me/offers 相同)
| 方法 | 路径 | 响应 |
|---|---|---|
GET | /me/tenant-profile | tenantProfileSelfJSON(所有字段,包括 birth_year、photo_url;未回答时为 null) |
PUT | /me/tenant-profile | 请求体:所有非照片字段;200 tenantProfileSelfJSON;400 ValidationError{Fields} |
POST | /me/tenant-profile/photo | multipart 字段名 photo(与房产照片相同);200 tenantProfileSelfJSON;400 类型/大小错误;503 ErrMediaUnavailable |
DELETE | /me/tenant-profile/photo | 200 tenantProfileSelfJSON |
GET | /requests/:id/tenant-profile | 200 tenantProfileOwnerJSON;调用者不是该申请的房东或申请不存在时返回 404 |
房东路由挂在现有的 /requests 路由组上(ViewingRequestHandler 的路由,module.go 中的 reqGroup),因此网页路径为 /api/rental/requests/:id/tenant-profile,与前端现有访问看房申请的方式一致。
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。
空资料时显示:“该租客尚未填写资料。”
Mei
25–29 · 华人 · 马来西亚人 · 软件工程师
安静整洁,平日在办公室上班。
TenantProfileCard(full 变体)——同一张卡片也作为租客的“房东看到的内容”预览。租客页面 /tenant/profile
- 在
TENANT_RENTAL_NAVIGATION(rentalNavigation.ts)末尾加入{ id: 'profile', href: '/tenant/profile' }。 - 引导文案:“这里的所有内容都是选填的。你申请看房的房东可以看到你填写的内容。”
- 一个表单,分四组:关于你(照片、性别、出生年份、种族、国籍)、工作(职业、就业类型)、入住计划(入住人数、入住月份、是否吸烟、宠物)、更多(语言、自我介绍)。每个下拉框默认为“未填写”;文本框显示字数;只有一个保存按钮。照片上传/移除立即生效。
- “房东看到的内容”预览用
TenantProfileCard(full)渲染已保存的本人资料,并在 TypeScript 中经过同样的房东视图映射(年龄段使用相同的分档)。 - 服务端返回的 400
fields会高亮对应输入框;已输入的内容会保留。
房东界面
看房申请
fullroutes/landlord/viewings/[id].tsx- 卡片位于
LandlordRequestActions上方
报价
fullroutes/landlord/offers/[id].tsx- 通过报价的
request_id
消息对话
compactInboxView,仅当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)
- 注册一个租客,填写部分字段并上传照片。
- 预约看房。
- 以房东身份在看房申请、报价和对话中看到卡片。
- 以第二个房东身份确认该接口返回 404。
不在范围内
合作方 API
不开放通过合作方 / 房东 /v1 API 开放资料。
核验
无核验任何字段(身份、工作、收入)。
筛选
无房东按资料字段筛选或排序看房申请。
删除清理
所有租赁数据表跨租赁数据表的账户删除清理。