# 用户名密码登录注册设计文档

日期：2026-04-16  
范围：仅实现用户名 + 密码的注册、登录、登出、登录态查询  
目标：按主线交付可用认证闭环，不扩展额外功能

## 1. 需求边界

### 1.1 必做功能

- 用户注册（用户名 + 密码）
- 用户登录（用户名 + 密码）
- 登录后通过 HttpOnly Cookie 维持会话
- 登出清理会话
- 获取当前登录用户信息（`/api/auth/me`）

### 1.2 明确不做

- 邮箱/手机登录
- 验证码
- 忘记密码
- 第三方登录
- 复杂权限系统
- 刷新 token、多设备管理
- 非必要 UI 优化

## 2. 约束与规则

### 2.1 字段规则

- `username`：3-20 位，仅允许字母、数字、下划线（正则：`^[a-zA-Z0-9_]{3,20}$`）
- `password`：最少 6 位

### 2.2 会话方式

- 登录成功后由后端写入 `HttpOnly Cookie`
- Cookie 建议配置：
  - `httpOnly: true`
  - `sameSite: 'lax'`
  - `secure: true`（仅生产环境）
  - `path: '/'`
  - `maxAge: 60 * 60 * 24 * 7`（7 天）

## 3. 接口设计

### 3.1 `POST /api/auth/register`

请求体：

```json
{
  "username": "demo_user",
  "password": "123456"
}
```

行为：

1. 校验参数格式
2. 检查用户名是否已存在
3. 生成密码哈希并写入 `users`
4. 返回注册成功

错误：

- 参数错误
- 用户名已存在

### 3.2 `POST /api/auth/login`

请求体：

```json
{
  "username": "demo_user",
  "password": "123456"
}
```

行为：

1. 校验参数格式
2. 按用户名查用户
3. 校验密码哈希
4. 创建 session
5. 写入 `HttpOnly Cookie`
6. 返回登录成功及最小用户信息

错误：

- 参数错误
- 用户名或密码错误（统一提示）

### 3.3 `POST /api/auth/logout`

行为：

1. 从 Cookie 读取 session 标识
2. 删除或失效 session
3. 清空 Cookie
4. 返回登出成功

### 3.4 `GET /api/auth/me`

行为：

1. 从 Cookie 读取 session
2. 校验 session 是否存在且未过期
3. 查询用户并返回最小信息（`id`、`username`）

错误：

- 未登录或会话失效

## 4. 数据模型设计

### 4.1 复用表：`users`

基于现有结构，认证主链仅依赖：

- `id`
- `username`（唯一）
- `password`（哈希后存储）

### 4.2 新增表：`sessions`

建议字段：

- `id`：session 主键（随机字符串/UUID）
- `userId`：关联 `users.id`
- `expiresAt`：过期时间
- `createdAt`：创建时间

说明：

- Cookie 仅保存 session 标识，不保存用户敏感信息
- `me` 通过 session 回查用户

## 5. 代码落点（最小改动）

### 5.1 后端

- `server/service/auth/index.ts`
  - 实现：`register`、`login`、`logout`、`getMe`
- `server/api/auth/register.post.ts`
- `server/api/auth/login.post.ts`
- `server/api/auth/logout.post.ts`
- `server/api/auth/me.get.ts`
- `packages/drizzle-pkg/database/pg/schema/auth.ts`
  - 新增 `sessions` 表
- `packages/drizzle-pkg/lib/schema/auth.ts`
  - 导出 `sessions`
- 数据库迁移文件（按项目迁移流程新增）

### 5.2 前端

- `app/pages/login/index.vue`
  - 由邮箱改为用户名输入
  - 从模拟提交改为调用 `POST /api/auth/login`
- `app/pages/register/index.vue`
  - 新增注册页，调用 `POST /api/auth/register`

## 6. 业务流程

### 6.1 注册

前端提交 -> 后端校验 -> 用户名唯一检查 -> 哈希密码入库 -> 返回成功

### 6.2 登录

前端提交 -> 后端校验 -> 用户验证 -> session 入库 -> 写 Cookie -> 返回成功

### 6.3 登录态读取

请求到达 -> 读取 Cookie -> 校验 session -> 查询用户 -> 返回最小用户信息

### 6.4 登出

读取 Cookie -> 删除 session -> 清空 Cookie -> 返回成功

## 7. 错误与安全策略

- 密码只存哈希，不存明文
- 登录失败统一提示“用户名或密码错误”
- 参数错误与业务错误分离
- `me` 与 `logout` 对无效 session 返回未授权

## 8. 验收标准

- 可成功注册新用户
- 重复用户名注册被拒绝
- 正确凭据可登录并写入 HttpOnly Cookie
- 错误凭据登录失败且错误信息统一
- `GET /api/auth/me` 在已登录状态下返回用户信息
- `POST /api/auth/logout` 后再次访问 `me` 返回未登录

## 9. 实施顺序建议

1. 数据表与迁移（`sessions`）
2. `server/service/auth` 业务函数
3. 认证 API 路由
4. 登录页与注册页对接
5. 手工验收 6 条用例

---

本设计文档仅覆盖当前主线目标：用户名密码注册登录，不包含任何扩展认证能力。