chore(doc):add AI collaborative documents helps AI understand the project context.

2025-11-11 23:41:50 +08:00
parent 2840da2f34
commit 0c4397bf46
7 changed files with 1051 additions and 0 deletions
@@ -0,0 +1,151 @@
+# PrivyDrop AI Playbook — 代码地图（中文）
+
+本地图以“快速定位”为目标，仅给出目录与关键入口文件的简要说明，不包含“常改动点/影响范围”。
+
+## 前端（Next.js，TypeScript）
+
+- `frontend/app/` — App Router 路由与页面。
+
+  - `frontend/app/[lang]/page.tsx` — 主页入口，生成元数据和 SEO 结构化数据（JsonLd），支持多语言 canonical 链接。
+  - `frontend/app/[lang]/*/page.tsx` — 静态页面：features(功能特性)、about(关于)、faq(常见问题)、help(帮助)、terms(服务条款)、privacy(隐私政策)，均包含多语言 SEO 元数据生成。
+  - `frontend/app/[lang]/blog/page.tsx` — 博客列表页，展示多语言文章列表。
+  - `frontend/app/[lang]/blog/[slug]/page.tsx` — 博客文章详情页，支持 MDX 渲染、目录生成、面包屑导航和 JSON-LD 结构化数据。
+  - `frontend/app/[lang]/blog/tag/[tag]/page.tsx` — 博客标签页，按标签分类展示文章。
+  - `frontend/app/[lang]/layout.tsx` — 全局布局与 Provider 注入，包含 ThemeProvider、Header/Footer，生成组织架构和网站结构化数据。
+  - `frontend/app/[lang]/HomeClient.tsx` — 主客户端组件，组织页面结构（Hero 区域、ClipboardApp、HowItWorks、视频演示、系统架构图、功能特性、FAQ），支持多平台视频链接（YouTube/B 站）。
+  - `frontend/app/api/health/route.ts` — 基础健康检查 API。
+  - `frontend/app/api/health/detailed/route.ts` — 详细健康检查 API。
+  - `frontend/app/sitemap.ts` — 站点地图生成，支持多语言 URL 和博客文章动态收录。
+  - `frontend/middleware.ts` — i18n 与路由中间件。
+  - `frontend/app/config/environment.ts` — 运行时/环境配置（ICE、端点等）。
+  - `frontend/app/config/api.ts` — 后端 API 交互封装。
+
+- `frontend/components/` — UI，包括协调器与子组件。
+
+  - `frontend/components/ClipboardApp.tsx` — 顶层 UI 协调器，集成 5 个业务 hooks（useWebRTCConnection/useFileTransferHandler/useRoomManager/usePageSetup/useClipboardAppMessages），处理全局拖拽事件和双标签页（发送/接收）管理。
+  - `frontend/components/ClipboardApp/SendTabPanel.tsx` — 发送面板，集成富文本编辑器、文件上传、房间 ID 生成（支持 4 位数字/UUID 两种模式）、分享链接生成。
+  - `frontend/components/ClipboardApp/RetrieveTabPanel.tsx` — 接收面板，处理房间加入、文件接收、目录选择（File System Access API）、富文本内容显示。
+  - `frontend/components/ClipboardApp/FileListDisplay.tsx` — 文件列表显示组件，支持文件/文件夹分组显示、进度跟踪、多浏览器下载策略（Chrome 自动下载/其他浏览器手动保存）、下载计数统计。
+  - `frontend/components/ClipboardApp/FullScreenDropZone.tsx` — 全屏拖拽提示组件，文件拖拽时的视觉反馈。
+  - `frontend/components/ClipboardApp/*` — 其他子组件：FileUploadHandler（文件上传处理）、ShareCard（二维码分享）、TransferProgress（进度条）、CachedIdActionButton（缓存 ID 操作）、FileTransferButton（文件传输按钮）。
+  - `frontend/components/Editor/` — 富文本编辑器模块，包含 RichTextEditor 主编辑器、工具栏组件（BasicFormatTools/FontTools/AlignmentTools/InsertTools）、SelectMenu 下拉选择、类型定义和编辑器 hooks。
+  - `frontend/components/blog/` — 博客相关组件，包含 TableOfContents（支持中文目录生成和滚动跟踪）、Mermaid 图表渲染、MDXComponents、ArticleListItem 文章列表。
+  - `frontend/components/common/` — 通用组件，包含 clipboard_btn（读写剪贴板按钮）、AutoPopupDialog（自动弹出对话框）、LazyLoadWrapper（懒加载包装器）、YouTubePlayer（YouTube 播放器）。
+  - `frontend/components/web/` — 网站页面组件，包含 Header（响应式导航和多语言支持）、Footer（版权和语言链接）、FAQSection（可配置 FAQ 展示）、HowItWorks（步骤说明和视频演示）、SystemDiagram（系统架构图）、KeyFeatures（功能特性展示）、theme-provider 主题提供者。
+  - `frontend/components/seo/JsonLd.tsx` — SEO 结构化数据组件，支持多类型 JSON-LD 数据生成。
+  - `frontend/components/LanguageSwitcher.tsx` — 语言切换器。
+  - `frontend/components/ui/*` — 基础 UI 原子组件（基于 Radix UI 和 shadcn/ui），包含 Button（多变体按钮）、Accordion（手风琴）、Dialog（模态对话框）、Card（卡片）、Tooltip（工具提示）、Select、Input、Textarea、Checkbox、DropdownMenu、Toast 通知系统和 AnimatedButton 动画按钮。
+
+- `frontend/hooks/` — 业务逻辑中枢（React Hooks）。
+
+  - `frontend/hooks/useWebRTCConnection.ts` — WebRTC 生命周期与编排 API。
+  - `frontend/hooks/useRoomManager.ts` — 房间创建/加入/校验与 UI 状态，支持缓存 ID 重连（≥8 字符自动发送 initiator-online）。
+  - `frontend/hooks/useFileTransferHandler.ts` — 文件/文本负载编排与回调，使用 getState() 修复闭包问题，支持 JSZip 文件夹下载。
+  - `frontend/hooks/useClipboardActions.ts` — 剪贴板操作与状态管理，支持现代 API 和 document.execCommand 降级，处理 HTML/富文本粘贴。
+  - `frontend/hooks/useClipboardAppMessages.ts` — 应用消息处理（shareMessage/retrieveMessage），4 秒自动消失机制。
+  - `frontend/hooks/useLocale.ts` — 国际化语言切换，基于 pathname 解析。
+  - `frontend/hooks/usePageSetup.ts` — 页面配置与 SEO 设置，处理 URL 参数 roomId 自动加入和引荐来源追踪。
+  - `frontend/hooks/useRichTextToPlainText.ts` — 富文本转纯文本工具，处理块级元素换行和文本节点包装。
+
+- `frontend/lib/` — 核心库与工具。
+
+  - WebRTC 基础与角色
+    - `frontend/lib/webrtc_base.ts` — WebRTC 基础类，提供 Socket.IO 信令、RTCPeerConnection 管理、ICE 候选者队列、双重断开检测重连机制、唤醒锁管理、数据通道发送重试（5 次递增间隔）、优雅断开跟踪（gracefullyDisconnectedPeers Set）和多格式数据类型兼容性支持（ArrayBuffer/Blob/Uint8Array/TypedArray）。
+    - `frontend/lib/webrtc_Initiator.ts` — 发起方实现，处理`ready`/`recipient-ready`事件，创建 RTCPeerConnection 和主动式 DataChannel，发送 offer，处理 answer 响应，支持 256KB 缓冲阈值配置。
+    - `frontend/lib/webrtc_Recipient.ts` — 接收方实现，处理`offer`事件，创建 RTCPeerConnection 和响应式 DataChannel（ondatachannel），生成并发送 answer，处理`initiator-online`重连信号和现有连接清理。
+    - `frontend/lib/webrtcService.ts` — WebRTC 服务单例封装，管理 sender/receiver 实例，提供统一业务接口，处理连接状态变更、数据广播、文件请求和连接断开清理。
+  - 发送（sender）
+    - `frontend/lib/fileSender.ts` — 发送端向后兼容包装层，内部使用 FileTransferOrchestrator 提供统一服务。
+    - `frontend/lib/transfer/FileTransferOrchestrator.ts` — 发送端主编排器，集成所有组件管理文件传输生命周期。
+    - `frontend/lib/transfer/StreamingFileReader.ts` — 高性能流式文件读取器，采用 32MB 批次+64KB 网络块的双层缓冲架构。
+    - `frontend/lib/transfer/NetworkTransmitter.ts` — 网络传输器，使用 WebRTC 原生背压控制，支持嵌入元数据分片发送。
+    - `frontend/lib/transfer/StateManager.ts` — 状态管理中心，跟踪 peer 状态、待发送文件、文件夹元数据。
+    - `frontend/lib/transfer/ProgressTracker.ts` — 进度跟踪器，处理文件/文件夹进度计算、速度统计和回调触发。
+    - `frontend/lib/transfer/MessageHandler.ts` — 消息处理器，负责 WebRTC 消息路由（fileRequest/fileReceiveComplete/folderReceiveComplete）。
+    - `frontend/lib/transfer/TransferConfig.ts` — 传输配置管理，定义文件读取 4MB 分片、32MB 批次、64KB 网络发送块。
+  - 接收（receiver）
+    - `frontend/lib/fileReceiver.ts` — 接收端向后兼容包装层，内部使用 FileReceiveOrchestrator 提供统一服务。
+    - `frontend/lib/receive/FileReceiveOrchestrator.ts` — 接收端主编排器，集成所有组件管理文件接收生命周期，支持断点续传和磁盘流式写入。
+    - `frontend/lib/receive/ReceptionStateManager.ts` — 状态管理中心，管理文件元数据、活跃接收状态、文件夹进度、保存类型配置。
+    - `frontend/lib/receive/ChunkProcessor.ts` — 分片处理器，处理多种数据格式转换、嵌入元数据解析、分片验证和索引映射。
+    - `frontend/lib/receive/StreamingFileWriter.ts` — 流式文件写入器，包含 SequencedDiskWriter 严格顺序写入机制，支持大文件磁盘流式写入。
+    - `frontend/lib/receive/FileAssembler.ts` — 内存文件组装器，处理小块文件的内存重组、完整性校验和文件对象创建。
+    - `frontend/lib/receive/MessageProcessor.ts` — 消息处理器，负责 WebRTC 消息路由（fileMeta/stringMetadata/fileRequest/folderReceiveComplete）。
+    - `frontend/lib/receive/ProgressReporter.ts` — 进度报告器，处理文件/文件夹进度计算、速度统计和节流回调。
+    - `frontend/lib/receive/ReceptionConfig.ts` — 接收配置管理，定义大文件阈值 1GB、64KB 分片、缓冲区大小和调试开关。
+  - 工具与辅助
+    - `frontend/lib/fileReceiver.ts`、`frontend/lib/fileUtils.ts`、`frontend/lib/speedCalculator.ts`、`frontend/lib/utils.ts` — 基础工具。
+    - `frontend/lib/roomIdCache.ts` — 房间 ID 缓存管理。
+    - `frontend/lib/wakeLockManager.tsx` — 屏幕唤醒锁管理（移动端优化）。
+    - `frontend/lib/utils/ChunkRangeCalculator.ts` — 文件分片范围计算。
+    - `frontend/lib/browserUtils.ts` — 浏览器兼容性工具。
+    - `frontend/lib/tracking.ts` — 用户行为追踪。
+    - `frontend/lib/dictionary.ts`、`frontend/lib/mdx-config.ts`、`frontend/lib/blog.ts` — i18n/内容与 SEO 辅助。
+
+- `frontend/stores/` — 共享应用状态（Zustand）。
+
+  - `frontend/stores/fileTransferStore.ts` — 传输进度/状态的唯一事实来源。
+
+- `frontend/types/`、`frontend/constants/` — 类型定义与常量。
+
+  - `frontend/types/global.d.ts` — 全局类型定义（lodash 模块、FileSystemDirectoryHandle 接口）。
+  - `frontend/types/messages.ts` — 多语言消息与 UI 内容类型定义（Meta、Text、Messages 等国际化结构）。
+  - `frontend/types/webrtc.ts` — WebRTC 传输协议类型（文件元数据、分片结构、状态机接口）。
+  - `frontend/constants/messages/` — 多语言消息文件（7 种语言：en、zh、de、es、fr、ja、ko）。
+  - `frontend/constants/i18n-config.ts` — 国际化配置（默认语言、支持语言列表、显示名称映射）。
+
+- `frontend/content/` — 内容资源。
+
+  - `frontend/content/blog/` — 博客文章（MDX 格式，多语言），包含开源发布、WebRTC 文件传输、断点续传等主题文章。
+  - `frontend/lib/blog.ts` — 博客工具函数，支持多语言文章读取、frontmatter 解析、标签提取和内容验证。
+
+- **配置与构建**
+  - `frontend/package.json`、`frontend/tsconfig.json`、`frontend/tailwind.config.ts` — 项目配置。
+  - `frontend/next.config.mjs`、`frontend/postcss.config.mjs`、`frontend/components.json` — Next.js 与组件配置。
+  - `frontend/.eslintrc.json` — 代码检查配置。
+  - `frontend/Dockerfile`、`frontend/health-check.js` — Docker 部署与健康检查。
+
+## 后端（Express，Socket.IO，Redis）
+
+- `backend/src/server.ts` — 启动入口：Express + Socket.IO 初始化与监听。
+- `backend/src/config/env.ts`、`backend/src/config/server.ts` — 环境与服务配置。
+  - `backend/src/config/env.ts` — 环境变量配置与验证，包含端口、CORS、Redis 连接设置，支持开发/生产环境自动加载对应.env 文件。
+  - `backend/src/config/server.ts` — CORS 配置，区分开发/生产环境，支持多域名配置和 LAN 地址正则匹配。
+- `backend/src/routes/api.ts` — REST：房间创建/校验、追踪、调试日志。
+- `backend/src/routes/health.ts` — 健康检查。
+- `backend/src/socket/handlers.ts` — 信令事件：`join`、`initiator-online`、`recipient-ready`、`offer`、`answer`、`ice-candidate`。
+- `backend/src/services/redis.ts` — Redis 客户端。
+- `backend/src/services/room.ts` — 房间/成员存储与辅助。
+- `backend/src/services/rateLimit.ts` — 基于 Redis 有序集的 IP 限流。
+- `backend/src/types/room.ts`、`backend/src/types/socket.ts` — 类型定义与接口。
+
+  - `backend/src/types/socket.ts` — Socket.IO 相关类型，包含 JoinData 房间加入数据、SignalingData WebRTC 信令数据(offer/answer/candidate)、InitiatorData 发起方数据、RecipientData 接收方数据。
+  - `backend/src/types/room.ts` — 房间相关类型，包含 RoomInfo 房间信息(创建时间)、ReferrerTrack 来源追踪数据、LogMessage 日志消息结构。
+
+- **后端配置与脚本**
+  - `backend/package.json`、`backend/tsconfig.json` — 项目配置。
+  - `backend/Dockerfile`、`backend/.dockerignore` — Docker 配置。
+  - `backend/health-check.js` — 健康检查脚本。
+  - `backend/scripts/export-tracking-data.js` — 数据导出脚本。
+  - `backend/docker/` — Docker 相关配置与脚本（包含 Nginx、TURN 服务器配置）。
+
+## 部署与运维
+
+- **根目录配置**
+
+  - `docker-compose.yml`、`ecosystem.config.js` — Docker Compose 与 PM2 配置。
+  - `build-and-deploy.sh`、`deploy.sh` — 构建与部署脚本。
+  - `deploy.config_prod`、`deploy.config_test` — 生产与测试环境配置。
+
+- **Docker 基础设施**
+
+  - `docker/nginx/` — Nginx 反向代理配置。
+  - `docker/scripts/` — 部署相关脚本（环境检测、配置生成、部署测试）。
+  - `docker/ssl/` — SSL 证书目录。
+  - `docker/coturn/` — TURN 服务器配置。
+  - `docker/letsencrypt-www/` — Let's Encrypt 配置。
+
+- **构建与文档**
+  - `build/` — 请忽略这个临时目录。
+  - `test-health-apis.sh` — 健康 API 测试脚本。
+  - `README.md`、`README.zh-CN.md`、`ROADMAP.md`、`ROADMAP.zh-CN.md` — 项目文档。
@@ -0,0 +1,149 @@
+# PrivyDrop AI Playbook — 协作规则（中文）
+
+本规则面向“人类开发者 + AI 助手”的协作，确保在保持隐私立场与技术基线的前提下，高效而可控地演进代码。与目录索引（index.zh-CN.md）和流程地图（flows.zh-CN.md）互补：它约束“如何做”，不复述“做什么”。
+
+- 适用范围：本仓库全部代码与文档
+- 读者对象：人类开发者、AI 助手、评审者
+- 变更原则：最佳实践优先、一次只解决一类问题、可回滚、可验证
+
+## 一、协作原则
+
+- Best Practices 优先：选用经过验证且与现有栈一致的方案，避免“自造轮子”。
+- 单一主题：每个变更聚焦一个目标，避免“顺手修复”无关问题。
+- 隐私立场：严禁引入服务器中转文件数据的实现或建议；后端仅做信令与房间协调。
+- 小步快跑：小 PR、易回滚，优先最小可行改动。
+- 可追溯：提交信息、PR 描述、代码注释清晰、可复现。
+
+## 二、计划先行（强约束）
+
+任何实现前，必须先提交“变更计划”，经同意后再实施。计划应包含：目标、影响范围与文件列表、方案概述、风险与缓解、验收标准、回滚策略、需更新的文档、验证方式。
+
+推荐模板见“模板”章节。实施前需阅读并引用：
+
+- docs/ai-playbook/index.zh-CN.md
+- docs/ai-playbook/code-map.zh-CN.md
+- docs/ai-playbook/flows.zh-CN.md
+
+## 三、语言与注释
+
+- 沟通语言：与项目负责人沟通一律使用中文（简体）。
+- 代码注释、导出符号命名、提交信息、PR 标题/描述一律英文。
+- 用户/市场文档可中英双语；本协作规则为中文。
+- 导出函数、复杂流程、公共类型使用 TSDoc/JSDoc（英文），保证 API 可读性。
+
+## 四、Next.js（前端）约定
+
+- App Router 默认 Server Components；仅在确需交互时使用 "use client"。
+- 复用现有 UI（Tailwind + shadcn/ui + Radix）；未经批准不引入新组件库。
+- i18n：所有可见文案走字典与 `frontend/app/[lang]` 路由，不在组件内硬编码。
+- 命名与文件：
+  - 组件：PascalCase 文件与导出（ExampleCard.tsx）
+  - Hooks：camelCase 文件，导出以 use\* 开头（useSomething.ts）
+  - 类型/常量集中维护，避免循环依赖
+- SEO：使用 Next Metadata 与 `frontend/components/seo/JsonLd.tsx`；页面需补 canonical、多语言链接。
+- 性能与可访问性：按需动态导入重组件；确保 aria/焦点管理基本可用。
+
+## 五、TypeScript 与风格
+
+- 类型严格，避免 any；必要时用 unknown 并显式收窄；导出函数显式返回类型。
+- 遵循现有 ESLint/Prettier 与路径别名（`@/...`）；不引入新格式化器。
+- 函数小而清晰；复杂逻辑下沉到 service/util，组件只消费不变更状态。
+- 不使用一字母变量名；避免魔法数，集中到常量。
+
+## 六、WebRTC/传输“护栏”（不得突破）
+
+- 保持既定策略：32MB 批次 + 64KB 网络块；DataChannel bufferedAmountLowThreshold 与 maxBuffer 策略不随意更改。
+- 断点续传、严格顺序写入、多格式兼容是默认能力，禁止降级或移除。
+- 信令与消息名（offer/answer/ice-candidate 等）保持兼容；如需破坏性变更，必须走“必须请示”流程。
+- 重连与队列处理（ICE 候选缓存、背压、发送重试）策略保持一致，变更需风险评估与充分验证。
+- 严禁将文件内容（任何形式）发往服务器或第三方服务。
+
+## 七、后端约束（信令服务）
+
+- 仅负责信令与房间管理；不落地用户文件数据；日志中不得包含敏感内容或原始 payload。
+- 速率与滥用防护保留；如需扩展接口，必须保证向后兼容或提供迁移策略。
+
+## 八、依赖与安全
+
+- 新依赖需在计划中论证：体积（含 ESM/SSR 兼容性）、维护健康度、许可、替代方案、安全影响。
+- 不引入遥测/埋点；不将敏感数据写入日志；最小权限原则。
+- 配置通过环境变量注入；严禁在仓库中硬编码密钥或服务端点。
+
+## 九、文档同步更新
+
+- 代码改动若影响流程、接口或关键文件入口，须同步更新：
+  - docs/ai-playbook/flows.zh-CN.md
+  - docs/ai-playbook/code-map.zh-CN.md
+- PR 必须列出“受影响文档”，避免 AI Playbook 过时；索引页（index.zh-CN.md）保持简洁，仅新增链接时更新。
+
+## 十、验证与回归
+
+- 前端：能构建通过（next build）；关键路径手测说明（至少：创建/加入房间、单/多文件、文件夹、大文件、断点续传、双浏览器互传、i18n 路由与 SEO 元数据）。
+- 后端：Socket.IO 基本流程可用。
+- 回归清单：重连流程、下载计数与状态清理、Store 单一数据源约束、浏览器兼容（Chromium/Firefox）。
+
+## 十一、必须请示（需先获批）
+
+- 协议/消息名/公共 API/存储格式的破坏性变更。
+- 影响隐私立场或跨边界的架构调整（如任何形式的中转或持久化）。
+- 引入新依赖、新基础设施或大规模重构。
+- 修改传输“护栏”参数（分片、背压、重试等）。
+
+## 十二、常见误区
+
+- 组件内直改全局状态（违背单向数据流）。
+- 只改代码不更文档，导致 Playbook 过期。
+- 使用 any 绕过类型与边界检查。
+- 将 UI 文案硬编码在组件内，绕过字典/i18n。
+- 擅自调整 WebRTC 关键参数，导致隐性性能回退或兼容性问题。
+
+## 十三、模板
+
+变更计划模板
+
+```
+Title: <简明标题>
+
+Goals
+- <预期达成的目标>
+
+Scope / Files
+- <将修改与新增的文件路径清单 + 原因>
+
+Approach
+- <实现思路与关键设计点>
+
+Risks & Mitigations
+- <主要风险> → <缓解策略>
+
+Acceptance Criteria
+- <可验证的验收项>
+
+Rollback
+- <如何快速回滚>
+
+Docs to Update
+- code-map.zh-CN.md / flows.zh-CN.md / README(.zh-CN).md / others?
+
+Validation
+- Build: next build / backend health
+- Manual: <列出关键用例>
+```
+
+PR 校验清单
+
+```
+- [ ] 仅包含单一主题改动
+- [ ] 代码注释与提交信息为英文
+- [ ] 未引入未批准的依赖/组件库
+- [ ] i18n 与 SEO 按约定接入（如适用）
+- [ ] 传输护栏未被破坏（或已获批且有验证）
+- [ ] flows / code-map 文档已同步
+- [ ] 附带验证说明与回归清单
+```
+
+## 十四、引用与快速入口
+
+- 索引与上下文：docs/ai-playbook/index.zh-CN.md
+- 代码地图：docs/ai-playbook/code-map.zh-CN.md
+- 关键流程：docs/ai-playbook/flows.zh-CN.md
@@ -0,0 +1,684 @@
+# PrivyDrop AI Playbook — 流程（含微方案模板，中文）
+
+本文汇总 P2P 传输与信令重连的关键流程与消息序列，并给出简明的调试要点与“微方案模板”。用于在改动前快速对齐阶段、事件与入口文件。
+
+## 1）文件传输（单文件）
+
+序列（通过 DataChannel，发送端 ↔ 接收端）：
+
+1. 发送端 → `fileMetadata`（id、name、size、type、fullName、folderName）。
+2. 接收端 → `fileRequest`（确认元信息；支持 offset 续传）。
+3. 发送端 → 分片流（高性能双层缓冲架构）：
+   - StreamingFileReader 使用 32MB 批次读取 + 64KB 网络块发送
+   - NetworkTransmitter 使用 WebRTC 原生背压控制（bufferedAmountLowThreshold）
+   - 发送时嵌入元数据（chunkIndex、totalChunks、fileOffset、fileId）
+4. 接收端 → 完整性检查与组装（严格顺序写入或内存组装，支持断点续传）。
+5. 接收端 → `fileReceiveComplete`（成功回执，包含 receivedSize）。
+6. 发送端 → MessageHandler 触发 100% 进度回调，清理发送状态。
+
+发送侧详细流程：
+
+1. FileTransferOrchestrator.sendFileMeta() → StateManager 记录文件夹文件大小
+2. 接收 fileRequest → FileTransferOrchestrator.handleFileRequest()
+3. 初始化 StreamingFileReader（支持 startOffset 续传）
+4. processSendQueue() 循环：
+   - getNextNetworkChunk() 获取 64KB 块（批次内高效切片）
+   - NetworkTransmitter.sendEmbeddedChunk() 背压控制发送
+   - ProgressTracker.updateFileProgress() 更新进度和速度
+5. 等待 fileReceiveComplete 确认，清理 isSending 状态
+
+入口：
+
+- 发送侧：`frontend/lib/fileSender.ts`（兼容层）→ `frontend/lib/transfer/FileTransferOrchestrator.ts`（主编排器）
+- 关键组件：StreamingFileReader（高性能读取）、NetworkTransmitter（背压发送）、StateManager（状态管理）、ProgressTracker（进度计算）
+
+接收侧详细流程：
+
+1. MessageProcessor.handleFileMetadata() → ReceptionStateManager 记录文件元数据
+2. FileReceiveOrchestrator.requestFile() → 检查断点续传（getPartialFileSize）
+3. 初始化接收：计算期望分片数，根据文件大小选择存储方式（内存 vs 磁盘）
+4. 发送 fileRequest（带 offset 参数）→ 等待发送端开始传输
+5. handleBinaryChunkData() 循环：
+   - ChunkProcessor.convertToArrayBuffer() 处理多种数据格式（Blob/Uint8Array/ArrayBuffer）
+   - ChunkProcessor.parseEmbeddedChunkPacket() 解析嵌入元数据包格式
+   - ChunkProcessor.validateChunk() 验证 fileId、chunkIndex、chunkSize
+   - 存储分片到 chunks 数组（或通过 SequencedDiskWriter 顺序写入磁盘）
+   - ProgressReporter.updateFileProgress() 节流更新进度（100ms 间隔）
+6. 自动完成检测：checkAndAutoFinalize() 验证分片完整性
+7. 根据存储方式选择最终化：
+   - 大文件/磁盘存储：StreamingFileWriter.finalizeWrite()
+   - 小文件/内存存储：FileAssembler.assembleFileFromChunks()
+8. 发送 fileReceiveComplete 确认，包含 receivedSize 和 receivedChunks
+
+入口：
+
+- 发送侧：`frontend/lib/fileSender.ts`（兼容层）→ `frontend/lib/transfer/FileTransferOrchestrator.ts`（主编排器）
+- 接收侧：`frontend/lib/fileReceiver.ts`（兼容层）→ `frontend/lib/receive/FileReceiveOrchestrator.ts`（主编排器）
+- 关键组件：StreamingFileReader（高性能读取）、NetworkTransmitter（背压发送）、ChunkProcessor（格式处理）、StreamingFileWriter（磁盘写入）、FileAssembler（内存组装）
+
+备注：
+
+- **发送侧**：双层缓冲架构（32MB 批次+64KB 网络块），WebRTC 原生背压控制，支持断点续传
+- **接收侧**：严格顺序写入机制（SequencedDiskWriter），支持多种数据格式转换，智能存储选择（≥1GB 文件自动磁盘存储）
+- **兼容性处理**：ChunkProcessor 支持 Blob/Uint8Array/ArrayBuffer 多种格式，解决 Firefox 兼容性问题
+- **进度节流**：ProgressReporter 使用不同频率更新（文件 100ms，文件夹 200ms），避免 UI 过载
+- **断点续传**：通过 getPartialFileSize() 检查本地部分文件，fileRequest.offset 参数指定续传位置
+- **调试支持**：ReceptionConfig 提供详细的分片日志和进度日志，便于问题排查
+
+## 2）文件传输（文件夹）
+
+序列（对文件逐个进行单文件流程）：
+
+1. 发送端 → 发送文件夹内全部文件的 `fileMetadata`。
+2. 接收端 → `folderRequest`（确认开始批量传输）。
+3. 每个文件：按“单文件流程”执行，但单个文件完成时不标记全局 100%。
+4. 接收端 → 所有文件完成后发送 `folderReceiveComplete`。
+5. 发送端 → 将文件夹整体进度标记为 100%（触发最终回调）。
+
+## 3）信令与重连（Socket.IO）
+
+高层序列：
+
+1. 客户端 → REST：创建或获取 `roomId`（`backend/src/routes/api.ts`）。
+2. 客户端 → Socket.IO：`join` 房间（后端校验并绑定 socket 到房间）。
+3. 在房间内进行在线状态与重连协作：
+   - 发起方 → `initiator-online`（上线/就绪，通知对端可重建连接）。
+   - 接收方 → `recipient-ready`（表示就绪；发起方可发起 offer）。
+4. WebRTC 协商转发：
+   - `offer` → 后端 → 转发给对端。
+   - `answer` → 后端 → 转发给对端。
+   - `ice-candidate` → 后端 → 转发给对端。
+
+重连机制细节（移动端网络切换支持）：
+
+- **双重断开检测**：Socket.IO 断开触发 `disconnect` 事件 → 标记 `isSocketDisconnected = true`；P2P 连接断开触发 `disconnected` 状态 → 标记 `isPeerDisconnected = true`，自动调用 `cleanupExistingConnection()` 清理资源
+- **重连触发条件**：仅当 socket 和 P2P 都断开时才启动重连 → `attemptReconnection()`，防止重复重连；使用 `reconnectionInProgress` 标志防止并发重连
+- **状态恢复机制**：重连时调用 `joinRoom(roomId, isInitiator, sendInitiatorOnline)` 恢复状态，发送方自动发送 `initiator-online` 信号，接收方响应 `recipient-ready`
+- **ICE 候选者队列机制**：连接未就绪时缓存候选者到 `iceCandidatesQueue` Map，连接就绪后批量处理；支持候选者失效时的重新入队和连接状态验证
+- **唤醒锁管理**：连接建立时通过 `WakeLockManager` 请求屏幕唤醒锁，连接断开时释放，优化移动端传输稳定性
+- **优雅断开跟踪**：`gracefullyDisconnectedPeers` Set 跟踪正常断开的 peer，发送重试时跳过这些 peer，避免不必要的重试
+- **数据通道发送重试**：5 次重试机制，间隔从 100ms 递增到 1000ms，支持 `gracefullyDisconnectedPeers` 检测跳过重试
+
+**后端信令与房间管理**：
+
+Socket.IO 事件处理流程：
+
+1. **join 事件**：IP 限流检查 → 房间存在性验证 → socket-room 绑定 → 成功响应 → 广播 `ready` 通知新用户加入
+2. **重连状态同步**：发送方重连时发送 `initiator-online` 信号，接收方响应 `recipient-ready` 确认就绪状态
+3. **信令转发**：offer/answer/ice-candidate 直接通过 `socket.to(peerId).emit()` 转发给目标客户端，包含 from 字段标识发送者
+4. **断开清理**：广播 `peer-disconnected` → 解绑 socket-room 关系 → 空房间 15 分钟后删除
+
+**房间管理机制**：
+
+- Redis 数据结构：
+  - `room:<roomId>` (Hash): 存储房间创建时间
+  - `room:<roomId>:sockets` (Set): 管理房间内 socket 连接
+  - `socket:<socketId>` (String): 存储 socket 对应的 roomId
+- ID 生成策略：优先 4 位数字 ID，冲突时切换到 4 位字母数字 ID
+- 幂等设计：长 ID(≥8 字符)支持重连时的房间复用
+- TTL 管理：24 小时过期，活动时自动刷新
+
+**限流保护**：
+
+- 基于 Redis Sorted Set 实现 IP 限流
+- 5 秒时间窗口最多允许 2 次请求
+- 使用 pipeline 确保原子性操作
+
+入口：
+
+- 前端：`frontend/hooks/useWebRTCConnection.ts`、`frontend/lib/webrtc_base.ts`、`frontend/lib/webrtc_Initiator.ts`、`frontend/lib/webrtc_Recipient.ts`。
+- 后端：`backend/src/socket/handlers.ts`（全部信令事件）、`backend/src/services/room.ts`、`backend/src/routes/api.ts`。
+
+## 4）DataChannel 消息与约束（概览）
+
+- 消息（示例命名）：`fileMetadata`、`fileRequest`、`chunk`、`fileReceiveComplete`、`folderRequest`、`folderReceiveComplete`，以及可能的流控/保活。
+- 核心字段：文件/文件夹 id、索引/范围、大小、名称、可选校验信息。
+- 关键约束：
+  - 分片大小：按浏览器/网络选择安全范围；注意通道缓冲阈值。
+  - 背压：检查 `RTCDataChannel.bufferedAmount` 并按需节流。
+  - 完成：仅在收到 `fileReceiveComplete`/`folderReceiveComplete` 后标记 100%。
+  - 续传：`fileRequest` 可设计为带 offset/range 以支持续传。
+
+## 5）调试要点（凝练自历史经验）
+
+- 下载竞争/重复计数：以 `frontend/stores/fileTransferStore.ts` 为单一事实来源；在 Store 层提供清理 API（如 `clearSendProgress`、`clearReceiveProgress`），避免组件本地删除对象导致重复计数。
+- 接收方重连与房间状态：正确的状态重置；UI 严格来源于 Store；离开/重进需清理相关状态；遵循 `initiator-online`/`recipient-ready` 的时序再发起 offer；重连后校验房间成员关系。
+- 缓存 roomId 的重连：若存在缓存 `roomId`，确保依赖在线状态同步（`initiator-online`/`recipient-ready`）触发重新协商；后端需保证 socket↔room 映射在断开/重连路径上被正确清理与恢复。
+- 多次传输计数：避免过度“去重”掩盖真实的二次下载；依赖正确的状态清理。
+- 数据流原则：单向数据流（Store → Hooks → Components）；Hooks 做适配，组件只消费不修改。
+- **实用调试策略**：
+  - 为连接状态变化与 Store 更新添加结构化日志；遇到时序/竞态可用 `setTimeout(..., 0)` 调整更新顺序
+  - DataChannel 发送重试机制：`sendToPeer()` 支持 5 次重试，间隔 100ms→1000ms 递增；优雅断开的 peer 跳过重试
+  - WebRTC 数据类型兼容性：支持 `ArrayBuffer`/`Blob`/`Uint8Array`/`TypedArray` 多种格式，解决 Firefox 兼容性问题
+  - 连接状态监控：`connectionState` 变化时触发相应的处理逻辑（connected/disconnected/failed/closed）
+  - 背压控制：DataChannel 设置 `bufferedAmountLowThreshold = 256KB`，发送时检查 `bufferedAmount` 状态
+
+## 6）前端组件系统与业务中枢协作流程
+
+### 组件架构层级
+
+```
+App Router (page.tsx/layout.tsx)
+    ↓
+HomeClient (页面布局与SEO)
+    ↓
+ClipboardApp (顶层UI协调器)
+    ↓
+SendTabPanel/RetrieveTabPanel (功能面板)
+    ↓
+业务中枢 Hooks (状态管理与业务逻辑)
+    ↓
+Core Services (webrtcService) + Store (fileTransferStore)
+```
+
+### ClipboardApp 顶层协调器模式
+
+**核心职责**：
+
+- 集成 5 个关键业务 hooks：useWebRTCConnection、useFileTransferHandler、useRoomManager、usePageSetup、useClipboardAppMessages
+- 全局拖拽事件处理：dragenter/dragleave/dragover/drop，支持多文件和文件夹树遍历
+- 双标签页状态管理：发送/接收面板切换，通过 activeTab 控制
+- 统一消息系统：shareMessage/retrieveMessage 4 秒自动消失机制
+
+### Hook 层级与职责分离
+
+**useWebRTCConnection**（状态桥梁）：
+
+- 计算全局传输状态（isAnyFileTransferring）
+- 暴露 webrtcService 方法（broadcastDataToAllPeers、requestFile、requestFolder）
+- 提供连接重置方法（resetSenderConnection、resetReceiverConnection）
+
+**useFileTransferHandler**（文件与内容管理）：
+
+- 文件操作：addFilesToSend（去重）、removeFileToSend
+- 下载功能：handleDownloadFile（支持文件夹压缩下载）
+- 关键修复：使用 `useFileTransferStore.getState()` 获取最新状态，避免闭包问题
+- 重试机制：最大 3 次重试，50ms 间隔，详细错误日志
+
+**useRoomManager**（房间生命周期管理）：
+
+- 房间操作：joinRoom（支持缓存 ID 重连）、processRoomIdInput（750ms 防抖）
+- 离开保护：传输中确认提示（isAnyFileTransferring 检查）
+- 状态文本：动态更新房间状态文本
+- 链接生成：自动生成分享链接
+
+**usePageSetup**（页面初始化）：
+
+- 国际化消息加载与错误处理
+- URL 参数处理：roomId 自动提取并触发加入房间（200ms 延迟确保 DOM 就绪）
+- 引荐来源追踪（trackReferrer）
+
+**useClipboardAppMessages**（消息管理）：
+
+- 分离式消息状态：shareMessage（发送相关）和 retrieveMessage（接收相关）
+- 统一消息显示接口：putMessageInMs(message, isShareEnd, displayTimeMs)
+- 自动清理机制：4 秒后自动清空消息状态
+
+### 面板组件特化设计
+
+**SendTabPanel 发送面板**：
+
+- 房间 ID 双模式生成：4 位数字（后端 API 生成）和 UUID（前端 crypto API）
+- 富文本编辑器集成（动态导入，SSR 禁用）
+- 文件上传处理和文件列表管理
+- 分享链接生成与二维码显示
+
+**RetrieveTabPanel 接收面板**：
+
+- File System Access API 集成：目录选择和直接保存到磁盘
+- 富文本内容渲染（dangerouslySetInnerHTML）
+- 文件请求和下载状态管理
+- 保存位置选择和大文件/文件夹提示
+
+**FileListDisplay 文件列表**：
+
+- 智能文件/文件夹分组和统计显示
+- 多浏览器下载策略：Chrome 自动下载，其他浏览器手动保存提示
+- 下载计数统计和传输进度跟踪
+- 断点续传和存储方式显示（内存/磁盘）
+
+### 关键用户体验优化
+
+1. **下载状态闭包修复**：`useFileTransferHandler.ts:110` 使用 `useFileTransferStore.getState()` 获取最新状态
+2. **房间 ID 输入防抖**：`useRoomManager.ts:247` 使用 lodash debounce 750ms 延迟验证
+3. **传输中离开保护**：`useRoomManager.ts:164,218` 检查 `isAnyFileTransferring` 状态并显示确认对话框
+4. **缓存 ID 重连**：`useRoomManager.ts:91` 检测长 ID（≥8 字符）自动发送 `initiator-online`
+5. **文件夹压缩下载**：`useFileTransferHandler.ts:89` 使用 JSZip 动态创建 ZIP 文件
+6. **全局拖拽优化**：ClipboardApp 使用 dragCounter 防止拖拽状态误判，支持 webkitGetAsEntry 文件树遍历
+7. **剪贴板兼容性**：useClipboardActions 支持现代 navigator.clipboard API 和 document.execCommand 降级方案
+8. **富文本安全处理**：useRichTextToPlainText 服务端渲染安全，客户端 DOM 转换处理块级元素
+
+### 前端组件架构特化
+
+**富文本编辑器模块**：
+
+- **RichTextEditor**：主编辑器组件，支持 contentEditable、图片粘贴、格式化工具、SSR 禁用
+- **工具栏组件分离**：BasicFormatTools（粗体/斜体/下划线）、FontTools（字体/大小/颜色）、AlignmentTools（对齐）、InsertTools（链接/图片/代码块）
+- **类型安全设计**：完整的 TypeScript 类型定义（FormatType、AlignmentType、FontStyleType、CustomClipboardEvent）
+- **编辑器 Hooks**：useEditorCommands（命令执行）、useSelection（选择管理）、useStyleManagement（样式管理）
+
+**网站页面组件设计**：
+
+- **Header 响应式导航**：桌面端水平导航+移动端汉堡菜单，集成 GitHub 链接和语言切换器
+- **Footer 国际化**：动态版权年份、多语言支持链接显示，使用 languageDisplayNames 配置
+- **FAQSection 灵活配置**：支持工具页面/独立页面切换、标题级别控制、自动 FAQ 数组生成
+- **内容展示组件**：HowItWorks（步骤动画+视频）、SystemDiagram（架构图）、KeyFeatures（图标+特性说明）
+
+**UI 组件库架构**：
+
+- **基于 Radix UI**：Button（CVA 多变体系统）、Accordion（手风琴）、Dialog（模态对话框）、Select、DropdownMenu
+- **设计系统一致性**：统一的 cn 工具函数、主题色彩系统、动画过渡效果
+- **组件组合模式**：DialogHeader/DialogFooter/DialogTitle/DialogDescription 组合设计
+- **懒加载优化**：LazyLoadWrapper 使用 react-intersection-observer，支持 rootMargin 配置防止布局跳动
+
+**通用组件工具化**：
+
+- **clipboard_btn**：WriteClipboardButton/ReadClipboardButton 分离设计，集成 useClipboardActions hook，支持国际化消息
+- **TableOfContents**：支持中文标题 ID 生成、滚动跟踪、层级缩进、IntersectionObserver 监听
+- **JsonLd SEO**：多类型数据支持、suppressHydrationWarning、数组/单对象处理
+- **AutoPopupDialog/YouTubePlayer**：业务场景封装，复用性设计
+
+### 数据流模式
+
+- **单向数据流**：Store → Hooks → Components
+- **状态管理集中化**：所有状态通过 `useFileTransferStore` 统一管理
+- **错误处理标准化**：统一的消息提示机制（putMessageInMs）
+- **国际化集成**：useLocale + getDictionary 提供多语言支持
+
+## 7）背压与分片策略深度分析
+
+### 发送侧双层缓冲架构
+
+**设计原理**：
+
+- **文件读取层**：4MB 分片减少 FileReader 调用，8 个分片组成 32MB 批次
+- **网络传输层**：64KB 小块适配 WebRTC DataChannel 限制，避免 sendData failed 错误
+- **性能优化**：批次内高效切片，一次 FileReader.read()产生 512 个网络块
+
+**配置参数**：
+
+```typescript
+TransferConfig.FILE_CONFIG = {
+  CHUNK_SIZE: 4194304, // 4MB - 文件读取分片
+  BATCH_SIZE: 8, // 8个分片 = 32MB批次
+  NETWORK_CHUNK_SIZE: 65536, // 64KB - WebRTC安全发送大小
+};
+```
+
+**背压控制机制**：
+
+- **DataChannel 阈值**：`bufferedAmountLowThreshold = 256KB`（Initiator）和`512KB`（NetworkTransmitter）
+- **最大缓冲限制**：`maxBuffer = 1MB`，超过时等待背压释放
+- **异步等待策略**：监听`bufferedamountlow`事件，支持超时机制（10 秒）
+
+**嵌入元数据包格式**：
+
+```
+[4字节长度][JSON元数据][实际数据块]
+```
+
+- 每个网络块都包含：chunkIndex、totalChunks、fileOffset、fileId、isLastChunk
+- 接收端可独立解析，无需依赖额外状态
+
+### 接收侧智能存储策略
+
+**存储选择逻辑**：
+
+```typescript
+ReceptionConfig.shouldSaveToDisk(fileSize, hasSaveDirectory);
+```
+
+- **内存存储**：文件 < 1GB 且未指定保存目录
+- **磁盘存储**：文件 ≥ 1GB 或用户选择了保存目录
+- **缓冲管理**：最多缓存 100 个分片（约 6.4MB）
+
+**分片验证机制**：
+
+- **格式兼容**：支持 ArrayBuffer/Blob/Uint8Array/TypedArray 多种格式
+- **完整性检查**：验证 fileId、chunkIndex、chunkSize 一致性
+- **Firefox 兼容**：Blob size 检测和转换错误处理
+
+**严格顺序写入**：
+
+- **SequencedDiskWriter**：确保分片按序写入磁盘，支持大文件流式处理
+- **断点续传**：通过`getPartialFileSize()`检查本地部分文件
+- **自动完成检测**：`checkAndAutoFinalize()`验证分片完整性
+
+### 性能优化细节
+
+**发送侧优化**：
+
+- **批量读取**：32MB 批次减少 I/O 操作，提升大文件读取性能
+- **网络适配**：64KB 块平衡传输效率与浏览器兼容性
+- **背压响应**：利用 WebRTC 原生背压控制，避免数据丢失
+
+**接收侧优化**：
+
+- **格式转换**：ChunkProcessor 统一处理多种数据格式
+- **进度节流**：文件 100ms、文件夹 200ms 间隔更新，避免 UI 过载
+- **内存管理**：小文件内存组装，大文件直接写入磁盘
+
+**错误处理**：
+
+- **发送重试**：NetworkTransmitter 返回 boolean 状态，支持上层重试逻辑
+- **转换容错**：Blob conversion failed 时返回 null，不中断整体传输
+- **超时保护**：文件完成 30 秒超时，优雅关闭 5 秒超时
+
+### 调试与监控
+
+**开发环境日志**：
+
+- **分片跟踪**：每 100 个分片或最后分片记录详细信息
+- **背压监控**：缓冲区大小变化和等待时间统计
+- **性能指标**：传输速度、批次处理时间、格式转换耗时
+
+**生产环境优化**：
+
+- **条件日志**：`ENABLE_CHUNK_LOGGING`和`ENABLE_PROGRESS_LOGGING`开关
+- **错误上报**：关键错误通过`postLogToBackend`发送到后端
+- **性能采样**：通过`performance.now()`精确测量耗时
+
+## 9）断点续传深度分析
+
+### 断点续传核心机制
+
+**续传检测与状态恢复**：
+
+- **发送侧初始化**：`StreamingFileReader constructor(file, startOffset)` 支持从任意偏移量开始
+- **接收侧检测**：`StreamingFileWriter.getPartialFileSize()` 通过 File System Access API 检查部分文件
+- **状态同步**：fileRequest 消息包含 offset 参数，通知发送方从指定位置继续传输
+
+**分片索引计算**：
+
+```typescript
+// 统一的分片计算逻辑
+const startChunk = Math.floor(startOffset / chunkSize);
+const expectedChunks = Math.ceil((fileSize - startOffset) / chunkSize);
+```
+
+### ChunkRangeCalculator 统一计算器
+
+**设计目的**：确保发送端和接收端使用完全相同的分片计算逻辑
+
+```typescript
+getChunkRange(fileSize, startOffset, chunkSize) {
+  const startChunk = Math.floor(startOffset / chunkSize);
+  const endChunk = Math.floor((fileSize - 1) / chunkSize);
+  return { startChunk, endChunk, totalChunks: endChunk - startChunk + 1 };
+}
+```
+
+**关键方法**：
+
+- `getRelativeChunkIndex()`：绝对索引转相对索引，用于接收端数组映射
+- `isChunkIndexValid()`：验证分片索引是否在预期范围内
+- `calculateExpectedChunks()`：计算预期分片数量，与 ReceptionConfig 保持一致
+
+### 接收侧续传流程
+
+**部分文件检测**：
+
+1. **目录准备**：`createFolderStructure()` 确保目标目录存在
+2. **文件查询**：通过 `getFileHandle(fileName, {create: false})` 检查文件是否存在
+3. **大小获取**：`file.getFile()` 获取当前文件大小作为续传起点
+
+**续传决策逻辑**：
+
+```typescript
+// FileReceiveOrchestrator.ts
+const offset = await this.streamingFileWriter.getPartialFileSize(
+  fileInfo.name,
+  fileInfo.fullName
+);
+if (offset === fileInfo.size) {
+  // 文件已完整，跳过传输
+  return;
+}
+if (offset > 0) {
+  // 发现部分文件，准备续传
+  // 发送包含 offset 的 fileRequest
+}
+```
+
+### 发送侧续传响应
+
+**续传准备**：
+
+- **重置读取器**：`StreamingFileReader.reset(startOffset)` 从新的偏移量开始
+- **批次调整**：`currentBatchStartOffset` 和 `totalFileOffset` 同步更新
+- **分片索引**：`startChunkIndex` 记录传输起始点，用于边界检测
+
+**续传日志**：
+
+```typescript
+const chunkRange = ChunkRangeCalculator.getChunkRange(
+  fileSize,
+  startOffset,
+  chunkSize
+);
+postLogToBackend(
+  `[SEND-SUMMARY] File: ${file.name}, offset: ${startOffset}, startChunk: ${chunkRange.startChunk}, endChunk: ${chunkRange.endChunk}`
+);
+```
+
+### 续传的优势与限制
+
+**优势**：
+
+- **带宽节省**：避免重新传输已接收的数据
+- **时间效率**：大文件传输中断后可快速恢复
+- **用户体验**：网络波动不会导致传输进度完全丢失
+
+**限制与注意点**：
+
+- **文件一致性**：依赖文件内容未发生变化，续传前应验证文件大小/修改时间
+- **存储位置**：仅在使用 File System Access API 选择保存目录时支持
+- **浏览器兼容**：File System Access API 主要支持 Chrome/Edge，其他浏览器降级为内存存储
+
+**调试支持**：
+
+- **详细日志**：开发环境下记录续传起点、分片范围、预期传输量
+- **错误处理**：文件访问失败时回退到从头开始传输
+- **状态跟踪**：Store 层记录续传状态和实际接收大小
+
+## 10）重连与状态一致性深度分析
+
+### WebRTC 基础层重连机制
+
+**双重断开检测架构**：
+
+```typescript
+// webrtc_base.ts
+private isSocketDisconnected = false;  // Socket.IO 连接状态
+private isPeerDisconnected = false;   // P2P 连接状态
+private gracefullyDisconnectedPeers = new Set(); // 优雅断开的 peer 列表
+```
+
+**重连触发条件**：仅当 Socket.IO 和 P2P 连接都断开时才启动重连：
+
+```typescript
+// 避免重复重连：socket 断开 ≠ P2P 断开
+if (
+  this.isSocketDisconnected &&
+  this.isPeerDisconnected &&
+  !this.reconnectionInProgress
+) {
+  this.attemptReconnection();
+}
+```
+
+### ICE 候选者队列管理
+
+**候选者缓存策略**：
+
+- **连接未就绪时**：候选者缓存到 `iceCandidatesQueue` Map，按 peerId 分组
+- **连接就绪后**：批量处理缓存的候选者，按序添加到 RTCPeerConnection
+- **失效处理**：候选者失效时重新入队，验证连接状态后重试
+
+**实现细节**：
+
+```typescript
+private iceCandidatesQueue = new Map<string, RTCIceCandidate[]>();
+// 缓存候选项直到连接就绪
+if (dataChannel?.readyState !== 'open') {
+  this.queueIceCandidate(candidate, peerId);
+} else {
+  this.addIceCandidate(candidate, peerId);
+}
+```
+
+### 数据通道发送重试机制
+
+**5 次重试策略**：
+
+```typescript
+async sendToPeer(data: string | ArrayBuffer, peerId: string): Promise<boolean> {
+  for (let attempt = 1; attempt <= 5; attempt++) {
+    try {
+      dataChannel.send(data);
+      return true;
+    } catch (error) {
+      if (this.gracefullyDisconnectedPeers.has(peerId)) {
+        return false; // 跳过已优雅断开的 peer
+      }
+      if (attempt === 5) throw error;
+      await new Promise(resolve => setTimeout(resolve, attempt * 100)); // 100ms→1000ms
+    }
+  }
+}
+```
+
+**重试间隔递增**：100ms → 200ms → 300ms → 400ms → 500ms，最大 5 次尝试
+
+### 房间管理层的重连支持
+
+**幂等性设计**：
+
+- **长 ID 重连**：≥8 字符的 roomId 支持断线重连时复用房间
+- **短 ID 限制**：4 位数字 ID 断线后需重新生成房间，避免冲突
+
+**缓存 ID 重连优化**：
+
+```typescript
+// useRoomManager.ts
+if (roomId.length >= 8) {
+  // 长ID自动发送 initiator-online 信号
+  this.sendInitiatorOnline();
+}
+```
+
+**状态同步序列**：
+
+1. **发送方重连**：`initiator-online` 信号通知接收方准备重建连接
+2. **接收方响应**：`recipient-ready` 确认就绪状态
+3. **WebRTC 协商**：重新开始 offer/answer/ICE 候选者交换
+4. **传输恢复**：在新的 DataChannel 上恢复文件传输
+
+### 状态一致性保证机制
+
+**Store 层单一事实来源**：
+
+```typescript
+// fileTransferStore.ts
+export const useFileTransferStore = create<TransferState>((set, get) => ({
+  sendProgress: new Map(),
+  receiveProgress: new Map(),
+  // 提供清理 API 避免重复计数
+  clearSendProgress: (fileId: string) =>
+    set((state) => {
+      const newProgress = new Map(state.sendProgress);
+      newProgress.delete(fileId);
+      return { sendProgress: newProgress };
+    }),
+}));
+```
+
+**连接状态机**：
+
+```typescript
+type ConnectionStatus = 'connecting' | 'connected' | 'disconnected' | 'failed' | 'closed';
+
+// 状态变更时触发相应处理
+connectionStateChangeHandler(status: ConnectionStatus) {
+  switch (status) {
+    case 'connected':
+      this.gracefullyDisconnectedPeers.clear(peerId);
+      this.resetReconnectionState();
+      break;
+    case 'disconnected':
+    case 'failed':
+      this.cleanupExistingConnection(peerId);
+      break;
+  }
+}
+```
+
+### 移动端优化策略
+
+**唤醒锁管理**：
+
+```typescript
+// WakeLockManager
+async requestWakeLock(): Promise<void> {
+  try {
+    this.wakeLock = await navigator.wakeLock.request('screen');
+    this.wakeLock.addEventListener('release', () => {
+      this.wakeLock = null;
+    });
+  } catch (error) {
+    console.warn('Wake lock request failed:', error);
+  }
+}
+```
+
+**网络切换适应**：
+
+- **连接检测**：监听 `connectionstatechange` 事件检测网络质量变化
+- **自动重连**：`iceConnectionState: 'disconnected'` 时触发重连流程
+- **状态恢复**：重连成功后恢复房间状态和传输进度
+
+### 重连调试要点
+
+**关键日志点**：
+
+- **双重断开检测**：记录 Socket.IO 和 P2P 断开的具体时间戳
+- **候选者队列**：统计缓存的 ICE 候选者数量和处理时间
+- **发送重试**：记录重试次数、间隔和最终结果
+- **状态恢复**：追踪 `initiator-online` → `recipient-ready` 的时序
+
+**常见问题诊断**：
+
+- **重复重连**：检查 `reconnectionInProgress` 标志和 `gracefullyDisconnectedPeers` 集合
+- **候选者失效**：验证 `iceConnectionState` 和 `iceGatheringState` 状态
+- **状态不一致**：确认 Store 层的进度清理和连接状态同步
+
+## 11）微方案模板（用于小改动前的对齐）
+
+标题：<简述>
+
+背景/问题
+
+- 要解决的用户场景或缺陷是什么？
+
+目标与非目标
+
+- 本次改动包含与不包含的范围？
+
+影响文件与消息
+
+- 代码：列出关键文件（如 `frontend/lib/webrtc_base.ts`、`backend/src/socket/handlers.ts`）。
+- 协议：列出将修改的 DataChannel 消息/字段。
+
+状态机/流程变化
+
+- 增删改的阶段；给出简要时序或步骤。
+
+测试与回归清单
+
+- 单测/集成（如适用）、手测场景、性能/边界、重连。
+
+需要更新的文档
+
+- `code-map.md`（如出现新的入口）
+- `flows.md`（流程/消息/约束变化）
+- 相关架构或部署文档（如涉及）
@@ -0,0 +1,47 @@
+# PrivyDrop AI Playbook — 上下文与索引（中文）
+
+本手册为 AI 与开发者提供一个高信噪比的入口，帮助快速定位到正确的代码位置。仅包含项目上下文与链接索引，不提供步骤化的任务指南。
+
+## 项目快照
+
+- 产品：基于 WebRTC 的 P2P 文件/文本分享，浏览器之间通过 RTCDataChannel 直接传输，端到端加密。
+- 前端：Next.js 14（App Router）、React 18、TypeScript、Tailwind、shadcn/ui。
+- 后端：Node.js、Express、Socket.IO、Redis；可选 STUN/TURN 做 NAT 穿透。
+- 隐私立场：服务器不承载文件数据中转；后端仅负责信令与房间协调。
+
+## 文档索引
+
+- AI Playbook
+
+  - 代码地图：`docs/ai-playbook/code-map.zh-CN.md`
+  - 流程（含微方案模板）：`docs/ai-playbook/flows.zh-CN.md`
+  - 协作规则：`docs/ai-playbook/collab-rules.zh-CN.md`
+
+- 系统与架构
+
+  - 系统架构：`docs/ARCHITECTURE.md` / `docs/ARCHITECTURE.zh-CN.md`
+  - 前端架构：`docs/FRONTEND_ARCHITECTURE.md` / `docs/FRONTEND_ARCHITECTURE.zh-CN.md`
+  - 后端架构：`docs/BACKEND_ARCHITECTURE.md` / `docs/BACKEND_ARCHITECTURE.zh-CN.md`
+
+- 部署
+  - 部署指南：`docs/DEPLOYMENT.md` / `docs/DEPLOYMENT.zh-CN.md`
+  - Docker 部署：`docs/DEPLOYMENT_docker.md` / `docs/DEPLOYMENT_docker.zh-CN.md`
+
+## 关键模块速览
+
+- 前端核心
+  - Hooks：`frontend/hooks/useWebRTCConnection.ts`（连接编排）、`useRoomManager.ts`（房间生命周期）、`useFileTransferHandler.ts`（负载编排）。
+  - WebRTC 基础：`frontend/lib/webrtc_base.ts`（Socket.IO 信令、RTCPeerConnection、数据通道）。
+  - 角色：`frontend/lib/webrtc_Initiator.ts`、`frontend/lib/webrtc_Recipient.ts`（发起/接收角色行为）。
+  - 发送：`frontend/lib/transfer/*`、`frontend/lib/fileSender.ts`（元数据、分片、进度）。
+  - 接收：`frontend/lib/receive/*`、`frontend/lib/fileReceiver.ts`（组装、校验、持久化）。
+  - Store：`frontend/stores/fileTransferStore.ts`（进度/状态的单一事实来源）。
+- 后端核心
+  - Socket.IO：`backend/src/socket/handlers.ts`（join、initiator-online、recipient-ready、offer/answer/ice-candidate）。
+  - Services：`backend/src/services/{room,redis,rateLimit}.ts`。
+  - REST：`backend/src/routes/api.ts`（房间、追踪、调试日志）。
+
+## 维护
+
+- 保持精简与事实，避免与系统级文档重复。
+- 本文用于团队协作与快速理解。