时间统一存服务端生成的 ISO 字符串 YYYY-MM-DDTHH:mm:ss.sssZ（TEXT），字符串比较即时间比较。
钱包 / agent 地址一律小写 hex，由 CHECK 强制；EIP-55 大小写只用于展示。
外键由 D1 强制执行（本地 SQLite 要显式 PRAGMA foreign_keys = ON）。
D1 没有交互式事务：多步写操作放进一个 db.batch([...]) 保证原子，再用 INSERT … SELECT … WHERE 加条件防并发。
「结束」多用时间戳标记（ended_at / revoked_at / held_until），不删行；过期数据由 cron（每 5 分钟）maintainUserData 分批清理。
testnet 绑 berth-users-testnet；mainnet 刻意未绑库（用户接口回 503）。

业务流程跟着流程看表怎么变

📱 第一次用手机钱包登录

App 请求登录 → 服务端在 user_login_clock 取号，写一条 login_challenges
原文由服务端保存，验签不接受客户端自己拼的版本
用户用钱包签名，App 把签名交回来
一个 batch 里一次做完：没有这个钱包就建 users（有就复用）→ 发 user_sessions → 删挑战 → 登记 user_login_devices
要么全成功，要么全不做；同一安装上的旧会话被结束
App 拿到 token（库里只有它的 SHA-256），30 天后到期需重新登录

💻 电脑扫码登录，agent 名额满了要顶掉一台

电脑出二维码 → 已登录的手机扫码确认
配对过程在 PairingSession DO，不进 USER_DB
电脑在本机生成一把 HL agent，手机签 approveAgent
HL 每账户 named agent 名额已知下限是 3；满了默认顶掉最久没活跃的那台电脑，沿用它的 agent 名，同名重批即注销旧 agent
插入新的 user_sessions，同名旧会话写上 ended_at + agent_revoked_at，那台电脑被当场踢下线
到期前 7 天起可续期：换新 agent、手机签一次，会话再延 30 天

🏷️ 把用户名从 alice 改成 bob

检查冷却：当前名用满 14 天了吗？没满 → USERNAME_COOLDOWN
alice 的 held_until 设为「现在 + 30 天」，变成保留名
插入 bob，held_until = NULL 即当前名
bob 已被占用 → 整笔回滚，alice 不变（USERNAME_UNAVAILABLE）
30 天后 cron 删掉 alice，别人才能注册这个名字

设计要点

🔐 token 只存哈希库泄露也拿不到能用的凭证。对外只暴露 session_id。

🕰️ 不删行，用时间戳标状态ended_at / revoked_at / held_until：能展示「待撤销设备」，旧设备上线也能知道记录已被改过。

⚛️ batch 代替事务D1 没有交互式事务；多步写放进一个 db.batch，配合 INSERT … SELECT … WHERE 条件写防并发。

🔢 版本号 + 回执 = 多端同步收藏用 version 做 CAS、每次操作留回执，离线回放不会覆盖新状态。

🎫 login_order 排先后同一安装并发登录或旧挑战晚到，都不能覆盖较新的设备登记。

⛓️ 链上状态不复制agent 是否有效实时查 HL extraAgents；库里只记「我们已知它被撤掉了」。

社交资料扩展外链账号 / 偏好暂无运行时写接口。PublicUserCard 只经 users /server 批量发布，注销时隐藏公开资料。社交图归 SOCIAL_DB，USER_DB 旧关注表待迁出后删表。

聚合每张表恰好属于一个聚合；kind=supporting 是辅助表

通用语言（术语定义）以 contexts/users/CONTEXT.md 为准，这里不重复。

User

聚合根 users + username_registry + user_external_accounts + user_settings

用户身份与公开资料。用户名是 User 的一部分，但单独成表以支持「保留旧名」。

领域对象

