# OIP-Mobile

**Repository Path**: orginone/OIP-Mobile

## Basic Information

- **Project Name**: OIP-Mobile
- **Description**: 移动端
- **Primary Language**: Dart
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-09-25
- **Last Updated**: 2026-10-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OIP-Mobile · 奥集能移动端

> **文档版本**：v1.2 | **更新**：2026-09-26 | **状态**：详细设计
>
> **关联**：[AGENTS.md](AGENTS.md) · [CODE_WIKI.md](CODE_WIKI.md) · [视觉规范](docs/ui-design-v2/overview.md) · [OIP-Frontend-Design.md](../OIP/docs/OIP-Frontend-Design.md) · [OIP-Protocol.md](../OIP/docs/OIP-Protocol.md)
> **结构变更**：AGENTS.md 章节重编号——原 15.5 节（字体统一设计规范）归位为 §16，原 16~23 各章顺延一位为 §17~§24；本文件对外章节引用同步更新。

奥集能开放架构（OIP）**人机交互层（L6）**的移动端实现，Flutter / Dart 技术栈。

奥集能（Orginone，发音 [ˈɔːdʒɪnʌn]）以所有权为第一优先级，按自组织分形理念抽象"沟通、办事、
门户、数据、关系"等通用本体，为 B/C 端融合的全场景业务提供新一代分布式应用架构与数据网络
操作系统。本仓库承载其中的**移动端交互面**。

> 前身为 `oiocns-flutter`，派生关系与许可声明见 [NOTICE](NOTICE)；本仓库以 MIT 协议发布。

---

## 一、在 OIP 中的定位

OIP 各仓库按层解耦，彼此通过 HTTP / WebSocket 经 **OIP-GoInOne 前门**耦合，**零代码级依赖**。

| 层 | 仓库 | 与本仓库的关系 |
| --- | --- | --- |
| L6 人机交互 | **OIP-Mobile（本仓库）** · OIP-Desktop · OIP-Web · OIP-Lite | 交互面，经前门收发 |
| L5 智能体 | OIP-Agent | 经前门调用 |
| L4 消息 | OIP-Message | 经前门路由 |
| L3 权利状态机 | OIP-Book | 经前门路由（唯一权威源） |
| L2 数据 | OIP-Data | 经前门 `DataProxy` 路由 |
| L1 物联网 | OIP-IoT | 经前门 `module:'iot'` 路由 |
| — | OIP-GoInOne | **唯一前门**：认证、路由、上行转发 |

**红线（MUST NOT 违反）**

1. MUST NOT 直连数据核（OIP-Data / OIP-Book），一切业务请求经前门。
2. MUST NOT 私建网络通道（自建 Hub / 独立长连接 / 直接 new Dio 拼 host）。
3. MUST NOT 绕过协议层（自行解析错误码、自行拼 `/oip/v1/*` 路径）。

### 1.1 模块名

本仓的规范模块名为 **`OIP-Mobile`**（前端四项目之一，按宿主载体划分）。文档、架构图与提交信息一律使用该名；技术栈称谓「Flutter 端」可出现在说明性文字中，但不作为模块名使用。前端四项目的划分与跨端一致性要求以 [OIP-Frontend-Design.md](../OIP/docs/OIP-Frontend-Design.md) 为单一真相源。

---

## 二、与服务端的对接

### 2.1 通道

| 通道 | 端点 | 用途 |
| --- | --- | --- |
| Hub（WebSocket，兼容 SignalR 线协议） | `/oip/v1/hub` | 通用请求 `Request` / 认证 `Auth` / `TokenAuth` / 数据核 `DataProxy` / 在线 `Online` / `HttpForward` / `DataShare` / `LoadShare` / `GetConnectionId` / `createTemporaryToken` / `Requests` |
| REST 降级通道 | `/oip/v1/rest/{method}` | Hub 不可用时的 HTTP 回退 |
| REST 认证 | `/oip/v1/auth/{login,refresh,token-auth}` | DID 登录与令牌轮换 |
| 节点能力声明 | `/oip/v1/bootstrap` | 节点发现与能力协商；服务端不提供该端点时客户端按 §2.4 的降级表回退 |

### 2.2 节点发现（三层，按序回退）

1. **配置注入层**：环境变量 `OIP_L3_ENDPOINT`（节点域名） / `OIP_L3_HUB_PATH`（Hub 路径） /
   `OIP_L3_DID`（节点 DID） / `OIP_L3_TLS_CA`（自签名 CA，可选） / `OIP_COMPLIANCE_LEVEL` / `OIP_ENV`。
   默认值见 [lib/dart/base/oip/oip_config.dart](lib/dart/base/oip/oip_config.dart)，可用 `--dart-define=OIP_L3_ENDPOINT=...` 覆盖。
2. **bootstrap 层**：`GET /oip/v1/bootstrap` 返回节点能力与端点。
3. **DID serviceEndpoints 层**：经 DID 文档解析服务端点。

