# 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/` 下面扩展。

这个项目还很干净，最适合先把结构搭好，再开始写业务页面。