cursor-init/prd/M2-基础用户系统-详细设计.back.md

M2 - 基础用户系统 - 详细设计 (V2)

---

1. 引言

1.1. 文档目的

本文档是 "M2 - 基础用户系统" 阶段的 V2 修订版，旨在提供一份详尽、准确、可直接用于开发的技术设计方案。V2 版根据反馈进行了全面重构，重点增强了数据库设计的合理性、API定义的完整性，并补充了关键的 root 用户机制和标签功能。

1.2. 模块范围

本设计覆盖功能点包括：

• 用户认证（注册、登录）及 root 超级管理员机制。
• 用户、角色、权限、组织、字典的CRUD管理，支持层级结构。
• 用户标签系统。
• 基于角色的访问控制（RBAC）的实现。

---

2. 数据库设计 (Revised)

2.1. E-R 图 (Entity-Relationship Diagram)

已更新，包含标签和重构后的字典表

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 通用错误响应结构:

{
  "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):

  { "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):

  { "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. 接口参数范围，校验