# Cents

家庭共享账本 App。

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

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

- [产品边界](docs/产品边界.md)
- [技术方案](docs/技术方案.md)
- [数据与同步](docs/数据与同步.md)
- [账号与权限](docs/账号与权限.md)
- [测试策略](docs/测试策略.md)
- [内网穿透调试](docs/内网穿透调试.md)
- [HTML 原型图](docs/原型图/原型说明.md)
- [评审问题](docs/评审问题.md)

## 本地开发

```bash
npm install
npm run dev
```

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

常用检查：

```bash
npm run typecheck
npm run build
```

## 生产环境启动

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

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

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

```dotenv
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
```

构建并启动生产环境：

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

检查容器状态和日志：

```bash
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`，否则会删除生产数据库卷：

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

## 生产环境添加用户

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

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

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

## 生产数据库备份

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

查看调度和备份日志：

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

立即手动备份一次：

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

备份文件位于宿主机：

```text
./backups/cents-YYYYMMDD-HHMMSS.dump
```