init: 项目初始提交 - NeoZQYY Monorepo 完整代码

apps/etl/pipelines/feiqiu/docs/api-reference/endpoints/member_profiles.md

@@ -0,0 +1,465 @@
+# 会员档案（GetTenantMemberList）
+
+> 自动生成于 2026-02-13 | 数据来源：本地 JSON 样本
+
+## 基本信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `MemberProfile/GetTenantMemberList` |
+| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/MemberProfile/GetTenantMemberList` |
+| 请求方法 | `POST` |
+| Content-Type | `application/json` |
+| 鉴权方式 | Bearer Token（`Authorization` 头） |
+| ODS 对应表 | `member_profiles` |
+| 分页方式 | `page` + `limit`（最大 100） |
+| 时间范围 | 不需要 |
+
+## 请求参数
+
+| 参数名 | 类型 | 示例值 | 说明 |
+|--------|------|--------|------|
+| `isMemberInBlackList` | int | `0` | 是否黑名单（0=全部） |
+| `status_Revoked` | int | `0` | 是否已注销（0=全部） |
+| `isBindOrg` | int | `0` | 是否绑定组织（0=全部） |
+| `registerSource` | int | `0` | 注册来源（0=全部） |
+| `page` | int | `1` | 页码（从 1 开始） |
+| `limit` | int | `100` | 每页条数（最大 100） |
+
+## 响应字段（共 15 个）
+
+| # | 字段名 | 类型 | 示例值 |
+|---|--------|------|--------|
+| 1 | `id` | int | 2955204541320325 |
+| 2 | `create_time` | string | '2025-11-08 01:29:33' |
+| 3 | `member_card_grade_code` | int | 2790683528022853 |
+| 4 | `mobile` | string | '18620043391' |
+| 5 | `nickname` | string | '胡先生' |
+| 6 | `register_site_id` | int | 2790685415443269 |
+| 7 | `site_name` | string | '朗朗桌球' |
+| 8 | `member_card_grade_name` | string | '储值卡' |
+| 9 | `system_member_id` | int | 2955204540009605 |
+| 10 | `tenant_id` | int | 2790683160709957 |
+| 11 | `referrer_member_id` | int | 0 |
+| 12 | `point` | float | 0.0 |
+| 13 | `user_status` | int | 1 |
+| 14 | `status` | int | 1 |
+| 15 | `growth_value` | float | 0.0 |
+
+## 新增字段（相对本地 JSON 样本）
+
+以下字段在最新 API 响应中出现，但本地 JSON 样本中不存在：
+
+| 字段名 | 类型 |
+|--------|------|
+| `pay_money_sum` | float |
+| `person_tenant_org_id` | int |
+| `person_tenant_org_name` | string |
+| `recharge_money_sum` | float |
+| `register_source` | int |
+
+## 详细字段分析
+
+> 以下内容迁移自旧版 `member_profiles-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
+
+三、主键 / 会员标识类字段
+1. id
+
+类型：int
+
+非空：200 条
+
+唯一值个数：199（有 1 个 ID 出现了 2 次，完全重复记录）
+
+含义：
+
+这是“租户内会员账户”的主键 ID。
+
+对应一个 会员在当前租户下的一条账户档案（通常是一张卡/一个账户）。
+
+和其它表的关系（从字段命名推断）：
+
+在余额变更、储值卡列表等表中，通常会有 member_card_id 或类似字段，按系统习惯，这类字段一般就对应这里的 id。
+
+重复记录说明：
+
+id=2799212615616261 的记录在文件中出现了两次，所有字段完全相同，明显是导出过程重复，不是设计层面的问题。
+
+2. system_member_id
+
+类型：int
+
+唯一值个数：199（同样有一个值出现了 2 次，对应上面的重复记录）
+
+含义（结合其它文件）：
+
+这是“系统级会员 ID”，在全平台唯一，用来把一个会员在不同门店/不同卡类型下的账户统一到一个“人”的维度上。
+
+在其它 JSON（例如助教流水）里也出现了 system_member_id，用来标识消费对应哪个会员。
+
+结构关系：
+
+在“会员档案”这张表里，system_member_id 与 id 是一对多的关系（理论上：一人可有多张卡），只是本次截取的数据里恰好只有一人一条记录（除那条导出重复）。
+
+3. member_card_grade_code / member_card_grade_name
+
+这两个字段是成对出现的：一个数值码，一个中文名称。
+
+member_card_grade_code
+
+类型：int
+
+唯一值个数：4
+
+member_card_grade_name
+
+类型：string
+
+唯一值个数：4
+
+从数据可得对应关系：
+
+member_card_grade_code -> member_card_grade_name
+2790683528022853       -> "储值卡"
+2790683528022855       -> "台费卡"
+2790683528022856       -> "活动抵用券"
+2790683528022857       -> "月卡"
+
+
+含义：
+
+这是“会员卡种类/等级”的定义字段。
+
+member_card_grade_code 是内部编码（枚举 ID），member_card_grade_name 是展示用名称。
+
+统计分布（只是为了说明结构，不做盈利分析）：
+
+储值卡：112 条
+
+台费卡：82 条
+
+活动抵用券：4 条
+
+月卡：2 条
+
+结构上的意义：
+
+从设计上看，这张“会员档案”实际上是 “会员 × 卡种” 级别的账户记录：
+
+system_member_id 表示“谁”；
+
+member_card_grade_code/name 表示“哪种卡”；
+
+id 则是这张卡在当前租户下的账号 ID。
+
+四、联系方式与会员展示信息
+4. mobile
+
+类型：string
+
+唯一值个数：199（1 个号码重复，对应重复记录）
+
+特征：
+
+全部是 11 位手机号字符串，未发现空字符串或明显无效值。
+
+含义：
+
+会员绑定的手机号码。
+
+结构意义：
+
+在普通业务里，“手机号 + tenant_id”通常具备“会员唯一性”的作用（禁止同租户重复注册同一个手机号）。
+
+在本数据中，手机号重复仅出现在那条重复的会员记录上，可以判断是导出重复，而非同一手机号注册多个账户。
+
+5. nickname
+
+类型：string
+
+唯一值个数：200（每条记录昵称都不同）
+
+含义：
+
+会员在当前租户下的显示名称（可以是姓名，也可以是昵称）。
+
+与助教流水里的 nickname 区分：
+
+助教流水中的 nickname 是“助教昵称”（服务人员），这里的 nickname 是“会员昵称”，虽然字段名相同，但含义不同，关联时要注意表的上下文。
+
+五、注册门店 / 租户维度
+6. register_site_id
+
+类型：int
+
+唯一值个数：1
+
+所有记录都是同一个值：2790685415443269
+
+含义：
+
+会员的注册门店 ID。
+
+结构关系：
+
+与其它 JSON 中普遍存在的 site_id 相同（都是“朗朗桌球”这家店的 ID）。
+
+说明本文件的 200 条会员账户，全部是在这家门店注册的。
+
+7. site_name
+
+类型：string
+
+唯一值个数：1
+
+全部为 "朗朗桌球"
+
+含义：
+
+注册门店名称，属于冗余字段，用于直接展示。
+
+与 register_site_id 关系：
+
+register_site_id → 逻辑外键
+
+site_name → 冗余的门店名称快照
+
+8. tenant_id
+
+类型：int
+
+唯一值个数：1
+
+全部为 2790683160709957
+
+含义：
+
+租户/品牌 ID。
+
+确认这批会员都是属于同一个租户“朗朗桌球”（而非连锁多店场景）。
+
+六、推荐关系与成长值字段
+9. referrer_member_id
+
+类型：int
+
+唯一值个数：1
+
+全部为 0
+
+含义（按命名推断）：
+
+推荐人会员 ID，用于记录该会员是由哪位老会员推荐。
+
+目前数据的状态：
+
+本批数据中全部为 0，意味着在导出时间范围内，这些会员账户没有记录任何推荐关系（或该功能未使用）。
+
+10. point
+
+类型：float
+
+唯一值个数：1
+
+全部为 0.0
+
+含义：
+
+当前积分余额（这条会员账户的积分值）。
+
+当前状态：
+
+所有账户积分为 0，说明要么积分体系刚启用，要么此数据截取点时，积分未开始累积或未导出非零记录。
+
+11. growth_value
+
+类型：float
+
+唯一值个数：1
+
+全部为 0.0
+
+含义（按常见会员体系设计）：
+
+成长值 / 经验值，用于会员等级晋升的累计指标。
+
+当前状态：
+
+与 point 一样，全部为 0，说明成长体系虽然有字段，但目前没有实际使用或数据尚在初期。
+
+从这三个字段可以看出：
+系统预留了“推荐关系 + 积分 + 成长值”的完整会员运营链路，但这家门店在当前截取时间点上基本还处于“只建档案、不玩复杂运营”的状态。结构上功能完备，只是业务上尚未填充数据。
+
+七、状态 / 启用标志相关字段
+12. user_status
+
+类型：int，枚举
+
+唯一值个数：1
+
+全部为 1
+
+含义（结合行业惯例）：
+
+用户账号状态（偏“用户逻辑”层面的状态）。
+
+典型枚举可能为：
+
+1：正常启用
+
+0：禁用 / 冻结
+
+其他值：例如已注销等（本数据尚未出现）
+
+当前数据：
+
+全为 1，说明导出的都是正常有效的会员账户。
+
+13. status
+
+类型：int，枚举
+
+唯一值个数：1
+
+全部为 1
+
+含义（按命名推断）：
+
+帐户状态（偏“卡状态/档案状态”）。
+
+在你之前的其它 JSON 里，“status = 1”通常也是“正常”，4 等值用来表示删除/失效等。
+
+当前数据：
+
+同样全部为 1，表示这些档案都是有效的卡档案，没有注销/停用记录被导出。
+
+这里有一个设计上的细节：
+
+user_status 和 status 都是状态字段，属于“业务状态 + 系统状态”并存的设计。
+
+很多系统会用：
+
+user_status 管用户层面（是否允许登录、是否冻结等）；
+
+status 管卡账户本身（卡是否作废、是否挂失）。
+
+在你这份数据里，两者当前值完全一致（都是 1），但从结构上可以看出未来可以出现两者不一致的场景（例如用户已注销但卡余额仍在清算中等）。
+
+八、时间字段
+14. create_time
+
+类型：string
+
+格式：YYYY-MM-DD HH:MM:SS
+
+唯一值个数：86
+
+典型样例：
+
+'2025-07-20 20:46:38'（出现 5 次）
+
+'2025-07-20 20:46:36'（5 次）
+
+…
+
+含义：
+
+会员账户的创建时间（即这条档案/这张卡在系统中被创建的时间）。
+
+数据特征：
+
+很多时间戳成批出现（同一时间出现 5 条），高度怀疑是“批量导入/老系统迁移”或“批量开卡”的结果，而不是一条条手动录入。
+
+和其它业务数据（例如消费流水）相比，时间集中在 2025-07-20 晚间，说明这批会员是某个时间点一次性导入的。
+
+九、综合结构判断与和其它 JSON 的关系
+
+从字段设计可以得出以下结构层面的结论（仅从结构出发，不做任何盈利/行为分析）：
+
+记录粒度
+
+每一条 tenantMemberInfos 记录，是一个“会员在当前租户下某个卡种/账户”的档案。
+
+关键组合键可以理解为：
+
+(tenant_id, system_member_id, member_card_grade_code)
+
+或更加具体的主键 id。
+
+与其它表的关联键
+
+与消费流水（台费、助教、商品等）
+
+通过 system_member_id 把会员消费流水与会员档案关联起来。
+
+一些表里还会出现 member_card_id 或类似字段，对应这里的 id。
+
+与储值卡/余额变更/充值等表：
+
+这些表的 member_card_id / system_member_id / tenant_member_id（在不同表叫法略有差异）会与这里的 id 和 system_member_id 做主外键关系。
+
+与门店（site）：
+
+register_site_id 与其他表的 site_id 援用同一门店 ID；site_name 是冗余名称。
+
+枚举字段总结
+
+卡种枚举（明确）：
+
+member_card_grade_code / member_card_grade_name 四种：
+
+储值卡 / 台费卡 / 活动抵用券 / 月卡
+
+状态枚举（当前只见到一种值，但显然是枚举型设计）：
+
+user_status：1（正常）
+
+status：1（正常）
+
+其它预留枚举（当前值全部为单一值）：
+
+referrer_member_id：目前全为 0（“无推荐人”状态）
+
+字段使用状态
+
+已投入使用的字段：
+
+id, system_member_id, member_card_grade_*, mobile, nickname, register_site_id, site_name, tenant_id, create_time, user_status, status。
+
+这些字段组合起来，足以支持基本的会员识别、卡种区分和简单状态管理。
+
+结构上预留但目前几乎未被使用的字段：
+
+referrer_member_id（推荐体系）
+
+point（积分体系）
+
+growth_value（成长值/等级成长体系）
+
+这些字段从结构上完整存在，但在当前数据截面上全部为默认值 0，说明门店尚未使用这些高级运营功能。
+
+分页与导出行为的结构线索
+
+data.total = 438，而本次两个 page 合并只有 200 条，说明：
+
+该接口是典型的分页接口（每页 100 条）；
+
+当前只导出了前两页（或者是时间/条件过滤导致只取到部分）。
+
+id 和 system_member_id 各有一个值重复了两次，且所有字段完全相同：
+
+很可能是分页处理时边界重叠导致的重复（比如页 1 末尾的记录又出现在页 2 的开头），不是数据设计错误。
+
+十、小结：会员档案.json 的角色
+
+从纯字段与结构角度，可以把 20251110_043209_会员档案.json 概括为：
+
+它不是“纯粹的人头表”，而是“会员 × 卡种 的账户档案表”，一条记录既包含“谁”（system_member_id / mobile / nickname），也包含“是什么卡”（member_card_grade_xxx）。
+
+它作为 会员维度的核心参照表，被其它业务表通过 system_member_id 和 id 广泛引用：
+
+消费流水中的会员消费，回来可以通过这些键指向这一表；
+
+储值余额变动、充值、退款等资金类流水，最终也会落到某个 id 所代表的“会员账户/卡”上。
+
+从字段现状可见：门店目前主要使用的是“储值卡 + 台费卡 + 少量月卡/抵用券”的基本功能，重点在“建档与卡种区分”，尚未真正利用积分、成长值、推荐等高级字段。这是“结构完备、业务使用部分开启”的典型状态。