ARTIFACT / BIPU

Bipupu

ACTIVE SYSTEM

手机里塞一个传呼机：服务器收到消息，手机把消息推到一块 128×64 的 ESP32 小屏上，屏幕装进口袋就不用一直看手机。

◈ System Profile ◈

ARTIFACT ID: bipu
COMPILED: 2026-10-23
STATUS / 状态: 后端可用、App 可安装（CI 出 APK）、固件独立维护

◈ Access · 访问入口 ◈

bipu-firmware ↗

◈ Sections · 章节 ◈

本质选型功能启动流程边界与已知问题文档索引

◈ README ◈

Bipupu

手机里塞一个传呼机：服务器收到消息，手机把消息推到一块 128×64 的 ESP32 小屏上，屏幕装进口袋就不用一直看手机。

状态：后端可用、App 可安装（CI 出 APK）、固件独立维护；入口：本地运行（backend/ + mobile/）；仓库：本仓库（后端 + Flutter App），固件在 bipu-firmware

本质

把手机消息经 App 与 BLE 推到 ESP32 小屏的传呼机系统。

选型

基于 FastAPI + Flutter 的前后端分离应用，前端 Flutter，后端 FastAPI，数据 PostgreSQL + 可选 Redis/Celery，设备 BLE NUS + 0xB0，部署 Docker Compose。

前端
- Flutter
  - flutter_bloc
  - go_router
  - dio
  - retrofit
  - Hive
  - flutter_secure_storage
  - flutter_blue_plus
  - speech_to_text
  - just_audio
  - flutter_background_service
  - easy_localization
后端
- FastAPI
  - SQLAlchemy 2.0
    - Alembic
  - Pydantic v2
  - python-jose
  - passlib
  - Jinja2
数据
- PostgreSQL 15
- Redis 7
  - Celery 5.5
    - Celery beat
协议
- BLE Nordic UART Service
  - Bipupu 协议 v1.2
部署
- Docker Compose
- GitHub Actions
- GHCR

功能

后端 12 组路由：认证、消息收发与长轮询、联系人、黑名单、用户与头像、服务号、海报、管理后台、WebSocket
服务号订阅可单独设推送时间，Celery beat 每 15 分钟扫窗口派发，push_logs 记完整状态
/admin 服务端渲染后台，管用户、消息、服务号、推送日志、海报
App 46 个页面文件：传呼机主界面、会话与收藏、蓝牙扫描/绑定/解绑、后台自动转发、双语与主题设置
未完成：后台转发依赖系统不杀进程，iOS 侧保活与转发可靠性未验证；App 无自动化测试，后端只有 3 个 test_ 用例

启动流程

# 后端
cd backend
cp .env.example .env            # 改 SECRET_KEY 与数据库密码
uv sync
uv run alembic upgrade head
uv run uvicorn app.main:app --reload --port 8000
# API 文档 /api/docs ，后台 /admin

# 后端容器（含 PostgreSQL）
cd backend && docker compose -f docker/docker-compose.yml up -d

# App
cd mobile && flutter pub get && flutter run    # 真机，模拟器无 BLE

固件编译烧录见 bipu-firmware；协议细节见 mobile/docs/BLUETOOTH_PROTOCOL_QUICK_REFERENCE.md。

边界与已知问题

docs/ARCHITECTURE.md 写 Web 管理端是 React/Vue，实际是 Jinja2 模板；写“离线语音识别 (Sherpa-ONNX)”，实际 ASR 走系统 speech_to_text，本地 TTS 引擎已注释关闭
bluetooth_forward_service.dart 注释里的“昵称: 正文 前缀”已过时，协议 v1.2 是 [sender_len][sender][body]，以 bipupu_protocol.h 为准
Redis 与 Celery 都是可选项；不启 Redis 用内存缓存，不启 Celery 就没有定时推送
没有限流与消息去重的成文策略，同账号多设备行为未定义
iOS 打包依赖远程 Mac，mobile/ 下的 IOS_BUILD_REPORT 等是过程记录，不等于现状
默认管理员口令只是示例，部署前必须改
本仓库不含固件；bipu-firmware 没有 OTA 分区，升级只能重烧

文档索引

docs/README.md — 文档总览
docs/API.md — HTTP API
docs/WEBSOCKET_API.md — WebSocket
docs/ARCHITECTURE.md — 架构
docs/DEPLOYMENT.md — 部署
mobile/docs/BLUETOOTH_PROTOCOL_QUICK_REFERENCE.md — BLE 协议