# 工单系统模块（Ticket System）

> **负责人**: FFOA 开发团队  
> **模块标识**: `platform_tickets`  
> **状态**: 🚧 开发中  
> **最后更新**: 2025-12-25

---

## 📋 文档导航

| 文档 | 状态 | 最后更新 |
|------|------|---------|
| [产品需求文档](./01-prd.md) | ✅ | 2025-12-11 |
| [架构设计](./03-architecture.md) | ✅ | 2025-12-11 |
| [API 接口文档](./07-api.md) | ✅ | 2025-12-11 |
| [开发路线图](./10-roadmap.md) | ✅ | 2025-12-25 |

**状态说明**:
- ✅ Completed/Approved - 已完成并通过评审
- 🚧 In Progress/Draft - 编写中
- ❌ Not Started - 未开始
- 📝 Need Update - 需要更新

---

## 📌 概述

工单系统是统一的服务请求管理平台，支持工单创建、自动分配、状态管理、协作沟通和数据分析。

### 核心功能

1. **工单创建** - 任何服务都可以提交工单请求
2. **自动分配** - 基于规则的智能工单分配
3. **状态管理** - 完整的工单生命周期管理
4. **协作沟通** - 评论、附件、@提醒、关注
5. **SLA 管理** - 服务等级协议和超时预警
6. **数据分析** - 工单效率和质量分析
7. **AI 联动** - 与企业智能助手协同，支持对话升级工单

### 业务价值

- **统一入口**: 集中管理所有服务请求
- **高效协作**: 多人协作处理，实时沟通
- **智能分配**: 自动路由到合适的处理人
- **质量保证**: SLA 管理确保服务质量
- **数据驱动**: 统计分析支持决策优化

---

## 🏗️ 技术信息

### 代码位置

- **前端**: `frontend/src/app/tickets/` - 工单管理页面
  - `/tickets/new` - 创建工单
  - `/tickets/list` - 工单列表
  - `/tickets/my` - 我的工单
  - `/tickets/[id]` - 工单详情
  - `/tickets/admin` - 管理后台
- **后端**: `backend/src/modules/tickets/`
  - tickets.controller.ts - 主控制器
  - tickets.service.ts - 工单服务
  - assign.service.ts - 分配服务
  - stats.service.ts - 统计服务
  - category.service.ts - 分类管理
  - group.service.ts - 处理组管理
- **数据库**: `platform_tickets` Schema

### API 端点

- **Base URL**: `/api/v1/tickets`
- **权限前缀**: `tickets:`
- **主要接口**: 
  - 工单管理: CRUD 操作
  - 状态管理: 状态流转
  - 分配管理: 自动分配、转派、认领
  - 协作功能: 评论、附件、关注
  - 统计分析: 多维度数据分析
  - 管理后台: 分类、处理组、SLA 配置
- **总计**: 30+ 接口

### 技术栈

- **前端**: Next.js 14 + TypeScript + Tailwind CSS
- **后端**: NestJS + Prisma + PostgreSQL
- **存储**: PostgreSQL（platform_tickets Schema）
- **通知**: 集成通知引擎

---

## 🔗 相关模块

### 核心依赖

- [组织架构](../organization/README.md) - 用户、部门信息
- [通知引擎](../notification-engine/README.md) - 工单状态变更通知

### 业务关联

- [企业智能助手](../ai-assistant/README.md) - AI 对话升级工单
- [审批引擎](../approval-engine/README.md) - 工单可触发审批流程
- [用户反馈](../feedback/README.md) - 类似的用户交互模式

---

## 🚀 快速开始

### 工单创建示例