UserProfile / 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`
外链 provider 与用户组成唯一键；社交偏好封闭枚举有效	数据库	user_external_accounts / user_settings PK、FK、CHECK
已注销用户公开卡片隐藏资料	领域代码	publicUserCard
改预设头像同语句写 avatar_kind='preset' 与 avatar_key	SQL	d1UserRepository.updateProfile
既有资料读不返回墓碑用户，关注列表过滤墓碑，新关注同语句检查双方未注销	SQL	d1UserRepository.findUser / followQueries.listFollows / setFollowing

生命周期 · 用户名

当前保留中已释放

当前→保留中改名（held_until = 现在 + 30 天）
保留中→当前本人冷却期满后改回旧名
保留中→已释放cron 删除 held_until ≤ 现在的行

Login

辅助根 login_challenges + user_login_clock

钱包签名登录的一次性挑战与全局取号。不是业务实体，只服务于「兑换会话」这一步。

领域对象

LoginChallenge 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

Session

聚合根 user_sessions

设备会话（门禁卡）。会话失效与交易授权撤销是两条独立的生命周期；agent 是否仍有效以链上为准。

领域对象

VerifiedSession 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）

生命周期 · 会话

有效已结束待撤销agent 已撤销已过期

有效→已结束登出 / 设备被撤销 / 同安装重新登录
已结束→待撤销电脑会话：agent 还挂在链上
待撤销→agent 已撤销手机撤销后链上确认 missing（endByAgent）或被同名顶替
有效→有效电脑续期：换 agent，expires_at 延 30 天
有效→已过期到达 expires_at；cron 清理（agent 未撤销的电脑会话再留 180 天）

LoginDevice

聚合根 user_login_devices + user_session_connections

手机端「用户 × 安装」的登录记录，以及判定设备是否真的断开所需的连接租约。

领域对象

LoginDevice / 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

生命周期 · 登录设备

activerevoking不再显示

active→revoking远程撤销（同时结束该设备全部会话）
revoking→不再显示推送确认撤销到该代，且没有活跃连接租约
revoking→active同一安装重新登录：revoked_at 置空、generation +1

Follow

聚合根 user_follows

有方向的关注关系；粉丝列表和关注列表分别成立。

领域对象

FollowItem / 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）

Favorite

聚合根 user_favorites + user_favorite_operations

多设备同步的收藏：版本号做 CAS，操作回执做幂等。

领域对象

UserFavorite / FavoriteChange / FavoriteResult contexts/users/src/domain/favorites/favorites.types.ts — 结果分 applied / converged / conflict
favoriteSyncController 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 昵称 / 头像；改预设头像时同语句写 avatar_kind='preset' 与 avatar_key。	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_external_accounts`	随用户资料保留；注销跨存储清理归 BERTH-1925，本票只建立 schema。
`user_settings`	随用户资料保留；注销跨存储清理归 BERTH-1925，本票只建立 schema。

敏感度未列出的字段视为「内部」

字段	级别	说明
`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`	公开	公开资料

全部字段1 个迁移叠加后的最终结构 · 由迁移自动提取

0003 绿色迁移号表示该字段由后续迁移 ALTER TABLE 加入。点表名展开。

login_challenges登录挑战（SIWE）6 字段 · 1 索引

服务端签发的待签文本，钱包签名后用来兑换会话。5 分钟有效，兑换即删，只能用一次。

聚合 Login · 主键 (challenge_id) · 引入于 0001

字段	类型	约束	含义	迁移
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
login_order	INTEGER	NOT NULL · DEFAULT 0	从 `user_login_clock` 取的序号，用来判断登录先后	0001
created_at	TEXT	NOT NULL	签发时间	0001
expires_at	TEXT	NOT NULL · CHECK(expires_at > created_at)	过期时间（+5 分钟）	0001

索引 / 唯一约束

login_challenges_expiry (expires_at)

user_external_accounts外链账号5 字段

每用户每 provider 一行，验证归属与写接口归后续用例。

聚合 User · 主键 (user_id, provider) · 引入于 0001

字段	类型	约束	含义	迁移
PKFKuser_id	TEXT	PK · FK→users.user_id	资料所属用户，挂 users 外键。	0001
PKprovider	TEXT	PK · CHECK(provider IN ('x','telegram','discord','website'))	x / telegram / discord / website。	0001
handle	TEXT	NOT NULL · CHECK(length(handle) BETWEEN 1 AND 100)	该服务上的账号或网站地址，不存密码。	0001
verified_at	TEXT		归属验证时刻；NULL 表示未验证。	0001
created_at	TEXT	NOT NULL	创建时间，ISO TEXT。	0001

user_favorite_operations收藏操作回执11 字段

每个客户端操作一条回执，保证幂等：同一 operation_id 重放直接返回第一次的结果。

聚合 Favorite · 主键 (user_id, operation_id) · 引入于 0001

