# 后端登录注册接口说明

本文档描述 `common-br-api` 项目中用户认证（注册、登录、Token 校验）的后端实现，便于前后端联调与部署排查。

---

## 1. 总览

| 项目 | 说明 |
|------|------|
| 路由前缀 | `/auth` |
| 框架 | FastAPI |
| 用户表 | `sys_users` |
| 会话表 | `user_sessions` |
| 密码算法 | PBKDF2-HMAC-SHA256（210000 次迭代） |
| Token 形式 | 自实现 JWT 风格 Bearer Token（HS256 签名） |
| 默认有效期 | 24 小时（1440 分钟） |

**当前已实现的 HTTP 接口：**

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/auth/register` | 注册并自动登录 |
| `POST` | `/auth/login` | 账号密码登录 |

**尚未实现的接口（前端 UI 可能已预留）：**

- `/auth/logout`（登出 / 服务端吊销会话）
- `/auth/refresh`（刷新 Token）
- 手机号 / 短信验证码登录

---

## 2. 代码结构

```
app/
├── api/
│   └── auth.py              # 注册、登录、get_current_user 依赖
├── core/
│   └── security.py          # 密码哈希、Token 签发、Token 哈希
├── models/
│   └── auth.py              # User、UserSession ORM 模型
├── config/
│   └── settings.py          # JWT 密钥、过期时间等配置
└── main.py                  # 挂载 auth 路由

