feat(架构): 完善基础架构设计

docs/swagger/swagger.yaml

@@ -0,0 +1,397 @@
+basePath: /api/v1
+definitions:
+  dto.ChangePasswordRequest:
+    properties:
+      code:
+        example: "123456"
+        type: string
+      confirm_new_password:
+        example: newpassword123
+        type: string
+      new_password:
+        example: newpassword123
+        maxLength: 128
+        minLength: 6
+        type: string
+      old_password:
+        example: oldpassword123
+        type: string
+    required:
+    - code
+    - confirm_new_password
+    - new_password
+    - old_password
+    type: object
+  dto.LoginResponse:
+    properties:
+      access_token:
+        example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+        type: string
+      expires_in:
+        example: 86400
+        type: integer
+      login_method:
+        description: password 或 sms
+        example: password
+        type: string
+      token_type:
+        example: Bearer
+        type: string
+      user:
+        $ref: '#/definitions/dto.UserResponse'
+    type: object
+  dto.LoginWithPasswordRequest:
+    properties:
+      password:
+        example: password123
+        type: string
+      phone:
+        example: "13800138000"
+        type: string
+    required:
+    - password
+    - phone
+    type: object
+  dto.LoginWithSMSRequest:
+    properties:
+      code:
+        example: "123456"
+        type: string
+      phone:
+        example: "13800138000"
+        type: string
+    required:
+    - code
+    - phone
+    type: object
+  dto.RegisterRequest:
+    properties:
+      code:
+        example: "123456"
+        type: string
+      confirm_password:
+        example: password123
+        type: string
+      password:
+        example: password123
+        maxLength: 128
+        minLength: 6
+        type: string
+      phone:
+        example: "13800138000"
+        type: string
+    required:
+    - code
+    - confirm_password
+    - password
+    - phone
+    type: object
+  dto.SendCodeRequest:
+    properties:
+      phone:
+        example: "13800138000"
+        type: string
+      scene:
+        allOf:
+        - $ref: '#/definitions/entities.SMSScene'
+        enum:
+        - register
+        - login
+        - change_password
+        - reset_password
+        - bind
+        - unbind
+        example: register
+    required:
+    - phone
+    - scene
+    type: object
+  dto.SendCodeResponse:
+    properties:
+      expires_at:
+        example: "2024-01-01T00:05:00Z"
+        type: string
+      message:
+        example: 验证码发送成功
+        type: string
+    type: object
+  dto.UserResponse:
+    properties:
+      created_at:
+        example: "2024-01-01T00:00:00Z"
+        type: string
+      id:
+        example: 123e4567-e89b-12d3-a456-426614174000
+        type: string
+      phone:
+        example: "13800138000"
+        type: string
+      updated_at:
+        example: "2024-01-01T00:00:00Z"
+        type: string
+    type: object
+  entities.SMSScene:
+    enum:
+    - register
+    - login
+    - change_password
+    - reset_password
+    - bind
+    - unbind
+    type: string
+    x-enum-comments:
+      SMSSceneBind: 绑定手机号
+      SMSSceneChangePassword: 修改密码
+      SMSSceneLogin: 登录
+      SMSSceneRegister: 注册
+      SMSSceneResetPassword: 重置密码
+      SMSSceneUnbind: 解绑手机号
+    x-enum-varnames:
+    - SMSSceneRegister
+    - SMSSceneLogin
+    - SMSSceneChangePassword
+    - SMSSceneResetPassword
+    - SMSSceneBind
+    - SMSSceneUnbind
+host: localhost:8080
+info:
+  contact:
+    email: support@example.com
+    name: API Support
+    url: https://github.com/your-org/tyapi-server-gin
+  description: |-
+    基于DDD和Clean Architecture的企业级后端API服务
+    采用Gin框架构建，支持用户管理、JWT认证、事件驱动等功能
+  license:
+    name: Apache 2.0
+    url: http://www.apache.org/licenses/LICENSE-2.0.html
+  title: TYAPI Server API
+  version: "1.0"
+paths:
+  /users/login-password:
+    post:
+      consumes:
+      - application/json
+      description: 使用手机号和密码进行用户登录，返回JWT令牌
+      parameters:
+      - description: 密码登录请求
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/dto.LoginWithPasswordRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: 登录成功
+          schema:
+            $ref: '#/definitions/dto.LoginResponse'
+        "400":
+          description: 请求参数错误
+          schema:
+            additionalProperties: true
+            type: object
+        "401":
+          description: 认证失败
+          schema:
+            additionalProperties: true
+            type: object
+        "500":
+          description: 服务器内部错误
+          schema:
+            additionalProperties: true
+            type: object
+      summary: 用户密码登录
+      tags:
+      - 用户认证
+  /users/login-sms:
+    post:
+      consumes:
+      - application/json
+      description: 使用手机号和短信验证码进行用户登录，返回JWT令牌
+      parameters:
+      - description: 短信登录请求
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/dto.LoginWithSMSRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: 登录成功
+          schema:
+            $ref: '#/definitions/dto.LoginResponse'
+        "400":
+          description: 请求参数错误或验证码无效
+          schema:
+            additionalProperties: true
+            type: object
+        "401":
+          description: 认证失败
+          schema:
+            additionalProperties: true
+            type: object
+        "500":
+          description: 服务器内部错误
+          schema:
+            additionalProperties: true
+            type: object
+      summary: 用户短信验证码登录
+      tags:
+      - 用户认证
+  /users/me:
+    get:
+      consumes:
+      - application/json
+      description: 根据JWT令牌获取当前登录用户的详细信息
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: 用户信息
+          schema:
+            $ref: '#/definitions/dto.UserResponse'
+        "401":
+          description: 未认证
+          schema:
+            additionalProperties: true
+            type: object
+        "404":
+          description: 用户不存在
+          schema:
+            additionalProperties: true
+            type: object
+        "500":
+          description: 服务器内部错误
+          schema:
+            additionalProperties: true
+            type: object
+      security:
+      - Bearer: []
+      summary: 获取当前用户信息
+      tags:
+      - 用户管理
+  /users/me/password:
+    put:
+      consumes:
+      - application/json
+      description: 使用旧密码、新密码确认和验证码修改当前用户的密码
+      parameters:
+      - description: 修改密码请求
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/dto.ChangePasswordRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: 密码修改成功
+          schema:
+            additionalProperties: true
+            type: object
+        "400":
+          description: 请求参数错误或验证码无效
+          schema:
+            additionalProperties: true
+            type: object
+        "401":
+          description: 未认证
+          schema:
+            additionalProperties: true
+            type: object
+        "500":
+          description: 服务器内部错误
+          schema:
+            additionalProperties: true
+            type: object
+      security:
+      - Bearer: []
+      summary: 修改密码
+      tags:
+      - 用户管理
+  /users/register:
+    post:
+      consumes:
+      - application/json
+      description: 使用手机号、密码和验证码进行用户注册，需要确认密码
+      parameters:
+      - description: 用户注册请求
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/dto.RegisterRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: 注册成功
+          schema:
+            $ref: '#/definitions/dto.UserResponse'
+        "400":
+          description: 请求参数错误或验证码无效
+          schema:
+            additionalProperties: true
+            type: object
+        "409":
+          description: 手机号已存在
+          schema:
+            additionalProperties: true
+            type: object
+        "500":
+          description: 服务器内部错误
+          schema:
+            additionalProperties: true
+            type: object
+      summary: 用户注册
+      tags:
+      - 用户认证
+  /users/send-code:
+    post:
+      consumes:
+      - application/json
+      description: 向指定手机号发送验证码，支持注册、登录、修改密码等场景
+      parameters:
+      - description: 发送验证码请求
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/dto.SendCodeRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: 验证码发送成功
+          schema:
+            $ref: '#/definitions/dto.SendCodeResponse'
+        "400":
+          description: 请求参数错误
+          schema:
+            additionalProperties: true
+            type: object
+        "429":
+          description: 请求频率限制
+          schema:
+            additionalProperties: true
+            type: object
+        "500":
+          description: 服务器内部错误
+          schema:
+            additionalProperties: true
+            type: object
+      summary: 发送短信验证码
+      tags:
+      - 用户认证
+securityDefinitions:
+  Bearer:
+    description: Type "Bearer" followed by a space and JWT token.
+    in: header
+    name: Authorization
+    type: apiKey
+swagger: "2.0"