Classboard

课堂作业管理应用 - 完全离线版本

功能

• 存储作业
• 展示作业
• 支持多平台：Linux、Windows、Android、iOS

架构

• UI: Flutter
• Native: C++20 (Foreign Function Interface)
• Database: SQLite
• 离线运行 - 无需网络连接

---

快速开始

环境要求

通用要求:

• Flutter SDK 3.0+
• Dart SDK 3.9+

平台特定要求:

平台	额外要求
Linux	CMake 3.14+, GCC 9+
Windows	CMake 3.14+, Visual Studio 2022
Android	Android NDK 26+
iOS	macOS, Xcode 15+

首次设置

.env文件示例

DATABASE_PATH=./classboard.db #数据库文件位置（相对路径）
API_BASE_URL=http://localhost:8080
NATIVE_LIB_LINUX=native/build/libclassboard_native.so #注意，打包时不要用这个

# 1. 获取依赖
flutter pub get

# 2. 生成配置代码
dart run build_runner build

# 3. 构建原生库（所有平台都需要）
# Linux/macOS
./build_native.sh

# Windows
build_native.bat

---

平台详细指南

打包发布时需要修改.env文件内指明打包产物中原生库的相对路径，并保证你的原生库在你最终在你的打包产物中
注意：修改后需要重新生成配置代码

🐧 Linux

开发调试

# 直接运行（调试模式）
flutter run -d linux

# 或指定设备
flutter run -d linux --debug

# 热重载：运行中按 'r'
# 热重启：运行中按 'R'
# 退出：运行中按 'q'

打包发布

# 构建 Release 版本
flutter build linux --release

# 输出位置
# ./build/linux/x64/release/bundle/

# 打包为 zip
cd build/linux/x64/release/bundle
zip -r classboard-linux.zip *

常见问题

# 如果遇到 GTK 相关错误
sudo apt install libgtk-3-dev

# 如果遇到 CMake 错误
sudo apt install cmake ninja-build

---

🪟 Windows

开发调试

# 使用 PowerShell 或 CMD

# 直接运行（调试模式）
flutter run -d windows

# 或指定设备
flutter run -d windows --debug

打包发布

# 构建 Release 版本
flutter build windows --release

# 输出位置
# ./build/windows/x64/runner/Release/

# 打包为 zip
cd build/windows/x64/runner/Release
Compress-Archive -Path * -DestinationPath classboard-windows.zip

常见问题

# 确保 Visual Studio 2022 已安装 C++ 桌面开发组件
# 在 Visual Studio Installer 中选择 "使用 C++ 的桌面开发"

---

🤖 Android

开发调试

# 连接设备或启动模拟器
adb devices

# 直接运行（调试模式）
flutter run -d android

# 或指定设备
flutter run -d <device_id>

# 查看日志
flutter logs

打包发布

# 构建 APK (包含所有架构)
flutter build apk --release

# 输出位置
# ./build/app/outputs/flutter-apk/app-release.apk

# 构建分架构 APK (更小体积)
flutter build apk --split-per-abi

# 输出位置
# ./build/app/outputs/flutter-apk/
#   - app-armeabi-v7a-release.apk (32 位 ARM)
#   - app-arm64-v8a-release.apk (64 位 ARM)
#   - app-x86_64-release.apk (x86_64)

签名配置

# 1. 创建密钥库
keytool -genkey -v -keystore ~/classboard-key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias classboard

# 2. 在 android/key.properties 中配置
# storePassword=<密码>
# keyPassword=<密码>
# keyAlias=classboard
# storeFile=/home/用户/classboard-key.jks

# 3. 修改 android/app/build.gradle.kts 添加签名配置

---

🍎 iOS (需要 macOS)

开发调试

# 直接运行（调试模式）
flutter run -d ios

# 或指定设备
flutter run -d <device_id>

# 在模拟器上运行
flutter run -d "iPhone 15"

