# 5-26 代码优化

本文档说明 **2026-05-26** 对美国版接口的变更。

1. **`/api/app/product-category`**：新增/编辑 **`categoryCode` 取消必填**（见 [product-category-categoryCode](#product-category-categorycode-可选)）。
2. **`/api/app/label-template`**：新增/编辑/列表/详情支持 **Region、Location 多选数组**；列表 Query 增加 **Region/Location 筛选**（见 [label-template-regionlocation](#label-template-regionlocation-多选)）。
3. **`/api/app/rbac-role`**：修复 **`accessPermissions` JSON 数组**（如 `manage_labels`）无法绑定菜单（见 [rbac-role-accesspermissions](#rbac-role-accesspermissions-修复)）。
4. **`/api/app/auth-scope`**：管理员（及按数据范围受限账号）登录后 **Company → Region → Location** 级联选店（见 [auth-scope-登录选店](#auth-scope-登录后-company--region--location-级联选店)）。
5. **`/api/app/us-app-auth`**：App 管理员 Token 专用 **Company / Region / 门店筛选** 接口（见 [us-app-auth-管理员选店](#us-app-auth-app-管理员级联选店)）。

**应用服务**：`ProductCategoryAppService`、`LabelTemplateAppService`、`RbacRoleAppService`  
**命名约定**（与 5-17 / 5-18 一致）：UI **Region** = API **`regionIds` / `groupIds` / `groupId`**（`fl_group.Id`）；UI **Location** = **`locationIds` / `locationId`**（`location.Id`）。

---

## product-category categoryCode 可选

**影响接口**

| 方法 | 路径 |
|------|------|
| POST | `/api/app/product-category` |
| PUT | `/api/app/product-category/{id}` |

### 变更说明

| 项 | 变更前 | 变更后 |
|----|--------|--------|
| **categoryCode** | 必填；空则报「类别编码和名称不能为空」 | **可选**；可不传、传 `null` 或 `""` |
| **categoryName** | 必填 | 仍必填 |
| **落库** | — | 未填编码时 `CategoryCode` 存 **空字符串** |
| **唯一性** | 编码或名称重复即报错 | 有编码：编码 **或** 名称重复报错；**无编码**：仅校验 **名称** 不重复 |

### 入参（节选）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| categoryCode | string | **否** | 类别编码 |
| categoryName | string | **是** | 类别名称 |
| regionIds / groupIds / locationIds | string[] | 否 | Region·Location 范围（规则见 `5-17接口优化.md`） |

### 请求示例（无编码）

```http
POST /api/app/product-category
Content-Type: application/json
Authorization: Bearer {token}
```

```json
{
  "categoryName": "Beverages",
  "buttonAppearance": "TEXT",
  "state": true,
  "availabilityType": "ALL",
  "orderNum": 0
}
```

### 联调注意

| 现象 | 处理 |
|------|------|
| 仍报「类别编码和名称不能为空」 | 确认已部署含本变更的后端；仅需保证 **categoryName** 非空 |
| 无编码时名称重复 | 正常：仅按 **categoryName** 判重 |

> Region/Location 多选、列表 `region`/`location` 展示等完整说明见 `5-17接口优化.md` → product-category 章节。

---

## label-template Region·Location 多选

**应用服务**：`LabelTemplateAppService`  
**存储表**：`fl_label_template_location`（模板 ↔ 门店，**无新表**）  
**主表字段**：`fl_label_template.AppliedLocationType` = `ALL` / `SPECIFIED`

### 变更说明

| 项 | 变更前 | 变更后 |
|----|--------|--------|
| **新增/编辑 Body** | 仅 `appliedLocation` + `appliedLocationIds` | 增加 **`regionIds`**、**`groupIds`**、**`locationIds`**（与 `appliedLocationIds` 合并） |
| **列表 Query** | 仅 `locationId` | 增加 **`groupId`**（Region）；`locationId` 优先于 `groupId`（与 product-category 一致） |
| **列表出参** | 仅 `locationText`（单条展示） | 增加 **`region`**、**`location`** 展示 + **`regionIds`**、**`locationIds`** 数组 |
| **详情出参** | `appliedLocationIds` | 同上，并保留 **`appliedLocationIds`**（与 `locationIds` 一致，兼容编辑器） |
| **范围解析** | 仅显式门店 Id | Region 展开为门店后与门店 Id **取并集** 落库 |

### 影响接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/app/label-template?SkipCount=1&MaxResultCount=10` | 列表支持 `groupId`/`locationId` 筛选；`items[]` 增加 `region`、`location`、`regionIds`、`locationIds` |
| GET | `/api/app/label-template/{id}` | 详情增加上述字段 |
| POST | `/api/app/label-template` | Body 支持 Region/Location 多选 |
| PUT | `/api/app/label-template/{id}` | 同新增 |

路径参数 **`id`** 仍为模板编码 **`TemplateCode`**（与编辑器 JSON 的 `id` 一致）。

### 新增/编辑入参（Body：`LabelTemplateCreateInputVo`）

| 字段 | JSON 名 | 类型 | 必填 | 说明 |
|------|---------|------|------|------|
| TemplateCode | `id` | string | 是 | 模板编码 |
| TemplateName | `name` | string | 是 | 模板名称 |
| AppliedLocationType | `appliedLocation` | string | 否 | `ALL` / `SPECIFIED`，默认 `ALL` |
| RegionIds | `regionIds` | string[] | 否 | Region 多选（`fl_group.Id`） |
| GroupIds | `groupIds` | string[] | 否 | 与 `regionIds` 等价，合并去重 |
| LocationIds | `locationIds` | string[] | 否 | 门店多选（`location.Id`） |
| AppliedLocationIds | `appliedLocationIds` | string[] | 否 | 兼容旧字段，与 `locationIds` 合并 |
| Elements | `elements` | array | 否 | 模板组件，全量重建 |
| TemplateProductDefaults | `templateProductDefaults` | array | 否 | 仅 **编辑** 时显式传入才重建 |

**自动规则**

| 入参 | 行为 |
|------|------|
| `regionIds` / `groupIds` / `locationIds` / `appliedLocationIds` 任一有有效 Id | `appliedLocation` 按 **`SPECIFIED`** 处理 |
| 仅传空数组 `[]` 且 `appliedLocation` 为 `ALL` | 不绑定门店（全部门店） |
| `appliedLocation: "SPECIFIED"` 且合并后无有效门店 | 报错：`指定适用区域或门店时，至少需要匹配到一个有效门店` |
| `appliedLocation` 非法值 | 报错：`适用门店范围不合法（ALL/SPECIFIED）` |

**合并规则**：每个 `regionIds` 展开为该 Region 下全部门店，再与 `locationIds`、`appliedLocationIds` **取并集** → 写入 `fl_label_template_location`。

### 请求示例（Region + 门店多选）

```http
POST /api/app/label-template
Content-Type: application/json
Authorization: Bearer {token}
```

```json
{
  "id": "TPL_TEST_001",
  "name": "Price Tag 4x6",
  "labelType": "PRICE",
  "unit": "inch",
  "width": 4,
  "height": 6,
  "appliedLocation": "SPECIFIED",
  "regionIds": [
    "fl_group_id_east",
    "fl_group_id_west"
  ],
  "locationIds": [
    "11111111-1111-1111-1111-111111111111"
  ],
  "showRuler": true,
  "showGrid": true,
  "state": true,
  "elements": []
}
```

### 请求示例（全部门店，兼容旧版）

```json
{
  "id": "TPL_ALL",
  "name": "Global Template",
  "labelType": "PRICE",
  "unit": "inch",
  "width": 4,
  "height": 6,
  "appliedLocation": "ALL",
  "appliedLocationIds": [],
  "elements": []
}
```

### 列表（`GET /api/app/label-template`）

**Query 参数**

| 字段 | 类型 | 说明 |
|------|------|------|
| SkipCount / MaxResultCount | int | 分页（项目约定 SkipCount 从 1 起） |
| keyword | string | 模板名称/编码模糊 |
| **groupId** | string | **按 Region 筛选**（`fl_group.Id`）：命中 `appliedLocation=ALL` 的模板，或在 `fl_label_template_location` 中绑定了该 Region 下任一门门店的模板 |
| **locationId** | string | **按门店筛选**（`location.Id`）；**优先于 groupId** |
| labelType | string | 如 `PRICE` |
| state | bool | 启用状态 |
| sorting | string | 排序（可选） |

**筛选规则**（与 product-category / label-type 相同，内部 `LocationScopeBindingHelper.ResolveScopedLocationIdsAsync`）

| 入参 | 行为 |
|------|------|
| 均未传 `groupId`、`locationId` | 不过滤适用范围 |
| 仅 `groupId` | 解析该 Region 下全部门店 Id，再筛模板 |
| 仅 `locationId` | 按该门店 Id 筛模板 |
| 同时传 | **以 `locationId` 为准**（忽略 `groupId`） |
| Region/门店无效或解析结果为空 | 仅返回 **`appliedLocation=ALL`** 的模板 |

命中条件（满足其一即可出现在列表）：

- `fl_label_template.AppliedLocationType = 'ALL'`
- `SPECIFIED` 且 `fl_label_template_location` 中存在 `LocationId ∈` 解析得到的门店集合

**请求示例**

```http
GET /api/app/label-template?SkipCount=1&MaxResultCount=10&groupId=fl_group_id_east HTTP/1.1
Authorization: Bearer {token}
```

```http
GET /api/app/label-template?SkipCount=1&MaxResultCount=10&locationId=11111111-1111-1111-1111-111111111111 HTTP/1.1
Authorization: Bearer {token}
```

**命名对照**：UI **Region** → Query **`groupId`**；UI **Location** → Query **`locationId`**。

### 列表出参

**`items[]` 新增/对齐字段**

| 字段 | 类型 | 说明 |
|------|------|------|
| region | string | 适用 Region 展示文案 |
| location | string | 适用门店展示文案 |
| regionIds | string[] | Region Id 多选；`ALL` 时为 `[]` |
| locationIds | string[] | 门店 Id 多选；`ALL` 时为 `[]` |
| locationText | string | **兼容字段**，与 `location` 相同 |

其它字段不变：`id`（= TemplateCode）、`templateName`、`contentsCount`、`sizeText`、`versionNo`、`lastEdited` 等。

**列表响应示例片段**

```json
{
  "pageIndex": 1,
  "pageSize": 10,
  "totalCount": 2,
  "items": [
    {
      "id": "TPL_ALL",
      "templateCode": "TPL_ALL",
      "templateName": "Global Template",
      "labelType": "PRICE",
      "region": "All Regions",
      "location": "All Locations",
      "locationText": "All Locations",
      "regionIds": [],
      "locationIds": [],
      "contentsCount": 5,
      "sizeText": "4x6inch",
      "versionNo": 1,
      "lastEdited": "2026-05-26T10:00:00"
    },
    {
      "id": "TPL_TEST_001",
      "templateName": "Price Tag 4x6",
      "region": "East Region, West Region",
      "location": "UNCC store, Central Park Store",
      "locationText": "UNCC store, Central Park Store",
      "regionIds": ["fl_group_id_east", "fl_group_id_west"],
      "locationIds": [
        "11111111-1111-1111-1111-111111111111",
        "22222222-2222-2222-2222-222222222222"
      ],
      "contentsCount": 3,
      "sizeText": "4x6inch",
      "versionNo": 2,
      "lastEdited": "2026-05-26T11:30:00"
    }
  ]
}
```

### 详情出参（`GET /api/app/label-template/{id}`）

在原有 `elements`、`templateProductDefaults`、`appliedLocationType` 等基础上增加：

| 字段 | 类型 | 说明 |
|------|------|------|
| region | string | 展示文案 |
| location | string | 展示文案 |
| regionIds | string[] | Region Id 多选 |
| groupIds | string[] | 与 `regionIds` 相同（兼容） |
| locationIds | string[] | 门店 Id 多选 |
| appliedLocationIds | string[] | 与 `locationIds` 一致（编辑器回显） |

### 展示规则

| appliedLocation | region | location | regionIds / locationIds |
|-----------------|--------|----------|-------------------------|
| **ALL** | `All Regions` | `All Locations` | 空数组 `[]` |
| **SPECIFIED** | 绑定门店 `location.GroupName` 去重后 `, ` 拼接 | 门店名（优先 `LocationName`，否则 `LocationCode`）拼接 | 由绑定门店反推 / 直接为绑定 Id |
| **SPECIFIED** 无绑定 | `无` | `无` | `[]` |

`regionIds` 由 `locationIds` 反查 `fl_group` 得到（与 product-category、label-type 一致）。

### 编辑说明

- `PUT` Body 字段与 `POST` 相同；传 `regionIds` / `locationIds` 会 **全量替换** 模板适用门店（先删 `fl_label_template_location` 再插入）。
- `elements` 仍为全量重建；`templateProductDefaults` 仅当 Body **显式包含** 该字段时才重建，避免普通保存误清空。
- 编辑成功 **`versionNo` +1**。

### 联调注意

| 现象 | 处理 |
|------|------|
| 列表无 `regionIds` | 确认已部署含本变更的后端 |
| 传 `groupId` 列表仍很多 | 正常：`appliedLocation=ALL` 的模板始终可见 |
| 传 `groupId` 列表为空 | 检查 Region 是否存在、其下是否有门店；无效 Region 时仅剩 ALL 模板 |
| 传了 Region 仍显示 All Locations | 检查 Region Id 是否有效、是否能在库中展开到门店 |
| 仅 `appliedLocationIds` 不传 `locationIds` | 仍支持，与 `locationIds` 合并 |
| 前端编辑器仍传 `appliedLocation: "ALL"` | 管理端若需多选，须在 Body 增加 `regionIds` / `locationIds`（见 `labelTemplateService.ts`） |
| 指定范围但 0 门店 | 后端报错，需至少 1 个有效门店 |

### 与 product-category / label-type 的关系

逻辑与 **`5-17接口优化.md`** 中 product-category、label-type 的 Region·Location 绑定一致，差异仅为：

| 模块 | 范围字段名 | 关联表 |
|------|------------|--------|
| product-category | `availabilityType` | `fl_product_category_location` |
| label-type | `availabilityType` | `fl_label_type_location` |
| **label-template** | **`appliedLocation`** | **`fl_label_template_location`** |

---

## rbac-role accessPermissions 修复

**应用服务**：`RbacRoleAppService`  
**影响接口**：`POST` / `PUT /api/app/rbac-role/{id}`、`GET` 列表/详情回显

### 问题与根因

| 现象 | 根因 |
|------|------|
| 保存报 `accessPermissions 未匹配到任何菜单` | 前端提交 **JSON 数组字符串**（如 `["manage_labels",...]`），旧逻辑按逗号拆分，解析结果带 `["` 引号，无法匹配 |
| 传 `manage_labels` 等仍无菜单 | 表单权限码为 **UI 编码**（`manage_labels`），菜单侧为 **`menu.labels`**（由 `Menu.Router` 推导）；二者未做映射 |
| 详情 `accessPermissionCodes` 为空 | 新增/编辑未写入 **`Role.AccessPermissionCodes`**（JSON 列），仅依赖 `RoleMenu` 反查 |

### 变更说明

| 项 | 变更后 |
|----|--------|
| **入参解析** | `accessPermissions` 支持 **JSON 数组字符串**、逗号分隔、以及 Body 字段 **`accessPermissionCodes`** 数组 |
| **菜单绑定** | UI 权限码经 **`RoleAccessPermissionMenuMapping`** 映射到 `Menu.Router`，再写入 **`RoleMenu`** |
| **落库** | 同时将勾选的 UI 编码写入 **`Role.AccessPermissionCodes`**（JSON 数组），供 GET 回显 |
| **PermissionCode 为空** | 仍可按 **`Router`** 推导 `menu.xxx`（建议执行 `menu_backfill_permission_code.sql`） |

### UI 权限码 → 菜单 Router 映射（当前库）

| accessPermissions（UI） | 绑定菜单 Router |
|-------------------------|-----------------|
| `manage_labels` | `/labeling`、`/labels`、`/label-categories`、`/label-types`、`/label-templates` |
| `manage_people` | `/account-management` |
| `edit_settings` | `/menu-management`、`/multiple-options` |
| `view_reports` | `/reports` |
| `manage_products` | （当前 `Menu` 表无 Products 路由，勾选不绑定菜单，**不单独报错**） |
| `approve_batches` | （当前无对应菜单路由，同上） |

> 至少 **1 个** 权限码能匹配到菜单即保存成功；若 **全部** 均无法匹配（例如只勾 `manage_products` 且库中无对应菜单），仍返回业务错误。

### 请求示例（与前端一致）

```http
PUT /api/app/rbac-role/3a1f077b-3665-63f2-5fea-0fd7e7044b88
Content-Type: application/json
Authorization: Bearer {token}
```

```json
{
  "roleName": "Partner Admin",
  "roleCode": "admin",
  "remark": "Admin",
  "dataScope": 0,
  "state": true,
  "orderNum": 999,
  "accessPermissions": "[\"manage_labels\",\"edit_settings\",\"view_reports\",\"manage_people\",\"manage_products\",\"approve_batches\"]"
}
```

也可使用逗号分隔（旧格式）：

```json
{
  "accessPermissions": "manage_labels, view_reports, manage_people"
}
```

或同时传数组字段（与 `accessPermissions` 合并去重）：

```json
{
  "accessPermissionCodes": ["manage_labels", "view_reports"]
}
```

### 入参优先级（与 5-18 一致）

| menuIds | accessPermissions / accessPermissionCodes | 行为 |
|---------|-------------------------------------------|------|
| 非空数组 | 任意 | **以 menuIds 为准** |
| 不传 | 非空 | 按 UI 权限码映射菜单并覆盖 `RoleMenu` |
| 不传 | `""` 或空数组 | 清空 `RoleMenu` 与 `AccessPermissionCodes` |
| `[]` | 不传 | 清空绑定 |

### 响应回显

| 字段 | 说明 |
|------|------|
| `accessPermissionCodes` | 来自 **`Role.AccessPermissionCodes`**，如 `["manage_labels","view_reports"]` |
| `accessPermissions` | 已绑定菜单的 **`menu.xxx`** 汇总（逗号拼接，只读展示） |
| `menuIds` | 已绑定菜单 Guid 列表（`RoleMenu`） |

### 数据库准备（推荐）

```bash
美国版/Food Labeling Management Code/Yi.Abp.Net8/module/food-labeling-us/scripts/menu_backfill_permission_code.sql
```

### 联调注意

| 现象 | 处理 |
|------|------|
| 仍报未匹配到菜单 | 确认已部署本修复；检查 `Menu` 是否存在上表 Router |
| 只勾 Products/Batches 报错 | 当前库无对应菜单属预期；请同时勾选 Labels/Reports 等 |
| 同时传 `menuIds: []` | **menuIds 优先**，会清空绑定并忽略 accessPermissions |

> 更完整的 RBAC 说明见 **`5-18接口优化.md`** → rbac-role 章节。

---

## auth-scope 登录后 Company · Region · Location 级联选店

**应用服务**：`AuthScopeAppService`  
**适用场景**：Web `POST /api/app/account/login` 或 App `POST /api/app/us-app-auth/login` 取得 Token 后，**管理员**无 `userlocation` 绑定时需先选工作门店；亦支持非管理员在数据范围内级联选择（须已绑定该门店）。

**命名约定**（与 5-17 一致）：UI **Company** = **`partnerId`**（`fl_partner.Id`）；UI **Region** = **`groupId`**（`fl_group.Id`）；UI **Location** = **`locationId`**（`location.Id`，Guid 字符串）。

### 接口一览

| 步骤 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 1 | GET | `/api/app/auth-scope/companies` | 可选公司列表 |
| 2 | GET | `/api/app/auth-scope/regions?partnerId={partnerId}` | 指定公司下 Region |
| 3 | GET | `/api/app/auth-scope/locations?partnerId={partnerId}&groupId={groupId}` | 指定公司+Region 下门店 |
| 4 | POST | `/api/app/auth-scope/select-location` | 确认当前工作门店 |
| — | GET | `/api/app/auth-scope/current-scope` | 查询已选工作门店（未选返回 `null`） |

**鉴权**：均需 `Authorization: Bearer {token}`。

### 数据范围

| 角色 | Company | Region | Location |
|------|---------|--------|----------|
| **管理员**（`admin` / 用户名 `admin` / 权限 `*:*:*`） | 全部未删除公司 | 该公司下全部 Region | 该 Region 下全部门店（`location.Partner` + `location.GroupName` 与 `fl_group` 一致） |
| **非管理员** | `userlocation` 绑定门店所属公司 | 绑定门店对应 Region | 上述 Region 内且符合 `LocationRegionScopeHelper` 的门店；**选店时**须已绑定该 `locationId` |

### 1）公司列表

```http
GET /api/app/auth-scope/companies HTTP/1.1
Authorization: Bearer {token}
```

**响应**：`AuthScopeCompanyOptionDto[]`

```json
[
  { "id": "fl_partner_id_1", "partnerName": "Acme Foods", "state": true }
]
```

### 2）Region 列表

```http
GET /api/app/auth-scope/regions?partnerId=fl_partner_id_1 HTTP/1.1
Authorization: Bearer {token}
```

**响应**：`AuthScopeRegionOptionDto[]`

```json
[
  { "id": "fl_group_id_east", "groupName": "East Region", "partnerId": "fl_partner_id_1", "state": true }
]
```

### 3）门店列表

```http
GET /api/app/auth-scope/locations?partnerId=fl_partner_id_1&groupId=fl_group_id_east HTTP/1.1
Authorization: Bearer {token}
```

**响应**：`AuthScopeLocationOptionDto[]`（含 `fullAddress`、`groupName` 等）

### 4）确认选店（与现有 App 逻辑对齐）

```http
POST /api/app/auth-scope/select-location HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json
```

```json
{
  "partnerId": "fl_partner_id_1",
  "groupId": "fl_group_id_east",
  "locationId": "a2696b9e-2277-11f1-b4c6-00163e0c7c4f"
}
```

**响应**：`AuthScopeSelectLocationOutputDto`

| 字段 | 说明 |
|------|------|
| partnerId / partnerName | 所选公司 |
| groupId / groupName | 所选 Region |
| location | 与 **`UsAppBoundLocationDto`** 相同（`id`、`locationCode`、`locationName`、`fullAddress`、`state`） |

**选店后的服务端行为**（无需改前端即可对接 App）：

| 能力 | 行为 |
|------|------|
| **工作范围缓存** | 写入分布式缓存（24h）；退出 `POST /api/app/auth-session/logout` 时清除 |
| **`GET /api/app/us-app-auth/my-locations`** | 管理员在缓存选店后，列表 **合并** 该门店（与 `userlocation` 并集） |
| **`GET .../location-detail/{locationId}`** | 管理员可不依赖 `userlocation` 访问已选门店（`UsAppPrintLogScopeHelper.EnsureUserCanAccessLocationAsync`） |
| **App 打印/报表** | 仍传 `locationId`；权限规则不变（见 `5-18接口优化.md`） |

### 5）当前工作范围

```http
GET /api/app/auth-scope/current-scope HTTP/1.1
Authorization: Bearer {token}
```

未选店时响应体为 **`null`**（HTTP 200）。

### 联调注意

| 现象 | 处理 |
|------|------|
| `regions` 为空 | 公司下无 `fl_group` 或当前账号无 Region 数据范围 |
| `locations` 为空 | 门店 `Partner` / `GroupName` 未与 `fl_partner`、`fl_group` 对齐 |
| 选店报「门店与所选公司/区域不匹配」 | 检查 `location.Partner`、`location.GroupName` |
| 非管理员选店报未绑定 | 须在 **Team Member** 中为该账号绑定该门店 |
| 选店后 `my-locations` 仍为空 | 确认已调 `select-location` 且 Token 为管理员身份 |

> Web 管理端报表等模块仍可按 Query 传 `partnerId` / `groupId` / `locationId` 收窄；本组接口主要解决 **登录后选工作门店** 与 **App 门店列表** 一致性问题。

---

## us-app-auth App 管理员级联选店

**应用服务**：`UsAppAuthAppService`  
**适用场景**：App 使用 **`POST /api/app/us-app-auth/login`** 登录后，持 **管理员** 身份（`admin` 角色 / 用户名 `admin` / 权限 `*:*:*`）且 JWT 含 **`client_kind=us-app`**，按 Company → Region 筛选门店。

**与 `auth-scope` 关系**：查询逻辑共用 `AuthScopeQueryHelper`；App 侧路径统一在 **`us-app-auth`** 下，并 **强制 App Token + 管理员**，避免误用 Web Token。

### 接口一览

| 步骤 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 0 | POST | `/api/app/us-app-auth/login` | 获取 App Token（须管理员账号） |
| 1 | GET | `/api/app/us-app-auth/admin-scope-companies` | 公司列表 → 取 `id` 作 `partnerId` |
| 2 | GET | `/api/app/us-app-auth/admin-scope-regions?partnerId={partnerId}` | Region 列表 → 取 `id` 作 `groupId` |
| 3 | GET | `/api/app/us-app-auth/admin-scope-locations?partnerId={partnerId}&groupId={groupId}` | **按公司与 Region Id 筛选门店** |
| 4 | POST | `/api/app/us-app-auth/select-admin-scope-location` | 确认工作门店 |
| — | GET | `/api/app/us-app-auth/my-locations` | 选店后刷新绑定门店（含缓存门店） |

**鉴权**：步骤 1–4 须 Header `Authorization: Bearer {App登录返回的token}`。

### 前置条件

| 项 | 要求 |
|----|------|
| Token 来源 | 必须来自 **`/api/app/us-app-auth/login`**（非 Web `/api/app/account/login`） |
| JWT 声明 | `client_kind` = `us-app` |
| 角色 | 平台管理员（`ReportsRoleHelper.IsAdminRole`） |
| 违反时 | `请使用 App 登录令牌调用该接口` 或 `仅管理员可使用公司/区域/门店筛选接口` |

### 1）公司列表

```http
GET /api/app/us-app-auth/admin-scope-companies HTTP/1.1
Authorization: Bearer {app_token}
```

**响应**：`AuthScopeCompanyOptionDto[]`（与 auth-scope 相同）

```json
[
  { "id": "fl_partner_id_1", "partnerName": "Acme Foods", "state": true }
]
```

### 2）Region 列表

```http
GET /api/app/us-app-auth/admin-scope-regions?partnerId=fl_partner_id_1 HTTP/1.1
Authorization: Bearer {app_token}
```

**响应**：`AuthScopeRegionOptionDto[]`

```json
[
  { "id": "fl_group_id_east", "groupName": "East Region", "partnerId": "fl_partner_id_1", "state": true }
]
```

### 3）门店列表（按 partnerId + groupId 筛选）

```http
GET /api/app/us-app-auth/admin-scope-locations?partnerId=fl_partner_id_1&groupId=fl_group_id_east HTTP/1.1
Authorization: Bearer {app_token}
```

**Query**

| 参数 | 必填 | 说明 |
|------|------|------|
| partnerId | 是 | 公司 Id（`fl_partner.Id`） |
| groupId | 是 | Region Id（`fl_group.Id`） |

**响应**：`AuthScopeLocationOptionDto[]`

```json
[
  {
    "id": "a2696b9e-2277-11f1-b4c6-00163e0c7c4f",
    "locationCode": "LOC-1",
    "locationName": "Downtown Kitchen",
    "fullAddress": "123 Main St, New York, NY 10001",
    "state": true,
    "partnerId": "fl_partner_id_1",
    "groupId": "fl_group_id_east",
    "groupName": "East Region"
  }
]
```

筛选规则：`location.Partner` 匹配该公司（Id 或名称），且 `location.GroupName` 与所选 `fl_group.GroupName` 一致。

### 4）确认选店

```http
POST /api/app/us-app-auth/select-admin-scope-location HTTP/1.1
Authorization: Bearer {app_token}
Content-Type: application/json
```

```json
{
  "partnerId": "fl_partner_id_1",
  "groupId": "fl_group_id_east",
  "locationId": "a2696b9e-2277-11f1-b4c6-00163e0c7c4f"
}
```

**响应**：`AuthScopeSelectLocationOutputDto`（含 `location` 节点，结构同 `UsAppBoundLocationDto`）

### 推荐调用顺序（App）

```text
POST /api/app/us-app-auth/login
  → GET  admin-scope-companies
  → GET  admin-scope-regions?partnerId=...
  → GET  admin-scope-locations?partnerId=...&groupId=...
  → POST select-admin-scope-location
  → GET  my-locations
  → 后续业务接口传 locationId（打印、报表等，规则不变）
```

### 联调注意

| 现象 | 处理 |
|------|------|
| 报「请使用 App 登录令牌」 | 勿用 Web `account/login` 的 Token；须重新 App 登录 |
| 报「仅管理员可使用」 | 换管理员账号或绑定 `admin` 角色 |
| `locations` 为空 | 核对门店 `Partner`、`GroupName` 与 `fl_partner`、`fl_group` |
| 与 auth-scope 重复 | App 端 **优先** 使用本节前缀；Web 端用 `auth-scope` |

---

## 变更记录

| 日期 | 说明 |
|------|------|
| 2026-05-26 | us-app-auth：App 管理员 `admin-scope-companies/regions/locations`、`select-admin-scope-location` |
| 2026-05-26 | auth-scope：登录后 Company/Region/Location 级联选店；选店缓存；`my-locations` / 门店详情与管理员选店对齐 |
| 2026-05-26 | product-category：`categoryCode` 新增/编辑改为可选 |
| 2026-05-26 | label-template：新增/编辑/列表/详情支持 `regionIds`、`locationIds` 及 `region`、`location` 展示 |
| 2026-05-26 | label-template 列表 Query 增加 `groupId`（Region）、`locationId`（门店）筛选 |
| 2026-05-26 | rbac-role：支持 accessPermissions JSON 数组 + UI 权限码映射 Menu；落库 AccessPermissionCodes |