recorder

2025-08-12 23:59:32 +08:00
parent ffe1677630
commit 01c73efb1e
20 changed files with 6125 additions and 2 deletions
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -0,0 +1,507 @@
+# think-plugs-recorder 插件设计文档
+
+## 1. 功能需求分析
+
+### 1.1 项目概述
+think-plugs-recorder 是一个基于 ThinkAdmin v6.1 的操作记录插件，用于记录用户在系统中的各种操作行为，提供完整的操作日志追踪功能。
+
+### 1.2 核心功能需求
+
+#### 1.2.1 操作记录功能
+- 记录用户的读取操作
+- 记录用户的自定义操作
+- 支持记录操作数据的类型和ID
+- 支持记录关联数据的类型和ID
+
+#### 1.2.2 记录字段要求
+1. **操作类型** (operation_type): 如 create, read, update, delete, custom 等
+2. **操作说明** (operation_desc): 具体的操作描述
+3. **用户ID** (user_id): 操作用户的唯一标识
+4. **用户昵称** (user_nickname): 操作用户的显示名称
+5. **操作时间** (operation_time): 操作发生的时间戳
+6. **当前操作数据类型** (data_type): 如 user, order, product 等
+7. **当前操作数据ID** (data_id): 具体数据记录的ID
+8. **关联数据类型** (related_type): 关联数据的类型（可选）
+9. **关联数据ID** (related_id): 关联数据的ID（可选）
+
+#### 1.2.3 功能扩展需求
+- 支持批量记录操作
+- 支持按多种条件查询操作记录
+- 支持操作记录的导出功能
+- 支持自定义操作类型配置
+- 支持敏感操作的特殊标记
+
+### 1.3 非功能性需求
+- **性能要求**: 记录操作不应影响主业务性能
+- **存储要求**: 支持大量历史记录存储
+- **安全要求**: 操作记录不可被随意修改或删除
+- **可维护性**: 提供清晰的接口和配置选项
+
+## 2. 数据库设计
+
+### 2.1 主要数据表设计
+
+#### 2.1.1 操作记录表 (jl_recorder_log)
+
+```sql
+CREATE TABLE `jl_recorder_log` (
+  `id` bigint(20) unsigned NOT NULL AUTO_INCREMENT COMMENT '记录ID',
+  `operation_type` varchar(50) NOT NULL DEFAULT '' COMMENT '操作类型',
+  `operation_desc` varchar(500) NOT NULL DEFAULT '' COMMENT '操作说明',
+  `user_id` bigint(20) unsigned NOT NULL DEFAULT '0' COMMENT '操作用户ID',
+  `user_nickname` varchar(100) NOT NULL DEFAULT '' COMMENT '操作用户昵称',
+  `data_type` varchar(100) NOT NULL DEFAULT '' COMMENT '操作数据类型',
+  `data_id` varchar(100) NOT NULL DEFAULT '' COMMENT '操作数据ID',
+  `related_type` varchar(100) NOT NULL DEFAULT '' COMMENT '关联数据类型',
+  `related_id` varchar(100) NOT NULL DEFAULT '' COMMENT '关联数据ID',
+  `request_method` varchar(10) NOT NULL DEFAULT '' COMMENT '请求方法',
+  `request_url` varchar(500) NOT NULL DEFAULT '' COMMENT '请求URL',
+  `request_ip` varchar(50) NOT NULL DEFAULT '' COMMENT '请求IP',
+  `user_agent` varchar(500) NOT NULL DEFAULT '' COMMENT '用户代理',
+  `extra_data` text COMMENT '额外数据(JSON格式)',
+  `created_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+  `updated_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  KEY `idx_user_id` (`user_id`),
+  KEY `idx_operation_type` (`operation_type`),
+  KEY `idx_data_type_id` (`data_type`, `data_id`),
+  KEY `idx_created_at` (`created_at`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT='操作记录表';
+```
+
+#### 2.1.2 预置操作类型说明
+操作类型直接使用中文字符串，常用的操作类型包括：
+- **创建**: 新增数据记录
+- **读取**: 查看数据详情  
+- **更新**: 修改数据记录
+- **删除**: 删除数据记录
+- **导出**: 导出数据
+- **登录**: 用户登录
+- **登出**: 用户登出
+- **审核**: 审核操作
+- **发布**: 发布操作
+
+### 2.2 索引设计说明
+- `idx_user_id`: 按用户查询操作记录
+- `idx_operation_type`: 按操作类型查询
+- `idx_data_type_id`: 按数据类型和ID查询特定数据的操作记录
+- `idx_created_at`: 按时间范围查询操作记录
+
+## 3. 架构设计
+
+### 3.1 插件架构
+```
+think-plugs-recorder/
+├── composer.json                 # Composer配置
+├── DESIGN.md                    # 设计文档
+├── README.md                    # 使用说明
+├── src/                         # 源码目录
+│   ├── Service.php             # 插件服务类
+│   ├── model/                  # 模型目录
+│   │   └── RecorderLog.php     # 操作记录模型
+│   ├── service/                # 服务目录
+│   │   └── RecorderService.php # 核心服务类
+│   ├── controller/             # 控制器目录 (可选)
+│   │   └── RecorderController.php # 记录管理控制器
+│   ├── middleware/             # 中间件目录
+│   │   └── RecorderMiddleware.php # 操作记录中间件
+│   └── helper/                 # 辅助工具目录
+│       └── ViewHelper.php      # 视图辅助类
+├── stc/                        # 静态资源
+│   └── database/               # 数据库迁移脚本
+│       └── 20241201000001_create_recorder_logs_table.php
+└── view/                       # 视图文件
+    └── recorder/
+        ├── components/             # 视图组件
+        │   ├── record_list.html   # 记录列表组件
+        │   ├── record_item.html   # 记录项组件
+        │   └── record_timeline.html # 时间线组件
+        ├── index.html             # 管理页面
+        └── detail.html            # 详情页面
+```
+
+### 3.2 核心类设计
+
+#### 3.2.1 RecorderService 核心服务类
+```php
+<?php
+namespace jerryyan\recorder\service;
+
+class RecorderService
+{
+    // 记录操作
+    public function record(array $data): bool;
+    
+    // 批量记录操作
+    public function batchRecord(array $records): bool;
+    
+    // 查询操作记录
+    public function query(array $conditions = []): array;
+    
+    // 获取用户操作记录
+    public function getUserRecords(int $userId, array $conditions = []): array;
+    
+    // 获取数据操作记录
+    public function getDataRecords(string $dataType, string $dataId): array;
+    
+    // 导出操作记录
+    public function export(array $conditions = []): string;
+    
+    // 清理过期记录
+    public function cleanup(int $days = 90): int;
+}
+```
+
+#### 3.2.2 RecorderLog 数据模型
+```php
+<?php
+namespace jerryyan\recorder\model;
+
+class RecorderLog extends \think\admin\Model
+{
+    
+    // 自动时间戳
+    protected $autoWriteTimestamp = true;
+    
+    // 字段类型转换
+    protected $type = [
+        'id' => 'integer',
+        'user_id' => 'integer',
+        'created_at' => 'datetime',
+        'updated_at' => 'datetime',
+    ];
+    
+    // 字段验证规则
+    protected function getRules(): array;
+    
+    
+    // 获取额外数据
+    public function getExtraDataAttr($value): array;
+    
+    // 设置额外数据
+    public function setExtraDataAttr($value): string;
+}
+```
+
+#### 3.2.3 ViewHelper 视图辅助类
+```php
+<?php
+namespace jerryyan\recorder\helper;
+
+class ViewHelper
+{
+    // 获取操作记录数据
+    public static function getRecords(array $conditions = []): array;
+    
+    // 渲染记录列表HTML
+    public static function renderList(array $conditions = [], array $options = []): string;
+    
+    // 渲染记录时间线HTML
+    public static function renderTimeline(array $conditions = [], array $options = []): string;
+    
+    // 渲染单条记录HTML
+    public static function renderItem(array $record, array $options = []): string;
+    
+    // 注册模板函数
+    public static function registerTemplateFunctions(): void;
+}
+```
+
+### 3.3 接口设计
+
+#### 3.3.1 记录接口
+```php
+// 基础记录接口
+RecorderService::record([
+    'operation_type' => '读取',
+    'operation_desc' => '查看用户信息',
+    'data_type' => 'user',
+    'data_id' => '123',
+    'related_type' => 'department',
+    'related_id' => '456'
+]);
+
+// 自动记录当前用户信息
+RecorderService::autoRecord([
+    'operation_type' => '创建',
+    'operation_desc' => '创建新订单',
+    'data_type' => 'order',
+    'data_id' => '789'
+]);
+```
+
+#### 3.3.2 查询接口
+```php
+// 查询用户操作记录
+$records = RecorderService::getUserRecords(123, [
+    'operation_type' => '读取',
+    'start_time' => '2024-01-01',
+    'end_time' => '2024-12-31'
+]);
+
+// 查询数据操作记录
+$records = RecorderService::getDataRecords('user', '123');
+
+// 复杂条件查询
+$records = RecorderService::query([
+    'user_id' => 123,
+    'operation_type' => ['读取', '更新'],
+    'data_type' => 'user',
+    'date_range' => ['2024-01-01', '2024-12-31']
+]);
+```
+
+#### 3.3.3 视图调用接口
+```php
+// 在模板中获取操作记录
+{:recorder_get_records(['data_type' => 'user', 'data_id' => $user_id])}
+
+// 渲染记录列表
+{:recorder_render_list(['user_id' => $user_id], ['limit' => 10])}
+
+// 渲染时间线
+{:recorder_render_timeline(['data_type' => 'order', 'data_id' => $order_id])}
+
+// 渲染单条记录
+{:recorder_render_item($record)}
+```
+
+## 4. 使用方式设计
+
+### 4.1 手动记录
+在业务代码中手动调用记录方法：
+```php
+use jerryyan\recorder\service\RecorderService;
+
+// 在控制器或服务中记录操作
+RecorderService::record([
+    'operation_type' => '读取',
+    'operation_desc' => '查看用户详情',
+    'data_type' => 'user',
+    'data_id' => $userId
+]);
+```
+
+### 4.2 中间件自动记录
+通过中间件自动记录请求操作：
+```php
+// 在应用配置中启用中间件
+'middleware' => [
+    'jerryyan\recorder\middleware\RecorderMiddleware'
+]
+```
+
+### 4.3 模型事件记录
+在模型事件中自动记录CRUD操作：
+```php
+// 在模型中添加事件监听
+protected static function onAfterInsert($model) {
+    RecorderService::autoRecord([
+        'operation_type' => '创建',
+        'operation_desc' => '创建' . $model->getTable() . '记录',
+        'data_type' => $model->getTable(),
+        'data_id' => $model->getPk()
+    ]);
+}
+```
+
+### 4.4 视图模板调用
+在ThinkPHP模板中直接调用操作记录功能：
+
+#### 4.4.1 获取记录数据
+```html
+<!-- 获取用户操作记录 -->
+{assign name="user_records" value=":recorder_get_records(['user_id' => $user_id, 'limit' => 5])" /}
+
+<!-- 获取特定数据的操作记录 -->
+{assign name="data_records" value=":recorder_get_records(['data_type' => 'order', 'data_id' => $order_id])" /}
+
+<!-- 遍历显示记录 -->
+{volist name="user_records" id="record"}
+<div class="record-item">
+    <span class="operation">{$record.operation_type}</span>
+    <span class="desc">{$record.operation_desc}</span>
+    <span class="time">{$record.created_at}</span>
+</div>
+{/volist}
+```
+
+#### 4.4.2 渲染HTML组件
+```html
+<!-- 渲染操作记录列表 -->
+<div class="record-section">
+    <h4>操作记录</h4>
+    {:recorder_render_list(['user_id' => $user_id], ['limit' => 10, 'show_user' => false])}
+</div>
+
+<!-- 渲染时间线样式 -->
+<div class="timeline-section">
+    <h4>操作时间线</h4>
+    {:recorder_render_timeline(['data_type' => 'order', 'data_id' => $order_id], ['theme' => 'vertical'])}
+</div>
+
+<!-- 在用户详情页显示最近操作 -->
+<div class="recent-actions">
+    <h5>最近操作</h5>
+    {:recorder_render_list(['user_id' => $user_id], ['limit' => 3, 'compact' => true])}
+</div>
+```
+
+#### 4.4.3 AJAX异步加载
+```html
+<!-- 异步加载更多记录 -->
+<div id="record-container">
+    <div class="record-list">
+        {:recorder_render_list(['data_type' => 'user', 'data_id' => $user_id], ['limit' => 10])}
+    </div>
+    <button onclick="loadMoreRecords()" class="load-more">加载更多</button>
+</div>
+
+<script>
+function loadMoreRecords() {
+    $.post('/recorder/load_more', {
+        data_type: 'user',
+        data_id: {$user_id},
+        offset: $('.record-item').length
+    }, function(html) {
+        $('.record-list').append(html);
+    });
+}
+</script>
+```
+
+#### 4.4.4 可配置的显示选项
+```html
+<!-- 带配置选项的记录列表 -->
+{assign name="list_options" value="[
+    'limit' => 20,
+    'show_user' => true,
+    'show_ip' => false,
+    'date_format' => 'Y-m-d H:i:s',
+    'theme' => 'card',
+    'show_extra' => false
+]" /}
+
+{:recorder_render_list(['user_id' => $user_id], $list_options)}
+
+<!-- 简洁模式的时间线 -->
+{:recorder_render_timeline(['data_type' => 'project', 'data_id' => $project_id], ['compact' => true, 'limit' => 5])}
+```
+
+## 5. 配置设计
+
+### 5.1 插件配置
+```php
+return [
+    'recorder' => [
+        // 是否启用操作记录
+        'enabled' => true,
+        
+        // 自动记录模式
+        'auto_record' => [
+            'enabled' => true,
+            'exclude_operations' => ['读取'], // 排除的操作类型
+            'exclude_controllers' => [], // 排除的控制器
+        ],
+        
+        // 记录保留天数
+        'retention_days' => 90,
+        
+        // 敏感操作标记
+        'sensitive_operations' => ['删除', '导出'],
+        
+        // 视图组件配置
+        'view' => [
+            'default_limit' => 10,
+            'date_format' => 'Y-m-d H:i:s',
+            'theme' => 'default', // default, card, timeline
+            'show_user' => true,
+            'show_ip' => false,
+            'compact_mode' => false,
+        ]
+    ]
+];
+```
+
+## 6. 安全考虑
+
+### 6.1 数据安全
+- 记录表只允许插入和查询，不允许更新和删除
+- 敏感操作需要特殊权限才能查看
+- 支持数据脱敏显示
+
+### 6.2 性能考虑
+- 异步记录操作日志，不影响主业务
+- 定期清理过期日志
+- 合理的索引设计
+
+### 6.3 权限控制
+- 基于 ThinkAdmin 的权限系统
+- 不同用户只能查看自己的操作记录
+- 管理员可以查看所有用户的操作记录
+
+## 7. 扩展计划
+
+### 7.1 功能扩展
+- 支持操作记录的统计分析
+- 支持异常操作的告警机制
+- 支持操作记录的可视化展示
+
+### 7.2 集成扩展
+- 支持与其他日志系统集成
+- 支持导出到第三方审计系统
+- 支持API接口调用记录
+
+### 7.3 视图功能扩展
+- 支持更多主题样式和布局
+- 支持自定义模板和组件
+- 支持实时刷新和WebSocket推送
+- 支持操作记录的图表统计
+
+## 8. 视图模板函数设计
+
+### 8.1 注册的模板函数
+插件将自动注册以下模板函数供视图调用：
+
+```php
+// 获取操作记录数据
+function recorder_get_records(array $conditions = []): array
+
+// 渲染记录列表
+function recorder_render_list(array $conditions = [], array $options = []): string
+
+// 渲染时间线
+function recorder_render_timeline(array $conditions = [], array $options = []): string
+
+// 渲染单条记录
+function recorder_render_item(array $record, array $options = []): string
+
+// 获取记录统计
+function recorder_get_stats(array $conditions = []): array
+```
+
+### 8.2 可用的显示选项
+```php
+$options = [
+    'limit' => 10,                    // 显示数量限制
+    'show_user' => true,              // 是否显示用户信息
+    'show_ip' => false,               // 是否显示IP地址
+    'show_extra' => false,            // 是否显示额外数据
+    'date_format' => 'Y-m-d H:i:s',   // 日期格式
+    'theme' => 'default',             // 主题样式 (default, card, timeline, compact)
+    'compact' => false,               // 是否紧凑模式
+    'css_class' => '',                // 自定义CSS类
+    'template' => '',                 // 自定义模板文件
+];
+```
+
+### 8.3 视图组件样式
+插件提供多种预置样式主题：
+- **default**: 默认列表样式
+- **card**: 卡片式布局
+- **timeline**: 时间线布局
+- **compact**: 紧凑式布局
+
+---
+
+**注意**: 此设计文档需要在开始编码前经过确认，确保需求理解准确无误。