王明 / Food-Labeling-Management-Platform

概述

美国版后端采用 ABP 动态接口（ConventionalControllers），宿主统一前缀为 api/app，Swagger 地址为：

• http://localhost:19001/swagger

门店模块的服务类为 LocationAppService（模块：food-labeling-us）。

说明：接口的最终 URL 以 Swagger 展示为准（在 Swagger 里搜索 Location 或 LocationAppService 即可）。

批量（下载模板 / Excel 导出 / Excel 导入 / JSON 批量编辑）与后续其它模块同类接口的统一汇总文档见：批量导入导出接口说明.md（本文件「接口 3～5」与汇总文档中导入导出一致；批量编辑见汇总文档 1.4；后续新增批量类接口建议优先更新汇总文档）。

---

数据库表

表名：location

核心字段（与原型一致）：

• Partner：Partner
• Group：GroupName
• Location ID：LocationCode
• Location Name：LocationName
• Street/City/State/Country/Zip：Street/City/StateCode/Country/ZipCode
• Phone/Email：Phone/Email
• GPS：Latitude/Longitude
• Active Location：State（1=启用，0=停用）

---

接口 1：门店分页列表

方法签名

Task<PagedResultWithPageDto<LocationGetListOutputDto>> GetListAsync(LocationGetListInputVo input)

入参（LocationGetListInputVo）

• SkipCount：跳过条数（分页用）
• MaxResultCount：每页条数（分页用）
• Sorting：排序字段（可选；不传默认按 CreationTime 倒序）
• Keyword：关键字模糊搜索（会匹配 LocationCode/LocationName/Street/City/StateCode/Country/ZipCode/Phone/Email）
• Partner：Partner 精确过滤（可选）
• GroupName：Group 精确过滤（可选）
• State：启用状态过滤（可选，true/false）

出参（PagedResultWithPageDto）

• PageIndex：当前页码（从 1 开始）
• PageSize：每页条数
• TotalCount：总条数
• TotalPages：总页数
• Items：列表

LocationGetListOutputDto 字段：

• Id
• Partner
• GroupName
• LocationCode
• LocationName
• Street
• City
• StateCode
• Country
• ZipCode
• Phone
• Email
• Latitude
• Longitude
• State

---

接口 2：新增门店

方法签名

Task<LocationGetListOutputDto> CreateAsync(LocationCreateInputVo input)

入参（LocationCreateInputVo）

• Partner：可选
• GroupName：可选
• LocationCode：必填（唯一，重复会报错）
• LocationName：必填
• Street/City/StateCode/Country/ZipCode：可选
• Phone/Email：可选
• Latitude/Longitude：可选（decimal）
• State：是否启用（默认 true）

校验规则

• LocationCode 不能为空，且唯一
• LocationName 不能为空

---

接口 3：下载批量导入模板（Excel 文件）

从服务器配置的目录读取已部署的模板文件（如宝塔目录 batchImportOfFiles 下的 Location-Manager-批量导入模板.xlsx），以附件形式返回给浏览器/客户端。

方法签名

Task<IActionResult> DownloadLocationImportTemplateAsync()

HTTP

• 方法：GET
• 鉴权：与其它 LocationAppService 接口一致（Authorization 携带登录返回的 data.token 完整值）

常见路由（以 Swagger 为准）

在 RootPath = api/app、约定式控制器默认命名规则下，一般为：

• GET /api/app/location/download-location-import-template

响应

• 成功：Content-Type 为 application/vnd.openxmlformats-officedocument.spreadsheetml.sheet，Content-Disposition 带下载文件名（与服务器上模板文件名一致）
• 失败：业务异常提示（如未配置目录、模板文件不存在）

相关配置（appsettings）

配置节：FoodLabeling:BatchImport（类名 FoodLabelingBatchImportOptions）

配置项	说明
TemplateDirectory	模板所在目录绝对路径（生产示例：/www/wwwroot/FoodLabelingManagementUs/batchImportOfFiles）
LocationTemplateFileName	Location 模板文件名（默认：Location-Manager-批量导入模板.xlsx）

---

接口 4：批量导出门店（Excel）

按与 接口 1 相同的筛选条件全量导出门店数据；导出为 .xlsx，列顺序与 Location Manager 表头及导入模板一致（含 Latitude、Longitude、Active 等）。不按条数截断；数据量大时占用内存与生成时间会增加。

方法签名

