多租户公寓管理SaaS平台-Apartment SaaS

1. 立项背景和目标
长租公寓行业在房源管理、租客签约、租金催收、水电抄表、维修报修等日常运营中
依赖大量纸质台账和Excel表格，数据分散、协同效率低、对账易出错。本项目设计并
实现了一套多租户SaaS公寓管理平台，支持多家公寓公司同时入驻，每个公司数据完全
隔离，通过管理后台（PC端）和租客小程序（移动端）双端协同，覆盖"房源录入→客户
跟进→合同签署→租金收取→水电计费→维修派单→数据报表"全链路业务流程。

2. 核心功能模块
系统包含8大业务模块：房源管理（房源CRUD、Excel批量导入、房源统计看板）、客户CRM
（客户信息、跟进记录、意向等级、黑名单标记）、合同全生命周期（模板管理、电子
签署状态机、PDF合同生成、在线签约）、租金账单（合同签约自动生成全期账单、
滞纳金引擎、支付记录）、水电表管理（水/电/气三表、抄表录入、用量自动计费）、
维修工单（报修→派单→施工→完工→评价五步流转）、数据报表（入住率/月收入/
逾期统计/6个月趋势图）、消息通知（到期提醒、逾期告警、待签通知自动推送）。

3. 业务流程描述
管理员创建房源（支持Excel批量导入）→添加客户并跟进→选择合同模板创建租赁合同→
推送租客小程序电子签署→系统自动生成全期租金账单→每月到期自动提醒→逾期触发
滞纳金计算（宽限期+日1%复利+超期自动终止合同）→水电抄表自动出账→租客小程序
缴费/报修/查合同→管理员查看Dashboard统计报表。

1. 整体架构和设计思路
采用前后端分离的三端架构。后端使用Python 3.11 + FastAPI异步框架，SQLAlchemy 2.0
异步ORM操作PostgreSQL 15数据库，通过TenantMiddleware中间件实现多租户数据隔离
（JWT解码→注入company_id→所有查询自动限定租户范围）。Celery + Redis实现异步
任务队列（定时账单生成、合同到期提醒、逾期自动终止）。前端管理后台采用Vue 3.5 +
Vite 6 + TypeScript + Element Plus + ECharts构建SPA；租客端采用Vue 3 + Vant 4
移动端适配，支持UniApp结构。16个API Router、13个数据库模型、11个Service业务
模块。Docker Compose编排6个容器（数据库、缓存、后端、Worker、定时任务、Nginx
反向代理）一键部署。
2. "我"的负责模块和结果
独立负责全栈开发（后端API设计+前端双端开发+数据库建模+容器化部署）。完成8大
业务模块的全栈实现，设计16个RESTful API路由组覆盖公开接口/平台管理/公司管理/
租客服务四种权限域。实现6种用户角色（平台管理员/公司管理员/员工/财务/维修/租客）
的RBAC鉴权体系。合同签署状态机支持4态流转（draft→pending_tenant→
pending_company→signed + terminated）。滞纳金引擎实现可配置宽限期+日费率
复利+超期自动终止。Excel批量导入支持中英文表头自动映射。合同PDF生成集成fpdf2
中文字体方案。
3. 遇到的难点和解决方案
- 多租户数据隔离：传统方案需要每个租户独立数据库，成本高。通过TenantMiddleware
在请求层解码JWT注入company_id，Service层所有查询自动追加租户过滤条件，实现
逻辑隔离的单库多租户方案，兼顾安全性和查询性能。
- 合同签署状态机一致性：合同涉及双方签署操作（租客审批→公司确认），需要防止
并发下的状态跳跃。在contract_service中实现严格的状态转换校验函数，每次状态
变更前校验当前状态是否为合法前置状态，配合数据库行级锁保证原子性。
- 全期账单自动生成：合同签约时需根据付款周期（月/季/半年/年）自动生成整个租赁
期的账单序列。设计generate_contract_bills算法，从起始日期按周期滚动计算每期
起止日期和金额，处理末尾不足一个完整周期的边界情况。
- Excel导入中英文表头自动映射：不同用户上传的Excel表头格式不一（中文/英文/
混合），设计双语言映射表（如"房间号"↔"room_code"），先尝试精确匹配再模糊
匹配，校验返回