backend/       Kotlin + Spring Boot 模块化单体
mobile/        Flutter 移动客户端
admin-web/     React + TypeScript 表单设计与流程配置管理端
ai-service/    Python AI 服务
contracts/     OpenAPI 与事件契约
deploy/        本地与部署配置
docs/          产品、架构和开发文档
scripts/       开发辅助脚本

开发环境

JDK 21
Docker 28+
Docker Compose v2
Flutter stable（与当前主机架构一致）
Python 3.11+

复制 .env.example 为 .env 后，可使用 docker compose --env-file .env -f deploy/compose/compose.yaml up -d 启动基础依赖。

本地 PostgreSQL 暴露在 127.0.0.1:15432，避免与系统或其他项目常用的 5432 端口冲突。

千问 AI 服务通过 QWEN_API_KEY 环境变量读取密钥。密钥只能放在被 Git 忽略的本地 .env 或部署密钥系统中，不得写入 .env.example、代码、镜像或 Flutter 客户端。启动 AI 服务：

docker compose --env-file .env -f deploy/compose/compose.yaml up -d ai-service

Android 模拟器登录前运行 scripts/dev-android-reverse.sh，使 Keycloak 的固定开发 Issuer http://localhost:8081/realms/aioa 与 Android 回调环境保持一致，并允许访问 MinIO 预签名地址。iOS Simulator 可直接使用默认本机地址。

后端测试：

cd backend
export JAVA_HOME=/usr/local/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home
export GRADLE_USER_HOME=/tmp/aioa-gradle-home
./gradlew --no-daemon test

当前实施范围和验收标准见 docs/product/mvp.md。

一键执行本地提交前验证：

./scripts/verify-all.sh

需要同时生成 Android 和 iOS Simulator 构建产物时：

AIOA_FULL_BUILD=1 ./scripts/verify-all.sh

Flutter 已实现 Schema 驱动的请假表单卡片演示，详见 docs/engineering/mobile-schema-forms.md。

Web 管理端已实现可视化表单设计、实时移动卡片预览和版本发布。运行与验证方式见 admin-web/README.md。

持续集成

仓库根目录的 .gitlab-ci.yml 默认执行：

JDK 21 后端测试，并上传 JUnit 报告；
Python 3.12 AI 服务编译检查与测试；
Flutter 格式检查、静态分析和测试；
React 管理端单元测试和生产构建；
Android Debug APK 构建与产物归档。

流水线不需要数据库、Keycloak 或千问密钥。iOS 构建需要带 Xcode 的 macOS GitLab Runner，配置 Runner 后按流水线文件末尾的说明启用。

移动推送

移动端使用 Firebase Cloud Messaging，同时承载 Android FCM 与 iOS APNs。生产构建需要分别提供 Firebase 项目的 google-services.json 和 GoogleService-Info.plist，后端通过 FIREBASE_CREDENTIALS_FILE 指向 Firebase Admin 服务账号 JSON。凭证文件必须由部署密钥系统挂载，不得提交到仓库。

未配置 Firebase 时，Flutter 会自动降级，站内通知仍然可用；后端推送 outbox 会保留并延迟重试。FlutterFire 当前最低支持 iOS 15，因此项目部署目标已统一调整为 iOS 15。