# 自营售票 · 管理端接口（按调试顺序）

租户管理端，前缀 `/tenant`。请求头带现有租户 token：`satoken`。

统一 `POST` + `application/json`。业务参数放在 `data` 里，和现有管理端其它模块一致。

```text
{ "data": { ... } }
```

成功：`code = 200`，业务数据在 `data`。写接口成功时 `data` 可能为空。

分页列表的 `data` 是 MyBatis-Plus 分页对象，前端主要用：

| 字段 | 说明 |
|---|---|
| records | 当前页列表 |
| total | 总条数 |
| size | 每页条数 |
| current | 当前页 |

列表筛选请求都挂在 `data` 上，公共分页字段：

| 字段 | 必填 | 说明 |
|---|---|---|
| pageNum | 否 | 页码，默认按后端，建议传 1 |
| pageSize | 否 | 每页条数。要下拉全量时可传 `-1` |

删除类统一：

| 字段 | 必填 | 说明 |
|---|---|---|
| idList | 是 | 要删的 id 数组，至少 1 个 |

修改类统一带 `id`。

**接口目录（按联调顺序）**

| 顺序 | 模块 | 方法 | 路径 |
|---|---|---|---|
| 1 | 景点 | POST | `/tenant/selfScenic` 列表 |
| 1 | 景点 | POST | `/tenant/selfScenic/add` 新增 |
| 1 | 景点 | POST | `/tenant/selfScenic/update` 编辑 |
| 1 | 景点 | POST | `/tenant/selfScenic/delete` 删除 |
| 2 | 线下票种 | POST | `/tenant/otaTicketType` 列表（只读，创建自营票种时选） |
| 3 | 自营票种 | POST | `/tenant/selfTicketType` 列表 |
| 3 | 自营票种 | POST | `/tenant/selfTicketType/{id}` 详情 |
| 3 | 自营票种 | POST | `/tenant/selfTicketType/add` 新增 |
| 3 | 自营票种 | POST | `/tenant/selfTicketType/update` 编辑 |
| 3 | 自营票种 | POST | `/tenant/selfTicketType/delete` 删除 |
| 4 | 销售日历 | POST | `/tenant/selfTicketSaleCalendar/list` 查询 |
| 4 | 销售日历 | POST | `/tenant/selfTicketSaleCalendar/add` 全量保存 |
| 4 | 销售日历 | POST | `/tenant/selfTicketSaleCalendar/delete` 删除规则 |
| 5 | 分销商 | POST | `/tenant/userThirdParty` 列表 |
| 5 | 分销商 | POST | `/tenant/userThirdParty/add` 新增 |
| 5 | 分销商 | POST | `/tenant/userThirdParty/update` 修改资料/密码/启用禁用 |
| 5 | 分销商 | POST | `/tenant/userThirdParty/bind` 票种授权（可批量） |
| 5 | 分销商 | POST | `/tenant/userThirdParty/recharge` 充值 |
| 5 | 分销商 | POST | `/tenant/userThirdParty/decrease` 扣款 |
| 5 | 分销商 | POST | `/tenant/userThirdParty/delete` 删除 |
| 6 | 余额流水 | POST | `/tenant/thirdPartyBalanceLog` 列表 |
| 7 | 售票统计 | POST | `/tenant/statistics/orderSaleStatistics` 查询，`export=true` 导出 |
| 7 | 核销统计 | POST | `/tenant/statistics/orderCheckStatistics` 查询，`export=true` 导出 |
| 7 | 报表 | POST | `/tenant/reportMission` 导出任务列表 |
| 7 | 报表 | POST | `/tenant/reportMission/delete` 删除报表 |

建议前端按上面顺序联调：先有景点，才能绑票种；先有票种，才能做日历和分销商授权。统计、报表走租户已有接口，不需要新接 `/thirdParty/**`。

---

## 1. 自营景点 `/tenant/selfScenic`

