自营售票管理端接口.md 20 KB
自营售票 · 管理端接口（按调试顺序）
租户管理端，前缀 /tenant。请求头带现有租户 token：satoken。
统一 POST + application/json。业务参数放在 data 里，和现有管理端其它模块一致。
{ "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 是数组，不是对象。
{ "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。
联调顺序（建议）
- 景点：列表 → 新增 → 列表能看到 → 编辑 → 删除
- 线下票种列表能拉到数据（数据来自线下同步，管理端只读）
- 自营票种：列表 → 新增（绑景点 + 勾渠道）→ 详情回填 → 编辑 → 删除
- 销售日历：按票种 list → 用数组全量 add → 再 list 核对 → 按规则 id 删除
- 分销商：列表 → 新增 → 修改资料/密码 → bind 授权（可一次多个分销商同一批票种）→ 充值 → 扣款 → 流水列表能看到 1/2 两类
- 删除分销商：余额清零且无未完结订单后再删
- 统计：售票统计、核销统计能出数；
export=true后到报表列表能下到文件
C 端微信/小程序售票、下单、支付，以及分销商自己的统计/报表，不在本文。管理端订单、退单沿用现有订单模块即可。