skycurtain
e4d25526f3
- 需求清单：独立计费平台定位，R1-R15 全部定案（12 项裁决 + R10 裁撤 + R3/R4 延后），裁决档案含访问主体模型（作者登录体系 + 成员长期令牌）、分摊哲学（平台不做价值判断只提供事实服务）、双形态交付（完整前后端先行，CFW 抽取版后续） - 数据模型定稿（一表一文档）：api_keys（16 列，401 状态机裁撤——引擎记录不决策）/ usage_logs（25 列，billing_source 与 subscription_id 提列，非消费行去重含 content 指纹）/ payments（币种无关支付记录，只存事实）/ qpu_history（按日志时刻取值）/ members（成员实体与长期令牌）/ users（空库双通道初始化与重置）/ sessions（服务端会话，否决 JWT） - 接口参考：NewAPI-接口范围融合字段级实证，定位 docs/references/（计费平台可用接口参考，唯一上游参考） - README / AGENTS：新版设计语境（项目沿革、重开设计动因、协作约定、文档自立原则）
65 lines
3.5 KiB
Markdown
65 lines
3.5 KiB
Markdown
# users 表字段设计
|
||
|
||
> 数据模型新增表之二：管理员——登录体系的身份落点，**实际只有一行**（作者，唯一管理员）。裁决背景见 `docs/design/需求清单.md` §9「访问主体模型」。
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 状态 | 定稿（2026-10-01） |
|
||
| 关联 | `docs/design/sessions表字段设计.md`（登录会话指向本表）· `docs/design/需求清单.md` §9 |
|
||
| 范围 | 列结构 + 语义 + 写入时机；登录流程细节（PBKDF2 参数、节流）归技术稿；方言映射归数据访问层设计 |
|
||
| 字段数 | 4 = 1 主键 + 3 业务字段 |
|
||
|
||
---
|
||
|
||
## 1. 表定位
|
||
|
||
- **一行 = 一个管理员账号**——本表设计为单行（作者），不存在注册路径
|
||
- 凭证经**部署期初始化**创建（env / wrangler secret 的引导凭证，空库幂等落库）——部署完成即就绪；空库且 env 无凭证时由**引导页**完成初始化（重置兜底通道，见 3.1）
|
||
|
||
## 2. 字段清单
|
||
|
||
| 列 | 类型 | 值来源 | 说明 |
|
||
|----|------|--------|------|
|
||
| `id` | bigserial PK | 自增 | |
|
||
| `username` | text UNIQUE | 部署期初始化 | 登录名 |
|
||
| `password_hash` | text | 部署期初始化 / 改密 | PBKDF2-SHA256 哈希（WebCrypto 原生，两形态统一——Workers 无 argon2/bcrypt） |
|
||
| `created_at` | timestamptz | 初始化时 | |
|
||
|
||
## 3. 决策记录（含理由）
|
||
|
||
### 3.1 单行表，不做注册；初始化与重置 = 空库双通道
|
||
|
||
管理员账号由空库初始化创建；改密走登录后的表单（旧密码验证 → 落库）。「单行」是**部署行为约定，不是 schema 约束**——表结构天然支持多行，未来若需要多管理员 + 角色，扩展为增量动作（加 `role` 列 + 中间件分支 + 管理页），无需推倒任何东西。
|
||
|
||
**管理面入口的幂等三态判断**：
|
||
|
||
- `users` 非空 → 登录页（如常）
|
||
- 空库 + env 凭证在 → **静默重建**（部署与重置共用此通道；密码即 env 凭证）
|
||
- 空库 + env 凭证无 → **引导页**（设置新用户名密码，直接进入登录态；`users` 非空后永不复现）
|
||
|
||
**忘记密码的重置**：删除 `users` 行（母体：请运营方执行一条 SQL；CFW：自助 `wrangler d1 execute`）→ 下一次请求触发三态判断 → 有 env 静默重建后改密，无 env 引导页当场设新密码。**env 凭证可留可删、无依赖**——留着享受静默重建，删了有页面兜底；抢注窗口仅存在于「删 env + 删行」的重置瞬间（作者主导、分钟级），部署路径（env 在）永远无窗口。
|
||
|
||
### 3.2 密码哈希选 PBKDF2-SHA256
|
||
|
||
WebCrypto 原生支持——母体与 CFW 抽取版同一实现（Workers runtime 无 argon2/bcrypt，选它们会造成两形态分叉）；迭代参数归技术稿。
|
||
|
||
### 3.3 不建多用户 / 角色引擎
|
||
|
||
管理操作只有作者一人——RBAC 无用武之地；权限边界由访问面物理隔离（管理面 API 与成员 API 两套路由）。
|
||
|
||
## 4. 写入时机
|
||
|
||
| 时机 | 动作 |
|
||
|------|------|
|
||
| 部署期初始化（双通道） | 空库 + env 凭证在 → 静默 INSERT（幂等，已初始化则永远跳过）；空库 + env 凭证无 → 引导页设新密码后 INSERT（重置兜底） |
|
||
| 改密（管理面表单） | UPDATE `password_hash` |
|
||
|
||
改密落**审计日志**（审计为独立需求，表结构归技术稿）。
|
||
|
||
## 5. 待定事项
|
||
|
||
| 事项 | 归属 |
|
||
|------|------|
|
||
| PBKDF2 迭代参数、登录失败节流策略 | 技术稿 |
|
||
| 审计日志表结构 | 技术稿 |
|