FoodLabeling.Application.Contracts 当前登录用户简要信息（不含敏感字段） 当前用户可见菜单树节点（与权限分配一致） 当前登录用户的菜单与权限码（用于前端动态路由/按钮权限） 分页返回（包含当前页、总页数） 列表项类型 当前页码（从 1 开始） 每页条数 总条数 总页数 列表数据 分类分布项 分类Id 分类名称 数量 占比（百分比） 日趋势点 日期（yyyy-MM-dd） 值 仪表盘指标卡片 指标唯一标识（如 labelsPrintedToday） 指标标题 当前值 对比周期值 增减值（Value - PreviousValue） 增减比例（百分比） 仪表盘总览输出 今日打印标签 启用模板数 活跃用户数 门店数 人员数 产品数 指标卡片 近7天打印趋势 按分类分布 分类分布总数 按分类分布（前端直观命名） 按分类分布总数（前端直观命名） 最近打印标签（全门店最新若干条，用于 Recent Labels 区块） 统计时间 Dashboard「Recent Labels」单行数据（最近打印记录） 打印任务 Id（fl_label_print_task.Id） 标签编码（界面 Serial / Label ID，如 1-251201） 展示名称：优先产品名，否则标签名称 打印人用户 Id（CreatedBy） 打印人展示名（User.Name 或 UserName） 打印时间（PrintedAt 优先，否则 CreationTime） 状态：active 或 expired（依据 PrintInputJson 中保质期与当前日期比较） 角标/尺寸短文案（如 2"x2"，用于左侧圆标） 新建组织入参 指派到的合作伙伴 Id（Assign to Partner） 组织（Group）分页查询入参 模糊搜索（GroupName、所属 Partner 的 PartnerName） 按所属合作伙伴筛选（fl_partner.Id） 启用状态 组织列表项 所属合作伙伴名称（列表「Parent Partner」列） 组织详情 编辑组织入参 按钮展示文案（为空则默认使用 CategoryName） COLOR 模式存色值、IMAGE 模式存图片 URL、TEXT 可为分类小图或空（与 buttonAppearance 配合） 按钮外观：TEXT / COLOR / IMAGE（展示值见 categoryPhotoUrl） 门店可用范围：ALL / SPECIFIED 指定门店 Id 列表（当 AvailabilityType=SPECIFIED 时必填） editor JSON 里的 id，对应数据库 fl_label_template.TemplateCode editor JSON 里的 name，对应数据库 fl_label_template.TemplateName editor JSON 里的 appliedLocation（ALL / SPECIFIED） 预留：前端可能不传；如果不传则默认 true elements（前端 editor 的 elements[]，会全量重建） 当 AppliedLocationType=SPECIFIED 时生效 模板与产品/标签类型绑定默认值 模板元素（对齐 editor JSON：id/type/typeAdd/elementName/x/y/width/height/rotation/border/config 等） 元素附加类型（分组前缀 + 控件名），如 label_Duration 值来源：FIXED / AUTO_DB / PRINT_INPUT 元素配置 标签模板分页查询入参 关键字（模板名称/模板编码） 门店Id（用于筛选：ALL 或指定门店） 标签类型（例如 PRICE） 状态 位置展示：All Locations 或首个指定门店的名称 elements 数量（Contents） 模板与产品/标签类型绑定后的默认值行 默认值JSON（建议结构：{ "el-xxx": "默认值" }） 标签分页列表入参（按产品展示多个标签） 门店Id（可选） 产品Id（可选；用于“一个产品展示多个标签”） 模板编码（可选） 同一个标签绑定的产品名称，用 “,” 分割 绑定模板的编码（与详情接口一致，供管理端「录入数据」等按模板操作） 模板缺失字段告警（当前阶段暂定 false） 标签编码（fl_label.LabelCode） 选择用于预览的产品Id（fl_product.Id） 如果不传，默认取该标签绑定的第一个产品 业务基准时间（用于 DATE/TIME 元素的渲染计算） 不传则默认使用服务器当前时间 打印输入（前端传，用于 PRINT_INPUT 元素） key 建议使用模板元素的 InputKey 预览输出：与前端 LabelCanvas/LabelPreviewOnly 的 LabelTemplate 结构尽量一致 新增门店 Support 联系方式 门店 Support 联系方式详情 编辑门店 Support 联系方式 Location Manager 批量导入（Excel） 上传的 Excel 文件（与模板列一致） Location 批量导入结果 门店批量编辑（网格「保存全部」）请求体 待保存的行；id 为 。可含空行：忽略 的项。 单行编辑数据：主键 + 与单条 PUT /location/{id} 相同的可编辑字段。 门店主键（非空、非 Empty 时才会更新） 门店批量编辑结果 批量编辑中单条失败信息 在请求 items 数组中的序号（从 1 开始，与前端网格行对应） 新增门店入参 Location ID（业务编码） 门店分页查询入参 模糊搜索（Location ID/Name/Street/City/State/Country/Zip/Phone/Email） Partner Group 启用状态 门店列表输出 编辑门店入参 Location Name 启用状态 新建合作伙伴入参 合作伙伴分页查询入参 模糊搜索（PartnerName / ContactEmail / PhoneNumber） 启用状态（与列表筛选一致） 合作伙伴列表项 合作伙伴详情 编辑合作伙伴入参 可选子目录（相对路径），例如：category、category/2026-03 可直接保存到业务表的访问 URL（相对路径） 产品模块：新增类别入参 按钮展示文案（为空则默认使用 CategoryName） COLOR 模式存色值、IMAGE 模式存图片 URL、TEXT 可为分类小图或空（与 buttonAppearance 配合） 按钮外观：TEXT / COLOR / IMAGE（展示值见 categoryPhotoUrl） 门店可用范围：ALL / SPECIFIED 指定门店 Id 列表（当 AvailabilityType=SPECIFIED 时必填） 产品模块：类别分页列表入参 模糊搜索（CategoryCode/CategoryName） 启用状态过滤 产品模块：类别列表行 产品模块：类别详情 COLOR 色值 / IMAGE 图片 URL / TEXT 可选图 产品模块：编辑类别入参 门店Id 产品Id列表 产品-门店分页查询入参 门店Id（location.Id，string 表示） 产品Id（fl_product.Id，string） 产品Id列表（将替换当前门店下的全部产品关联） Product 批量导入（Excel） 上传的 Excel（列：Location / Product Category / Product / Product Code） Product 批量编辑（网格保存全部） 单行：产品主键（字符串 Guid）+ 与单条 PUT 相同的 body 字段。 可选。不传或空则创建时由后端生成唯一编码（如 PRD_xxxxxxxx）。 可选。门店 Id 列表；每个 Id 在 fl_location_product 落一行（同一 fl_product 可对应多门店）。 不传或空列表则不在本接口写入门店关联（仍可用 product-location 接口维护）。 产品分页查询入参 模糊搜索（ProductCode/ProductName/CategoryName） 启用状态 该产品关联的标签数量（fl_label_product + fl_label） 该产品关联的门店Id列表（来自 fl_location_product） 新增权限(Menu)入参（美国版对外） 父级ID（menu 表为字符串ID，可能是数字；根节点默认 0） 权限(Menu)分页查询入参（美国版对外） 菜单来源（与 rbac 的 MenuSource 含义一致，int 存储） 权限(Menu)列表输出（美国版对外） 权限树节点（返回菜单表全部字段） 编辑权限(Menu)入参（美国版对外） 角色-权限移除入参 角色-权限设置入参（覆盖式） 角色ID 菜单ID列表（覆盖式） 新增角色入参（美国版对外） 数据范围（与 rbac 的 DataScope 含义一致，int 存储） 角色分页查询入参（美国版对外） 角色名称（模糊） 角色编码（模糊） 启用状态 角色列表输出（美国版对外） 角色详情输出（美国版对外） 该角色已分配的菜单权限ID列表 编辑角色入参（美国版对外） Label Report 聚合结果（卡片 + 图表 + Top 产品表） 按标签分类的打印量（柱状图） 折线图：默认统计区间内最后 7 个自然日（按日汇总） 用量最高的产品（含占比） 相对上一同长周期变化率（百分比，如 20.1 表示 +20.1%） Label Report 统计与导出共用筛选 Web Reports — Print Log 分页查询 Print Log 列表行（Reports 管理端） 打印任务 Id（fl_label_print_task.Id），重打时使用 标签编码（展示为 Label ID） 分类展示名（优先产品分类，否则标签分类） 模板展示（尺寸 + 模板名） 打印人姓名 门店展示：名称 (编码) 门店 Id（重打校验用） 从 PrintInputJson 尽力解析的保质期文本；无则「无」 Team Member 批量导入（Excel） 上传的 Excel 文件（与模板列一致） Team Member 批量导入结果 Team Member 批量编辑（网格「保存全部」）请求体 待保存的行；id 为成员主键。可含空行：忽略 id 为全零 GUID 的项。 单行：主键 + 与单条 PUT 更新相同的字段。 登录账号（建议用邮箱或自定义用户名） 关联门店（至少1个） 成员分页查询入参 关键字（姓名/用户名/邮箱/电话） 角色ID（可选） 门店ID（可选） 启用状态（可选） 角色（当前仅返回第一个） 为空表示不改密码 App 端展示的绑定门店信息 门店主键 Id（Guid 字符串） 业务编码，如 LOC-1 门店名称 拼接后的完整地址，便于移动端展示 门店是否启用 App 修改密码入参 当前密码 新密码 确认新密码 App「Location」门店详情（与原型字段对齐） 门店主键（Guid 字符串） 门店名称 完整地址（街道、城市、州、邮编拼接；无则为「无」） 门店电话（来自 location.Phone；空为「无」） 营业时间；当前库无字段，固定返回「无」直至业务落库 店长姓名；优先取绑定本店且角色名/编码含 manager 的用户 店长电话；同上用户 User.Phone 格式化；无则为「无」 美国版 App 登录入参（使用邮箱作为账号，支持图形验证码） 登录邮箱（对应 user.Email） 图形验证码 UUID（开启验证码时必填） 图形验证码（开启验证码时必填） 美国版 App 登录返回（含 Token 与绑定门店） 当前账号在 userlocation 中绑定的门店列表 App「我的资料」展示数据（My Profile） 全名（Name，无则 Nick，再无则 UserName） 邮箱 电话展示（如 +1 (555) 123-4567）；无则「无」 员工号/登录名（当前使用 User.UserName，可与业务约定为工号） 角色展示名（多角色英文逗号拼接，按角色 OrderNum） 主角色编码（第一个角色 RoleCode，供前端样式） 打印明细快照（接口 10，对应 fl_label_print_data 解析后的元素级信息） 元素完整 JSON（与 LabelTemplateElementDto / 编辑器 elements[] 项同构），供 App 重打组装模板。 App 打印日志分页查询入参（仅当前登录账号 + 当前门店） 当前门店 Id（location.Id，Guid 字符串） 打印日志列表项 任务Id（fl_label_print_task.Id） 批次Id（同一次点击 Print 共享） 第几份（从 1 开始） 标签Id 标签编码 产品Id 产品名称 标签类型名称（来自 fl_label_type.TypeName） 模板尺寸（来自 fl_label_template.Width/Height/Unit） 打印入参 JSON（直接来自 fl_label_print_task.PrintInputJson 列） 打印时间（PrintedAt ?? CreationTime） 操作人姓名（当前登录账号 Name） 门店名称 第一级：标签分类（fl_label_category） 按钮外观：TEXT / COLOR / IMAGE（COLOR/IMAGE 的展示值在 categoryPhotoUrl） 第三级：产品卡片（同一产品 Id 若存在多套标签模板，按 TemplateId 拆成多条，便于端上多卡展示） 当前卡片对应 fl_label.TemplateId；与 ProductId 共同唯一标识一张卡 当前卡片所用模板编码（与四级节点一致） 当前卡片模板尺寸文案（如 6.00x12.00cm） 副标题（无独立业务字段时：有编码显示编码，否则「无」） 第四级：该产品在当前标签分类+门店下可选的标签种类 App Labeling 四级列表入参 当前门店 Id（location.Id，Guid 字符串） 关键词（匹配标签分类/产品分类/产品名/标签类型/标签名称） 仅展示某一标签分类（侧边栏选中时传）；不传则返回全部分类 App 标签预览出参（顶部信息 + 预览模板结构） 预览图（base64 png，可空；若为空，客户端可用 Template 自行渲染） 预览模板结构（与 LabelCanvas/LabelPreviewOnly 结构尽量一致） 当前预览上下文（模板+产品+标签类型）命中的默认值配置。 数据来源：fl_label_template_product_default.DefaultValuesJson App 标签预览入参 门店Id（fl_label.LocationId） 标签编码（fl_label.LabelCode） 选择用于预览的产品Id（fl_product.Id） 不传则默认取该标签绑定的第一个产品 业务基准时间（用于 DATE/TIME 等元素的计算） 打印输入（用于 PRINT_INPUT 元素） App 打印入参 门店Id（fl_label.LocationId） 标签编码（fl_label.LabelCode） 选择用于打印的产品Id（fl_product.Id） 不传则默认取该标签绑定的第一个产品 打印份数（<=0 则按 1 处理） 客户端幂等请求Id（可选）。 同一个 clientRequestId 重复调用 print 接口时，后端会直接返回首次创建的 batchId/taskIds，不会重复写库。 业务基准时间（用于 DATE/TIME 等元素的计算） 打印数据（对齐《标签模块接口对接说明(10)》）： - App 推荐传：与平台导出 label-template-*.json 同构的合并后模板（含 elements[].config），便于落库后直接重打； - 兼容旧客户端：扁平字典（key 对齐元素 inputKey），由服务端 PreviewAsync 解析生成 RenderDataJson。 打印机Id（可选，若业务需要追踪） 打印机蓝牙 MAC（可选） 打印机地址（可选） App 打印出参（接口 9 / 11） App 重新打印入参（根据历史任务Id重打） 当前门店Id（用于权限校验，必须与历史任务一致） 历史打印任务Id（fl_label_print_task.Id） 重新打印份数（<=0 则按 1 处理；默认 1） 客户端幂等请求Id（可选）。 同一个 clientRequestId 重复调用 reprint 接口时，后端会直接返回首次创建的 batchId/taskIds，不会重复写库。 重新打印时可覆盖打印机Id（可选） 重新打印时可覆盖打印机蓝牙 MAC（可选） 重新打印时可覆盖打印机地址（可选） 第四级：标签种类（对应一条可打印的标签实例） 业务标签编码，预览/打印流程使用 模板物理尺寸描述，如 2"x2" 第二级：产品分类（fl_product.CategoryId join fl_product_category） 产品分类Id；当产品未归类或分类不存在时为空 产品分类图片地址；当产品未归类或分类不存在时为空 分类显示名；空为「无」 按钮展示文案；为空时客户端可回退使用 Name 按钮外观：TEXT / COLOR / IMAGE（COLOR/IMAGE 的展示值在 categoryPhotoUrl） 门店可用范围：ALL / SPECIFIED（本树已按当前门店过滤） 排序号（来自 fl_product_category；未归类为较大值以排在后） Food Labeling 模块 - 应用契约层（美国版） 当前登录会话：菜单权限与退出（美国版 Web 管理端） 获取当前登录用户的角色编码、权限码与可见菜单树 与框架 UserManager.GetInfoAsync 一致；用户名为 admin 时返回全部未删除菜单（与 AccountService.GetVue3Router 行为对齐）。 用户简要信息、权限码与菜单树 成功 未登录或令牌无效 服务器错误 退出登录：清除服务端用户信息缓存（JWT 仍由前端丢弃） 与框架 AccountService.PostLogout 一致；未登录时返回 false。 是否执行了缓存清理（已登录为 true） 成功 服务器错误 Dashboard 统计接口（美国版） 获取 Dashboard 总览统计（卡片 + 周趋势 + 分类分布 + Recent Labels 最近打印） Food Labeling 示例应用服务接口（美国版） 简单问候示例接口 姓名 问候语 组织（Group）管理接口（fl_group） 组织分页列表（与导出使用相同筛选条件） 分页与筛选；SkipCount 为页码（从 1 起） 组织详情 新增组织 编辑组织 删除组织（逻辑删除） 按列表相同筛选条件全量导出组织（Region）为 PDF（不分页；与 相同筛选；单次最多 5000 条） Keyword、PartnerId、State、Sorting；分页字段忽略 application/pdf 标签管理接口（美国版） 按产品分页列表（一个产品展示多个标签） 标签详情（id=LabelCode） 新增标签 编辑标签（id=LabelCode） 删除标签（逻辑删除） 标签预览：解析模板 AUTO_DB/PRINT_INPUT（不做打印落库） 标签模板管理接口（美国版对外） 标签模板分页列表 标签模板详情（含 elements 与适用门店） 新增标签模板 编辑标签模板（版本号 +1，重建 elements） 删除标签模板（逻辑删除；若已被标签引用则禁止） 门店管理接口（美国版） 门店分页列表 查询条件 新增门店 门店信息 编辑门店 门店Id 门店信息 删除门店（逻辑删除） 门店Id 下载 Location Manager 批量导入模板（读取服务器 batchImportOfFiles 目录下 xlsx） 按列表筛选条件全量导出门店为 Excel（与列表相同过滤与排序，不分页、不限条数） 批量导入门店（Excel，multipart/form-data 字段 file） 批量编辑门店（网格保存全部，JSON 一次提交多行） 每行通过 id 定位门店，字段与单条 PUT /location/{id} 一致；id 为 的项忽略。 示例请求： ```json { "items": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "partner": "MedVantage Cafe Group", "groupName": "NC Region", "locationName": "UNCC store", "street": "222 School House Lane", "city": "Charlotte", "stateCode": "NC", "country": "USA", "zipCode": "29889", "phone": "2123456789", "email": "nc@example.com", "latitude": 35.3, "longitude": -80.7, "state": true } ] } ``` 参数说明： - items: 编辑行数组；单行失败不影响其它行提交结果汇总 批量编辑请求体 成功数、失败数及失败明细 全部或部分行处理完成，见返回体中的计数与 errors 整单校验失败（如超过单次条数上限、items 为空） 服务器错误 全局 Support 联系方式（全平台共用；Web 可增改查，App 仅可查） 查询全局 Support 联系方式（已登录即可；App / Web 共用） 新增全局 Support 联系方式（系统仅允许一条；Web 管理端） 联系方式 编辑全局 Support 联系方式（Web 管理端） 联系方式主键 联系方式 合作伙伴管理接口（fl_partner） 合作伙伴分页列表（与导出使用相同筛选条件） 分页与筛选；SkipCount 为页码（从 1 起） 分页数据 成功 参数错误 服务器错误 合作伙伴详情 主键 Id 详情 成功 Id 无效 服务器错误 新增合作伙伴 名称、邮箱、电话、启用状态 新建后的详情 示例请求： ```json { "partnerName": "Global Foods Inc.", "contactEmail": "admin@globalfoods.com", "phoneNumber": "+1 (555) 100-2000", "state": true } ``` 成功 校验失败 服务器错误 编辑合作伙伴 主键 Id 名称、邮箱、电话、启用状态 更新后的详情 成功 校验失败或记录不存在 服务器错误 删除合作伙伴（逻辑删除） 主键 Id 成功 Id 无效或记录不存在 服务器错误 按当前列表筛选条件批量导出合作伙伴为 PDF（Account Management「Company」页签；不分页，上限 5000 条） 与列表相同的 Keyword、State；分页字段忽略 PDF 文件流 筛选条件需与 一致，便于统计与导出数据对齐。 成功返回 application/pdf 参数错误 服务器错误 产品管理接口（Products，fl_product） 产品分页列表 产品详情 产品主键（Guid，与 fl_product.Id 一致；使用 Guid 路由约束，避免与 export-* 等字面路径冲突） 新增产品 可选；为空时后端生成唯一编码（如 PRD_ + Guid）。 若 有值，将在同一事务内批量写入 fl_location_product（一门店一条）。 编辑产品 当请求体包含 属性时，按该列表整表替换本产品在各门店的关联； 不传该属性则不改门店关联（兼容仅改名称/分类等调用）。 删除产品（逻辑删除） 下载 Product 批量导入模板（服务器 TemplateDirectory 下 xlsx） 按列表筛选条件全量导出产品为 Excel（与列表相同过滤；不分页） 批量导入产品（Excel，multipart/form-data 字段 file） 批量编辑产品（JSON 一次提交多行，与单条 PUT 字段一致） 产品模块：类别（Categories）接口 产品-门店关联管理（fl_location_product） 关联分页列表（可按门店Id/产品Id过滤） 门店下的全部产品（id=LocationId） 新增/批量建立门店与产品的关联 编辑：替换该门店下的全部产品关联 删除：删除该门店的全部产品关联 权限(Menu)管理接口（仅用于食品标签-美国版对外） 权限列表（不分页） 权限详情 新增权限 编辑权限 删除权限（逻辑删除） 获取全部权限树（GET） 树状权限列表 角色管理接口（仅用于食品标签-美国版对外） 角色分页列表 角色详情 新增角色 编辑角色 删除角色（逻辑删除） 角色-权限关联接口（仅用于食品标签-美国版对外） 覆盖式设置角色的菜单权限 获取角色已分配的菜单ID列表 移除角色的指定菜单权限 Reports（Print Log / Label Report）管理端接口 Print Log 分页列表；角色 admin 可查全部，否则仅当前用户打印记录。 Print Log 导出 PDF（筛选与列表一致，最多 5000 条） Print Log 全量导出 Excel（筛选与列表一致；排序与列表 PrintedAt 规则一致；最多 5000 条） 根据历史任务重打（与 App 入参一致）；admin 可重打任意用户任务，否则仅本人任务。 Label Report 统计（卡片 + 分类柱数据 + 7 日趋势 + Top 产品）；admin 统计全部，否则仅当前用户。 Label Report 导出 PDF 下载 Team Member 批量导入模板（服务器 batchImportOfFiles 目录下 xlsx） 按列表筛选条件全量导出成员为 PDF（与列表相同过滤；不分页、不限条数） 批量导入成员（Excel，multipart/form-data 字段 file） 批量编辑成员（JSON 一次提交多行） 美国版移动端认证（登录返回绑定门店） App 登录：使用邮箱 + 密码校验并签发 Token，同时返回 userlocation 绑定的门店 获取当前登录账号已绑定的门店（用于切换门店等场景） 获取当前登录用户资料（My Profile：姓名、邮箱、电话、员工号、角色） 资料 DTO 成功 未登录或用户不存在 服务器错误 当前登录用户修改密码（校验原密码与复杂度规则） 当前密码、新密码、确认密码 新密码需满足：至少 8 位；含大写与小写字母；至少 1 位数字；至少 1 个非字母数字特殊字符。 成功 参数或校验失败 服务器错误 按门店 Id 查询 Location 详情（须为当前账号 userlocation 绑定门店） 门店 Guid 字符串 店名、地址、电话、营业时间占位、店长信息 成功 参数非法、未绑定或无权限 服务器错误 App Labeling：四级列表（标签分类 → 产品分类 → 产品卡片「按模板拆分」→ 标签种类） 获取当前门店下四级嵌套树，供移动端 Labeling 首页使用 App 打印预览：按标签编码解析模板并返回顶部展示字段 + 预览模板结构 App 打印：创建打印任务并落库打印明细（fl_label_print_task / fl_label_print_data） App 重新打印：根据历史任务Id重打（创建新任务与明细） App 打印日志：获取当前登录账号在当前门店打印的记录（分页，时间倒序） 美国版 App JWT 自定义声明（用于与 Web 管理端 Token 区分能力） 声明类型：客户端种类 美国版移动端 App