字段	类型	约束	含义	迁移
PKFKuser_id	TEXT	PK · FK→users.user_id	用户	0001
PKoperation_id	TEXT	PK	客户端生成的操作 ID	0001
network	TEXT	NOT NULL	请求的网络	0001
market_type	TEXT	NOT NULL	请求的市场类型	0001
market_key	TEXT	NOT NULL	请求的市场	0001
base_version	INTEGER	NOT NULL	客户端以为的当前版本	0001
requested_selected	INTEGER	NOT NULL	客户端想要的状态	0001
selected	INTEGER	NOT NULL	操作后的实际状态	0001
version	INTEGER	NOT NULL	操作后的实际版本	0001
cas_applied	INTEGER	NOT NULL	1 = applied；0 时按 selected 判 converged / conflict	0001
created_at	TEXT	NOT NULL	操作时间	0001

user_favorites收藏市场7 字段

按网络 × 市场类型 × 市场逐项收藏，多设备同步。取消收藏只把 selected 置 0，行保留，旧设备上线才能识别已发生的更新。

聚合 Favorite · 主键 (user_id, network, market_type, market_key) · 引入于 0001

字段	类型	约束	含义	迁移
PKFKuser_id	TEXT	PK · FK→users.user_id	用户	0001
PKnetwork	TEXT	PK · CHECK(network IN ('mainnet','testnet'))	网络	0001
PKmarket_type	TEXT	PK · CHECK(market_type IN ('perps','spot','outcome'))	市场类型	0001
PKmarket_key	TEXT	PK · CHECK(length(market_key) BETWEEN 1 AND 128)	市场标识（如 coin）	0001
selected	INTEGER	NOT NULL · CHECK(selected IN (0,1))	是否收藏；取消 = 0	0001
version	INTEGER	NOT NULL · CHECK(version > 0)	乐观锁版本，每次生效变更 +1	0001
last_operation_id	TEXT	NOT NULL	最后一次生效的操作 ID	0001

user_follows关注（单向）3 字段 · 2 索引

两个用户之间有方向的公开关系。粉丝数 / 关注数不落列，查询时 COUNT(*) 现算。

聚合 Follow · 主键 (follower_id, followee_id) · 引入于 0001

字段	类型	约束	含义	迁移
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

表级 CHECK

follower_id <> followee_id

索引 / 唯一约束

user_follows_followers_page (followee_id, created_at DESC, follower_id DESC)

user_follows_following_page (follower_id, created_at DESC, followee_id DESC)

user_login_clock登录取号机（单行）2 字段

全局单行计数器。每签发一个挑战 +1，给 login_order 提供单调序号。

聚合 Login · 主键 (id) · 引入于 0001

字段	类型	约束	含义	迁移
PKid	INTEGER	PK · CHECK(id=1)	固定为 1	0001
ordinal	INTEGER	NOT NULL	当前序号，初始 0	0001

种子行

[{"id":1,"ordinal":0}]

user_login_devices手机登录设备13 字段 · 1 索引

「某用户在某次 App 安装中的登录」，不是物理手机，也不是硬件身份。generation 是代际号，撤销只作用于指定那一代。

聚合 LoginDevice · 主键 (device_id) · 引入于 0001

字段	类型	约束	含义	迁移
PKdevice_id	TEXT	PK	设备记录 ID	0001
FKuser_id	TEXT	FK→users.user_id ON DELETE CASCADE · NOT NULL	所属用户（用户删除时级联删）	0001
installation_id	TEXT	NOT NULL	App 安装 ID	0001
name	TEXT	NOT NULL	设备名	0001
platform	TEXT	NOT NULL	ios / android（只由应用层约束，库里无 CHECK）	0001
system	TEXT	NOT NULL	系统版本	0001
generation	INTEGER	NOT NULL · DEFAULT 1	代际号：同一安装每次新登录 +1	0001
created_at	TEXT	NOT NULL	首次登记	0001
last_seen_at	TEXT	NOT NULL	最近活跃（按分钟节流写）	0001
revoked_at	TEXT		被远程撤销的时刻；同安装重新登录时置回 NULL	0001
notifications_revoked_generation	INTEGER		推送端已确认撤销到哪一代	0001
revoked_through_generation	INTEGER	NOT NULL · DEFAULT 0	这一代及更早的登录全部作废	0001
login_order	INTEGER	NOT NULL · DEFAULT 0	最近一次登记时的登录序号	0001