Task<IActionResult> ExportLocationsExcelAsync(LocationGetListInputVo input)

HTTP

• 方法：GET
• Query：筛选条件与接口 1 一致：Sorting、Keyword、Partner、GroupName、State。导出为全量（符合筛选的全部记录），不使用请求里的 SkipCount / MaxResultCount。

常见路由（以 Swagger 为准）

• GET /api/app/location/export-locations-excel?Partner=...&GroupName=...&State=...&Keyword=...&Sorting=...

响应

• 成功：application/vnd.openxmlformats-officedocument.spreadsheetml.sheet，文件名形如 locations-export-yyyyMMdd-HHmmss.xlsx
• 数据范围：在筛选结果上按 Sorting 或默认 CreationTime 降序导出全部行（无条数上限）

相关配置

门店导出不再使用条数上限配置；与导出体积相关的仅内存与 Excel 生成耗时。模板目录等仍见上文「相关配置（appsettings）」中 FoodLabeling:BatchImport 其它项。

---

接口 5：批量导入门店（Excel）

上传 .xlsx，按行解析后逐行调用与 接口 2 相同的新增逻辑；单行失败不影响其它行处理，最终在 JSON 中返回成功数、失败数及错误明细。

方法签名

Task<LocationBatchImportResultDto> ImportLocationsBatchAsync(LocationBatchImportInputVo input)

HTTP

• 方法：POST
• Content-Type：multipart/form-data
• 表单字段：file（类型：文件，扩展名必须为 .xlsx）

常见路由（以 Swagger 为准）

• POST /api/app/location/import-locations-batch

入参（表单）

• file：Excel 文件（必填）

出参（LocationBatchImportResultDto）

• SuccessCount：成功新增条数
• FailCount：失败条数（含解析阶段与逐行 CreateAsync 业务校验失败）
• SkippedEmptyRows：预留字段，当前实现一般为 0
• Errors：错误列表（LocationBatchImportErrorDto）
  • RowNumber：Excel 行号（表头为第 1 行，数据从第 2 行起；解析类错误可能为 0）
  • LocationCode：该行 Location ID（若有）
  • Message：错误说明

解析与业务规则摘要

• 表头需能识别 Location ID 列（或同义列，如 LocationCode）；建议使用服务器提供的官方模板。
• 必填：Location ID（LocationCode）、Location Name（与单条新增接口一致）。
• 可选：Company/Region、地址、电话、邮箱、经纬度、Active 等；经纬度有值时校验格式，空则按 null 入库。
• 单次处理行数上限：MaxImportRows（默认 5000）；单文件大小上限：MaxUploadBytes（默认 10MB）。

相关配置

配置项	说明
MaxImportRows	单次导入最多数据行数
MaxUploadBytes	上传文件最大字节数

---

curl 示例（本地 http://localhost:19001）

请先按项目规范登录获取 data.token（见 项目相关文档 或 .codex/skills/api-interface-testing），以下用环境变量占位：

# 登录（示例账号以环境为准）
curl -X POST "http://localhost:19001/api/oauth/Login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "userName=admin&password=123456"

# 下载模板（将 TOKEN 替换为响应中的 data.token 整段）
curl -X GET "http://localhost:19001/api/app/location/download-location-import-template" \
  -H "Authorization: TOKEN" \
  -o "Location-Manager-template.xlsx"

# 导出（带筛选示例，可按需删参）
curl -X GET "http://localhost:19001/api/app/location/export-locations-excel?Partner=MedVantage%20Cafe%20Group&Keyword=" \
  -H "Authorization: TOKEN" \
  -o "locations-export.xlsx"

# 批量导入（字段名必须为 file）
curl -X POST "http://localhost:19001/api/app/location/import-locations-batch" \
  -H "Authorization: TOKEN" \
  -F "file=@./Location-Manager-template.xlsx"

若实际路径与上表不一致，以 Swagger「食品标签-美国版接口」中 LocationAppService 展示的路径为准。

---

Swagger 中如何找到

1. 启动后端宿主（Yi.Abp.Web），确保端口为 19001
2. 打开 http://localhost:19001/swagger
3. 在接口分组里找到 「食品标签-美国版接口」 或直接搜索 Location
4. 查看 LocationAppService：GetListAsync、CreateAsync、UpdateAsync、DeleteAsync，以及 DownloadLocationImportTemplateAsync、ExportLocationsExcelAsync、ImportLocationsBatchAsync