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

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

@@ -0,0 +1,203 @@
+# 会员档案 — GetTenantMemberList
+
+> 模块：`MemberProfile` · ODS 表：`member_profiles` · 维度表（快照）
+
+---
+
+## 一、接口概述
+
+查询门店下所有会员的账户档案信息。每条记录对应一个"会员 × 卡种"级别的账户，包含会员身份、卡种类型、注册门店、积分/成长值、状态等。本表是会员维度的核心参照表，被消费流水、余额变更、储值卡等事实表通过 `system_member_id` 和 `id` 广泛引用。
+
+| 属性 | 值 |
+|------|-----|
+| 完整路径 | `POST /MemberProfile/GetTenantMemberList` |
+| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
+| 鉴权 | `Authorization: Bearer <token>` |
+| 分页 | `page` + `limit`（最大 100） |
+| 时间范围 | 不需要（全量快照） |
+| 响应数据路径 | `data.tenantMemberInfos` |
+
+---
+
+## 二、请求
+
+### 请求体（JSON）
+
+```json
+{
+  "isMemberInBlackList": 0,
+  "status_Revoked": 0,
+  "isBindOrg": 0,
+  "registerSource": 0,
+  "page": 1,
+  "limit": 100
+}
+```
+
+### 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `isMemberInBlackList` | int | 是 | 黑名单筛选。`0` = 全部 |
+| `status_Revoked` | int | 是 | 注销状态筛选。`0` = 全部 |
+| `isBindOrg` | int | 是 | 是否绑定组织筛选。`0` = 全部 |
+| `registerSource` | int | 是 | 注册来源筛选。`0` = 全部 |
+| `page` | int | 是 | 页码，从 1 开始 |
+| `limit` | int | 是 | 每页条数，最大 100 |
+
+---
+
+## 三、响应结构
+
+```
+{
+  "code": 200,
+  "data": {
+    "list": [ { ... }, { ... } ],
+    "total": 438
+  }
+}
+```
+
+`data.list` 中每个对象即为一条会员账户档案记录，共 21 个字段，按 9 个逻辑分组说明如下。
+
+---
+
+## 四、响应字段详解（21 个字段）
+
+### 4.1 主键与会员标识
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `id` | int | `2955204541320325` | 租户内会员账户主键 ID。对应一个会员在当前租户下某个卡种的账户档案。在余额变更表中对应 `tenant_member_id`，在储值卡列表中对应 `tenant_member_id` |
+| `system_member_id` | int | `2955204540009605` | 系统级会员 ID，全平台唯一。用于将同一会员在不同门店/不同卡种下的账户统一到一个"人"的维度。与 `id` 是一对多关系（一人可有多张卡） |
+
+### 4.2 卡种信息
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `member_card_grade_code` | int | `2790683528022853` | 会员卡种类/等级编码。枚举：`2790683528022853` = 储值卡，`2790683528022855` = 台费卡，`2790683528022856` = 活动抵用券，`2790683528022857` = 月卡 |
+| `member_card_grade_name` | string | `"储值卡"` | 卡种名称，与 `member_card_grade_code` 一一对应。枚举值：`"储值卡"`、`"台费卡"`、`"活动抵用券"`、`"月卡"` |
+
+### 4.3 联系方式与展示信息
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `mobile` | string | `"18620043391"` | 会员绑定手机号（11 位）。在同一租户下具备唯一性 |
+| `nickname` | string | `"胡先生"` | 会员显示名称（可以是姓名或昵称）。注意与助教流水中的 `nickname`（助教昵称）区分 |
+
+### 4.4 注册门店与租户
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `register_site_id` | int | `2790685415443269` | 会员注册门店 ID，与其他业务表的 `site_id` 一致 |
+| `site_name` | string | `"朗朗桌球"` | 注册门店名称，冗余展示字段 |
+| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID，所有记录相同 |
+
+### 4.5 推荐关系与成长体系
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `referrer_member_id` | int | `0` | 推荐人会员 ID。`0` = 无推荐人。当前门店未启用推荐体系 |
+| `point` | float | `0.0` | 当前积分余额。当前门店未启用积分体系 |
+| `growth_value` | float | `0.0` | 成长值/经验值，用于会员等级晋升。当前门店未启用 |
+
+### 4.6 状态字段
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `user_status` | int | `1` | 用户账号状态（用户逻辑层面）。`1` = 正常启用，`0` = 禁用/冻结 |
+| `status` | int | `1` | 账户/卡档案状态。`1` = 正常，`4` = 失效/注销。与 `user_status` 分别管理用户层面和卡层面的状态 |
+
+### 4.7 消费与充值统计
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `pay_money_sum` | number | `-12.79` | 累计消费金额（元）。负值表示支出方向 |
+| `recharge_money_sum` | number | `5000.0` | 累计充值金额（元） |
+
+### 4.8 组织归属与注册来源
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `person_tenant_org_id` | integer | `0` | 人事组织 ID。`0` = 未绑定组织 |
+| `person_tenant_org_name` | string | `""` | 人事组织名称。为空时表示未绑定 |
+| `register_source` | integer | `6` | 注册来源枚举。`6` = 小程序注册，其他值需结合系统配置 |
+
+### 4.9 时间元数据
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `create_time` | string | `"2025-11-08 01:29:33"` | 会员账户创建时间。批量出现相同时间戳的记录通常是批量导入/迁移的结果 |
+
+---
+
+## 五、响应样例（单条记录）
+
+```json
+{
+  "id": 2955204541320325,
+  "create_time": "2025-11-08 01:29:33",
+  "member_card_grade_code": 2790683528022853,
+  "mobile": "18620043391",
+  "nickname": "胡先生",
+  "register_site_id": 2790685415443269,
+  "site_name": "朗朗桌球",
+  "member_card_grade_name": "储值卡",
+  "system_member_id": 2955204540009605,
+  "tenant_id": 2790683160709957,
+  "referrer_member_id": 0,
+  "point": 0.0,
+  "user_status": 1,
+  "status": 1,
+  "growth_value": 0.0
+}
+```
+
+---
+
+## 六、跨表关联
+
+### 与储值卡列表（`member_stored_value_cards`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `id` | `tenant_member_id` | 会员账户主键 → 储值卡的持卡会员 ID |
+| `system_member_id` | `system_member_id` | 系统级会员 ID，完全一致 |
+| `member_card_grade_code` | `member_card_grade_code` | 卡种编码，可配套构成完整的卡种维度 |
+
+### 与余额变更记录（`member_balance_changes`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `id` | `tenant_member_id` | 会员账户主键 → 余额变更的会员 ID |
+| `system_member_id` | `system_member_id` | 系统级会员 ID |
+
+### 与消费流水（台费、助教、商品等）
+
+通过 `system_member_id` 将会员消费流水与会员档案关联。部分流水表中还有 `member_card_id` 或类似字段，对应本表的 `id`。
+
+### 与门店维度
+
+所有业务表的 `tenant_id`、`site_id` 一致，共享门店维度。`register_site_id` 与其他表的 `site_id` 引用同一门店 ID。
+
+<!--
+AI_CHANGELOG:
+- 日期: 2026-02-13
+- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
+- 直接原因: 按标杆文档格式重写高质量 API 参考文档
+- 变更摘要: 新建 docs/api-reference/member_profiles.md，按逻辑分组详解所有字段，含跨表关联
+- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
+
+- 日期: 2026-02-14
+- Prompt: P20260214-060000 / P20260214-061000 — 全量 JSON 刷新 + MD 文档补全 + 数据路径修正
+- 直接原因: 旧 JSON 样本仅含单条记录，缺少条件性字段；api_registry.json 中 17 个 data_path 与实际不符
+- 变更摘要: 新增「响应数据路径」行；补全 2 个缺失字段（person_tenant_org_id, person_tenant_org_name）
+- 风险与验证: 纯文档变更，无运行时影响；验证：python scripts/refresh_json_and_audit.py 输出 24/24 通过
+
+- 日期: 2026-02-14
+- Prompt: P20260214-130000 — 25 个 API 文档归档至 summary/ + 字段分组修正
+- 直接原因: 4.7"时间元数据"组混入 pay_money_sum/recharge_money_sum（消费统计）、person_tenant_org_id/name（组织归属）、register_source（注册来源）
+- 变更摘要: 新增 4.7"消费与充值统计"（2 字段）、4.8"组织归属与注册来源"（3 字段）；原 4.7 时间组重编号为 4.9；字段总数从 15 更正为 21
+- 风险与验证: 纯文档分组调整，无运行时影响；验证：统计各组字段数总和 = 21
+-->