migrations/versions/
└── 7c91a64f2b2e_create_auth_tables.py   # 建表迁移
```

路由挂载（`app/main.py`）：

```python
app.include_router(auth_router)   # 无前缀叠加，router 自身 prefix="/auth"
```

因此完整 URL 为：

```text
http://<host>:8000/auth/register
http://<host>:8000/auth/login
```

经 Next.js 代理后（开发环境）也可访问：

```text
http://localhost:3000/auth/register
http://localhost:3000/auth/login
```

---

## 3. 认证流程

### 3.1 注册 / 登录发 Token

```mermaid
sequenceDiagram
    participant Client as 客户端
    participant API as /auth/*
    participant DB as PostgreSQL

    Client->>API: POST /auth/register 或 /auth/login
    API->>DB: 查重 / 校验密码
    API->>API: create_access_token(sub, account, jti)
    API->>DB: INSERT user_sessions(jti, token_hash, expires_at)
    API-->>Client: TokenResponse(access_token, expires_at, user)
```

### 3.2 受保护接口校验 Token

```mermaid
sequenceDiagram
    participant Client as 客户端
    participant API as 业务接口
    participant DB as PostgreSQL

    Client->>API: Authorization: Bearer <token>
    API->>API: 校验 JWT 签名与 exp
    API->>DB: JOIN sys_users + user_sessions<br/>匹配 user_id, jti, token_hash
    alt 会话有效
        API-->>Client: 200 + 业务数据
    else 无效或过期
        API-->>Client: 401 / 403
    end
```

**要点：**

1. Token 不仅校验 JWT 签名和过期时间，还必须在 `user_sessions` 表中有对应且未吊销的记录。
2. 数据库存的是 Token 的 **SHA256 哈希**，不是明文 Token。
3. 每个 Token 有唯一 `jti`（JWT ID），用于会话追踪。

---

## 4. 数据库设计

### 4.1 `sys_users`

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | UUID | PK | 用户 ID |
| `account` | VARCHAR(100) | UNIQUE, NOT NULL | 登录账号 |
| `password_hash` | TEXT | NOT NULL | PBKDF2 哈希串 |
| `name` | VARCHAR(100) | NOT NULL | 显示名称 |
| `email` | VARCHAR(255) | UNIQUE, NOT NULL | 邮箱（注册时转小写） |
| `phone` | VARCHAR(50) | NULL | 手机号（可选） |
| `created_at` | TIMESTAMPTZ | NOT NULL | 创建时间 |
| `updated_at` | TIMESTAMPTZ | NOT NULL | 更新时间 |

索引：

- `ux_users_account`（account 唯一）
- `ux_users_email`（email 唯一）

### 4.2 `user_sessions`

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | UUID | PK | 会话记录 ID |
| `user_id` | UUID | FK → sys_users.id, CASCADE | 所属用户 |
| `jti` | VARCHAR(64) | UNIQUE, NOT NULL | Token 会话 ID |
| `token_hash` | TEXT | NOT NULL | SHA256(access_token) |
| `expires_at` | TIMESTAMPTZ | NOT NULL | 过期时间 |
| `revoked_at` | TIMESTAMPTZ | NULL | 吊销时间（预留，当前无 logout 接口写入） |
| `created_at` | TIMESTAMPTZ | NOT NULL | 创建时间 |
| `updated_at` | TIMESTAMPTZ | NOT NULL | 更新时间 |

---

## 5. 环境配置

配置类：`app/config/settings.py`

| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| `JWT_SECRET_KEY` | `change-me-in-production` | HMAC 签名密钥，**生产必须修改** |
| `JWT_ALGORITHM` | `HS256` | 写入 JWT Header（实际签名为 HMAC-SHA256） |
| `ACCESS_TOKEN_EXPIRE_MINUTES` | `1440`（24h） | Token 有效期（分钟） |
| `DATABASE_URL` | 见 `.env.example` | PostgreSQL 连接串 |

示例（`.env`）：

```env
JWT_SECRET_KEY=your-long-random-secret
DATABASE_URL=postgresql+asyncpg://user:pass@postgres:5432/brapi-python
```

---

## 6. 密码安全

实现文件：`app/core/security.py`

### 6.1 哈希格式

```
pbkdf2_sha256$210000$<salt_hex>$<digest_hex>
```

- 算法：`PBKDF2-HMAC-SHA256`
- 迭代次数：`210000`
- Salt：16 字节随机 hex（`secrets.token_hex(16)`）

### 6.2 注册时

```python
password_hash=hash_password(payload.password)
```

### 6.3 登录时

```python
verify_password(payload.password, user.password_hash)
```

校验失败统一返回 `401 Invalid account or password`，不区分「账号不存在」与「密码错误」。

---

## 7. Access Token 结构

Token 由 `create_access_token()` 生成，格式为三段式 Base64URL：

```text
<base64url(header)>.<base64url(payload)>.<base64url(signature)>
```

### 7.1 Header

```json
{"alg": "HS256", "typ": "JWT"}
```

### 7.2 Payload

```json
{
  "sub": "<user_uuid>",
  "account": "<login_account>",
  "jti": "<32_hex_chars>",
  "iat": 1710000000,
  "exp": 1710086400
}
```

| Claim | 含义 |
|-------|------|
| `sub` | 用户 UUID 字符串 |
| `account` | 登录账号 |
| `jti` | 会话唯一 ID |
| `iat` | 签发时间（Unix 秒） |
| `exp` | 过期时间（Unix 秒） |

### 7.3 签名

```python
HMAC-SHA256(key=JWT_SECRET_KEY, msg=f"{header_b64}.{payload_b64}")
```

> 注意：项目使用**自实现**的 JWT 编解码（`app/api/auth.py` + `app/core/security.py`），未依赖 PyJWT 库。

---

## 8. HTTP 接口详情

### 8.1 注册 `POST /auth/register`

**请求体 `RegisterRequest`：**

| 字段 | 类型 | 必填 | 校验 |
|------|------|------|------|
| `account` | string | 是 | 长度 3–100 |
| `password` | string | 是 | 长度 6–128 |
| `name` | string | 是 | 长度 1–100 |
| `email` | string | 是 | 长度 3–255，入库前转小写 |
| `phone` | string | 否 | 最大 50 |

**业务逻辑：**

1. `account`、`email` 去空格 / 小写处理
2. 查询 `sys_users`，若 `account` 或 `email` 已存在 → `409 Conflict`
3. 创建用户并 `flush`
4. 调用 `_issue_token()` 写入 `user_sessions` 并返回 Token

**成功响应：** `201 Created`，Body 为 `TokenResponse`

**curl 示例：**

```bash
curl -X POST http://127.0.0.1:8000/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "account": "demo_user",
    "password": "demo123456",
    "name": "演示用户",
    "email": "demo@example.com",
    "phone": "13800138000"
  }'
```

---

### 8.2 登录 `POST /auth/login`

**请求体 `LoginRequest`：**

| 字段 | 类型 | 必填 | 校验 |
|------|------|------|------|
| `account` | string | 是 | 长度 1–100 |
| `password` | string | 是 | 长度 1–128 |

**业务逻辑：**

1. 按 `account` 查用户
2. `verify_password` 失败 → `401 Unauthorized`
3. 成功则 `_issue_token()` 并返回

**成功响应：** `200 OK`，Body 为 `TokenResponse`

**curl 示例：**

```bash
curl -X POST http://127.0.0.1:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "account": "demo_user",
    "password": "demo123456"
  }'
```

---

### 8.3 统一成功响应 `TokenResponse`

```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....",
  "token_type": "bearer",
  "expires_at": "2026-05-27T10:00:00+00:00",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "account": "demo_user",
    "name": "演示用户",
    "email": "demo@example.com",
    "phone": "13800138000"
  }
}
```

| 字段 | 说明 |
|------|------|
| `access_token` | Bearer Token 字符串 |
| `token_type` | 固定 `"bearer"` |
| `expires_at` | ISO8601 UTC 过期时间 |
| `user` | 当前用户公开信息（不含密码） |

---

### 8.4 错误响应格式

认证相关错误通过 `ApiError` 抛出，由 `app/main.py` 统一处理：

```json
{
  "message": "错误摘要",
  "detail": "错误摘要或详细信息"
}
```

| HTTP 状态码 | 场景 | message 示例 |
|-------------|------|----------------|
| `401` | 登录失败 | `Invalid account or password` |
| `401` | 缺少 Token | `Missing bearer token` |
| `401` | Token 无效 | `Invalid token signature` / `Session invalid or expired` |
| `403` | Token 过期 | `Token expired` |
| `409` | 注册冲突 | `Account or email already exists` |
| `422` | 参数校验失败 | `Validation failed`（detail 为字段错误列表） |

---

## 9. 受保护接口：`get_current_user`

定义位置：`app/api/auth.py`

```python
async def get_current_user(
    credentials: HTTPAuthorizationCredentials | None = Depends(bearer_scheme),
    session: AsyncSession = Depends(get_db_session),
) -> User:
    ...
```

### 9.1 客户端如何携带 Token

```http
Authorization: Bearer <access_token>
```

### 9.2 校验步骤

1. 检查 `Authorization` 头是否存在且 scheme 为 `bearer`
2. `_decode_access_token()`：验证格式、HMAC 签名、`exp` 未过期
3. 从 payload 读取 `sub`（user_id）、`jti`
4. 数据库查询：

```sql
SELECT sys_users.*
FROM sys_users
JOIN user_sessions ON user_sessions.user_id = sys_users.id
WHERE sys_users.id = :user_id
  AND user_sessions.jti = :jti
  AND user_sessions.token_hash = sha256(:token)
  AND user_sessions.revoked_at IS NULL
  AND user_sessions.expires_at > now()
```

5. 查不到用户 → `401 Session invalid or expired`

### 9.3 哪些接口使用了 `get_current_user`

#### `/auth` 模块

无（register/login 本身不需要 Token）

#### `/api/dictionaries` 模块（`app/api/dictionaries.py`）

| 接口 | 是否需要登录 |
|------|-------------|
| `GET /api/dictionaries/crops` | 否 |
| `POST /api/dictionaries/crops` | **是** |
| `GET /api/dictionaries/persons` | 否 |
| `POST /api/dictionaries/persons` | 否 |
| `POST /api/dictionaries/countries` | **是** |
| `PUT /api/dictionaries/countries/{code}` | **是** |

#### `/brapi/v2` 模块（`app/api/router.py`）

- 多数 **GET** 接口：接收 `Authorization` 头但**不强制校验**（BrAPI 兼容占位）
- 多数 **POST / PUT / DELETE** 写操作：通过 `Depends(get_current_user)` **强制登录**

写操作成功后会将 `current_user.id` 写入业务表的 `auth_user_id` 字段，用于记录数据创建者。

> 上传接口 `POST /brapi/v2/upload/image` 当前**未**接入 `get_current_user`，前端可选择性携带 Token。

---

## 10. `_issue_token` 内部流程

```python
async def _issue_token(session: AsyncSession, user: User) -> TokenResponse:
    jti = uuid4().hex
    token, expires_at = create_access_token(
        subject=str(user.id),
        account=user.account,
        jti=jti,
    )
    session.add(UserSession(
        user_id=user.id,
        jti=jti,
        token_hash=hash_token(token),
        expires_at=expires_at,
    ))
    await session.commit()
    return TokenResponse(...)
```

每次登录/注册都会**新增一条** `user_sessions` 记录；旧会话不会自动吊销（除非手动清理数据库或未来实现 logout）。

---

## 11. 前端对接（简要）

| 文件 | 作用 |
|------|------|
| `frontend/src/services/authService.ts` | 封装 `loginWithPassword`、`registerAccount` |
| `frontend/src/lib/api/sdk.gen.ts` | OpenAPI 生成的 `/auth/login`、`/auth/register` 客户端 |
| `frontend/src/stores/modules/auth.ts` | Zustand 持久化 Token 与用户信息 |
| `frontend/src/utils/token.ts` | 从 `localStorage` 读取 `auth_token` |
| `frontend/src/lib/client.ts` | 请求拦截器自动附加 `Authorization: Bearer ...` |

登录成功后前端会：

1. 调用 `setSession(session)` 写入 Zustand + `localStorage.auth_token`
2. 跳转到 `/central-config/user/employee` 或 `redirect` 参数指定页

登出：仅前端 `logout()` 清除本地存储，**不会**通知后端吊销会话。

---

## 12. 本地调试

### 12.1 启动后端

```bash
uv run uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload
```

### 12.2 Swagger 文档

```text
http://127.0.0.1:8000/docs
```

在 Swagger 中可找到 `auth` 分组下的 `register`、`login`。

### 12.3 用 Token 访问受保护接口

```bash
TOKEN="<access_token>"

curl http://127.0.0.1:8000/api/dictionaries/crops \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"crop_name": "maize"}'
```

---

## 13. 部署注意事项

1. **必须修改** `JWT_SECRET_KEY`，不要使用默认值 `change-me-in-production`。
2. 首次部署需执行数据库迁移：`uv run alembic upgrade head`（包含 `sys_users`、`user_sessions` 建表）。
3. Docker / K8s 环境中，容器内 `API_BASE_URL=http://127.0.0.1:8000` 供 Next.js 代理；客户端浏览器仍通过同源 `/auth/*` 访问。
4. 当前无服务端 logout：Token 在过期前始终有效（只要 `user_sessions` 记录存在）。如需强制下线，需扩展 logout 接口并设置 `revoked_at`。

---

## 14. 后续可扩展项

| 功能 | 建议实现 |
|------|----------|
| 登出 | `POST /auth/logout`，将当前 `jti` 的 `revoked_at` 设为 now |
| 刷新 Token | `POST /auth/refresh`，验证旧 Token 后签发新 Token |
| 当前用户 | `GET /auth/me`，返回 `UserResponse` |
| 修改密码 | `POST /auth/change-password` |
| 手机号登录 | 独立短信验证码表 + 新 login 分支 |
| 上传鉴权 | `upload.py` 增加 `Depends(get_current_user)` |

---

## 15. 相关源码索引

| 内容 | 路径 |
|------|------|
| 路由与 DTO | `app/api/auth.py` |
| 密码 / Token 工具 | `app/core/security.py` |
| ORM 模型 | `app/models/auth.py` |
| 配置 | `app/config/settings.py` |
| 建表迁移 | `migrations/versions/7c91a64f2b2e_create_auth_tables.py` |
| 应用入口 | `app/main.py` |
| 前端封装 | `frontend/src/services/authService.ts` |