From a4669f8561fae42d8a1a29bdae6b63f4c991c605 Mon Sep 17 00:00:00 2001
From: meoacgx <a1478882500@gmail.com>
Date: Tue, 3 Mar 2026 01:01:41 +0800
Subject: [PATCH] =?UTF-8?q?docs(modules):=20=E8=A1=A5=E5=85=85=E8=B4=A6?=
 =?UTF-8?q?=E5=8F=B7=E6=95=B0=E6=8D=AE=E5=8C=85=E5=AF=BC=E5=87=BA=E8=B0=83?=
 =?UTF-8?q?=E7=94=A8=E8=AF=B4=E6=98=8E=E4=B8=8E=20tdata=20=E5=85=B3?=
 =?UTF-8?q?=E9=94=AE=E6=B3=A8=E6=84=8F=E4=BA=8B=E9=A1=B9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增模块复用 AccountExportService 的推荐方式\n- 补充 /downloads/accounts.zip 参数与鉴权/缓存注意\n- 记录 tdata 导出稳定条件：padding、user_id 注入、已授权 DCSession 选择\n- 便于后续模块实现按账号下载 telethon/tdata 数据包
---
 docs/developer/modules.md | 45 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/docs/developer/modules.md b/docs/developer/modules.md
index 02b866e..a75b9f0 100644
--- a/docs/developer/modules.md
+++ b/docs/developer/modules.md
@@ -257,6 +257,51 @@ public sealed class MyHandler : IModuleTaskHandler
 }
 ```
 
+## 账号导出下载（Telethon / Tdata）
+
+如果模块需要“下载某个账号的数据包”，建议优先使用宿主服务直接生成 Zip（同进程内调用），避免绕 HTTP 鉴权与 Cookie。
+
+### 推荐方式：模块内直接调用导出服务
+
+可注入：
+
+- `TelegramPanel.Web.Services.AccountExportService`
+- `TelegramPanel.Core.Services.AccountManagementService`
+
+核心调用链：
+
+1. 先通过 `AccountManagementService` 获取目标账号（或账号列表）
+2. 调用 `AccountExportService.BuildAccountsZipAsync(accounts, ct, format)`
+3. 将 `byte[]` 按模块自己的场景返回/落盘/上传
+
+其中 `format`：
+
+- `AccountExportFormat.Telethon`：导出 `.json + .session (+2fa.txt)`
+- `AccountExportFormat.Tdata`：在以上基础上额外导出 `tdata/`
+
+### HTTP 方式（备选）
+
+宿主现有下载接口：
+
+- `GET /downloads/accounts.zip`
+- Query:
+  - `ids=1,2,3`（可选，不传则导出全部）
+  - `format=telethon|tdata`（不传默认 `telethon`）
+  - `ts=<timestamp>`（可选，建议带上，避免浏览器缓存旧包）
+
+注意：
+
+- 若开启后台登录，接口受登录态保护（需带管理端 Cookie）
+- 响应已设置 `no-store/no-cache`，但调用方仍建议加 `ts`
+
+### Tdata 导出的实现要点（后续扩展必须保持）
+
+1. `session -> telethon string` 时必须保留 Base64 padding（尾部 `=`）
+2. `telethon string -> tdata` 时必须注入 `session.self.userId`
+3. 生成 `telethon string` 时要优先选择“已授权 DCSession”（不是任意 DC）
+
+否则会出现“包结构看似正常，但 Telegram Desktop 仍要求重新登录”。
+
 ## UI 模块项目模板（Razor 组件）
 
 如果你的模块需要提供页面（`IModuleUiProvider.GetPages`），推荐把模块做成 `Microsoft.NET.Sdk.Razor` 项目（类似 Razor Class Library），例如：