{
  "openapi": "3.0.3",
  "info": {
    "title": "YwxApp 标准 App 接口 v1",
    "description": "YwxApp App/小程序/第三方客户端标准接口。\n\n统一响应：{\"code\":0,\"msg\":\"success\",\"data\":{},\"timestamp\":1765900000}\n- code=0 成功；code=1 业务失败；code=401 未登录/鉴权失败\n- 业务 code 与 HTTP 状态码解耦（未登录时 HTTP 状态也为 401）\n- 需登录接口在 Header 携带 Authorization: Bearer <access_token>\n- 登录类接口 data 内含 access_token / refresh_token / expires_in；响应顶层也回写 token 字段",
    "version": "1.0.0"
  },
  "servers": [
    { "url": "http://localhost/api/v1", "description": "本地开发" }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "ApiResponse": {
        "type": "object",
        "required": ["code", "msg", "timestamp"],
        "properties": {
          "code": { "type": "integer", "description": "0=成功 1=业务失败 401=未登录", "example": 0 },
          "msg": { "type": "string", "description": "提示信息", "example": "success" },
          "data": { "type": "object", "nullable": true, "description": "业务数据" },
          "timestamp": { "type": "integer", "description": "服务器时间戳(秒)", "example": 1765900000 }
        }
      },
      "LoginData": {
        "type": "object",
        "properties": {
          "uid": { "type": "integer", "example": 1 },
          "account": { "type": "string", "example": "testuser" },
          "nickname": { "type": "string", "example": "测试用户" },
          "mobile": { "type": "string", "example": "" },
          "email": { "type": "string", "example": "" },
          "avatar": { "type": "string", "example": "" },
          "status": { "type": "integer", "example": 1 },
          "access_token": { "type": "string", "example": "eyJ0eXAiOiJKV1Q..." },
          "refresh_token": { "type": "string", "example": "def50200..." },
          "expires_in": { "type": "integer", "example": 3600 },
          "token_type": { "type": "string", "example": "Bearer" }
        }
      },
      "ProfileData": {
        "type": "object",
        "properties": {
          "uid": { "type": "integer", "example": 1 },
          "account": { "type": "string", "example": "testuser" },
          "nickname": { "type": "string", "example": "测试用户" },
          "mobile": { "type": "string", "example": "" },
          "email": { "type": "string", "example": "" },
          "avatar": { "type": "string", "example": "" },
          "status": { "type": "integer", "example": 1 },
          "status_text": { "type": "string", "example": "正常" },
          "last_login": { "type": "string", "example": "2026-08-17 10:00:00" }
        }
      }
    }
  },
  "security": [{ "bearerAuth": [] }],
  "paths": {
    "/common/init": {
      "get": {
        "tags": ["Common"],
        "summary": "启动初始化",
        "description": "App 冷启动首屏调用，返回站点信息/注册方式/版本。公开。",
        "security": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiResponse" },
                "example": {
                  "code": 0, "msg": "success",
                  "data": { "site": {}, "register_type": "all", "version": "1.0.0" },
                  "timestamp": 1765900000
                }
              }
            }
          }
        }
      }
    },
    "/common/config": {
      "get": {
        "tags": ["Common"],
        "summary": "站点配置",
        "security": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiResponse" },
                "example": { "code": 0, "msg": "success", "data": { "site": {} }, "timestamp": 1765900000 }
              }
            }
          }
        }
      }
    },
    "/common/upload": {
      "post": {
        "tags": ["Common"],
        "summary": "文件上传(需登录)",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": { "file": { "type": "string", "format": "binary" } }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiResponse" },
                "example": {
                  "code": 0, "msg": "上传成功",
                  "data": { "url": "/storage/uploads/xxx.png", "path": "uploads/xxx.png" },
                  "timestamp": 1765900000
                }
              }
            }
          }
        }
      }
    },
    "/user/register": {
      "post": {
        "tags": ["User"],
        "summary": "注册",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": ["account", "password"],
                "properties": {
                  "account": { "type": "string", "example": "testuser" },
                  "password": { "type": "string", "example": "123456", "description": "至少6位" },
                  "nickname": { "type": "string", "example": "测试用户" },
                  "mobile": { "type": "string", "example": "13800138000" },
                  "email": { "type": "string", "example": "user@example.com" },
                  "captcha": { "type": "string", "example": "1234", "description": "手机号注册时必填" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "注册成功并签发 token",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiResponse" },
                "example": {
                  "code": 0, "msg": "注册成功",
                  "data": { "uid": 1, "account": "testuser", "access_token": "eyJ...", "refresh_token": "def...", "expires_in": 3600, "token_type": "Bearer" },
                  "access_token": "eyJ...", "access_expired": 3600, "refresh_token": "def...", "refresh_expired": 86400,
                  "timestamp": 1765900000
                }
              }
            }
          }
        }
      }
    },
    "/user/login": {
      "post": {
        "tags": ["User"],
        "summary": "账号密码登录",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": ["account", "password"],
                "properties": {
                  "account": { "type": "string", "example": "testuser" },
                  "password": { "type": "string", "example": "123456" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "登录成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiResponse" },
                "example": {
                  "code": 0, "msg": "登录成功",
                  "data": { "uid": 1, "access_token": "eyJ...", "refresh_token": "def...", "expires_in": 3600 },
                  "timestamp": 1765900000
                }
              }
            }
          }
        }
      }
    },
    "/user/loginBySms": {
      "post": {
        "tags": ["User"],
        "summary": "短信验证码登录(未注册自动注册)",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": ["mobile", "captcha"],
                "properties": {
                  "mobile": { "type": "string", "example": "13800138000" },
                  "captcha": { "type": "string", "example": "1234" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiResponse" },
                "example": { "code": 0, "msg": "登录成功", "data": { "uid": 1, "access_token": "eyJ...", "refresh_token": "def..." }, "timestamp": 1765900000 }
              }
            }
          }
        }
      }
    },
    "/user/refresh": {
      "post": {
        "tags": ["User"],
        "summary": "刷新 access_token",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": ["refresh_token"],
                "properties": { "refresh_token": { "type": "string", "example": "def50200..." } }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "刷新成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiResponse" },
                "example": { "code": 0, "msg": "刷新成功", "data": { "access_token": "eyJ...", "refresh_token": "def...", "expires_in": 3600 }, "timestamp": 1765900000 }
              }
            }
          },
          "401": {
            "description": "refresh_token 失效",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiResponse" },
                "example": { "code": 401, "msg": "refresh_token 无效或已过期", "timestamp": 1765900000 }
              }
            }
          }
        }
      }
    },
    "/user/logout": {
      "post": {
        "tags": ["User"],
        "summary": "退出登录(需登录)",
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiResponse" },
                "example": { "code": 0, "msg": "已登出", "data": [], "timestamp": 1765900000 }
              }
            }
          }
        }
      }
    },
    "/user/profile": {
      "get": {
        "tags": ["User"],
        "summary": "获取会员资料(需登录)",
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiResponse" },
                "example": { "code": 0, "msg": "success", "data": { "uid": 1, "account": "testuser", "nickname": "测试", "status": 1, "status_text": "正常", "last_login": "2026-08-17 10:00:00" }, "timestamp": 1765900000 }
              }
            }
          },
          "401": {
            "description": "未登录",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiResponse" },
                "example": { "code": 401, "msg": "请先登录", "timestamp": 1765900000 }
              }
            }
          }
        }
      }
    },
    "/user/updateProfile": {
      "post": {
        "tags": ["User"],
        "summary": "修改资料(需登录)",
        "requestBody": {
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "nickname": { "type": "string", "example": "新昵称" },
                  "mobile": { "type": "string", "example": "13800138000" },
                  "email": { "type": "string", "example": "user@example.com" },
                  "avatar": { "type": "string", "example": "" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiResponse" },
                "example": { "code": 0, "msg": "保存成功", "data": { "uid": 1, "nickname": "新昵称" }, "timestamp": 1765900000 }
              }
            }
          }
        }
      }
    },
    "/user/changePwd": {
      "post": {
        "tags": ["User"],
        "summary": "修改密码(需登录)",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": ["oldpassword", "newpassword"],
                "properties": {
                  "oldpassword": { "type": "string", "example": "123456" },
                  "newpassword": { "type": "string", "example": "654321", "description": "至少6位" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiResponse" },
                "example": { "code": 0, "msg": "密码修改成功", "data": [], "timestamp": 1765900000 }
              }
            }
          }
        }
      }
    },
    "/user/resetPwdBySms": {
      "post": {
        "tags": ["User"],
        "summary": "短信重置密码(免登录)",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": ["mobile", "captcha", "newpassword"],
                "properties": {
                  "mobile": { "type": "string", "example": "13800138000" },
                  "captcha": { "type": "string", "example": "1234" },
                  "newpassword": { "type": "string", "example": "654321" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiResponse" },
                "example": { "code": 0, "msg": "密码重置成功", "data": [], "timestamp": 1765900000 }
              }
            }
          }
        }
      }
    },
    "/user/resetPwdByEmail": {
      "post": {
        "tags": ["User"],
        "summary": "邮箱重置密码(免登录)",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": ["email", "captcha", "newpassword"],
                "properties": {
                  "email": { "type": "string", "example": "user@example.com" },
                  "captcha": { "type": "string", "example": "1234" },
                  "newpassword": { "type": "string", "example": "654321" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiResponse" },
                "example": { "code": 0, "msg": "密码重置成功", "data": [], "timestamp": 1765900000 }
              }
            }
          }
        }
      }
    },
    "/sms/send": {
      "post": {
        "tags": ["验证码"],
        "summary": "发送短信验证码",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": ["mobile", "event"],
                "properties": {
                  "mobile": { "type": "string", "example": "13800138000" },
                  "event": { "type": "string", "example": "register", "description": "register/login/mobilelogin/resetpwd/changepwd/changemobile" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiResponse" },
                "example": { "code": 0, "msg": "发送成功", "data": [], "timestamp": 1765900000 }
              }
            }
          }
        }
      }
    },
    "/sms/check": {
      "post": {
        "tags": ["验证码"],
        "summary": "校验短信验证码",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": ["mobile", "event", "captcha"],
                "properties": {
                  "mobile": { "type": "string", "example": "13800138000" },
                  "event": { "type": "string", "example": "register" },
                  "captcha": { "type": "string", "example": "1234" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiResponse" },
                "example": { "code": 0, "msg": "成功", "data": [], "timestamp": 1765900000 }
              }
            }
          }
        }
      }
    },
    "/ems/send": {
      "post": {
        "tags": ["验证码"],
        "summary": "发送邮箱验证码",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": ["email"],
                "properties": {
                  "email": { "type": "string", "example": "user@example.com" },
                  "event": { "type": "string", "example": "register" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiResponse" },
                "example": { "code": 0, "msg": "发送成功", "data": [], "timestamp": 1765900000 }
              }
            }
          }
        }
      }
    },
    "/ems/check": {
      "post": {
        "tags": ["验证码"],
        "summary": "校验邮箱验证码",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": ["email", "captcha"],
                "properties": {
                  "email": { "type": "string", "example": "user@example.com" },
                  "event": { "type": "string", "example": "register" },
                  "captcha": { "type": "string", "example": "1234" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiResponse" },
                "example": { "code": 0, "msg": "验证码正确", "data": [], "timestamp": 1765900000 }
              }
            }
          }
        }
      }
    }
  }
}