网络功能

// src/network/CrossPointWebServer.cpp
void CrossPointWebServer::begin() {
  // ===== 页面路由 =====
  webServer.on("/", HTTP_GET, [this]() { servePage(HomePage); });
  webServer.on("/files", HTTP_GET, [this]() { servePage(FilesPage); });
  webServer.on("/settings", HTTP_GET, [this]() { servePage(SettingsPage); });

  // ===== REST API =====
  webServer.on("/api/files", HTTP_GET, [this]() { handleFileList(); });
  webServer.on("/api/upload", HTTP_POST,
    [this]() { handleUploadComplete(); },   // 上传完成回调
    [this]() { handleUploadChunk(); });      // 每收到一个 4KB 分块就回调一次
  webServer.on("/api/download", HTTP_GET, [this]() { handleDownload(); });
  webServer.on("/api/settings", HTTP_GET, [this]() { handleGetSettings(); });
  webServer.on("/api/settings", HTTP_POST, [this]() { handleSetSettings(); });

  webServer.begin();  // 开始监听 HTTP:80 端口
}

index.html → const uint8_t homepage_html[] = {0x3C, 0x21, 0x44, ...};

1. 阅读器启动 WiFi（AP 或 STA 模式）
2. 阅读器启动 Web 服务器（监听 80 端口）
3. 用户在手机浏览器输入阅读器的 IP 地址
4. 浏览器加载管理页面（HTML/JS 从固件中返回）
5. 用户在页面上点击"上传"，选择 EPUB 文件
6. 浏览器通过 POST /api/upload 发送文件
7. 阅读器以 4KB 分块接收，每块直接写入 SD 卡
8. 上传完成，阅读器刷新文件列表

// src/activities/webserver/CrossPointWebServerActivity.cpp
void CrossPointWebServerActivity::startAccessPoint() {
  WiFi.mode(WIFI_AP);
  WiFi.softAP(AP_SSID, nullptr, AP_CHANNEL, false, AP_MAX_CONNECTIONS);
  // 参数说明：热点名称, 无密码, WiFi 信道, 不隐藏SSID, 最大连接数

  MDNS.begin(AP_HOSTNAME);  // 注册 mDNS：crosspoint.local

  // 关键：启动 DNS 服务器，劫持所有域名解析
  dnsServer = new DNSServer();
  dnsServer->setErrorReplyCode(DNSReplyCode::NoError);
  dnsServer->start(DNS_PORT, "*", apIP);  // "*" = 所有域名都解析到设备 IP
}

正常的 WiFi 连接流程：
  手机连上 WiFi → DNS 查询 "connectivitycheck.gstatic.com" → 得到真实 IP
  → 访问成功 → 系统判定"网络正常"

连接 CrossPoint AP 时：
  手机连上热点 → DNS 查询 "connectivitycheck.gstatic.com"
  → DNS 服务器把所有域名都解析到阅读器 IP（例如 192.168.4.1）
  → 手机访问检测 URL，得到的不是预期响应
  → 系统判定"需要登录" → 自动弹出内置浏览器
  → 浏览器访问任意 URL → 全部被导向阅读器的管理页面

// src/network/WebDAVHandler.cpp
void WebDAVHandler::setup(WebServer& s) {
  // WebDAV 要求支持的 HTTP 方法：
  // OPTIONS   — 客户端询问"你支持哪些操作"
  // PROPFIND  — 获取文件/目录的属性（类似 ls -l）
  // GET       — 下载文件
  // HEAD      — 获取文件元信息（不下载内容）
  // PUT       — 上传/覆盖文件
  // DELETE    — 删除文件或目录
  // MKCOL     — 创建目录（Make Collection）
  // MOVE      — 移动/重命名
  // COPY      — 复制
  // LOCK      — 锁定文件（防止并发修改）
  // UNLOCK    — 解锁
}

void WebDAVHandler::handlePut(WebServer& s) {
  // 1. 先写入临时文件（文件名加 .davtmp 后缀）
  std::string tmpPath = path + ".davtmp";
  Storage.openFileForWrite("DAV", tmpPath, file);

  // 2. 接收数据并写入临时文件
  while (hasMoreData()) {
    size_t received = s.readBytes(buffer, sizeof(buffer));
    file.write(buffer, received);
  }
  file.close();

  // 3. 上传完成后，原子替换目标文件
  Storage.rename(tmpPath.c_str(), path.c_str());

  // 4. 如果是 EPUB 文件且有旧版缓存，清除缓存
  clearEpubCacheIfNeeded(path);
}

