Feature Setting - EDU 教育引导接口文档

概述

EDU (Education) 功能设置模块是 Katana 平台的新用户教育引导系统，用于向 Promoter（推广者）和 Consumer（消费者）展示分步骤的引导流程，帮助用户快速了解平台核心功能。

核心概念

• FeatureName: 功能名称标识符，每个 EDU 功能对应一个唯一的 FeatureName
• FeatureScene: 功能场景，定义了在哪些页面/场景下应该展示哪些 EDU 功能
• PromoterSetting: 推广者个人功能设置，记录用户是否完成某个引导
• FeatureSetting: 全局功能配置，定义功能的默认配置（如引导文案、图片等）
• ConsumerSetting: 消费者功能设置，记录消费者对某个推广者的引导状态

功能优先级规则

系统按顺序返回未完成的引导流程。当前一个流程完成后，才会返回下一个流程。

数据库表结构

-- 推广者个人功能设置表
model PromoterSetting {
  id          String   @id @db.Uuid
  promoterId  String   @map("promoter_id") @db.Uuid
  createdAt   DateTime @default(now()) @map("created_at") @db.Timestamptz()
  updatedAt   DateTime @updatedAt @map("updated_at") @db.Timestamptz()
  featureName String   @default("") @map("feature_name")
  settingData Json     @default("{}") @map("setting_data")

  @@unique([promoterId, featureName])
  @@index([promoterId])
}

-- 全局功能配置表
model FeatureSetting {
  id          String   @id @db.Uuid
  createdAt   DateTime @default(now()) @map("created_at") @db.Timestamptz()
  updatedAt   DateTime @updatedAt @map("updated_at") @db.Timestamptz()
  featureName String   @map("feature_name")
  enable      Boolean  @default(true)
  featureData Json     @default("{}") @map("feature_data")

  @@index([featureName])
}

-- 消费者功能设置表
model ConsumerSetting {
  id          String   @id @db.Uuid
  consumerId  String   @map("consumer_id") @db.Uuid
  promoterId  String?  @map("promoter_id") @db.Uuid
  createdAt   DateTime @default(now()) @map("created_at") @db.Timestamptz()
  updatedAt   DateTime @updatedAt @map("updated_at") @db.Timestamptz()
  featureName String   @map("feature_name")
  featureData Json     @default("{}") @map("feature_data")

  @@index([promoterId])
  @@index([consumerId])
}

接口列表

1. 获取推广者功能设置列表

根据指定场景获取当前用户待展示的 EDU 功能设置列表。

接口信息

• 请求地址: /feature-setting/promoter
• 请求方式: GET
• 需要认证: 是（JWT Token）

请求头（Header）

请求参数（Query）

FeatureSettingScene 枚举值

响应结构

{
  "code": number,           // 状态码，200 表示成功
  "message": string,        // 响应消息
  "request_id": string,     // 请求追踪 ID
  "data": {                 // 功能设置映射表
    "[FeatureName]": {      // 功能名称作为 key
      // 功能配置数据
    }
  }
}

响应字段说明

通用字段

功能配置字段

成功响应示例

{
  "code": 200,
  "message": "success",
  "request_id": "17840261-7252-428b-8a14-1a0babb0168f",
  "data": {
    "EDU_INTRODUCE_SHOP": {
      "step1": {
        "cta": "Next",
        "title": "Customize your shop",
        "description": "Add your cover image, intro, and social, then adjust colors and fonts to make it your own."
      },
      "step2": {
        "cta": "Next",
        "title": "Add new module",
        "backCta": "Back",
        "description": "Add modules to feature your events, products, or content exactly how you want."
      },
      "step3": {
        "cta": "Next",
        "title": "Preview your shop",
        "backCta": "Back",
        "description": "Preview your storefront exactly as your visitors will see it."
      },
      "step4": {
        "cta": "Got it",
        "title": "Introduce content tabs",
        "backCta": "Back",
        "description": "These tabs are your content library. All posts and links live here until deleted. They're hidden by default and best shared via custom modules."
      },
      "completed": false,
      "enable": true
    }
  }
}

业务逻辑

