From 03b7a8bf25d2ed69733bd72796a07826304067ac Mon Sep 17 00:00:00 2001
From: YANG JIANKUAN <tim.yee@hotmail.com>
Date: Thu, 26 Feb 2026 22:19:55 +0800
Subject: [PATCH] feat: update readme file

---
 README.md | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/README.md b/README.md
index 0095fff..aa1e9a4 100644
--- a/README.md
+++ b/README.md
@@ -53,6 +53,40 @@ DDYSClient/
 └── Utilities/              # 通用扩展
 ```
 
+## 数据获取原理
+
+ddys.io 是一个服务端渲染 (SSR) 的网站，没有提供公开的 REST API（仅有少量内部接口）。本客户端通过**模拟浏览器请求网页 + 解析 HTML** 的方式获取数据，整体流程如下：
+
+### 1. 列表页 & 分类浏览
+
+客户端直接以 GET 请求访问网站的 HTML 页面（如 `/movie`、`/series/page/2`），携带浏览器 User-Agent 和 Referer 头以通过服务端校验。返回的 HTML 经 SwiftSoup 解析，通过 CSS 选择器（如 `.movie-card`、`h3 a`、`.badge-top-right`）提取标题、海报、评分、年份等结构化数据。分页信息从页面底部的 `.pagination-active` 和 `.pagination-btn` 元素中解析得到。
+
+### 2. 详情页
+
+详情页同样请求对应路径的 HTML（如 `/movie/slug`）。页面内嵌了 `<script type="application/ld+json">` 结构化数据，包含导演、演员、类型、评分、简介等信息，客户端优先从 JSON-LD 提取。对于 JSON-LD 中缺失的字段（如地区、播放源），再 fallback 到 HTML 元素解析。
+
+### 3. 播放源 & 剧集
+
+播放源信息嵌入在详情页 HTML 的 `<button onclick="switchSource(...)">` 属性中，通过正则表达式提取源 ID、视频地址和格式。剧集列表以 `集名$url#集名$url` 的格式编码在 URL 字符串中，按 `#` 和 `$` 分隔解析出每集的名称和 m3u8 播放地址。视频播放直接使用 AVKit 原生 HLS 支持。
+
+### 4. 搜索
+
+搜索通过 GET 请求 `/search?q=关键词&type=all` 实现（网站前端使用 POST 表单提交后 302 重定向到此 GET 地址）。返回的 HTML 结构与列表页一致，复用同一套解析逻辑。
+
+### 5. 认证
+
+网站使用 Cloudflare Turnstile 验证码保护，原生客户端无法自动完成验证。因此提供两种方式：通过内嵌 WKWebView 让用户在网页中完成登录后自动提取 Cookie，或由用户从浏览器手动复制 Cookie 粘贴到应用中。Cookie 注入到 URLSession 的 HTTPCookieStorage 后，后续所有请求自动携带认证信息。
+
+```
+┌─────────┐     GET HTML      ┌──────────┐    SwiftSoup     ┌──────────┐
+│  Client  │ ───────────────→ │  ddys.io  │ ──────────────→ │  Models  │
+│  (App)   │ ← HTML response  │  (SSR)    │   CSS解析/正则   │  (Swift) │
+└─────────┘                   └──────────┘    JSON-LD提取    └──────────┘
+     │                                                            │
+     │              m3u8 URL                                      │
+     └──────────────────────────────────────→ AVPlayer (HLS播放)  │
+```
+
 ## 构建 & 运行
 
 ### 环境要求