void WebDAVHandler::handleLock(WebServer& s) {
  // 不真的加锁，只是返回一个固定的锁令牌
  s.sendHeader("Lock-Token", "<urn:uuid:dummy-lock-token>");
  s.send(200, "application/xml", dummyLockXml);
}

// lib/OpdsParser/OpdsParser.cpp

// OpdsParser 继承自 Print，可以作为 HTTP 响应的"输出目标"
size_t OpdsParser::write(const uint8_t* xmlData, size_t length) {
  size_t remaining = length;
  const uint8_t* pos = xmlData;

  while (remaining > 0) {
    // 从 Expat 获取一块 1KB 的内部缓冲区
    void* buf = XML_GetBuffer(parser, 1024);
    size_t toRead = std::min(remaining, (size_t)1024);

    // 将 HTTP 响应数据复制到 Expat 缓冲区
    memcpy(buf, pos, toRead);

    // 增量解析——Expat 每解析完一个 XML 元素就回调通知
    XML_ParseBuffer(parser, toRead, 0);

    pos += toRead;
    remaining -= toRead;
  }
  return length;
}

OPDS 服务器
  │
  │ HTTP 响应（Atom XML）
  ▼
HTTPClient 接收数据
  │
  │ 调用 opdsParser.write(data, len)
  ▼
OpdsParser（实现了 Print 接口）
  │
  │ 每 1KB 喂给 Expat
  ▼
Expat XML 解析器
  │
  │ 回调：发现一本新书 / 一个新分类 / 一个下载链接
  ▼
更新 UI（显示书目列表）

// lib/KOReaderSync/KOReaderSyncClient.cpp

// 认证：每个请求都附带用户名和 MD5 密码哈希
void addAuthHeaders(HTTPClient& http) {
  http.addHeader("x-auth-user", KOREADER_STORE.getUsername().c_str());
  http.addHeader("x-auth-key", KOREADER_STORE.getMd5Password().c_str());
}

// 获取某本书在其他设备上的最新阅读进度
Error getProgress(const std::string& docHash, KOReaderProgress& out) {
  // docHash 是书籍文件的哈希值，用于跨设备识别"同一本书"
  HTTPClient http;
  http.begin(serverUrl + "/syncs/progress/" + docHash);
  addAuthHeaders(http);

  int code = http.GET();
  if (code == 200) {
    // 解析 JSON 响应
    JsonDocument doc;
    deserializeJson(doc, http.getString());
    out.percentage = doc["percentage"].as<float>();    // 阅读百分比
    out.progress = doc["progress"].as<std::string>();  // XPath 精确位置
  }
  return toError(code);
}

// 上传当前阅读进度到服务器
Error updateProgress(const KOReaderProgress& progress) {
  HTTPClient http;
  http.begin(serverUrl + "/syncs/progress");
  addAuthHeaders(http);

  JsonDocument doc;
  doc["document"] = progress.document;       // 书籍标识
  doc["progress"] = progress.progress;       // XPath 位置
  doc["percentage"] = progress.percentage;   // 阅读百分比
  doc["device"] = "CrossPoint";              // 设备标识

  String body;
  serializeJson(doc, body);
  http.PUT(body);
  return toError(http.GET());
}

                    ┌──────────────────────────────────┐
                    │       CrossPointWebServerActivity │
                    │       (管理 WiFi 和所有网络服务)   │
                    └─────────────┬────────────────────┘
                                  │
              ┌───────────────────┼───────────────────┐
              │                   │                   │
     WiFi AP 模式            WiFi STA 模式       WiFi STA 模式
     (无路由器)              (有路由器)           (有路由器)
              │                   │                   │
    ┌─────────┴──────────┐       │                   │
    │                    │       │                   │
DNS 劫持          mDNS 注册     │                   │
(自动弹出页面)  (crosspoint.local)│                   │
    │                    │       │                   │
    └────────┬───────────┘       │                   │
             │                   │                   │
    ┌────────┴───────────────────┴───┐               │
    │       Web 服务器 (HTTP:80)      │               │
    │  ┌──────────┐  ┌────────────┐ │               │
    │  │ 管理页面  │  │  REST API  │ │               │
    │  │ (HTML/JS) │  │(文件/设置) │ │               │
    │  └──────────┘  └────────────┘ │               │
    ├────────────────────────────────┤               │
    │     WebDAV 服务器               │               │
    │  (Calibre 无线传书)             │               │
    └────────────────────────────────┘               │
                                                     │
                              ┌───────────────────────┘
                              │
                 ┌────────────┴──────────────┐
                 │                           │
          OPDS 客户端              KOReader 同步客户端
       (浏览在线书库)            (跨设备进度同步)