# LighthouseApp 技术文档

欢迎查阅 LighthouseApp 技术文档。本目录包含项目的架构设计、开发指南和故障排查信息。

## 📚 文档导航

### Clash Meta 核心 (推荐阅读)

| 文档 | 说明 | 适用人群 |
|------|------|----------|
| [**架构文档**](./CLASH_ARCHITECTURE.md) | 完整架构设计、数据流、关键决策 | 所有开发者 |
| [**编译指南**](./CLASH_BUILD_GUIDE.md) | 本地编译步骤、环境配置、优化方法 | 核心开发者 |
| [**故障排查**](./CLASH_TROUBLESHOOTING.md) | 常见问题、日志分析、崩溃调试 | 测试/运维 |

### CI/CD 工作流

| 文档 | 说明 |
|------|------|
| [**GitHub Actions 说明**](../.github/workflows/README.md) | 自动化构建、发布流程 |

## 🚀 快速开始

### 新开发者入门

1. **了解架构** (必读)
   - 阅读 [CLASH_ARCHITECTURE.md](./CLASH_ARCHITECTURE.md)
   - 理解 Dart → Android → Go 三层架构
   - 掌握 FFI 通信机制

2. **配置开发环境**
   - 按照 [CLASH_BUILD_GUIDE.md](./CLASH_BUILD_GUIDE.md) 配置环境
   - 编译第一个 Clash Core
   - 验证编译结果

3. **运行项目**
   ```bash
   # 1. 获取代码
   git clone <repo-url>
   cd LighthouseApp

   # 2. 初始化子模块
   git submodule update --init --recursive

   # 3. 编译核心
   cd core
   make android-arm64

   # 4. 运行 Flutter
   cd ..
   flutter pub get
   flutter run
   ```

### 核心开发者

如果您需要修改 Clash Meta 核心:

1. **修改代码**
   ```bash
   cd core
   vim lib_android.go  # 或其他核心文件
   ```

2. **本地测试**
   ```bash
   make android-arm64
   flutter run
   ```

3. **提交 PR**
   - CI/CD 会自动构建所有架构
   - 检查 Actions 页面的构建结果
   - 等待代码审查

## 🏗️ 架构速览

```
┌─────────────────────────────────────────────────────────────┐
│                   LighthouseApp                             │
├─────────────────────────────────────────────────────────────┤
│  Flutter/Dart Layer                                         │
│  └─ lib/app/services/clash_imp/                             │
│      ├─ kr_clash_imp.dart      (核心封装)                   │
│      ├─ clash_ffi.dart         (FFI 绑定)                   │
│      └─ clash_config_generator (配置生成)                   │
├─────────────────────────────────────────────────────────────┤
│  Android Native Layer                                       │
│  └─ android/app/src/main/kotlin/com/hiddify/hiddify/        │
│      ├─ bg/VPNService.kt       (VPN 服务)                   │
│      └─ bg/ClashService.kt     (Clash 服务)                 │
├─────────────────────────────────────────────────────────────┤
│  Go Core Layer                                              │
│  └─ core/                                                   │
│      ├─ Clash.Meta/            (Git 子模块)                 │
│      ├─ lib_android.go         (JNI 桥接)                   │
│      └─ libclash.so            (编译产物)                    │
└─────────────────────────────────────────────────────────────┘
```

详细架构请参考 [CLASH_ARCHITECTURE.md](./CLASH_ARCHITECTURE.md)

## 🔧 常见任务

### 编译核心

```bash
cd core

# 单个架构 (快速)
make android-arm64

# 所有架构 (发布)
make android-all

# 清理
make clean

# 验证
make verify
```

### 更新 Clash.Meta

```bash
cd core
make update  # 更新子模块到最新版本
make android-arm64  # 重新编译
```

### 调试问题

```bash
# 查看 Android 日志
adb logcat -s "A/Clash" "E/Clash"

# 查看编译详情
cd core
go build -v -x -buildmode=c-shared -o test.so .

# 验证 SO 文件
nm -D libclash.so | grep quickStart
```

