# DayTrace

**Repository Path**: tooka/DayTrace

## Basic Information

- **Project Name**: DayTrace
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: feat/daytrace-time-river-mvp
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-05
- **Last Updated**: 2026-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">
  <img src="docs/assets/daytrace-avatar.svg" width="128" height="128" alt="DayTrace 日晷标志">
  <h1>DayTrace</h1>
  <p>记录每天做了什么，看见时间流向，建立属于自己的时间档案。</p>
</div>

DayTrace 是一款私密的原生微信小程序。它帮助用户快速记录真实发生过的活动，
通过一天的时间河流、日历回看和保守的月度统计，逐渐形成可追溯的个人时间档案。

项目坚持三个原则：

- **记录事实，不评价生活。** 未记录时间只是空白，不是失败、待办或完成率。
- **宁可不给结论，也不制造结论。** 月度数据不足或覆盖度差异过大时，不展示增减判断。
- **数据属于用户。** 所有云数据按可信微信身份隔离，并支持恢复、导出和可验证删除。

## 功能

### 今天

- 一句话快速记录，输入过程中自动保存本地草稿
- 原生时间选择、分类、描述与时间重叠校验
- 完整覆盖 00:00–24:00 的时间河流
- 已记录时长、未记录时长、条目数与分类占比
- 已记录片段可查看，空白片段可直接补记
- 离线 outbox、幂等重试和待同步状态

### 回看

- 月历切换与历史日期回看
- 今日、已记录、未记录、未来日期的无障碍状态
- 所选日期的记录时长和条目概览
- 从过去空白日期进入补记

### 统计

- 月度已记录时长、有记录天数和日均时长
- 按已记录时长计算分类占比
- 分类统计下钻到构成数字的源记录
- 进行中月份只与上月等长区间比较
- 仅在两段数据均至少有 7 个记录日，且记录量差异不超过 30% 时给出比较结论

### 我的

- 分类新增、重命名、颜色、排序、归档与恢复
- 同一微信身份的跨设备云数据恢复
- 版本化 JSON 数据导出
- 可恢复、可核验的全量在线数据删除
- 删除后 generation 栅栏阻止旧设备重新写回历史数据

## 不做什么

当前版本不包含提醒、AI、日程规划、长日记、社交、广告、支付或位置能力。
DayTrace 记录已经发生的生活，不替用户安排未来。

## 技术架构

```text
微信小程序页面
  ├─ domain/     纯函数、时间区间、统计、导出格式
  ├─ state/      页面状态、缓存、恢复与错误降级
  └─ services/   本地存储、云 API、同步、导出与删除
          │
          ▼
可信 CloudBase 云函数 API
  ├─ 微信上下文解析 owner，忽略客户端伪造身份
  ├─ generation 栅栏阻止删除后旧写入复活
  ├─ 日锁文档 + 事务保证同一天时间段不重叠
  ├─ export lease 保证导出快照一致
  └─ deletion state machine 完成全访问封锁与可恢复清理
          │
          ▼
CloudBase 经典文档数据库 + 临时文件存储
```

### 已冻结的关键决策

- [持久化后端：CloudBase 经典文档数据库](docs/decisions/0001-persistence-backend-document-database.md)
- [写路径并发：日锁文档 + 事务](docs/decisions/0002-write-path-concurrency-model.md)
- 跨进程操作名由共享定义维护，真实 API 闸门仍手写字面量作为外部观察者
- 派生统计读时计算，不持久化第二份可能漂移的事实

## 项目结构

```text
DayTrace/
├─ miniprogram/                 小程序生产代码
│  ├─ pages/                    今天、记录、回看、统计、我的
│  ├─ components/               时间河流、摘要、编辑器、统计组件
│  ├─ domain/                   跨端纯领域逻辑
│  ├─ state/                    客户端状态层
│  └─ services/                 本地存储、云 API、同步与隐私能力
├─ services/                    TypeScript 云函数源代码
├─ cloudfunctions/              微信云函数部署入口/构建产物目录
├─ scripts/                     部署、真实云闸门、发布治理
├─ tests/                       单元、组件、工具链测试
├─ docs/
│  ├─ decisions/               架构决策
│  ├─ specs/                   数据契约和机器证据
│  ├─ runbooks/                部署、删除、备份与回滚手册
│  └─ release/                 发布清单、隐私、无障碍与提审材料
└─ .trellis/                    项目规范与任务归档
```

## 本地开发

### 环境要求

- Node.js 24
- npm 11
- 微信开发者工具 Stable
- 已开通的微信小程序 AppID
- 已绑定的 CloudBase 传统模式环境

### 安装

```powershell
git clone https://gitee.com/tooka/DayTrace.git
Set-Location DayTrace
git switch feat/daytrace-time-river-mvp
npm install
```

