# 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. 接口参数范围,校验