给装修师傅用的电子流水账微信小程序。一句话记一笔:去哪家、干了什么、收了多少钱、结清没有。
原生小程序 + 腾讯云开发(CloudBase),零构建、零服务器运维。
项目状态:原型完成,未上线。 为一位木门安装工长辈设计,目标是替掉纸质账本,做到「3 步记一笔」。
装修师傅的账大多记在纸上:一张纸记一天,月底翻着找谁还欠钱。三个真实痛点:
- 挂账容易忘——门店的活月结,干完没记,月底对不上账
- 报价要翻旧账——同一扇门上次收多少,想不起来
- 说不清干过啥——装完出问题,谁的责任扯不清
纸质账本的问题不是记不住,是翻不出来:想查「老李今年一共欠多少」,得把十几张纸翻一遍。
一条活 = 一次上门(一户人家),下挂 1~N 条明细行。列表按天分组,一天一张卡片。
| 概念 | 说明 |
|---|---|
| 活 job | 一次上门 |
| 明细行 item | 如「卧室门 3 套 × 80 元 = 240」 |
| 店名和称呼 | 给谁干的。门店活可挂账,自己接的活当场结清 |
| 套包 package | 一次加多项,如「卧室门一套 = 卧室门 + 门套」。价 = 各单项之和,不能单独定价 |
| 结算 | 自己接的活默认已结清,门店活默认未结清,一键「标记已经给了」 |
| 留痕 media | 照片最多 4 张 + 视频 1 段(≤15 秒)。选完先本地预览,点保存才上传 |
计价方式混合:门按套/扇、窗套阳台套按平米、拆除费按项,每行独立单价。 单位字典固定 5 种:套 / 扇 / 米 / 平米 / 项。
明确不做的:材料用量与成本、其他费用与净得、部分收款、离线模式、微信支付、AI、深色模式、语音输入。
- 前端:微信原生小程序(无框架、无构建),WXML / WXSS / JS
- 后端:腾讯云开发 CloudBase——云函数 + 云数据库(MongoDB 兼容)+ 云存储
- 部署:
tcbCLI(CloudBase CLI)
选云开发而不是自建服务器的原因:免备案域名、免自建鉴权、运维为 0。自建服务器只保留「离线备份」一个角色。
miniprogram/
app.js 云初始化、用户偏好加载、首次灌初始字典
app-config.js ★ 云环境 ID、单位/材质/初始常用项目/套包/结算方式
services/ ★ 所有云函数调用的唯一出口
base.js job.js dict.js stats.js user.js
utils/
date.js 本地时区日期(禁止 toISOString)
terms.js 界面称呼字典(默认「客户」,可改成老板/主家/自己填)
pages/
home 首页
job-edit 记一笔
job-list / job-detail 记录列表 / 详情
stats 统计
debt 待收
profile / dict 我的 / 字典管理
export 导出对账单
privacy 隐私政策
components/number-keyboard 大数字键盘
cloudfunctions/
shared/ ★ 单一源:date.js / validate.js / handler.js / sec-check.js
jobCRUD/ 活:create / update / remove / query / detail / settle / exportStatement
dictCRUD/ 字典四合一:店名和称呼 / 门的种类和价格 / 套包 / 常去的地方
getStats/ overview / byMonth / byCustomer / byItem / byAddress / debt(全走聚合管道)
getUserProfile/ 用户档案与偏好
sendFeedback/ 意见反馈(写库 + 可选邮件)
dailyBackup/ 每日备份到自建服务器(未启用)
scripts/sync-shared.js 把 cloudfunctions/shared/ 同步到各函数目录(--check 供 CI 校验)
docs/ 需求规格、重构评估、UI 原型
server/backup-receiver/ 自建备份接收服务(纯 Node 标准库,零依赖)
git clone https://github.com/study-yang/shifu-ledger.git
cd shifu-ledger仓库里所有账号相关的值都是空的,必须换成你自己的:
| 文件 | 字段 | 填什么 |
|---|---|---|
project.config.json |
appid |
你的小程序 AppID |
miniprogram/app-config.js |
CLOUD_ENV_ID |
你的云开发环境 ID |
cloudbaserc.json |
envId |
同一个环境 ID |
在云开发控制台建 7 个集合:
jobs shops job_templates packages addresses users feedbacks
索引定义写在 cloudbaserc.json 的 database.indexes 里,可照着在控制台手动建,或用 tcb 导入。
# ⚠️ 先装依赖,CLI 不会自动装
for d in cloudfunctions/*/; do
[ -f "$d/package.json" ] && (cd "$d" && npm install --omit=dev)
done
# 再部署
tcb fn deploy jobCRUD -e <你的环境ID> --force用微信开发者工具打开项目根目录(project.config.json 已配好 miniprogramRoot)。
首次启动会自动灌入初始字典(单位、门的种类、套包)。
这些都是踩过坑之后定下来的,改之前先看清代价。
1. 云函数运行环境时区是 UTC,不是北京时间
取业务日期一律用 shared/date.js(内部做了东八区偏移后读 UTC 字段)。
禁止 toISOString(),也禁止直接用 getFullYear() 系列——后者在云函数里读的同样是 UTC,
会让北京时间 0:00–8:00 的记账算到前一天。
2. 价格快照,改字典不影响旧账
jobs.items[] 存的是落库时的完整快照(含 price / amount),套包也展开成明细行后才落库。
字典改价只对新记的活生效。要改旧账,进那一笔点「改这一笔」单独改。
3. shared 单一源,禁止手改副本
cloudfunctions/shared/ 是唯一真身,各函数目录下的 shared/*.js 都是自动生成的副本。
改完跑 node scripts/sync-shared.js,提交前跑 --check(CI 也会拦)。
4. 页面禁止直接调 wx.cloud.callFunction
一律走 services/*,统一处理错误和加载态,换云函数名时只改一处。
5. 留痕有硬上限 照片 4 张 + 视频 1 段。云开发个人版容量只有 3GB,这是成本红线,别放开。
6. 界面称呼不写死
用 terms.js 的字典,别在 WXML 里硬写「客户」——师傅可能管对方叫老板、主家、甲方。
7. 导出对账单只导店家的活
customerType === 'shop' 才进对账单,自己接的私活一行都不能出现。
jobs date/dateKey/monthKey address customerType(shop|owner)
customerName(快照) items[{name,material,qty,unit,price,amount}]
totalIncome settle{settled,settledAt,method}
media[{type,fileID,createdAt}] note createTime/updateTime
shops name/boss/phone/settleCycle(once|monthly)/address/note
stat{jobCount,totalIncome,unpaidAmount}
job_templates name/material/unit/price/useCount
packages name/items[{name,material,qty,unit,price}]/totalPrice/useCount
addresses name/useCount/lastUsedAt
users 用户档案与偏好
feedbacks 反馈内容 + dateKey(每日限额用)
- 云函数响应统一
{ code, data, message },code = 0表示成功 - 前端所有页面只做静态检查(
node --check+ JSON 合法性),真机验证仍需人工过一遍 cloudfunctions/*/config.json进版本管理,但禁止写入任何密钥,SMTP 等凭证走控制台环境变量
MIT © 2026 Zhiyang Liu