# 权限和网络安全配置指南

## 问题描述

如果遇到 "DocsAPI 未加载成功" 错误，即使服务器可以访问，通常是因为 Android/iOS 的网络安全策略阻止了 WebView 加载外部资源。

## Android 配置

### 1. AndroidManifest.xml

确保在 `android/app/src/main/AndroidManifest.xml` 中添加了以下配置：

```xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- 网络权限 -->
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    
    <application
        android:usesCleartextTraffic="true"
        android:networkSecurityConfig="@xml/network_security_config"
        ...>
        ...
    </application>
</manifest>
```

### 2. network_security_config.xml

创建文件 `android/app/src/main/res/xml/network_security_config.xml`：

```xml
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <!-- 允许所有 HTTPS 连接 -->
    <base-config cleartextTrafficPermitted="true">
        <trust-anchors>
            <certificates src="system" />
            <certificates src="user" />
        </trust-anchors>
    </base-config>
    
    <!-- 允许特定域名的 HTTP 连接（如果需要） -->
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">localhost</domain>
        <domain includeSubdomains="true">10.0.2.2</domain>
    </domain-config>
</network-security-config>
```

### 3. 目录结构

确保目录结构正确：
```
android/app/src/main/res/
└── xml/
    └── network_security_config.xml
```

## iOS 配置

### Info.plist

在 `ios/Runner/Info.plist` 中添加：

```xml
<key>NSAppTransportSecurity</key>
<dict>
    <!-- 允许所有 HTTPS 连接 -->
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>
```

或者只允许特定域名（更安全）：

```xml
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSExceptionDomains</key>
    <dict>
        <key>document.23544.com</key>
        <dict>
            <key>NSIncludesSubdomains</key>
            <true/>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <false/>
        </dict>
    </dict>
</dict>
```

## 验证配置

### 1. 检查文件是否存在

**Android**:
```bash
ls -la example/android/app/src/main/res/xml/network_security_config.xml
```

**iOS**:
```bash
grep -A 5 "NSAppTransportSecurity" example/ios/Runner/Info.plist
```

### 2. 重新构建应用

配置更改后，需要完全重新构建应用：

```bash
# 清理构建缓存
flutter clean

# 重新获取依赖
flutter pub get

# 重新构建
flutter run
```

### 3. 检查日志

运行应用后，查看日志中是否有：
- ✅ `页面加载完成`
- ✅ `DocsAPI loaded successfully`
- ❌ 如果有错误，查看具体的错误信息

## 常见问题

### Q: 配置后仍然无法加载？

**A**: 尝试以下步骤：

1. **完全清理并重建**:
   ```bash
   flutter clean
   cd android && ./gradlew clean && cd ..
   flutter pub get
   flutter run
   ```

2. **检查网络权限**:
   - 确保 AndroidManifest.xml 中有 `INTERNET` 权限
   - 确保应用有网络访问权限（在设备设置中检查）

3. **检查服务器证书**:
   - 如果使用自签名证书，需要在 `network_security_config.xml` 中添加证书配置

4. **查看详细日志**:
   - 运行应用时查看控制台输出
   - 查看是否有 JavaScript 错误

### Q: 生产环境是否安全？

**A**: 当前配置允许所有 HTTPS 连接，适合开发环境。生产环境建议：

1. **Android**: 只允许特定域名
   ```xml
   <domain-config cleartextTrafficPermitted="false">
       <domain includeSubdomains="true">your-server.com</domain>
   </domain-config>
   ```

2. **iOS**: 只允许特定域名（见上方 iOS 配置示例）

### Q: 是否需要其他权限？

**A**: 对于基础功能，只需要：
- `INTERNET` - 网络访问
- `ACCESS_NETWORK_STATE` - 检查网络状态

如果使用图片插入功能，还需要：
- `CAMERA` - 相机权限
- `READ_EXTERNAL_STORAGE` - 读取存储权限（Android）
- `WRITE_EXTERNAL_STORAGE` - 写入存储权限（Android）

## 测试清单

- [ ] AndroidManifest.xml 包含 INTERNET 权限
- [ ] AndroidManifest.xml 引用了 network_security_config
- [ ] network_security_config.xml 文件存在且配置正确
- [ ] iOS Info.plist 包含 NSAppTransportSecurity 配置
- [ ] 执行了 `flutter clean` 和重新构建
- [ ] 在浏览器中可以访问 API 脚本 URL
- [ ] 应用日志显示页面加载完成
- [ ] 应用日志显示 DocsAPI 加载成功

## 相关文件

- `example/android/app/src/main/AndroidManifest.xml`
- `example/android/app/src/main/res/xml/network_security_config.xml`
- `example/ios/Runner/Info.plist`

## 参考文档

- [Android Network Security Configuration](https://developer.android.com/training/articles/security-config)
- [iOS App Transport Security](https://developer.apple.com/documentation/security/preventing_insecure_network_connections)