# Flarum-recommendations

**Repository Path**: lcoy/flarum-recommendations

## Basic Information

- **Project Name**: Flarum-recommendations
- **Description**: 推荐系统扩展，基于 FoF Forum Widgets Core 框架构建，在论坛首页以三栏小部件形式展示推荐帖子、最新帖子和热门浏览帖子。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-03
- **Last Updated**: 2026-06-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Recommendations

[中文文档](#中文说明) | [English](#english)

---

## English

A Flarum 2.0 extension that adds a three-column recommendation widget to the forum homepage, built on the [FoF Forum Widgets Core](https://github.com/FriendsOfFlarum/forum-widgets-core) framework.

### Features

- **Recommended** — HN/Reddit hotness algorithm with stochastic sampling for diversity
- **Latest** — Time-window filtered, low-engagement posts to surface undiscovered content
- **Most Viewed** — View-count ranked with configurable threshold and randomization

Each item displays: **avatar + title + metadata** (comments / time / views). Clickable to the discussion page.

### Requirements

| Package | Type | Notes |
|---|---|---|
| `flarum/core` | **Required** | ^2.0 |
| `fof/forum-widgets-core` | **Required** | ^2.0 |
| `fof/discussion-views` | Recommended | Provides `view_count` data. Without it, Most Viewed column has no data to rank |
| Redis cache | Recommended | Better caching performance. Falls back to file cache |

### Installation

```bash
composer require lcoy/recommendations
php flarum cache:clear
```

For view tracking support:

```bash
composer require fof/discussion-views
```

### Admin Settings

8 configurable parameters under **Admin → Forum Widgets → Recommendations**:

| Setting | Default | Description |
|---|---|---|
| Recommended Count | 5 | Items shown in Recommended column |
| Gravity Factor | 1.5 | Time-decay strength (higher = newer posts favored) |
| Latest Count | 5 | Items shown in Latest column |
| Time Window (days) | 7 | Only show posts within this many days |
| Max Participants | 5 | Only show posts with unique participants ≤ this |
| Most Viewed Count | 5 | Items shown in Most Viewed column |
| Min View Threshold | 0 | Minimum views to enter candidate pool (0 = no limit) |
| Cache TTL (minutes) | 15 | Frontend polling & backend cache interval (0 = disabled) |

### Algorithm

**Recommended (Hotness + Randomization)**

```
engagement = comments × 2.0 + participants × 3.0 + views × 0.05
hours      = max(1, hours since creation)
score      = engagement / (hours + 2)^gravity
```

1. Fetch top 200 candidates from the last 90 days
2. Rank by hotness score
3. Take top N×10 as the random pool
4. Shuffle and pick N items

**Most Viewed (Threshold + Randomization)**

1. Fetch top N×10 by view count (with optional min-views filter)
2. Shuffle and pick N items

### Tech Stack

- Backend: PHP 8.1+, Laravel Cache (Redis recommended)
- Frontend: Mithril.js, Flarum Admin Extender API
- Widget framework: FoF Forum Widgets Core

### License

MIT

---

## 中文说明

基于 [FoF Forum Widgets Core](https://github.com/FriendsOfFlarum/forum-widgets-core) 框架构建的 Flarum 2.0 推荐系统扩展，在论坛首页以三栏小部件形式展示推荐帖子、最新帖子和热门浏览帖子。

### 功能

- **推荐帖子** — HN/Reddit 热度算法 + 随机选取，兼顾质量与多样性
- **最新帖子** — 时间窗口 + 低互动过滤，挖掘尚待发现的新内容
- **热门浏览** — 浏览量门槛 + 随机选取，确保热门内容不重复

每个栏目项展示：**头像 + 标题 + 元数据**（评论数 / 发布时间 / 浏览数），点击可跳转到帖子详情。

### 依赖

| 扩展 | 必要性 | 说明 |
|---|---|---|
| `flarum/core` | **必需** | ^2.0 |
| `fof/forum-widgets-core` | **必需** | ^2.0 |
| `fof/discussion-views` | **推荐** | 提供浏览量数据，未安装时热门栏目无区分度 |
| Redis 缓存 | **推荐** | 更好的缓存性能，未配置时回退到文件缓存 |

### 安装

```bash
composer require lcoy/recommendations
php flarum cache:clear
```

推荐同时安装浏览量追踪扩展：

```bash
composer require fof/discussion-views
```

### 后台设置

8 项可配置参数，位于 **后台 → 论坛小组件 → Recommendations**：

| 设置项 | 默认值 | 说明 |
|---|---|---|
| 推荐帖子展示数量 | 5 | 推荐栏目展示条数 |
| 重力因子 | 1.5 | 热度算法时间衰减强度，值越大新帖权重越高 |
| 最新帖子展示数量 | 5 | 最新栏目展示条数 |
| 时间窗口（天） | 7 | 仅展示此天数内发布的帖子 |
| 最大参与人数 | 5 | 仅展示参与者 ≤ 此值的帖子 |
| 热门浏览展示数量 | 5 | 热门栏目展示条数 |
| 热门浏览最低门槛 | 0 | 浏览量需 ≥ 此值才进入候选池，0 不设限 |
| 数据刷新间隔（分钟） | 15 | 前端轮询与后端缓存时长，0 关闭缓存 |

### 算法详解

**推荐算法（热度 + 随机化）**

```
engagement = 评论数 × 2.0 + 参与人数 × 3.0 + 浏览量 × 0.05
hours      = max(1, 距发布小时数)
score      = engagement / (hours + 2)^gravity
```

1. 从近 90 天帖子中取 200 条候选
2. 按热度分降序排列
3. 取前 N×10 条组成随机池
4. shuffle 后选取前 N 条

**热门浏览随机化**

1. 按浏览量降序取前 N×10 条（可设最低门槛过滤）
2. shuffle 后取前 N 条

### 技术架构

```
lcoy/recommendations
├── src/
│   ├── Api/Controller/
│   │   └── ListRecommendationsController.php  # API 控制器
│   └── Service/
│       └── HotnessCalculator.php              # 热度算法
├── js/
│   ├── dist/                                  # 构建产物（已提交）
│   └── src/
│       ├── admin/
│       │   └── extendSettingsPage.js          # 后台设置注册
│       └── common/
│           ├── components/
│           │   ├── RecommendationsWidget.js       # 前台小部件
│           │   └── RecommendationsWidgetAdmin.js  # 后台小部件注册
│           └── registerWidget.js                  # 小部件注册
├── less/
│   └── forum.less                            # 前台样式（含移动端适配）
├── locale/
│   ├── zh.yml                                # 中文翻译
│   └── en.yml                                # 英文翻译
├── extend.php                                # 扩展入口
└── composer.json
```

### 许可证

MIT