王明 / Food-Labeling-Management-Platform

  # 6-1 代码优化
  
  本文档说明 **2026-06-01** 对美国版 **`auth-session/my-menus`** 中 **`lastUpdated`** 字段的语义与实现变更。
  
  ---
  
  ## my-menus 的 lastUpdated（系统编辑更新时间）
  
  ### 背景
  
  前端（`AuthProvider`）用 `GET /api/app/auth-session/my-menus` 返回的 **`lastUpdated`** 判断菜单/权限缓存是否需要刷新。原先取 **`User.LastModificationTime`**，仅在用户资料变更时变化，**菜单、角色、业务数据** 等任意接口修改后不会更新。
  
  ### 目标行为
  
  - **`lastUpdated`** 表示 **系统编辑更新时间**。
  - 宿主下任意 **`/api/app`** 的 **写操作**（`POST` / `PUT` / `PATCH` / `DELETE`）且 **HTTP 2xx 成功** 后，刷新全局时间戳（分布式缓存）。
  - **`my-menus`** 返回：`max(系统编辑时间戳, User.LastModificationTime)`；若从未有过写操作，则仅回退用户资料时间。
  
  ### 接口
  
  | 项 | 说明 |
  |----|------|
  | 方法 | `GET` |
  | 路径 | `/api/app/auth-session/my-menus` |
  | 鉴权 | Web 登录 Bearer Token |
  | 测试环境示例 | `http://flus-test.3ffoodsafety.com/api/app/auth-session/my-menus` |
  
  **请求示例**
  
  ```http
  GET /api/app/auth-session/my-menus HTTP/1.1
  Host: flus-test.3ffoodsafety.com
  Authorization: Bearer {access_token}
  ```
  
  **响应字段（与本次变更相关）**
  
  | 字段 | 类型 | 说明 |
  |------|------|------|
  | `lastUpdated` | `DateTime?` | 系统编辑全局时间戳；与任意符合条件的写接口成功联动。与用户 `LastModificationTime` 取 **较晚** 者。 |
  | `menus` | 数组 | 可见菜单树 |
  | `permissionCodes` | 字符串数组 | 权限码 |
  | `role` / `fullName` | 字符串 | 角色展示名、全名 |
  
  **响应片段示例**
  
  ```json
  {
    "user": {
      "id": "…",
      "userName": "admin"
    },
    "lastUpdated": "2026-06-01T14:32:10.123",
    "menus": [],
    "permissionCodes": [],
    "role": "Administrator",
    "fullName": "Admin"
  }
  ```
  
  ### 写操作如何刷新时间戳
  
  实现类：`SystemEditStampGlobalFilter`（注册于 `FoodLabelingApplicationModule`）。
  
  | 条件 | 是否刷新 |
  |------|----------|
  | 路径以 `/api/app` 开头 | 是（含 RBAC、美国版 `food-labeling-us`、同宿主泰额版等） |
  | 方法为 POST / PUT / PATCH / DELETE | 是 |
  | 响应状态码 2xx | 是 |
  | 路径含 `/login`、`/logout`、`forgot-password`、`/captcha`、`/my-menus`、`get-label-report` | **否**（登录、退出、验证码、纯查询报表等） |
  
  缓存键：`FoodLabeling:SystemEditStamp`（`SystemEditStampCacheHelper`）。
  
  ### 验证步骤（建议）
  
  1. 调用 `my-menus`，记录 `lastUpdated` 为 **T0**。
  2. 调用任意会改数据的写接口（如新增/修改产品、用户、菜单、选店 `auth-scope/select-location` 等），确认 **2xx**。
  3. 再次调用 `my-menus`，`lastUpdated` 应为 **T1**，且 **T1 > T0**（秒级即可）。
  4. 仅调用 `get-label-report` 等排除路径时，`lastUpdated` **不应** 变化。
  
  ### 涉及文件
  
  | 文件 | 说明 |
  |------|------|
  | `FoodLabeling.Application/Filters/SystemEditStampGlobalFilter.cs` | 写成功后 Touch 时间戳 |
  | `FoodLabeling.Application/Helpers/SystemEditStampCache.cs` | 缓存读写 |
  | `FoodLabeling.Application/Services/AuthSessionAppService.cs` | `GetMyMenusAsync` 组装 `lastUpdated` |
  | `FoodLabeling.Application.Contracts/.../CurrentUserMenuPermissionsOutputDto.cs` | DTO 注释 |
  | `FoodLabeling.Application.Contracts/IServices/IAuthSessionAppService.cs` | 接口 XML 注释 |
  
  ### 前端说明
  
  `Food Labeling Management Platform/src/components/auth/AuthProvider.tsx` 已支持从响应根级或 `user` 内读取 `lastUpdated`，**无需改前端**即可使用新语义；建议在本地对比 `lastUpdated` 与上次缓存值，变化时重新拉取菜单。
  
  ---
  
  ## team-member 列表按 Token 权限过滤
  
  ### 背景
  
  `GET /api/app/team-member` 原先仅按 Query 的 `partnerId` / `groupId` / `locationId` 筛选，**未**结合登录 Token 的数据范围，非管理员可能看到其它公司的成员。
  
  ### 目标行为
  
  | 登录身份 | 列表可见成员 |
  |----------|----------------|
  | **系统管理员**（`ReportsRoleHelper.IsAdminRole`：用户名 `admin`、角色码 `admin`、权限 `*:*:*` 等） | **全部** 用户（仍可用 Query 按 Company / Region / Location 收窄） |
  | **其它账号** | 仅在 **`userlocation` 至少绑定一家门店**，且该门店属于当前账号 **绑定门店所属公司**（`fl_partner`，见 `PartnerScopeHelper`）下的成员 |
  
  与 **`GET /api/app/partner`** 公司列表、`auth-scope` 级联选店使用的公司范围规则一致。
  
  ### 接口
  
  | 项 | 说明 |
  |----|------|
  | 方法 | `GET` |
  | 路径 | `/api/app/team-member` |
  | 鉴权 | Web 登录 Bearer Token |
  | 测试环境示例 | `http://flus-test.3ffoodsafety.com/api/app/team-member?SkipCount=1&MaxResultCount=10` |
  | PDF 导出 | `GET /api/app/team-member/export-team-members-pdf`（**相同** Token 范围 + Query 筛选） |
  
  ### Query 参数
  
  | 参数 | 说明 |
  |------|------|
  | `SkipCount` | 跳过条数（分页） |
  | `MaxResultCount` | 每页条数 |
  | `Keyword` | 姓名 / 用户名 / 邮箱 / 电话模糊搜索 |
  | `RoleId` | 角色 Id |
  | `State` | 启用状态 |
  | `partnerId` | Company（`fl_partner.Id`）；非管理员须在本人可见公司内 |
  | `groupId` | Region（`fl_group.Id`） |
  | `locationId` | 门店 Id；传则优先于 `partnerId` / `groupId` |
  | `Sorting` | 排序（可选） |
  
  **筛选优先级**（Query 内）：`locationId` → `groupId` → `partnerId`；均未传时，管理员不限制组织范围，非管理员限定为其可见公司下全部门店。
  
  **命中规则**：成员须在 `userlocation` 中至少绑定一家落在「最终门店集合」内的门店。
  
  ### 请求示例
  
  ```http
  GET /api/app/team-member?SkipCount=1&MaxResultCount=10 HTTP/1.1
  Host: flus-test.3ffoodsafety.com
  Authorization: Bearer {access_token}
  ```
  
  非管理员带 Company 筛选（须在本人可见公司内）：
  
  ```http
  GET /api/app/team-member?SkipCount=1&MaxResultCount=10&partnerId={fl_partner.Id}
  Authorization: Bearer {partner_admin_token}
  ```
  
  ### 验证步骤（建议）
  
  1. 使用 **系统管理员** Token 调用列表 → 应返回全库成员（或受 Query 筛选）。
  2. 使用 **仅绑定 A 公司门店** 的 Partner/公司管理员 Token → 仅返回在 A 公司门店有 `userlocation` 绑定的成员；不应出现仅绑定 B 公司的成员。
  3. 非管理员传 **其它公司** 的 `partnerId` → 空列表（非 403）。
  4. `export-team-members-pdf` 与列表使用同一套范围，条数应与列表筛选一致。
  
  ### 库内核对（非管理员 · 某公司）
  
  ```sql
  -- 替换 :partnerId 为 fl_partner.Id，:partnerName 为 PartnerName
  SELECT DISTINCT u.Id, u.UserName, u.Name
  FROM `User` u
  INNER JOIN userlocation ul ON ul.UserId = CAST(u.Id AS CHAR) AND ul.IsDeleted = 0
  INNER JOIN location loc ON ul.LocationId = CAST(loc.Id AS CHAR) AND loc.IsDeleted = 0
  INNER JOIN fl_partner p ON p.IsDeleted = 0 AND (loc.Partner = p.PartnerName OR loc.Partner = p.Id)
  WHERE u.IsDeleted = 0
    AND p.Id = :partnerId;
  ```
  
  ### 涉及文件
  
  | 文件 | 说明 |
  |------|------|
  | `FoodLabeling.Application/Helpers/TeamMemberListScopeHelper.cs` | Token 范围 + Query 交集 |
  | `FoodLabeling.Application/Helpers/PartnerScopeHelper.cs` | 公司可见范围（复用） |
  | `FoodLabeling.Application/Services/TeamMemberAppService.cs` | `GetListAsync`、PDF 导出 |
  | `FoodLabeling.Application.Contracts/.../TeamMemberGetListInputVo.cs` | 入参注释 |
  | `FoodLabeling.Application.Contracts/IServices/ITeamMemberAppService.cs` | 接口 XML 注释 |
  
  ### 联调注意
  
  | 现象 | 处理 |
  |------|------|
  | 非管理员列表为空 | 确认当前账号 `userlocation` 是否已绑定门店，且门店 `Partner` 能对应到 `fl_partner` |
  | 成员无门店绑定 | 不会出现在非管理员列表中（无 `userlocation` 命中） |
  | 与 5-18 文档关系 | 5-18 描述 Query 筛选字段；本节补充 **Token 权限范围**，以本节为准 |
  
  ---
  
  ## product 下载导入模板 405 修复
  
  ### 问题现象
  
  ```http
  GET|POST http://flus-test.3ffoodsafety.com/api/app/product/download-product-import-template
  Authorization: Bearer {token}
  ```
  
  使用 **POST** 调用时返回 **405 Method Not Allowed**（后端已限定为 **GET**；旧版 Web 用 `authorizedPostBlobDownload` 发 POST）。
  
  ### 根因
  
  | 项 | 说明 |
  |----|------|
  | 后端 | `DownloadProductImportTemplateAsync` 标注 **`[HttpGet]`**（ABP 对 `Download*` 也可能误判动词，需显式路由） |
  | 前端（修复前） | `productService.downloadProductImportTemplate` 使用 **POST** 下载 Blob |
  | 约定 | 与 `export-products-excel`、Location/批量文档一致：**下载模板 / 导出** 均为 **GET**，无 Body |
  
  ### 修复方式
  
  1. **后端** `ProductAppService`：增加显式路径，并 **同时接受 GET 与 POST**（兼容未刷新前端）：
     - `[HttpGet("product/download-product-import-template")]`
     - `[HttpPost("product/download-product-import-template")]`
  2. **前端** `productService.ts`：改为 **`authorizedGetBlobDownload`**（GET）。
  
  ### 接口说明
  
  | 项 | 说明 |
  |----|------|
  | 方法 | **`GET`**（推荐）；**`POST`**（兼容，无 Body） |
  | 路径 | `/api/app/product/download-product-import-template` |
  | 鉴权 | Web 登录 Bearer Token |
  | 响应 | `Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`；文件名来自配置 `FoodLabeling:BatchImport:ProductTemplateFileName`（默认 `Product-Manager-批量导入模板.xlsx`） |
  | 配置 | `TemplateDirectory` + `ProductTemplateFileName`（见 `批量导入导出接口说明.md` §3.1） |
  
  ### 请求示例
  
  ```http
  GET /api/app/product/download-product-import-template HTTP/1.1
  Host: flus-test.3ffoodsafety.com
  Authorization: Bearer {access_token}
  ```
  
  ```bash
  curl -X GET "http://flus-test.3ffoodsafety.com/api/app/product/download-product-import-template" \
    -H "Authorization: Bearer {token}" \
    -o "Product-Manager-template.xlsx"
  ```
  
  ### 验证步骤
  
  1. 浏览器或 Postman 使用 **GET** + Token → 应下载 xlsx（非 405）。
  2. 仍用 **POST**（无 Body）→ 部署新后端后亦应成功（兼容）。
  3. 若返回业务错误「模板文件不存在」→ 检查服务器 `TemplateDirectory` 下是否存在配置的 xlsx。
  
  ### 涉及文件
  
  | 文件 | 说明 |
  |------|------|
  | `FoodLabeling.Application/Services/ProductAppService.cs` | 显式 GET/POST 路由 |
  | `FoodLabeling.Application.Contracts/IServices/IProductAppService.cs` | XML 注释 |
  | `Food Labeling Management Platform/src/services/productService.ts` | 改为 GET 下载 |
  
  ### 联调注意
  
  | 现象 | 处理 |
  |------|------|
  | 仍 405 | 确认已部署含本修复的后端；前端须 GET 或等新后端支持 POST |
  | 404 | 路径须为 `download-product-import-template`，勿当成 `GET /product/{id}` |
  | 与导出区别 | 全量导出为 `GET .../export-products-excel?Keyword=...`；模板下载无 Query |
  
  ---
  
  ## dashboard/overview 首页统计口径修复
  
  ### 问题现象
  
  `GET /api/app/dashboard/overview` 返回的 **Active Users**、**Locations**、**People** 与业务实际不符；公司维度账号可能看到全库用户数/门店数，且**系统 admin** 被计入某公司成员统计。
  
  测试环境示例：`http://flus-test.3ffoodsafety.com/api/app/dashboard/overview`
  
  ### 目标行为
  
  | 指标 | 统计口径 |
  |------|----------|
  | **Locations** | 范围内未删除门店数：管理员=全平台；其它账号=其绑定门店所属公司下全部门店 |
  | **People** | 范围内**团队成员**：在 `userlocation` 中至少绑定一家范围内门店的用户（`User.IsDeleted=false`），**排除**系统 admin |
  | **Active Users** | 同上，且 `User.State=true` |
  | **系统 admin** | 用户名 `admin` 或角色码 `admin` 的账号**不计入** People / Active Users（不归属任何 Company） |
  
  打印类指标（**Labels Printed Today**、**Weekly Print Volume**、**Recent Labels**）与 **Products** 亦按同一门店范围过滤；**Active Templates**、**By Category** 仍为全平台口径（与改前一致）。
  
  ### 接口
  
  | 项 | 说明 |
  |----|------|
  | 方法 | `GET` |
  | 路径 | `/api/app/dashboard/overview` |
  | 鉴权 | Web 登录 Bearer Token |
  | 请求参数 | 无（范围由 Token 解析，与 `team-member` 列表、`partner` 列表一致） |
  
  ### 请求示例
  
  ```http
  GET /api/app/dashboard/overview HTTP/1.1
  Host: flus-test.3ffoodsafety.com
  Authorization: Bearer {access_token}
  ```
  
  ### 响应字段（本次相关）
  
  | 字段 | 说明 |
  |------|------|
  | `activeUsers` | 启用状态的范围内团队成员数（不含系统 admin） |
  | `locations` | 范围内门店数 |
  | `people` | 范围内团队成员总数（含禁用，不含系统 admin） |
  | `labelsPrintedToday` | 范围内门店当日打印任务数 |
  | `weeklyPrintVolume` | 近 7 天范围内打印量 |
  | `recentLabels` | 范围内门店最近 10 条打印记录 |
  
  各指标对象含 `value`、`previousValue`、`changeValue`、`changeRate`（周对比基准：最近 7 天起始日前创建的存量等，见实现）。
  
  ### 验证步骤（建议）
  
  1. **系统管理员** Token：Locations / People 为全平台（People 不含 `admin` 账号）；与库内 `location`、`userlocation` 汇总大致一致。
  2. **仅绑定 A 公司门店** 的账号：三项指标仅反映 A 公司范围；不应等于全库总数。
  3. 确认 `admin` 用户不在 People / Active Users 中（即使其有 `userlocation` 绑定）。
  4. 无 `userlocation` 的普通用户：不计入 People / Active Users。
  
  ### 库内核对（某公司团队成员，不含 admin）
  
  ```sql
  SELECT COUNT(DISTINCT ul.UserId) AS people_count
  FROM userlocation ul
  INNER JOIN location loc ON ul.LocationId = CAST(loc.Id AS CHAR) AND loc.IsDeleted = 0
  INNER JOIN fl_partner p ON p.IsDeleted = 0 AND (loc.Partner = p.PartnerName OR loc.Partner = p.Id)
  INNER JOIN `User` u ON CAST(u.Id AS CHAR) = ul.UserId AND u.IsDeleted = 0
  WHERE ul.IsDeleted = 0
    AND p.Id = :partnerId
    AND u.UserName <> 'admin'
    AND u.Id NOT IN (
      SELECT ur.UserId FROM UserRole ur
      INNER JOIN Role r ON r.Id = ur.RoleId AND r.IsDeleted = 0 AND r.RoleCode = 'admin'
    );
  ```
  
  ### 涉及文件
  
  | 文件 | 说明 |
  |------|------|
  | `FoodLabeling.Application/Helpers/DashboardScopeHelper.cs` | 范围解析、admin 排除、计数 |
  | `FoodLabeling.Application/Helpers/TeamMemberListScopeHelper.cs` | 门店范围（复用） |
  | `FoodLabeling.Application/Services/DashboardAppService.cs` | `GetOverviewAsync` |
  | `FoodLabeling.Application.Contracts/IServices/IDashboardAppService.cs` | XML 注释 |
  
  ### 联调注意
  
  | 现象 | 处理 |
  |------|------|
  | 公司账号统计仍为 0 | 检查该账号 `userlocation` 与门店 `Partner` 能否关联到 `fl_partner` |
  | admin 仍出现在 People | 确认用户名/角色码是否为 `admin`；部署须含本修复 |
  | 与 `Dashboard统计接口对接说明.md` | 该文档为通用结构说明；**统计口径以本节为准** |
  
  ---
  
  ## 标签 `/api/app/label` 适用 Region（新增/编辑）
  
  ### 背景
  
  标签原先仅通过 `locationId` 绑定单门店，无法显式表达「适用哪些 Region」。现与 **label-type**、**label-multiple-option** 一致，支持 **全选（ALL）**、**单选/多选 Region（SPECIFIED + `regionIds`）**，Region 主键为 **`fl_group.Id`**。
  
  ### 存储
  
  | 位置 | 字段 | 说明 |
  |------|------|------|
  | `fl_label` | `AppliedRegionType` | `ALL` = 全平台 Region；`SPECIFIED` = 按关联表 |
  | `fl_label_region` | `LabelId` + `GroupId` | 多选 Region 明细（`GroupId` = `fl_group.Id`） |
  | `fl_label` | `LocationId` | 仍保留：App 打印/树展示兼容；多 Region 且未显式传门店时，取合并门店列表**第一家** |
  
  **DDL（测试/生产须先执行）**：`module/food-labeling-us/scripts/fl_label_region_scope.sql`
  
  ### 接口一览
  
  | 方法 | 路径 | 说明 |
  |------|------|------|
  | `GET` | `/api/app/label?SkipCount=&MaxResultCount=` | 分页列表；支持 `GroupId` 按 Region 筛选；出参含 `region`、`regionIds`、`appliedRegionType` |
  | `GET` | `/api/app/label/{id}` | 详情（`id` = `LabelCode`） |
  | `POST` | `/api/app/label` | 新增 |
  | `PUT` | `/api/app/label/{id}` | 编辑 |
  
  测试环境示例列表：`http://flus-test.3ffoodsafety.com/api/app/label?SkipCount=1&MaxResultCount=10`
  
  ### 请求 Body（新增 / 编辑，JSON）
  
  | 字段 | 类型 | 必填 | 说明 |
  |------|------|------|------|
  | `appliedRegionType` | string | 否 | `ALL` 或 `SPECIFIED`。传了非空 `regionIds`/`groupIds` 时按 **SPECIFIED** 落库 |
  | `regionIds` | string[] | 条件 | Region Id 数组（`fl_group.Id`）；与 `groupIds` **合并去重** |
  | `groupIds` | string[] | 否 | 与 `regionIds` 等价别名 |
  | `locationId` | string | 条件 | 门店 Id；SPECIFIED 时用于校验是否在 Region 范围内；ALL 时可单独指定 |
  | `locationIds` | string[] | 否 | 门店候选多选（与 Region 合并解析） |
  | `labelName` | string | 是 | 标签名称 |
  | `templateCode` | string | 是 | 模板编码 |
  | `labelCategoryId` | string | 是 | 标签类别 |
  | `labelTypeId` | string | 是 | 标签类型 |
  | `productIds` | string[] | 是 | 至少 1 个产品 Id |
  | `labelInfoJson` | object | 否 | 模板填写数据 |
  | `state` | bool | 否 | 默认 `true` |
  
  ### 三种适用范围示例
  
  **1. 全选 Region（ALL）**
  
  ```json
  {
    "labelName": "Demo Label",
    "templateCode": "TPL001",
    "appliedRegionType": "ALL",
    "regionIds": [],
    "labelCategoryId": "...",
    "labelTypeId": "...",
    "productIds": ["..."],
    "locationId": "可选-指定展示/打印默认门店"
  }
  ```
  
  **2. 单选 Region**
  
  ```json
  {
    "appliedRegionType": "SPECIFIED",
    "regionIds": ["1234567890123456789"],
    "locationId": "门店Id-须在Region内",
    "labelName": "...",
    "templateCode": "...",
    "labelCategoryId": "...",
    "labelTypeId": "...",
    "productIds": ["..."]
  }
  ```
  
  **3. 多选 Region**
  
  ```json
  {
    "regionIds": ["regionId1", "regionId2"],
    "groupIds": ["regionId2"],
    "labelName": "...",
    "templateCode": "...",
    "labelCategoryId": "...",
    "labelTypeId": "...",
    "productIds": ["..."]
  }
  ```
  
  > 未传 `locationId` 且合并 Region 对应多家门店时，后端取**第一家**写入 `fl_label.LocationId`；App 侧 `labeling-tree` / 预览打印通过 Region 关联判断是否适用该门店。
  
  ### 响应字段（详情 / 列表相关）
  
  | 字段 | 说明 |
  |------|------|
  | `appliedRegionType` | `ALL` / `SPECIFIED` |
  | `regionIds` | Region Id 数组（ALL 时为空） |
  | `groupIds` | 与 `regionIds` 相同 |
  | `region` | 展示名：ALL 时为 `All Regions`；SPECIFIED 时为 Region 名称逗号拼接 |
  | `locationId` | 当前绑定门店 |
  
  ### 列表筛选
  
  | 查询参数 | 说明 |
  |----------|------|
  | `GroupId` | 按 Region（`fl_group.Id`）过滤：命中 `fl_label_region`，或 `AppliedRegionType=ALL` 的标签 |
  | `LocationId` | 按门店（原有） |
  | `Keyword` 等 | 与其它筛选组合 |
  
  ### 验证步骤（建议）
  
  1. 执行 `fl_label_region_scope.sql` 后部署后端。
  2. **POST** 新增：仅 `regionIds` 单选 → 查 `fl_label_region` 一行、`AppliedRegionType=SPECIFIED`。
  3. **POST** `appliedRegionType=ALL` → `fl_label_region` 无行、`AppliedRegionType=ALL`。
  4. **PUT** 编辑：改为多选 `regionIds` → 关联表行数与 Id 一致（先删后插）。
  5. **GET** 列表/详情：出参 `region`、`regionIds` 与库一致。
  6. App：`/api/app/us-app-labeling/labeling-tree` 仅展示对当前门店 Region 命中的标签（ALL 或关联 Region）。
  
  ### 库内核对 SQL
  
  ```sql
  -- 标签 Region 范围
  SELECT l.Id, l.LabelCode, l.AppliedRegionType, l.LocationId
  FROM fl_label l
  WHERE l.IsDeleted = 0 AND l.LabelCode = :labelCode;
  
  SELECT lr.GroupId, g.GroupName
  FROM fl_label_region lr
  INNER JOIN fl_group g ON g.Id = lr.GroupId AND g.IsDeleted = 0
  WHERE lr.LabelId = :labelId;
  ```
  
  ### 涉及文件
  
  | 文件 | 说明 |
  |------|------|
  | `scripts/fl_label_region_scope.sql` | DDL |
  | `Helpers/LabelRegionScopeHelper.cs` | 保存/展示/列表筛选/App 校验 |
  | `Services/LabelAppService.cs` | CRUD、列表出参 |
  | `Services/UsAppLabelingAppService.cs` | App 树与打印范围 |
  | `Contracts/Dtos/Label/*` | 入参/出参 |
  | `Contracts/IServices/ILabelAppService.cs` | XML 注释 |
  | Web `labelService.ts` / `types/label.ts` | 前端 API 映射 |
  | Web `LabelsList.tsx` | 创建/编辑提交 `appliedRegionType` + `regionIds` |
  
  ### 联调注意
  
  | 现象 | 处理 |
  |------|------|
  | 保存报「请选择适用 Region」 | SPECIFIED 须传 `regionIds` 或 `locationId` |
  | 列表无 `region` 列 | 确认已执行 DDL 并部署含 `LabelRegionScopeHelper` 的版本 |
  | 编辑后 Region 未变 | 检查 Body 是否带 `regionIds`；Web 创建/编辑已随 Region 选择器提交 |