Metadata-Version: 2.4
Name: ErisPulse-Feedback
Version: 1.0.0
Summary: ErisPulse 反馈系统模块
Author-email: wsu2059 <wsu2059@qq.com>
License: MIT
Keywords: erispulse,bot,feedback,module,chatbot
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# ErisPulse-Feedback

ErisPulse 反馈系统模块

## 功能特性

- 反馈提交 - 用户可以提交反馈，选择类别并输入内容
- 反馈列表 - 查看所有反馈及统计信息
- 状态管理 - 修改反馈状态（待处理/处理中/已完成）
- 多群聊支持 - 每个群聊可以独立设置反馈组
- 反馈组管理 - 一个反馈组可以包含多个群聊
- 灵活配置 - 支持自定义类别、超时时间、内容长度等
- 多格式消息 - 支持 HTML、Markdown、纯文本三种消息格式
- 权限控制 - 反馈组创建者自动成为管理员
- 解散反馈组 - 仅反馈组创建者可以解散反馈组
- 数据导出 - 导出反馈数据为 JSON 格式，方便备份和迁移
- 数据导入 - 导入之前导出的 JSON 数据，支持覆盖和合并模式

## 安装

```bash
epsdk install feedback
```

## 配置

在 `config.toml` 中添加以下配置：

```toml
[Feedback]
# 命令配置
commands = ["提交反馈", "反馈列表", "修改状态", "反馈帮助", "设置反馈组"]

# 全局管理员ID列表
global_admins = ["admin_user_1", "admin_user_2"]

# 默认反馈类别
default_categories = ["功能", "优化", "建议", "bug"]

# 超时时间（秒）
timeout = 60

# 内容最大长度
max_content_length = 500

# 反馈ID前缀
id_prefix = "#"

# 存储前缀
storage_prefix = "fb_"
```

### 全局管理员配置

全局管理员拥有最高权限，可以管理所有反馈组。在配置文件中设置 `global_admins` 列表即可。

全局管理员可以使用隐藏命令 `/反馈全局管理` 来执行高级操作：
- 列出所有反馈组
- 重新设定任意反馈组的管理员
- 解散任意反馈组

## 使用说明

### 核心概念

**反馈组**：一个可以包含多个群聊的反馈系统。每个反馈组有自己的配置和数据，与其他反馈组完全隔离。

**反馈组创建者**：创建反馈组的用户，自动成为该反馈组的管理员，拥有以下权限：
- 将其他群加入到该反馈组
- 配置反馈组
- 解散反馈组
- 修改组内任何反馈的状态

**全局管理员**：配置在 `global_admins` 中的用户，拥有最高权限：
- 查看所有反馈组
- 修改任意反馈组的管理员
- 解散任意反馈组
- 拥有所有反馈组创建者权限

### 基本使用流程

#### 场景：多群共享反馈系统

假设你有多个群聊，希望共享一个反馈系统：

**步骤1：在第一个群创建反馈组**

在群A中执行：
```
/设置反馈组
```

系统会显示管理菜单：
```
1. 创建新的反馈组
2. 加入现有反馈组
3. 查看反馈组信息
4. 配置反馈组
5. 解散反馈组
```

选择"1"，然后输入反馈组名称，例如"公司产品反馈"。

创建成功后，系统会显示反馈组ID（如 `group_1`）。

**步骤2：将其他群加入反馈组**

在群B中，**必须由群A的创建者**执行：
```
/设置反馈组
```

选择"2. 加入现有反馈组"，输入反馈组ID `group_1`。

成功后，群B就加入了"公司产品反馈"反馈组。

**步骤3：用户提交反馈**

现在，群A和群B的用户都可以：
```
/提交反馈
```

所有反馈都会存储在同一个反馈组中，在任何群都可以查看。

**步骤4：查看反馈列表**

在群A或群B中：
```
/反馈列表
```

可以看到所有反馈的统计和详情。

**步骤5：修改反馈状态**

只有反馈创建者或反馈组管理员可以修改状态：
```
/修改状态
```

选择要修改的反馈并更改状态。

#### 场景：独立反馈系统