### 2.3 首次启动时序

```text
配置注入 → bootstrap（前门无该能力则回退配置层）
        → Auth("GetChallenge") → DID Proof 签名
        → Auth("Login")        → TokenAuth → 建立 Hub 连接
```

DID Proof 私钥经 `SecureTokenStorage`（iOS Keychain / Android Keystore）托管，
MUST NOT 落入 SQLite / SharedPreferences / 明文文件。

### 2.4 命名空间切换与降级

命名空间切换由功能开关控制（默认关闭），各开关可独立回退（开关定义见
[lib/config/oip_feature_flags.dart](lib/config/oip_feature_flags.dart)）：

| 开关 | 覆盖范围 | 中断风险 |
| --- | --- | --- |
| Hub 命名空间开关 | 仅切 Hub URL（`/orginone/kernel/hub` ↔ `/oip/v1/hub`） | 零中断（前门对旧路径双侧挂载） |
| `Auth` 强类型开关 | `Auth` 调用强类型化 + 双轨错误码解析 | 低 |
| `DataNotify` 订阅开关 | 显式订阅（`Auth("Subscribe", {flags})`） | 低 |

**降级策略**：前门不提供 `bootstrap` 时回退到配置注入层；Hub 不可达时回退 REST 通道；
对端不可达 MUST NOT 降级为放行。

**服务端能力边界**（前端按降级表处置）：`/oip/v1/bootstrap`；`DataNotify` / `QrAuth` 推送协议；
`HttpForward`；`DataShare` / `LoadShare`；`Online`；`createTemporaryToken`；以及 Target / Identity /
Team CRUD、OTP、WorkDefine / WorkInstance、Object / Collection / Bucket / Thing 等业务接口。
完整边界清单以 [OIP/docs/OIP-Frontend-Design.md](../OIP/docs/OIP-Frontend-Design.md) 与 [OIP/docs/OIP-Protocol.md](../OIP/docs/OIP-Protocol.md) 为准。

### 2.5 OIP 接入层

所有 OIP 协议适配集中在 `lib/dart/base/oip/`，业务代码经既有入口
（`HttpUtil` / `KernelApi`）间接使用，**不直接触碰协议细节**。
接入层约定与硬约束见 [AGENTS.md](AGENTS.md) §24。

端点解析：`Constant.kernelHub` / `Constant.rest` 由
[lib/dart/base/oip/endpoint_resolver.dart](lib/dart/base/oip/endpoint_resolver.dart)
按 `oipNamespace` 开关返回 legacy 或 OIP 命名空间地址，默认 legacy（前门双侧挂载，可随时回退）。

**客户端边界与已知约束**：

| 项 | 位置 | 约束 |
| --- | --- | --- |
| bootstrap 探活 | `lib/dart/base/oip/bootstrap_client.dart` | 前门不提供 `/oip/v1/bootstrap` 时，按降级表回退到配置注入层 |
| DID serviceEndpoint 探测 | `lib/dart/base/oip/oip_endpoint_router.dart` | `_probe` 仅做可达性超时探测，未接入真实 serviceEndpoint 解析 |
| 全局 OIP 会话 | `lib/main.dart` 的 `OipStateProvider` | 以空 session 占位；真实 session 由 DID 登录后经 `BootstrapClient` 协商注入 |
| 密码加密密钥 | `lib/env.dart`（`EnvConfig`）· `lib/dart/base/common/vocabulary/consts.dart`（`Constants.aesKey`） | 源码内**不含**任何硬编码密钥：`EnvConfig.pwdEncryptKey` 已移除，`aesKey` 为空串；密钥不得硬编码于源码，须由安全存储 / KMS 下发 |

### 2.6 配置说明

| 来源 | 内容 | 读取方 |
| --- | --- | --- |
| 编译期 `--dart-define=OIP_*` | 节点端点 `OIP_L3_ENDPOINT` · Hub 路径 `OIP_L3_HUB_PATH` · 节点 DID `OIP_L3_DID` · 自签名 CA `OIP_L3_TLS_CA` · 兼容等级 `OIP_COMPLIANCE_LEVEL` · 运行环境 `OIP_ENV` | [lib/dart/base/oip/oip_config.dart](lib/dart/base/oip/oip_config.dart)（`String.fromEnvironment`） |
| `.env`（仓库根，入库） | 响应式布局常量：断点、设计稿基准尺寸、边距、导航栏尺寸、内容最大宽度、栅格列数与间距 | 运行期布局断点以 [lib/config/responsive_breakpoints.dart](lib/config/responsive_breakpoints.dart) 中的 Dart 常量生效 |
| [lib/config/oip_feature_flags.dart](lib/config/oip_feature_flags.dart) | OIP 迁移阶段功能开关，默认关闭 | 各接入层模块 |

节点类配置可按需覆盖默认值：

```bash
flutter run --dart-define=OIP_L3_ENDPOINT=https://your-node.example.com \
            --dart-define=OIP_ENV=development
```

