fastapi-ws-module-skill

FastAPI WebSocket Module Skill

为 FastAPI 项目叠加一套 WebSocket 即时通信能力，不是重新生成新项目。

定位

• 目标：在已有 fastapi-init-skill 骨架上，添加可运行的 WebSocket 通信模块。
• 不替代：不重复生成 fastapi-init-skill 已经提供的 JWT、统一响应、SQLAlchemy async 等基础设施。
• 不做腾讯 IM：自建轻量方案，适合小中规模，不依赖第三方 IM 服务。
• 输出：连接管理器、消息路由、消息存储、离线推送、会话管理、好友校验、接口契约。

骨架依赖（子模块）

本模块是 fastapi-init-skill 的子模块，必须在骨架基础上使用。

使用前必须满足以下条件：

1. ✅ 已安装 fastapi-init-skill（项目骨架）
2. ✅ 骨架包含：JWT、统一响应、SQLAlchemy async、分页、目录结构
3. ✅ 遵循骨架的表前缀、字段命名、软删除规范

检测逻辑：

1. 读取用户项目根目录，检查是否包含 fastapi-init-skill 的标志性文件（app/main.py、app/config.py、app/response.py）
2. 检查 app/dependencies.py 是否已有 get_current_user 依赖
3. 如未检测到骨架，提示："本模块需要先安装 fastapi-init-skill 骨架"
4. 如用户拒绝安装骨架，则终止并提示无法使用

用户问题（最多 3 个）

1. 现有项目的包名是什么？（默认从 fastapi-init-skill 推断，如 app）
2. 表前缀是什么？（默认 wg）
3. 是否需要群聊？（默认不需要，先做单聊）

核心能力清单

#	能力	说明
1	WebSocket 长连接	WS /api/ws?token=<jwt>，query 参数鉴权，多端登录（PC/手机/Web 同时在线）
2	单聊消息	文本/图片/语音实时投递，在线直推，离线入库
3	好友校验	仅允许已通过好友互发消息，避免陌生人骚扰
4	消息幂等	客户端传 client_msg_id，网络抖动重发不重复入库
5	离线消息	用户上线时自动推送未送达消息（最多 100 条）
6	未读数	单聊未读计数，支持清零 + 实时通知对方
7	会话列表	最近会话排序，最后一条消息预览
8	聊天记录	基于 cursor 翻页的历史消息查询
9	消息状态	未读 → 已送达 → 已读 三态流转
10	接口契约	生成 api-contract-ws.md，与 frontend-request-skill 对齐

生成流程

1. 确认已存在 FastAPI 骨架（含 JWT、统一响应、分页）。
2. 询问用户包名、表前缀（默认 wg）、是否需要群聊。
3. 按 references/skeleton.py 生成 ws/ 下全部源码：
   • 将所有 {prefix} 占位符替换为用户指定的表前缀（如 wg_）
   • 将 app.ws 替换为用户的包名（如 app.ws）
4. 生成 api-contract-ws.md 与 docs/ws-module-guide.md。
5. 在 app/main.py 注册 WebSocket 路由。
6. 提示用户：重启服务后可通过 WebSocket 客户端测试连接。

模块结构

{{PROJECT_NAME}}/
├── app/
│   ├── ws/
│   │   ├── __init__.py
│   │   ├── manager.py          # WebSocket 连接管理器（多端登录）
│   │   ├── heartbeat.py        # 心跳保活（任何消息都算心跳）
│   │   ├── handler.py          # 消息路由与处理（好友/幂等/校验/落库/推送）
│   │   ├── friend.py           # 好友关系校验
│   │   ├── validators.py       # 消息内容校验 + 预览生成
│   │   ├── offline.py          # 离线消息推送
│   │   ├── models/
│   │   │   ├── __init__.py
│   │   │   ├── message.py      # {prefix}_chat_message 消息表
│   │   │   ├── conversation.py # {prefix}_chat_conversation 会话表
│   │   │   └── friend.py       # {prefix}_user_friend 好友表
│   │   ├── schemas/
│   │   │   ├── __init__.py
│   │   │   ├── message.py      # 消息入参/出参（含 image_url/voice_url 等）
│   │   │   └── conversation.py # 会话入参/出参 + MarkReadRequest
│   │   ├── services/
│   │   │   ├── __init__.py
│   │   │   ├── message_service.py       # 消息存储与查询
│   │   │   └── conversation_service.py  # 会话管理
│   │   └── routers/
│   │       ├── __init__.py
│   │       ├── ws.py           # WebSocket 端点 /api/ws
│   │       ├── chat.py         # REST 接口（历史/会话/未读/已读/发消息）
│   │       └── friend.py       # 好友 REST 接口（可选，没装 auth-module-skill 时兜底）
├── alembic/
│   └── versions/
│       └── ws_module.py        # 迁移文件
├── api-contract-ws.md          # 接口契约
└── docs/
    └── ws-module-guide.md      # 接入指南