合作伙伴（Partner）与组织（Group）接口对接说明

适用范围：美国版 Web 管理端「Account Management」下的 Partner、Group 主数据
Partner 表：fl_partner，接口：IPartnerAppService / PartnerAppService
Group 表：fl_group（PartnerId 关联 fl_partner.Id），接口：IGroupAppService / GroupAppService
宿主路由前缀：/api/app（与 YiAbpWebModule 中 RootPath = api/app 一致）

---

0. 通用说明

• 鉴权：需要登录（Authorization: Bearer {token}），与其它 /api/app/* 接口一致。
• Content-Type：POST / PUT 使用 application/json。
• 分页约定（美国版食品标签模块）：skipCount 表示页码（从 1 起），不是 0 基 offset；第一页请传 skipCount=1。与 PagedQueryConvention 及 SqlSugar ToPageListAsync 用法一致。
• 逻辑删除：DELETE 将对应表的 IsDeleted 置为 true（fl_partner / fl_group），不物理删行。
• 列表与导出筛选一致：各模块列表的筛选字段与对应 export-pdf 接口一致，便于数据对齐。
• Group 与 Partner：新建/编辑 Group 时 partnerId 必须指向未逻辑删除的 fl_partner；列表左联 Partner 时仅展示未删除合作伙伴名称，已删 Partner 在列表中显示为 无。

---

第一部分：Partner（合作伙伴）

1. 分页列表

• 方法：GET
• 路径：/api/app/partner

1.1 查询参数（PartnerGetListInputVo）

参数	类型	必填	说明
skipCount	int	是	页码，从 1 开始
maxResultCount	int	是	每页条数
sorting	string	否	排序，仅支持白名单（见下）
keyword	string	否	模糊匹配 PartnerName、ContactEmail、PhoneNumber
state	bool	否	按启用状态筛选；不传则不过滤

排序白名单（大小写不敏感）：

• PartnerName asc / PartnerName desc
• CreationTime asc / CreationTime desc
• State asc / State desc

其它值将回退为默认：按 CreationTime 降序。

1.2 请求示例

GET /api/app/partner?skipCount=1&maxResultCount=10&keyword=Global&state=true&sorting=CreationTime%20desc HTTP/1.1
Authorization: Bearer {token}

1.3 响应结构（PagedResultWithPageDto<PartnerGetListOutputDto>）

{
  "pageIndex": 1,
  "pageSize": 10,
  "totalCount": 2,
  "totalPages": 1,
  "items": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "partnerName": "Global Foods Inc.",
      "contactEmail": "admin@globalfoods.com",
      "phoneNumber": "+1 (555) 100-2000",
      "state": true,
      "creationTime": "2026-04-27T10:00:00"
    }
  ]
}

1.4 列表项字段（PartnerGetListOutputDto）

字段	类型	说明
id	string	主键
partnerName	string	合作伙伴名称
contactEmail	string \	null
phoneNumber	string \	null
state	bool	是否启用（UI Active 开关）
creationTime	string (datetime)	创建时间

---

2. 详情

• 方法：GET
• 路径：/api/app/partner/{id}

2.1 路径参数

参数	说明
id	fl_partner.Id

2.2 响应结构（PartnerGetOutputDto）

字段	类型	说明
id	string	主键
partnerName	string	合作伙伴名称
contactEmail	string \	null
phoneNumber	string \	null
state	bool	是否启用
creationTime	string (datetime)	创建时间
lastModificationTime	string (datetime) \	null

2.3 错误说明

• id 为空或记录不存在（含已逻辑删除）：业务错误提示「合作伙伴不存在」等。

---

3. 新增

• 方法：POST
• 路径：/api/app/partner

3.1 Body（PartnerCreateInputVo）

{
  "partnerName": "Global Foods Inc.",
  "contactEmail": "admin@globalfoods.com",
  "phoneNumber": "+1 (555) 100-2000",
  "state": true
}

字段	类型	必填	说明
partnerName	string	是	合作伙伴名称，去首尾空格后不能为空
contactEmail	string	否	若填写则做简单格式校验（含 @ 等）
phoneNumber	string	否	电话
state	bool	否	默认 true

3.2 响应

• 成功：返回 PartnerGetOutputDto（与详情结构一致）。

---

4. 编辑

• 方法：PUT
• 路径：/api/app/partner/{id}

4.1 参数

• Path：id 为当前合作伙伴主键。
• Body：PartnerUpdateInputVo，字段与新增相同。

{
  "partnerName": "Global Foods Inc.",
  "contactEmail": "admin@globalfoods.com",
  "phoneNumber": "+1 (555) 100-2000",
  "state": false
}

4.2 响应

• 成功：返回更新后的 PartnerGetOutputDto。

---

5. 删除（逻辑删除）

• 方法：DELETE
• 路径：/api/app/partner/{id}

5.1 路径参数

参数	说明
id	fl_partner.Id

5.2 行为

• 将 IsDeleted 置为 true，并更新 LastModificationTime / LastModifierId（若当前用户存在）。

---

6. 批量导出 PDF

• 方法：GET
• 路径：/api/app/partner/export-pdf
• 响应：Content-Type: application/pdf，附件名形如 partners_yyyy-MM-dd_HH-mm-ss.pdf

6.1 查询参数

与列表接口相同的筛选字段（分页字段可忽略）：

参数	类型	必填	说明
keyword	string	否	与列表 keyword 一致
state	bool	否	与列表 state 一致
sorting	string	否	与列表白名单一致，用于导出行顺序

6.2 限制

• 命中行数 超过 5000 时接口返回业务错误，需缩小筛选范围后再导出。
• 导出最多取 5000 条，排序与列表查询逻辑一致。

6.3 请求示例

GET /api/app/partner/export-pdf?keyword=Global&state=true HTTP/1.1
Authorization: Bearer {token}

6.4 PDF 内容说明

• 表头列：Partner、Contact、Phone、Status、Created。
• Status 文本：state === true 时为 active，否则 inactive。
• 空邮箱、空电话在 PDF 中显示为 无（与项目列表空值展示约定一致）。

---

7. 数据库与建表（Partner）

• 建表脚本：美国版/Food Labeling Management Code/Yi.Abp.Net8/module/food-labeling-us/scripts/fl_partner_create.sql
• 主要字段：Id、IsDeleted、CreationTime、CreatorId、LastModificationTime、LastModifierId、PartnerName、ContactEmail、PhoneNumber、State

---

8. 与门店字段的关系说明

• 门店（location）上可能存在 Partner 字符串字段（原型/筛选用），与本文 fl_partner 主数据表 无强制外键关联。
• 若后续要将门店关联到合作伙伴主数据，需单独产品方案（例如增加 PartnerId 或同步名称）。

---

9. 前端对接提示（Partner）

• 列表「Search」对应 keyword；「Active」筛选对应 state。
• 「Bulk Export (PDF)」调用 第 6 节 导出接口，查询参数与当前列表筛选保持一致即可。

---

第二部分：Group（组织 / Group）

UI：Group Name、Parent Partner（下拉绑定合作伙伴）、Status、Bulk Export (PDF)、New+ 弹窗（Group Name、Assign to Partner、Active）。

10. 数据库与建表（Group）

• 库中原先无独立 Group 业务表；新建表名：fl_group。
• 建表脚本：美国版/Food Labeling Management Code/Yi.Abp.Net8/module/food-labeling-us/scripts/fl_group_create.sql
• 须先存在 fl_partner 表（脚本内含外键 FK_fl_group_partner → fl_partner(Id)）。
• 主要字段：Id、IsDeleted、CreationTime、CreatorId、LastModificationTime、LastModifierId、GroupName、PartnerId、State

建表 SQL（与脚本文件一致，便于直接执行）：

CREATE TABLE IF NOT EXISTS `fl_group` (
  `Id` varchar(64) NOT NULL COMMENT '主键',
  `IsDeleted` tinyint(1) NOT NULL DEFAULT 0 COMMENT '逻辑删除',
  `CreationTime` datetime(6) NOT NULL COMMENT '创建时间',
  `CreatorId` varchar(64) DEFAULT NULL COMMENT '创建人',
  `LastModificationTime` datetime(6) DEFAULT NULL COMMENT '最后修改时间',
  `LastModifierId` varchar(64) DEFAULT NULL COMMENT '最后修改人',
  `GroupName` varchar(256) NOT NULL COMMENT '组织名称',
  `PartnerId` varchar(64) NOT NULL COMMENT '所属合作伙伴 fl_partner.Id',
  `State` tinyint(1) NOT NULL DEFAULT 1 COMMENT '是否启用',
  PRIMARY KEY (`Id`),
  KEY `IX_fl_group_IsDeleted` (`IsDeleted`),
  KEY `IX_fl_group_State` (`State`),
  KEY `IX_fl_group_PartnerId` (`PartnerId`),
  KEY `IX_fl_group_GroupName` (`GroupName`(128)),
  KEY `IX_fl_group_CreationTime` (`CreationTime`),
  CONSTRAINT `FK_fl_group_partner` FOREIGN KEY (`PartnerId`) REFERENCES `fl_partner` (`Id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='组织（Group）';

---

11. Group — 分页列表

• 方法：GET
• 路径：/api/app/group

11.1 查询参数（GroupGetListInputVo）

参数	类型	必填	说明
skipCount	int	是	页码，从 1 开始
maxResultCount	int	是	每页条数
sorting	string	否	排序白名单（见下）
keyword	string	否	模糊匹配 GroupName、所属 未删除 Partner 的 PartnerName
partnerId	string	否	仅查看某合作伙伴下的组织（fl_partner.Id）
state	bool	否	按启用状态筛选；不传则不过滤

排序白名单（大小写不敏感）：

• GroupName asc / GroupName desc
• CreationTime asc / CreationTime desc
• State asc / State desc
• PartnerName asc / PartnerName desc（按关联合作伙伴名称）

其它值回退为默认：按 CreationTime 降序。

11.2 请求示例

GET /api/app/group?skipCount=1&maxResultCount=10&keyword=West&partnerId={partnerGuid}&state=true HTTP/1.1
Authorization: Bearer {token}

11.3 响应结构（PagedResultWithPageDto<GroupGetListOutputDto>）

{
  "pageIndex": 1,
  "pageSize": 10,
  "totalCount": 2,
  "totalPages": 1,
  "items": [
    {
      "id": "…",
      "groupName": "West Coast Region",
      "partnerId": "…",
      "partnerName": "Global Foods Inc.",
      "state": true,
      "creationTime": "2026-04-27T10:00:00"
    }
  ]
}

11.4 列表项字段

字段	类型	说明
id	string	主键
groupName	string	组织名称
partnerId	string	所属合作伙伴 Id
partnerName	string	父级合作伙伴名称（UI「Parent Partner」）
state	bool	是否启用
creationTime	string (datetime)	创建时间

---

12. Group — 详情

• 方法：GET
• 路径：/api/app/group/{id}

路径参数 id：fl_group.Id。响应为 GroupGetOutputDto（在列表字段基础上增加 lastModificationTime）。

---

13. Group — 新增

• 方法：POST
• 路径：/api/app/group

Body（GroupCreateInputVo）

{
  "groupName": "West Coast Region",
  "partnerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "state": true
}

字段	类型	必填	说明
groupName	string	是	组织名称
partnerId	string	是	Assign to Partner，须为未删除的 fl_partner.Id
state	bool	否	默认 true

---

14. Group — 编辑

• 方法：PUT
• 路径：/api/app/group/{id}
• Body：GroupUpdateInputVo（字段同新增）

---

15. Group — 删除（逻辑删除）

• 方法：DELETE
• 路径：/api/app/group/{id}

---

16. Group — 批量导出 PDF

• 方法：GET
• 路径：/api/app/group/export-pdf
• 响应：application/pdf，附件名形如 groups_yyyy-MM-dd_HH-mm-ss.pdf

16.1 查询参数

与列表一致（分页可忽略）：keyword、partnerId、state、sorting。

16.2 限制

• 命中行数 超过 5000 返回业务错误；导出最多 5000 条。

16.3 PDF 列

Group Name、Parent Partner、Status（active / inactive）、Created。

---

17. 前端对接提示（Group）

• 「Search」→ keyword；按父级合作伙伴筛选 → partnerId（下拉选中项的 id）；「Active」→ state。
• 「Assign to Partner」下拉数据来自 Partner 列表接口（/api/app/partner）。
• 「Bulk Export (PDF)」→ 第 16 节，查询参数与当前列表筛选一致。