312 lines
13 KiB
Markdown
312 lines
13 KiB
Markdown
# 会员储值卡 — GetTenantMemberCardList
|
||
|
||
> 模块：`MemberProfile` · ODS 表：`member_stored_value_cards` · 维度表（快照）
|
||
|
||
---
|
||
|
||
## 一、接口概述
|
||
|
||
查询门店下所有会员卡（储值卡/次卡/券类）的列表视图。每条记录对应一张已开通的具体会员卡，同时包含卡定义属性（卡种、折扣规则、适用范围）、当前余额、持卡会员快照、有效期与状态信息。虽然接口名为"储值卡列表"，实际涵盖五类卡：储值卡、活动抵用券、台费卡、酒水卡、月卡。
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 完整路径 | `POST /MemberProfile/GetTenantMemberCardList` |
|
||
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
|
||
| 鉴权 | `Authorization: Bearer <token>` |
|
||
| 分页 | `page` + `limit`（最大 100） |
|
||
| 时间范围 | 不需要（全量快照） |
|
||
|
||
---
|
||
|
||
## 二、请求
|
||
|
||
### 请求体（JSON）
|
||
|
||
```json
|
||
{
|
||
"siteId": 2790685415443269,
|
||
"cardPhysicsType": 0,
|
||
"status": 0,
|
||
"page": 1,
|
||
"limit": 100
|
||
}
|
||
```
|
||
|
||
### 参数说明
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `siteId` | int | 是 | 门店 ID |
|
||
| `cardPhysicsType` | int | 是 | 卡物理类型筛选。`0` = 全部 |
|
||
| `status` | int | 是 | 状态筛选。`0` = 全部 |
|
||
| `page` | int | 是 | 页码，从 1 开始 |
|
||
| `limit` | int | 是 | 每页条数，最大 100 |
|
||
|
||
---
|
||
|
||
## 三、响应结构
|
||
|
||
```
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"list": [ { ... }, { ... } ],
|
||
"total": 200
|
||
}
|
||
}
|
||
```
|
||
|
||
`data.list` 中每个对象即为一条会员卡记录，共 68 个字段，按逻辑分组说明如下。
|
||
|
||
---
|
||
|
||
## 四、响应字段详解（68 个字段）
|
||
|
||
### 4.1 卡主键与卡种信息
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `id` | int | `2955206162843781` | 会员卡账户主键 ID，唯一标识一张已开通的卡 |
|
||
| `card_type_id` | int | `2793266846533445` | 卡种 ID，定义"这是哪一种卡"。不同卡种对应不同的配置规则 |
|
||
| `member_card_grade_code` | int | `2790683528022856` | 卡等级/卡类代码。枚举：`2790683528022853` = 储值卡，`2790683528022855` = 台费卡，`2790683528022856` = 活动抵用券，`2790683528022857` = 月卡，`2790683528022858` = 酒水卡 |
|
||
| `member_card_grade_code_name` | string | `"活动抵用券"` | 卡等级/卡类名称，与 `member_card_grade_code` 一一对应 |
|
||
| `member_card_type_name` | string | `"活动抵用券"` | 卡类型名称，与 `member_card_grade_code_name` 一致，偏展示用的冗余字段 |
|
||
| `card_physics_type` | int | `1` | 物理卡类型。`1` = 实体卡/标准卡，其他值可能代表虚拟卡 |
|
||
| `card_no` | string | `""` | 实体卡物理卡号/条码号。当前全部为空（无物理卡号） |
|
||
| `bind_password` | string | `""` | 卡绑定密码，用于消费验证。当前未启用 |
|
||
| `use_scene` | string | `""` | 卡使用场景说明（如"仅店内使用"）。当前未使用 |
|
||
| `sort` | int | `1` | 前端展示排序权重 |
|
||
|
||
### 4.2 持卡会员信息
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `member_name` | string/null | `"胡先生"` | 持卡会员姓名快照。`null` 表示未绑定会员 |
|
||
| `member_mobile` | string/null | `"18620043391"` | 持卡会员手机号快照。与 `member_name` 对应 |
|
||
| `system_member_id` | int | `2955204540009605` | 系统级会员 ID（跨门店统一主键）。`0` = 未绑定具体会员/散客卡 |
|
||
| `tenant_member_id` | int | `2955204541320325` | 租户内会员主键 ID。`0` = 未绑定会员。与会员档案表的 `id` 对应 |
|
||
|
||
### 4.3 门店与适用范围
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `site_name` | string | `"朗朗桌球"` | 卡归属门店名称，展示用 |
|
||
| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID |
|
||
| `register_site_id` | int | `2790685415443269` | 卡首次办理的门店 ID |
|
||
| `effect_site_id` | int | `0` | 卡片限定生效门店 ID。`0` 配合 `able_cross_site=1` 表示所有门店可用 |
|
||
| `able_cross_site` | int | `1` | 是否允许跨店使用。`1` = 可跨门店，`0` = 仅限开卡门店 |
|
||
| `tenantName` | string | `""` | 租户/品牌名称，当前未配置 |
|
||
| `tenantAvatar` | string | `""` | 品牌头像 URL，当前未配置 |
|
||
|
||
### 4.4 余额与面额
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `balance` | float | `0.0` | 当前卡内余额（元）。对储值卡为实际余额，对券类卡为剩余额度 |
|
||
| `denomination` | float | `0.0` | 面额/初始储值额度（元）。当前未填充，可能在卡种配置表中维护 |
|
||
|
||
### 4.5 折扣规则 — 折扣百分比
|
||
|
||
> 采用"几折"记法：`10` = 不打折，`9` = 九折，`8` = 八折。当前所有卡的折扣均为 `10.0`（无折扣）。
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `table_discount` | float | `10.0` | 台费折扣 |
|
||
| `table_service_discount` | float | `10.0` | 台费服务费折扣 |
|
||
| `goods_discount` | float | `10.0` | 商品折扣 |
|
||
| `goods_service_discount` | float | `10.0` | 商品服务费折扣 |
|
||
| `assistant_discount` | float | `10.0` | 助教费折扣 |
|
||
| `assistant_service_discount` | float | `10.0` | 助教服务费折扣 |
|
||
| `assistant_reward_discount` | float | `10.0` | 助教奖励金折扣 |
|
||
| `coupon_discount` | float | `10.0` | 优惠券折扣 |
|
||
|
||
### 4.6 折扣规则 — 折扣叠加开关
|
||
|
||
> 控制折扣是否与其他折扣叠加。`1` = 叠加，`2` = 不叠加（仅用卡折扣）。当前全部为 `2`。
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `table_discount_sub_switch` | int | `2` | 台费折扣叠加开关 |
|
||
| `goods_discount_sub_switch` | int | `2` | 商品折扣叠加开关 |
|
||
| `assistant_discount_sub_switch` | int | `2` | 助教折扣叠加开关 |
|
||
| `assistant_reward_discount_sub_switch` | int | `2` | 助教奖励金折扣叠加开关 |
|
||
| `goods_discount_range_type` | int | `1` | 商品折扣范围类型 |
|
||
|
||
### 4.7 折扣规则 — 抵扣比例（%）
|
||
|
||
> 允许从卡余额中抵扣的比例。`100.0` = 允许 100% 用卡支付，`0` = 不允许抵扣。当前全部为 `100.0`。
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `table_deduct_radio` | float | `100.0` | 台费抵扣比例 |
|
||
| `table_service_deduct_radio` | float | `100.0` | 台费服务费抵扣比例 |
|
||
| `goods_deduct_radio` | float | `100.0` | 商品抵扣比例 |
|
||
| `goods_service_deduct_radio` | float | `100.0` | 商品服务费抵扣比例 |
|
||
| `assistant_deduct_radio` | float | `100.0` | 助教费抵扣比例 |
|
||
| `assistant_service_deduct_radio` | float | `100.0` | 助教服务费抵扣比例 |
|
||
| `assistant_reward_deduct_radio` | float | `100.0` | 助教奖励金抵扣比例 |
|
||
| `coupon_deduct_radio` | float | `100.0` | 优惠券抵扣比例 |
|
||
|
||
### 4.8 折扣规则 — 扣卡金额配置
|
||
|
||
> 针对不同消费场景的固定扣卡金额配置。当前全部为 `0.0`（未启用固定扣卡规则）。
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `cardSettleDeduct` | float | `0.0` | 结算时扣卡金额上限/规则配置 |
|
||
| `tableCardDeduct` | float | `0.0` | 台费扣卡金额 |
|
||
| `tableServiceCardDeduct` | float | `0.0` | 台费服务金扣卡金额 |
|
||
| `goodsCarDeduct` | float | `0.0` | 商品扣卡金额 |
|
||
| `goodsServiceCardDeduct` | float | `0.0` | 商品服务金扣卡金额 |
|
||
| `assistantCardDeduct` | float | `0.0` | 助教扣卡金额 |
|
||
| `assistantServiceCardDeduct` | float | `0.0` | 助教服务金扣卡金额 |
|
||
| `assistantRewardCardDeduct` | float | `0.0` | 助教奖励金扣卡金额 |
|
||
| `couponCardDeduct` | float | `0.0` | 券额度扣卡金额 |
|
||
| `deliveryFeeDeduct` | float | `0.0` | 配送费扣卡金额 |
|
||
|
||
### 4.9 适用范围扩展（列表型）
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `tableAreaId` | array | `[]` | 限定可使用的台区 ID 列表。空 = 不限制台区 |
|
||
| `goodsCategoryId` | array | `[]` | 可用的商品分类 ID 列表。空 = 所有商品分类有效 |
|
||
| `pdAssisnatLevel` | array | `[]` | 允许使用的陪打/助教等级列表。空 = 不限制 |
|
||
| `cxAssisnatLevel` | array | `[]` | 促销活动中的助教等级限制列表。空 = 不限制 |
|
||
|
||
### 4.10 有效期与时间
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `create_time` | string | `"2025-11-08 01:31:12"` | 卡片创建时间（开卡时间） |
|
||
| `start_time` | string | `"2025-11-08 01:31:12"` | 卡片生效开始时间 |
|
||
| `end_time` | string | `"2225-01-01 00:00:00"` | 卡片有效期结束时间。远未来日期表示长期有效 |
|
||
| `disable_start_time` | string | `"0001-01-01 00:00:00"` | 停用窗口起始时间。`0001-01-01` = 未启用停用 |
|
||
| `disable_end_time` | string | `"0001-01-01 00:00:00"` | 停用窗口结束时间。`0001-01-01` = 未启用停用 |
|
||
| `last_consume_time` | string | `"2025-11-09 07:48:23"` | 最近一次消费时间。`1970-01-01 00:00:00` = 从未消费 |
|
||
|
||
### 4.11 卡状态与标志
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `status` | int | `1` | 卡当前状态。`1` = 正常可用，`4` = 过期/停用/作废 |
|
||
| `is_delete` | int | `0` | 逻辑删除标记。`0` = 未删除，`1` = 已逻辑删除 |
|
||
| `is_allow_give` | int | `0` | 是否允许转赠。`0` = 不允许，`1` = 允许转赠 |
|
||
| `is_allow_order_deduct` | int | `0` | 是否允许订单层面统一扣款。`0` = 不允许（仅按项目扣卡），`1` = 允许整单抵扣 |
|
||
|
||
---
|
||
|
||
## 五、响应样例（单条记录）
|
||
|
||
```json
|
||
{
|
||
"site_name": "朗朗桌球",
|
||
"member_name": "胡先生",
|
||
"member_mobile": "18620043391",
|
||
"member_card_type_name": "活动抵用券",
|
||
"table_service_discount": 10.0,
|
||
"assistant_service_discount": 10.0,
|
||
"coupon_discount": 10.0,
|
||
"goods_service_discount": 10.0,
|
||
"is_allow_give": 0,
|
||
"able_cross_site": 1,
|
||
"cardSettleDeduct": 0.0,
|
||
"tenantAvatar": "",
|
||
"tenantName": "",
|
||
"member_card_grade_code_name": "活动抵用券",
|
||
"table_discount_sub_switch": 2,
|
||
"tableAreaId": [],
|
||
"goods_discount_sub_switch": 2,
|
||
"goodsCategoryId": [],
|
||
"assistant_discount_sub_switch": 2,
|
||
"pdAssisnatLevel": [],
|
||
"assistant_reward_discount_sub_switch": 2,
|
||
"cxAssisnatLevel": [],
|
||
"goods_discount_range_type": 1,
|
||
"use_scene": "",
|
||
"balance": 0.0,
|
||
"table_deduct_radio": 100.0,
|
||
"table_service_deduct_radio": 100.0,
|
||
"goods_deduct_radio": 100.0,
|
||
"goods_service_deduct_radio": 100.0,
|
||
"assistant_deduct_radio": 100.0,
|
||
"assistant_service_deduct_radio": 100.0,
|
||
"assistant_reward_deduct_radio": 100.0,
|
||
"coupon_deduct_radio": 100.0,
|
||
"tableCardDeduct": 0.0,
|
||
"tableServiceCardDeduct": 0.0,
|
||
"goodsCarDeduct": 0.0,
|
||
"goodsServiceCardDeduct": 0.0,
|
||
"assistantCardDeduct": 0.0,
|
||
"assistantServiceCardDeduct": 0.0,
|
||
"assistantRewardCardDeduct": 0.0,
|
||
"couponCardDeduct": 0.0,
|
||
"deliveryFeeDeduct": 0.0,
|
||
"is_allow_order_deduct": 0,
|
||
"id": 2955206162843781,
|
||
"assistant_discount": 10.0,
|
||
"assistant_reward_discount": 10.0,
|
||
"bind_password": "",
|
||
"card_no": "",
|
||
"card_physics_type": 1,
|
||
"card_type_id": 2793266846533445,
|
||
"create_time": "2025-11-08 01:31:12",
|
||
"denomination": 0.0,
|
||
"disable_end_time": "0001-01-01 00:00:00",
|
||
"disable_start_time": "0001-01-01 00:00:00",
|
||
"effect_site_id": 0,
|
||
"end_time": "2225-01-01 00:00:00",
|
||
"goods_discount": 10.0,
|
||
"is_delete": 0,
|
||
"last_consume_time": "2025-11-09 07:48:23",
|
||
"member_card_grade_code": 2790683528022856,
|
||
"register_site_id": 2790685415443269,
|
||
"sort": 1,
|
||
"start_time": "2025-11-08 01:31:12",
|
||
"status": 1,
|
||
"system_member_id": 2955204540009605,
|
||
"table_discount": 10.0,
|
||
"tenant_id": 2790683160709957,
|
||
"tenant_member_id": 2955204541320325
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 六、跨表关联
|
||
|
||
### 与会员档案（`member_profiles`）
|
||
|
||
| 本表字段 | 关联表字段 | 说明 |
|
||
|----------|-----------|------|
|
||
| `tenant_member_id` | `id` | 租户内会员主键 |
|
||
| `system_member_id` | `system_member_id` | 系统级会员 ID |
|
||
|
||
> 卡与会员是多对一关系：一个会员可持有多张不同类型的卡。
|
||
|
||
### 与余额变更记录（`member_balance_changes`）
|
||
|
||
| 本表字段 | 关联表字段 | 说明 |
|
||
|----------|-----------|------|
|
||
| `id` | `tenant_member_card_id` | 卡账户 ID → 余额变更针对的具体卡 |
|
||
| `card_type_id` | `card_type_id` | 卡种类型 ID |
|
||
|
||
> 本表记录"当前余额"和规则配置；余额变更表记录每次充值/消费的明细流水。
|
||
|
||
### 与消费流水（台费、助教、商品等）
|
||
|
||
折扣/抵扣规则字段（`table_discount`、`goods_deduct_radio` 等）在消费结算时被引用，消费流水中对应 `coupon_deduct_money`、`member_discount_amount` 等字段体现实际扣卡结果。
|
||
|
||
### 与门店/台区维度
|
||
|
||
- `register_site_id` / `site_name`：与门店档案关联
|
||
- `tableAreaId`：理论上可与台桌区域表关联（当前为空，不限制台区）
|
||
|
||
<!--
|
||
AI_CHANGELOG:
|
||
- 日期: 2026-02-13
|
||
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
|
||
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
|
||
- 变更摘要: 新建 docs/api-reference/member_stored_value_cards.md，68 个字段按 11 个逻辑分组详解，含跨表关联
|
||
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
|
||
-->
|