# MaxHap - 跨平台 Compose 应用框架

<div align="center">

[![Kotlin](https://img.shields.io/badge/Kotlin-1.9+-blue.svg?logo=kotlin)](https://kotlinlang.org)
[![Compose Multiplatform](https://img.shields.io/badge/Compose-Multiplatform-red.svg)](https://www.jetbrains.com/lp/compose-multiplatform/)
[![Android](https://img.shields.io/badge/Android-支持-green.svg?logo=android)](https://developer.android.com)
[![HarmonyOS](https://img.shields.io/badge/HarmonyOS-支持-orange.svg)](https://developer.harmonyos.com)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)

**一个基于 Kotlin Multiplatform 和 Jetpack Compose 的高性能跨平台应用开发框架**

</div>

MaxHap 是一个创新的跨平台移动应用开发解决方案，专注于提供极致的开发体验和卓越的应用性能。通过统一的代码库，开发者可以同时为 Android 和 HarmonyOS 平台构建功能丰富、界面精美的现代化应用。

## 🏗️ 项目架构

```
MaxHap/
├── composeApp/          # 🎨 核心 Compose UI 层（跨平台共享）
├── harmonyApp/          # 🔷 HarmonyOS 原生集成层
├── iosApp/              # 🍎 iOS 原生壳应用
├── nestedlib1-5/        # 📚 模块化嵌套页面库（1000层深度导航测试）
├── scripts/             # ⚙️ 自动化构建和测试脚本
├── build.gradle.kts     # 🛠️ 根项目构建配置
└── settings.gradle.kts  # 📋 项目模块管理配置
```

## 🚀 核心功能与工具集

### 🧪 深度嵌套页面测试框架

MaxHap 内置了一套完整的深度嵌套页面测试系统，用于验证跨平台导航和性能表现：

#### 📁 generate_hap_test_files.sh - 基础嵌套页面生成器

生成5个独立的模块化库，构建1000层深度嵌套导航结构。

**核心特性：**
- 🏗️ **模块化架构**：5个独立的Kotlin Multiplatform库（nestedlib1-5）
- 📊 **海量文件**：每个库200个.kt文件（总计1000个页面组件）
- 🔗 **智能跨库调用**：每库第200层自动跳转至下个库第201层
- 🎨 **视觉差异化**：每层页面拥有独特配色方案
- ⚡ **自动配置**：一键生成完整的Gradle构建配置

**技术亮点：**
```kotlin
// 示例：第200层跨库调用
if (showNextPage200) {
    com.dong.maxhap.nestedlib2.NestedPage201()
    return
}
```

**快速开始：**
```bash
# 赋予执行权限（首次使用）
chmod +x generate_hap_test_files.sh

# 一键生成全部测试文件
./generate_hap_test_files.sh
```

**输出目录：**
```
📁 nestedlib1/src/commonMain/kotlin/com/dong/maxhap/nestedlib1/
📁 nestedlib2/src/commonMain/kotlin/com/dong/maxhap/nestedlib2/
...
📁 nestedlib5/src/commonMain/kotlin/com/dong/maxhap/nestedlib5/
```

### 🧹 测试环境管理工具

#### 🔄 cleanup_hap_test_files.sh - 交互式清理工具

安全可靠地清理所有生成的测试文件，防止误删。

**安全保障机制：**
- 📊 **文件统计**：显示待删除文件数量和大小
- ✅ **双重确认**：执行前需要用户明确确认
- 🧼 **智能清理**：可选删除空目录，保持项目整洁
- 🛡️ **防误操作**：避免意外删除重要文件

**使用示例：**
```bash
# 添加执行权限
chmod +x cleanup_hap_test_files.sh

# 启动交互式清理流程
./cleanup_hap_test_files.sh

# 输出示例：
# 🔍 发现 1000 个测试文件 (约 50MB)
# ❓ 确认删除这些文件吗？(y/N): y
# ✅ 清理完成！
```

#### ⚡ quick_cleanup.sh - 快速清理工具

为CI/CD和自动化测试场景设计的一键清理方案。

**适用场景：**
- 🤖 **持续集成**：自动化测试流水线
- 🚀 **快速迭代**：频繁重构和重试
- 📦 **批量操作**：脚本化部署流程

**注意事项：** ⚠️ 无确认机制，请谨慎使用

**使用方式：**
```bash
# 快速清理（无确认）
chmod +x quick_cleanup.sh
./quick_cleanup.sh

# CI/CD 集成示例
./quick_cleanup.sh && ./generate_hap_test_files.sh && ./gradlew test
```

## 🛠️ 开发环境与技术栈

### 📱 支持平台
| 平台 | 版本要求 | 构建工具 |
|------|----------|----------|
| Android | API 24+ | Gradle + AGP |
| HarmonyOS | 6.0+ | Hvigor |
| iOS | 12.0+ | Xcode + CocoaPods |

### 🔧 核心技术栈

**语言与框架：**
- Kotlin Multiplatform 1.9+
- Jetpack Compose Multiplatform
- Android Jetpack
- HarmonyOS ArkUI

**构建与工具链：**
- Gradle 8.0+
- Hvigor 6.0+ (HarmonyOS)
- Android Gradle Plugin 8.0+
- Kotlin Compiler 1.9+

## 🏗️ 构建与部署

### 🤖 Android 平台
```bash
# Debug 构建与安装
./gradlew assembleDebug
./gradlew installDebug

# Release 构建
./gradlew assembleRelease

# 运行单元测试
./gradlew test
```

### 🔷 HarmonyOS 平台
```bash
# 进入HarmonyOS项目目录
cd harmonyApp

# 构建HAP包
hvigorw assembleHap

# 构建Debug版本
hvigorw assembleHap -p module=entry@default -p buildMode=debug

# 查看构建报告
hvigorw --info
```

### 🍎 iOS 平台
```bash
# 在Xcode中打开项目
open iosApp/iosApp.xcworkspace

# 或使用命令行构建
xcodebuild -workspace iosApp/iosApp.xcworkspace \
           -scheme iosApp \
           -configuration Debug \
           -destination 'platform=iOS Simulator,name=iPhone 15' \
           build
```

## 🌟 项目特色优势

### 💡 核心价值
- **🎯 一次编写，多端运行**：真正意义上的代码复用
- **⚡ 高性能渲染**：原生级别的用户体验
- **🎨 统一设计语言**：一致的视觉和交互体验
- **🔧 模块化架构**：高内聚低耦合的设计原则

### 🛡️ 质量保障
- **🧪 深度测试覆盖**：1000层嵌套页面的压力测试
- **📊 性能监控**：实时跟踪内存和CPU使用情况
- **🔒 类型安全**：Kotlin强类型系统保驾护航
- **🔄 热重载支持**：开发效率大幅提升

## ⚠️ 重要提醒与最佳实践

### 📈 性能考量
- **调用栈深度**：1000层嵌套可能触发栈溢出，请根据设备能力调整
- **内存占用**：大量Composable组件需关注内存泄漏问题
- **启动时间**：复杂嵌套结构会影响冷启动性能

### 🔧 使用建议
- **开发阶段**：建议减少嵌套层数进行快速迭代
- **生产环境**：务必进行全面的性能测试和优化
- **数据备份**：重要修改前请及时提交代码或备份
- **渐进式采用**：可以从简单页面开始逐步迁移到复杂结构

### 🛡️ 安全须知
- 清理脚本仅删除自动生成的测试文件
- 不会影响手动编写的业务代码
- 建议定期检查.gitignore确保测试文件不会被提交

## 📋 常见问题与解决方案

### 🔧 HarmonyOS 配置文件缺失

**问题描述：** 构建时提示 `main_pages.json` 或相关配置文件缺失

**解决方案：**

在 `/harmonyApp/entry/src/main/resources/base/profile/` 目录下创建以下配置文件：

**📄 main_pages.json**
```json
{
  "src": [
    "pages/Index"
  ]
}
```

**📄 backup_config.json**
```json
{
  "allowToBackupRestore": true
}
```

### 🚀 其他常见问题

<details>
<summary><strong>构建失败：依赖下载超时</strong></summary>

```bash
# 切换到国内镜像源
# 在 ~/.gradle/gradle.properties 中添加：
systemProp.http.proxyHost=your-proxy-host
systemProp.http.proxyPort=your-proxy-port
```
</details>

<details>
<summary><strong>HarmonyOS模拟器无法启动</strong></summary>

```bash
# 检查Hvigor版本兼容性
hvigorw --version

# 清理缓存重新构建
cd harmonyApp && rm -rf .hvigor/cache && hvigorw clean
```
</details>

## 🤝 贡献指南

我们欢迎各种形式的贡献！

### 📝 如何参与
1. Fork 本项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

### 🎯 贡献方向
- ✨ 新功能开发
- 🐛 Bug修复
- 📚 文档完善
- 🧪 测试用例补充
- 💡 性能优化建议

## 📄 许可证

本项目采用 Apache License 2.0 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 📞 联系方式

- **项目维护者**：dong.sq@example.com
- **GitHub Issues**：[提交问题](https://github.com/yourusername/MaxHap/issues)
- **讨论交流**：QQ群 123456789

---

<div align="center">

**如果你觉得这个项目有帮助，请给个⭐Star支持一下！**

[![GitHub stars](https://img.shields.io/github/stars/yourusername/MaxHap?style=social)](https://github.com/yourusername/MaxHap)

</div>
