Initial Flutter project structure、

2026-07-15 12:01:04 +08:00
commit 120525741d
138 changed files with 7888 additions and 0 deletions
@@ -0,0 +1,343 @@
+# Patbond Flutter 项目结构说明
+
+## 项目概况
+
+这是一个标准 Flutter 新项目，项目名是 `patbond_flutter`。目前还没有真正的业务代码，只有 Flutter 模板生成的计数器 Demo。
+
+核心信息：
+
+- 入口文件：`lib/main.dart`
+- 依赖配置：`pubspec.yaml`
+- 当前依赖很少：只有 Flutter SDK、`cupertino_icons`、`flutter_lints`
+- 业务结构尚未搭建
+- 支持的平台包括：Android、iOS、Web、Linux、macOS、Windows
+
+## 顶层目录说明
+
+### `lib/`
+
+这是之后主要写代码的地方。
+
+当前只有：
+
+```text
+lib/main.dart
+```
+
+里面是 Flutter 默认的计数器 Demo，包括：
+
+- `main()`：应用启动入口
+- `MyApp`：根组件，创建 `MaterialApp`
+- `MyHomePage`：默认首页
+- `_MyHomePageState`：计数器状态逻辑
+
+以后项目的大部分页面、组件、状态管理、接口请求、业务逻辑都会放在 `lib/` 下面。
+
+### `pubspec.yaml`
+
+Flutter 项目的核心配置文件。
+
+它负责：
+
+- 项目名称
+- Dart SDK 版本
+- 第三方依赖
+- 图片、字体等资源声明
+- Flutter 配置
+
+以后添加依赖会改这里，比如：
+
+```yaml
+dependencies:
+  dio: ^x.x.x
+  go_router: ^x.x.x
+  flutter_riverpod: ^x.x.x
+```
+
+如果要添加图片资源，也会在这里配置：
+
+```yaml
+flutter:
+  assets:
+    - assets/images/
+```
+
+### `pubspec.lock`
+
+依赖锁定文件。
+
+它记录当前项目实际安装的依赖版本。一般不要手动改，由 `flutter pub get` 自动生成和更新。
+
+### `analysis_options.yaml`
+
+Dart / Flutter 代码检查规则配置。
+
+当前使用的是：
+
+```yaml
+include: package:flutter_lints/flutter.yaml
+```
+
+也就是 Flutter 推荐的默认 lint 规则。
+
+以后如果团队有代码规范，可以在这里加规则，比如是否强制单引号、是否允许 `print` 等。
+
+### `test/`
+
+测试目录。
+
+当前只有：
+
+```text
+test/widget_test.dart
+```
+
+这是 Flutter 默认生成的计数器测试，用来测试点击按钮后数字是否增加。
+
+当删掉默认计数器页面后，这个测试大概率也要同步修改或删除，否则测试会失败。
+
+### `android/`
+
+Android 原生工程目录。
+
+里面是 Android 平台相关配置，例如：
+
+- 包名
+- Gradle 配置
+- AndroidManifest
+- 权限
+- 启动图标
+- 原生插件注册
+
+平时写 Flutter UI 不需要经常碰它。
+
+什么时候会改：
+
+- 修改 Android 应用包名
+- 添加相机、定位、蓝牙等权限
+- 配置 Firebase、推送、地图 SDK
+- 修改 Android 启动页、图标、签名
+
+### `ios/`
+
+iOS 原生工程目录。
+
+里面是 Xcode 工程配置，例如：
+
+- `Runner.xcworkspace`
+- `Info.plist`
+- iOS 权限
+- Bundle ID
+- iOS 插件配置
+
+什么时候会改：
+
+- 修改 iOS Bundle ID
+- 添加相机、相册、定位等权限描述
+- 配置推送、登录、支付、地图
+- 修改 iOS 启动页、图标、签名
+
+### `web/`
+
+Flutter Web 平台目录。
+
+主要文件：
+
+- `index.html`
+- `manifest.json`
+- `favicon.png`
+- `icons/`
+
+如果要把项目跑成 Web 应用，会用到这里。
+
+什么时候会改：
+
+- 改网页标题
+- 改 favicon
+- 配置 PWA
+- 添加 Web 端脚本
+- 配置第三方 Web SDK
+
+### `linux/`、`macos/`、`windows/`
+
+桌面端平台目录。
+
+如果项目只做移动端，这几个目录通常不用管。
+
+它们的作用类似 `android/` 和 `ios/`，只是对应桌面端平台。
+
+### `build/`
+
+构建产物目录。
+
+由 Flutter 自动生成。
+
+不要手动改，也不应该提交重要业务代码到这里。
+
+### `.dart_tool/`
+
+Dart / Flutter 工具生成的缓存目录。
+
+不要手动改。
+
+### `.idea/`、`patbond_flutter.iml`
+
+JetBrains / Android Studio / IntelliJ 的 IDE 配置文件。
+
+通常不写业务逻辑。
+
+### `.metadata`
+
+Flutter 项目元信息。
+
+一般不需要手动改。
+
+### `README.md`
+
+项目说明文档。
+
+现在大概率还是模板内容。以后可以写：
+
+- 项目介绍
+- 如何运行
+- 环境要求
+- 常用命令
+- 目录结构
+- 开发规范
+
+## 应该从哪里开始写
+
+第一步应该从 `lib/` 开始，不要先改平台目录。
+
+当前项目还处于默认模板阶段，建议先把 `lib/` 组织起来。
+
+推荐的最小起步结构：
+
+```text
+lib/
+  main.dart
+  app/
+    app.dart
+    router.dart
+    theme.dart
+  features/
+    home/
+      home_page.dart
+  shared/
+    widgets/
+    constants/
+    utils/
+```
+
+含义：
+
+### `main.dart`
+
+只保留启动逻辑，例如：
+
+```dart
+void main() {
+  runApp(const App());
+}
+```
+
+### `app/app.dart`
+
+放全局 `MaterialApp`，例如主题、路由、全局配置。
+
+### `app/router.dart`
+
+如果项目有多个页面，路由放这里。
+
+前期简单项目可以先不用路由库，直接用 Flutter 自带 `Navigator`。如果页面比较多，可以考虑 `go_router`。
+
+### `app/theme.dart`
+
+统一管理颜色、字体、按钮样式等主题配置。
+
+### `features/`
+
+按功能模块放业务代码。
+
+例如：
+
+```text
+features/
+  home/
+  auth/
+  profile/
+  bond/
+  settings/
+```
+
+每个功能模块下面可以继续放：
+
+```text
+pages/
+widgets/
+models/
+services/
+```
+
+但一开始不要拆太细，避免目录很多但没内容。
+
+### `shared/`
+
+放跨多个功能复用的东西，例如：
+
+- 通用组件
+- 常量
+- 工具函数
+- 通用样式
+- 网络层
+- 本地存储封装
+
+## 实际开发顺序建议
+
+1. 先确定产品的第一个页面，例如首页、登录页、仪表盘、列表页。然后把默认计数器 Demo 替换掉。
+2. 清理 `lib/main.dart`，不要继续在 `main.dart` 里堆所有页面。可以把根 App 和首页拆出去。
+3. 建立最小目录结构，建议先建 `lib/app/app.dart` 和 `lib/features/home/home_page.dart`，先不要一口气创建很多空目录。
+4. 确定状态管理方案。如果只是简单页面，先用 `StatefulWidget`；如果会有登录状态、接口数据、多个页面共享状态，建议尽早选一个方案，例如 `riverpod`、`provider`、`bloc`。
+5. 确定路由方案。页面少可以先用 `Navigator.push`；页面多、需要登录拦截、深链接，建议用 `go_router`。
+6. 添加资源目录。如果要放图片、图标、字体，可以加 `assets/images/`、`assets/icons/`、`assets/fonts/`，然后在 `pubspec.yaml` 注册。
+7. 再处理 Android / iOS 配置。只有当需要权限、包名、签名、推送、第三方 SDK 时，才去改 `android/` 和 `ios/`。
+
+## 当前这个项目最重要的文件
+
+现在最应该关注这几个：
+
+```text
+lib/main.dart
+pubspec.yaml
+analysis_options.yaml
+test/widget_test.dart
+```
+
+其中真正开始写业务，入口是：
+
+```text
+lib/main.dart
+```
+
+但不建议长期把所有代码写在 `main.dart` 里。
+
+## 建议的下一步
+
+如果准备正式开始项目，建议先做这件事：
+
+把默认计数器 Demo 改成干净的应用骨架：
+
+```text
+lib/
+  main.dart
+  app/
+    app.dart
+    theme.dart
+  features/
+    home/
+      home_page.dart
+```
+
+然后首页先写一个简单的 `HomePage`，后续所有功能都从 `features/` 下面扩展。
+
+这个项目还很干净，最适合先把结构搭好，再开始写业务页面。