景点是抽象游玩项目。票种要绑定景点，C 端景点列表也依赖「有票种绑了这个景点」。**先做这个模块。**

轮播图、富文本图片：沿用现有管理端文件上传，把返回的地址填进对应字段。`picture` 多张用英文逗号拼接，最多 6 张。

### 1.1 列表

`POST /tenant/selfScenic`

| 字段 | 必填 | 说明 |
|---|---|---|
| name | 否 | 景点名称，模糊 |
| isOpen | 否 | 是否开放：`1` 开放 / `0` 关闭 |

返回 `records` 每项：

| 字段 | 说明 |
|---|---|
| id | 景点 id，后续票种绑定用这个 |
| name | 名称 |
| address | 地址 |
| openingTime | 开放时间文案，例如「08:00~18:00」。真正能不能买由票种控制 |
| picture | 轮播图，逗号分隔 |
| isOpen | 是否开放 |
| publicAnnouncement | 公告 |
| scenicDescription | 图文描述（富文本） |
| createTime | 创建时间 |

### 1.2 新增

`POST /tenant/selfScenic/add`

| 字段 | 必填 | 说明 |
|---|---|---|
| name | 是 | 景点名称 |
| isOpen | 是 | `1` / `0` |
| address | 否 | 地址 |
| openingTime | 否 | 开放时间文案 |
| picture | 否 | 轮播图 URL，逗号分隔，最多 6 张 |
| publicAnnouncement | 否 | 公告 |
| scenicDescription | 否 | 富文本 |

### 1.3 编辑

`POST /tenant/selfScenic/update`

在新增字段基础上多一个 `id`（必填）。没有单独详情接口，编辑回填用列表数据即可。

### 1.4 删除

`POST /tenant/selfScenic/delete`

`data.idList`。已绑到票种上的景点删掉后，C 端列表可能不再展示该景点（票种侧绑定会失效），删除前建议前端提示。

---

## 2. 线下票种（创建自营票种时的下拉）

自营票种必须绑一个**线下已同步**的票种，一个线下票种只能创建一次自营票种。

### 2.1 线下票种列表

`POST /tenant/otaTicketType`

这个接口管理端其它地方可能已经接过，这里只作为自营票种的选择源。

| 字段 | 必填 | 说明 |
|---|---|---|
| ticketTypeId | 否 | 线下票种数字 id |
| name | 否 | 名称 |

返回每项主要用：

| 字段 | 说明 |
|---|---|
| ticketTypeId | 线下票种 id，创建自营票种时传这个 |
| name | 线下票种名称 |
| category | 大类：`ticket` 景区门票 / `batch` 场次售票 / `member` 年卡次卡。创建自营票种时大类应与这个一致 |
| batchConfigList | 仅场次票有。线下场次配置，自营侧只读展示，不用单独维护 |

场次配置 `batchConfigList` 项（只读）：

| 字段 | 说明 |
|---|---|
| batchConfigId | 线下场次 id |
| name | 场次名称 |
| startTime / endTime | 场次时段 |
| maxSaleNums | 无座位时最大数量 |

---

## 3. 自营票种 `/tenant/selfTicketType`

依赖：景点列表、线下票种列表。

渠道决定 C 端谁能看到：

| 值 | 含义 |
|---|---|
| wx | 微信公众号 |
| wx-mini | 微信小程序 |
| third-party | 自营分销商 |

要给分销商卖，必须勾选 `third-party`，然后再走第 5 步授权。只授权不勾渠道，分销商端看不到。

### 3.1 列表

`POST /tenant/selfTicketType`

| 字段 | 必填 | 说明 |
|---|---|---|
| category | 否 | `ticket` / `batch` / `member` |
| name | 否 | 名称，模糊 |
| isSale | 否 | `1` 在售 / `0` 禁售 |

返回每项字段见 3.2 详情（列表也会带绑定景点、渠道、场次）。

### 3.2 详情（编辑页回填用这个）

`POST /tenant/selfTicketType/{id}`

