DeviseInvitable 技术文档

1. 安装指南

安装 DeviseInvitable Gem

首先，你需要安装 devise_invitable gem。可以通过以下命令进行安装：

gem install devise_invitable

添加到 Gemfile

将 devise_invitable 添加到你的 Gemfile 中：

gem 'devise_invitable', '~> 2.0.0'

自动安装

运行以下生成器，将 devise_invitable 的配置选项添加到 Devise 配置文件 (config/initializers/devise.rb) 中：

rails generate devise_invitable:install

完成后，你可以使用以下生成器将 devise_invitable 添加到任何 Devise 模型中：

rails generate devise_invitable MODEL

将 MODEL 替换为你想要添加 devise_invitable 的类名，例如 User、Admin 等。这将向你的模型的 Devise 模块添加 :invitable 标志，并生成一个迁移文件（如果 ORM 支持）。

手动安装

如果你选择手动安装，请按照以下步骤操作：

Devise 配置

在你的模型中，将 :invitable 添加到 devise 调用中：

class User < ActiveRecord::Base
  devise :database_authenticatable, :confirmable, :invitable
end

ActiveRecord 迁移

在你的 Devise 模型迁移中添加 t.invitable：

create_table :users do
  ...
    ## Invitable
    t.string   :invitation_token
    t.datetime :invitation_created_at
    t.datetime :invitation_sent_at
    t.datetime :invitation_accepted_at
    t.integer  :invitation_limit
    t.integer  :invited_by_id
    t.string   :invited_by_type
  ...
end
add_index :users, :invitation_token, unique: true

对于已经存在的模型，定义一个迁移来添加 devise_invitable：

def change
    add_column :users, :invitation_token, :string
    add_column :users, :invitation_created_at, :datetime
    add_column :users, :invitation_sent_at, :datetime
    add_column :users, :invitation_accepted_at, :datetime
    add_column :users, :invitation_limit, :integer
    add_column :users, :invited_by_id, :integer
    add_column :users, :invited_by_type, :string
    add_index :users, :invitation_token, unique: true
end

如果你之前在 :invitation_token 上使用了 :limit，请移除它：

def up
  change_column :users, :invitation_token, :string, limit: nil
end

def down
  change_column :users, :invitation_token, :string, limit: 60
end

2. 项目的使用说明

模型配置

devise_invitable 添加了一些新的配置选项：

• invite_for：生成的邀请令牌的有效期。默认值为 0，表示邀请不会过期。
• invitation_limit：用户可以发送的邀请数量。默认值为 nil，表示没有限制。
• invite_key：发送邀请时用于检查现有用户的键。
• validate_on_invite：在实际邀请之前强制记录有效。
• resend_invitation：如果用户处于邀请状态，重新发送邀请。默认启用。
• invited_by_class_name：邀请模型的类名。如果为 nil，则使用多态关联。
• invited_by_foreign_key：邀请模型的外键。
• invited_by_counter_cache：用于 counter_cache 列的列名。
• allow_insecure_sign_in_after_accept：用户设置密码后自动登录。默认启用。
• require_password_on_accepting：用户接受邀请时需要设置密码。默认启用。

配置视图

所有视图都打包在 gem 中。如果你想自定义视图，可以使用以下生成器将所有视图复制到你的应用程序中：

rails generate devise_invitable:views

你还可以使用生成器生成作用域视图：

rails generate devise_invitable:views users

然后在 config/initializers/devise.rb 中启用作用域视图：

config.scoped_views = true

配置控制器

要更改控制器的行为，创建一个继承自 Devise::InvitationsController 的控制器。可用的方法有：new、create、edit 和 update。

例如：

class Users::InvitationsController < Devise::InvitationsController
  def update
    if some_condition
      redirect_to root_path
    else
      super
    end
  end
end

然后在 routes.rb 中指定使用你的控制器：

devise_for :users, controllers: { invitations: 'users/invitations' }

确保生成视图并将其放入生成的控制器中。

3. 项目API使用文档

邀请用户

Devise::InvitationsController#create 方法用于发送邀请。默认情况下，只允许传递认证键（如 email）。

接受邀请

Devise::InvitationsController#update 方法用于接受邀请。默认情况下，允许传递 invitation_token、password 和 password_confirmation。

4. 项目安装方式

自动安装

通过运行以下命令自动安装：

rails generate devise_invitable:install

手动安装

手动安装需要按照以下步骤进行配置：

1. 在模型中添加 :invitable。
2. 在迁移文件中添加相关字段。
3. 配置 devise.rb 文件中的选项。

通过以上步骤，你可以成功安装并使用 devise_invitable 扩展 Devise 的功能。