# 小芽成长存折

**Repository Path**: AndrewFengCode/xiaoya-growth-ledger

## Basic Information

- **Project Name**: 小芽成长存折
- **Description**: 面向家庭的儿童成长奖励、储蓄目标与存取管理微信小程序
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-20
- **Last Updated**: 2026-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 小雅成长账本（xiaoya-growth-ledger）

家庭成长银行教育账本：孩子通过家务、学习和成长任务获得家庭奖励，在家长审核下存取和储蓄。
家庭内部虚拟账本，不连接真实银行或支付渠道。

技术栈：Python 3 + Flask 内存数据后端，uni-app(Vue3 + Vite) 前端，H5 本地联调优先，
同时保留微信小程序编译能力。无 Docker / Redis / MySQL / Pandas / NumPy 依赖。

## 目录

- `backend/`：Flask API，`route -> service -> repository`，`MockFamilyBankRepository` 确定性内存数据
- `frontend/`：uni-app Vue3 工程，四个页面（大盘、孩子首页、任务、家长审核）
- `docs/实施计划-20260920.md`：实施计划存档

## 环境要求

- Python 3.9+（在 3.14 验证通过；仅依赖 Flask 2.3.3）
- Node 18+（在 Node 24 + npm 10 验证通过）

## 启动（本地联调）

终端 1 — 后端（127.0.0.1:8080）：

```bash
cd backend
python3 -m venv .venv
./.venv/bin/pip install -r requirements.txt
./scripts/start.sh            # 或 ./.venv/bin/python run.py
curl http://127.0.0.1:8080/health
```

终端 2 — 前端 H5（127.0.0.1:5173，`/api` 已代理到 8080）：

```bash
cd frontend
npm install
npm run dev:h5
# 浏览器打开 http://127.0.0.1:5173/
```

浏览器按下方走查清单点验四页交互。微信小程序端：`npm run build:mp-weixin` 后用微信开发者工具
导入 `frontend/dist/build/mp-weixin`（游客 appid、关闭合法域名校验，直连 127.0.0.1:8080）。

## 自动化验证

```bash
# 后端：12 个契约测试 + 7 个展示层测试
cd backend && ./scripts/check.sh

# 真实 HTTP 全链路（自启后端，34 个断言）
cd backend && ./.venv/bin/python scripts/e2e_http.py

# 前端工具函数单测 + H5/小程序构建
cd frontend && npm test && npm run build:h5
```

当前结果（2026-09-20）：后端 19/19、e2e 34/34、前端 vitest 4/4、H5 与 mp-weixin 构建通过。

## 固定演示数据（2026-09）

- 家庭 F001 林家：C001 豆豆余额 ¥328.50（目标天文望远镜 ¥600，55%），C002 果果 ¥400.00（轮滑鞋 ¥600，67%）
- 家庭总余额 ¥728.50；9 月已确认奖励 +¥166.50、取用 -¥50.00；待审核 3 项
  （T1003 阅读 +¥8、T1004 数学 +¥50、取用 -¥30 买科普书）
- 任务 T1001 整理书桌 ¥5、T1002 洗碗 ¥3 可提交；奖励来源 家务 46% / 学习 42% / 成长 12%
- 演示身份：右上角"家长端/孩子端"标签可切换角色（无登录）；数据内存态，**重启后端即重置**

## 浏览器走查清单

1. 大盘：总额/月奖励/取用/待审核数、6 月双柱趋势、来源分段与占比、两个孩子目标进度。
2. 孩子首页：余额、9 月已赚、目标卡、今日任务金额、最近流水；存入/取用弹窗（金额非法值拦截）。
3. 提交任务 → 余额不立即变化 → 任务进入"等待确认"；重复提交同任务得到 409 友好提示。
4. 切家长端审核：批准 T1001 后余额 +¥5，大盘总额、孩子首页、任务状态同步；"已处理"可见记录。
5. 拒绝任务：余额不变，任务回到"可以完成"，可再次提交。
6. 超额取用：可提交申请但家长批准时 409，余额不变、审核项保持待审核；正常取用批准后扣减。
7. 写操作连续快速点击只生效一次（提交中按钮禁用 + 幂等键）；断网/停后端时有错误提示与重试。

## 业务规则

金额整数分（页面两位小数元）；任务/存取申请先进待审核，批准才动账；拒绝不改余额；
取用批准时重查最新余额，不足返回 409；创建/审核接口必须带 `Idempotency-Key`，同键重放幂等；
审核携带 `version`，过期版本 409；任务同周期防重复领取（被拒绝后可重新提交）；
月度统计时区 Asia/Shanghai。

## 已知边界

- 内存数据、单进程，生产化需换 sqlite 仓储（保持 repository 方法签名即可）。
- 无登录鉴权，身份写死在路径与演示角色中。
- 周挑战为只读派生（本周已批准任务数 / 目标 5 / 鼓励金 ¥5 仅展示，不自动入账）。
- "预计还需 N 周"按月奖励 ÷4 的简单估算；H5 运行态视觉需人工在浏览器确认（自动化无法截图）。