Metadata-Version: 2.4
Name: ErisPulse-Feedback
Version: 1.1.1
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. 退出反馈组
6. 解散反馈组
```

选择"1"，然后输入反馈组名称，例如"ErisPulse框架清单"。

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

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

在群B中，**由反馈组创建者或管理员**执行：
```
/设置反馈组
```

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

成功后，群B就加入了"ErisPulse框架清单"反馈组。

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

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

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

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

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

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

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

维护者及以上权限可以修改状态：
```
/修改状态
```

选择要修改的反馈并更改状态。状态包括：待处理、处理中、已完成、搁置。

**步骤6：编辑自己的反馈**

用户可以编辑自己提交的反馈（仅待处理状态）：
```
/编辑反馈
```

### 管理功能

#### 配置反馈组

反馈组创建者或管理员可以配置反馈组：
```
/设置反馈组
```

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

#### 退出反馈组

群聊可以退出所属的反馈组：
```
/设置反馈组
```

选择"5. 退出反馈组"。

注意：创建者不能退出反馈组，只能解散。

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

反馈组创建者可以解散反馈组：
```
/设置反馈组
```

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

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

#### 全局管理员命令

全局管理员可以使用隐藏命令：
```
/反馈全局管理
```

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

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

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

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

#### 查看反馈组信息
```
/设置反馈组
```

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

### 权限说明

| 角色 | 创建反馈组 | 添加群聊 | 配置反馈组 | 成员管理 | 退出反馈组 | 解散反馈组 | 修改状态 | 编辑自己反馈 |
|------|-----------|---------|-----------|---------|-----------|-----------|---------|------------|
| 创建者 | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ |
| 管理员 | ❌ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ |
| 维护者 | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ✅ |
| 全局管理员 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 普通用户 | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ✅ |

### 重要提示

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

2. **创建者不能退出反馈组**：创建者只能解散反馈组，或者转移创建者身份后由新创建者操作。

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

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

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

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

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

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

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

10. **编辑反馈限制**：只能编辑自己提交的、状态为"待处理"的反馈。

## 数据结构

### 反馈组数据

```python
{
    "id": "group_1",
    "name": "产品反馈",
    "creator_id": "user123",
    "admin_ids": ["user456"],
    "maintainer_ids": ["user789"],
    "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
}
```

### 状态说明

| 状态 | 说明 |
|------|------|
| pending | 待处理 |
| processing | 处理中 |
| completed | 已完成 |
| rejected | 搁置 |

## 开发

### 项目结构

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