索引 / 唯一约束

UNIQUE (约束) (user_id, installation_id)

user_session_connections实时连接租约5 字段 · 2 索引

Bot 侧实时连接的 30 秒租约，只供 bot → server 的可信 RPC 使用。会话撤销后租约保留到 Bot 确认断开或租约过期，避免过早宣称「已全部退出」。

聚合 LoginDevice · 主键 (user_id, connection_id) · 引入于 0001

字段	类型	约束	含义	迁移
PKuser_id	TEXT	PK	用户	0001
FKsession_id	TEXT	FK→user_sessions.session_id ON DELETE CASCADE · NOT NULL	连接所属会话；外键 ON DELETE CASCADE，会话行被清理时租约一并删除（撤销只写 ended_at，不删租约）	0001
PKconnection_id	TEXT	PK	Bot 侧连接 ID	0001
FKdevice_id	TEXT	FK→user_login_devices.device_id ON DELETE SET NULL	连接所属登录设备；外键 ON DELETE SET NULL	0001
lease_expires_at	TEXT	NOT NULL	租约到期；每次续约 +30 秒	0001

索引 / 唯一约束

user_session_connections_device (user_id, device_id, lease_expires_at)

user_session_connections_session (session_id)

user_sessions会话 / 设备会话16 字段 · 5 索引

一台设备一条会话（门禁卡）。手机经钱包签名登录；网页 / 桌面只能经手机扫码配对签发，并带一把自己的 HL named agent。会话结束只记 ended_at，行留着供「待撤销」展示。

聚合 Session · 主键 (session_id) · 引入于 0001

字段	类型	约束	含义	迁移
PKsession_id	TEXT	PK	主键；对外暴露的会话引用（token 不外露），租约外键指向它	0001
UQtoken_hash	TEXT	UQ · NOT NULL · 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
FKdevice_id	TEXT	FK→user_login_devices.device_id	手机会话所在的登录设备；电脑会话为 NULL	0001
login_order	INTEGER	NOT NULL · DEFAULT 0	来自挑战的登录序号	0001
client	TEXT	NOT NULL · DEFAULT 'mobile' · CHECK(client IN ('mobile','web','desktop'))	签发端，签发后不可改	0001
device_label	TEXT	CHECK(device_label IS NULL OR length(device_label) BETWEEN 1 AND 80)	设备名（展示用）	0001
ua	TEXT	CHECK(ua IS NULL OR length(ua) <= 512)	User-Agent（只给本人设备页看）	0001
ip_geo	TEXT	CHECK(ip_geo IS NULL OR length(ip_geo) <= 120)	IP 粗略地理位置（只给本人设备页看）	0001
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 的地址；续期会换	0001
agent_name	TEXT	CHECK(agent_name IS NULL OR length(agent_name) BETWEEN 1 AND 16)	HL named agent 名 `berth-xxxxxx`；顶号时沿用旧名	0001
created_at	TEXT	NOT NULL	签发时间	0001
expires_at	TEXT	NOT NULL · CHECK(expires_at > created_at)	到期时间；固定 30 天，电脑续期时延长	0001
last_seen_at	TEXT		最近活跃（按分钟节流写）	0001
ended_at	TEXT		已登出 / 被结束的时刻；非空即失效	0001
agent_revoked_at	TEXT		agent 已确认从链上撤掉或被同名顶替；为空且已结束 = 待撤销 SQL 注释：这把 agent 已确认从链上撤掉（撤销中继轮到 userRole = missing），或已被新设备同名顶替。未过期且为空 = 仍占 HL named agent 名额（含已登出、待撤销的设备）。	0001

索引 / 唯一约束

UNIQUE (约束) (token_hash)

user_sessions_agent_slots (user_id, agent_name, expires_at) WHERE agent_name IS NOT NULL AND agent_revoked_at IS NULL

user_sessions_device (device_id)

user_sessions_expiry (expires_at)

user_sessions_owner (user_id)

user_settings隐私偏好6 字段

每用户一行；没行 = 所有默认值。写接口随社交用例交付。

聚合 User · 主键 (user_id) · 引入于 0001

