ucvl-zonghengjia-android/README.md

# 纵横家 Android 客户端

版本 `1.0.4` 本地候选，尚未作为正式版发布；包名 `cn.toplc.zonghengjia`。这是公司 Android 客户端的 GPL-3.0 衍生源码，不包含服务器端、账号、节点凭据或公司签名私钥。

1.0.4 纳入2026-09-17的后台授权隔离修复：区分“旧会话停止”和“当前账号撤销”，防止重新登录后的延迟响应误报新账号失效。旧1.0.3候选APK不含此修复。修复历史见`acceptance/AUTH-SESSION-ISOLATION-20260917.md`；1.0.4的构建、签名和本地验证见`acceptance/ACCEPTANCE-1.0.4.md`。本地检查不替代真实服务/设备VPN验收，候选未发布。

## 2026-09-08：1.0.3 本地候选

新增启动与手动 Git 更新检查，只提示 `pro.ucvl.cn` 正式 Android Release 的通用 APK；忽略草稿/试用/其它平台，下载路径固定在公司公开安装包仓库。提示不改变 VPN，不共享平台登录令牌。用户同意后打开下载；系统要求的 APK 安装授权仍需确认，尚不是应用内静默下载安装。

1.0.3 的 34 项单元测试和 APK 构建通过，五种 APK 已沿用公司原证书签名，尚未上传或向员工推送。构建请使用 ASCII 路径：中文目录下本轮 Gradle 测试工作进程未能加载测试类；独立 ASCII 源码副本重编译后全套通过，没有关闭或跳过失败测试。

## 已实现

- 公司账号登录、浏览器注册、设备授权、个人信息、套餐/额度/有效期。
- 由平台自动分配节点，客户端只显示实际工作节点，不提供节点选择。
- 完整保留平台下发的路由规则，支持智能/全局代理；使用 Android VpnService + HEV 隧道接管其他应用。
- 仅统计 proxy 出站的速度/流量，两条低高度曲线；直连不计入代理统计。
- Android Keystore 加密会话、同一证书覆盖升级保留配置。
- VPN 后台每 60 秒检查授权，401/403 时断开并清除会话；临时网络错误不误当账号撤销。
- 退出等待服务停止，TLS 清理在后台线程执行；系统 VPN 关闭后由 Android 恢复原网络。
- 兼容后台 `config_contract=2`，连接时把节点地址切换到统一 NPM 公网网关，同时保留每个节点的端口和 Reality SNI；旧后台仍按原配置工作。

## 验收边界

`acceptance/` 保存实际测试记录，不把编译成功当作手机实测。原生内核三节点 × 两模式 HTTPS、系统 VPN 独立 UID、退出/后台回收、同证书覆盖升级测试已通过。独立源码副本重新下载依赖并从头构建，通过 26 项单测；生成的 APK 解包内容与候选构建逐项相同。没有 Android 实体手机测试，尚未宣称与 Windows 全功能等价。

当前没有实现 Android 未知目标失败的全量学习闭环、持续故障自动换节点和应用内下载安装升级流程。公司已确认的规则会随连接配置下发。暂不作为全公司稳定版通知。

## 从源码构建

1. 安装 JDK 21、Python 3、Android SDK（platforms;android-37、build-tools;37.0.0 和 platform-tools）；设置 `JAVA_HOME`、`ANDROID_HOME`。Windows 建议使用不含中文的项目路径。
2. 运行 `python Restore-Dependencies.py`，恢复锁定的 AAR/JNI。文件逐一校验 SHA256；不读取公司密钥。
3. 在 `V2rayNG` 运行 `gradlew :app:testPlaystoreReleaseUnitTest :app:assemblePlaystoreRelease`（Linux/macOS 用 `./gradlew`）。Gradle wrapper 为 9.4.1，AGP/Kotlin/Maven 依赖锁定在 `gradle/libs.versions.toml`。
4. 构建生成的 release APK 未签名。用自己的 Android keystore、`zipalign` 和 `apksigner` 签名后可安装；自行签名不能覆盖公司原证书安装的包，先备份数据再卸载旧包。私钥不属于本源码分发内容。
5. 公司发布工具 `Sign-Candidate.ps1` 使用本地私有 `.tools/signing/signing.properties`；此文件和 keystore 永不入库。不必使用公司密钥即可构建和运行修改版。

测试专用的 `acceptanceProbe` 是独立 UID 网络探针，不随客户端打包，不对员工发布。需要时用 `-PUCVL_ACCEPTANCE=true :acceptanceProbe:assembleDebug` 构建。`src/androidTest` 需要隔离模拟器和临时授权测试会话；仓库不附真实会话。

## 来源与许可

- v2rayNG 2.2.1，源提交 `39d2513`，https://github.com/2dust/v2rayNG ，GPL-3.0。保留原始 `LICENSE`、版权、原始说明和依赖许可；2026-09-03 UCVL 修改包含公司界面/API、完整路由桥接、流量显示、授权回收与测试。
- AndroidLibXrayLite v26.5.19，`4c3a3cd051ac6a10d27ba1347a05fff2697ea272`；对应 Xray-core `1bdb488c9ec0`，见其 `go.mod/go.sum` 及原始许可。AAR 与上游 release SHA256 一致。
- HEV SOCKS5 Tunnel `dfabaa9cadf8894eb8ebfa0f75b1fee331869b34` 及递归子模块源代码保留。可用 Android NDK 28.2.13676358 和 `compile-hevtun.sh` 自行重建；发布用 JNI 来自上游 v2rayNG 2.2.1 APK，逐 ABI 哈希锁定。
- QuickieExtended quickie-foss 1.14.0、Toasty 1.5.2；其余 AndroidX、OkHttp、Gson、MMKV 等按各自许可使用。详见 `V2rayNG/app/src/main/assets/open_source_licenses.html` 和版本目录。
- 源码副本中的 `AndroidLibXrayLite/`、`hev-socks5-tunnel/` 为带原始许可的上游快照，包含递归子模块。`SOURCE-PROVENANCE.json` 列明每个完整提交；不依赖公司私有仓库。

本程序依 GPL-3.0 提供，不提供任何担保；可以按许可证复制、修改及再分发。公司名称/Logo 保留作为原始来源标识，不表示修改后的第三方版本获得公司服务授权。公司服务器和其他平台的私有源码不在此次公开范围。

客户端公开源码：https://pro.ucvl.cn/admin/ucvl-zonghengjia-android