chongming-plugins/auth/README.md

# Auth Worker 插件 — 用户管理

auth 域拆分后的**用户管理插件**（可替换的业务部分）。
登录 / token 签发 / admin 种子已**内置在网关**（管理平面底线，不依赖本插件是否
加载，本插件缩容到 0 或全部副本故障时登录与 admin API 仍可用）。

共享契约归 `chongming-auth` 包（`utils/auth/`）：Users 模型（唯一权威定义）、
建库、登录校验、JWT 签发。本插件与网关内置登录**共用同一张 users 表**。

---

## 功能

- **用户注册**：用户名 + 邮箱 + 密码注册，自动校验唯一性
- **获取用户信息**：根据 JWT Token 获取完整用户档案
- **修改密码**：旧密码验证 + 新密码更新
- **更新资料**：更新全名、邮箱、头像、手机号等信息

（登录 `POST /auth/login` 由网关内置提供，路径与响应 shape 不变）

---

## 数据库

使用 SQLite（通过 `chongming-database` 异步封装），数据库文件位于
`data/auth.db`（`[workers.config].data_dir` 下）；配置 `database.url` 时走
PostgreSQL。库位置与网关内置登录读同一份配置（本插件 `config.toml` 的
`[workers.config]`），指向同一张 users 表。

### Users 表结构

权威定义见 `chongming_auth.models.Users`（本仓库 `models/auth.py` 仅为 re-export）：

| 字段              | 类型              | 说明                              |
| ----------------- | ----------------- | --------------------------------- |
| `id`              | `str` (PK)        | UUID 格式主键                     |
| `username`        | `str(50)` UNIQUE  | 登录用户名                        |
| `email`           | `str(255)` UNIQUE | 电子邮箱                          |
| `hashed_password` | `str(255)`        | Argon2id 加密密码                 |
| `full_name`       | `str(100)`        | 用户全名（可选）                  |
| `avatar_url`      | `str(500)`        | 头像链接（可选）                  |
| `phone`           | `str(20)`         | 手机号码（可选）                  |
| `is_active`       | `bool`            | 账户启用状态（默认 `true`）       |
| `is_verified`     | `bool`            | 邮箱/手机验证状态（默认 `false`） |
| `is_superuser`    | `bool`            | 超级管理员标识（默认 `false`）    |
| `created_at`      | `datetime`        | 创建时间                          |
| `updated_at`      | `datetime`        | 最后更新时间                      |
| `last_login_at`   | `datetime`        | 最后登录时间（可选）              |

密码使用 Rust 实现的 **Argon2id** 哈希，内存成本 19456 KiB，迭代 2 次，并行度 1。

---

## API 端点

所有端点路由前缀为 `/auth`。

### `POST /auth/login` — 登录（网关内置）

无需认证。由网关核心 `chongming/app/routes/auth.py` 提供（非本插件），
路径与响应 shape 与拆分前一致。JWT claims 契约见 `chongming-auth` 包 README。

```json
// 请求
{
  "username": "admin",
  "password": "admin"
}

// 响应
{
  "result": "success",
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "message": "登录成功",
  "timestamp": 1720000000.123
}
```

### `POST /auth/register` — 用户注册

无需认证。

```json
// 请求
{
  "username": "john",
  "password": "secret123",
  "email": "john@example.com",
  "full_name": "John Doe",
  "phone": "13800138000"
}

// 响应
{
  "result": "success",
  "message": "注册成功",
  "user_id": "a1b2c3d4_12345_1720000000.123",
  "timestamp": 1720000000.123
}
```

### `GET /auth/me?user_id=<id>` — 获取用户信息

需要 JWT 鉴权（`Authorization: Bearer <token>`）。

```json
// 响应
{
  "result": "success",
  "id": "a1b2c3d4_12345_1720000000.123",
  "username": "john",
  "email": "john@example.com",
  "full_name": "John Doe",
  "avatar_url": null,
  "phone": "13800138000",
  "is_active": true,
  "is_verified": false,
  "is_superuser": false,
  "created_at": "2024-01-01T00:00:00+00:00",
  "updated_at": "2024-01-01T00:00:00+00:00",
  "last_login_at": null
}
```

### `POST /auth/change_password` — 修改密码

需要 JWT 鉴权。

```json
// 请求
{
  "user_id": "a1b2c3d4_12345_1720000000.123",
  "old_password": "secret123",
  "new_password": "newSecret456"
}

// 响应
{
  "result": "success",
  "message": "密码修改成功",
  "timestamp": 1720000000.123
}
```

### `POST /auth/update_profile` — 更新用户资料

需要 JWT 鉴权。仅更新非空字段。

```json
// 请求
{
  "user_id": "a1b2c3d4_12345_1720000000.123",
  "full_name": "John Updated",
  "email": "",
  "avatar_url": "https://example.com/avatar.png",
  "phone": ""
}

// 响应
{
  "result": "success",
  "message": "资料更新成功",
  "timestamp": 1720000000.123
}
```

---

## 默认管理员账户

admin 种子逻辑随登录一并内置到网关（网关 lifespan 的 `setup_auth_store`
→ `chongming_auth.seed_admin`，幂等，多进程并发启动安全），不再依赖本插件。
数据库 `auth.db` 本插件仍由 `Plugin` 基类统一初始化并在 cleanup 时释放。

首次启动时自动创建：

| 字段         | 值                    |
| ------------ | --------------------- |
| **用户名**   | `admin`               |
| **密码**     | `admin`               |
| **邮箱**     | `admin@example.com`   |
| **超管权限** | `is_superuser = true` |

> ⚠️ **生产环境务必修改默认密码！**

---

## 安全说明

- 密码使用 **Argon2id**（Rust 实现），对抗 GPU/ASIC 暴力破解
- JWT 使用 **HS256** 算法，密钥在 `config.toml` 的 `[security]` 节配置
- JWT 有效期 3 小时，过期后需重新登录
- 支持用户软禁用（`is_active = false`）
- 接口级鉴权控制：每个端点可通过 TOML 的 `auth_required` 独立配置

---

## 依赖

| 工具包               | 用途                                 |
| -------------------- | ------------------------------------ |
| `chongming-auth`     | Users 模型 / 建库 / 登录校验 / 签发（共享契约） |
| `chongming-database` | 异步 SQLite 数据库操作               |
| `chongming-config`   | 全局配置加载                         |
| `chongming-worker`   | `@rpc_method` 装饰器 + Worker 运行时 |