## 概述

美国版后端采用 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<LocationGetListOutputDto>）

- `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`），以下用环境变量占位：

```bash
# 登录（示例账号以环境为准）
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`**