# 美国版 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）

未开启图形验证码时：

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

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

```json
{
  "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 | 门店是否启用 |

### 响应示例

```json
{
  "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 解析。

### 传参示例

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

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

### 响应体

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

### 响应示例

```json
[
  {
    "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`** 字段，否则无法通过邮箱登录。