schulcloud/gamification

Gamification 服务

一个可重用的游戏化微服务。

本项目提供一个微服务，用于管理应用程序的游戏化功能。它不提供任何图形界面或预定义内容，仅提供后端REST API。其核心功能是监听通过HTTP POST调用发送或从RabbitMQ接收的事件，然后根据新接收的事件测试用户定义的成就规则。如果成就规则评估为true，则向用户授予新成就。

术语

用户

所有游戏化数据都与用户关联。用户通过唯一字符串user_id标识。每个用户拥有：

• 一个等级
• 多个已授予的成就
• 多个XP池中的XP

注意：没有显式的用户表。用户数据分布在多个其他表中，按需聚合。

成就

成就是游戏化服务的核心对象。用户努力收集成就。成就可视为徽章、腰带或任何其他进度表示形式。对游戏化服务而言，这些都统一称为“成就”。成就通常定义一个或多个授予条件，例如：

• 用户达到10 XP
• 用户获得了FooAchievement成就
• 收到FooEvent事件且用户XP少于42

如果需要，同一成就可多次授予同一用户。成就授予后也可撤销，例如用难以获得的FooGold成就替换容易获得的FooSilver成就。部分成就撤销后可再次授予，部分则不可。此行为可通过maxAwarded和maxAwardedTotal配置选项分别设置。

XP池

应用程序可定义多个XP池。默认池名为“XP”，始终存在。每个用户在每个XP池中拥有一定数量的XP。新用户在所有XP池中初始XP为0。XP可增减，但不应低于0。不同XP池的用途包括：

• 计算游戏中常见的“经验值”
• 表示用户可赚取和消费的某种“货币”
• 统计特定事件发生的次数，该计数器可用于更复杂的成就条件

等级

每个用户都有等级。用户从1级开始，且等级永不低于1级。等级与用户的主XP池“XP”直接关联。各级所需XP可配置为线性增长、指数增长或完全自定义。等级不存储在数据库中，而是动态计算。若用户因某种原因失去XP，其等级可能降低。

工作流程

本部分详细描述游戏化服务的总体概念。该服务设计为完全事件驱动，可与RabbitMQ良好集成，适用于现有微服务架构。它监听其他服务发出的可配置事件，这些事件并非游戏化专用。例如，应用程序通常不会发送“Grant10XP”事件，而是发送“ForumPost”或“UserSignup”等事件。需配置规则（见下节）以定义收到“ForumPost”或“UserSignup”事件后执行的操作（如授予10 XP）。现有服务无需知晓其事件被用于游戏化。

游戏化服务订阅RabbitMQ队列并处理事件。收到事件后，服务检查该事件是否与游戏化相关。若相关，执行任何已配置的即时操作，然后检查所有配置的成就规则，确定是否应向用户授予新成就。需根据应用需求自行设置要监听的事件、事件操作和成就规则。成就或XP授予后，将持久化到MongoDB。计划在授予成就或XP时向RabbitMQ发送事件。

游戏化服务还提供（主要为只读的）REST API，可用于查询用户的成就、XP和等级。未来API可能支持排行榜等高级用例。API文档位于http://localhost:3030/docs。

游戏化配置

游戏化规则必须在config/gamification.yml文件中配置。该文件在应用启动时解析，需根据游戏化需求调整。最基本的配置如下：

yml
XPs: []
levels:
  type: linear
  interval: 100
events: {}
achievements: {}

以下是详细配置选项。注意：目前没有配置验证逻辑，配置错误可能导致应用崩溃！

XP池

定义应用中的不同XP池。“XP”池始终存在。

yml
XPs:
  - money
  - myOtherXP
  - myXP

注意：配置解析器目前不验证此处定义的XP池名称，即未指定可用XP池或指定额外XP池不会引发错误。但计划加强配置验证，届时使用未在此处定义的XP池将引发错误。

等级

定义用户基于XP提升等级的条件。等级始终完全基于用户当前的XP。无论配置如何，用户始终从1级开始。这意味着第一个配置值指定用户达到2级的条件，而非1级。有三种配置等级的方式：