flowchart TD
    A[开始: GET /feature-setting/promoter] --> B[从 JWT 获取 promoterId]
    B --> C{验证用户是否存在}
    C -->|不存在| D[抛出 ResourceNotFound]
    C -->|存在| E{用户是否为 Promoter}
    E -->|否| F[返回空对象 {}]
    E -->|是| G[根据 scene 获取功能名称列表]
    G --> H[查询所有功能的用户设置]
    H --> I[过滤已完成的功能]
    I --> J{scene 是否为 SCENE_CURATOR_PDP}
    J -->|是| K[返回所有未完成功能]
    J -->|否| L[按优先级返回第一个未完成功能]
    L --> M[合并全局功能配置数据]
    M --> N[检查功能启用状态和白名单]
    N --> O[返回结果]

场景与功能映射表

错误响应示例

401 Unauthorized

{
  "statusCode": 401,
  "message": "Unauthorized"
}

404 Not Found

{
  "statusCode": 404,
  "message": "Resource not found",
  "error": "User not found"
}

注意事项

1. 认证要求: 接口需要有效的 JWT Token，从 Token 中提取 userId 作为 promoterId
2. 角色校验: 非 Promoter 角色的用户会返回空对象
3. 功能优先级: 除 SCENE_CURATOR_PDP 外，其他场景只返回第一个未完成的功能
4. 白名单验证: 部分功能可能受白名单限制，未通过验证的用户会自动标记为已完成
5. 自动创建: 首次调用时自动创建用户功能设置记录

2. 更新推广者功能设置状态

将指定的 EDU 功能标记为已完成。

接口信息

• 请求地址: /feature-setting/promoter/{featureName}
• 请求方式: PATCH
• 需要认证: 是（JWT Token）

请求头（Header）

路径参数（Path）

请求体（Body）

{
  "completed?: boolean",      // 是否标记为完成（可选）
  "triggerDate?: string",     // 触发日期，ISO 8601 格式（可选）
  "promoterId?: string",      // 推广者 ID（可选，通常从 JWT 获取）
  "id?: string"               // 功能 ID（可选，用于公告类功能）
}

请求体字段说明

响应结构

{
  "code": number,           // 状态码，200 表示成功
  "message": string,        // 响应消息
  "request_id": string      // 请求追踪 ID
}

成功响应示例

{
  "code": 200,
  "message": "success",
  "request_id": "989e4eb5-cacb-44aa-b17e-110e3f4c84be"
}

业务逻辑

flowchart TD
    A[开始: PATCH /feature-setting/promoter/{featureName}] --> B[从 JWT 获取 promoterId]
    B --> C{功能名称是否在 FeatureScene 中}
    C -->|否| D[抛出 BadRequestException]
    C -->|是| E[查询用户功能设置]
    E --> F{设置是否存在}
    F -->|否| G[抛出 ResourceNotFound]
    F -->|是| H{功能类型判断}
    H -->|一次性完成类| I[标记 completed = true]
    H -->|显示控制类| J[设置 display = false]
    H -->|公告类| K[更新 dismissed 列表]
    H -->|计数器类| L[更新日期和计数]
    I --> M[保存到数据库]
    J --> M
    K --> M
    L --> M
    M --> N[返回成功响应]

功能类型与处理方式

错误响应示例

400 Bad Request - 未知功能

{
  "statusCode": 400,
  "message": "Unknown feature-setting type"
}

404 Not Found

{
  "statusCode": 404,
  "message": "Resource not found",
  "error": "PromoterSetting not found"
}

401 Unauthorized

{
  "statusCode": 401,
  "message": "Unauthorized"
}

注意事项

1. 幂等性: 重复标记已完成的功能不会报错，但会更新数据库记录
2. 功能验证: 只有在 FeatureScene 中定义的功能才能被更新
3. 自动完成标记: 调用后会将 completed 字段设置为 true
4. 公告类功能: 需要传 id 参数来标记具体哪条公告已读

3. 获取单个推广者功能设置

获取指定功能的详细配置，包括全局配置和用户个人设置。

接口信息

• 请求地址: /feature-setting/promoter/{featureName}
• 请求方式: GET
• 需要认证: 是（JWT Token）

