Berth 的「户口本 + 门禁登记处」：记录你是谁（钱包 → 用户）、你在哪些设备上登录（手机 / 网页 / 桌面），以及公开资料、关注和收藏。
不存钱：订单 / 仓位 / 资产 / 交易授权的权威都在 Hyperliquid 链上（ADR-0083）；私钥归 wallet，交易授权归 account。
YYYY-MM-DDTHH:mm:ss.sssZ（TEXT），字符串比较即时间比较。PRAGMA foreign_keys = ON）。db.batch([...]) 保证原子，再用 INSERT … SELECT … WHERE 加条件防并发。ended_at / revoked_at / held_until），不删行；过期数据由 cron（每 5 分钟）maintainUserData 分批清理。berth-users-testnet；mainnet 刻意未绑库（用户接口回 503）。user_login_clock 取号，写一条 login_challengesusers（有就复用）→ 发 user_sessions → 删挑战 → 登记 user_login_devicesPairingSession DO，不进 USER_DBapproveAgentuser_sessions，同名旧会话写上 ended_at + agent_revoked_at，那台电脑被当场踢下线USERNAME_COOLDOWNalice 的 held_until 设为「现在 + 30 天」，变成保留名bob，held_until = NULL 即当前名USERNAME_UNAVAILABLE）session_id。ended_at / revoked_at / held_until：能展示「待撤销设备」，旧设备上线也能知道记录已被改过。db.batch，配合 INSERT … SELECT … WHERE 条件写防并发。version 做 CAS、每次操作留回执，离线回放不会覆盖新状态。extraAgents；库里只记「我们已知它被撤掉了」。通用语言（术语定义）以 contexts/users/CONTEXT.md 为准，这里不重复。
users + username_registryUserProfile / PublicUser contexts/users/src/domain/user.types.ts — 读模型：users ⋈ 当前用户名 + 关注计数UsernameClaim contexts/users/src/domain/userRepository.ts — 一条当前名或保留名userRules contexts/users/src/domain/userRules.ts — 用户名 / 昵称 / 头像规则与期限常量| 一个钱包只对应一个用户，不换绑 | 数据库 | users.wallet_address UNIQUE |
| 钱包地址存小写 0x hex | 数据库 | users.wallet_address CHECK |
| 每人至多一个当前用户名 | 数据库 | 部分唯一索引 username_one_current_per_user |
| 当前名与保留旧名共用一个命名空间 | 数据库 | username_registry.username PK |
| 改名冷却 14 天；旧名保留 30 天 | SQL | claimUsername batch（userTransactions.ts） |
| 保留词（admin / api / berth / official / root / support / system）不可注册 | 领域代码 | isReservedUsername（userRules.ts） |
| 昵称 1–40 个 code point、NFC、无首尾空白与控制字符 | 领域代码 | displayNameViolation（userRules.ts），库里只兜底长度 |
| 没有用户名的用户没有公开主页 | 领域代码 | publicProfile() 抛 USER_NOT_FOUND |
| 用户永不删除（没有删除路径，外键多为 RESTRICT） | SQL | 全仓无 DELETE FROM users |
held_until = 现在 + 30 天）held_until ≤ 现在的行login_challenges + user_login_clockLoginChallenge contexts/users/src/domain/user.types.ts — 服务端视角的挑战siweWalletProof contexts/users/src/infrastructure/auth/siweWalletProof.ts — SIWE 验签| 挑战只能用一次（兑换即删） | SQL | exchangeLogin / consumeChallenge 里的条件 DELETE |
| 挑战 5 分钟过期 | 领域代码 | CHALLENGE_TTL_MS（userRules.ts）+ CHECK expires_at > created_at |
| 验签只认服务端保存的原文 | 领域代码 | login_challenges.message |
| 取号机永远只有一行 | 数据库 | user_login_clock.id CHECK = 1 |
user_sessionsVerifiedSession contexts/users/src/domain/user.types.ts — SessionRpc 验证后给 bot / strategy 的身份DeviceSession / ComputerSessionGrant contexts/users/src/domain/device-sessions/deviceSession.ts — 设备页一行 / 电脑会话签发参数computerAgentCapacity contexts/users/src/domain/device-sessions/agentCapacity.ts — agent 名额预检（下限 3）与默认顶替对象UserSessionRecord contexts/users/src/domain/userSession.ts — 客户端安全存储里的会话记录（不在库里）| token 原文不落库，只存 64 位 hex SHA-256 | 数据库 | token_hash CHECK + userCredentials.ts |
| 会话固定 30 天，没有滑动续期和 refresh token | 领域代码 | SESSION_TTL_MS（userRules.ts） |
有效会话 = expires_at > now 且 ended_at IS NULL | SQL | 所有会话查询的 WHERE |
client 签发后不可改；web / desktop 只能经扫码配对签发 | SQL | 只有 issueComputer 写非 mobile 会话 |
| 同名 agent 的新会话签发时，旧会话被结束并标记已顶替 | SQL | issueComputer batch（deviceSessionRepository.ts） |
agent 是否仍有效不存库，展示时查链上 extraAgents | 外部 | Hyperliquid（ADR-0083） |
endByAgent）或被同名顶替expires_at 延 30 天expires_at；cron 清理（agent 未撤销的电脑会话再留 180 天）user_login_devices + user_session_connectionsLoginDevice / LoginInstallation / DeviceRevocation contexts/users/src/domain/devices/loginDevice.types.ts — 状态由 revoked_at 派生为 active / revoking| 同一用户同一安装只有一条设备记录 | 数据库 | UNIQUE(user_id, installation_id) |
| 同一安装新登录会结束该安装上的旧会话 | SQL | deviceEnrollmentStatements（loginDeviceRepository.ts） |
旧挑战（login_order 更小）不能覆盖较新的设备登记 | SQL | exchangeLogin / 设备登记里的 NOT EXISTS 条件 |
| 撤销只作用于指定 generation | SQL | revoke(userId, deviceId, generation) |
| 撤销的设备要等推送确认且没有活跃租约后才从列表消失 | SQL | 设备列表 PROJECTION |
revoked_at 置空、generation +1user_followsFollowItem / FollowPage / FollowCursor / UserFollowing contexts/users/src/domain/user.types.ts — 列表项、分页与游标| 不能关注自己 | 数据库 | 表级 CHECK follower_id <> followee_id |
| 双方都有当前用户名才能关注 | SQL | setFollowing 的 INSERT … WHERE EXISTS（followQueries.ts） |
| 取消关注 = 物理删除 | SQL | setFollowing(false) |
| 粉丝数 / 关注数实时计算，不落列 | SQL | USER_PROJECTION（userRows.ts） |
user_favorites + user_favorite_operationsUserFavorite / FavoriteChange / FavoriteResult contexts/users/src/domain/favorites/favorites.types.ts — 结果分 applied / converged / conflictfavoriteSyncController contexts/users/src/application/favorites/favoriteSyncController.ts — 客户端离线队列与回放只有 base_version 等于当前 version 时变更才生效（CAS） | SQL | applyFavorite batch（favoriteRepository.ts） |
同一 operation_id 只执行一次，重放返回首次回执 | SQL | user_favorite_operations PK + NOT EXISTS |
| 重放请求与回执内容不一致时报 VALIDATION_ERROR | SQL | applyFavorite 读回执后比对 |
| 取消收藏不删行 | SQL | selected 置 0 |
保证方：数据库 约束 / 索引 / 触发器 SQL 仓储里的条件写 / batch 领域代码 domain 层规则 外部 链上等外部权威
| 操作 | 原子性 | login_challenges | user_favorite_operations | user_favorites | user_follows | user_login_clock | user_login_devices | user_session_connections | user_sessions | username_registry | users |
|---|---|---|---|---|---|---|---|---|---|---|---|
| saveChallenge contexts/users/src/infrastructure/d1/d1UserRepository.ts 取号 +1 后插入挑战 | batch | ● | ● | ||||||||
| exchangeLogin contexts/users/src/infrastructure/d1/userTransactions.ts 建 / 复用用户 → 发会话 → 删挑战 → 登记设备 | batch | ● | ● | ● | ● | ● | |||||
| findSession / findSessionIdentity contexts/users/src/infrastructure/d1/d1UserRepository.ts 顺带写 last_seen_at，1 分钟节流 | batch | ● | ● | ||||||||
| revokeSession / revokeSessions contexts/users/src/infrastructure/d1/d1UserRepository.ts 只写 ended_at | single | ● | |||||||||
| updateProfile contexts/users/src/infrastructure/d1/d1UserRepository.ts 昵称 / 头像 | single | ● | |||||||||
| claimUsername contexts/users/src/infrastructure/d1/userTransactions.ts 回收旧名 → 当前名转保留 → 插入新名 | batch | ● | |||||||||
| setFollowing contexts/users/src/infrastructure/d1/followQueries.ts 关注插入 / 取消删除 | single | ● | |||||||||
| enroll（登记设备） contexts/users/src/infrastructure/d1/devices/loginDeviceRepository.ts 已有会话补登记设备 | batch | ● | ● | ● | |||||||
| revoke（撤销设备） contexts/users/src/infrastructure/d1/devices/loginDeviceRepository.ts 标记撤销并结束该设备全部会话 | batch | ● | ● | ||||||||
| acknowledgeNotifications contexts/users/src/infrastructure/d1/devices/loginDeviceRepository.ts 推送端确认撤销到某一代 | single | ● | |||||||||
| issueComputer contexts/users/src/infrastructure/d1/sessions/deviceSessionRepository.ts 插入电脑会话 + 顶掉同名旧会话 | batch | ● | |||||||||
| renewComputer / end / endByAgent contexts/users/src/infrastructure/d1/sessions/deviceSessionRepository.ts 续期 / 登出 / 链上确认撤销 | single | ● | |||||||||
| consumeChallenge contexts/users/src/infrastructure/d1/sessions/deviceSessionRepository.ts 扫码配对路径一次性消费挑战 | single | ● | |||||||||
| sessionConnections.renew / close contexts/users/src/infrastructure/d1/devices/sessionConnections.ts bot → server RPC 续租 / 关闭 | single | ● | |||||||||
| applyFavorite contexts/users/src/infrastructure/d1/favorites/favoriteRepository.ts 插入或 CAS 更新 + 写回执 | batch | ● | ● | ||||||||
| maintainUserData（cron 每 5 分钟） contexts/users/src/infrastructure/d1/userMaintenance.ts 每类每批最多删 500 行 | batch | ● | ● | ● | ● |
| 本库字段 | 对应 | 说明 |
|---|---|---|
users.user_id | NOTIFICATION_DB push_subscriptions.user_id / push_deliveries.user_id | 不同 D1 库，没有外键 |
users.user_id | apps/bot BotOwner DO 名（getByName(userId)）与 owner.user_id | 每用户一个 DO |
users.user_id | apps/strategy StrategyOwner DO 名 | 每用户一个 DO |
user_login_devices.device_id | NOTIFICATION_DB push_subscriptions.login_device_id（+ login_generation） | 撤销设备时据此撤推送 |
user_sessions.session_id | apps/server PhoneSignInbox / PairingSession DO | 待签请求绑定发起会话；会话结束会作废它的待签请求 |
users.wallet_address | Hyperliquid Master Wallet | 链上公开地址 |
user_sessions.agent_address | Hyperliquid extraAgents | agent 是否有效以链上为准 |
| 表 | 规则 |
|---|---|
users | 永不删除 |
username_registry | 保留名到 held_until 后由 cron 删除；当前名不删 |
login_challenges | 兑换即删；过期的由 cron 删除 |
user_login_clock | 单行，永不删除 |
user_sessions | 结束不删；过期后由 cron 删除，但 agent 未撤销的电脑会话再留 180 天（HL valid_until 上限，期间仍可被顶替） |
user_login_devices | 不删除；随用户级联（用户不删） |
user_session_connections | 关闭即删；lease_expires_at 过后由 cron 删除 |
user_follows | 取消关注即删 |
user_favorites | 不删除（取消 = selected 置 0） |
user_favorite_operations | 不清理（当前无过期策略） |
| 字段 | 级别 | 说明 |
|---|---|---|
user_sessions.token_hash | 机密 | 凭证派生值，只在服务端比对，任何接口都不返回 |
user_sessions.ua | 个人数据 | 只展示给本人设备页 |
user_sessions.ip_geo | 个人数据 | 只展示给本人设备页 |
user_login_devices.installation_id | 个人数据 | 设备标识，不公开 |
users.wallet_address | 个人数据 | 链上公开，但与 Berth 身份关联；只在 /me 返回 |
login_challenges.message | 内部 | 含钱包地址与 nonce，5 分钟内有效 |
user_sessions.agent_address | 公开 | 链上公开 |
users.display_name | 公开 | 公开资料 |
0003 绿色迁移号表示该字段由后续迁移 ALTER TABLE 加入。点表名展开。
| 字段 | 类型 | 约束 | 含义 | 迁移 |
|---|---|---|---|---|
| PKchallenge_id | TEXT | PK | 挑战 ID | 0001 |
| wallet_address | TEXT | NOT NULL · CHECK(length(wallet_address) = 42 AND substr(wallet_address, 1, 2) = '0x' AND substr(wallet_address, 3) NOT GLOB '*[^0-9a-f]*') | 要登录的钱包 | 0001 |
| message | TEXT | NOT NULL | 服务端签发的完整原文；验签只认它，不接受客户端重建 | 0001 |
| created_at | TEXT | NOT NULL | 签发时间 | 0001 |
| expires_at | TEXT | NOT NULL · CHECK(expires_at > created_at) | 过期时间（+5 分钟） | 0001 |
| login_order | INTEGER | NOT NULL · DEFAULT 0 | 从 user_login_clock 取的序号，用来判断登录先后 | 0003 |
operation_id 重放直接返回第一次的结果。| 字段 | 类型 | 约束 | 含义 | 迁移 |
|---|---|---|---|---|
| PKFKuser_id | TEXT | PK · FK→users.user_id | 用户 | 0002 |
| PKoperation_id | TEXT | PK | 客户端生成的操作 ID | 0002 |
| network | TEXT | NOT NULL | 请求的网络 | 0002 |
| market_type | TEXT | NOT NULL | 请求的市场类型 | 0002 |
| market_key | TEXT | NOT NULL | 请求的市场 | 0002 |
| base_version | INTEGER | NOT NULL | 客户端以为的当前版本 | 0002 |
| requested_selected | INTEGER | NOT NULL | 客户端想要的状态 | 0002 |
| selected | INTEGER | NOT NULL | 操作后的实际状态 | 0002 |
| version | INTEGER | NOT NULL | 操作后的实际版本 | 0002 |
| cas_applied | INTEGER | NOT NULL | 1 = applied；0 时按 selected 判 converged / conflict | 0002 |
| created_at | TEXT | NOT NULL | 操作时间 | 0002 |
selected 置 0，行保留，旧设备上线才能识别已发生的更新。| 字段 | 类型 | 约束 | 含义 | 迁移 |
|---|---|---|---|---|
| PKFKuser_id | TEXT | PK · FK→users.user_id | 用户 | 0002 |
| PKnetwork | TEXT | PK · CHECK(network IN ('mainnet','testnet')) | 网络 | 0002 |
| PKmarket_type | TEXT | PK · CHECK(market_type IN ('perps','spot','outcome')) | 市场类型 | 0002 |
| PKmarket_key | TEXT | PK · CHECK(length(market_key) BETWEEN 1 AND 128) | 市场标识（如 coin） | 0002 |
| selected | INTEGER | NOT NULL · CHECK(selected IN (0,1)) | 是否收藏；取消 = 0 | 0002 |
| version | INTEGER | NOT NULL · CHECK(version > 0) | 乐观锁版本，每次生效变更 +1 | 0002 |
| last_operation_id | TEXT | NOT NULL | 最后一次生效的操作 ID | 0002 |
COUNT(*) 现算。| 字段 | 类型 | 约束 | 含义 | 迁移 |
|---|---|---|---|---|
| PKFKfollower_id | TEXT | PK · FK→users.user_id ON DELETE RESTRICT | 关注者 | 0001 |
| PKFKfollowee_id | TEXT | PK · FK→users.user_id ON DELETE RESTRICT | 被关注者 | 0001 |
| created_at | TEXT | NOT NULL | 关注时间，也是分页游标 | 0001 |
login_order 提供单调序号。| 字段 | 类型 | 约束 | 含义 | 迁移 |
|---|---|---|---|---|
| PKid | INTEGER | PK · CHECK(id=1) | 固定为 1 | 0003 |
| ordinal | INTEGER | NOT NULL | 当前序号，初始 0 | 0003 |
generation 是代际号，撤销只作用于指定那一代。| 字段 | 类型 | 约束 | 含义 | 迁移 |
|---|---|---|---|---|
| PKdevice_id | TEXT | PK | 设备记录 ID | 0003 |
| FKuser_id | TEXT | FK→users.user_id ON DELETE CASCADE · NOT NULL | 所属用户（用户删除时级联删） | 0003 |
| installation_id | TEXT | NOT NULL | App 安装 ID | 0003 |
| name | TEXT | NOT NULL | 设备名 | 0003 |
| platform | TEXT | NOT NULL | ios / android（只由应用层约束，库里无 CHECK） | 0003 |
| system | TEXT | NOT NULL | 系统版本 | 0003 |
| generation | INTEGER | NOT NULL · DEFAULT 1 | 代际号：同一安装每次新登录 +1 | 0003 |
| created_at | TEXT | NOT NULL | 首次登记 | 0003 |
| last_seen_at | TEXT | NOT NULL | 最近活跃（按分钟节流写） | 0003 |
| revoked_at | TEXT | 被远程撤销的时刻；同安装重新登录时置回 NULL | 0003 | |
| notifications_revoked_generation | INTEGER | 推送端已确认撤销到哪一代 | 0003 | |
| revoked_through_generation | INTEGER | NOT NULL · DEFAULT 0 | 这一代及更早的登录全部作废 | 0003 |
| login_order | INTEGER | NOT NULL · DEFAULT 0 | 最近一次登记时的登录序号 | 0003 |
| 字段 | 类型 | 约束 | 含义 | 迁移 |
|---|---|---|---|---|
| PKuser_id | TEXT | PK | 用户 | 0004 |
| session_id | TEXT | NOT NULL | 连接所属会话（逻辑引用，无 FK） | 0004 |
| PKconnection_id | TEXT | PK | Bot 侧连接 ID | 0004 |
| device_id | TEXT | 连接所属登录设备 | 0004 | |
| lease_expires_at | TEXT | NOT NULL | 租约到期；每次续约 +30 秒 | 0004 |
ended_at，行留着供「待撤销」展示。| 字段 | 类型 | 约束 | 含义 | 迁移 |
|---|---|---|---|---|
| PKtoken_hash | TEXT | PK · CHECK(length(token_hash) = 64 AND token_hash NOT GLOB '*[^0-9a-f]*') | bearer token（32 字节随机数）的 SHA-256；原文不落库 | 0001 |
| FKuser_id | TEXT | FK→users.user_id ON DELETE RESTRICT · NOT NULL | 会话所属用户 | 0001 |
| created_at | TEXT | NOT NULL | 签发时间 | 0001 |
| expires_at | TEXT | NOT NULL · CHECK(expires_at > created_at) | 到期时间；固定 30 天，电脑续期时延长 | 0001 |
| UQsession_id | TEXT | UQ | 对外暴露的会话引用（token 不外露） | 0003 |
| FKdevice_id | TEXT | FK→user_login_devices.device_id | 手机会话所在的登录设备；电脑会话为 NULL | 0003 |
| login_order | INTEGER | NOT NULL · DEFAULT 0 | 来自挑战的登录序号 | 0003 |
| client | TEXT | NOT NULL · DEFAULT 'mobile' · CHECK(client IN ('mobile','web','desktop')) | 签发端，签发后不可改 | 0005 |
| device_label | TEXT | CHECK(device_label IS NULL OR length(device_label) BETWEEN 1 AND 80) | 设备名（展示用） | 0005 |
| ua | TEXT | CHECK(ua IS NULL OR length(ua) <= 512) | User-Agent（只给本人设备页看） | 0005 |
| ip_geo | TEXT | CHECK(ip_geo IS NULL OR length(ip_geo) <= 120) | IP 粗略地理位置（只给本人设备页看） | 0005 |
| agent_address | TEXT | CHECK(agent_address IS NULL OR (length(agent_address) = 42 AND substr(agent_address, 1, 2) = '0x' AND substr(agent_address, 3) NOT GLOB '*[^0-9a-f]*')) | 电脑设备 agent 的地址；续期会换 | 0005 |
| agent_name | TEXT | CHECK(agent_name IS NULL OR length(agent_name) BETWEEN 1 AND 16) | HL named agent 名 berth-xxxxxx；顶号时沿用旧名 | 0005 |
| last_seen_at | TEXT | 最近活跃（按分钟节流写） | 0005 | |
| ended_at | TEXT | 已登出 / 被结束的时刻；非空即失效 | 0005 | |
| agent_revoked_at | TEXT | agent 已确认从链上撤掉或被同名顶替；为空且已结束 = 待撤销 | 0005 |
held_until IS NULL 是当前名，有值是改名后保留到该时刻的旧名。| 字段 | 类型 | 约束 | 含义 | 迁移 |
|---|---|---|---|---|
| PKusername | TEXT | PK · CHECK(length(username) BETWEEN 3 AND 20 AND username NOT GLOB '*[^a-z0-9]*') | 用户名（存小写） | 0001 |
| FKuser_id | TEXT | FK→users.user_id ON DELETE RESTRICT · NOT NULL | 占用者 | 0001 |
| acquired_at | TEXT | NOT NULL | 取得时间；满 14 天才能再改名 | 0001 |
| held_until | TEXT | CHECK(held_until IS NULL OR held_until > acquired_at) | NULL = 当前名；有值 = 旧名保留到此时（改名时设为 +30 天） | 0001 |
username_registry），避免两个「当前用户名」权威源。| 字段 | 类型 | 约束 | 含义 | 迁移 |
|---|---|---|---|---|
| PKuser_id | TEXT | PK | 稳定用户 ID（UUID），永不变；也是 Bot / Strategy 所有者 DO 的名字 | 0001 |
| UQwallet_address | TEXT | UQ · NOT NULL · CHECK(length(wallet_address) = 42 AND substr(wallet_address, 1, 2) = '0x' AND substr(wallet_address, 3) NOT GLOB '*[^0-9a-f]*') | 登录钱包（小写）；一钱包一用户 | 0001 |
| display_name | TEXT | CHECK(display_name IS NULL OR length(display_name) BETWEEN 1 AND 40) | 公开昵称，可空、可重复；应用层另校验 NFC 与控制字符 | 0001 |
| avatar_id | TEXT | NOT NULL · DEFAULT 'default' · CHECK(avatar_id IN ('default', 'preset_01', 'preset_02', 'preset_03')) | 头像预设；客户端遇到未知值显示 default | 0001 |
| created_at | TEXT | NOT NULL | 创建时间 | 0001 |
| updated_at | TEXT | NOT NULL | 资料最近更新时间 | 0001 |