4.4 KiB

Raw Blame History

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

日期：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`

请求体：

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

行为：

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

错误：

参数错误
用户名已存在

3.2 `POST /api/auth/login`

请求体：

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

行为：

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

错误：

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

3.3 `POST /api/auth/logout`

行为：

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

3.4 `GET /api/auth/me`

行为：

从 Cookie 读取 session
校验 session 是否存在且未过期
查询用户并返回最小信息（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. 实施顺序建议

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

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

4.4 KiB Raw Blame History