第三方集成参考TigerTag Firebase Integration

客户端如何连接 TigerTag

每个客户端都遵循相同的四个步骤：获取公开的 Firebase 配置，以用户身份登录，使用用户的令牌调用 Firestore REST API，并保持该令牌有效。

1. 1

   获取公开配置

   一次 GET 请求即可返回 Firebase 项目配置。apiKey 本来就是公开的：它标识的是项目，而不是调用方。请缓存它，每周刷新一次即可。

   01-firebase-config.md
2. 2

   以用户身份登录

   用户自己的邮箱和密码会返回一个 UID、一个有效期 1 小时的 idToken 和一个 refreshToken。Google Sign-In 需要浏览器，因此无界面客户端使用密码登录。

   02-authentication.md
3. 3

   读写 Firestore

   将 idToken 作为 Bearer 令牌发送。线材卷位于 users/{uid}/inventory，料架位于 users/{uid}/racks；重量为净重（克），日期为 Unix 毫秒时间戳。

   03-data-model.md
4. 4

   保持令牌有效

   在一小时到期前刷新 idToken，并替换已保存的两个令牌。遇到 permission-denied 时，刷新一次并重试一次读取。

   刷新 idToken

GET  https://tigertag-cdn.web.app/__/firebase/init.json

POST https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key={apiKey}
     { "email": "user@example.com", "password": "…", "returnSecureToken": true }

GET  https://firestore.googleapis.com/v1/projects/{projectId}/databases/(default)/documents/users/{uid}/inventory
     Authorization: Bearer {idToken}

本仓库中记录的集成

docs/clients 中的每份指南都涵盖身份验证、读取或写入的数据、字段映射和代码。以下代码片段摘自这些指南。

{
  "domain": "tigertag",
  "name":   "TigerTag",
  "version": "0.1.0",
  "requirements": ["pyrebase4>=4.5.0"],
  "config_flow": true,
  "iot_class": "cloud_polling"
}

weight_available = max(0, measured_raw_weight - container_weight)

pip install -r requirements.txt
python tigertag_client.py

pip install -r requirements.txt
export TIGERTAG_EMAIL=you@example.com
export TIGERTAG_PASSWORD=yourpassword
export SPOOLMAN_URL=http://192.168.1.10:7912
export DRY_RUN=1                    # dry-run mode
python3 sync.py

users/{uid}/scales/{mac}          ← heartbeat, every 30 s
users/{uid}/inventory/{spoolId}   ← weight_available + last_update

要为其他平台开发？新指南放在 docs/clients 中，可选的可运行示例放在 examples/ 中。 CONTRIBUTING.md

用户的账户，用户的规则

没有需要保护的共享密钥，也没有可能泄露的主令牌：客户端能做的恰好就是其用户能做的，并由 Firestore 在服务器端强制执行。

面向集成者的公开契约

本仓库被视为一份公开契约：影响客户端的变更会在同一版本中同步到本仓库，更新日志将每项变更记录为 Added、Changed、Deprecated、Removed、Fixed 或 Security。

README 中的稳定性保证CHANGELOG.md

参考文档

每个集成所依赖的核心文档，按客户端需要的顺序排列。

• 01-firebase-config.md公开的 Firebase 配置端点、每个字段的用途，以及缓存时长。
• 02-authentication.md邮箱和密码登录、令牌刷新，以及 permission-denied 重试模式。
• 03-data-model.md每个 Firestore 集合和字段：库存、料架、好友、个人资料、电子秤。
• 04-friend-system.md好友访问的工作原理：公开代码、私有密钥、双向纽带。
• 05-rate-limiting.md轮询间隔、查询限制、监控，以及为何未强制启用 App Check。
• rules/firestore.rules已部署的 Firestore Security Rules 的公开副本。

TigerTag 生态的一部分

本指南涵盖云端账户。芯片、应用和 SDK 各有自己的代码仓库。

常见问题