expressgy/cursor-init
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
09a5dc30f1
cursor-init/prd/M2-基础用户系统-详细设计.back.md

9.5 KiB
Raw Blame History

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