# 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 迭代参数、登录失败节流策略 | 技术稿 |
| 审计日志表结构 | 技术稿 |