美国版 App 登录接口说明

概述

美国版移动端认证由 food-labeling-us 模块的 UsAppAuthAppService 提供，采用 ABP 约定式动态 API。宿主统一前缀为 /api/app，建议以 Swagger 为准核对路径（本地示例：http://localhost:19001/swagger，搜索 UsAppAuth）。

说明	内容
账号标识	使用 User.Email（邮箱）登录，邮箱比对忽略大小写
密码	与 Web 共用 User 表，校验方式与 RBAC AccountManager 一致（盐值 + MD5Helper.SHA2Encode）
权限	App 登录不校验角色/权限（允许“未配置权限”的账号登录）；H5 管理端再按 RBAC 权限控制
验证码	当配置 Rbac:EnableCaptcha 为 true 时，需先拉取图形验证码，本接口入参传 uuid、code；未开启时可传空或不传

---

接口 1：App 登录

签发 Access Token、Refresh Token，并返回当前用户在 userlocation 中绑定的门店列表（关联 location 表详情）。

HTTP

• 方法：POST
• 路径：/api/app/us-app-auth/login
• Content-Type：application/json
• 鉴权：无需登录（匿名）

请求体参数（UsAppLoginInputVo）

参数名（JSON）	类型	必填	说明
email	string	是	登录邮箱，对应数据库 User.Email
password	string	是	明文密码
uuid	string	条件	图形验证码 UUID；开启验证码时必填
code	string	条件	图形验证码；开启验证码时必填

传参示例（请求 Body）

未开启图形验证码时：

{
  "email": "admin@example.com",
  "password": "123456"
}

开启图形验证码时（需与系统验证码接口返回的 uuid、用户输入的验证码一致）：

{
  "email": "test@example.com",
  "password": "您的密码",
  "uuid": "验证码接口返回的 uuid",
  "code": "用户看到的验证码"
}

响应体（UsAppLoginOutputDto）

字段（JSON）	类型	说明
token	string	访问令牌（Bearer），后续业务接口放在 Header Authorization: Bearer {token}
refreshToken	string	刷新令牌（与系统账号体系一致，用于刷新 access token，具体用法与 Web 一致）
locations	array	绑定门店列表，元素见下表

locations[] 元素（UsAppBoundLocationDto）

字段（JSON）	类型	说明
id	string	门店主键（Guid 字符串）
locationCode	string	业务编码，如 LOC-1
locationName	string	门店名称
fullAddress	string	拼接后的完整地址（街道、城市、州、邮编等；无数据时可能为 "无"）
state	bool	门店是否启用

响应示例

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "locations": [
    {
      "id": "a2696b9e-2277-11f1-b4c6-00163e0c7c4f",
      "locationCode": "LOC-1",
      "locationName": "Downtown Kitchen",
      "fullAddress": "123 Main St, New York, NY 10001",
      "state": true
    }
  ]
}

常见错误提示（业务异常文案）

• 邮箱或密码为空：请输入合理数据！
• 邮箱在库中不存在（未删除且启用用户中无匹配邮箱）：登录失败！邮箱不存在！
• 密码错误：登录失败！用户名或密码错误！（与 UserConst.Login_Error 一致）
• 验证码错误（开启验证码时）：验证码错误

---

接口 2：获取当前账号绑定门店

无需重新登录即可刷新 userlocation 绑定门店列表（例如切换门店前先同步列表）。

HTTP

• 方法：GET
• 路径：/api/app/us-app-auth/my-locations
• 鉴权：需要登录，请求头携带 Authorization: Bearer {token}（使用接口 1 返回的 token）

请求参数

无 Query / Body 参数；用户身份由 JWT 解析。

传参示例

GET /api/app/us-app-auth/my-locations HTTP/1.1
Host: localhost:19001
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

若前端统一约定 GET 使用 data 封装，可自行在客户端组装；本接口服务端不读取额外 Query 参数。

响应体

与登录接口中 locations 相同：UsAppBoundLocationDto[]（数组）。

响应示例

[
  {
    "id": "a2696b9e-2277-11f1-b4c6-00163e0c7c4f",
    "locationCode": "LOC-1",
    "locationName": "Downtown Kitchen",
    "fullAddress": "123 Main St, New York, NY 10001",
    "state": true
  }
]

常见错误

• 未登录或 Token 无效：按网关/ABP 返回 401 及统一错误体
• 无用户上下文：用户未登录

---

与其他登录方式的区别

场景	说明
Web 管理端	仍使用 RBAC AccountService.PostLoginAsync，一般为人 userName + 密码
美国版 App	仅本模块 /api/app/us-app-auth/login 使用 邮箱 + 密码

两者共用同一 User 表与 JWT 体系；App 端需保证账号已维护 Email 字段，否则无法通过邮箱登录。