yml
levels:
  # 手动等级阶梯：2级需10 XP，3级需100 XP，4级需1000 XP
  type: manual
  steps: [10, 100, 1000]
  # 线性等级阶梯：每100 XP提升一级，即2级需100 XP，3级需200 XP，依此类推
  type: linear
  interval: 100
  # 指数等级阶梯：提升下一级所需XP翻倍。2级需100 XP，3级需200 XP，4级需400 XP，依此类推
  type: exponential
  starting_value: 100

事件

定义要监听的事件。服务将忽略其他事件。每个键是要监听的事件名称，对应的值描述收到事件时执行的即时操作。

可使用actions数组指定收到事件后立即执行的操作。

yml
events:
  # 最简单形式：事件名称后接`: ~`，表示收到事件时不执行任何即时操作
  MyEvent: ~
  # 等效于
  MyEvent:
    actions: []

每个操作是一个对象，包含一个顶级键表示操作类型。目前仅支持“xp”操作。默认情况下，受奖者ID假定来自事件顶级user_id字段。若不想让触发事件的用户获得XP，可使用awardee_id配置选项从事件 payload 中获取受奖者ID。

yml
actions:
  - xp:
      # XP池名称
      name: myXP
      # 增减数量（可负数）
      amount: 1
      # 可选：payload中包含受奖者user_id的字段名
      awardee_id: receiver_id

成就规则

yml
# 定义所有可用成就。这些定义称为“成就规则”。每个键是成就的唯一名称，对应的值描述该成就的详细信息。
achievements:
  # 最简单但无用的成就配置
  MyAchievement: ~
  # 等效于以下配置
  MyAchievement:
    # 成就的要求列表
    requirements: []
    # 授予此成就时，用户若拥有的其他成就名称列表（将被撤销）
    replaces: []
    maxAwarded: 1
    maxAwardedTotal: 1
    actions: []
    hidden: false
    # 尚未实现：作用域
    scope: [user_id]

成就规则 requirements

requirements键指定成就授予用户必须满足的所有条件。每个条件包含一个顶级键表示条件类型，对应值设置进一步配置选项。默认情况下，所有条件必须满足才能授予成就。此外，下文描述的maxAwarded和maxAwardedTotal选项也可能限制成就授予。

支持四种条件类型，部分支持amount设置。amount可以是数字x（视为>= x），或以下字符串之一：

• "== x"：等于x
• "!= x"：不等于x
• ">= x"：至少x
• "> x"：大于x
• "<= x"：至多x
• "< x"：小于x

xp 条件

xp条件指定某个XP池中的XP数量要求。需指定XP池名称和所需数量。以下示例在用户XP少于42时满足：

yml
- xp:
    name: XP
    amount: "< 42"

achievement 条件

achievement条件指定所需的其他成就。需指定其他成就名称和数量。以下示例在用户拥有2个MyAchievement成就时满足：

yml
- achievement:
    name: MyAchievement
    amount: 2

AnyOf 条件

AnyOf条件允许在条件间指定“或”语义。条件值是子条件列表，只要任一子条件满足，该条件即满足。以下示例在用户yourXP至少10或XP至少20时满足：

yml
- AnyOf:
  - xp:
      name: yourXP
      amount: 10
  - xp:
      name: XP
      amount: 20

event 条件

event条件指定必须已收到的事件。需指定事件名称和数量，还可选择定义事件的“条件”。以下是复杂示例：

yml
- event:
    name: YourEventName
    amount: >= 10
    conditions:
      # 条件有两种类型：`parameter`和`AnyOf`。与要求类似，条件使用“与”语义。
      - parameter: someParameter
        value: 100
      - AnyOf:
        - parameter: someOtherParameter
          value: 10
        - parameter: someOtherParameter2
          value: 100
        - AnyOf:
          - parameter: someOtherParameter3
            value: 10
          - parameter: someOtherParameter4
            value: 100

成就规则 replaces

replaces键指定其他成就名称数组。当用户获得新成就时，若拥有此处指定的任何成就，将被撤销。这适用于多级成就（如用“金”成就替换“银”成就）。若用户拥有多个被替换的成就，将全部移除。

成就规则 maxAwarded 和 maxAwardedTotal

