pit-router/CHANGELOG.md

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

---

## [Unreleased]

---

## [0.6.1] - 2026-03-14

### Fixed

- **根路由缺失** - 添加 `/` 路由，返回服务信息和端点列表
- **CORS 拼写错误** - 修复 `cors_allowed_origins` 拼写

---

## [0.6.0] - 2026-03-14

### Fixed

- **命名冲突** - 修复 `socketio` 变量与 `app/socketio` 模块冲突，重命名为 `socketio_app`
- **config.py** - 移除生产环境强制数据库检查，允许开发环境使用 SQLite

### Added

- **.gitignore** - 添加 Python 缓存和数据库文件忽略规则

### Test Results

- 调度器测试: ✅ 11/11 通过
- 消息队列测试: ✅ 7/7 通过
- 验证工具测试: ✅ 3/4 通过
- 认证 API 测试: ⚠️ 3/9 (测试配置问题)

**总计**: 24/31 测试通过

---

## [0.5.0] - 2026-03-14

### Added

#### 🔧 工具层实现 (Phase 3)

- **validators.py** - 输入验证工具
  - Marshmallow Schema 验证
  - UUID/Email/用户名/URL 验证
  - 字符串清理

- **security.py** - 安全工具
  - Token/密码哈希
  - API Key 生成
  - RateLimiter 限流器
  - IPWhitelist IP 白名单

- **helpers.py** - 辅助函数
  - 日期时间格式化
  - 分页辅助
  - JSON 安全解析

#### 🧪 测试模块

- **conftest.py** - pytest 配置
- **test_auth.py** - 认证 API 单元测试
- **test_scheduler.py** - 调度器单元测试
- **test_message_queue.py** - 消息队列单元测试

#### 🗄️ 数据库迁移

- **Alembic 配置** - 数据库迁移工具
- **初始迁移脚本** - 创建所有数据表

### Changed

- **requirements.txt** - 添加 gevent 依赖（用于 gunicorn）

---

## [0.4.0] - 2026-03-14

### Added

#### 🔧 服务层实现 (Phase 2)

- **AgentScheduler** - 5 种调度策略
  - RoundRobinScheduler - 轮询调度
  - WeightedRoundRobinScheduler - 加权轮询调度（默认）
  - LeastConnectionsScheduler - 最少连接调度
  - LeastResponseTimeScheduler - 最快响应调度
  - CapabilityMatchScheduler - 能力匹配调度

- **MessageQueue** - 消息队列管理
  - 消息入队/出队
  - ACK 确认机制
  - 重试队列管理
  - Redis 存储支持

- **SessionService** - 会话服务
  - 创建/关闭会话
  - Agent 分配
  - 多 Agent 协作支持
  - 会话活跃度追踪

- **MessageService** - 消息服务
  - 创建/获取消息
  - 消息确认
  - 已读标记
  - 重试机制
  - 消息统计

- **AgentService** - Agent 服务
  - Agent 注册/注销
  - 状态更新
  - 心跳管理
  - 配置更新
  - 离线检测

### Fixed

- **gateways.py** - 修复蓝图名称错误 (`gateway_bp` → `gateways_bp`)

### Changed

- **Dockerfile** - 添加生产环境 Docker 镜像配置

---

## [0.3.0] - 2026-03-14

### Added

#### 🏗️ 项目结构

- **Flask 应用工厂** - `app/__init__.py` 模块化应用初始化
- **配置管理** - `app/config.py` 支持开发/生产/测试环境
- **扩展初始化** - `app/extensions.py` 统一管理 Flask 扩展

#### 📦 数据模型实现

- **User 模型** - 用户模型，支持 bcrypt 密码哈希
- **Session 模型** - 会话模型，支持多 Agent 协作
- **Agent 模型** - Agent 模型，支持优先级和权重调度
- **Gateway 模型** - Gateway 模型，支持 Token 哈希存储
- **Message 模型** - 消息模型，支持 ACK 状态追踪
- **Connection 模型** - 连接模型，追踪 WebSocket 连接

#### 🔌 HTTP API 实现

- **认证 API** - 注册、登录、Token 刷新、用户信息
- **会话 API** - 创建、查询、关闭会话
- **Agent API** - 列表、详情、状态、配置更新、心跳上报
- **Gateway API** - 注册、注销、状态查询、心跳上报
- **消息 API** - 发送、获取、确认、已读标记
- **统计 API** - 系统、会话、消息、Agent 统计

