incuna-groups 4.1.0

# `incuna-groups` [](https://travis-ci.org/incuna/incuna-groups)

一个可扩展的Django应用，提供论坛功能。
- 管理员可以创建讨论组。
- 用户可以在组中创建讨论，并对这些讨论进行评论。
- 用户还可以订阅组和/或讨论以接收通知，并通过对通知电子邮件进行回复来发布回复。

## 安装

`incuna-groups` 在PyPI上，所以您可以使用 `pip install incuna-groups` 进行安装。将 `groups` 和 `pagination`（用于 `incuna-pagination` 的依赖项）添加到您的 `INSTALLED_APPS` 中。

此项目包含迁移，所以在使用之前请运行 `python manage.py migrate`。

## 使用

`incuna-groups` 是自包含的 - 它提供模型、视图和模板。目前，它不提供样式或REST API。

一些简单的自定义通过 `AppConfig`（默认为 `groups.apps.GroupsConfig`）公开，并且模板可以轻松覆盖。

每个页面模板都有一个 `base` 版本，页面模板直接 `extends`，这意味着您可以替换页面模板，同时仍然使用所有原始的块和其他HTML。例如，`discussion_thread.html` 除了扩展 `discussion_thread_base.html` 什么都不做。您可以覆盖 `discussion_thread.html`，以相同的方式扩展 `discussion_thread_base.html`，并更改单个块的内容，而无需复制和粘贴整个讨论线程模板并从中修改。

### 模型

有三个主要模型围绕一切旋转，其中一个是多态的，易于扩展。

- `组`: 包含任意数量讨论的组，类似于论坛版块。在 Django 管理界面创建，并包含用户添加的讨论线程。组可以标记为私有，这种情况下用户必须申请加入才能阅读或发布任何评论。组也可以有管理员，他们有权删除或编辑其他用户的评论。用户可以订阅一个组，这样他们就会收到该组中创建的任何讨论或评论的提醒。
- `讨论`: 单个讨论线程，至少有一个评论（通常是初始评论）。由用户创建。用户可以对讨论发表评论并订阅讨论。如果用户已经订阅了讨论的父组，他们可以取消订阅该讨论，这将在内部导致讨论对该用户被视为“忽略”，他们将不会收到任何通知。
- `BaseComment`: `Comment` 的 `django-polymorphic` 基类。本身不执行任何操作，但用于测试和引用任意不同类型的评论。`BaseComment` 的子类由与讨论相关的视图拾取。它包含一些子类
* `TextComment`: 带有文本内容的评论 - 一个完全普通的消息。
* `FileComment`: 包含上传文件的评论。

三个主要模型每个都有一个自定义查询集（然后由其管理器使用），包含几个附加方法。其中大多数允许获取最近活跃的项目或访问与这三个实例之一的任何实例相关的组/讨论/评论。这些查询集和方法可以在 `managers.py` 中找到。

### 视图和管理页面

有许多不同的视图组合在一起以使论坛工作。

- `组`
* 由 `admin.GroupAdmin` 创建 - 在 Django 管理界面
* 由 `views.groups.GroupList` 列出
* 由 `views.groups.GroupDetail` 详细说明 - 实现为 `ListView` 用于 `Discussion`s，以显示组的内容。
* 由 `views.subscriptions.GroupSubscribe` 订阅
- `讨论`
* 由 `admin.DiscussionAdmin` 创建 - 在 Django 管理界面
* 由 `views.discussions.DiscussionCreate` 创建 - 此操作还创建了 `Discussion` 的第一个评论，目前是一个 `TextComment`。
* 由 `views.groups.GroupDetail` 列出
* 由 `views.discussions.DiscussionThread` 详细说明 - 实现为来自 `views._helpers` 的 `CommentPostView`，允许人们通过讨论页面本身进行回复。
* 由 `views.subscriptions.DiscussionSubscribe` 订阅
- `评论`
* 由 `views._helpers.CommentPostView` 创建 - 这是一个基类，既可以创建评论，也可以向相关人士发送电子邮件通知。
* 由 `views.discussions.DiscussionThread` 创建 - 讨论线程页面提供了一个内联回复表单，用于提交 `TextComment`s。
* 由 `views.comments.CommentUploadFile` 创建 - 用于上传 `FileComment`s 的单独页面。
* 由 `views.comments.CommentPostByEmail` 创建 - 一个适合通过 Mailgun 接收电子邮件回复的端点。
* 由 `views.discussions.DiscussionThread` 列出
* 由 `views.comments.CommentDelete` 删除 - 一个评论提供了一个“删除”按钮，这将将其存档并隐藏其内容。

