Hua.Todo/docs/project/研发工单-v1.3.0/03-01-会议数据模型与API.md

# 研发工单 v1.3.0 - 03-01 会议数据模型与 API

> 父工单：[03-会议任务拆分](./03-会议任务拆分.md)

---

## 一、目标

为"会议任务拆分"功能建立数据模型：扩展 `TaskEntity` 新增 `TaskType` 枚举和 `MeetingNotes`/`AudioDuration` 字段，定义完整的会议相关 API 端点与 DTO，完成数据库迁移。

## 二、范围

**包含**：
- 新增 `TaskType` 枚举（Normal / Meeting）
- `TaskEntity` 新增字段：`TaskType`、`MeetingNotes`、`AudioDuration`
- EF Core 数据库迁移
- DTO 扩展：`CreateTaskDto`、`UpdateTaskDto`、`TaskDto` 新增对应字段
- 会议 API 端点骨架：`MeetingController` + `MeetingService`
- API 路径：`/api/meeting/{taskId}/transcribe`、`/api/meeting/{taskId}/notes`
- 会议相关 DTO 定义：`TranscribeRequest`、`TranscribeResponse`、`MeetingNotesRequest`

**不包含**：
- AI 拆分逻辑（由 03-03 完成）
- STT 转写实现（由 03-02 完成）
- 前端组件（由 03-04 完成）

## 三、前置条件

| 条件 | 说明 |
|---|---|
| Hua.Todo v1.2.0 | 基础 Task CRUD 能力、父子任务、DynamicApi 中间件 |
| ABP 基类迁移（可选） | 若工单 09（v1.2.0）已完成，TaskEntity 已转为 ABP 基类，字段新增方式不同 |

## 四、详细规格

### 4.1 TaskType 枚举

```csharp
/// <summary>待办项类型，区分普通待办项与会议</summary>
public enum TaskType
{
    /// <summary>普通待办项（默认）</summary>
    Normal = 0,
    /// <summary>会议：包含录音/纪要，支持 AI 任务拆分</summary>
    Meeting = 1
}
```

文件位置：`src/Hua.Todo.Core/Entities/TaskType.cs`

### 4.2 TaskEntity 新增字段

```csharp
/// <summary>待办项类型</summary>
public TaskType TaskType { get; set; } = TaskType.Normal;

/// <summary>会议纪要/转写文字（仅 Meeting 类型有值）</summary>
[MaxLength(20000)]
public string? MeetingNotes { get; set; }

/// <summary>录音时长（秒），仅 Meeting 类型有值</summary>
public double? AudioDuration { get; set; }
```

### 4.3 EF Core 配置（TodoDbContext.cs）

```csharp
builder.Entity<TaskEntity>(b =>
{
    // ... 现有配置 ...

    b.Property(x => x.TaskType)
        .HasDefaultValue(TaskType.Normal)
        .HasConversion<int>(); // 枚举存为整数

    b.Property(x => x.MeetingNotes)
        .HasMaxLength(20000); // 最多约 20000 字符

    b.Property(x => x.AudioDuration)
        .IsRequired(false);
});
```

### 4.4 数据库迁移

```
dotnet ef migrations add AddMeetingFieldsToTasks
```

迁移应在 `Hua.Todo.Application/Migrations/` 目录生成。

### 4.5 DTO 扩展

**CreateTaskDto** 新增：
```csharp
/// <summary>待办项类型（0=Normal, 1=Meeting），默认 Normal</summary>
public TaskType TaskType { get; set; } = TaskType.Normal;
```

**TaskDto** 新增：
```csharp
/// <summary>待办项类型</summary>
public TaskType TaskType { get; set; }
/// <summary>会议纪要/转写文字</summary>
public string? MeetingNotes { get; set; }
/// <summary>录音时长（秒）</summary>
public double? AudioDuration { get; set; }
```

### 4.6 会议 DTO

```csharp
/// <summary>转写请求</summary>
public class TranscribeRequest
{
    public IFormFile Audio { get; set; } = null!;
    public string? Format { get; set; }
}

/// <summary>转写响应</summary>
public class TranscribeResponse
{
    public int TaskId { get; set; }
    public string Transcript { get; set; } = string.Empty;
    public double AudioDuration { get; set; }
}

/// <summary>保存会议纪要请求</summary>
public class MeetingNotesRequest
{
    public string Notes { get; set; } = string.Empty;
}

/// <summary>会议纪要响应</summary>
public class MeetingNotesResponse
{
    public int TaskId { get; set; }
    public string MeetingNotes { get; set; } = string.Empty;
}
```

