有声书聚合平台 - 技术文档

📌 快速开始： 查看 TECHNICAL_GUIDE.md 获取完整的技术指南和常见问题解答

📚 项目概述

有声书搜索和播放平台，支持多接口聚合、离线缓存、后台播放。

• Web 端：PWA 支持，离线可用
• Android APP：原生开发（Java + Kotlin），独立项目
• 后端：Flask + SQLite
• 前端：原生 JavaScript（无框架）

---

📖 核心文档

🚀 快速开始

• TECHNICAL_GUIDE.md - 完整技术指南（推荐从这里开始）
• BUILD_GUIDE.md - 构建和部署指南
• troubleshooting.md - 故障排查指南

系统架构

• architecture.md - 系统架构设计
• routes-api.md - API 路由文档
• field-naming-convention.md - 字段命名规范

用户系统

• user-system.md - 用户认证、权限、游客模式
• security.md - 安全机制、防护措施
• path-key-validation.md - 路径密钥验证系统（Android APP 安全）

音频播放

• audio-player.md - 音频播放器（Web Audio API）
• audio-player-architecture.md - 播放器架构设计
• ios-pwa-continuous-playback.md - iOS PWA 后台播放

接口系统

• interface-adapter.md - 接口适配器
• interface-test-system.md - 接口测试系统
• script-writing.md - 脚本编写指南

管理后台

• admin-panel.md - 管理后台功能
• version-management.md - 版本管理和强制更新系统
• admob-api.md - AdMob 广告集成
• app-debug-panel.md - APP 调试面板

平台相关

• platform-detection.md - 平台检测系统

其他

• deployment.md - 部署指南
• logging.md - 日志系统
• troubleshooting.md - 故障排查
• CHANGELOG_DOCS.md - 文档更新日志

---

🚀 快速开始

本地开发

# 安装依赖
pip install -r requirements.txt
npm install

# 初始化数据库
python init_db.py

# 运行开发服务器
python app.py

Android 原生应用

原生 Android 项目位于 android-native/ 目录，使用 Android Studio 开发。

详见 android-native/README.md

---

🎯 核心功能

1. 多接口聚合

• 支持多个有声书源
• 统一的接口适配层
• 自动故障转移

2. 离线缓存

• IndexedDB 存储章节数据
• 自动预加载书架书籍
• 智能缓存管理
• 批量缓存（最多3本）

3. 后台播放

• MediaSession API（Web、iOS PWA）
• 锁屏控制、通知栏控制
• iOS PWA 连续播放支持

4. 游客模式

• 自动创建游客账户
• 无需注册即可使用
• 数据持久化

5. 书架管理

• 自动同步
• 批量缓存
• 更新检测（每天一次）
• 手动更新（15分钟限制）

6. 管理后台

• 用户管理
• 接口管理
• 统计分析
• 主题定制

---

🛠️ 技术栈

后端

• 框架：Flask 3.x
• 数据库：SQLite
• 认证：Session + Remember Token
• 缓存：内存缓存

前端

• 核心：原生 JavaScript（ES6+）
• 存储：IndexedDB + localStorage
• 音频：Web Audio API + MediaSession
• PWA：Service Worker + Manifest

Android 原生应用

• 语言：Java (70%) + Kotlin (30%)
• 网络：Retrofit + OkHttp
• 播放器：ExoPlayer
• 最低版本：Android 7.0 (API 24)
• 项目位置：android-native/ 目录

---

📝 开发规范

代码风格

• Python：PEP 8
• JavaScript：ES6+ 标准
• 命名：snake_case（Python）、camelCase（JavaScript）

提交规范

feat: 新功能
fix: 修复
docs: 文档
style: 格式
refactor: 重构
perf: 性能优化
test: 测试
chore: 构建/工具

---

🔒 安全特性

• HMAC 请求签名
• CSRF 保护
• XSS 防护
• SQL 注入防护
• 频率限制
• IP 黑名单
• 设备限制

详见 security.md

---

📱 平台支持

平台	支持	说明
Chrome/Edge	✅	完全支持
Firefox	✅	完全支持
Safari	✅	完全支持
iOS PWA	✅	支持后台播放
Android 浏览器	✅	完全支持
Android 原生 APP	🚧	开发中（android-native/ 目录）

---

📞 快速导航

新增接口

1. 阅读 interface-adapter.md
2. 阅读 script-writing.md
3. 管理后台 → 接口管理 → 新建接口

用户权限问题

1. 阅读 user-system.md
2. 管理后台 → 用户管理 → 修改权限

调试问题

1. 阅读 logging.md
2. 管理后台 → 调试模式 → 开启
3. 查看 logs/debug.jsonl

Android 原生应用开发

1. 阅读 android-native/README.md
2. 使用 Android Studio 打开项目
3. 连接设备或模拟器运行

---

最后更新：2026-02-02
最近更新：整合技术文档，删除临时文档，创建 TECHNICAL_GUIDE.md 统一入口