请求头（Header）

路径参数（Path）

响应结构

{
  "code": number,
  "message": string,
  "request_id": string,
  "data": {
    // 功能配置数据
  }
}

成功响应示例

EDU_NEW_BUSINESS_PARTNER 响应

{
  "code": 200,
  "message": "success",
  "request_id": "xxx-xxx-xxx",
  "data": {
    "completed": false,
    "enable": true,
    "pass": true,
    // 其他功能特定配置...
  }
}

EDU_INTRODUCE_SHOP 响应

{
  "code": 200,
  "message": "success",
  "request_id": "xxx-xxx-xxx",
  "data": {
    "step1": {
      "cta": "Next",
      "title": "Customize your shop",
      "description": "Add your cover image, intro, and social..."
    },
    "step2": { /* ... */ },
    "step3": { /* ... */ },
    "step4": { /* ... */ },
    "completed": false,
    "enable": true
  }
}

业务逻辑

flowchart TD
    A[开始: GET /feature-setting/promoter/{featureName}] --> B[从 JWT 获取 promoterId]
    B --> C{用户角色是否为 CONSUMER}
    C -->|是| D[返回 { completed: true }]
    C -->|否| E[查询用户功能设置]
    E --> F{功能类型特殊处理}
    F -->|EDU_NEW_BUSINESS_PARTNER| G[检查用户是否为 Business Partner]
    F -->|EDU_SETUP_SHOP| H[检查 shopProfileUpdated 状态]
    F -->|EDU_NEW_CURATOR_COUPON| I[检查注册时间是否过期]
    F -->|其他| J[使用默认处理]
    G --> K{是否满足条件}
    H --> K
    I --> K
    J --> L[返回配置数据]
    K -->|不满足| M[返回 { completed: true }]
    K -->|满足| L
    L --> N[合并全局配置和用户设置]
    N --> O[检查功能启用状态]
    O --> P[返回最终数据]

特殊功能逻辑

EDU_NEW_BUSINESS_PARTNER

• 显示条件: 用户必须是 BUSINESS_PARTNER 角色
• 自动完成: 非 Business Partner 自动标记为已完成
• 实现代码位置: src/feature-setting/onboarding/promoter-onboarding.service.ts:232-246

EDU_INTRODUCE_SHOP

• 功能类型: CompleteOnce（一次性完成）
• 步骤配置: 4 个步骤，每个步骤包含 cta、title、description 字段
• 场景: SCENE_MY_SHOP

EDU_REARRANGE_MODULES

• 显示条件: 用户的 StoreFront 模块数量必须 > 1
• 自动完成: 模块数量 ≤ 1 时自动标记为已完成
• 实现代码位置: src/feature-setting/onboarding/promoter-onboarding.service.ts:475-492

错误响应示例

400 Bad Request - 未知功能

{
  "statusCode": 400,
  "message": "EDU_UNKNOWN_FEATURE: Unknown feature name"
}

404 Not Found

{
  "statusCode": 404,
  "message": "Resource not found",
  "error": "FeatureSetting not found"
}

注意事项

1. 消费者角色: CONSUMER 角色的用户请求时会直接返回 { completed: true }
2. 自动创建: 首次获取时自动创建用户功能设置记录
3. 条件验证: 部分功能会根据用户属性动态判断是否应该显示

FeatureName 枚举说明

EDU - 新用户引导类

订阅类

公告类

注册类

其他

数据结构定义

CompleteOnce（一次性完成）

{
  completed: boolean;  // 是否已完成
}

DateAndCount（日期计数）

{
  completed: boolean;  // 是否已完成
  count: number;       // 计数器
  date: Date;          // 日期
}

EduDisplay（显示控制）

{
  display: boolean;    // 是否显示
}

DisMiss（可关闭）

{
  completed: boolean;   // 是否已完成
  dismissed: string[];  // 已关闭的项目 ID 列表
}

PromoterDefaultSetting（推广者默认设置）

联合类型，可能是以下类型之一：

• CompleteOnce
• DateAndCount
• EduDisplay
• DisMiss

白名单与功能开关

功能开关验证流程