如果某个群需要独立的反馈系统：

在群中执行：
```
/设置反馈组
```

选择"1. 创建新的反馈组"，输入组名即可。

这样该群的数据与其他群完全隔离。

### 管理功能

#### 配置反馈组

反馈组创建者可以配置反馈组：

```
/设置反馈组
```

选择"4. 配置反馈组"，可以选择配置：
1. **反馈类别** - 设置可用的反馈类别（如：功能,优化,建议,bug）
2. **超时时间** - 设置操作超时时间（10-300秒）
3. **内容最大长度** - 设置反馈内容的最大长度（10-2000字）
4. **反馈ID前缀** - 设置反馈ID的前缀（如 #, FB, 等）

#### 解散反馈组（仅创建者可用）

反馈组创建者可以解散反馈组：

```
/设置反馈组
```

选择"5. 解散反馈组"，系统会显示警告信息并要求确认。

注意：解散后，所有反馈数据将被永久删除，无法恢复。

#### 全局管理员命令

全局管理员可以使用隐藏命令：

```
/反馈全局管理
```

系统会显示全局管理员菜单：
```
1. 列出所有反馈组
2. 重新设定组管理员
3. 解散反馈组
```

**列出所有反馈组**：查看系统中所有反馈组的详细信息，包括ID、名称、创建者、管理员、关联群聊数等。

**重新设定组管理员**：修改任意反馈组的管理员列表，第一个ID将成为新的创建者。

**解散反馈组**：解散任意反馈组，需要二次确认。

#### 查看反馈组信息

```
/设置反馈组
```

选择"3. 查看反馈组信息"可查看：
- 反馈组ID和名称
- 管理员列表
- 关联的群聊
- 创建时间
- 当前配置

### 权限说明

| 角色 | 创建反馈组 | 添加群聊 | 配置反馈组 | 解散反馈组 | 修改所有反馈状态 | 修改自己的反馈状态 |
|------|-----------|---------|-----------|-----------|--------------|----------------|
| 反馈组创建者 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 反馈组管理员 | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
| 全局管理员 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 普通用户 | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ |

### 重要提示

1. **只有反馈组创建者才能添加群聊**：如果你想让其他群加入你的反馈组，需要由你（创建者）在那个群里执行加入操作。

2. **一个群只能属于一个反馈组**：如果群已加入反馈组，需要先联系管理员处理（目前不支持退出）。

3. **数据隔离**：不同反馈组的数据完全独立，不会相互影响。

4. **配置可继承**：新创建的反馈组会使用全局配置作为默认值，但创建后可以独立修改。

5. **解散警告**：解散反馈组会永久删除所有数据，请谨慎操作。

6. **隐藏命令**：全局管理员命令不会在帮助中显示，只有知道命令名称的全局管理员才能使用。

7. **全局管理员权限**：全局管理员拥有最高权限，请谨慎配置 global_admins 列表。

8. **数据备份建议**：定期使用导出功能备份数据，特别是在进行重要操作前。

9. **导入数据安全**：导入操作不可撤销，建议在导入前先导出当前数据作为备份。

## 数据结构

### 反馈组数据

```python
{
    "id": "group_1",
    "name": "产品反馈",
    "admin_ids": ["user123"],
    "allowed_groups": ["G001", "G002", "G003"],
    "config": {
        "categories": ["功能", "优化", "建议", "bug"],
        "timeout": 60,
        "max_content_length": 500,
        "id_prefix": "#"
    },
    "created_at": 1234567890
}
```

### 反馈数据

```python
{
    "id": "#1",
    "group_id": "group_1",
    "source_group_id": "G001",
    "user_id": "U001",
    "user_nickname": "张三",
    "category": "功能",
    "content": "希望添加导出功能",
    "status": "pending",
    "timestamp": 1234567890
}
```

## 开发

### 项目结构

```
ErisPulse_Feedback
   ├── __init__.py
   ├── Core.py              # 主模块类
   ├── logic.py             # 业务逻辑（反馈组管理 + 反馈管理）
   ├── templates.py         # 消息模板
   └── registry.py          # 命令注册
```
