ProjectAGiPrompt/8-CMII-RMDC/1-rmdc-system/login-api-specification.md

登录接口统一定义文档

版本信息

• 版本: v1.0
• 创建日期: 2026-01-15
• 最后更新: 2026-01-15

概述

本文档定义了 RMDC 系统登录接口的统一结构体规范，确保前端和后端之间的数据交互一致性。

后端定义 (Go)

文件位置

rmdc-user-auth/internal/model/dto/auth_dto.go

结构体定义

LoginRequest - 登录请求

type LoginRequest struct {
    Username          string `json:"username" binding:"required"`           // 用户名（中文真实姓名）
    Password          string `json:"password"`                              // 明文密码（已废弃，保持兼容）
    EncryptedPassword string `json:"encrypted_password" binding:"required"` // RSA加密后的密码
}

LoginResponse - 登录响应

type LoginResponse struct {
    Token              string   `json:"token"`                // JWT令牌
    User               *UserDTO `json:"user"`                 // 用户信息
    MustChangePassword bool     `json:"must_change_password"` // 是否必须修改密码
    PasswordExpireDays int      `json:"password_expire_days"` // 密码剩余天数（7天内提醒）
}

UserDTO - 用户信息传输对象

type UserDTO struct {
    ID              int64      `json:"id"`                        // 用户ID
    Username        string     `json:"username"`                  // 中文真实姓名
    EnglishUsername string     `json:"english_username"`          // 英文用户名
    AvatarID        string     `json:"avatar_id"`                 // 头像ID
    AvatarFrameID   string     `json:"avatar_frame_id"`           // 头像框ID
    Gender          string     `json:"gender"`                    // 性别: male/female
    Email           string     `json:"email"`                     // 邮箱
    Phone           string     `json:"phone"`                     // 手机号
    ShortNumber     string     `json:"short_number,omitempty"`    // 短号
    WorkID          string     `json:"work_id,omitempty"`         // 工号
    GroupName       string     `json:"group_name,omitempty"`      // 所属小组
    Company         string     `json:"company"`                   // 公司名称
    DevRole         string     `json:"dev_role"`                  // 开发角色: backend/frontend/testing/devops
    Role            string     `json:"role"`                      // RMDC系统角色: superadmin/admin/normal/third
    Status          string     `json:"status"`                    // 状态: active/locked/disabled
    RegisteredByID  int64      `json:"registered_by_id"`          // 注册人ID
    CreatedAt       time.Time  `json:"created_at"`                // 注册时间
    UpdatedAt       time.Time  `json:"updated_at"`                // 更新时间
    DeletedAt       *time.Time `json:"deleted_at,omitempty"`      // 删除时间
    LastLoginAt     *time.Time `json:"last_login_at,omitempty"`   // 最后登录时间
    PasswordExpires *time.Time `json:"password_expires,omitempty"` // 密码过期时间
}

前端定义 (TypeScript)

文件位置

frontend/src/types/api.ts

接口定义

LoginResponse - 登录响应

export interface LoginResponse {
    token: string                 // JWT令牌
    user: User                    // 用户信息
    must_change_password: boolean // 是否必须修改密码
    password_expire_days: number  // 密码剩余天数（7天内提醒）
}

User - 用户信息

export interface User {
    id: number
    username: string            // 中文真实姓名
    english_username: string    // 英文用户名
    avatar_id: string           // 头像ID
    avatar_frame_id: string     // 头像框ID
    gender: string              // 性别: male/female
    email: string               // 邮箱
    phone: string               // 手机号
    short_number?: string       // 短号
    work_id?: string            // 工号
    group_name?: string         // 所属小组
    company: string             // 公司名称
    dev_role: string            // 开发角色: backend/frontend/testing/devops
    role: string                // 用户角色: superadmin/admin/normal/third
    status: string              // 用户状态: active/locked/disabled
    registered_by_id: number    // 注册人ID
    created_at: string          // 注册时间
    updated_at: string          // 更新时间
    deleted_at?: string         // 删除时间
    last_login_at?: string      // 最后登录时间
    password_expires?: string   // 密码过期时间
}

API 接口规范

请求端点

POST /api/auth/login

请求体示例

{
    "username": "张三",
    "encrypted_password": "RSA加密后的密码字符串"
}

响应示例

成功响应 (HTTP 200)