路径上的 `{id}` 是自营票种 id。body 仍走统一 `Request`，`data` 可空对象。

返回除票种字段外还有：

| 字段 | 说明 |
|---|---|
| scenicList | 已绑定景点 |
| scenicList[].selfScenicId | 景点 id |
| scenicList[].selfScenicName | 景点名称 |
| channels | 渠道字符串数组 |
| batchConfigList | 场次票只读，来自线下票种 |
| ticketTypeId / category | 创建后不可改，编辑页只展示 |

### 3.3 新增

`POST /tenant/selfTicketType/add`

**公共必填**

| 字段 | 必填 | 说明 |
|---|---|---|
| ticketTypeId | 是 | 线下票种 id（数字）。已创建过会报「票种已存在」 |
| category | 是 | 与线下票种大类保持一致：`ticket` / `batch` / `member` |
| name | 是 | 对客名称 |
| price | 是 | 底价。具体某天售价可被销售日历覆盖 |
| realNameType | 是 | `0` 不限；`1` 一证一人；`2` 一证多人 |
| saleDateStart / saleDateEnd | 是 | 可售日期，`yyyy-MM-dd` |
| saleTimeStart / saleTimeEnd | 是 | 可售时段，`HH:mm:ss`，例如 `00:00:00` ~ `23:59:59` |

**公共选填**

| 字段 | 说明 |
|---|---|
| isSale | 在售，默认按 `1` 理解 |
| highPrice | 划线价 |
| buyProtocol | 购买协议富文本 |
| isAgreeProtocol | `1` 必须勾选协议才能买，默认 `0` |
| saleMaxPreDays | 最多可订未来 X 天 |
| saleMinPreDays | 最少提前 X 天，`0` 可订当天 |
| saleMinNums / saleMaxNums | 单订单最小/最大张数，`>0` 才生效 |
| isAllowCancel | `1` 可退，默认 `1` |
| dayStock | 每日库存上限，`0` 不限 |
| totalStock | 总库存上限，`0` 不限 |
| scenicIds | 绑定的自营景点 id 数组 |
| channels | 渠道数组，取值见上表 |

**按大类展示的字段**

景区门票 `ticket`：

| 字段 | 说明 |
|---|---|
| useDays | 使用天数，当天有效一般是 `1` |
| useDateType | `1` 日历票（只能游玩所选日期）；`2` 期票（期限内都能用） |
| useDateStart / useDateEnd | 期票时的有效期 |

年卡次卡 `member`：

| 字段 | 说明 |
|---|---|
| memberUseDateType | `1` 按天（看 `useDays`）；`2` 固定日期（看 `useDateStart` / `useDateEnd`） |
| useDays | 按天时的有效天数，例如 `365` |
| useDateStart / useDateEnd | 固定日期模式 |
| memberActiveType | `1` 购买即激活；`2` 首次使用激活 |

场次票 `batch`：场次来自线下票种，这里不用填场次。售卖规则用上面公共字段即可。

### 3.4 修改

`POST /tenant/selfTicketType/update`

必填 `id`。**不能改** `ticketTypeId`、`category`。其余与新增相同（含 `scenicIds`、`channels`）。

景点、渠道是整表覆盖：传当前完整数组。要清空就传空数组。

### 3.5 删除

`POST /tenant/selfTicketType/delete`

`data.idList`。

---

## 4. 销售日历 `/tenant/selfTicketSaleCalendar`

依赖：已有自营票种。用来覆盖「某一天」的价格和是否可售。C 端**列表**仍是票种底价，**详情/下单**才走日历。

规则优先级：**特定日期 > 周期性规则**。同类型里 `priority` 越小越优先。前端拖拽排序后把序号写成 `priority`（建议从 1 开始）。

没有单独的修改接口。`/add` 会先删掉该票种全部旧规则再写入，等于**全量保存**。编辑页应：先 list 回填，用户改完把**完整规则列表**再提交 add。

### 4.1 查询某票种的规则

`POST /tenant/selfTicketSaleCalendar/list`

