expressgy
2518986557
✨ 新增功能设计文档： - M2基础用户系统数据库设计（12个核心表，RBAC权限模型） - M2基础用户系统接口设计（41个API接口，含排序功能） - 完整的项目需求文档和开发计划 📚 核心文档结构： - 数据库设计：支持树形结构、软删除、审计日志的完整用户权限体系 - 接口设计：包含认证、用户管理、角色权限、组织架构、字典标签等9大模块 - 排序功能：新增7个排序接口，支持拖拽和批量操作 - 项目规划：从MVP到完整生态的4阶段开发计划 🔧 技术栈确定： - 后端：Elysia + Bun.js + MySQL + Redis + Elasticsearch - 前端：Vue.js/React + TypeScript - 部署：Docker + Docker Compose - 测试：Vitest + 完整测试规范 📋 设计亮点： - 无外键约束设计，应用层维护数据完整性 - 树形结构支持（path、level字段优化查询） - 完整的权限继承机制和权限快照 - 支持root超级管理员和多级角色体系 - 标签系统和智能推荐功能 - 统一的响应格式和错误码规范 🎯 覆盖功能： - 用户认证与管理（注册、登录、权限控制） - RBAC角色权限体系（树形角色、权限继承） - 组织架构管理（多级组织、人员分配） - 数据字典与标签系统 - 完整的排序和数据导入导出功能 📈 文档规模： - 数据库设计：38KB，922行 - 接口设计：55KB，3024行 - 总计：约100KB的详细技术文档 🔄 配套更新： - 更新Elysia后端开发规范 - 完善健康检查控制器 - 统一项目代码规范和注释规范
249 lines
10 KiB
Markdown
249 lines
10 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. 接口参数范围，校验 |