```typescript
// 1. 创建工单
const ticket = await ticketService.create({
  title: '电脑无法开机',
  description: '今天早上电脑突然无法开机，电源灯不亮',
  categoryId: 'it-support',
  priority: 'HIGH',
  attachments: ['screenshot.png'],
});

// 2. 分配工单（自动或手动）
await ticketService.assign(ticket.id, {
  assigneeId: 'user-123',
  comment: '请尽快处理',
});

// 3. 更新工单状态
await ticketService.updateStatus(ticket.id, 'IN_PROGRESS', {
  comment: '已收到，正在处理中',
});

// 4. 添加评论
await ticketService.addComment(ticket.id, {
  content: '已更换电源适配器，请确认是否正常',
  attachments: ['repair-photo.jpg'],
});

// 5. 完成工单
await ticketService.complete(ticket.id, {
  resolution: '更换电源适配器后恢复正常',
  satisfactionSurvey: true,
});
```

### 工单编号规则

- 格式: `TK-{YYYYMMDD}-{序号}`
- 示例: `TK-20251225-001`
- 自动生成，保证唯一性

---

## 📊 工单生命周期

```
NEW (新建)
  ↓
ASSIGNED (已分配)
  ↓
IN_PROGRESS (处理中)
  ↓
PENDING (等待中) ←→ IN_PROGRESS
  ↓
RESOLVED (已解决)
  ↓
CLOSED (已关闭)
  
其他状态:
- CANCELLED (已取消)
- REJECTED (已拒绝)
```

---

## 🧪 测试

### E2E 测试覆盖

按 `docs/modules/tickets/10-e2e-test-spec.md` 执行（Agent + Playwright MCP）。

- ✅ 工单 CRUD（43个测试用例）
- ✅ 状态流转
- ✅ 自动分配（轮询、负载均衡）
- ✅ 评论系统
- ✅ 关注功能
- ✅ 统计分析
- ✅ 满意度评价

详见架构文档中的测试策略部分。

---

## 📚 详细文档

- [产品需求文档](./01-prd.md) - 完整功能需求、业务场景
- [架构设计](./03-architecture.md) - 技术架构、数据模型、状态机
- [API 接口文档](./07-api.md) - 完整 API 定义、请求响应示例
- [开发路线图](./10-roadmap.md) - 开发进度、里程碑、待办事项

---

## 🎯 开发状态

### 已完成功能（Phase 1-3, 5）

- ✅ **基础工单管理** - 工单 CRUD、编号生成、状态管理
- ✅ **分类与处理组** - 分类管理、处理组管理、成员管理
- ✅ **自动分配** - 轮询分配、负载均衡分配、手动分配
- ✅ **协作沟通** - 评论、附件、关注、活动日志
- ✅ **统计分析** - 多维度统计、趋势分析、满意度评价
- ✅ **前端页面** - 创建、列表、详情、管理后台
- ✅ **E2E 测试** - 43个测试用例全部通过

### 开发中功能（Phase 4）

- 📋 **SLA 管理** - 服务等级协议、超时预警、自动升级

### 待规划功能（Phase 6）

- 📋 工单模板
- 📋 自定义字段
- 📋 知识库集成
- 📋 批量操作
- 📋 与审批引擎集成
- 📋 与 AI 智能助手深度集成
- 📋 多区域/多租户支持

---

## 📊 模块统计

| 指标 | 数量 |
|------|------|
| **API 端点** | 30+ |
| **权限点** | 17个 |
| **工单状态** | 8种 |
| **优先级** | 4种 |
| **E2E 测试** | 43个 |
| **文档行数** | 3,740行 |

---

## 🔐 权限控制

工单系统支持细粒度的权限控制：

- `tickets:create` - 创建工单
- `tickets:read` - 查看工单
- `tickets:update` - 更新工单
- `tickets:delete` - 删除工单
- `tickets:assign` - 分配工单
- `tickets:manage` - 管理权限（分类、处理组、SLA）
- 更多权限详见 API 文档

---

## 👥 贡献者

- **创建者**: FFOA Team
- **维护者**: Backend Team
- **最后更新**: 2025-12-25

---

**创建时间**: 2025-12-11  
**更新时间**: 2025-12-25  
**状态**: 🚧 开发中（Phase 4）  
**版本**: v1.3