Skip to content

About

A WeChat Mini Program that helps handicraft workers log jobs, prices and income. Native mini program + WeChat CloudBase.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

师傅账本 · Shifu Ledger

给装修师傅用的电子流水账微信小程序。一句话记一笔:去哪家、干了什么、收了多少钱、结清没有。

原生小程序 + 腾讯云开发(CloudBase),零构建、零服务器运维。

项目状态:原型完成,未上线。 为一位木门安装工长辈设计,目标是替掉纸质账本,做到「3 步记一笔」。


为什么做这个

装修师傅的账大多记在纸上:一张纸记一天,月底翻着找谁还欠钱。三个真实痛点:

  1. 挂账容易忘——门店的活月结,干完没记,月底对不上账
  2. 报价要翻旧账——同一扇门上次收多少,想不起来
  3. 说不清干过啥——装完出问题,谁的责任扯不清

纸质账本的问题不是记不住,是翻不出来:想查「老李今年一共欠多少」,得把十几张纸翻一遍。

核心设计

一条活 = 一次上门(一户人家),下挂 1~N 条明细行。列表按天分组,一天一张卡片。

概念 说明
活 job 一次上门
明细行 item 如「卧室门 3 套 × 80 元 = 240」
店名和称呼 给谁干的。门店活可挂账,自己接的活当场结清
套包 package 一次加多项,如「卧室门一套 = 卧室门 + 门套」。价 = 各单项之和,不能单独定价
结算 自己接的活默认已结清,门店活默认未结清,一键「标记已经给了」
留痕 media 照片最多 4 张 + 视频 1 段(≤15 秒)。选完先本地预览,点保存才上传

计价方式混合:门按套/扇、窗套阳台套按平米、拆除费按项,每行独立单价。 单位字典固定 5 种:套 / 扇 / 米 / 平米 / 项。

明确不做的:材料用量与成本、其他费用与净得、部分收款、离线模式、微信支付、AI、深色模式、语音输入。

技术栈

  • 前端:微信原生小程序(无框架、无构建),WXML / WXSS / JS
  • 后端:腾讯云开发 CloudBase——云函数 + 云数据库(MongoDB 兼容)+ 云存储
  • 部署:tcb CLI(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 标准库,零依赖)

快速开始

1. 克隆并准备

git clone https://github.com/study-yang/shifu-ledger.git
cd shifu-ledger

2. 填三处配置

仓库里所有账号相关的值都是空的,必须换成你自己的:

文件 字段 填什么
project.config.json appid 你的小程序 AppID
miniprogram/app-config.js CLOUD_ENV_ID 你的云开发环境 ID
cloudbaserc.json envId 同一个环境 ID

3. 建数据库

在云开发控制台建 7 个集合:

jobs  shops  job_templates  packages  addresses  users  feedbacks

索引定义写在 cloudbaserc.json 的 database.indexes 里,可照着在控制台手动建,或用 tcb 导入。

4. 部署云函数

# ⚠️ 先装依赖,CLI 不会自动装
for d in cloudfunctions/*/; do
  [ -f "$d/package.json" ] && (cd "$d" && npm install --omit=dev)
done

# 再部署
tcb fn deploy jobCRUD -e <你的环境ID> --force

5. 打开小程序

用微信开发者工具打开项目根目录(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 等凭证走控制台环境变量

License

MIT © 2026 Zhiyang Liu

About

A WeChat Mini Program that helps handicraft workers log jobs, prices and income. Native mini program + WeChat CloudBase.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages