# 贡献指南

<cite>
**本文引用的文件**
- [package.json](file://package.json)
- [tsconfig.json](file://tsconfig.json)
- [.eslintrc.cjs](file://.eslintrc.cjs)
- [jest.config.js](file://jest.config.js)
- [src/index.ts](file://src/index.ts)
- [src/server.ts](file://src/server.ts)
- [src/class/websockethandler.ts](file://src/class/websockethandler.ts)
- [src/class/httphandler.ts](file://src/class/httphandler.ts)
- [.gitignore](file://.gitignore)
</cite>

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

## 简介
本贡献指南面向希望参与“视频流服务器”项目的开发者，提供从 Fork、Clone、分支与提交、Pull Request 到代码审查、Issue 提交、版本发布与变更日志维护、社区行为准则与协作规范的全流程说明。同时给出新贡献者的入门建议与资源链接，帮助快速上手。

## 项目结构
该项目采用前后端一体化的 Node/Express + TypeScript 后端，内置静态前端资源与测试框架，支持 WebSocket 与 HTTP 两种信令模式，具备会话管理、WebRTC 信令转发、文件上传与 Swagger 文档能力。

```mermaid
graph TB
subgraph "后端"
IDX["入口: src/index.ts"]
SRV["服务器: src/server.ts"]
WS["WebSocket处理器: src/class/websockethandler.ts"]
HTTP["HTTP处理器: src/class/httphandler.ts"]
end
subgraph "前端"
PUB["静态资源: client/public/**/*"]
SRC["前端模块: client/src/**/*"]
end
subgraph "工具与配置"
PKG["包脚本: package.json"]
TSC["编译配置: tsconfig.json"]
ESL["代码规范: .eslintrc.cjs"]
JST["测试配置: jest.config.js"]
GIT["忽略规则: .gitignore"]
end
IDX --> SRV
SRV --> WS
SRV --> HTTP
SRV --> PUB
SRV --> SRC
PKG --> TSC
PKG --> ESL
PKG --> JST
PKG --> GIT
```

**图表来源**
- [src/index.ts:1-109](file://src/index.ts#L1-L109)
- [src/server.ts:1-90](file://src/server.ts#L1-L90)
- [src/class/websockethandler.ts:1-479](file://src/class/websockethandler.ts#L1-L479)
- [src/class/httphandler.ts:1-800](file://src/class/httphandler.ts#L1-L800)
- [package.json:1-60](file://package.json#L1-L60)
- [tsconfig.json:1-13](file://tsconfig.json#L1-L13)
- [.eslintrc.cjs:1-25](file://.eslintrc.cjs#L1-L25)
- [jest.config.js:1-196](file://jest.config.js#L1-L196)
- [.gitignore:1-187](file://.gitignore#L1-L187)

**章节来源**
- [src/index.ts:1-109](file://src/index.ts#L1-L109)
- [src/server.ts:1-90](file://src/server.ts#L1-L90)
- [package.json:1-60](file://package.json#L1-L60)
- [tsconfig.json:1-13](file://tsconfig.json#L1-L13)
- [.eslintrc.cjs:1-25](file://.eslintrc.cjs#L1-L25)
- [jest.config.js:1-196](file://jest.config.js#L1-L196)
- [.gitignore:1-187](file://.gitignore#L1-L187)

## 核心组件
- 入口与启动
  - 通过命令行参数解析与 HTTPS/HTTP 服务启动，支持 WebSocket 或 HTTP 信令模式，以及公共/私有通信模式。
- 服务器与路由
  - Express 应用挂载 CORS、日志中间件、静态资源、Swagger 文档、上传接口与信令路由。
- WebSocket 信令
  - 实现 1 对多（主持人/参与者）模式下的 offer/answer/candidate 转发、广播、心跳检测与断线清理。
- HTTP 信令
  - 基于轮询的信令 API，提供会话创建、连接管理、offer/answer/candidate 获取与断线记录。
- 测试与规范
  - Jest 测试配置与覆盖率收集；ESLint TypeScript 规则；TypeScript 编译配置。

**章节来源**
- [src/index.ts:1-109](file://src/index.ts#L1-L109)
- [src/server.ts:1-90](file://src/server.ts#L1-L90)
- [src/class/websockethandler.ts:1-479](file://src/class/websockethandler.ts#L1-L479)
- [src/class/httphandler.ts:1-800](file://src/class/httphandler.ts#L1-L800)
- [jest.config.js:1-196](file://jest.config.js#L1-L196)
- [.eslintrc.cjs:1-25](file://.eslintrc.cjs#L1-L25)
- [tsconfig.json:1-13](file://tsconfig.json#L1-L13)

## 架构总览
后端以 Express 为核心，根据信令类型选择 WebSocket 或 HTTP 处理器；静态资源与前端模块通过 Express 提供；测试与规范工具贯穿开发流程。

```mermaid
graph TB
Client["浏览器/客户端"] --> Mode{"信令模式"}
Mode --> |WebSocket| WS["WebSocket处理器<br/>websockethandler.ts"]
Mode --> |HTTP| HTTP["HTTP处理器<br/>httphandler.ts"]
WS --> Server["Express服务器<br/>server.ts"]
HTTP --> Server
Server --> Static["静态资源<br/>client/public/**/*"]
Server --> Front["前端模块<br/>client/src/**/*"]
Server --> Swagger["Swagger文档"]
Server --> Upload["头像上传API"]
```

**图表来源**
- [src/server.ts:1-90](file://src/server.ts#L1-L90)
- [src/class/websockethandler.ts:1-479](file://src/class/websockethandler.ts#L1-L479)
- [src/class/httphandler.ts:1-800](file://src/class/httphandler.ts#L1-L800)

## 详细组件分析

### WebSocket 信令处理流程
WebSocket 处理器支持公共/私有模式，实现连接、断开、offer/answer/candidate 转发与广播、心跳检测与断线清理。

```mermaid
sequenceDiagram
participant C as "客户端"
participant S as "WebSocket处理器"
participant G as "连接组"
participant H as "主持人"
participant P as "参与者"
C->>S : "connect(connectionId)"
S->>G : "创建/加入连接组"
S-->>C : "connect(角色, participantId)"
C->>S : "offer/answer/candidate"
alt 私有模式
S->>H : "主持人接收转发"
S->>P : "参与者接收转发"
else 公共模式
S->>G : "广播到其他客户端"
end
C->>S : "disconnect"
S->>G : "清理连接组并通知"
S-->>C : "disconnect"
```

**图表来源**
- [src/class/websockethandler.ts:145-206](file://src/class/websockethandler.ts#L145-L206)
- [src/class/websockethandler.ts:214-338](file://src/class/websockethandler.ts#L214-L338)
- [src/class/websockethandler.ts:448-473](file://src/class/websockethandler.ts#L448-L473)

**章节来源**
- [src/class/websockethandler.ts:1-479](file://src/class/websockethandler.ts#L1-L479)

### HTTP 信令处理流程
HTTP 处理器提供会话与连接管理、offer/answer/candidate 获取、断线记录与全量信令拉取。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Handler as "HTTP处理器"
participant Store as "内存存储"
participant Other as "其他会话/连接"
Client->>Handler : "PUT /signaling (创建会话)"
Handler->>Store : "初始化会话映射"
Handler-->>Client : "{ sessionId }"
Client->>Handler : "PUT /signaling/connection (创建连接)"
Handler->>Store : "登记连接ID与配对"
Handler-->>Client : "{ connectionId, polite }"
Client->>Handler : "GET /signaling/offer?fromtime"
Handler->>Store : "按模式过滤并返回offer列表"
Client->>Handler : "GET /signaling (全量信令)"
Handler->>Store : "聚合连接/断线/offer/answer/candidate"
Handler-->>Client : "{ messages, datetime }"
Client->>Handler : "DELETE /signaling/connection"
Handler->>Store : "清理连接与配对"
```

**图表来源**
- [src/class/httphandler.ts:664-783](file://src/class/httphandler.ts#L664-L783)
- [src/class/httphandler.ts:492-641](file://src/class/httphandler.ts#L492-L641)

**章节来源**
- [src/class/httphandler.ts:1-800](file://src/class/httphandler.ts#L1-L800)

### 代码规范与测试
- ESLint 规则启用 TypeScript 推荐规则与 Jest 推荐规则，强制分号与多余分号检查。
- Jest 配置启用覆盖率收集、TS 转换、Node 环境与测试匹配规则。
- TypeScript 编译配置输出至 build 目录，源码位于 src，测试位于 test。

**章节来源**
- [.eslintrc.cjs:1-25](file://.eslintrc.cjs#L1-L25)
- [jest.config.js:1-196](file://jest.config.js#L1-L196)
- [tsconfig.json:1-13](file://tsconfig.json#L1-L13)

## 依赖关系分析
- 后端运行时依赖：Express、WS、CORS、Morgan、Multer、Swagger。
- 开发依赖：Jest、TS-Jest、ESLint、TypeScript、pkg 等。
- 构建与打包：通过 TypeScript 编译与 pkg 配置，打包静态资源与前端模块。

```mermaid
graph LR
PKG["package.json"] --> DEPS["运行时依赖"]
PKG --> DEVDEPS["开发依赖"]
PKG --> BIN["构建与打包配置"]
BIN --> TSC["tsconfig.json"]
BIN --> ESL["eslint配置"]
BIN --> JST["jest配置"]
```

**图表来源**
- [package.json:1-60](file://package.json#L1-L60)
- [tsconfig.json:1-13](file://tsconfig.json#L1-L13)
- [.eslintrc.cjs:1-25](file://.eslintrc.cjs#L1-L25)
- [jest.config.js:1-196](file://jest.config.js#L1-L196)

**章节来源**
- [package.json:1-60](file://package.json#L1-L60)

## 性能考量
- WebSocket 心跳与超时：处理器内置心跳检测与超时断开逻辑，避免僵尸连接占用资源。
- HTTP 轮询：提供 fromtime 参数过滤增量消息，降低带宽与计算压力。
- 日志与中间件：morgan 日志级别可配置，建议在生产环境调整为合适级别。
- 静态资源：静态目录与前端模块统一托管，确保缓存与压缩策略一致。

**章节来源**
- [src/class/websockethandler.ts:404-430](file://src/class/websockethandler.ts#L404-L430)
- [src/server.ts:17-20](file://src/server.ts#L17-L20)

## 故障排查指南
- 启动失败
  - 检查证书文件路径与权限（HTTPS 模式），确认端口占用与网络接口。
- 信令异常
  - 确认信令模式（WebSocket/HTTP）与通信模式（public/private）配置一致。
  - 查看日志输出定位连接组状态与消息转发问题。
- 测试失败
  - 使用 Jest 覆盖率报告定位未覆盖路径，修正测试用例与模拟。
- 规范检查
  - 运行 ESLint 并修复规则冲突，确保提交前通过静态检查。

**章节来源**
- [src/index.ts:52-91](file://src/index.ts#L52-L91)
- [src/server.ts:25-42](file://src/server.ts#L25-L42)
- [jest.config.js:19-26](file://jest.config.js#L19-L26)
- [.eslintrc.cjs:18-23](file://.eslintrc.cjs#L18-L23)

## 结论
本指南提供了从开发环境准备到贡献流程、代码审查、Issue 规范、版本发布与变更日志维护、社区协作的完整实践路径。建议贡献者在提交前完成本地测试与规范检查，并遵循分支命名与提交信息格式，确保高质量交付。

## 附录

### 代码贡献流程
- Fork 仓库
  - 在代码托管平台执行 Fork 操作，获得个人副本。
- Clone 与安装
  - 克隆到本地，安装依赖并运行开发脚本。
- 分支与提交
  - 基于主分支创建特性分支，遵循分支命名规范与提交信息格式。
- Pull Request
  - 提交 PR，填写模板信息，等待审查与合并。

**章节来源**
- [package.json:5-12](file://package.json#L5-L12)

### 分支命名规范与提交信息格式
- 分支命名
  - feat/xxx：新增功能
  - fix/xxx：缺陷修复
  - docs/xxx：文档更新
  - refactor/xxx：重构
  - test/xxx：测试相关
- 提交信息格式
  - 类型(scope): 描述
  - 例如：feat(server): 支持自定义日志级别

### 代码审查标准与流程
- 审查清单
  - 功能正确性与边界条件
  - 性能影响与资源占用
  - 日志与错误处理
  - 单元测试覆盖率
  - 规范检查通过
- 审查流程
  - 提交 PR → 指派审查者 → 评论与修改 → 合并

### Issue 提交规范
- Bug 报告
  - 环境信息、复现步骤、期望/实际结果、日志片段
- 功能请求
  - 背景、需求描述、影响范围、优先级建议

### 版本发布与变更日志维护
- 版本号
  - 遵循语义化版本：主版本.次版本.修订
- 变更日志
  - 按版本记录新增、修复、变更与废弃项，标注影响与迁移指引

### 社区行为准则与协作规范
- 尊重与包容：保持友善与专业
- 明确沟通：使用清晰、简洁的语言
- 合规贡献：遵守开源许可证与安全政策

### 新贡献者入门指导与资源链接
- 环境准备
  - Node.js、TypeScript、Git 基础
- 本地运行
  - 使用开发脚本启动服务，访问静态页面与 Swagger 文档
- 学习资源
  - Express、WebSocket、WebRTC 信令基础
  - Jest 与 ESLint 使用指南