| 字段 | 必填 | 说明 |
|---|---|---|
| selfTicketTypeId | 是 | 自营票种 id |

返回数组（不是分页），按 `priority` 升序。每项含 `id`（删除单条用）、价格、是否可售、特定日期或周期字段。

### 4.2 保存规则（全量覆盖）

`POST /tenant/selfTicketSaleCalendar/add`

注意：这个接口的 `data` 是**数组**，不是对象。

```text
{ "data": [ { 规则1 }, { 规则2 } ] }
```

数组里每条规则：

| 字段 | 必填 | 说明 |
|---|---|---|
| selfTicketTypeId | 是 | 同一批必须是同一个票种 |
| price | 是 | 该规则价格 |
| isSale | 是 | `1` 可售 / `0` 禁售 |
| priority | 是 | 越小越优先 |

两种规则二选一：

**特定日期**

| 字段 | 说明 |
|---|---|
| specificDate | 日期字符串。多天用逗号，例如 `2026-10-01,2026-10-02` |

**周期性**（没传 `specificDate` 时三个都要有）

| 字段 | 说明 |
|---|---|
| startDate | 周期开始 `yyyy-MM-dd` |
| endDate | 周期结束 |
| weekdays | 周几，逗号分隔。`1` 周日，`2` 周一 … `7` 周六。例如周末：`1,7` |

空数组不要调这个接口（会取第 0 条票种 id）。要清空规则用下面的删除，把 list 返回的 id 全部删掉。

### 4.3 删除规则

`POST /tenant/selfTicketSaleCalendar/delete`

`data.idList` 为日历规则 id，不是票种 id。

---

## 5. 自营分销商 `/tenant/userThirdParty`

旅行社、酒店等，登录分销商端售票。可与票种并行开发账号 CRUD，但**授权必须先有票种**。

登录名、名称全局唯一。名称不能和总库 OTA 渠道名冲突。密码：至少 8 位，且同时包含大小写字母和数字。

分销商的资料、余额、授权、**启用/禁用**都在本模块完成，只做一个「自营分销商」菜单即可。不要用 `/tenant/user` 管分销商：那个接口只服务微信/小程序 C 端用户拉黑，列表里也不会再出现分销商。

### 5.1 列表

`POST /tenant/userThirdParty`

| 字段 | 必填 | 说明 |
|---|---|---|
| name | 否 | 分销商名称，模糊 |
| contactName | 否 | 联系人，精确 |
| phone | 否 | 电话，精确 |
| remark | 否 | 备注 |
| status | 否 | `1` 正常 / `0` 禁用 |

返回每项：

| 字段 | 说明 |
|---|---|
| id | 分销商 id，授权/充扣/禁用都用这个 |
| name | 名称 |
| contactName / phone | 联系人、电话 |
| loginName | 登录名 |
| status | `1` 正常 / `0` 禁用。禁用后不能登录、不能下单 |
| lastLoginTime | 最近一次登录时间 |
| balance | 余额，不足不能下单 |
| selfTicketTypeList | 已授权的自营票种，结构同票种详情（含景点、渠道、场次） |
| remark | 备注 |
| createTime | 创建时间 |

列表**不返回密码**。没有单独详情接口，编辑回填用列表。

### 5.2 新增

`POST /tenant/userThirdParty/add`

| 字段 | 必填 | 说明 |
|---|---|---|
| name | 是 | 分销商名称 |
| loginName | 是 | 登录名 |
| password | 是 | 登录密码，复杂度见上 |
| contactName | 否 | 联系人 |
| phone | 否 | 联系方式 |
| remark | 否 | 备注 |

新建余额为 0。创建后不会自动授权票种。

### 5.3 修改

`POST /tenant/userThirdParty/update`

