CASE STUDY / PRODUCT ENGINEERING
CabinFy
01 / PRODUCT SCOPE
为什么需要一个双端住宿产品
CabinFy 同时服务希望发现并预订小木屋的旅客,以及需要管理房源、预订和入住流程的管理员。项目的挑战不只是完成一个房源列表,而是在同一套数据模型上组织两类用户的路由、服务端状态、表单、数据表格和响应式交互,让一个课程原型逐步具备完整产品的结构。
- 在同一套房源与预订数据上组织游客端和管理员端体验
- 使用 React Query 分离服务端状态与本地交互状态
- 通过表单校验、可复用组件和懒加载保持前端可维护性
- 在多语言、暗色模式和不同屏幕尺寸下保持一致的使用体验
02 / BOOKING FLOW
一次预订如何从浏览走到后台处理
- 01
Discover
游客在首页浏览房源,通过筛选、排序和分页获取可用的小木屋列表。
- 02
Decide
房源详情页集中展示图片、描述、价格、位置和评价,用户选择日期与入住人数。
- 03
Calculate
Booking Form 根据入住日期、住宿晚数、人数和早餐选项展示预估价格与预订信息。
- 04
Book
游客完成登录后,前端通过 JWT Cookie 访问受保护的创建预订接口并提交表单。
- 05
Operate
管理员在 Dashboard、Bookings、Cabins 和 Check-in 页面中处理预订、房源和入住状态。
03 / ENGINEERING DECISIONS
代码中真实存在的前端与全栈设计
- 01
用 React Query 管理服务端状态
实现房源、预订、评价和设置分别通过 Query Hook 获取,新增、修改和删除由 Mutation Hook 承担;页面消费统一的加载、错误和更新状态。
价值将服务端数据与本地 UI 状态分离,避免把请求结果、表单输入和弹窗状态耦合到一个全局状态容器中。
- 02
按业务边界组织前端模块
实现features 目录按 authentication、bookings、cabins、check-in-out、dashboard、guests 和 settings 拆分,每个模块组合页面组件、表单和数据 Hook。
价值业务规则和交互入口更容易定位,列表、表单、弹窗和数据请求也能在同一领域内复用。
- 03
隔离游客端与管理端路由
实现React Router 将 /admin/* 与游客端页面分开,管理后台使用独立布局和 ProtectedRoute,游客端则围绕房源浏览、详情和预订组织导航。
价值两类用户拥有不同的信息层级和操作边界,同时保留一套可复用的 API 和领域数据。
- 04
用懒加载和骨架屏处理页面切换
实现Dashboard、Bookings、Cabins、Home 和 Cabin 等页面通过 React.lazy 与 Suspense 按路由加载,并为房源列表和详情页提供专用 Skeleton。
价值减少初始 JavaScript 负担,并用稳定的布局占位降低异步请求带来的空白和跳动。
- 05
让表单校验和基础组件保持一致
实现React Hook Form 管理表单状态,Zod 负责运行时校验,Table、Dialog、Select、Form、Sheet 等组件为游客端和后台提供统一交互基础。
价值减少重复表单逻辑,让房源、预订、登录和设置等不同业务流程拥有一致的错误反馈和交互习惯。
- 06
将多语言、暗色和响应式作为产品能力
实现react-i18next 通过浏览器语言检测和 JSON locale 文件加载中英文文案;Tailwind 响应式样式、DarkModeProvider 和移动端布局共同覆盖不同设备与偏好。
价值国际化和可访问的视觉体验不再是页面完成后的补丁,而是贯穿游客端与管理端的界面基础。
04 / CURRENT BOUNDARIES
后端仍需继续收敛的边界
前端体验和业务流程已经形成清晰骨架,但认证、授权和预订一致性仍需要在下一轮迭代中加强。
- 高优先级
管理接口的后端授权还不统一
前端通过 ProtectedRoute 限制管理页面,但后端部分房源写操作、预订操作和设置更新路由仍缺少统一的认证与 ADMIN 角色校验。下一步应以服务端权限为最终边界。
- 高优先级
预订一致性不能只依赖客户端表单
当前创建预订的核心流程完成了参数校验,但日期重叠、并发预订、服务端重新计算金额和事务级保护仍需要加强,否则高并发下可能出现重复预订或价格被篡改。
- 中优先级
认证方案同时使用 Session 和 JWT
管理员和游客分别使用 Passport Session 与 JWT Cookie。方案可以工作,但 Cookie 安全属性、刷新与撤销、CORS、限流和统一错误响应仍需进一步收敛。
- 中优先级
后端可观测性和自动化测试仍较薄
当前主要依赖 Morgan 和应用日志,没有看到完整的健康检查、指标、链路追踪及覆盖预订冲突、权限和失败恢复的测试体系。
- 中优先级
金额与部署配置还需要更严格的生产约束
金额字段使用 Float,部署配置中也存在环境相关的路径和安全选项。下一步应使用 Decimal、环境变量和显式的生产 Cookie/CORS 配置。
05 / NEXT ITERATION
下一轮应该怎么做
- 01
为房源、预订和设置写操作增加统一认证与 ADMIN 角色中间件
- 02
在服务端重新计算预订金额,并用事务和日期重叠检查保证预订一致性
- 03
统一 Session/JWT 的安全策略,补齐 Secure Cookie、SameSite、CORS 与登录限流
- 04
为核心业务增加 API 集成测试、前端交互测试和端到端预订流程测试
- 05
补充健康检查、结构化日志和基础指标,再评估缓存与异步任务的必要性