Cents

家庭共享账本 App。

目标是做一个精简、可靠、可离线使用的手机应用，支持 Android 和 iOS。用户在无网络时也能记账，网络恢复后自动同步到家庭共享账本。

当前阶段：产品边界和技术设计。

• 产品边界
• 技术方案
• 数据与同步
• 账号与权限
• 测试策略
• 内网穿透调试
• HTML 原型图
• 评审问题

本地开发

npm install
npm run dev

npm run dev 会同时启动 API 和前端。前端运行在 http://localhost:6064/，并与 compose.dev.yaml 的 frp 调试入口保持一致。

常用检查：

npm run typecheck
npm run build

生产环境启动

在生产环境 clone 目录中更新代码。首次启动时从示例创建 .env；如果已经存在 .env，不要覆盖：

git pull
test -f .env || cp .env.example .env

编辑 .env，确认域名、frp 服务地址和数据库配置正确，并为 POSTGRES_PASSWORD 设置高强度密码：

DOMAIN=cents.homemade.net.cn
APP_VARIANT=pro
FRPC_SERVER_HOST=119.28.12.24
FRPC_SERVER_PORT=7000
TEST_MODE=false
POSTGRES_DB=cents
POSTGRES_USER=cents
POSTGRES_PASSWORD=replace-with-a-strong-password

构建并启动生产环境：

docker compose --env-file .env -f compose.pro.yaml up -d --build

检查容器状态和日志：

docker compose --env-file .env -f compose.pro.yaml ps
docker compose --env-file .env -f compose.pro.yaml logs -f api web frpc cert

后续更新同样执行 git pull 和 up -d --build，数据库卷会保留。停止环境时不要添加 -v，否则会删除生产数据库卷：

docker compose --env-file .env -f compose.pro.yaml down

生产环境添加用户

生产环境通过 Docker Compose 在 API 容器内运行 npm 脚本，宿主机无需安装 Node.js 或 npm：

docker compose --env-file .env -f compose.pro.yaml exec api \
  npm run user:add -- '用户名' '至少8位的密码'

用户与唯一的“个人账本”会在同一个数据库事务内创建。

导入旧版 Excel 账本

backup/import-legacy-excel.sql 是根据 backup/excel 中的百事 AA 记账导出文件生成的可重复执行脚本。它会创建 QHB 和 WHR 用户（新用户的密码为 12345678）、个人账本、5 个共享账本及 252 笔有效流水；其中 EUR 流水会先标记为待换算。金额为 0 的旧记录会被跳过，因为 Cents 不允许保存 0 金额流水。

生产环境执行：

docker compose --env-file .env -f compose.pro.yaml exec -T db \
  psql -U "${POSTGRES_USER:-cents}" -d "${POSTGRES_DB:-cents}" \
  < backup/import-legacy-excel.sql

生产数据库备份

backup 容器每天北京时间 03:00 将 PostgreSQL 备份到生产 clone 目录下的 ./backups。备份采用 PostgreSQL custom format，并在写入后校验；超过 30 天的备份会自动删除。

查看调度和备份日志：

docker compose --env-file .env -f compose.pro.yaml logs -f backup

立即手动备份一次：

docker compose --env-file .env -f compose.pro.yaml exec backup \
  /usr/local/bin/cents-backup run

备份文件位于宿主机：

./backups/cents-YYYYMMDD-HHMMSS.dump