**`.env` 保持入库**：该文件**仅含非敏感的界面布局常量**，不含任何密钥、令牌或凭证。
新增敏感配置 MUST NOT 写入 `.env`——DID 私钥经 `SecureTokenStorage`
（iOS Keychain / Android Keystore）托管（§2.3），其余密钥由安全存储或 KMS 下发。

---

## 三、快速开始

```bash
# 依赖
flutter pub get

# 静态分析（基线：0 error / 0 warning；既有 info 基线不拦截）
flutter analyze --no-fatal-infos

# 单元测试
flutter test

# 协议面产物漂移校验（在仓库根目录执行；产物必须与 spec 一致）
python3 ../OIP/tools/gen_protocol.py --check

# 构建（调试）
flutter build apk --debug
```

**环境要求**：Flutter >= 3.41.6、Dart >= 3.9.0（见 [pubspec.yaml](pubspec.yaml)）。
CI（[`.github/workflows/ci.yml`](.github/workflows/ci.yml)）在 Flutter 3.47.2 上执行
`flutter analyze --no-fatal-infos`、`flutter test` 与协议面漂移校验。

打包脚本：`build_dev_apk.sh`（测试环境）、`build_prod_apk.sh`（正式环境）、
`build_prod_ios.sh`、`build_multiplatform.sh`。

---

## 四、目录结构

```text
lib/
├── config/                 # 配置 / 常量 / 主题 / 功能开关 / 响应式断点 / i18n
├── components/             # 可复用 UI 组件（XScaffold、ChatSessionWidget/cards、form 等）
├── routers/                # app_route / index / pages（路由表）/ router_const（路由常量）/ observers
├── dart/                   # 业务内核
│   ├── base/               # 基础设施
│   │   ├── api/            # HttpUtil / KernelApi / StoreHub
│   │   ├── oip/            # OIP 接入层（协议面产物 / 节点发现 / 错误码 / 离线队列）
│   │   ├── security/       # SecureTokenStorage 等
│   │   ├── storages/       # SQLite / 文件系统 / KV / Hive
│   │   ├── common/         # 通用基础设施
│   │   └── regex/          # 正则与校验
│   ├── core/               # 领域逻辑（chat / work / thing / iot / ai / oip / provider /
│   │                       #   repository / public / space / target / share / call / mall）
│   ├── controller/         # 全局编排（启动、网络波动、重连、数据新鲜度）
│   └── extension/          # Dart 扩展方法
├── pages/                  # 页面（auth / chats / home / portal / relation / store / work /
│                           #   iot / agent / discover / oip / common）
└── utils/                  # 通用工具（date_util / encryption_util / file_utils / string_util）；
                            #   日志经 XLogUtil（lib/dart/base/common/log_util.dart），响应式经 XUi（lib/config/theme/unified_style.dart）
```

其余仓库根目录：`android/` `ios/` `macos/`（平台工程）、`assets/`（静态资源）、
`test/`（单元测试）、`tool/` `auto/`（构建与自动化）、`docs/`（设计文档）、
`.github/workflows/`（CI）。

构建与平台本地产物（`build/`、`.dart_tool/`、`ios/Pods/`、`android/.gradle/`）不入库，
由根 `.gitignore` 与平台子目录的 `.gitignore` 共同覆盖。

---

## 五、文档

| 文档 | 内容 |
| --- | --- |
| [AGENTS.md](AGENTS.md) | **协作规范（先读）**：目录分层、三条红线、网络/存储约束、OIP 接入层约定、视觉与数据更新规范 |
| [CODE_WIKI.md](CODE_WIKI.md) | 代码导览：模块职责、关键类与接口、路由与页面清单、依赖关系 |
| [docs/ui-design-v2/overview.md](docs/ui-design-v2/overview.md) | 视觉规范 v2（设计令牌、组件状态、页面骨架） |
| [OIP/docs/OIP-Frontend-Design.md](../OIP/docs/OIP-Frontend-Design.md) | OIP 前端契约：节点发现、Hub 方法、错误码、跨端一致性 |
| [OIP/docs/OIP-Protocol.md](../OIP/docs/OIP-Protocol.md) | OIP 协议规范（配置注入层、错误码、Hub 方法权威定义） |

---

## 六、贡献

- 分支前缀：`common` / `feature` / `fix` / `hotfix` / `perf` / `other` + 姓名缩写 + 描述/日期。
- 提交信息：`type: subject`（如 `feat: 新增物联网设备详情页`）。
- 提交前对照 [AGENTS.md](AGENTS.md) §21 PR 自检清单逐条自查。
- 默认中文沟通；修改前先读相关文件，只做需求相关改动。

---

## 七、许可

[MIT](LICENSE) © 2026 潘朝晖。

派生自 `oiocns-flutter`（木兰宽松许可证第 2 版），原始来源与许可声明保留于 [NOTICE](NOTICE)。