# Flutter-os

**Repository Path**: xiangkp/flutter-os

## Basic Information

- **Project Name**: Flutter-os
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: Artistic-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-16
- **Last Updated**: 2026-07-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Flutter OS Enterprise

面向 Android、iOS、HarmonyOS/OpenHarmony 的企业级 Flutter 工程模板。项目不是只有页面的演示，而是把常见的登录、会话恢复、网络请求、离线缓存、分页搜索、主题、语言、环境隔离、原生安全存储和原生事件流串成了一条可继续开发的完整链路。

> “可上线”指工程具备规范的分层、安全存储、构建参数、质量检查和发布清单。真实产品上线前仍必须替换演示 API、接入企业认证、隐私协议、监控、正式签名，并完成三端真机与商店审核。

## 已包含

- Flutter 3.44.6 / Dart 3.12
- Feature-first + Clean Architecture + Repository
- Riverpod 3 状态管理
- GoRouter 登录守卫和底部导航
- Dio 超时、鉴权拦截和脱敏日志
- JSONPlaceholder 示例列表、搜索、分页、刷新和离线缓存
- 登录、会话恢复和退出
- Material 3 浅色/深色主题
- 中文/英文切换
- `dart-define` 开发、预发布、生产环境
- Android Kotlin MethodChannel / EventChannel
- iOS Swift MethodChannel / EventChannel
- HarmonyOS ArkTS MethodChannel / EventChannel 宿主模板
- Android Keystore、iOS Keychain、HarmonyOS HUKS 安全存储示例
- 单元测试、Widget 测试、静态检查和 GitHub Actions

## 快速运行

```bash
flutter pub get
flutter run \
  --dart-define=APP_ENV=dev \
  --dart-define=API_BASE_URL=https://jsonplaceholder.typicode.com
```

演示登录信息已经预填：

```text
demo@flutteros.dev
123456
```

替换真实登录时，只需实现 `lib/features/auth/data/auth_repository.dart` 中的 `AuthRepository`，页面和路由不需要重写。

## 目录

```text
lib/
├── app/                         # 应用入口、路由、导航壳
├── core/                        # 环境、网络、存储、主题、语言、原生桥
└── features/
    ├── auth/                    # 登录与会话
    ├── home/                    # 列表、搜索、分页、缓存
    ├── native_bridge/           # 原生能力演示页
    └── settings/                # 主题、语言、环境、退出
android/                         # Kotlin 宿主与 Android Keystore
ios/                             # Swift 宿主与 Keychain
ohos/                            # ArkTS 宿主与 HUKS
docs/                            # 架构、桥接、开发和上线文档
```

## 文档导航

- [高 Star 项目调研与取舍](docs/research-comparison.md)
- [总体架构](docs/architecture.md)
- [原生桥接：小白版](docs/native-bridge.md)
- [HarmonyOS 开发说明](docs/harmonyos.md)
- [开发、环境与构建](docs/development.md)
- [上线检查清单](docs/release-checklist.md)

## 质量检查

Linux/macOS：

```bash
chmod +x scripts/check.sh
./scripts/check.sh
```

Windows PowerShell：

```powershell
.\scripts\check.ps1
```

## 三端状态

| 平台 | 工程 | 原生桥 | 当前验证 |
| --- | --- | --- | --- |
| Android | `android/` | Kotlin + Keystore | Flutter/Dart 检查已运行；见最终验证记录 |
| iOS | `ios/` | Swift + Keychain | 源码已提供；必须在 macOS + Xcode 构建 |
| HarmonyOS | `ohos/` | ArkTS + HUKS | 模板已提供；必须在 DevEco + OpenHarmony Flutter SDK 构建 |

标准 Flutter SDK 不能直接产出 HarmonyOS 包。HarmonyOS 的工具链和插件切换步骤请严格参考 [docs/harmonyos.md](docs/harmonyos.md)。

## 安全提醒

- 非敏感主题、语言和缓存使用 `SharedPreferences`。
- token 不写普通偏好存储，而是通过 `NativeBridge` 进入系统安全存储。
- 生产环境禁止把密钥、签名文件和 `.env` 提交到 Git。
- 示例 token 仅用于演示会话流程，不能作为真实认证方案。

## License

建议在正式采用前由项目所有者补充组织认可的 LICENSE。本仓库调研引用了开源项目的设计思想，没有复制其业务源码；使用任何第三方代码前仍需单独审查许可证。