# 内容发布系统

<cite>
**本文引用的文件**
- [server/src/modules/publish/publish.controller.ts](file://server/src/modules/publish/publish.controller.ts)
- [server/src/modules/publish/publish.service.ts](file://server/src/modules/publish/publish.service.ts)
- [server/src/modules/publish/publish.types.ts](file://server/src/modules/publish/publish.types.ts)
- [server/src/modules/book-generator/album-controller.ts](file://server/src/modules/book-generator/album-controller.ts)
- [server/src/modules/book-generator/album-management.controller.ts](file://server/src/modules/book-generator/album-management.controller.ts)
- [server/src/modules/categories/categories.controller.ts](file://server/src/modules/categories/categories.controller.ts)
- [server/src/modules/categories/categories.service.ts](file://server/src/modules/categories/categories.service.ts)
- [server/src/models/index.ts](file://server/src/models/index.ts)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本技术文档面向“内容发布系统”，聚焦以下能力与实践：
- 内容发布流程：从专辑内容生成到多平台自动发布，覆盖任务创建、状态跟踪与结果回写。
- 专辑管理机制：专辑创建、章节组织、章节合并与排序移动。
- 内容审核与发布：结合合规检查与质量评分等前置能力，确保内容可发布。
- 发布策略配置：平台账号绑定、凭证校验、发布参数与封面/标签等策略化配置。
- 内容格式验证：视频/音频路径解析、文件存在性校验、上传参数构造。
- 多平台发布适配：抖音、B站等平台的差异化接入与错误处理。
- 版权保护与权限控制：基于用户态的任务隔离与平台账号绑定。
- 发布统计分析：发布任务列表、状态聚合与平台分布。

## 项目结构
后端采用 Koa 路由 + Prisma ORM 的模块化设计，发布模块位于 server/src/modules/publish，专辑与章节管理位于 server/src/modules/book-generator，分类管理位于 server/src/modules/categories，数据库连接入口位于 server/src/models/index.ts。

```mermaid
graph TB
subgraph "发布模块"
PC["publish.controller.ts<br/>路由层"]
PS["publish.service.ts<br/>业务层"]
PT["publish.types.ts<br/>类型定义"]
end
subgraph "专辑与章节"
AC["album-controller.ts<br/>专辑/章节路由"]
AMC["album-management.controller.ts<br/>专辑/章节管理路由"]
end
subgraph "分类"
CC["categories.controller.ts<br/>分类路由"]
CS["categories.service.ts<br/>分类服务"]
end
DB["models/index.ts<br/>Prisma 客户端"]
PC --> PS
PS --> DB
AC --> DB
AMC --> DB
CC --> CS
CS --> DB
```

**图表来源**
- [server/src/modules/publish/publish.controller.ts:1-333](file://server/src/modules/publish/publish.controller.ts#L1-L333)
- [server/src/modules/publish/publish.service.ts:1-630](file://server/src/modules/publish/publish.service.ts#L1-L630)
- [server/src/modules/publish/publish.types.ts:1-80](file://server/src/modules/publish/publish.types.ts#L1-L80)
- [server/src/modules/book-generator/album-controller.ts:1-433](file://server/src/modules/book-generator/album-controller.ts#L1-L433)
- [server/src/modules/book-generator/album-management.controller.ts:1-77](file://server/src/modules/book-generator/album-management.controller.ts#L1-L77)
- [server/src/modules/categories/categories.controller.ts:1-55](file://server/src/modules/categories/categories.controller.ts#L1-L55)
- [server/src/modules/categories/categories.service.ts:1-65](file://server/src/modules/categories/categories.service.ts#L1-L65)
- [server/src/models/index.ts:1-15](file://server/src/models/index.ts#L1-L15)

**章节来源**
- [server/src/modules/publish/publish.controller.ts:1-333](file://server/src/modules/publish/publish.controller.ts#L1-L333)
- [server/src/modules/publish/publish.service.ts:1-630](file://server/src/modules/publish/publish.service.ts#L1-L630)
- [server/src/modules/book-generator/album-controller.ts:1-433](file://server/src/modules/book-generator/album-controller.ts#L1-L433)
- [server/src/modules/book-generator/album-management.controller.ts:1-77](file://server/src/modules/book-generator/album-management.controller.ts#L1-L77)
- [server/src/modules/categories/categories.controller.ts:1-55](file://server/src/modules/categories/categories.controller.ts#L1-L55)
- [server/src/modules/categories/categories.service.ts:1-65](file://server/src/modules/categories/categories.service.ts#L1-L65)
- [server/src/models/index.ts:1-15](file://server/src/models/index.ts#L1-L15)

## 核心组件
- 发布控制器（publish.controller.ts）：提供平台账号管理、发布任务管理、预览与重发等 API。
- 发布服务（publish.service.ts）：封装平台账号存取、任务创建/查询/更新、抖音/B站发布、凭证校验与视频项目信息获取。
- 发布类型（publish.types.ts）：统一定义平台、状态、账号、任务、上传响应等类型。
- 专辑控制器（album-controller.ts）：专辑列表、书籍列表、章节树形结构、章节合并音频等。
- 专辑管理控制器（album-management.controller.ts）：专辑/章节重命名、章节移动。
- 分类控制器与服务（categories.controller.ts、categories.service.ts）：分类列表与占位实现。
- 数据库连接（models/index.ts）：Prisma 客户端初始化与连接。

**章节来源**
- [server/src/modules/publish/publish.controller.ts:1-333](file://server/src/modules/publish/publish.controller.ts#L1-L333)
- [server/src/modules/publish/publish.service.ts:1-630](file://server/src/modules/publish/publish.service.ts#L1-L630)
- [server/src/modules/publish/publish.types.ts:1-80](file://server/src/modules/publish/publish.types.ts#L1-L80)
- [server/src/modules/book-generator/album-controller.ts:1-433](file://server/src/modules/book-generator/album-controller.ts#L1-L433)
- [server/src/modules/book-generator/album-management.controller.ts:1-77](file://server/src/modules/book-generator/album-management.controller.ts#L1-L77)
- [server/src/modules/categories/categories.controller.ts:1-55](file://server/src/modules/categories/categories.controller.ts#L1-L55)
- [server/src/modules/categories/categories.service.ts:1-65](file://server/src/modules/categories/categories.service.ts#L1-L65)
- [server/src/models/index.ts:1-15](file://server/src/models/index.ts#L1-L15)

## 架构总览
发布系统以“路由层-业务层-数据层”三层解耦，路由层负责鉴权与参数校验，业务层负责跨平台发布与任务编排，数据层通过 Prisma 访问数据库。

```mermaid
sequenceDiagram
participant C as "客户端"
participant R as "发布控制器"
participant S as "发布服务"
participant P as "平台(抖音/B站)"
participant D as "数据库(Prisma)"
C->>R : "POST /api/publish/tasks"
R->>R : "鉴权/参数校验"
R->>S : "createPublishTask(...)"
S->>D : "插入发布任务"
S-->>R : "返回任务"
R->>S : "根据平台调用发布方法"
alt 抖音
S->>P : "上传视频/封面/标签"
P-->>S : "返回作品链接"
else B站
S->>P : "OAuth2上传"
P-->>S : "返回BV号/链接"
end
S->>D : "更新任务状态/链接"
R-->>C : "返回任务ID与发布结果"
```

**图表来源**
- [server/src/modules/publish/publish.controller.ts:206-277](file://server/src/modules/publish/publish.controller.ts#L206-L277)
- [server/src/modules/publish/publish.service.ts:159-316](file://server/src/modules/publish/publish.service.ts#L159-L316)
- [server/src/modules/publish/publish.service.ts:478-548](file://server/src/modules/publish/publish.service.ts#L478-L548)

**章节来源**
- [server/src/modules/publish/publish.controller.ts:206-277](file://server/src/modules/publish/publish.controller.ts#L206-L277)
- [server/src/modules/publish/publish.service.ts:245-316](file://server/src/modules/publish/publish.service.ts#L245-L316)
- [server/src/modules/publish/publish.service.ts:478-548](file://server/src/modules/publish/publish.service.ts#L478-L548)

## 详细组件分析

### 发布模块（发布流程、策略与状态）
- 平台账号管理
  - 绑定/解绑/校验：支持抖音、B站等平台账号绑定，凭证有效期与有效性校验。
  - 参数要点：cookies、headers(User-Agent等)、昵称、头像、过期时间。
- 发布任务管理
  - 创建任务：记录视频项目ID、平台、标题、描述、标签、封面、初始状态 pending。
  - 查询任务：支持按平台/状态分页查询；单个任务读取并校验归属。
  - 更新任务：上传中/成功/失败状态切换，记录错误信息与发布链接。
- 多平台发布
  - 抖音：预上传获取上传凭证，读取本地视频文件并上传，更新为成功并返回作品链接；异常时置失败并记录错误。
  - B站：使用官方 API，需 OAuth2 access_token，上传成功后返回 BV 号并拼装播放链接。
- 发布策略配置
  - 标题/描述/标签/封面策略：统一从请求体或视频项目中提取，支持缺省值与回填。
  - 平台差异：抖音使用 cookies+headers，B站使用 OAuth2 Bearer Token。
- 内容格式验证
  - 视频/封面路径解析：支持相对路径转绝对路径；文件存在性校验。
  - 标签与封面可选，标题必填；视频来源支持“视频项目ID”或“直传URL”。

```mermaid
flowchart TD
Start(["提交发布任务"]) --> CheckParams["校验平台/标题/来源参数"]
CheckParams --> ParamsOK{"参数合法?"}
ParamsOK -- 否 --> ErrParams["返回错误: 缺少必要参数"]
ParamsOK -- 是 --> ResolveVideo["解析视频/封面/描述"]
ResolveVideo --> CreateTask["创建发布任务(pending)"]
CreateTask --> ChoosePlat{"平台类型"}
ChoosePlat -- 抖音 --> Douyin["上传至抖音"]
ChoosePlat -- B站 --> Bili["上传至B站(OAuth2)"]
ChoosePlat -- 其他 --> NotSupport["返回错误: 不支持平台"]
Douyin --> UpdateTask["更新状态为成功/失败并记录链接/错误"]
Bili --> UpdateTask
UpdateTask --> Done(["返回任务ID与结果"])
ErrParams --> Done
NotSupport --> Done
```

**图表来源**
- [server/src/modules/publish/publish.controller.ts:206-277](file://server/src/modules/publish/publish.controller.ts#L206-L277)
- [server/src/modules/publish/publish.service.ts:159-177](file://server/src/modules/publish/publish.service.ts#L159-L177)
- [server/src/modules/publish/publish.service.ts:245-316](file://server/src/modules/publish/publish.service.ts#L245-L316)
- [server/src/modules/publish/publish.service.ts:478-548](file://server/src/modules/publish/publish.service.ts#L478-L548)

**章节来源**
- [server/src/modules/publish/publish.controller.ts:34-145](file://server/src/modules/publish/publish.controller.ts#L34-L145)
- [server/src/modules/publish/publish.controller.ts:149-200](file://server/src/modules/publish/publish.controller.ts#L149-L200)
- [server/src/modules/publish/publish.controller.ts:206-277](file://server/src/modules/publish/publish.controller.ts#L206-L277)
- [server/src/modules/publish/publish.service.ts:23-121](file://server/src/modules/publish/publish.service.ts#L23-L121)
- [server/src/modules/publish/publish.service.ts:159-238](file://server/src/modules/publish/publish.service.ts#L159-L238)
- [server/src/modules/publish/publish.service.ts:245-316](file://server/src/modules/publish/publish.service.ts#L245-L316)
- [server/src/modules/publish/publish.service.ts:478-548](file://server/src/modules/publish/publish.service.ts#L478-L548)

### 专辑与章节管理（专辑创建、内容组织、章节合并）
- 专辑管理
  - 列表：按用户维度返回专辑基础信息。
  - 创建：标题必填，描述可选，初始章节数为 0。
- 章节管理
  - 章节树形结构：支持章(level=1)/节(level=2)/小节(level=3)，按序号排序。
  - 合并音频：将指定章下的所有小节音频合并为单个文件，计算总时长并回写到章。
  - 权限与可见性：非所有者仅能查看公开内容，否则音频字段清空。
- 专辑/章节重命名与移动
  - 重命名：更新专辑或章节标题。
  - 移动：调整章节序号，同时维护其他章节序号一致性。

```mermaid
sequenceDiagram
participant U as "用户"
participant AC as "专辑控制器"
participant AMC as "专辑管理控制器"
participant DB as "数据库(Prisma)"
U->>AC : "GET /api/book-generator/albums"
AC->>DB : "查询用户专辑"
DB-->>AC : "返回专辑列表"
AC-->>U : "返回专辑基础信息"
U->>AC : "POST /api/book-generator/albums"
AC->>DB : "创建专辑"
DB-->>AC : "返回专辑ID/标题"
AC-->>U : "返回创建结果"
U->>AC : "GET /api/book-generator/albums/ : id/chapters"
AC->>DB : "查询章节树形结构"
DB-->>AC : "返回章节与小节音频"
AC-->>U : "返回章节(含合并音频)"
U->>AC : "POST /api/book-generator/albums/ : id/chapters/ : chapterId/merge-audio"
AC->>DB : "查询节/小节音频URL"
AC->>AC : "合并音频并计算时长"
AC->>DB : "更新章的合并音频URL与时长"
AC-->>U : "返回合并结果"
U->>AMC : "PUT / : id/rename"
AMC->>DB : "更新专辑标题"
AMC-->>U : "返回更新结果"
U->>AMC : "PUT / : bookId/chapters/ : chapterId/move"
AMC->>DB : "调整序号并维护其他章节序号"
AMC-->>U : "返回更新结果"
```

**图表来源**
- [server/src/modules/book-generator/album-controller.ts:21-143](file://server/src/modules/book-generator/album-controller.ts#L21-L143)
- [server/src/modules/book-generator/album-controller.ts:151-297](file://server/src/modules/book-generator/album-controller.ts#L151-L297)
- [server/src/modules/book-generator/album-controller.ts:303-384](file://server/src/modules/book-generator/album-controller.ts#L303-L384)
- [server/src/modules/book-generator/album-management.controller.ts:9-74](file://server/src/modules/book-generator/album-management.controller.ts#L9-L74)

**章节来源**
- [server/src/modules/book-generator/album-controller.ts:21-143](file://server/src/modules/book-generator/album-controller.ts#L21-L143)
- [server/src/modules/book-generator/album-controller.ts:151-297](file://server/src/modules/book-generator/album-controller.ts#L151-L297)
- [server/src/modules/book-generator/album-controller.ts:303-384](file://server/src/modules/book-generator/album-controller.ts#L303-L384)
- [server/src/modules/book-generator/album-management.controller.ts:9-74](file://server/src/modules/book-generator/album-management.controller.ts#L9-L74)

### 分类管理（分类组织与占位实现）
- 分类列表：返回固定默认分类集合（故事/小说/儿童/知识/娱乐等），图标为表情符号。
- 按分类获取音频：当前占位返回空列表，未来可扩展自书籍章节统计。

**章节来源**
- [server/src/modules/categories/categories.controller.ts:10-24](file://server/src/modules/categories/categories.controller.ts#L10-L24)
- [server/src/modules/categories/categories.controller.ts:30-52](file://server/src/modules/categories/categories.controller.ts#L30-L52)
- [server/src/modules/categories/categories.service.ts:10-34](file://server/src/modules/categories/categories.service.ts#L10-L34)

### 数据模型与类型
- 发布类型
  - 平台：douyin/kuaishou/bilibili
  - 状态：pending/uploading/success/failed
  - 账号：cookies/headers/nickname/avatar/isValid/expireTime
  - 任务：videoProjectId/videoUrl/platform/title/description/tags/coverUrl/status/errorMsg/publishedUrl
- 数据库连接
  - PrismaClient 初始化与连接日志。

**章节来源**
- [server/src/modules/publish/publish.types.ts:5-80](file://server/src/modules/publish/publish.types.ts#L5-L80)
- [server/src/models/index.ts:5-13](file://server/src/models/index.ts#L5-L13)

## 依赖关系分析
- 控制器依赖服务：发布控制器通过服务层调用平台账号与任务操作。
- 服务依赖 Prisma：所有持久化操作通过 Prisma 客户端完成。
- 平台差异：抖音与 B站分别使用不同认证与上传协议，服务层内部分流处理。
- 前端交互：专辑与章节管理通过 Koa 路由返回统一结构，便于前端消费。

```mermaid
graph LR
PC["publish.controller.ts"] --> PS["publish.service.ts"]
PS --> PT["publish.types.ts"]
PS --> PRISMA["Prisma Client(models/index.ts)"]
AC["album-controller.ts"] --> PRISMA
AMC["album-management.controller.ts"] --> PRISMA
CC["categories.controller.ts"] --> CS["categories.service.ts"]
CS --> PRISMA
```

**图表来源**
- [server/src/modules/publish/publish.controller.ts:1-30](file://server/src/modules/publish/publish.controller.ts#L1-L30)
- [server/src/modules/publish/publish.service.ts:1-19](file://server/src/modules/publish/publish.service.ts#L1-L19)
- [server/src/modules/publish/publish.types.ts:1-80](file://server/src/modules/publish/publish.types.ts#L1-L80)
- [server/src/models/index.ts:1-15](file://server/src/models/index.ts#L1-L15)
- [server/src/modules/book-generator/album-controller.ts:1-15](file://server/src/modules/book-generator/album-controller.ts#L1-L15)
- [server/src/modules/book-generator/album-management.controller.ts:1-6](file://server/src/modules/book-generator/album-management.controller.ts#L1-L6)
- [server/src/modules/categories/categories.controller.ts:1-4](file://server/src/modules/categories/categories.controller.ts#L1-L4)
- [server/src/modules/categories/categories.service.ts:1-65](file://server/src/modules/categories/categories.service.ts#L1-L65)

**章节来源**
- [server/src/modules/publish/publish.controller.ts:1-30](file://server/src/modules/publish/publish.controller.ts#L1-L30)
- [server/src/modules/publish/publish.service.ts:1-19](file://server/src/modules/publish/publish.service.ts#L1-L19)
- [server/src/models/index.ts:1-15](file://server/src/models/index.ts#L1-L15)

## 性能考量
- 异步并发：任务列表查询使用 Promise.all 并行获取 items 与 total，降低 RTT。
- 文件IO：合并音频与读取视频/封面前进行存在性校验，避免无效 IO。
- 上传策略：抖音上传采用简化流程，生产环境建议实现分片上传与断点续传。
- 错误快速失败：凭证过期、文件缺失、平台接口异常均及时更新任务状态并返回错误。

[本节为通用性能建议，不直接分析具体文件]

## 故障排查指南
- 平台账号问题
  - 未绑定账号：请先绑定对应平台账号并填写 cookies/headers。
  - 凭证过期：调用校验接口刷新授权；抖音/B站均支持有效期检查。
- 发布失败
  - 抖音：常见 403 登录过期，需重新授权；检查 cookies 与 headers 是否匹配。
  - B站：需 access_token，若缺失或过期需重新授权。
- 任务状态异常
  - 上传中卡住：检查视频文件是否存在且可读；确认网络可达平台上传域名。
  - 任务不存在：确认 taskId 与用户归属一致。
- 专辑/章节
  - 合并音频失败：确认章节下存在有效音频URL；检查输出目录权限。

**章节来源**
- [server/src/modules/publish/publish.service.ts:126-152](file://server/src/modules/publish/publish.service.ts#L126-L152)
- [server/src/modules/publish/publish.service.ts:245-316](file://server/src/modules/publish/publish.service.ts#L245-L316)
- [server/src/modules/publish/publish.service.ts:478-548](file://server/src/modules/publish/publish.service.ts#L478-L548)
- [server/src/modules/book-generator/album-controller.ts:303-384](file://server/src/modules/book-generator/album-controller.ts#L303-L384)

## 结论
本发布系统以清晰的三层架构实现了从内容生成到多平台发布的闭环：专辑与章节管理提供内容组织能力，发布模块提供跨平台自动化发布与状态跟踪，分类模块提供内容组织入口。通过严格的参数校验、凭证校验与状态机管理，系统具备良好的可运维性与扩展性。后续可在上传策略、合规检查与统计分析方面进一步增强。

[本节为总结性内容，不直接分析具体文件]

## 附录

### 常见场景与示例路径
- 提交发布申请（创建任务并触发发布）
  - 路径参考：[server/src/modules/publish/publish.controller.ts:206-277](file://server/src/modules/publish/publish.controller.ts#L206-L277)
- 进行内容审核（结合合规检查与质量评分）
  - 参考路径：合规检查接口与质量评分接口（见功能清单中的相关条目）
- 管理发布状态（查询任务列表/单个任务）
  - 路径参考：[server/src/modules/publish/publish.controller.ts:149-200](file://server/src/modules/publish/publish.controller.ts#L149-L200)
- 专辑创建与管理（创建专辑/重命名/移动）
  - 路径参考：[server/src/modules/book-generator/album-controller.ts:110-143](file://server/src/modules/book-generator/album-controller.ts#L110-L143)、[server/src/modules/book-generator/album-management.controller.ts:9-74](file://server/src/modules/book-generator/album-management.controller.ts#L9-L74)
- 内容分类组织（分类列表）
  - 路径参考：[server/src/modules/categories/categories.controller.ts:10-24](file://server/src/modules/categories/categories.controller.ts#L10-L24)

**章节来源**
- [server/src/modules/publish/publish.controller.ts:149-277](file://server/src/modules/publish/publish.controller.ts#L149-L277)
- [server/src/modules/book-generator/album-controller.ts:110-143](file://server/src/modules/book-generator/album-controller.ts#L110-L143)
- [server/src/modules/book-generator/album-management.controller.ts:9-74](file://server/src/modules/book-generator/album-management.controller.ts#L9-L74)
- [server/src/modules/categories/categories.controller.ts:10-24](file://server/src/modules/categories/categories.controller.ts#L10-L24)