#### 🔌 WebSocket 实现

- **认证流程** - `connect` → `auth` → `authenticated`
- **心跳机制** - `ping` / `pong` 事件
- **会话管理** - 创建、加入会话
- **消息路由** - 发送消息、消息确认
- **连接管理器** - 管理用户和 Agent 的 Socket 连接

#### 📄 配置文件

- **requirements.txt** - Python 依赖列表
- **requirements-dev.txt** - 开发依赖
- **.env.example** - 环境变量模板
- **docker-compose.yaml** - Docker 编排配置
- **run.py** - 启动入口

### Changed

- **开发计划进度** - Phase 1 核心功能已完成

---

## [0.2.0] - 2026-03-14

### Changed

#### 🔴 数据模型修复

- **新增 Message 模型** - 支持消息持久化，包含 `status`、`ack_status`、`retry_count` 等字段
- **新增 Connection 模型** - 追踪 WebSocket 连接状态，包含 `socket_id`、`ip_address`、`user_agent` 等
- **Session 模型扩展** - 添加 `user_socket_id`、`participating_agent_ids`、`unread_count` 字段
- **Agent 模型扩展** - 添加 `socket_id`、`connection_limit`、`current_sessions` 字段
- **Gateway 模型扩展** - 添加 `token_hash`、`allowed_ips`、`heartbeat_interval` 字段

#### 🟡 WebSocket 协议完善

- **新增认证流程** - `connect` → `auth` → `authenticated` / `auth_error`
- **新增心跳事件** - `ping` / `pong` / `heartbeat_timeout`
- **新增消息确认** - `message.ack` / `message.acked` / `message.read`
- **新增会话事件** - `session.leave` / `session.left` / `session.closed` / `session.assigned`
- **新增输入状态** - `typing` 事件
- **明确消息格式** - 与 PIT Channel 插件兼容的 JSON-RPC 风格格式

#### 🟢 API 补充

- **新增消息 API** - `POST /api/messages`、`GET /api/messages/:id`、`PUT /api/messages/:id/ack`
- **新增统计 API** - `GET /api/stats`、`GET /api/stats/sessions`、`GET /api/stats/messages`
- **新增心跳接口** - `POST /api/agents/:id/heartbeat`、`POST /api/gateways/:id/heartbeat`
- **新增会话操作** - `GET /api/sessions/:id/participants`、`POST /api/sessions/:id/transfer`
- **修改会话关闭** - `DELETE /api/sessions/:id` 改为 `PUT /api/sessions/:id/close`

#### 🔵 架构优化

- **数据库更换** - SQLite → PostgreSQL (生产环境)
- **Agent 调度策略** - 定义 5 种调度算法：轮询、加权轮询、最少连接、最快响应、能力匹配
- **消息可靠性机制** - ACK 确认流程、重试机制、持久化策略
- **安全增强** - WebSocket 认证、IP 白名单、Token 哈希存储

#### 🟣 部署配置完善

- **Docker Compose** - 添加健康检查、资源限制、Nginx 反向代理
- **新增服务** - PostgreSQL、Nginx
- **SSL 支持** - Nginx HTTPS/WSS 配置

#### 📝 文档更新

- **完善技术栈说明** - 添加 PostgreSQL
- **完善项目结构** - 新增 `messages.py`、`connection.py`、`stats.py` 等
- **完善开发计划** - 调整为 4 个阶段，总计 9-12 天
- **新增对接说明** - 与 PIT Channel 插件的协议兼容性

---

## [0.1.0] - 2026-03-14

### Added

- **项目初始化** - 创建 pit-router 项目
- **基础架构设计** - 三层架构：接入层、业务层、数据层
- **技术栈选型** - Python 3.12 + Flask 3.0 + Flask-SocketIO 5.3
- **数据模型设计** - User、Session、Agent、Gateway 四个核心模型
- **HTTP API 设计** - 认证、会话、Agent、Gateway 四组 API
- **WebSocket 协议** - 基础事件定义
- **Docker 部署** - docker-compose.yaml 配置
- **安全设计** - JWT 认证、CORS、Rate Limit

---

## 版本说明

| 版本 | 状态 | 说明 |
|------|------|------|
| 0.1.0 | 初始版本 | 基础架构设计 |
| 0.2.0 | 设计完善 | 修复技术方案问题，完善架构设计 |
| 1.0.0 | 待发布 | 完整功能实现 |

---

*维护者: 小白 🐶*