租房管理 Rental

面向个人房东、小型公寓运营者与工厂宿舍管理员的租房管理系统：房源、租户、月度抄表账单（水电气费用自动计算）、收款与欠缴跟踪、CSV 导入导出、收费单据打印

v0.1.0

界面预览

功能特性

🏠

房源管理

按小区、楼栋、单元、楼层、房号结构化录入，不同小区允许使用相同房号；可设置默认租金、卫生费、管理费、水电气单价与抄表底数

👥

租户管理

入住与退租登记，宿舍场景支持同一房间登记多名租户；租约到期时间按剩余天数着色提醒，快到期一眼看到

📊

月度抄表账单

一键生成当月账单，本月用量自动衔接上一期读数（无历史则取房间底数）；水、电、气费用按用量 × 单价自动计算

💰

收款与欠缴

支持多次收款累加，是否欠缴与欠缴金额自动判定，列表中以欠缴徽标醒目标注，催收不漏人

🧾

收费单据打印

单据编号、出租方抬头、费用明细与合计一应俱全，浏览器直接打印或另存为 PDF 交给租户

📥

CSV 模板导入导出

提供 Excel 中文无乱码的 CSV 模板下载，账单与房源可导出；导入时自动建小区/房间/租户，同一月份账单自动更新

📱

移动端专属布局

底部导航栏、账单/房源/租户卡片式列表、弹窗自适应窄屏；桌面端保留全字段表格，两端都好用

🧮

金额计算精度

用量与费用统一走 money 规则，分位四舍五入、比较带半分容差；单价优先取账单行内价，其次房间覆盖价，最后全局默认价

🔐

登录与权限

基于 smallgo 框架的登录认证与用户管理，所有查询按用户隔离数据，支持飞牛 fnOS NAS 账号登录

💾

数据备份

SQLite 数据库自动每日 03:00 生成一致性快照，管理员可随时手动备份、下载或删除

🌗

明暗双主题

浅色与深色主题自适应，白天夜间查看账单都清晰

📦

三种部署形态

飞牛 fnOS 应用包一键安装、Docker 镜像部署、裸二进制解压即用，数据都在自己的设备上

技术架构

后端技术栈

Go - 高性能编译型语言
Gin - 轻量级 HTTP 框架
GORM - ORM 框架
SQLite (WAL) - 单文件数据库

前端技术栈

Vue 3 - 现代前端框架
TypeScript - 类型安全
Vite - 构建工具
Pinia - 状态管理
Tailwind CSS - 原子化样式

部署方式

飞牛 NAS（fnOS）FPK 包（x86 / ARM）
Docker 多平台镜像
二进制解压即用

租房管理基于 smallgo 应用框架实例化，与家族应用（bill、reminders、worklog）同构，框架层文件保持同步，业务代码集中在 server/rental/ 与 web/src/views|api。

快速开始

飞牛 NAS 安装

下载对应架构的 techfunway-rental 安装包（.fpk，支持 amd64 / arm64）
打开飞牛 NAS 桌面 → 应用中心
点击右上角 手动安装，选择下载的 .fpk 文件
在安装向导中设置应用端口（默认 8910），点击完成
安装完成后打开应用，首次没有用户时直接创建管理员账号；已有用户可登录并绑定飞牛 NAS 账号

Docker 运行

docker run -d \
  --name techfunway-rental \
  -p 8910:8910 \
  -v rental-data:/app/data \
  -e TZ=Asia/Shanghai \
  --restart unless-stopped \
  techfunways/rental:latest

docker-compose.yaml

services:
  rental:
    image: techfunways/rental:latest
    container_name: techfunway-rental
    restart: unless-stopped
    ports:
      - "8910:8910"
    volumes:
      - rental-data:/app/data
    environment:
      - TZ=Asia/Shanghai

volumes:
  rental-data:

数据库、上传文件与运行日志都存放在数据卷 rental-data（容器内 /app/data），重建或升级容器不会丢失数据。

二进制直接运行

解压对应平台的发布压缩包（内含可执行文件与前端资源）后：

# Linux / macOS
./rental -data-dir ./data -web-dir ./static/dist -port 8910

启动后浏览器访问 http://localhost:8910，首次注册的账号自动成为管理员。业务数据存储于 data/db/rental.db（SQLite，WAL 模式）。

💡 提示：账单金额规则为「用量 = max(0, 本月读数 − 上月读数)，费用 = 用量 × 单价（分位四舍五入）」，本月应付合计 = 租金 + 水电燃气 + 卫生费 + 管理费。删除房源前需先清理其名下账单，账单删除需二次确认，避免误删历史数据。

端口与仓库信息

默认端口 8910（HTTP，安装向导、-port 参数或 PORT 环境变量均可修改）

容器名 techfunway-rental

数据卷 rental-data → 容器内 /app/data（数据库、上传文件、日志）

Docker 镜像 techfunways/rental（多平台，端口 8910）

fnOS 包名 techfunway-rental（桌面显示名「租房管理」）

源码仓库 TechFunWay/rental（Go + Gin + GORM + SQLite / Vue 3 + TypeScript）

运行数据 data/db/rental.db（SQLite WAL），备份快照位于 data/backups/

上游框架 smallgo，可用 ./scripts/check-sync.sh . 检查框架层漂移

常见问题

如何修改端口？

飞牛 NAS 安装时可在向导中设置端口（默认 8910）。Docker 方式通过 -p 参数映射端口。二进制方式通过 -port 参数指定端口。

账单金额是怎么算出来的？

用量 = max(0, 本月读数 − 上月读数)，费用 = 用量 × 单价（分位四舍五入）。单价优先级为：账单行内单价 > 房间覆盖价 > 偏好设置中的全局默认价。生成新账单时「上月读数」自动取上一期账单的「本月读数」，没有历史则取房间底数。

怎么判断某个租户是否欠缴？

应付合计 − 已收金额 > 0 即判定为欠缴，差额就是欠缴额（带半分容差）。多次收款会累加计入已收金额，列表中的欠缴徽标直接显示欠缴状态。

批量导入数据有什么要求？

在应用内下载 CSV 模板（Excel 中文无乱码），按模板填写后导入。单个文件限制 2MB 且仅支持 .csv；导入会自动创建小区、房间与租户，同一月份的账单会更新而不是重复新增。

数据存在哪里，怎么备份？

全部数据保存在数据目录下的 SQLite 数据库（data/db/rental.db）。备份数据目录即可；Docker 与二进制部署都建议持久化该目录，管理员也可在应用内使用备份管理功能生成一致性快照。