# 用户反馈系统 PRD > 产品需求文档 - 定义用户反馈收集与管理的功能需求和验收标准 > > **版本**: v1.0.3 > **模块标识**: `platform_feedback` > **创建日期**: 2025-12-08 > **更新日期**: 2026-01-07 --- ## 📋 背景与目标 ### 背景 用户反馈是产品持续改进的重要信息来源。当前 FFOA 平台缺少统一的用户反馈收集渠道，用户遇到问题或有建议时无法便捷地提交。同时，管理员也缺少集中管理和处理反馈的工具。 ### 目标 1. **便捷反馈** - 用户可以在系统内任何位置快速提交反馈 2. **分类管理** - 支持按类型（问题反馈、功能建议、其他）分类 3. **状态追踪** - 管理员可以管理反馈状态（待处理、处理中、已完成、已关闭） 4. **透明反馈** - 用户可以查看自己提交的反馈及处理进度 5. **多区域支持** - 支持按地域分区管理反馈，区域管理员只管理本区域反馈 ### 边界声明 | 模块 | 职责 | |------|------| | **用户反馈系统** | 反馈的创建、分类、状态管理、查询 | | **用户与组织架构管理** | 提供用户身份信息 | | **通知系统（预留）** | 反馈状态变更通知（后续集成） | ### 模块依赖关系 ``` ┌─────────────────────────────────────────────────────────────────┐ │ platform_feedback (本模块) │ ├─────────────────────────────────────────────────────────────────┤ │ 依赖方（上游） │ │ └── platform_iam：用户身份验证与信息 │ ├─────────────────────────────────────────────────────────────────┤ │ 被依赖方（下游） │ │ └── 暂无 │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## 🏗️ 核心概念 ### 整体架构 ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ 用户端 │ │ ┌─────────────┐ │ │ │ 反馈入口 │ │ │ │ (全局悬浮) │ │ │ └──────┬──────┘ │ │ │ │ │ ▼ │ │ ┌─────────────┐ │ │ │ 反馈表单 │ │ │ │ 类型+内容 │ │ │ └──────┬──────┘ │ │ │ │ ├────────────────────────────────┼─────────────────────────────────────────┤ │ ▼ │ │ 管理端 │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ 反馈列表 │ │ 状态管理 │ │ │ │ 筛选/搜索/排序 │ │ 处理进度追踪 │ │ │ └────────┬────────┘ └────────┬────────┘ │ │ ▼ ▼ │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ 反馈详情 │ │ 管理员备注 │ │ │ │ 查看完整内容 │ │ 内部处理记录 │ │ │ └─────────────────┘ └─────────────────┘ │ └──────────────────────────────────────────────────────────────────────────┘ ``` ### 核心实体 #### Feedback（反馈） ```typescript Feedback { id: UUID // 全局唯一标识 // 反馈内容 type: FeedbackType // 反馈类型 title: string // 反馈标题 content: string // 反馈详细内容 attachments?: string[] // 附件（截图等），存储文件 URL // 上下文信息 pageUrl?: string // 提交时的页面 URL userAgent?: string // 浏览器 User-Agent // 状态管理 status: FeedbackStatus // 处理状态 priority?: FeedbackPriority // 优先级（可选） // 管理员处理 adminNote?: string // 管理员内部备注 adminReply?: string // 管理员回复（对用户可见） assigneeId?: UUID // 指派处理人 resolvedAt?: Date // 解决时间 // 用户信息 userId: UUID // 提交用户 ID // 多区域支持 region: string // 地域标识（CN/US/EU/APAC），从用户 metadata.region 继承 // 审计 createdAt: Date updatedAt: Date deletedAt?: Date // 软删除 } ``` #### 枚举定义 ```typescript // 反馈类型 enum FeedbackType { BUG = 'BUG', // 问题反馈 / Bug 报告 FEATURE = 'FEATURE', // 功能建议 IMPROVEMENT = 'IMPROVEMENT', // 改进建议 OTHER = 'OTHER' // 其他 } // 反馈状态 enum FeedbackStatus { PENDING = 'PENDING', // 待处理 IN_PROGRESS = 'IN_PROGRESS', // 处理中 RESOLVED = 'RESOLVED', // 已解决 CLOSED = 'CLOSED' // 已关闭（不处理） } // 优先级（可选） enum FeedbackPriority { LOW = 'LOW', // 低 MEDIUM = 'MEDIUM', // 中 HIGH = 'HIGH', // 高 URGENT = 'URGENT' // 紧急 } ``` ### 状态流转 ``` ┌──────────┐ ┌──────────────┐ ┌──────────┐ │ PENDING │ ──> │ IN_PROGRESS │ ──> │ RESOLVED │ │ 待处理 │ │ 处理中 │ │ 已解决 │ └──────────┘ └──────────────┘ └──────────┘ │ │ │ │ │ │ ▼ ▼ ▼ ┌────────────────────────────────────────────────┐ │ CLOSED │ │ 已关闭 │ │ （可从任意状态转为 CLOSED，表示不再处理） │ └────────────────────────────────────────────────┘ ``` **状态说明**： | 状态 | 说明 | 允许操作者 | |------|------|------------| | `PENDING` | 新提交，等待管理员处理 | 系统自动（创建时） | | `IN_PROGRESS` | 管理员已开始处理 | 管理员 | | `RESOLVED` | 问题已解决或建议已采纳 | 管理员 | | `CLOSED` | 不处理/无效反馈/重复 | 管理员 | ### 多区域支持 #### Region（地域）说明 反馈记录的 `region` 字段用于标识反馈所属的地域/区域，支持多地域办公场景下的分区管理。 **地域枚举**： ```typescript enum Region { CN = 'CN', // 中国 US = 'US', // 美国 EU = 'EU', // 欧洲 APAC = 'APAC', // 亚太 } ``` #### 来源规则 | 场景 | Region 来源 | |------|-------------| | 用户提交反馈 | 自动继承提交用户的 `metadata.region` 字段 | | 用户无 region | 使用系统默认值（`CN`） | > ⚠️ **约定**：反馈的 `region` 字段**不可手动修改**，始终与提交用户的 `metadata.region` 保持一致。 #### 使用场景 1. **按区域筛选反馈**：管理员可按 `region` 筛选查看特定区域的反馈 2. **区域管理员**：区域管理员只能查看和处理本区域的反馈 3. **区域统计**：按地域维度统计反馈数量、类型分布、响应时效等 4. **区域优先级**：不同区域可配置不同的默认优先级或处理规则 #### 数据权限矩阵 | 角色 | 权限范围 | 说明 | |------|----------|------| | 普通用户 | 仅自己的反馈 | 不受 region 限制 | | 区域管理员 (`FEEDBACK_ADMIN_CN`) | 本区域所有反馈 | 只能管理 `region = 'CN'` 的反馈 | | 区域管理员 (`FEEDBACK_ADMIN_US`) | 本区域所有反馈 | 只能管理 `region = 'US'` 的反馈 | | 全局管理员 (`ADMINISTRATOR`) | 所有区域反馈 | 不受 region 限制 | #### 区域管理员角色定义 为支持多区域管理，可创建区域级别的反馈管理员角色： | 角色编码 | 角色名称 | 权限范围 | |----------|----------|----------| | `FEEDBACK_ADMIN` | 反馈管理员（全局） | 所有区域 | | `FEEDBACK_ADMIN_CN` | 反馈管理员（中国） | 仅 CN 区域 | | `FEEDBACK_ADMIN_US` | 反馈管理员（美国） | 仅 US 区域 | | `FEEDBACK_ADMIN_EU` | 反馈管理员（欧洲） | 仅 EU 区域 | | `FEEDBACK_ADMIN_APAC` | 反馈管理员（亚太） | 仅 APAC 区域 | > 💡 **实现方式**：区域权限控制通过角色编码前缀 `FEEDBACK_ADMIN_` 进行区域划分。 --- ## 👤 用户故事 ### US1: 普通用户提交反馈 **作为** 一个系统用户 **我希望** 能够在任何页面快速提交反馈 **以便于** 我遇到问题或有建议时能够及时反馈给开发团队 **验收标准**： - [ ] 页面右下角有悬浮的反馈入口按钮 - [ ] 点击后弹出反馈表单 - [ ] 表单包含：类型选择、标题、详细描述 - [ ] 支持附加截图 URL（可选） - [ ] 提交成功后显示确认提示 ### US2: 用户查看自己的反馈 **作为** 一个系统用户 **我希望** 能够查看我提交过的反馈列表和处理状态 **以便于** 我了解反馈的处理进度 **验收标准**： - [ ] 在个人中心或反馈入口可查看「我的反馈」 - [ ] 列表显示：标题、类型、状态、提交时间 - [ ] 点击可查看详情，包括管理员回复 ### US3: 管理员查看反馈列表 **作为** 管理员 **我希望** 能够查看所有用户提交的反馈 **以便于** 我了解用户遇到的问题和建议 **验收标准**： - [ ] 有独立的反馈管理页面 - [ ] 支持按状态、类型、时间筛选 - [ ] 支持关键词搜索 - [ ] 列表显示：标题、类型、状态、提交人、提交时间 ### US4: 管理员处理反馈 **作为** 管理员 **我希望** 能够更新反馈状态并添加处理备注 **以便于** 跟踪反馈的处理进度 **验收标准**： - [ ] 可修改反馈状态 - [ ] 可添加管理员备注（内部可见） - [ ] 可添加回复（用户可见） - [ ] 可设置优先级 - [ ] 状态变更记录可追溯 ### US5: 管理员指派处理人 **作为** 管理员 **我希望** 能够将反馈指派给特定的处理人 **以便于** 明确反馈的责任人 **验收标准**： - [ ] 可从用户列表中选择指派人 - [ ] 指派后显示处理人信息 - [ ] 被指派人可在自己的任务列表中看到 ### US6: 区域管理员管理本区域反馈 **作为** 区域管理员（如中国区管理员） **我希望** 只看到和管理本区域用户提交的反馈 **以便于** 专注处理本区域的问题，提高响应效率 **验收标准**： - [ ] 区域管理员登录后，反馈列表默认只显示本区域反馈 - [ ] 无法查看或操作其他区域的反馈 - [ ] 反馈详情页显示所属区域标识 - [ ] 统计数据仅包含本区域数据 ### US7: 全局管理员跨区域管理 **作为** 全局管理员 **我希望** 能够查看和管理所有区域的反馈 **以便于** 进行跨区域的问题协调和统筹管理 **验收标准**： - [ ] 可查看所有区域的反馈 - [ ] 可按区域筛选反馈 - [ ] 可查看跨区域的统计数据 - [ ] 可将反馈指派给任意区域的处理人 --- ## 📦 功能需求 ### F1: 反馈提交 | 功能点 | 优先级 | 状态 | 说明 | |--------|--------|------|------| | F1.1 反馈入口 | P0 | ✅ | 全局悬浮按钮，点击打开反馈表单 | | F1.2 反馈表单 | P0 | ✅ | 类型、标题、内容必填；附件 URL 可选 | | F1.3 自动上下文 | P1 | ✅ | 自动记录当前页面 URL 和浏览器信息 | | F1.4 提交确认 | P0 | ✅ | 提交成功后显示确认提示 | ### F2: 我的反馈 | 功能点 | 优先级 | 状态 | 说明 | |--------|--------|------|------| | F2.1 反馈列表 | P0 | ✅ | 查看自己提交的反馈列表 | | F2.2 反馈详情 | P0 | ✅ | 查看反馈详情和管理员回复 | | F2.3 状态筛选 | P1 | ✅ | 按状态筛选自己的反馈 | ### F3: 反馈管理（管理员） | 功能点 | 优先级 | 状态 | 说明 | |--------|--------|------|------| | F3.1 反馈列表 | P0 | ✅ | 查看所有反馈，支持筛选和搜索 | | F3.2 反馈详情 | P0 | ✅ | 查看反馈完整内容和上下文信息 | | F3.3 状态管理 | P0 | ✅ | 更新反馈状态 | | F3.4 管理员备注 | P0 | ✅ | 添加内部备注 | | F3.5 用户回复 | P1 | ✅ | 添加对用户可见的回复 | | F3.6 优先级设置 | P1 | ✅ | 设置反馈优先级 | | F3.7 指派处理人 | P2 | ✅ | 指派反馈处理人 | | F3.8 批量操作 | P2 | ✅ | 批量更新状态 | ### F4: 统计分析（后续规划） | 功能点 | 优先级 | 状态 | 说明 | |--------|--------|------|------| | F4.1 反馈统计 | P2 | ✅ | 按类型、状态统计反馈数量 | | F4.2 趋势分析 | P3 | 📋 | 反馈数量趋势图 | | F4.3 响应时效 | P3 | ✅ | 平均处理时长统计 | --- ## 🔌 API 端点概览 ### 用户端接口 | 方法 | 路径 | 说明 | 权限 | |------|------|------|------| | `POST` | `/feedbacks` | 提交反馈 | 登录用户 | | `GET` | `/feedbacks/my` | 获取我的反馈列表 | 登录用户 | | `GET` | `/feedbacks/my/:id` | 获取我的反馈详情 | 登录用户 | ### 管理端接口 | 方法 | 路径 | 说明 | 权限 | |------|------|------|------| | `GET` | `/feedbacks` | 获取所有反馈列表 | `feedback:read` | | `GET` | `/feedbacks/:id` | 获取反馈详情 | `feedback:read` | | `PATCH` | `/feedbacks/:id/status` | 更新反馈状态 | `feedback:update` | | `PATCH` | `/feedbacks/:id` | 更新反馈信息（备注、回复、优先级、指派人） | `feedback:update` | | `DELETE` | `/feedbacks/:id` | 删除反馈（软删除） | `feedback:delete` | ### 统计接口（已实现） | 方法 | 路径 | 说明 | 权限 | |------|------|------|------| | `GET` | `/feedbacks/stats` | 获取反馈统计 | `feedback:read` | --- ## 🔐 权限设计 ### 权限点 | 权限点 | 说明 | |--------|------| | `feedback:read` | 查看所有反馈（管理员） | | `feedback:update` | 更新反馈状态和信息（管理员） | | `feedback:delete` | 删除反馈（管理员） | ### 数据权限 | 角色 | 权限范围 | |------|----------| | 普通用户 | 只能查看和提交自己的反馈 | | 管理员（`ADMINISTRATOR`） | 查看和管理所有反馈 | | 反馈管理员（`FEEDBACK_ADMIN`） | 查看和管理所有反馈（可选角色） | --- ## 🎨 界面设计 ### 反馈入口 - **位置**：页面右下角悬浮按钮 - **图标**：消息/反馈图标 - **样式**：圆形按钮，hover 时展开显示文字「反馈」 ### 反馈表单（Modal） ``` ┌─────────────────────────────────────┐ │ 提交反馈 ✕ │ ├─────────────────────────────────────┤ │ │ │ 反馈类型 * │ │ ┌─────────────────────────────┐ │ │ │ ○ 问题反馈 ○ 功能建议 │ │ │ │ ○ 改进建议 ○ 其他 │ │ │ └─────────────────────────────┘ │ │ │ │ 标题 * │ │ ┌─────────────────────────────┐ │ │ │ │ │ │ └─────────────────────────────┘ │ │ │ │ 详细描述 * │ │ ┌─────────────────────────────┐ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └─────────────────────────────┘ │ │ │ │ 附件 URL（可选） │ │ ┌─────────────────────────────┐ │ │ │ 请输入附件 URL │ │ │ └─────────────────────────────┘ │ │ │ │ ┌────────┐ ┌────────┐ │ │ │ 取消 │ │ 提交 │ │ │ └────────┘ └────────┘ │ └─────────────────────────────────────┘ ``` ### 管理端列表 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 反馈管理 │ ├─────────────────────────────────────────────────────────────────┤ │ ┌────────┐ ┌──────────┐ ┌──────────┐ ┌─────────────────┐ │ │ │ 全部 ▼ │ │ 待处理 ▼ │ │ 问题反馈 │ │ 🔍 搜索关键词 │ │ │ └────────┘ └──────────┘ └──────────┘ └─────────────────┘ │ ├─────────────────────────────────────────────────────────────────┤ │ □ │ 标题 │ 类型 │ 状态 │ 提交人 │ 提交时间 │ ├─────────────────────────────────────────────────────────────────┤ │ □ │ 登录页面无响应 │ 问题反馈 │ 待处理 │ 张三 │ 2025-12-08 │ │ □ │ 建议增加暗色模式│ 功能建议 │ 处理中 │ 李四 │ 2025-12-07 │ │ □ │ 表格排序功能异常│ 问题反馈 │ 已解决 │ 王五 │ 2025-12-06 │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## 🔒 非功能需求 ### 性能要求 | 场景 | 要求 | |------|------| | 反馈列表查询 | < 200ms | | 反馈提交 | < 500ms | | 附件 URL 提交 | < 500ms（后端仅记录 URL） | ### 安全要求 | 要求 | 说明 | |------|------| | 内容转义 | 后端不做内容过滤，展示层需转义 | | 权限控制 | 用户只能查看自己的反馈 | | 附件校验 | 仅校验 URL 格式与数量 | ### 数据保留 | 数据类型 | 保留策略 | |----------|----------| | 反馈记录 | 永久保留（软删除） | | 附件 URL | 随反馈一起保留 | --- ## ✅ 验收标准 ### 用户端 - [ ] 页面右下角有反馈入口悬浮按钮 - [ ] 点击按钮可打开反馈表单弹窗 - [ ] 表单可选择反馈类型（问题反馈/功能建议/改进建议/其他） - [ ] 表单必填项验证正常（类型、标题、内容） - [ ] 支持附加截图 URL - [ ] 提交成功后有确认提示 - [ ] 可查看自己提交的反馈列表 - [ ] 可查看反馈详情和管理员回复 ### 管理端 - [ ] 可查看所有反馈列表 - [ ] 支持按状态、类型筛选 - [ ] 支持关键词搜索 - [ ] 可查看反馈详情（包括页面 URL、浏览器信息） - [ ] 可更新反馈状态（待处理 → 处理中 → 已解决/已关闭） - [ ] 可添加管理员备注（用户不可见） - [ ] 可添加回复（用户可见） - [ ] 可设置优先级 - [ ] 可指派处理人 ### 权限控制 - [ ] 普通用户只能查看自己的反馈 - [ ] 管理员可以查看和管理所有反馈 - [ ] 管理接口有权限守卫 --- ## ⚠️ 典型错误码 ### 错误码命名规范 - **命名空间**：`FEEDBACK_` 前缀（`platform_feedback` 模块专属） - **格式**：`FEEDBACK_{RESOURCE}_{ERROR_TYPE}`，全大写下划线分隔 ### 错误码列表 | 错误码 | HTTP 状态 | 场景 | 说明 | |--------|----------|------|------| | `FEEDBACK_NOT_FOUND` | 404 | 查看/更新/删除 | 反馈不存在或已删除 | | `FEEDBACK_ACCESS_DENIED` | 403 | 查看/更新/删除 | 无权操作该反馈（区域不匹配或非本人） | | `FEEDBACK_INVALID_STATUS_TRANSITION` | 400 | 状态变更 | 无效的状态流转 | | `FEEDBACK_ATTACHMENTS_EXCEED_LIMIT` | 400 | 创建反馈 | 附件数量超过限制（最多 5 个） | | `FEEDBACK_BATCH_LIMIT_EXCEEDED` | 400 | 批量操作 | 批量操作数量超过限制（最多 100 个） | --- ## 📅 里程碑 | 阶段 | 内容 | 状态 | |------|------|------| | Phase 1 | 基础反馈提交 + 我的反馈 | ✅ 已完成 | | Phase 2 | 管理员列表 + 状态管理 | ✅ 已完成 | | Phase 3 | 优先级 + 指派处理人 | ✅ 已完成 | | Phase 4 | 统计分析 | ✅ 已完成 | | Phase 5 | 通知集成 | 📋 待规划 | --- ## 📚 相关文档 - [架构设计文档](./03-architecture.md) - 系统架构、数据模型、核心设计决策 - [API 接口文档](./07-api.md) - 完整的接口定义和示例 - [用户与组织架构管理](../organization/01-prd.md) - 用户身份依赖 --- **最后更新**: 2026-01-07 **版本**: v1.0.3