项目名称：智能影记 - Memoria
时间：2026.03.20 - 2026.03.23
核心任务：Flutter 客户端目录规范制定、核心依赖引入、Git 协作基建

---

一、 前言：为什么“建文件夹”也值得写一篇博客？

在结束了高强度的产品脑暴和 Figma 原型设计后，我们的 Memoria 项目终于迎来了代码落地的时刻。

很多初学者在写跨平台 App 时，习惯于把所有的 UI 逻辑、网络请求甚至本地数据库调用全塞进 lib/main.dart 或是几个零散的页面文件里。对于普通的课设，这或许行得通；但 Memoria 是一个集成了端侧 C++ NCNN 推理、本地高维向量数据库检索以及云端大模型通信的复杂异构系统。

如果在第一周不把模块的边界划清楚，随着后续几位队友的代码不断合入，整个工程必将陷入“牵一发而动全身”的“屎山”危机。因此，本周我个人的核心工作，就是为团队搭建一个具有高度可扩展性的 Flutter 客户端骨架。

---

二、 工程架构设计：融合 AI 工具链的“大平层”

针对我们的业务需求，我和负责 AI 与后端的队友们进行了多轮对齐，最终在 Gitee 上初始化了如下的工程目录树：

intelligent_imaging_memory/
├── ai_tools/             # 端侧 AI 脚本、模型量化导出工具（Python）
├── checkpoints/          # 模型权重与检查点（受 .gitignore 保护）
├── android/              # Android 原生工程（含 NCNN C++ FFI 桥接层）
├── ios/                  # iOS 原生工程
├── lib/                  # Flutter 核心 Dart 源码
│   ├── core/             # 全局核心层（主题、常量、路由中心）
│   ├── models/           # 数据模型层（端云通信的标准数据结构）
│   ├── services/         # 接口服务层（AI 推理调度、本地 DB 调用）
│   └── views/            # 表现层（UI 页面与组件）
├── .gitignore            # 严格的团队协作忽略规范
├── launch.sh             # 自动化编译/运行脚本
└── pubspec.yaml          # Flutter 依赖配置

2.1 目录设计

1. 多端与 AI 的物理融合：我们将 ai_tools 和 checkpoints 直接放在了 Flutter 根目录下。这并非杂乱，而是为了让负责端侧模型部署的队友能在这个统一的仓库里管理所有的导出脚本，真正实现“代码即基础设施”。
2. 逻辑与视图的严格解耦：在 lib 目录下，所有的 AI 模型调用接口被抽象在 services/ai_service.dart 中。未来，UI 层的同学（我）只需要调用 AIService.extractFeatures(image)，而不需要关心底层究竟是走了 FFI 桥接还是 HTTP 请求。

---

三、 核心依赖选型（pubspec.yaml 解析）

在初始化的 pubspec.yaml 中，并没有引入过多花哨的 UI 库，而是重点夯实了项目的“地基”。以下是我们在会议上共同确定的几个核心依赖包：

3.1 状态管理与路由

• provider: 经过团队评估，虽然 GetX 更容易上手，但 Provider 的状态流转更加透明可控，非常适合我们这种有着复杂数据流（如从相册读取 -> 传递给端侧模型提取向量 -> 返回 UI 展示）的应用。
• go_router: 官方推荐的声明式路由，能够很好地处理深层链接，为以后可能的外部应用唤醒（比如从系统相册直接分享到 Memoria）打下基础。

3.2 底层通信与存储基建

• ffi: 这是本项目最重要的依赖之一。Memoria 的核心创新点在于端侧 AI。我们将利用 Dart FFI（Foreign Function Interface）直接调用用 C++ 编写的 NCNN/ONNX 推理引擎，实现 Flutter UI 与底层算力的高效通信。
• sqflite: 用于本地结构化数据的存储。在接下来的预研中，我们将探索结合 SQLite-VSS 扩展，直接在本地完成高维图像向量的余弦相似度检索。

---

四、 避坑指南：大文件隔离与 .gitignore 规约

跨模态项目最容易踩的坑就是版本控制仓库的急剧膨胀。在第一次 Push 代码时，如果不加限制，Flutter 的 build 产物、iOS 的 Pods 依赖，甚至上百兆的 .onnx 模型文件会瞬间撑爆 Gitee 的缓冲区。

为此，我们在初始化仓库时，拉出了一条严格的 .gitignore 防线：

# 核心阻断：防止编译产物污染
build/
.dart_tool/
ios/Pods/

# 核心阻断：防止模型文件撑爆仓库
checkpoints/
*.onnx
*.bin
*.param

团队规约：所有的模型权重文件和大型测试数据集，均通过团队群文件或网盘流转。开发者拉取代码后，需根据文档手动将模型放入 checkpoints 目录下。这一举措保证了我们的代码仓库永远保持“轻便敏捷”。

---

五、 本周总结与后续展望

搭建框架的过程，其实也是团队技术思维不断“碰撞与对齐”的过程。从明确 services 层的接口契约，到制定严格的代码提交规约，这些看似枯燥的基建工作，实际上为未来 14 周的高效并行开发扫清了障碍。

目前，整个项目的骨架已立，粮草先行。

接下来的攻坚计划：

1. 完善 lib/core/theme，将 Figma 中的“毛玻璃”与“沉浸式”设计规范转化为 Dart 代码。
2. 配合负责 AI 的队友，走通第一个 C++ FFI 的“Hello World”调用，验证端侧通道的可行性。

大平层已建好，下周开始“内部精装修”！