## 功能说明

### `AppConfig`

`incuna-groups` 有一个 `AppConfig`，位于 `apps.py` 中，允许轻松自定义其一些行为。有关 `AppConfig` 的文档（及其使用）在此：https://docs.django.ac.cn/en/1.8/ref/applications/#for-application-users

`AppConfig`公开
- `default_within_days` - 一些模型管理器的 `within_days` 方法的默认参数，这些方法返回在指定时间段内发布或回复的项目。
- `new_comment_subject` 和 `new_discussion_subject` - 通知电子邮件的主题。每个主题都将分别使用评论所在的 `{discussion}` 或讨论所属的 `{group}` 进行格式化。
`- `group_admin_class_path` 和 `discussion_admin_class_path` - 这些允许您通过插入不同的 `ModelAdmin` 类来覆盖 `incuna-groups` 的管理行为。这些可能基于或不基于 `admin.py` 中的现有管理类。

### 邮件通知

每当在组中创建讨论时，订阅该组的人都会收到电子邮件通知。每当对讨论发表评论时，订阅该讨论或其父组的人也会收到电子邮件通知。

电子邮件模板位于 `templates/groups/emails` 中。讨论通知由 `views.discussions.DiscussionCreate` 发送；评论通知由 `CommentEmailMixin` 的子类（`CommentPostView`、`DiscussionThread` 和 `CommentUploadFile`）发送。

### 邮件回复

用户可以通过回复通知电子邮件来回复讨论或评论。通过一个端点（`/groups/reply/`，提供 `CommentPostByEmail` 视图）实现电子邮件回复，该端点接受包含表示电子邮件的 JSON 内容的 POST 请求。库设置为与 [Mailgun](https://www.mailgun.com/) 路由一起工作。

用户和讨论通过一个定制的 `Reply-To` 报头进行识别，该报头包含 `reply-{uuid}@{domain}` 的回复地址。UUID 通过安全地签名包含用户和讨论 PK 的字典生成，并在端点接收到 Mailgun 的 JSON 消息时进行解包。Mailgun 提供了一个 `stripped-text` 字段，它会从电子邮件内容中删除引号和签名，因此用户无需以特定方式回复，我们也不需要自己处理这些操作。

Mailgun 的粗略 API 描述可以在[这里](http://blog.mailgun.com/handle-incoming-emails-like-a-pro-mailgun-api-2-0/)找到。POST 和文件数据将分别位于 `request.POST` 和 `request.FILES` 中。

有一些需要注意的地方

- `/groups/reply/` 端点 _具有尾部斜杠_。确保在任何 Mailgun 路由目标中都包含此斜杠，否则您将收到一系列 HTTP301。
- 如果您使用 `incuna_auth.LoginRequiredMiddleware`，请确保将 `/groups/reply/` 添加到 `LOGIN_EXEMPT_URLS` 中，以避免更多 301。
- `CommentPostByEmail` 视图在 `dispatch()` 方法上使用 `@csrf_exempt` 装饰器来避免与 CSRF 相关的 HTTP403 错误。如果您扩展该类，请确保添加 CSRF 免除。

### 覆盖管理类

`Group` 和 `Discussion` 都有自定义的管理类，在 `admin.py` 中定义。这两个都可以通过 `AppConfig`（参见上面）轻松替换。`AppConfig` 会为您注册这些管理类，因此不要自己调用 `admin.site.register`。