使用微信开发者工具导入仓库根目录。若用于自己的小程序，需要修改：

1. `project.config.json` 中的 `appid`
2. `miniprogram/config/cloud-env.ts` 中的 CloudBase 环境 ID
3. 脚本运行时的 `DAYTRACE_ENV_ID`

不要提交上传私钥、云登录态、临时下载能力或任何用户数据。仓库已忽略常见密钥文件，
但秘密仍应放在仓库外部。

### 初始化云环境

```powershell
$env:DAYTRACE_ENV_ID="<你的 CloudBase 环境 ID>"

npm run provision:collections
npm run deploy:functions
npm run gate:persistence
npm run gate:api
```

集合权限和索引需要按
[控制台配置清单](docs/runbooks/backend-console-release-blockers.md)人工配置并独立复核。

全量删除还要求为 `daytrace-api` 云函数配置真实的备份保留期：

```text
DAYTRACE_BACKUP_RETENTION_DAYS=<控制台实际显示的整数天数>
```

不得根据套餐或文档示例猜测该值。

## 质量验证

### 基础检查

```powershell
npm run typecheck
npm test
npm run scan:secrets
```

### 真实云与页面检查

运行前需在微信开发者工具中开启“服务端口”。

```powershell
npm run gate:persistence
npm run gate:api
npm run check:runtime-management
npm run check:record
npm run check:timeline
npm run check:stats
npm run check:categories
npm run check:restore-export
npm run check:delete
```

端到端脚本使用专用日期或 synthetic owner，并在前后清理夹具；删除检查不会删除
开发者工具当前登录的主账号。

### 测试策略

| 层级 | 主要验证 |
|---|---|
| 单元测试 | 领域不变量、状态机、外部响应解码 |
| 组件测试 | 数据投影、事件与交互状态 |
| WXML 无障碍 | 可识别名称、错误播报、焦点顺序 |
| API 闸门 | 真实身份、owner 隔离、幂等、并发、导出与删除 |
| 持久化闸门 | 集合、事务、日锁和运行时能力 |
| 页面 E2E | 各层接线、真实落云、密集布局几何 |

关键测试均要求通过变异证明它们真的会失败，相关纪律见
[测试有效性规范](.trellis/spec/testing/index.md)。

## 发布

```powershell
npm run gate:release
```

退出码：

- `0`：自动门禁与人工证据均满足，可进入上传
- `2`：自动门禁通过，但仍有人工或生产环境 blocker
- `1`：执行或一致性检查失败

Preview 和上传默认都是 dry-run：

```powershell
npm run release:preview
npm run release:upload
```

真实执行需要仓库外部私钥、匹配的 AppID、干净且与证据一致的提交，以及精确的
版本确认词。详细规则见 [发布说明](docs/release/README.md)。

当前机器发布状态以
[release-evidence.json](docs/release/release-evidence.json) 为准。自动检查通过不代表
已经完成真实设备、读屏、微信控制台、备案、生产 smoke 或 24 小时观察。

## 隐私与数据安全

- 不请求手机号、位置、头像、昵称、相册或系统日历权限
- owner 只取自可信微信云函数上下文
- 跨用户访问返回不可区分的 not-found 语义
- 导出对象和临时下载能力视为 bearer secret，不写入日志
- 在线删除完成前不会显示成功
- 平台备份按生产控制台实际保留策略自然过期，不用于分析或正常恢复

详见：

- [隐私数据清单](docs/release/privacy-data-inventory.md)
- [数据删除手册](docs/runbooks/data-deletion.md)
- [备份保留说明](docs/runbooks/backup-retention.md)
- [秘密矩阵](docs/release/secret-matrix.md)

## 当前状态

Phase 1 的产品功能、恢复/导出、全量删除和发布自动化已经实现。
仓库当前**不等于已可发布**：权限/索引独立复核、真实设备与读屏、微信隐私声明、
服务类目、备案材料、生产部署证据、Preview artifact、production smoke 和 24 小时观察
仍由机器发布证据作为 blocker 管理。

## 文档入口

- [权威实施计划](docs/plans/2026-08-03-001-feat-daytrace-time-river-mvp-plan.md)
- [数据模型](docs/specs/data-model.md)
- [短语解析契约](docs/specs/phrase-entry-parsing.md)
- [后端部署手册](docs/runbooks/backend-deployment.md)
- [回滚矩阵](docs/runbooks/backend-rollback-matrix.md)
- [发布检查清单](docs/release/release-checklist.md)
- [提审文案草案](docs/release/submission-copy.md)

## 许可证

当前仓库未声明开源许可证。除非仓库所有者另行授权，代码默认保留全部权利。