10 KiB
iOS 原生应用说明（当前实现）
本文是 iPhone 应用的唯一现行说明，内容与仓库代码一致。历史设计稿和执行计划保留在
docs/superpowers/ 下，其中已被实现推翻的决策在本文第 9 节逐条列出。
- 当前版本：
0.2.1 (build 6) - 承载分支：
ios-native-ipa - 运行要求：iOS 16.0 及以上，
arm64，Bundle IDfun.chick.multi-simadmin - 产物：未签名
MultiSimAdmin.ipa，由 TrollStore 或用户自有签名流程安装
1. 形态
独立 iPhone 应用。应用直接以 HTTP/HTTPS 访问用户添加的每个 SimAdmin 节点，不经过 8788 控制台，不含 WebView，不内嵌 Node.js，也不与 Web 端共享数据库或进程。Web 前端和 Node 控制面仍然独立存在，两者只共享上游接口契约。
2. 导航
底部固定三个入口，高度 62pt（AITabBar）：
| 入口 | 页面 | 内容 |
|---|---|---|
| 节点 | FleetView |
节点总览、运行概览、标签筛选、分组视图、批量选择、添加与编辑实例 |
| 消息 | MessagesView |
跨实例短信读取、按实例与方向筛选、搜索、发送、删除 |
| 设置 | SettingsView |
主题外观、应用信息、本地数据（进入日志中心）、隐私与数据、数据清理 |
实例详情 InstanceDetailView 由节点卡片进入；日志中心 LogsView 只出现在
「设置 → 本地数据」里，不占用底部入口。启动参数 --tab-messages、--tab-settings
可直达对应 Tab，--tab-detail、--tab-logs 只在 Debug 构建生效，供逐页截图验证使用。
3. 页面能力
节点总览
- 运行概览：在线率、异常节点、检测进度、今日消息、分组与标签统计，可折叠。
- 分组视图：按分组折叠成段，段头给出该组健康度与台数，支持展开与折叠。
- 标签筛选：标签条支持多选叠加，标签上直接显示命中台数，可单个取消或全部清除。
- 搜索：匹配名称、地址、运营商与标签。
- 节点卡片：号码、运营商、制式、温度、电量、内存、存储、延迟、信号、固件、运行时间等 指标，超出一屏时折叠为「另有 N 项指标」。
- 批量选择：工具栏为 34pt 图标按钮（全选、删除、退出等高），勾选列独立于名称区域， 选中态不遮挡文字。
- 实例增删改：地址、名称、标签、分组、访问凭据；删除前确认，并一并清除本地登录信息。
实例详情
- 头部卡片：地址、连接状态、四项仪表（信号、延迟、CPU、内存）、身份摘要（号码、运营商、 网络、IP）、模块可用度读数、分组与标签。
- 数据模块：设备、SIM、蜂窝网络、系统资源、CPU、连接状态共 6 个分区，逐模块独立加载， 单模块失败只标记该模块，不影响其余分区。
- 敏感值（IMEI、ICCID 等）默认隐藏，需要显式开启显示，离开页面后自动恢复隐藏。
- 本机保存的配置：地址、凭据状态、标签、分组，以及登录、登出、重新检测。
消息中心
逐实例读取 /api/sms/list 后在本地合并，不做跨设备中转：
- 列表按时间排序，显示来源实例、方向、号码、正文与相对时间。
- 支持按实例筛选、按上行/下行筛选、按号码或内容搜索。
- 发送写入目标实例；失败可重试；单条删除走该实例的上游接口。
日志中心与设置
- 日志中心：运行日志统一时间线、连接探测记录（结果、错误码、耗时）、设备诊断快照； 支持按级别、来源、实例、结果筛选与关键字搜索，支持清理过期连接日志。
- 设置：主题外观（跟随系统、浅色、深色，即时作用于全部页面）、应用信息与系统版本、 本地数据统计、隐私与数据说明、清除运行日志（不可恢复确认）。
4. 上游访问
只允许固定白名单，不存在任意 URL 代理：
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/health |
可达性与版本 |
| GET | /api/device |
设备信息 |
| GET | /api/sim |
SIM 与号码 |
| GET | /api/network |
蜂窝网络与信号 |
| GET | /api/network/signal-strength |
信号强度明细 |
| GET | /api/stats |
系统资源 |
| GET | /api/stats/cpu |
CPU 明细 |
| GET | /api/connectivity |
连接状态 |
| GET | /api/sms/list |
短信列表（limit、offset、direction） |
| POST | /api/sms/send |
发送短信 |
| POST | /api/sms/batch-delete |
批量删除短信 |
| POST | /api/auth/login |
使用实例密码换取会话 |
| POST | /api/auth/logout |
注销会话 |
请求超时 30 秒，单响应体上限 262144 字节，错误统一映射为请求非法、需要登录、权限受限、不支持、 超时、传输失败、响应非法七类可读文案。会话 Cookie 按实例隔离保存在内存中，并绑定创建时 的节点地址，地址改变后旧 Cookie 立即失效。应用不请求定位、相机、麦克风、通讯录或后台 刷新权限，不声明任何后台模式。
5. 本地数据与安全
全部数据落在应用沙盒 Documents 目录，无 Keychain、无 SQLite、无服务端上传：
| 文件 | 内容 |
|---|---|
instances.json |
实例名称、地址、标签、分组、修订号 |
instance-groups.json |
分组定义 |
credentials.json |
实例访问密码 |
log-center.json |
运行日志、连接探测记录、诊断快照缓存 |
主题偏好存在 UserDefaults（键 aiThemeMode）。登录会话只存在于进程内存，应用退出即消失。
密码与 Cookie 不写日志、不进导出内容。删除应用即彻底清除本机数据。允许 HTTP 明文访问是
为了兼容局域网 SimAdmin，公网节点应由用户自行通过 HTTPS 反代暴露。
6. 设计语言
深墨蓝与金色构成品牌色，界面在浅色下使用中性冷灰画布与纯白卡片，深色下使用低明度蓝黑分层，
主操作使用蓝色，危险操作使用红色。控件令牌集中在 AITheme：主按钮高 48pt（紧凑 44pt、大号
56pt）、工具栏按钮高 44pt（宽 104pt）、导航栏图标按钮 34pt 方形（圆角 11pt）、输入框高 52pt、
卡片圆角 22pt、按钮圆角 16pt、标签为 28pt 胶囊。
同屏并排控件必须等高，选中态不得改变控件尺寸，卡片内部不再嵌套卡片，正文与标题不使用负字距。
7. 构建与产物
./scripts/build-ios-ipa.sh
流程：xcodebuild -scheme MultiSimAdmin -configuration Release（generic/platform=iOS）编译
可执行文件 → 手工组装 Payload/MultiSimAdmin.app → 用 xcrun actool 编译 Assets.xcassets
得到 Assets.car 并合并图标元数据到 Info.plist → zip 打包 → 生成 .sha256。产物：
build/ipa/MultiSimAdmin.ipabuild/ipa/MultiSimAdmin.ipa.sha256
脚本不需要证书与描述文件，不做任何签名改动；Assets.car 缺失时直接失败退出，避免发布没有
图标的包。
应用图标由脚本光栅化生成，不使用手工位图：
cd apps/ios && swift Design/generate_app_icon.swift \
Sources/MultiSimAdmin/Resources/Assets.xcassets/AppIcon.appiconset/AppIcon1024.png
图标几何与 Web 端 favicon 一致：深墨蓝底、金色 SIM 面板（切角在左上）、三根底部对齐的递增
信号条。apps/ios/Design/AppIcon.svg 是同构图参考稿，实际构建使用 PNG。
8. 验证方式
cd apps/ios
swift build
swift test # 48 个用例
xcodebuild -scheme MultiSimAdmin \
-destination 'platform=iOS Simulator,id=<UDID>' \
-configuration Debug build
单元测试覆盖实例仓储与修订冲突、地址规范化与去重、标签归一化、上游路由白名单、会话隔离、 连接探测分类、短信解析与分页、设备快照解析、日志仓储与清理、主题模式持久化、时间相对显示、 版本号契约。界面改动在 iPhone 17 Pro 模拟器上以截图逐页核对浅色与深色两套主题，重点检查控件 等高、文字不溢出、按钮在深色下不消失。
9. 与设计稿的偏离
docs/superpowers/specs/2026-09-08-ios-native-ipa-design.md 的以下决策已被实现推翻，该文档
只作为历史背景保留：
| 原设计 | 当前实现 | 原因 |
|---|---|---|
| 底部五 Tab：节点/消息/通知/日志/设置 | 三 Tab：节点/消息/设置 | 应用内通知中心依赖进程常驻，关闭后不可用；日志属于低频排查，收进设置 |
| 通知通道、规则、投递队列、立即投递 | 未实现 | 同上，移除后不再保留只读残壳 |
| 实例密码存 iOS Keychain | 沙盒内 credentials.json |
Keychain 在 TrollStore 环境下读写不稳定 |
| GRDB + SQLite 控制面库 | 沙盒内 JSON 文件 | 去掉第三方依赖，数据结构与备份语义更直观 |
| 操作目录、任务、审计、维护、备份 | 未实现 | 高风险写操作与常驻调度不在 iPhone 前台场景内 |
| 设备模块 13 项（含通话、eSIM、OTA、WiFi Calling、自动化） | 6 个只读模块 + 短信读写 | 上游只保留有稳定读取价值的接口，其余按需在后续版本评估 |
| 浅灰画布、青绿主按钮 | 深浅双主题、蓝色主操作、金色品牌色 | 0.2.x 视觉重构结论 |
10. 已确认的移除边界
不实现：应用启动后的周期轮询、后台任务与静默推送、Cron 与自动投递、自动备份与自动日志修剪、 控制台自更新、多用户与远程访问、全局访问密码。
保留：进入前台与下拉刷新触发的一次同步、页面可见时的按需刷新、用户主动发起的登录、检测、 发送、删除与日志清理。
11. 文档索引
- docs/ios-native.md：本文，现行说明
- docs/ios-native-0.2.1.md：0.2.1 (6) 发布说明与校验值
- docs/ios-native-0.2.0.md：0.2.0 发布说明
- docs/superpowers/specs/2026-09-08-ios-native-ipa-design.md：历史设计稿
- docs/superpowers/plans/2026-09-08-ios-native-ipa-foundation.md：地基执行计划（已完成）