279 lines
9.5 KiB
Markdown
279 lines
9.5 KiB
Markdown
# M2 - 基础用户系统 - 详细设计 (V2)
|
||
|
||
---
|
||
|
||
## 1. 引言
|
||
|
||
### 1.1. 文档目的
|
||
|
||
本文档是 "M2 - 基础用户系统" 阶段的 **V2 修订版**，旨在提供一份详尽、准确、可直接用于开发的技术设计方案。V2 版根据反馈进行了全面重构，重点增强了数据库设计的合理性、API定义的完整性，并补充了关键的 `root` 用户机制和标签功能。
|
||
|
||
### 1.2. 模块范围
|
||
|
||
本设计覆盖功能点包括：
|
||
|
||
- 用户认证（注册、登录）及 `root` 超级管理员机制。
|
||
- 用户、角色、权限、组织、字典的CRUD管理，支持层级结构。
|
||
- 用户标签系统。
|
||
- 基于角色的访问控制（RBAC）的实现。
|
||
|
||
---
|
||
|
||
## 2. 数据库设计 (Revised)
|
||
|
||
### 2.1. E-R 图 (Entity-Relationship Diagram)
|
||
|
||
_已更新，包含标签和重构后的字典表_
|
||
|
||
```mermaid
|
||
erDiagram
|
||
users {
|
||
bigint id PK
|
||
varchar(50) username UK
|
||
varchar(255) email UK
|
||
varchar(255) password_hash
|
||
varchar(20) status
|
||
datetime created_at
|
||
datetime updated_at
|
||
}
|
||
|
||
roles {
|
||
bigint id PK
|
||
varchar(50) name UK
|
||
text description
|
||
bigint parent_id FK "nullable, self-ref"
|
||
datetime created_at
|
||
datetime updated_at
|
||
}
|
||
|
||
permissions {
|
||
bigint id PK
|
||
varchar(50) action UK
|
||
varchar(50) resource UK
|
||
text description
|
||
}
|
||
|
||
organizations {
|
||
bigint id PK
|
||
varchar(100) name
|
||
text description
|
||
bigint parent_id FK "nullable, self-ref"
|
||
datetime created_at
|
||
datetime updated_at
|
||
}
|
||
|
||
dictionary_types {
|
||
bigint id PK
|
||
varchar(50) type_name UK
|
||
text description
|
||
}
|
||
|
||
dictionary_items {
|
||
bigint id PK
|
||
bigint type_id FK
|
||
varchar(50) `key`
|
||
varchar(255) value
|
||
int sort_order
|
||
}
|
||
|
||
tags {
|
||
bigint id PK
|
||
varchar(50) name UK
|
||
}
|
||
|
||
users ||--o{ user_roles : "has"
|
||
roles ||--o{ user_roles : "assigned to"
|
||
roles ||--o{ role_permissions : "has"
|
||
permissions ||--o{ role_permissions : "granted to"
|
||
users ||--o{ user_organizations : "belongs to"
|
||
organizations ||--o{ user_organizations : "has"
|
||
users ||--o{ user_tags : "has"
|
||
tags ||--o{ user_tags : "applied to"
|
||
dictionary_types ||--o{ dictionary_items : "has"
|
||
|
||
roles }o..o| roles : "is child of"
|
||
organizations }o..o| organizations : "is child of"
|
||
|
||
user_roles { bigint user_id PK,FK; bigint role_id PK,FK }
|
||
role_permissions { bigint role_id PK,FK; bigint permission_id PK,FK }
|
||
user_organizations { bigint user_id PK,FK; bigint organization_id PK,FK }
|
||
user_tags { bigint user_id PK,FK; bigint tag_id PK,FK }
|
||
```
|
||
|
||
### 2.2. 表结构定义
|
||
|
||
#### `roles` / `organizations`
|
||
|
||
- **`parent_id`**: `BIGINT NULL`, `FOREIGN KEY (parent_id) REFERENCES roles(id) ON DELETE SET NULL`。此字段用于实现树形层级结构。值为`NULL`表示为顶级角色/组织。
|
||
|
||
#### `dictionary_types` - 字典类型表
|
||
|
||
| 字段名 | 类型 | 约束 | 描述 |
|
||
| ------------- | ------------- | -------------------- | ------------------------------- |
|
||
| `id` | `BIGINT` | `PK`, `AI` | 类型唯一ID |
|
||
| `type_name` | `VARCHAR(50)` | `UNIQUE`, `NOT NULL` | 字典类型名（如: `user_status`） |
|
||
| `description` | `TEXT` | | 类型描述 |
|
||
|
||
#### `dictionary_items` - 字典条目表
|
||
|
||
| 字段名 | 类型 | 约束 | 描述 |
|
||
| ------------ | -------------- | ---------------- | --------------------------- |
|
||
| `id` | `BIGINT` | `PK`, `AI` | 条目唯一ID |
|
||
| `type_id` | `BIGINT` | `NOT NULL`, `FK` | 关联到`dictionary_types.id` |
|
||
| `key` | `VARCHAR(50)` | `NOT NULL` | 键 (程序中使用) |
|
||
| `value` | `VARCHAR(255)` | `NOT NULL` | 值 (UI中显示) |
|
||
| `sort_order` | `INT` | `DEFAULT 0` | 排序字段 |
|
||
|
||
_复合唯一键: `(type_id, key)`_
|
||
|
||
#### `tags` - 标签表
|
||
|
||
| 字段名 | 类型 | 约束 | 描述 |
|
||
| ------ | ------------- | -------------------- | ---------- |
|
||
| `id` | `BIGINT` | `PK`, `AI` | 标签唯一ID |
|
||
| `name` | `VARCHAR(50)` | `UNIQUE`, `NOT NULL` | 标签名 |
|
||
|
||
#### `user_tags` - 用户标签关联表
|
||
|
||
| 字段名 | 类型 | 约束 | 描述 |
|
||
| --------- | -------- | ---------- | ---------- |
|
||
| `user_id` | `BIGINT` | `PK`, `FK` | 关联用户ID |
|
||
| `tag_id` | `BIGINT` | `PK`, `FK` | 关联标签ID |
|
||
|
||
---
|
||
|
||
## 3. Root 用户与系统初始化
|
||
|
||
- **`root` 用户**:
|
||
- `root` 是一个特殊的超级管理员账户，拥有系统中所有权限。
|
||
- 此账户 **不可通过 API 创建或删除**。它应在系统首次部署时，通过数据库 **Seeding (种子填充) 脚本** 创建。
|
||
- `root` 用户的角色是固定的（如 `super_admin`），此角色同样通过 Seeding 创建，并关联所有已定义的权限。
|
||
- 任何权限校验逻辑都必须对 `root` 用户或 `super_admin` 角色开绿灯。任何API都不能降低 `root` 的权限或删除该用户。
|
||
|
||
---
|
||
|
||
## 4. API 接口设计 (Detailed)
|
||
|
||
**Base URL**: `/api/v1`
|
||
**通用错误响应结构**:
|
||
|
||
```json
|
||
{
|
||
"code": 40001, // 详细业务错误码
|
||
"message": "Validation failed: username must be at least 3 characters.",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
### 3.1. Auth - 认证接口 (`/auth`)
|
||
|
||
#### `POST /register` - 用户注册
|
||
|
||
- **权限**: Public
|
||
- **请求体 (`application/json`)**:
|
||
| 名称 | 类型 | 必填 | 校验规则 | 描述 |
|
||
|------------|--------|------|----------------------------------------------------|----------------|
|
||
| `username` | string | 是 | min:3, max:50, 字母/数字/下划线组合 | 用户名 |
|
||
| `email` | string | 是 | valid email format | 邮箱地址 |
|
||
| `password` | string | 是 | min:8, max:100, 必须包含大小写字母和数字 | 密码 |
|
||
- **成功响应 (201 Created)**:
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "User registered successfully.",
|
||
"data": { "id": 1, "username": "newuser", "email": "..." }
|
||
}
|
||
```
|
||
- **异常响应**:
|
||
| HTTP 码 | 业务码 | 原因 |
|
||
|---------|----------|----------------------------|
|
||
| 400 | 40001 | 请求参数不符合校验规则 |
|
||
| 409 | 40901 | 用户名或邮箱已被占用 |
|
||
|
||
#### `POST /login` - 用户登录
|
||
|
||
- **权限**: Public
|
||
- **请求体 (`application/json`)**:
|
||
| 名称 | 类型 | 必填 | 校验规则 | 描述 |
|
||
|------------|--------|------|------------------|------------------|
|
||
| `username` | string | 是 | - | 用户名或邮箱 |
|
||
| `password` | string | 是 | - | 密码 |
|
||
- **成功响应 (200 OK)**:
|
||
```json
|
||
{ "code": 0, "message": "Login successful.", "data": { "token": "ey..." } }
|
||
```
|
||
- **异常响应**:
|
||
| HTTP 码 | 业务码 | 原因 |
|
||
|---------|----------|--------------------------|
|
||
| 401 | 40101 | 用户名或密码错误 |
|
||
| 401 | 40102 | 账户被禁用或未激活 |
|
||
|
||
---
|
||
|
||
### 3.2. Users - 用户接口 (`/users`)
|
||
|
||
_除特殊说明外，均需认证_
|
||
|
||
#### `GET /me` - 获取当前用户信息
|
||
|
||
- **权限**: Authenticated
|
||
- **成功响应 (200 OK)**: `data` 包含当前用户详细信息、关联的角色和权限列表。
|
||
|
||
#### `GET /` - 获取用户列表
|
||
|
||
- **权限**: `read:users`
|
||
- **查询参数**:
|
||
| 名称 | 类型 | 必填 | 描述 |
|
||
|-----------|--------|------|------------------------------------|
|
||
| `page` | number | 否 | 页码, default 1 |
|
||
| `pageSize`| number | 否 | 每页数量, default 10 |
|
||
| `keyword` | string | 否 | 按用户名或邮箱模糊搜索 |
|
||
- **成功响应 (200 OK)**: `data` 包含 `items` (用户列表) 和 `pagination` (分页信息)。
|
||
|
||
#### `PUT /{userId}/status` - 更新用户状态
|
||
|
||
- **权限**: `update:user_status`
|
||
- **请求体**: `{ "status": "active" }` (status 必须是字典中 `user_status` 类型的值)
|
||
- **成功响应 (200 OK)**: 返回更新后的用户信息。
|
||
- **异常响应**:
|
||
| HTTP 码 | 业务码 | 原因 |
|
||
|---------|----------|--------------------------|
|
||
| 403 | 40301 | 试图修改 `root` 用户状态 |
|
||
| 404 | 40401 | 指定用户不存在 |
|
||
|
||
#### `POST /{userId}/tags` - 为用户打标签
|
||
|
||
- **权限**: `update:user_tags`
|
||
- **请求体**: `{ "tagIds": [1, 2, 3] }`
|
||
- **成功响应 (204 No Content)**.
|
||
|
||
---
|
||
|
||
### 3.3. Roles - 角色接口 (`/roles`)
|
||
|
||
_所有接口均需 `manage:roles` 权限_
|
||
|
||
#### `GET /` - 获取角色列表
|
||
|
||
- **描述**: 以树形结构返回所有角色。
|
||
- **成功响应 (200 OK)**: `data` 是一个包含 `children` 属性的树形数组。
|
||
|
||
#### `POST /` - 创建新角色
|
||
|
||
- **请求体**: `{ "name": "editor", "description": "...", "parentId": 1, "permissionIds": [101, 102] }`
|
||
- **成功响应 (201 Created)**: `data` 包含新创建的角色信息。
|
||
- **异常响应 (409 Conflict)**: 角色名已存在。
|
||
|
||
---
|
||
|
||
_其他模块（Organizations, Dictionaries, Tags）的API将遵循类似的详细设计模式：提供完整的增删改查接口，明确定义权限、请求体、校验规则和所有可能的成功/异常响应。_
|
||
|
||
# 补充说明
|
||
|
||
1. 你忽略了我在main.md中提到的root用户，所以缺少一类集中管理的接口和机制，请认真阅读
|
||
2. 接口设计太简陋了，太粗略了，需要把异常情况考虑进去，
|
||
3. 数据库设计完全无法满足需求，没有pid如何实现层级结构
|
||
4. 字典确实，无法完成拓展任务
|
||
5. 标签功能呢
|
||
6. 接口参数范围，校验
|