PaperTrail 技术文档

本文档旨在帮助用户了解和使用 PaperTrail 项目，内容包括安装指南、使用说明、API 使用文档以及项目安装方式。

1、安装指南

要使用 PaperTrail，请按照以下步骤进行安装：

1. 将 PaperTrail 添加到您的 Gemfile 文件中，并运行 bundle 命令。

   gem 'paper_trail'
   

2. 为您的数据库添加 versions 表：

   bundle exec rails generate paper_trail:install [--with-changes] [--uuid]
   bundle exec rails db:migrate
   

   有关详细信息，请参阅生成器部分。

3. 在您想要跟踪的模型中添加 has_paper_trail 方法。

   class Widget < ActiveRecord::Base
     has_paper_trail
   end
   

4. 如果您的控制器有一个 current_user 方法，您可以通过添加一个控制器回调来轻松跟踪谁负责更改。

   class ApplicationController
     before_action :set_paper_trail_whodunnit
   end
   

2、项目的使用说明

PaperTrail 为模型提供了跟踪更改的功能，以下是一些基本用法：

• 使用 versions 方法获取模型的更改历史。

  widget = Widget.find 42
  widget.versions
  # 返回一个包含 <PaperTrail::Version> 对象的数组
  

• 获取特定版本的详细信息。

  v = widget.versions.last
  v.event # 'update', 'create', 'destroy'
  v.created_at
  v.whodunnit # 负责更改的用户 ID，需要 `set_paper_trail_whodunnit` 回调
  widget = v.reify # 更改前模型的状态（创建事件返回 nil）
  

• PaperTrail 存储了模型更改前的状态，而不是更改后的状态。

  widget = Widget.find 153
  widget.name # 'Doobly'
  
  # 向 Widget 模型添加 has_paper_trail
  
  widget.versions # []
  widget.update name: 'Wotsit'
  widget.versions.last.reify.name # 'Doobly'
  widget.versions.last.event # 'update'
  

3、项目API使用文档

在您声明 has_paper_trail 的模型中，您将获得以下方法：

class Widget < ActiveRecord::Base
  has_paper_trail
end

# 返回此模型的版本数组
widget.versions

# 返回当前版本或 nil（如果它是活动的）
widget.version

# 返回 true 如果此模型是当前的，否则 false（如果是旧版本）
widget.paper_trail.live?

# 返回负责将模型置于当前状态的用户
widget.paper_trail.originator

# 返回在给定时间戳时模型的外观
widget.paper_trail.version_at(timestamp)

# 返回模型的上一个版本
widget.paper_trail.previous_version

# 返回模型的下一个版本
widget.paper_trail.next_version

PaperTrail::Version 实例（只是一个普通的 ActiveRecord 实例）具有以下方法：

# 从此版本恢复项目
version.reify(options = {})

# 从此版本创建一个新项目
version.reify(dup: true)

# 返回负责将项目置于此版本状态的用户
version.paper_trail_originator

# 返回将项目从此版本状态更改的用户
version.terminator
version.whodunnit
version.version_author

# 返回下一个版本
version.next

# 返回前一个版本
version.previous

# 返回此版本在所有版本中的索引
version.index

# 返回导致此版本的事件（创建|更新|删除）
version.event

这只是常见功能的一个示例。请继续阅读以获取更多信息。

4、项目安装方式

请参考上文“安装指南”部分进行项目安装。