接口文档工具与API设计实践

项目文档/
├── 01-项目说明/
│   ├── 项目简介
│   ├── 技术栈说明
│   ├── 团队成员
│   └── 开发规范
├── 02-变更日志/
│   ├── WIP（进行中）
│   ├── v1.1.0
│   └── v1.0.0
├── 03-数据库设计/
│   ├── 用户表（users）
│   ├── 订单表（orders）
│   └── 数据字典
├── 04-功能模块/
│   ├── 首页模块/
│   │   ├── 首页-轮播图接口
│   │   └── 首页-推荐列表接口
│   ├── 用户模块/
│   │   ├── 用户-登录接口
│   │   └── 用户-注册接口
│   └── 订单模块/
│       ├── 订单-创建接口
│       └── 订单-列表接口
└── 05-附录/
    ├── 错误码说明
    ├── 通用参数说明
    └── 版本规划

# 变更日志

## [WIP] - 进行中
### 新增
- [用户模块] 用户登录接口

## [v1.1.0] - 2024-02-01
### 新增
- [商品模块] 商品搜索接口
### 修复
- [订单模块] 修复订单列表分页问题

## [v1.0.0] - 2024-01-01
### 新增
- [用户模块] 用户登录/注册接口
- [商品模块] 商品列表接口

# conventional-changelog
npm install -g conventional-changelog-cli
conventional-changelog -p angular -i CHANGELOG.md -s

CREATE TABLE users (
  id INT PRIMARY KEY AUTO_INCREMENT COMMENT '用户ID',
  username VARCHAR(50) NOT NULL UNIQUE COMMENT '用户名',
  password VARCHAR(255) NOT NULL COMMENT '密码（bcrypt加密）',
  nickname VARCHAR(50) COMMENT '昵称',
  email VARCHAR(100) UNIQUE COMMENT '邮箱',
  phone VARCHAR(20) UNIQUE COMMENT '手机号',
  avatar VARCHAR(255) COMMENT '头像URL',
  role ENUM('user', 'admin') DEFAULT 'user' COMMENT '角色',
  status TINYINT DEFAULT 1 COMMENT '状态：1-正常，0-禁用',
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  INDEX idx_username (username),
  INDEX idx_email (email)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户表';

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": 1,
      "username": "testuser",
      "nickname": "测试用户",
      "role": "user"
    }
  }
}

// 统一响应结构
interface ApiResponse<T> {
  code: number
  message: string
  data: T
}

// 分页响应
interface PaginatedData<T> {
  list: T[]
  pagination: {
    page: number
    size: number
    total: number
    totalPages: number
  }
}

// 用户实体
interface User {
  id: number
  username: string
  nickname: string
  email: string
  avatar: string
  role: 'user' | 'admin'
}