这两个设置配置成就可授予用户的次数。maxAwarded指定用户可同时拥有该成就的最大数量；maxAwardedTotal指定用户一生中可被授予该成就的最大总次数。两者均为可选，若同时设置，需确保maxAwarded <= maxAwardedTotal。若两者均未设置，默认值为1；仅设置maxAwarded时，maxAwardedTotal默认为正无穷；仅设置maxAwardedTotal时，maxAwarded默认为maxAwardedTotal。

成就规则 actions

actions数组指定成就授予时执行的操作。每个操作是一个对象，包含一个顶级键表示操作类型。目前仅支持“xp”操作：

yml
actions:
  - xp:
      # XP池名称
      name: myXP
      # 增减数量（可负数）
      amount: 1

成就规则 hidden

布尔值，指示成就是否“公开”及是否在/user端点返回。默认为false。适用于仅表示状态且不应向用户显示的成就。

成就规则 scope

尚未实现。计划用于覆盖在实体（如课程或教室）范围内授予成就的场景。

内部实现

本项目使用Feathers作为API框架，MongoDB存储数据，Mongoose验证存储数据。

Feathers服务

游戏化服务基于四个Feathers服务构建：

1. Achievements：处理成就数据，将已授予的成就存储在achievements集合中。每行包含user_id、name（成就名称）、current_amount（用户当前拥有该成就的数量）、total_amount（用户获得该成就的总次数）和scope（尚未实现）。

2. Events：处理事件数据，将所有传入事件存储在events集合中。每行包含user_id、name（事件名称）和payload（事件负载）。

3. XP：处理XP池数据，将所有授予的XP存储在xp集合中。每行包含user_id、name（XP池名称）和amount（用户在该XP池中的XP数量）。

4. User：聚合其他三个服务的数据，用于检索单个用户的游戏化信息。是唯一没有自己集合的服务，还负责计算用户等级。

开发指南

本地开发

1. 确保安装https://nodejs.org/ >= 8.0.0、https://www.npmjs.com/ >= 6.1.0和MongoDB。

2. 若无本地RabbitMQ，临时从src/index.js中移除AmqpConnector.connect()调用。

3. 安装npm依赖：

   bash
   cd path/to/gamification; npm install
   

4. 启动应用：

   bash
   npm dev
   

Docker开发

项目提供两个docker-compose文件：一个用于开发，一个用于生产。生产环境docker-compose.yml不包含RabbitMQ服务定义（假设连接到现有RabbitMQ实例）；开发环境docker-compose.dev.yml包含RabbitMQ定义以简化开发。

首先运行npm install，然后启动Docker环境：

bash
docker-compose -f docker-compose.dev.yml up

这将启动应用、MongoDB和RabbitMQ容器。应用可通过http://localhost:3030%E8%AE%BF%E9%97%AE%E3%80%82

RabbitMQ：手动发送事件

RabbitMQ管理界面位于http://localhost:***%E3%80%82%E5%BC%80%E5%8F%91%E6%A8%A1%E5%BC%8F%E4%B8%8B%EF%BC%8C%E4%BD%BF%E7%94%A8%E7%94%A8%E6%88%B7%E5%90%8D%60guest%60%E5%92%8C%E5%AF%86%E7%A0%81%60guest%60%E7%99%BB%E5%BD%95%E3%80%82

可在“Exchanges”部分手动发送事件：选择交换机，然后在“Publish message”处发布消息，不要忘记输入“routing key”。

测试

运行npm test执行所有代码检查和测试。使用npm coverage生成覆盖率报告。

生产运行

建议使用docker-compose在生产环境运行此微服务。在项目根目录执行RABBITMQ_HOST=rabbit-host:5672 docker-compose up启动Node.js应用和MongoDB容器。需自行启动独立的RabbitMQ容器并相应设置RABBITMQ_HOST环境变量。若不使用RabbitMQ集成，省略该环境变量即可。

许可证

版权所有 (c) 2018 Kim-Pascal Borchart, Christian Flach, Corinna Jaschek, Sebastian Kliem, Mandy Klingbeil, Marcus Konrad, Frederike Ramin。

根据MIT许可证授权。