inp2p/docs/android-mvp-plan.md

INP2P Android 客户端开工计划（MVP → V1）

目标

在不改动核心服务端协议的前提下，先交付“可运维、可观察、可控风险”的安卓客户端。

分阶段路线

Phase 0：开工准备（1-2 天）

• 明确 API 契约（当前后端已具备）
• 固化角色与权限矩阵（admin/operator/apikey）
• 建立 Android 项目骨架（Kotlin + Compose + Retrofit + Room + WorkManager）
• 建立日志/崩溃/埋点规范

Phase 1：MVP（5-7 天）

• 登录/会话管理（/api/v1/auth/login）
• 节点列表与状态（/api/v1/nodes）
• 手动 connect（/api/v1/connect）
• 远程推配置（/api/v1/nodes/apps）
• 节点踢下线（/api/v1/nodes/kick，仅 admin/operator）
• SDWAN 基础配置只读 + 编辑（按权限）
• 审计查看（admin only，/api/v1/admin/audit）

Phase 2：增强（7-10 天）

• 设置页：高级开关联动（/api/v1/admin/settings）
• 断线重连与 Token 续期提示
• 更完整的错误态/空态/离线态
• 细化操作确认（高风险动作二次确认）

Phase 3：V1（后续）

• VpnService + TUN 数据面接入
• 网络切换稳定性（Wi-Fi/4G）
• 前台服务保活与电量策略优化

MVP 范围边界（本次明确）

• ✅ 做：控制面（鉴权、查询、下发）
• ❌ 不做：首版直接上 TUN 全数据面

技术选型（建议）

• 语言：Kotlin
• UI：Jetpack Compose
• 网络：Retrofit + OkHttp
• 本地存储：Room + EncryptedSharedPreferences
• 并发：Kotlin Coroutines + Flow
• 任务调度：WorkManager
• 最低版本：Android 8.0+

核心风险与对策

1. Token 过期导致操作失败
   • 对策：统一 401 拦截，跳登录；关键动作前校验登录态。
2. 移动网络切换导致请求失败
   • 对策：重试策略（指数退避）、弱网提示、幂等操作提示。
3. 高危动作误触（kick/connect/sdwan）
   • 对策：二次确认 + 审计可追踪 + 角色按钮可见性控制。
4. 后端字段变动影响兼容
   • 对策：DTO 宽容解析 + 版本检查 + 契约文档锁定。

验收标准（MVP）

• 能用 admin/operator 成功登录并执行对应权限动作
• apikey 仅可读，写操作被正确拒绝
• 关键操作成功/失败信息明确可见
• 审计与后端一致（至少覆盖 connect/kick/apps/sdwan）