字段	类型	约束	含义	迁移
PKFKuser_id	TEXT	PK · FK→users.user_id	偏好所属用户，挂 users 外键。	0001
dm_policy	TEXT	NOT NULL · DEFAULT 'everyone' · CHECK(dm_policy IN ('everyone','following','mutuals','nobody'))	everyone / following / mutuals / nobody；默认 everyone。	0001
group_invite_policy	TEXT	NOT NULL · DEFAULT 'everyone' · CHECK(group_invite_policy IN ('everyone','following','nobody'))	everyone / following / nobody；默认 everyone。	0001
show_trading_stats	INTEGER	NOT NULL · DEFAULT 1 · CHECK(show_trading_stats IN (0,1))	默认 1，只控制展示许可，不建立金融权威源。	0001
discoverable	INTEGER	NOT NULL · DEFAULT 1 · CHECK(discoverable IN (0,1))	默认 1，允许被发现；0 时后续发现用例需过滤。	0001
updated_at	TEXT	NOT NULL	最近修改时刻，ISO TEXT。	0001

username_registry用户名登记簿4 字段 · 2 索引

当前用户名和保留中的旧名共用一个命名空间：held_until IS NULL 是当前名，有值是改名后保留到该时刻的旧名。

聚合 User · 主键 (username) · 引入于 0001

字段	类型	约束	含义	迁移
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

索引 / 唯一约束

UNIQUE username_one_current_per_user (user_id) WHERE held_until IS NULL

username_registry_expiry (held_until) WHERE held_until IS NOT NULL

users用户本体10 字段 · 1 索引

一个钱包对应一个 Berth 用户，ID 永久不变，不换绑、不合并。用户名不在这张表里（见 username_registry），避免两个「当前用户名」权威源。

聚合 User · 主键 (user_id) · 引入于 0001

字段	类型	约束	含义	迁移
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
bio	TEXT	CHECK(bio IS NULL OR length(bio) BETWEEN 1 AND 160)	可选个人简介，NULL 表示未填写；本票仅扩展 schema。	0001
avatar_kind	TEXT	NOT NULL · DEFAULT 'preset' · CHECK(avatar_kind IN ('preset','upload'))	preset 预设头像 / upload R2 object key；资料接口的 avatarId 只表达 preset（presetAvatarIdOf），upload 回落 default。 SQL 注释：preset = 预设头像 id（集合归 domain，库不枚举）；upload = R2 object key。	0001
avatar_key	TEXT	NOT NULL · DEFAULT 'default' · CHECK(length(avatar_key) BETWEEN 1 AND 256)	预设 id 或 R2 key；唯一的头像存储。	0001
badge	TEXT	NOT NULL · DEFAULT 'none' · CHECK(badge IN ('none','verified','official'))	none / verified / official，首版运维直写。 SQL 注释：徽章首版由运维脚本直写。	0001
deactivated_at	TEXT		注销墓碑，NULL 表示未注销；公开卡片屏蔽可识别资料。跨存储编排归 BERTH-1925。 SQL 注释：注销墓碑（Apple 5.1.1(v)）：非空 = 资料隐藏、用户名进保留期、社交显示「已注销用户」。跨存储编排归 BERTH-1925。	0001
created_at	TEXT	NOT NULL	创建时间	0001
updated_at	TEXT	NOT NULL	资料最近更新时间	0001

索引 / 唯一约束

UNIQUE (约束) (wallet_address)

由 pnpm schema-docs build user-db 生成 · 结构来源 apps/server/migrations/users · 语义来源 docs/data/user-db/annotations.json · 指纹 sha256:13b99b758335e3f9

USER_DB

板块颜色贯穿全文

身份

登录与会话

设备

社交与偏好

全库约定

业务流程跟着流程看表怎么变

📱 第一次用手机钱包登录

💻 电脑扫码登录，agent 名额满了要顶掉一台

🏷️ 把用户名从 alice 改成 bob

设计要点

聚合每张表恰好属于一个聚合；kind=supporting 是辅助表

User

Login

Session

LoginDevice

Follow

Favorite

写路径矩阵哪个仓储方法写哪几张表

跨库 / 链上引用都没有外键，靠应用层维持

保留与清理

敏感度未列出的字段视为「内部」

全部字段1 个迁移叠加后的最终结构 · 由迁移自动提取

关系图实线 = 数据库外键（乌鸦脚在「多」端）· 虚线 = 逻辑关联 / 流程 · 点表框跳到字段