flowchart TD
    A[开始功能检查] --> B{查询 FeatureSetting}
    B --> C{enable 是否为 true}
    C -->|否| D[返回 false - 功能禁用]
    C -->|是| E{isWhiteListOn 是否为 true}
    E -->|否| F[返回 true - 功能启用]
    E -->|是| G{检查 FeatureFlag 白名单}
    G -->|用户在白名单| F
    G -->|用户不在白名单| D

配置示例

{
  "featureName": "EDU_INTRODUCE_SHOP",
  "enable": true,
  "featureData": {
    "isWhiteListOn": false,
    "step1": {
      "cta": "Next",
      "title": "Customize your shop"
    }
  }
}

使用场景示例

场景 1：新 Business Partner 首次进入我的店铺

# 1. 前端请求待展示的功能
curl -X GET 'https://katana-api.1m.app/feature-setting/promoter?scene=SCENE_MY_SHOP' \
  -H 'authorization: Bearer {JWT_TOKEN}'

# 2. 返回 EDU_NEW_BUSINESS_PARTNER 功能配置
# 前端展示引导弹窗

# 3. 用户点击"我知道了"，标记完成
curl -X PATCH 'https://katana-api.1m.app/feature-setting/promoter/EDU_NEW_BUSINESS_PARTNER' \
  -H 'authorization: Bearer {JWT_TOKEN}' \
  -H 'content-type: application/json' \
  -d '{}'

# 4. 下次请求时，会返回下一个未完成的功能 EDU_INTRODUCE_SHOP

场景 2：完成 EDU_INTRODUCE_SHOP 的 4 步引导

# 获取功能配置
curl -X GET 'https://katana-api.1m.app/feature-setting/promoter/EDU_INTRODUCE_SHOP' \
  -H 'authorization: Bearer {JWT_TOKEN}'

# 返回包含 4 个步骤的配置
# 前端根据 step1, step2, step3, step4 展示分步引导

# 用户完成所有步骤后，标记功能完成
curl -X PATCH 'https://katana-api.1m.app/feature-setting/promoter/EDU_INTRODUCE_SHOP' \
  -H 'authorization: Bearer {JWT_TOKEN}' \
  -H 'content-type: application/json' \
  -d '{"completed": true}'

场景 3：处理公告类功能

# 获取待显示的公告
curl -X GET 'https://katana-api.1m.app/feature-setting/promoter?scene=SCENE_MY_SHOP' \
  -H 'authorization: Bearer {JWT_TOKEN}'

# 假设返回 PEAR_ANNOUNCEMENTS，包含多条公告
# 用户关闭某条公告时，传递公告 ID
curl -X PATCH 'https://katana-api.1m.app/feature-setting/promoter/PEAR_ANNOUNCEMENTS' \
  -H 'authorization: Bearer {JWT_TOKEN}' \
  -H 'content-type: application/json' \
  -d '{"id": "announcement-123"}'

常见问题

Q1: 为什么有些功能没有返回？

A: 可能的原因：

1. 功能已完成（completed = true）
2. 功能未启用（enable = false）
3. 用户不在白名单中（pass = false）
4. 功能的显示条件不满足（如 EDU_NEW_BUSINESS_PARTNER 要求用户是 Business Partner）

Q2: 如何判断是否应该显示引导弹窗？

A: 判断逻辑：

1. 检查 completed 是否为 false
2. 检查 enable 是否为 true
3. 检查 pass 是否为 true（如果存在）
4. 所有条件满足时应该显示弹窗

Q3: 同一场景多个功能的优先级如何确定？

A: 按 FeatureScene 中定义的数组顺序，数组前面的优先级更高。只有当前一个功能完成后，才会返回下一个功能。

Q4: PATCH 请求需要传什么参数？

A:

• 大多数情况：传空对象 {} 即可，系统自动标记为完成
• 公告类功能：传 { "id": "announcement-id" } 标记具体公告已读
• 如需延迟完成：传 { "completed": false }（但不推荐）

Q5: Consumer 角色用户会返回什么？

A: 返回空对象 {} 或 { completed: true }，不会显示任何引导内容。

相关文件

更新日志