### 4.7 API 端点

#### POST /api/meeting/{taskId}/transcribe

- 接收：multipart/form-data（音频文件）
- 返回：`TranscribeResponse`
- 业务：音频上传后异步转写，结果存回 `TaskEntity.MeetingNotes`
- 当前骨架：返回占位文字，具体转写逻辑由 03-02 实现

#### POST /api/meeting/{taskId}/notes

- 接收：`MeetingNotesRequest`
- 返回：`MeetingNotesResponse`
- 业务：保存/更新会议纪要

### 4.8 MeetingService 骨架

```csharp
/// <summary>会议业务服务</summary>
public class MeetingService
{
    private readonly ITaskRepository _taskRepo;

    public MeetingService(ITaskRepository taskRepo)
    {
        _taskRepo = taskRepo;
    }

    /// <summary>验证 taskId 对应的待办项存在且为 Meeting 类型</summary>
    public async Task<TaskEntity> GetMeetingTaskOrThrow(int taskId)
    {
        var task = await _taskRepo.GetAsync(taskId);
        if (task == null)
            throw new NotFoundException($"任务 {taskId} 不存在");
        if (task.TaskType != TaskType.Meeting)
            throw new BusinessException($"任务 {taskId} 不是会议类型");
        return task;
    }

    /// <summary>保存会议纪要</summary>
    public async Task<TaskEntity> SaveNotes(int taskId, string notes)
    {
        var task = await GetMeetingTaskOrThrow(taskId);
        task.MeetingNotes = notes;
        task.UpdatedAt = DateTime.UtcNow;
        await _taskRepo.UpdateAsync(task);
        return task;
    }

    /// <summary>保存转写结果与音频时长</summary>
    public async Task<TaskEntity> SaveTranscript(int taskId, string transcript, double audioDuration)
    {
        var task = await GetMeetingTaskOrThrow(taskId);
        task.MeetingNotes = transcript;
        task.AudioDuration = audioDuration;
        task.UpdatedAt = DateTime.UtcNow;
        await _taskRepo.UpdateAsync(task);
        return task;
    }
}
```

## 五、验收标准

| 验收项 | 验证方法 | 预期结果 |
|---|---|---|
| TaskType 枚举可用 | 编译通过 | `TaskType.Normal` / `TaskType.Meeting` 可正常赋值 |
| DB 迁移可执行 | `dotnet ef database update` | `Tasks` 表新增 `TaskType`/`MeetingNotes`/`AudioDuration` 列 |
| 创建 Meeting 类型任务 | `POST /api/task` 带 `taskType:1` | 返回的 TaskDto 中 `taskType=1` |
| 保存会议纪要 | `POST /api/meeting/{id}/notes` | `meetingNotes` 字段更新成功 |
| 非 Meeting 类型调用会议 API | 普通任务调 `/api/meeting/{id}/notes` | 返回业务异常 |
| 现有代码兼容 | 运行所有已有测试 | 不破坏现有业务 |

## 六、风险

| 风险 | 影响 | 应对 |
|---|---|---|
| TaskEntity 已重构为 ABP 基类 | 字段新增方式不同 | 通过 ABP 的 `ExtraProperties` 或标准字段新增，迁移方式略有调整 |
| 字段长度限制 | 超长会议纪要截断 | `MeetingNotes` 设 `MaxLength(20000)`，前端也做长度限制 |

## 七、Touch List

| 文件路径 | 修改类型 | 是否共享 |
|---|---|---|
| `src/Hua.Todo.Core/Entities/TaskType.cs` | 新增 | 否 |
| `src/Hua.Todo.Core/Entities/TaskEntity.cs` | 修改 | 是 |
| `src/Hua.Todo.Application/Data/TodoDbContext.cs` | 修改 | 是 |
| `src/Hua.Todo.Application/Models/TaskModels.cs` | 修改 | 是 |
| `src/Hua.Todo.Application/Meeting/MeetingController.cs` | 新增 | 否 |
| `src/Hua.Todo.Application/Meeting/MeetingService.cs` | 新增 | 否 |
| `src/Hua.Todo.Application/Meeting/Models/MeetingDtos.cs` | 新增 | 否 |
| `src/Hua.Todo.Web/src/types/task.ts` | 修改 | 是 |
| `Migrations/AddMeetingFieldsToTasks.cs` | 新增 | 是 |

---

**工单编号**：03-01
**标题**：会议数据模型与 API
**版本**：v1.3.0
**创建日期**：2026-06-16