| 字段 | 必填 | 说明 |
|---|---|---|
| id | 是 | 分销商 id |
| contactName / phone / remark | 否 | 资料。不传的字段保持原值，可以只传 `id` + `status` 做启用/禁用 |
| password | 否 | 不传或空字符串表示不改密码；传了就要满足复杂度 |
| status | 否 | `1` 启用 / `0` 禁用。不传不改。禁用会立即踢下线 |

**不能改** `name`、`loginName`。要改名称只能删了重建。

### 5.4 票种授权

`POST /tenant/userThirdParty/bind`

可一次给多个分销商绑定**同一批**票种。每个被选中的分销商，原有授权都会被这批票种覆盖。只改某一个时，列表里传 1 个分销商 id 即可。

| 字段 | 必填 | 说明 |
|---|---|---|
| userThirdPartyIdList | 是 | 分销商 id 数组，至少一个 |
| selfTicketTypeIdList | 是 | 票种 id 数组。传 `[]` 表示清空所选分销商的授权，不能不传该字段 |

前端交互建议：列表多选分销商，弹窗多选票种，提交完整选中结果。不同分销商要配不同票种时，分开调两次。

被授权的票种自身还需要勾了渠道 `third-party`，分销商端才能看到。

### 5.5 充值

`POST /tenant/userThirdParty/recharge`

| 字段 | 必填 | 说明 |
|---|---|---|
| userThirdPartyId | 是 | 分销商 id |
| amount | 是 | 金额，必须 `> 0`，最小 `0.01` |

### 5.6 扣款

`POST /tenant/userThirdParty/decrease`

字段同充值。扣款不能大于当前余额。

### 5.7 删除

`POST /tenant/userThirdParty/delete`

`data.idList`。以下情况会失败，前端先拦一下更好：

- 余额大于 0
- 还有未完结订单（不是已取消 / 已关闭 / 已完成）

删除会踢掉该分销商登录，并清掉票种授权。

---

## 6. 余额流水 `/tenant/thirdPartyBalanceLog`

依赖：已有分销商。充值、扣款、分销商下单消费、退单退款都会记流水。建议和分销商列表放一起，从某行点进流水。

### 6.1 流水列表

`POST /tenant/thirdPartyBalanceLog`

| 字段 | 必填 | 说明 |
|---|---|---|
| userThirdPartyId | 否 | 按分销商筛 |
| type | 否 | 见下表 |
| tradeTimeStart / tradeTimeEnd | 否 | 交易时间，`yyyy-MM-dd HH:mm:ss` |

`type`：

| 值 | 含义 |
|---|---|
| 1 | 充值（管理端） |
| 2 | 人工扣款（管理端） |
| 3 | 消费（分销商下单扣余额） |
| 4 | 退款（分销商退单退余额） |

返回每项：

| 字段 | 说明 |
|---|---|
| id | 流水 id |
| userThirdPartyId | 分销商 id |
| userThirdPartyName | 分销商名称 |
| type | 类型 |
| amount | 发生额 |
| beforeBalance / afterBalance | 变动前 / 后余额 |
| orderId | 消费、退款时关联订单 |
| operatorAdminId | 管理端充扣时的操作人 |
| tradeTime | 交易时间 |
| createTime | 创建时间 |

流水只读，没有新增/修改/删除。充扣走 5.5 / 5.6。

---

## 7. 售票统计 / 核销统计 / 报表（沿用租户现有接口）

管理端看自营售票数据，用租户已经接过的统计和报表，不要调 `/thirdParty/statistics`、`/thirdParty/reportMission`。那两个是**分销商自己登录后**用的，小程序/公众号调会返回「无权访问」。

自营分销商下单时，订单上的销售来源 `otaSourceName` = 分销商 **name**（不是 id）。微信是「微信」，小程序是「微信小程序」。

导出：统计请求里 `export` 设为 `true` 会异步出 Excel，到报表列表拿 `downloadUrl`。`exportDetail` 为 `true` 时，售票统计会多两个 sheet（售票明细、退票明细），核销统计会多核销明细。

### 7.1 售票统计

`POST /tenant/statistics/orderSaleStatistics`