{
    "code": 0,
    "status": 200,
    "timestamp": "2026-01-15T17:40:00Z",
    "message": "success",
    "data": {
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "user": {
            "id": 1,
            "username": "张三",
            "english_username": "zhangsan",
            "avatar_id": "default_1",
            "avatar_frame_id": "default",
            "gender": "male",
            "email": "zhangsan@example.com",
            "phone": "13800138000",
            "company": "示例公司",
            "dev_role": "backend",
            "role": "admin",
            "status": "active",
            "registered_by_id": 1,
            "created_at": "2026-01-01T00:00:00Z",
            "updated_at": "2026-01-15T17:40:00Z"
        },
        "must_change_password": false,
        "password_expire_days": 30
    }
}

失败响应 (HTTP 401)

{
    "code": 10003,
    "status": 401,
    "timestamp": "2026-01-15T17:40:00Z",
    "message": "用户名或密码错误",
    "data": null,
    "error": "invalid credentials"
}

字段映射对照表

后端字段 (Go)	前端字段 (TypeScript)	字段说明	必填
ID	id	用户ID	✓
Username	username	中文真实姓名	✓
EnglishUsername	english_username	英文用户名	✓
AvatarID	avatar_id	头像ID	✓
AvatarFrameID	avatar_frame_id	头像框ID	✓
Gender	gender	性别	✓
Email	email	邮箱	✓
Phone	phone	手机号	✓
ShortNumber	short_number	短号	×
WorkID	work_id	工号	×
GroupName	group_name	所属小组	×
Company	company	公司名称	✓
DevRole	dev_role	开发角色	✓
Role	role	用户角色	✓
Status	status	用户状态	✓
RegisteredByID	registered_by_id	注册人ID	✓
CreatedAt	created_at	注册时间	✓
UpdatedAt	updated_at	更新时间	✓
DeletedAt	deleted_at	删除时间	×
LastLoginAt	last_login_at	最后登录时间	×
PasswordExpires	password_expires	密码过期时间	×

关键改进点

1. 统一命名规范

• 前后端一致性: 所有字段名统一使用 snake_case (下划线命名)
• 修正: avatar_frame → avatar_frame_id（与后端保持一致）

2. 新增字段

• short_number: 短号（可选）
• work_id: 工号（可选）
• password_expires: 密码过期时间（可选）

3. 标准化响应结构

• 后端: 使用 dto.LoginResponse 替代 gin.H 直接返回
• 前端: 从 ApiResponse<LoginResponse> 中提取 data 字段

4. 类型安全

• 后端使用强类型 DTO 结构体
• 前端使用 TypeScript 接口定义
• 消除了隐式类型转换的风险

5. 密码安全

• 统一使用 RSA 加密传输密码
• 移除明文密码支持（保持向后兼容）

使用示例

后端 Handler 实现

func (h *AuthHandler) Login(c *gin.Context) {
    var req dto.LoginRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        wdd_res.ResponseErrorWithDetail(c, wdd_res.CodeValidationFail, "请求参数错误", err)
        return
    }

    // ... 业务逻辑 ...

    resp := dto.LoginResponse{
        Token:              token,
        User:               userDTO,
        MustChangePassword: mustChangePassword,
        PasswordExpireDays: passwordExpireDays,
    }

    wdd_res.ResponseSuccess(c, resp)
}

前端 Store 实现

async login(username: string, password: string): Promise<boolean> {
    const requestBody = {
        username,
        encrypted_password: await encryptPasswordWithPublicKey(password)
    }

    const apiResponse = await api.post<LoginResponse>('/auth/login', requestBody)
    
    if (apiResponse.code !== 0) {
        console.error('Login failed:', apiResponse.message)
        return false
    }

    const response = apiResponse.data
    this.token = response.token
    this.user = response.user
    this.mustChangePassword = response.must_change_password
    this.passwordExpireDays = response.password_expire_days

    localStorage.setItem('token', this.token)
    localStorage.setItem('user', JSON.stringify(this.user))

    return true
}

相关文件清单

后端文件

• rmdc-user-auth/internal/model/dto/auth_dto.go - 登录相关 DTO 定义
• rmdc-user-auth/internal/handler/auth_handler.go - 登录处理器
• rmdc-user-auth/internal/model/entity/user.go - 用户实体

前端文件

• frontend/src/types/api.ts - API 类型定义
• frontend/src/store/auth.ts - 认证状态管理
• frontend/src/api/index.ts - API 请求封装

遵循的规范文档

• 3-api-development-prompt.md - API 开发规范
• go-gin-gorm-style.md - Go/Gin/GORM 编码规范
• vue3-typescript-stye.md - Vue3/TypeScript 编码规范

版本历史

版本	日期	变更说明
v1.0	2026-01-15	初始版本，统一前后端登录接口定义