王明 / Food-Labeling-Management-Platform

  # 6-23 代码优化
  
  本文档说明 **2026-06-23** 对美国版标签（Label）接口的多门店绑定改造：一个标签可绑定多个门店（`locationIds` 数组），关联表为 `fl_label_location`。
  
  ---
  
  ## 一、背景与目标
  
  | 项目 | 说明 |
  |------|------|
  | 原行为 | 标签仅通过 `fl_label.LocationId` 绑定单门店 |
  | 新行为 | **`locationIds` 为主字段**，落库 `fl_label_location`；`fl_label.LocationId` 保留为首项兼容列 |
  | 兼容 | 未建 `fl_label_location` 时仍读/写 `LocationId`；已建表时列表/筛选/App 打印校验均命中关联表 |
  
  ---
  
  ## 二、数据库迁移
  
  脚本路径：`美国版/Food Labeling Management Code/Yi.Abp.Net8/module/food-labeling-us/scripts/fl_label_location_scope.sql`
  
  | 步骤 | 内容 |
  |------|------|
  | 1 | 创建 `fl_label_location`（`LabelId` + `LocationId`） |
  | 2 | 若关联表为空，将现有 `fl_label.LocationId` 迁移写入关联表 |
  
  **执行前请备份数据库。**
  
  ---
  
  ## 三、`locationIds` 字段规范
  
  ### 入参（POST / PUT）
  
  | 字段 | 类型 | 说明 |
  |------|------|------|
  | `locationIds` | `string[]` | **主字段**。适用门店 Id（`location.Id`），全量写入 `fl_label_location` |
  | `locationId` | `string` | **兼容**。与 `locationIds` 合并；合并后首项写入 `fl_label.LocationId` |
  | `appliedRegionType` | `string` | `ALL` / `SPECIFIED` |
  | `regionIds` / `groupIds` | `string[]` | Region（`fl_group.Id`），落库 `fl_label_region`；可与 `locationIds` 组合校验 |
  
  **解析规则（`ResolveScopeForSaveAsync`）**
  
  - `appliedRegionType=ALL` 且未传 region：仅校验/保存 `locationIds`（可为空表示全部门店）
  - `appliedRegionType=SPECIFIED`：须传 `regionIds` 和/或 `locationIds`；显式 `locationIds` 须在 Region 展开门店范围内
  - `locationId` 与 `locationIds` 合并去重，`locationId` 排在数组首位
  
  ### 出参（GET 列表 / 详情）
  
  | 字段 | 说明 |
  |------|------|
  | `locationIds` | 门店 Id 数组（来自 `fl_label_location`，无关联表时回退 `LocationId`） |
  | `location` / `locationName` | 门店名称逗号拼接展示 |
  | `locationId` | **兼容**：等于 `locationIds[0]`，无门店时为空 |
  
  ---
  
  ## 四、接口说明
  
  ### 1. 标签列表
  
  | 项目 | 内容 |
  |------|------|
  | 方法 | `GET` |
  | 路径 | `/api/app/label` |
  | 鉴权 | Bearer Token |
  
  **筛选（Query / data）**
  
  | 参数 | 说明 |
  |------|------|
  | `SkipCount` | 页码，从 1 起 |
  | `MaxResultCount` | 每页条数 |
  | `GroupId` | 按 Region 筛选：命中 `fl_label_region`、`fl_label_location` 或 `AppliedRegionType=ALL` |
  | `LocationId` | 按门店筛选：命中 `fl_label_location` 或兼容列 `LocationId` |
  | `PartnerId` | 按 Company 下门店集合筛选（同 Location 逻辑） |
  | `ProductId` / `Keyword` / `LabelCategoryId` / `LabelTypeId` / `TemplateCode` / `State` | 其它原有筛选 |
  
  **出参 `items[]` 新增/变更**
  
  | 字段 | 说明 |
  |------|------|
  | `locationIds` | 适用门店 Id 数组 |
  | `locationName` | 门店展示名（逗号拼接） |
  | `region` / `regionIds` / `appliedRegionType` | Region 范围（逻辑不变） |
  
  ---
  
  ### 2. 标签详情
  
  | 项目 | 内容 |
  |------|------|
  | 方法 | `GET` |
  | 路径 | `/api/app/label/{id}` |
  | 路径参数 | `id` = 标签 `LabelCode` |
  
  **出参要点**
  
  | 字段 | 说明 |
  |------|------|
  | `locationIds` | 适用门店数组 |
  | `location` | 门店展示名 |
  | `locationId` | 兼容首项 |
  | `regionIds` / `groupIds` / `appliedRegionType` | Region 范围 |
  
  ---
  
  ### 3. 新增标签
  
  | 项目 | 内容 |
  |------|------|
  | 方法 | `POST` |
  | 路径 | `/api/app/label` |
  
  **Body 示例**
  
  ```json
  {
    "labelName": "Price Label A",
    "templateCode": "TPL_PRICE_2X2",
    "labelCategoryId": "...",
    "labelTypeId": "...",
    "productIds": ["..."],
    "appliedRegionType": "SPECIFIED",
    "regionIds": ["group-id-1"],
    "locationIds": ["loc-id-1", "loc-id-2"],
    "state": true
  }
  ```
  
  **落库**
  
  - `fl_label.LocationId` ← `locationIds[0]`
  - `fl_label_location` ← 全量 `locationIds`
  - `fl_label_region` ← `regionIds`（SPECIFIED 时）
  
  ---
  
  ### 4. 编辑标签
  
  | 项目 | 内容 |
  |------|------|
  | 方法 | `PUT` |
  | 路径 | `/api/app/label/{id}` |
  | Body | 同 POST；`locationIds` 全量覆盖关联表 |
  
  ---
  
  ### 5. 删除标签
  
  逻辑删除 `fl_label`，并删除 `fl_label_region`、`fl_label_location`、`fl_label_product` 关联行（表存在时）。
  
  ---
  
  ## 五、App 打印校验
  
  `UsAppLabelingAppService.PrintAsync` / `PreviewAsync` 使用 `LabelRegionScopeHelper.EnsureLabelAppliesToLocationAsync` / `LabelAppliesToLocationAsync`，支持：
  
  - `AppliedRegionType=ALL` 且配置了 `fl_label_location`：须在关联门店内
  - `SPECIFIED`：命中 `fl_label_location`、`LocationId` 或 `fl_label_region`
  
  ---
  
  ## 六、代码改动摘要
  
  | 文件 | 改动 |
  |------|------|
  | `LabelRegionScopeHelper.cs` | 多门店解析/保存/列表筛选/展示；`ApplyLabelRegionListFilter` 用 SQL `EXISTS` 查 `fl_label_location` |
  | `LabelAppService.cs` | CRUD 读写 `locationIds`；列表筛选走 Helper |
  | `LabelCreateInputVo` / `LabelGetOutputDto` / `LabelGetListOutputDto` | 增加 `locationIds` 等字段 |
  | `UsAppLabelingAppService.cs` | 打印/预览门店校验对齐多门店 |
  | `ILabelAppService.cs` | XML 注释补充 `locationIds` |
  
  ---
  
  ## 七、向后兼容
  
  | 场景 | 行为 |
  |------|------|
  | 仅传 `locationId` | 合并为单元素 `locationIds` |
  | 未执行 SQL 迁移 | 无 `fl_label_location` 时读写 `fl_label.LocationId` |
  | 前端仍读 `locationId` | 详情/列表返回首项，不影响旧页面 |
  
  ---
  
  ## 八、部署注意
  
  1. 测试/生产库执行 `fl_label_location_scope.sql`
  2. `dotnet build` 编译 `FoodLabeling.Application` 后重启 Web 进程
  3. 管理端表单改为多选 `locationIds`；旧单选 `locationId` 可逐步下线
  
  ---
  
  ## 九、请求示例
  
  ### 登录获取 Token
  
  ```bash
  curl -X POST "http://flus-test.3ffoodsafety.com/api/oauth/Login" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "userName=admin&password=123456"
  ```
  
  ### 标签列表（第一页）
  
  ```bash
  curl -G "http://flus-test.3ffoodsafety.com/api/app/label" \
    -H "Authorization: Bearer {token}" \
    --data-urlencode "SkipCount=1" \
    --data-urlencode "MaxResultCount=10"
  ```
  
  ### 按门店筛选
  
  ```bash
  curl -G "http://flus-test.3ffoodsafety.com/api/app/label" \
    -H "Authorization: Bearer {token}" \
    --data-urlencode "SkipCount=1" \
    --data-urlencode "MaxResultCount=10" \
    --data-urlencode "LocationId={location.Id}"
  ```
  
  ### 新增标签（多门店）
  
  ```bash
  curl -X POST "http://flus-test.3ffoodsafety.com/api/app/label" \
    -H "Authorization: Bearer {token}" \
    -H "Content-Type: application/json" \
    -d '{
      "labelName": "Price Label A",
      "templateCode": "TPL_PRICE_2X2",
      "labelCategoryId": "...",
      "labelTypeId": "...",
      "productIds": ["..."],
      "appliedRegionType": "SPECIFIED",
      "regionIds": ["group-id-1"],
      "locationIds": ["loc-id-1", "loc-id-2"],
      "state": true
    }'
  ```
  
  ### 编辑标签（全量覆盖 locationIds）
  
  ```bash
  curl -X PUT "http://flus-test.3ffoodsafety.com/api/app/label/{labelCode}" \
    -H "Authorization: Bearer {token}" \
    -H "Content-Type: application/json" \
    -d '{
      "labelName": "Price Label A",
      "templateCode": "TPL_PRICE_2X2",
      "labelCategoryId": "...",
      "labelTypeId": "...",
      "productIds": ["..."],
      "locationIds": ["loc-id-1", "loc-id-3"],
      "state": true
    }'
  ```
  
  ### 详情
  
  ```bash
  curl -G "http://flus-test.3ffoodsafety.com/api/app/label/{labelCode}" \
    -H "Authorization: Bearer {token}"
  ```
  
  ### 响应片段（详情）
  
  ```json
  {
    "id": "LBL0001",
    "labelName": "Price Label A",
    "locationIds": ["loc-id-1", "loc-id-2"],
    "locationId": "loc-id-1",
    "location": "Store A, Store B",
    "appliedRegionType": "SPECIFIED",
    "regionIds": ["group-id-1"],
    "region": "West Region"
  }
  ```
  
  ---
  
  ## 十、标签模板列表 500 修复（`GET /api/app/label-template`）
  
  ### 现象
  
  `GET /api/app/label-template?SkipCount=1&MaxResultCount=10` 返回 **500**，日志：
  
  ```text
  Unknown column 'AppliedPartnerType' in 'field list'
  ```
  
  对应 SQL 会 SELECT 库中不存在的列：`AppliedPartnerType`、`AppliedRegionType`、`BorderType`。
  
  **MCP 查库（当前测试库）**：`fl_label_template` 仅有 `AppliedLocationType`、`PrintOrientation` 等基础列；**无** scope 列与 `BorderType`；**无** `fl_label_template_partner` / `fl_label_template_region` 表（仅有 `fl_label_template_location`）。
  
  ### 根因
  
  `FlLabelTemplateDbEntity` 仍映射 ORM 属性到不存在的列，SqlSugar 生成 `SELECT` 时全部拼入，未执行 `fl_label_template_scope.sql` 的库直接报错。
  
  ### 修复说明
  
  | 改动 | 说明 |
  |------|------|
  | `FlLabelTemplateDbEntity` | **删除** `AppliedPartnerType` / `AppliedRegionType` / `BorderType` 属性 |
  | `LabelTemplateQueryHelper.ProjectListColumns` | 列表/详情只读查询 **显式 Select** 真实列 |
  | `LabelTemplateQueryHelper.ApplyListSorting` | 默认 `IFNULL(LastModificationTime, CreationTime) DESC`；`Sorting` 白名单 |
  | `LabelTemplateScopeSchemaHelper` | 探测 scope / border 列；已迁移时用 raw SQL 读写 |
  | `LabelTemplateScopeHelper.SaveTemplateScopeAsync` | 保存关联表后调用 `SetAppliedScopeTypesAsync` |
  | `LabelTemplateAppService.GetListAsync` | 排序后 `ProjectListColumns` 再分页 |
  
  > Company/Region 展示与 Id 数组仍由 `fl_label_template_location`（及已迁移时的 partner/region 关联表）推断，**不依赖**主表 scope 列。
  
  ### 接口说明
  
  | 项目 | 内容 |
  |------|------|
  | 方法 | `GET` |
  | 路径 | `/api/app/label-template` |
  | 鉴权 | Bearer Token |
  
  **入参（Query）**
  
  | 参数 | 说明 |
  |------|------|
  | `SkipCount` | 页码，从 1 起 |
  | `MaxResultCount` | 每页条数 |
  | `Keyword` | 模板名称/编码模糊搜索 |
  | `PartnerId` / `GroupId` / `LocationId` | 适用范围筛选 |
  | `LabelType` / `State` / `Sorting` | 其它筛选与排序（`Sorting` 白名单字段） |
  
  **出参 `items[]` 要点**
  
  | 字段 | 说明 |
  |------|------|
  | `id` / `templateCode` | 模板编码 |
  | `company` / `region` / `location` | 适用范围展示 |
  | `partnerIds` / `regionIds` / `locationIds` | 对应 Id 数组 |
  | `printOrientation` | 打印方向 `vertical` / `horizontal` |
  | `sizeText` / `contentsCount` / `lastEdited` | 尺寸、控件数、最近编辑 |
  
  ### 请求示例
  
  ```bash
  curl -G "http://flus-test.3ffoodsafety.com/api/app/label-template" \
    -H "Authorization: Bearer {token}" \
    --data-urlencode "SkipCount=1" \
    --data-urlencode "MaxResultCount=10"
  ```
  
  ### 部署注意
  
  1. **必须**重新编译 `FoodLabeling.Application` 并**完全重启** Web 进程；若 Yi-SQL 仍出现 `AppliedPartnerType`，说明旧 DLL 未替换。
  2. 可选：执行 `scripts/fl_label_template_scope.sql` 启用 Company/Region 主表列与关联表（非列表 500 的必要条件）。
  3. 可选：为 `BorderType` 增加列后，`SetBorderTypeAsync` / `GetBorderTypeForTemplateAsync` 会自动读写；未迁移时详情/预览 `border` 默认为 `none`。
  
  ---
  
  ## 十一、我的菜单 500 修复（`GET /api/app/auth-session/my-menus`）
  
  ### 现象
  
  `GET /api/app/auth-session/my-menus` 返回 **500**，日志：
  
  ```text
  Unknown column 'r.AccessPermissionCodesJson' in 'field list'
  ```
  
  对应 SQL 错误地 SELECT 了 `Role.AccessPermissionCodesJson`。
  
  ### 根因
  
  | 层级 | 名称 |
  |------|------|
  | C# 属性 | `RoleAggregateRoot.AccessPermissionCodesJson` |
  | **数据库列** | **`Role.AccessPermissionCodes`**（`VARCHAR`，JSON 数组字符串） |
  
  `UserRoleAccessPermissionHelper` 直写 SQL 时误用了 C# 属性名作为列名，导致 MySQL 报列不存在。
  
  **MCP 查库**：`Role` 表**有** `AccessPermissionCodes` 列，**无** `AccessPermissionCodesJson` 列。
  
  ### 修复说明
  
  | 文件 | 改动 |
  |------|------|
  | `RoleAccessPermissionSchemaHelper.cs` | **新增**：探测 `Role.AccessPermissionCodes` 列是否存在 |
  | `UserRoleAccessPermissionHelper.cs` | SQL 改为读 `AccessPermissionCodes`；列不存在时返回空数组 |
  | DTO 注释 | 统一说明库字段名为 `AccessPermissionCodes` |
  
  未执行列迁移的环境（无 `AccessPermissionCodes`）接口仍可返回菜单树，`accessPermissionCodes` 为空数组，不 500。
  
  ### 接口说明
  
  | 项目 | 内容 |
  |------|------|
  | 方法 | `GET` |
  | 路径 | `/api/app/auth-session/my-menus` |
  | 鉴权 | Bearer Token（须已登录） |
  
  **出参要点（`CurrentUserMenuPermissionsOutputDto`）**
  
  | 字段 | 说明 |
  |------|------|
  | `user` | 当前用户摘要（id、userName、nick、email 等） |
  | `roleCodes` | JWT 中的角色编码列表 |
  | `role` | 角色展示名 |
  | `menus` | 树形菜单（admin 返回全部未删除菜单；其它用户按 RoleMenu 关联） |
  | `permissionCodes` | 可见菜单的 `PermissionCode` 去重列表 |
  | `accessPermissionCodes` | 绑定角色 `AccessPermissionCodes` JSON 合并（如 `manage_people`、`manage_labels`） |
  | `lastUpdated` | 用户最后修改时间 |
  
  **`accessPermissionCodes` 与菜单的关系**
  
  - 菜单可见性仍由 **RoleMenu + Menu** 决定；
  - `accessPermissionCodes` 用于前端/Account Management 等「访问权限」勾选项（Region/Location 管理等能力开关）；
  - 列未迁移时该数组为空，不影响基础菜单加载。
  
  ### 数据库（可选迁移）
  
  若库中尚无 `AccessPermissionCodes` 列，可执行：
  
  `scripts/repair_after_clear_keep_admin_menu_role.sql` 第 1 段，或：
  
  ```sql
  ALTER TABLE `Role`
    ADD COLUMN `AccessPermissionCodes` VARCHAR(2000) NULL
    COMMENT '访问权限 JSON 数组，如 ["manage_labels","manage_people"]';
  ```
  
  ### 请求示例
  
  ```bash
  curl -G "http://flus-test.3ffoodsafety.com/api/app/auth-session/my-menus" \
    -H "Authorization: Bearer {token}"
  ```
  
  ### 响应片段
  
  ```json
  {
    "user": { "id": "...", "userName": "admin", "nick": "Admin" },
    "roleCodes": ["admin"],
    "permissionCodes": ["menu.labels", "menu.reports"],
    "accessPermissionCodes": ["manage_labels", "manage_people"],
    "menus": [ { "id": "...", "menuName": "Labels", "router": "/labels", "children": [] } ]
  }
  ```
  
  ### 部署注意
  
  1. 重新编译并重启 Web 进程；
  2. 若仍报 `AccessPermissionCodesJson`，说明旧 DLL 未替换；
  3. 无 `AccessPermissionCodes` 列时接口可正常返回菜单，仅 `accessPermissionCodes` 为空。