按分销渠道 + 票种 + 单价分组，最后一行是总计。

| 字段 | 必填 | 说明 |
|---|---|---|
| timeBegin / timeEnd | 是 | 统计时间，`yyyy-MM-dd HH:mm:ss`。售票按购票时间，退票按退票完成时间 |
| ticketTypeIdList | 否 | **线下票种数字 id**，不是自营票种 id |
| otaSourceNameList | 否 | 销售来源名称。只看某个自营分销商时，传该分销商的 `name` |
| groupByList | 否 | 额外维度，目前支持 `orderDateDay`（按天） |
| export | 否 | `true` 异步导出 |
| exportDetail | 否 | `true` 导出时带明细，需同时 `export=true` |

返回数组，每项：

| 字段 | 说明 |
|---|---|
| orderDateDay | 按天分组时的日期；未分组可为空；总计行为「总计」 |
| otaSourceName | 分销渠道 |
| ticketTypeName | 票种名称 |
| unitPrice | 单价 |
| saleNum / salePrice / saleSettlementPrice | 售票张数、金额、结算价 |
| cancelNum / cancelPrice / cancelSettlementPrice | 退票张数、金额、结算价 |
| actualNum / actualPrice / actualSettlementPrice | 实售（售 − 退） |

### 7.2 核销统计

`POST /tenant/statistics/orderCheckStatistics`

| 字段 | 必填 | 说明 |
|---|---|---|
| checkTimeBegin / checkTimeEnd | 是 | 首次核销时间 |
| ticketTypeIdList | 否 | 线下票种数字 id |
| otaSourceNameList | 否 | 销售来源名称，自营分销商传 `name` |
| groupByList | 否 | `orderDateDay` |
| export / exportDetail | 否 | 同售票统计 |

返回数组，每项：

| 字段 | 说明 |
|---|---|
| orderDateDay | 按天时的日期 |
| otaSourceName | 订单渠道 |
| ticketTypeName | 票种 |
| unitPrice | 单价 |
| checkCount | 核销张数 |
| checkPrice | 核销金额 |
| checkSettlementPrice | 结算价 |

### 7.3 报表列表

`POST /tenant/reportMission`

导出任务进这张表。筛选字段：

| 字段 | 必填 | 说明 |
|---|---|---|
| createTimeBegin / createTimeEnd | 否 | 任务创建时间 |
| name | 否 | 文件名称（请求字段名是 `name`） |
| type | 否 | `0` 导出 / `1` 导入 |
| status | 否 | `0` 进行中 / `1` 成功 / `2` 失败 |

返回 `records` 每项：

| 字段 | 说明 |
|---|---|
| id | 任务 id |
| fileName | 文件名 |
| type | 导入/导出 |
| downloadUrl | 成功后的下载地址 |
| status | 任务状态 |
| adminId / adminName | 操作人 |
| createTime | 创建时间 |

点导出后先轮询列表，`status=1` 再用 `downloadUrl`。

### 7.4 删除报表

`POST /tenant/reportMission/delete`

`data.idList`。

---

## 联调顺序（建议）

1. 景点：列表 → 新增 → 列表能看到 → 编辑 → 删除  
2. 线下票种列表能拉到数据（数据来自线下同步，管理端只读）  
3. 自营票种：列表 → 新增（绑景点 + 勾渠道）→ 详情回填 → 编辑 → 删除  
4. 销售日历：按票种 list → 用数组全量 add → 再 list 核对 → 按规则 id 删除  
5. 分销商：列表 → 新增 → 修改资料/密码 → bind 授权（可一次多个分销商同一批票种）→ 充值 → 扣款 → 流水列表能看到 1/2 两类  
6. 删除分销商：余额清零且无未完结订单后再删  
7. 统计：售票统计、核销统计能出数；`export=true` 后到报表列表能下到文件  

C 端微信/小程序售票、下单、支付，以及分销商自己的统计/报表，不在本文。管理端订单、退单沿用现有订单模块即可。