{"skill":{"slug":"teamgram-client-e2e-flow","displayName":"Teamgram Client E2E Flow","summary":"Documents the KHF Android client architecture and complete end-to-end data flows for login, messaging, and file operations through all Teamgram Server layers.","description":"---\nname: teamgram-client-e2e-flow\ndescription: Documents the KHF Android client architecture and complete end-to-end data flows for login, messaging, and file operations through all Teamgram Server layers.\ncompatibility: Documentation/knowledge skill only. No executable code. Reference material for Teamgram Server developers.\nmetadata:\n  author: zhihang9978\n  version: \"1.0.0\"\n  source: https://github.com/teamgram/teamgram-server\n  homepage: https://github.com/teamgram/teamgram-server\n  openclaw:\n    requires:\n      env: []\n      bins: []\n    securityNotes: |\n      Documentation-only skill. Contains no executable code, no network calls, no credential handling.\n      APP_ID and APP_HASH are public application identifiers, not secrets.\n      All content references the open-source teamgram-server project (Apache-2.0).\n---\n\n# KHF Android 客户端架构与端到端数据流\n\n## KHF 客户端关键常量\n\n从 KHF 源码提取（必须与服务端兼容）：\n- `TLRPC.LAYER = 222`\n- `BuildVars.APP_ID = 4`\n- `BuildVars.APP_HASH = \"014b35b6184100b085b0d0572f9b5103\"`\n\n## tgnet/ConnectionsManager：Java → JNI → Native MTProto\n\nConnectionsManager 负责：\n- `native_init(...)` 初始化 MTProto（layer/api_id/设备信息）\n- `native_sendRequest(...)` 发送 RPC\n- DC/网络状态管理\n\n客户端通过 JNI 调用 Native C++ 层实现 MTProto 协议，包括：\n- 加密/解密（AES-IGE）\n- 握手（DH 密钥交换生成 auth_key）\n- 消息序列化/反序列化（TL 二进制格式）\n- 网络连接管理（TCP/WebSocket）\n- 重连与退避策略\n\n## MessagesController：业务层\n\nMessagesController 负责 dialogs/messages/users/chats 的本地模型与网络请求，典型方法：\n- loadAppConfig — 加载应用配置\n- loadDialogs — 加载对话列表\n- loadMessages — 加载消息\n- loadFullChat — 加载群组完整信息\n- loadFullUser — 加载用户完整信息\n\n## 端到端数据流示例\n\n### 登录流程：auth.sendCode → auth.signIn\n\n```text\nClient (KHF)\n  -> TL: auth.sendCode(phone_number, api_id, api_hash, settings)\n  -> MTProto encrypted message\n  -> gnetway decrypt + QuickAck + SendDataToSession\n  -> session decode TLMessage2 -> route to /mtproto.RPCAuthorization via IDMap\n  -> bff.authorization.AuthSendCode\n       -> biz.user (check phone registered)\n       -> status (online sessions)\n       -> verify-code plugin (sms) OR app code\n  <- bff returns auth.SentCode or error\n  <- session wraps rpc_result\n  <- gnetway encrypts + send back\n  <- client parses auth.SentCode\n```\n\n### 消息发送流程：messages.sendMessage\n\n```text\nClient\n  -> TL: messages.sendMessage / messages.sendMedia / ...\n  -> gnetway -> session -> bff.messages\n  -> bff.messages\n       -> biz_service (dialog/message/chat/user)\n       -> msg service (异步投递 + Kafka)\n  -> messenger.msg produces to Kafka Inbox-T\n  -> inbox consumes Inbox-T, writes inbox/outbox state\n  -> produces updates to Kafka Sync-T\n  -> sync consumes Sync-T, decides UpdatesMe/NotMe/PushRpcResult\n  -> sync calls session (gRPC) to push updates/rpc_result\n  -> session routes to correct sessionId\n  -> gnetway encrypt -> client\n```\n\n### 文件上传下载流程\n\n```text\nClient\n  -> files.upload* / upload.getFile\n  -> bff.files\n       -> dfs 保存/获取 file parts\n       -> media 生成缩略图/元数据\n       -> db 写入 documents/photos/photo_sizes/...\n  <- 返回 inputFile / fileLocation / document/photo\n\nDFS\n  - Minio buckets: documents/photos/videos/encryptedfiles\n  - MiniHttp 0.0.0.0:11701 提供 HTTP 下载入口\n```\n\n## 客户端与服务端兼容性要点\n\n1. **LAYER 版本**：客户端 LAYER=222 必须与服务端 session.yaml 中的 layer 配置一致\n2. **APP_ID/APP_HASH**：必须与服务端 BFF 配置中的 ApiId/ApiHash 匹配\n3. **MTProto 握手**：客户端使用 obfuscated2 + AES-IGE 加密\n4. **TL 序列化**：客户端和服务端必须使用相同的 TL Schema 版本\n\n## 常见错误与排查\n\n| 错误 | 含义 | 排查方向 |\n|---|---|---|\n| PHONE_NUMBER_INVALID | 手机号格式不正确 | 检查国际格式（+86...） |\n| PHONE_NUMBER_BANNED | 手机号被封禁 | 检查 predefined_users 表 |\n| SESSION_PASSWORD_NEEDED | 需要两步验证 | 用户设置了密码 |\n| AUTH_KEY_UNREGISTERED | auth_key 未注册 | 清除客户端数据重新握手 |\n| CONNECTION_NOT_INITED | 未调用 initConnection | 客户端需先发 initConnection |\n| ERR_ENTERPRISE_IS_BLOCKED | 企业版功能锁定 | 需要解除企业版拦截（修改 biz_service 中的企业版检查逻辑） |\n| METHOD_NOT_IMPL | RPC 方法未实现 | 检查 BFF handler 和 session IDMap 路由是否配置 |\n\n## 企业版锁定模式\n\nTeamgram 社区版中部分功能被企业版锁定拦截，表现为：\n- `ERR_ENTERPRISE_IS_BLOCKED` 错误\n- 在 biz_service 层的 helper 中通过 `checkEnterprise()` 函数拦截\n\n解锁方法：修改 biz_service 中对应 helper 的企业版检查逻辑，移除或绕过 `checkEnterprise()` 调用。\n\n## 关键代码路径\n\n### 客户端 (KHF)\n- ConnectionsManager：`TMessagesProj/jni/tgnet/ConnectionsManager.cpp`\n- MessagesController：`TMessagesProj/src/main/java/org/telegram/messenger/MessagesController.java`\n- TLRPC 定义：`TMessagesProj/src/main/java/org/telegram/tgnet/TLRPC.java`\n- BuildVars：`TMessagesProj/src/main/java/org/telegram/messenger/BuildVars.java`\n\n### 服务端 (HD/Teamgram)\n- gnetway 入口：`app/interface/gnetway/`\n- session 路由：`app/interface/session/`\n- BFF 模块：`app/bff/`\n- biz_service：`app/service/biz/`\n- messenger：`app/messenger/`\n- 配置文件：`teamgramd/etc/`\n- SQL schema：`teamgramd/deploy/sql/`\n\n\n## Source Code References\n\n- Repository: https://github.com/teamgram/teamgram-server (Apache-2.0)\n","tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":565,"installsAllTime":0,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1773552719917,"updatedAt":1778491917527},"latestVersion":{"version":"1.0.0","createdAt":1773552719917,"changelog":"Initial release","license":"MIT-0"},"metadata":{"setup":[],"os":null,"systems":null},"owner":{"handle":"zhihang9978","userId":"s172je8v58fh44rr2hyzjrejen84qsq9","displayName":"zhihang9978","image":"https://avatars.githubusercontent.com/u/217701803?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1780089893097}}