打包发布

# 构建 IPA (需要开发者账号)
flutter build ios --release --no-codesign

# 输出位置
# ./build/ios/iphoneos/Runner.app

# 使用 Xcode 打包
# 1. 打开 ios/Runner.xcworkspace
# 2. Product -> Archive
# 3. Distribute App

签名配置

# 1. 在 Xcode 中配置自动签名
# 2. 或手动配置：
#    - 打开 ios/Runner.xcworkspace
#    - 选择 Runner 项目
#    - Signing & Capabilities
#    - 选择 Team 和 Bundle Identifier

---

原生库开发

修改 C++ 代码后

# 重新构建原生库
# Linux/macOS
./build_native.sh

# Windows
build_native.bat

# 重新运行 Flutter
flutter run

构建后需要修改.env文件

---

项目结构

classboard/
├── lib/                    # Dart 源代码
│   ├── screens/           # UI 界面
│   ├── models/            # 数据模型
│   ├── services/          # 服务层
│   └── repositories/      # 数据仓库
├── native/                 # C++ 原生代码
│   ├── api/               # API 头文件
│   └── src/               # 实现文件
├── android/               # Android 平台配置
├── ios/                   # iOS 平台配置
├── linux/                 # Linux 平台配置
├── windows/               # Windows 平台配置
├── build_native.sh        # 原生库构建脚本
└── pubspec.yaml           # Flutter 配置

---

常用命令

# 清理构建缓存
flutter clean

# 检查 Flutter 环境
flutter doctor -v

# 查看依赖
flutter pub get

# 运行测试
flutter test

# 代码格式化
dart format .

# 代码分析
flutter analyze

---

清理开发产物

快速清理

# 清理 Flutter 构建产物
flutter clean

# 清理 Dart 缓存
rm -rf .dart_tool/
rm -rf .packages
rm -rf pubspec.lock

# 重新获取依赖
flutter pub get

完整清理（推荐用于解决奇怪的问题）

# 1. 清理所有构建产物
flutter clean

# 2. 删除缓存和临时文件
rm -rf .dart_tool/
rm -rf build/
rm -rf .packages
rm -rf pubspec.lock
rm -rf android/.gradle/
rm -rf ios/Pods/
rm -rf ios/.symlinks/

# 3. 重新获取依赖
flutter pub get

# 4. 重新生成配置代码
dart run build_runner build --delete-conflicting-outputs

# 5. 重新构建原生库（如需要）
./build_native.sh   # Linux/macOS
build_native.bat    # Windows

清理特定平台

# Android
cd android && ./gradlew clean && cd ..
rm -rf android/.gradle/
rm -rf android/app/build/

# iOS (macOS only)
cd ios && pod deintegrate && pod install && cd ..
rm -rf ios/Pods/
rm -rf ios/build/

# Linux
rm -rf build/linux/

# Windows
rmdir /s /q build\windows  # PowerShell
# 或
rm -rf build/windows/      # Git Bash

Git 清理

# 清理未跟踪的文件（小心使用！）
git clean -fd

# 预览将要删除的文件
git clean -fdn

# 清理未跟踪的文件和目录
git clean -fdx

恢复初始状态

# 完全清理并恢复到初始开发状态
flutter clean
rm -rf .dart_tool/ build/
rm -rf android/.gradle/ android/app/build/
rm -rf ios/Pods/ ios/build/
rm -rf linux/flutter/ephemeral/
rm -rf windows/flutter/ephemeral/
flutter pub get
dart run build_runner build --delete-conflicting-outputs

---

开发建议

1. 调试模式 使用 flutter run 或 flutter run --debug
2. 性能测试 使用 flutter run --profile
3. 发布版本 使用 flutter build <platform> --release
4. 热重载 开发时按 r 快速刷新
5. 热重启 开发时按 R 完全重启
6. 遇到问题 先尝试 flutter clean 和 flutter pub get

---