Heart

Heart of Yours

Heart of Yours 健身应用的后端。Dart 服务运行在 AWS Lambda 上，通过 API Gateway 对外提供服务；Postgres 使用 Supabase；CDN 和存储均使用 AWS。

仓库结构

heart-go/
├── api/                       # Dart server (Lambda entrypoint)
├── shared/
│   ├── heart_models/          # Data classes + service interfaces (used by api + the Flutter client)
│   └── heart_aws/             # Boto3-shaped AWS clients (S3, SQS, SNS, Scheduler) on aws_signature_v4
├── database/
│   ├── migrations/            # Forward-only SQL migrations
│   ├── tests/                 # pgtap suite — public/{tables,functions}, archive/...
│   └── test_utils/            # Test helpers (builders + JSON validators)
├── firebase/                  # Python Lambda: FCM push + Firebase auth cleanup (uv workspace member)
├── assets/                    # Python Lambda: exercise media processing pipeline (uv workspace member)
├── infrastructure/            # Terraform stacks (api, assets, cdn, content, firebase, monitoring)
│                              # + environments/{dev,prod} — see infrastructure/README.md
├── content/                   # Exercise library YAML + schema + sample templates JSON, synced to CDN
├── scripts/                   # Migration runner, db test runner, library sync/validation
├── site/                      # Static marketing/legal pages
├── docs/                      # Dated design docs; handoff.md is the definition of done, style.md the house style
├── agents/                    # Autonomous agent launchers + guard hook (see agents/README.md)
└── .github/workflows/         # CI: deploy-api, deploy-assets, deploy-firebase, exercise-library
                               # (each split into a reusable workflow + dev/prod wrappers)

各组件文档：

• api/README.md — 服务架构、路由／数据库／AWS 约定、测试
• database/README.md — 迁移 + pgtap
• infrastructure/README.md — Terraform 技术栈 + 部署

技术栈

层级	技术
服务运行时	Dart 3.10 + relic，编译为原生程序 + Lambda Web Adapter
存储	Postgres（Supabase），无 ORM — 原始 SQL
对象存储／CDN	S3 + CloudFront
身份验证	Firebase OIDC 令牌验证
异步处理	EventBridge S3-rules → SQS → /events（Lambda 将事件路由回自身）
定时任务	EventBridge Scheduler → SQS → /events
辅助服务	uv 工作区中的 Python 3.13 Lambdas：firebase/（推送、清理身份验证数据）、assets/（媒体）
IaC	Terraform（使用 Supabase provider）
CI/CD	GitHub Actions，AWS OIDC 角色
测试	应用代码使用 Dart test + mockito，数据库使用 pgtap，Python 服务使用 pytest

本地开发

make bootstrap   # dart pub get + mocks for all packages, uv sync, git hooks
make db-up       # containerized Postgres 17 + pgtap (skip if you run a native one)
make test        # the full matrix: Dart x3, migrations + pgtap, pytest x3
make lint        # dart analyze x3 + ruff

每个测试套件也可单独运行 — make test-dart / test-db / test-python， 或直接运行底层命令（参见 Makefile 和各组件的 README）。

api 包可在本地连接任意 Postgres + AWS 配置运行 — 参见 api/README.md。

部署

每类工作流都由一个可复用工作流和精简的 -dev / -prod 封装组成。Dev 从 main 推送进行部署。Prod：api 和 exercise-library 从 v* 标签部署；assets 和 firebase 的生产 部署目前需手动触发（workflow_dispatch）。拉取请求只运行测试任务 — 部署任务会根据事件类型进行门控。

deploy-api.yml（api／共享／数据库变更）：

1. Lint、格式检查、分析
2. 对所有三个包运行 Dart 测试
3. 数据库测试：通过 scripts/db_tests.sh 启动临时 Postgres + pgtap，然后运行完整的 api 测试套件 （包括带 db 标签的集成测试），并确保覆盖率达到最低要求
4. 将尚未应用的迁移应用到 Supabase
5. 构建 Lambda 二进制文件、更新函数，并对 /version 进行冒烟测试

deploy-firebase.yml / deploy-assets.yml（Python 变更）：运行 pytest，然后打包并更新 函数代码。

exercise-library.yml（内容变更）：根据 JSON schema 验证资源库 YAML 和同步解析器，然后将练习 + 翻译同步到 Postgres（防止大规模归档）。

约定

• 迁移只允许向前。 不提供降级迁移。若 schema 有误 → 编写新的迁移来修复。
• 除非原因不明显，否则不添加注释 — 命名应说明是什么。
• 每种数据结构只有一个事实来源。 客户端可见的内容都放在 heart_models 中；仅服务端使用的类型留在 api/lib/models。
• 采用 Boto3 风格的 AWS 包 — 通用化，不包含领域知识，放在 heart_aws 中。

许可证

本仓库中的服务及其他所有内容均采用 GNU AGPL v3.0。共享包（shared/heart_models、shared/heart_aws、 shared/heart_design）采用 Apache License 2.0，练习库和 content/ 中的其他内容则采用 CC BY 4.0。 名称和徽标不受上述任何许可证约束。NOTICE 中列出了完整的对应关系，包括仓库中不属于我们的内容。相关原因见 docs/2026-10-24.licence.md。

贡献

贡献内容采用其修改目录对应的许可证（输入 = 输出）：服务采用 AGPL，共享包采用 Apache-2.0，content/ 采用 CC BY 4.0。提交拉取请求即表示你同意这些条款，并确认你有权提供相关作品。我们没有 CLA。