## 📖 核心概念

### 1. FFI 并发安全

**问题:** Go 运行时初始化不是线程安全的

**解决:** 使用 `Completer` 实现初始化锁

```dart
Future<void> _ensureInitialized() async {
  if (_initialized) return;
  if (_initLock != null) {
    await _initLock!.future;  // ✅ 等待其他初始化
    return;
  }
  // ... 执行初始化
}
```

详见 [CLASH_ARCHITECTURE.md § 并发安全保证](./CLASH_ARCHITECTURE.md#并发安全保证)

### 2. Service Isolate 架构

**为什么需要?**
- VPN 服务运行在后台
- 主 Isolate 可能被销毁
- 需要独立的 Dart 运行时

**实现:**
```kotlin
// ClashService.kt
serviceEngine = FlutterEngine(Application.application)
val entrypoint = DartExecutor.DartEntrypoint(..., "_clashService")
serviceEngine?.dartExecutor?.executeDartEntrypoint(entrypoint)
```

详见 [CLASH_ARCHITECTURE.md § Service Isolate 架构](./CLASH_ARCHITECTURE.md#2-android-service-层-clashservicekt)

### 3. Android VPN 路由配置

**关键:** `getAndroidVpnOptions()` 返回 35+ 详细 CIDR 路由

**为什么重要?**
- 避免 PermissionMonitor error 22
- 支持 bypass-LAN
- 兼容模拟器

详见 [CLASH_TROUBLESHOOTING.md § 问题 1](./CLASH_TROUBLESHOOTING.md#问题-1-vpn-连接失败日志显示-permissionmonitor-error-22-einval)

## 🐛 遇到问题?

1. **查看故障排查文档**
   - [CLASH_TROUBLESHOOTING.md](./CLASH_TROUBLESHOOTING.md) 包含所有常见问题

2. **收集诊断信息**
   ```bash
   # 系统信息
   adb shell "getprop ro.build.version.release"

   # 应用日志
   adb logcat -d > full_log.txt

   # 核心信息
   cd core
   make verify
   ```

3. **提交 Issue**
   - 使用诊断信息模板
   - 包含复现步骤
   - 附上日志文件

## 🤝 贡献指南

### 代码规范

项目遵循以下原则:
- **KISS** (Keep It Simple, Stupid) - 简单至上
- **DRY** (Don't Repeat Yourself) - 杜绝重复
- **SOLID** - 面向对象设计原则
- **YAGNI** (You Aren't Gonna Need It) - 精益求精

### 提交流程

1. Fork 项目
2. 创建特性分支 (`git checkout -b feature/amazing`)
3. 提交更改 (`git commit -m 'feat: add amazing feature'`)
4. 推送分支 (`git push origin feature/amazing`)
5. 创建 Pull Request

### Commit 规范

使用 Conventional Commits:
- `feat:` 新功能
- `fix:` 修复 Bug
- `docs:` 文档更新
- `refactor:` 代码重构
- `perf:` 性能优化
- `test:` 测试相关
- `chore:` 构建/工具链

## 📞 获取帮助

- **GitHub Issues:** [提交问题](https://github.com/your-repo/issues)
- **文档索引:** 您正在阅读!
- **外部资源:**
  - [Clash Meta Wiki](https://wiki.metacubex.one/)
  - [Flutter FFI 文档](https://dart.dev/guides/libraries/c-interop)
  - [Android VPN 指南](https://developer.android.com/reference/android/net/VpnService)

## 📝 更新日志

| 日期 | 版本 | 更新内容 |
|------|------|----------|
| 2025-10-25 | 1.0.0 | 完成 Xboard-Mihomo 核心集成 |
| 2025-10-25 | 1.0.0 | 修复 FFI 并发安全问题 |
| 2025-10-25 | 1.0.0 | 添加完整技术文档 |

## 📄 许可证

本项目采用 [LICENSE](../LICENSE) 许可证。

---

**最后更新:** 2025-10-25
**维护者:** LighthouseApp 开发团队