居小易 · 交付说明书

交付物与版本#

本文件是「居小易 · 公寓租赁管理系统」的交付说明书，用于交接、验收与后续运维。所有环境信息均取自交付当日的真实服务器状态，不是模板文字。

交付清单

访问入口#

账号与权限#

权限模型（两层）

• 菜单级：能不能看到这个页面。
• 动作级：能不能点这个按钮（如退款、作废、导出）。
• 前端隐藏只是体验层，后端有硬拦截（requirePerm），手工构造请求同样会被拒。
• 租客账号访问管理端路由会被强制跳回租客首页，不存在越权浏览。

服务器与站点#

IIS 站点与绑定

站点目录结构

D:\juxiaoyi.ezagent.work\
├─ index.html          官网 / 下载页
├─ login.html          PC 登录页
├─ admin\              PC 管理端（index.html / script.js / style.css / jxy-api.js / assets）
├─ app\                房东版网页
├─ t\                  租客版网页
├─ web\                旧 Web 后台
├─ manual\             操作手册（本次新增）
├─ handover\           交付说明书（本次新增）
├─ download\           安卓 APK
├─ qr\                 下载二维码
├─ img\  house-pics\   站点图片、房源图
├─ api\                后端代码 + node_modules + data\yuxiaoer.db
├─ logs\               运行日志
├─ backups\            数据库备份
├─ _b99bak-*\          本次部署前的自动备份
└─ web.config           IIS 规则（HTTPS 强制 + 反代）

web.config 关键规则

守护进程与计划任务#

HTTPS 证书#

功能清单与交付状态#

下表按业务模块列出交付状态。「已交付」＝代码上线且可操作；「需配置」＝功能在，但要填凭据或参数才能用。

本次上线内容（批次 97 / 98）#

新增：付呗 / 乐刷聚合收单

按付呗官方开放平台文档（yuque.com/51fubei/openapi）与乐刷开放平台文档（kancloud.cn/leshuadocs/saas）实现，不是占位。

同时修复的两个真实缺陷

本次实际改动的文件

验收执行记录#

以下检查均在交付当日真实执行，不是勾选表。

开发阶段的自动化验收（本地）

数据现状#

备份策略（本次已修复）#

发现的问题

交付核查时发现：计划任务 JuxiaoyiBackup 每天 03:00 执行的是 D:\backup-web.ps1（另一个项目），不是居小易的数据库备份脚本。

修复方式

• 新建独立计划任务 JuxiaoyiDbBackup，指向 D:\juxiaoyi.ezagent.work\backup-db.ps1。
• 触发：每日 03:30 + 开机时。以 SYSTEM 运行，最高权限。
• 脚本先做 wal_checkpoint(TRUNCATE) 合并 WAL，再复制成 yuxiaoer_YYYYMMDD_HHmmss.db，保留最近 14 份，滚动删除最旧的。
• 已立即手动执行一次：生成 yuxiaoer_20261102_063230.db（1496 KB），校验 integrity ok。
• 原来的 JuxiaoyiBackup 任务保留不动（它还在为另一个项目服务）。

恢复步骤

1. 1停 API
   结束监听 18890 的 node 进程（run-api.ps1 的循环会在 5 秒后自动拉起，所以要先停任务，或停完立刻换库）。更稳妥：Stop-ScheduledTask -TaskName JuxiaoyiApi 后再结束进程。
2. 2备份当前库
   把现在的 yuxiaoer.db 改名留档（如 yuxiaoer.db.before-restore），不要直接覆盖。
3. 3拷回备份
   把 backups\yuxiaoer_<时间戳>.db 复制为 api\data\yuxiaoer.db。
4. 4清理残留 WAL
   删除同目录下的 yuxiaoer.db-wal / yuxiaoer.db-shm，否则会回放旧事务。
5. 5起服务并验证
   启动 JuxiaoyiApi，访问 /api/health，再登录抽查房源数与账单数是否与备份时一致。

建议补充（当前未做）

数据结构概览#

共 71 张表，按用途分组：

启停与重启#

重启后端（最常用）

run-api.ps1 内部是 while(true) 循环：node 退出后 5 秒自动重启。所以结束 node 进程就等于重启。

# 方式一：结束进程，等 5~10 秒自动拉起
$c = Get-NetTCPConnection -LocalPort 18890 -State Listen | Select-Object -First 1
Stop-Process -Id $c.OwningProcess -Force
Start-Sleep -Seconds 10
Invoke-RestMethod http://127.0.0.1:18890/api/health

# 方式二：走计划任务（会停掉守护循环，需要手动再起）
Stop-ScheduledTask  -TaskName JuxiaoyiApi
Start-ScheduledTask -TaskName JuxiaoyiApi

静态文件更新

PC 管理端 / APP 网页版都是纯静态，覆盖文件后刷新即可（必要时 Ctrl+F5）。改完务必同步改缓存戳：index.html 的 style.css?v=、jxy-api.js?v=，以及 jxy-api.js 里的 BUILD，三处必须一致。

日志与排障#

常见故障对照表

发布流程（后续升级用）#

1. 1备份
   把要覆盖的文件复制到 _bNNbak-时间戳\，文件数异常则中止。
2. 2上传到临时目录
   打包成 zip 传到 C:\Windows\Temp\，不要直接传到站点目录 —— 先落文件再执行，避免半截文件被访问。
3. 3解包并覆盖
   覆盖 admin\ 与 api\src\。
4. 4重启 API
   结束 18890 进程，等自动拉起。
5. 5探活 + 业务抽查
   /api/health → 登录 → 抽查房源/账单/合同接口 → 关键页面截图。
6. 6改缓存戳
   三处一致（style.css?v= / jxy-api.js?v= / BUILD）。
7. 7回滚预案
   任何一步失败：把备份目录覆盖回去 + 重启 API，5 分钟内可恢复。

已知限制与待办#

后续建议（按优先级）#

1. 1P0 · 上线前必做
   配置支付凭据并做真单验证；清理演示数据；修改超管口令并建立子账号；给顶级域补 DNS 与证书。
2. 2P0 · 备份加固
   异地备份 + 备份校验 + 连续失败告警。现在只有本机 14 份滚动备份。
3. 3P1 · 提醒通道
   开通短信与微信提醒，让账单到期、催缴、报修进度能主动触达租客 —— 这直接影响回款速度。
4. 4P1 · 数据初始化
   楼栋、仪表单价、账单生成规则、审批流程这四项配齐，系统才算真正「能用」。
5. 5P2 · 合同与网签
   上传合同模板、配置电子签章与签约主体，启用「批量生成正文」与网签。
6. 6P2 · 设备接入
   接智能门锁与水电表，启用自动抄表、远程开门、临时密码 —— 这是省人力最明显的一块。

交付确认#

本说明书所列环境、功能、数据与验收结果，均已在交付当日核对。接收方确认后，运维责任移交。