# TinyTrail

**Repository Path**: whyCodeData/tiny-trail

## Basic Information

- **Project Name**: TinyTrail
- **Description**: No description available
- **Primary Language**: NodeJS
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-18
- **Last Updated**: 2026-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 时光机 · 成长档案（tiny-trail）

> 以孩子为中心的成长时光机——照片自动织成双刻度时光轴，家人共写，时光隧道里看着孩子长大，十八岁那年整段童年交还给他。

[![Vue 3](https://img.shields.io/badge/Vue-3-4FC08D)](https://vuejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5-3178C6)](https://www.typescriptlang.org/)
[![Cloudflare Workers](https://img.shields.io/badge/Workers-D1%20%2B%20R2-F6821F)](https://workers.cloudflare.com/)

---

## 一、这是什么

一款**亲子场景的成长记录产品**（Web / PWA 先行）。核心情绪动词是**重访（Revisit）**——不是"存照片"，而是"一次次回到那段时光"。

三种角色：

| 角色 | 是谁 | 能做什么 |
|---|---|---|
| 共建者 | 爸爸 / 妈妈 | 导入照片、确认整理结果、写批注、发起分享、互相同步 |
| 围观者 | 爷爷奶奶 / 外公外婆 | **零注册**，点开链接即看，可点赞留语音 |
| 主角 | 孩子 | 时光轴的主角，也是 18 岁那年的收件人 |

已拍板的方向（不轻易推翻）：

1. 主场景 = **给孩子建档**（亲子），不是照片管理工具；
2. **Web 先行（PWA）**，移动端优先，390pt 竖屏基准；
3. 本期**不商业化**，不调用按次付费的生成式 API。

北极星指标：**家庭周重访率 ≥ 40%**。

---

## 二、当前进度

### ✅ 已实现并可用

- **邮箱验证码登录**（无密码 passwordless）+ 登录门禁
- **建档**：孩子昵称 / 生日 / 监护人同意
- **导入照片**：多选、拖拽、EXIF 取时间、缩略图、内容哈希去重、分批导入
- **自动整理成事件**：时间聚类 + 可信度（●◐○）+ 低置信三出口（确认 / 改标题 / 不是一次）
- **时光轴** + **隧道飞行**（GSAP 3D，含 2D / 静态两档降级）
- **事件详情**：批注、封面
- **分享给祖辈**：生成链接 → 免注册只读浏览 → 可点赞 → 可彻底撤销
- **家庭共建**：建家庭 → 邀请另一位家长 → 对方加入 → 家庭管理页
- **家庭钥匙 + 备用钥匙**（建档末步强打断发放，无"重新生成"入口）
- **双端同步**：照片哈希去重、断点续传、弱网静默重试、里程碑确认 / 取消同步

### 🟡 有服务层代码、仍是占位实现（界面上看不到）

- 导出备份（`app/src/services/export/`，标注 M4 落地）
- 重逢引擎（`app/src/services/reunion/`，标注 M3 落地）

### ⬜ 尚未开工

- **备份导出 / 导入**（防"手机丢了记忆没了"，与双端同步是数据安全的两条腿）
- 18 年保存与交付、里程碑候选徽章（误报治理）、真机性能验证
- 生产硬化（邮件服务当前为桩，待接真实通道）与部署上线

---

## 三、目录地图

```
tiny-trail/
├── app/                      # 前端 PWA（Vue 3 + TS + Vite）
│   ├── src/
│   │   ├── engine/           # 隧道引擎（与 UI 框架解耦，可独立复用）
│   │   ├── services/         # 业务服务：整理 / 分享 / 家庭 / 同步 / 媒体
│   │   ├── db/               # Dexie 本地库（照片与元数据的主存储）
│   │   ├── views/            # 页面
│   │   ├── components/       # 组件（含 DatePicker 等通用组件）
│   │   └── styles/           # 设计令牌：tokens / motion / base / a11y
│   └── public/               # 静态资源与 PWA 图标
├── server/                   # 服务端（Cloudflare Workers + D1 + R2）
│   ├── src/handlers/         # auth / family / sync / share / blob / upload / reaction
│   ├── src/ddl.ts            # 建表与旧库自愈（幂等）
│   └── migrations/           # 0001_init / 0002_family_sync
├── docs/                     # 产品文档、技术方案、设计稿、验证报告
├── design/                   # 设计阶段产出（需求、动效系统、评审证据）
├── prototype/                # 可交互单文件原型（双击即开，无需装环境）
└── assets/                   # 绘本插画素材
```

---

## 四、快速开始（本地，无需任何云账号）

前置：Node 18+（推荐 20+）。

```bash
# 1) 服务端：本地模拟 D1 + R2
cd server
npm install
cp .dev.vars.example .dev.vars      # 本地密钥，已在 .gitignore 中，不会入库
npm run dev                          # → http://127.0.0.1:8787

# 2) 前端（另开一个终端）
cd app
npm install
npm run dev                          # → http://localhost:5173
```

界面层已接入 **vue-bits**（DriftWall 照片墙、Aurora、GradientText、DepthCarousel 等）；隧道飞行仍为独立 GSAP 引擎，可在隧道页切换「飞行 / 照片墙」。

首次请求服务端会**幂等建表**，无需手动迁移。

**登录方式**：输入任意邮箱即可，**验证码会直接显示在页面上**（开发期回显，生产环境不会）。之后走建档 → 导入照片 → 看时光轴 → 进隧道。

> 想先不看代码、直接体验交互？双击打开 `prototype/v3-立体书隧道版.html`，单文件原型，无需起服务。

常用命令：

| 位置 | 命令 | 作用 |
|---|---|---|
| app | `npm run dev` / `build` / `preview` / `typecheck` | 开发 / 构建 / 预览 / 类型检查 |
| server | `npm run dev` | 本地 Workers（8787） |
| server | `npm run typecheck` | 类型检查 |
| server | `npm run e2e` | 接口端到端实测 |

---

## 五、架构与数据流

**本地优先（Local-first）**：照片原图默认只存本机 IndexedDB，云端只收**加密后的缩略图密文**与**关系元数据**。

```
父母手机 A  ←── 加密同步 ──→  Cloudflare D1/R2  ──→  父母手机 B
     │                              │
     │  加密缩略图 + 元数据          │
     └──────────── 分享链接 ────────┴──→  祖辈浏览器（零注册只读）
```

两条链路**物理隔离**：

- **共建链路**（父母互相同步）：端到端加密，服务端只看到密文
- **分享链路**（祖辈围观）：只上传加密缩略图，**原图永不上传**

---

## 六、隐私与合规

这是儿童产品，隐私承诺写得很硬：

- ✅ **看不到照片**（端到端加密，服务端只有密文）
- ✅ **看不到孩子的名字和生日**（用家庭钥匙在客户端加密后上云，库层实测 0 行明文）
- ❌ **永远不会说"我们什么都看不到"**——以下仍然可见，隐私说明必须如实列出：
  - 家长邮箱、家庭结构（谁和谁一家、几个孩子）、操作时间戳
  - **分享给长辈的内容**（事件标题 / 月龄 / 日期）

> ⚠️ 部署说明：Cloudflare 仅用于**开发 / 概念测试**。生产环境须迁**境内存储**（腾讯云 COS + Node + PostgreSQL），前端只需切换 API 域名，业务零改动。

---

## 七、文档索引

| 文档 | 说明 |
|---|---|
| **[产品文档](docs/产品文档-时光机成长档案-v1.0.md)** | 定位、角色、用户旅程、功能清单、隐私承诺、路线图 |
| **[UI 设计稿](docs/设计稿-UI设计规格-v1.0.md)** | 设计原则、色彩令牌、组件规格、动效、无障碍 |
| [需求拆解与模块任务清单](docs/需求拆解与模块任务清单-v1.0.md) | 模块划分与实现顺序 |
| [系统架构与模块设计](docs/技术方案-系统架构与模块设计-v1.0.md) | 架构决策与 ADR |
| [家庭协同同步层](docs/技术方案-家庭协同同步层-v1.0.md) | 同步模型、冲突合并、原语接线范围 |
| [家庭共建实现规格](docs/技术方案-家庭共建实现规格-S1-v1.0.md) | 数据表与接口契约（开发唯一事实源） |
| [验证报告 · S1 终验](docs/验证报告-家庭共建-S1-终验-2026-09-18.md) | 独立验证结论（0 未决缺陷） |

设计阶段产出见 `design/`，可交互原型见 `prototype/`。

---

## 八、已知边界

- 真机性能（中端安卓帧率、iOS Safari CSS 3D 表现）**尚未实测**，属已知风险项
- 生产邮件通道为桩实现，上线前需接真实服务
- 备份导出 / 导入尚未实现——**手机丢失场景下的数据安全目前依赖双端同步**