Berth 的「推送收发室」：记着哪台手机、替哪个账户、收哪种推送，以及每条推送有没有发出去、Expo 回执怎么说。
不存钱、不存交易：成交 / 订单 / 仓位的权威在 Hyperliquid（ADR-0083 / ADR-0174），推送只带 templateKey + 安全参数 + 不透明 ID，点开后客户端仍直连 HL；用户与登录设备归 USER_DB。
YYYY-MM-DDTHH:mm:ss.sssZ（TEXT），字符串比较即时间比较。user_id 跨库（USER_DB users.user_id）不设外键；库内外键由 D1 强制执行（本地 SQLite 要显式 PRAGMA foreign_keys = ON）。push_kinds（BERTH-1924）：加一种推送 = 一条 INSERT 迁移，不再重建表；能开通 / 投递的种类 = 代码里有发送逻辑的 ∩ 表里登记的。db.batch([...])，并发下的容量上限靠 push_subscriptions 上的 BEFORE INSERT 触发器原子裁决。revoked_at / disabled_at），不立刻删行；过期数据由 cron maintainNotifications 清理。NOTIFICATIONS_ENABLED=false，连清理都不跑。bot：校验种类在 push_kinds 登记过 → 一个 batch 里 upsert push_devices、撤同种旧订阅、插 push_subscriptionsintent_id 去重写 push_deliveriespush_delivery_tickets 行再调 Expo，记下 ticket；15 分钟后 cron 查回执INSERT INTO push_kinds 登记种类PUSH_KINDS 与发送逻辑；两边都有才可开通 / 投递push_kinds 参照表后，加种类只要一条 INSERT。通用语言（术语定义）以 docs/adr/0174-offline-fill-notices-product-scope-and-authority-boundary.md 为准，这里不重复。
push_kindsPUSH_KINDS / pushKind apps/server/src/routes/notifications/contracts.ts — 代码里有发送逻辑的种类（zod 校验）pushKindRegistry apps/server/src/routes/notifications/pushKinds.ts — 每请求 / 每批次读一次 push_kinds| 订阅与投递的 kind 必须在 push_kinds 里登记 | 数据库 | push_subscriptions.kind / push_deliveries.kind 外键 |
| 开通与 Queue 消费只接受代码已知且库里登记的种类 | 领域代码 | openSubscriptionSchema + pushKindRegistry（subscriptions.ts / delivery.ts） |
push_subscriptions + push_devicesPushDevice / PushSubscription apps/server/src/routes/notifications/contracts.ts — 行类型openSubscription / revokeSubscription apps/server/src/routes/notifications/subscriptions.ts — 开通、换发、撤订| 同一设备 × 账户 × 种类至多一条活跃订阅 | 数据库 | 部分唯一索引 push_subscription_active |
| 一台设备最多替 10 个账户收推送；一个账户最多 10 台未失效设备 | 数据库 | 触发器 push_device_accounts_capacity / push_account_devices_capacity |
| fills 最多 5 个账户（NotificationStream 单条 WS 配额） | 数据库 | 触发器 push_fills_capacity，应用层先给可读拒绝 |
| 同一 Expo token 只属于一个安装；别人的活跃订阅占着时不能接管 | SQL | RELEASABLE_TOKEN_HOLDER（subscriptions.ts） |
| 开通后只认管理凭据，库里只存哈希 | 领域代码 | matchesSecret / hashSecret（security.ts） |
push_deliveries + push_delivery_ticketsPushIntentSchema / PushDelivery apps/server/src/routes/notifications/contracts.ts — 意图契约与行类型acceptPushIntent / deliverPushIntent apps/server/src/routes/notifications/delivery.ts — 去重落库、逐台投递| 同一 intent_id 只落库一次 | 数据库 | push_deliveries.intent_id PK + ON CONFLICT DO NOTHING |
| 同一意图对同一设备至多提交一次（宁缺不重） | 数据库 | push_delivery_tickets PK (intent_id, device_id) + 先占行再调 Expo |
| payload 不含敏感金融数据 | 领域代码 | storedPayload（delivery.ts） |
保证方：数据库 约束 / 索引 / 触发器 SQL 仓储里的条件写 / batch 领域代码 domain 层规则 外部 链上等外部权威
| 操作 | 原子性 | push_deliveries | push_delivery_tickets | push_devices | push_kinds | push_subscriptions |
|---|---|---|---|---|---|---|
| openSubscription apps/server/src/routes/notifications/subscriptions.ts 接管失效 token → upsert 设备 → 撤同种旧订阅 → 插新订阅（触发器裁决容量） | batch | ● | ● | |||
| updateSubscriptionDevice apps/server/src/routes/notifications/subscriptions.ts 换 token / 同步 locale，只认管理凭据 | batch | ● | ||||
| rotate / revokeSubscription apps/server/src/routes/notifications/subscriptions.ts 换发凭据哈希 / 写 revoked_at | single | ● | ||||
| revokeUserDeviceNotifications apps/server/src/routes/notifications/subscriptions.ts 远程退出：结束目标安装上该用户的旧代订阅 | single | ● | ||||
| acceptPushIntent apps/server/src/routes/notifications/delivery.ts Queue 消费：意图去重落库 | single | ● | ||||
| deliverPushIntent apps/server/src/routes/notifications/delivery.ts 逐台占行 → 调 Expo → 记 ticket / 错误；DeviceNotRegistered 停用设备；最后改状态 | single | ● | ● | ● | ||
| collectPushReceipts apps/server/src/routes/notifications/delivery.ts cron 查 Expo 回执，DeviceNotRegistered 停用设备 | single | ● | ● | |||
| maintainNotifications apps/server/src/routes/notifications/delivery.ts cron：补投卡住的意图 + 按保留期清理 | batch | ● | ● | ● |
| 本库字段 | 对应 | 说明 |
|---|---|---|
push_subscriptions.user_id | USER_DB users.user_id | 不同 D1 库，没有外键；开通时验 users 会话 |
push_deliveries.user_id | USER_DB users.user_id | 由 apps/bot / NotificationStream / strategy 投意图时带上 |
push_subscriptions.login_device_id | USER_DB user_login_devices | 投递前核对登录代次仍有效 |
| 表 | 规则 |
|---|---|
push_kinds | 永不删除（只读种子表） |
push_devices | disabled_at 超过 30 天由 cron 删除（级联删其订阅）；token 被接管时删旧行 |
push_subscriptions | revoked_at 超过 7 天由 cron 删除 |
push_deliveries | created_at 超过 7 天由 cron 删除 |
push_delivery_tickets | 随所属意图级联删除 |
| 字段 | 级别 | 说明 |
|---|---|---|
push_subscriptions.management_hash | 机密 | 凭证派生值，只在服务端比对，任何接口都不返回 |
push_devices.expo_token | 机密 | 拿到即可向该手机推送；不出服务端 |
push_deliveries.payload_json | 内部 | 只含模板键与安全参数，设计上不含金融敏感值 |
0003 绿色迁移号表示该字段由后续迁移 ALTER TABLE 加入。点表名展开。
intent_id 是幂等键：Queue 重投 / bot 重试撞同一个键什么都不改。状态机 pending → sent / expired / failed。| 字段 | 类型 | 约束 | 含义 | 迁移 |
|---|---|---|---|---|
| PKintent_id | TEXT | PK | 意图幂等键（生产方生成，如 run-…:0 / strategy:…） | 0001 |
| user_id | TEXT | NOT NULL | 收件账户（跨库无外键） | 0001 |
| FKkind | TEXT | FK→push_kinds.kind · NOT NULL | 推送种类，外键到 push_kinds | 0001 |
| payload_json | TEXT | NOT NULL | 只含 templateKey + 安全参数 + 不透明 ID，不含金额 / 地址等敏感值 | 0001 |
| expires_at | TEXT | NOT NULL | 过期时间；过期未发直接标 expired | 0001 |
| status | TEXT | NOT NULL · DEFAULT 'pending' · CHECK(status IN ('pending','sent','expired','failed')) | pending / sent / expired / failed | 0001 |
| created_at | TEXT | NOT NULL | 落库时间；7 天后连同回执清理 | 0001 |
| attempted_at | TEXT | 最近一次投递尝试时间；回执在其后 15 分钟起查 | 0001 |
| 字段 | 类型 | 约束 | 含义 | 迁移 |
|---|---|---|---|---|
| PKFKintent_id | TEXT | PK · FK→push_deliveries.intent_id ON DELETE CASCADE | 所属意图，级联删除 | 0001 |
| PKdevice_id | TEXT | PK | 目标设备（不设外键：设备被清理后回执仍按意图保留到期） | 0001 |
| expo_ticket_id | TEXT | Expo 受理后回的 ticket；为空 = 已占行未受理 | 0001 | |
| receipt_status | TEXT | CHECK(receipt_status IN ('ok','error')) | ok / error；为空 = 还没查回执 | 0001 |
| receipt_error | TEXT | 错误原因（如 DeviceNotRegistered / receipt_missing） | 0001 | |
| checked_at | TEXT | 回执查询 / 判定时间 | 0001 |
push_subscriptions 上，一台手机可替多个账户收推送。| 字段 | 类型 | 约束 | 含义 | 迁移 |
|---|---|---|---|---|
| PKdevice_id | TEXT | PK | 设备 ID（UUID），服务端生成 | 0001 |
| UQinstallation_id | TEXT | UQ · NOT NULL | App 安装 ID（客户端生成的 UUID）；重装即新安装 | 0001 |
| UQexpo_token | TEXT | UQ · NOT NULL | Expo push token；同一 token 只属于一个安装，换机 / 重装时按规则接管 | 0001 |
| platform | TEXT | NOT NULL · CHECK(platform IN ('ios','android')) | ios / android | 0001 |
| locale | TEXT | NOT NULL | 推送文案语言，随 App 同步 | 0001 |
| disabled_at | TEXT | Expo 判定 DeviceNotRegistered 的时间；非空即不再投递、不占容量名额SQL 注释：Expo DeviceNotRegistered | 0001 | |
| created_at | TEXT | NOT NULL | 创建时间 | 0001 |
| updated_at | TEXT | NOT NULL | 最近一次换 token / 重开通的时间；晚于发送时间的旧回执不再停用设备 | 0001 |
push_subscriptions.kind / push_deliveries.kind 上的 CHECK（BERTH-1924）。只读种子表：由迁移 INSERT，运行时只读不写。登记 ≠ 可用：social / billing 已登记但发送逻辑另票接。| 字段 | 类型 | 约束 | 含义 | 迁移 |
|---|---|---|---|---|
| PKkind | TEXT | PK | 种类键：fills / bot / sign / strategy / social / billing | 0005 |
| description | TEXT | NOT NULL | 这种推送是什么、出自哪张票（给人看） | 0005 |
| created_at | TEXT | NOT NULL | 登记时间 | 0005 |
revoked_at，不删行。| 字段 | 类型 | 约束 | 含义 | 迁移 |
|---|---|---|---|---|
| PKsubscription_id | TEXT | PK | 订阅 ID（UUID），管理接口路径参数 | 0001 |
| FKdevice_id | TEXT | FK→push_devices.device_id ON DELETE CASCADE · NOT NULL | 所在设备 | 0001 |
| user_id | TEXT | NOT NULL | 订阅的账户（USER_DB users.user_id，跨库无外键） | 0001 |
| FKkind | TEXT | FK→push_kinds.kind · NOT NULL | 推送种类，外键到 push_kinds | 0001 |
| management_hash | TEXT | NOT NULL | 管理凭据的 SHA-256；凭据只在开通响应里出现一次 | 0001 |
| created_at | TEXT | NOT NULL | 开通时间；fills 不补开通之前的成交 | 0001 |
| revoked_at | TEXT | 撤订 / 被换发 / 远程退出的时间；非空即失效 | 0001 | |
| login_device_id | TEXT | 开通时的 USER_DB 登录设备 ID，用于判定登录是否仍有效 | 0002 | |
| login_generation | INTEGER | 开通时的登录代次；旧代订阅在重新登录后不会复活 | 0002 |
CREATE TRIGGER push_account_devices_capacity BEFORE INSERT ON push_subscriptions WHEN NEW.revoked_at IS NULL AND NOT EXISTS (SELECT 1 FROM push_subscriptions WHERE revoked_at IS NULL AND user_id=NEW.user_id AND device_id=NEW.device_id) AND (SELECT COUNT(DISTINCT s.device_id) FROM push_subscriptions s JOIN push_devices d ON d.device_id=s.device_id WHERE s.revoked_at IS NULL AND d.disabled_at IS NULL AND s.user_id=NEW.user_id)>=10 BEGIN SELECT RAISE(ABORT, 'push account capacity'); END
CREATE TRIGGER push_device_accounts_capacity BEFORE INSERT ON push_subscriptions WHEN NEW.revoked_at IS NULL AND NOT EXISTS (SELECT 1 FROM push_subscriptions WHERE revoked_at IS NULL AND device_id=NEW.device_id AND user_id=NEW.user_id) AND (SELECT COUNT(DISTINCT user_id) FROM push_subscriptions WHERE revoked_at IS NULL AND device_id=NEW.device_id)>=10 BEGIN SELECT RAISE(ABORT, 'push device capacity'); END
CREATE TRIGGER push_fills_capacity BEFORE INSERT ON push_subscriptions WHEN NEW.revoked_at IS NULL AND NEW.kind='fills' AND NOT EXISTS (SELECT 1 FROM push_subscriptions s JOIN push_devices d ON d.device_id=s.device_id WHERE s.revoked_at IS NULL AND d.disabled_at IS NULL AND s.kind='fills' AND s.user_id=NEW.user_id) AND (SELECT COUNT(DISTINCT s.user_id) FROM push_subscriptions s JOIN push_devices d ON d.device_id=s.device_id WHERE s.revoked_at IS NULL AND d.disabled_at IS NULL AND s.kind='fills')>=5 BEGIN SELECT RAISE(ABORT, 'push fills capacity'); END