# Flutter星图

**Repository Path**: app_36/flutter-star-chart

## Basic Information

- **Project Name**: Flutter星图
- **Description**: Flutter星图是一套面向 Flutter 组件工程的智能测试与交付系统，支持自然语言驱动测试、自动回归与可行性交付报告。
- **Primary Language**: Unknown
- **License**: Unlicense
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-20
- **Last Updated**: 2026-03-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Flutter星图

`flutter_components` 是一套面向 Flutter 项目的自动化测试与交付系统，核心目标是：
**让你用更少命令跑通回归、拿到可读结论，并能在 CI 持续门禁。**

## 核心功能与亮点

- **Flutter App 核心功能**：提供可复用组件与页面架构能力，支持分页、Sliver/Tab、状态管理与本地插件协作（`hk_base`、`hk_net`、`flutter_ui`）。
- **AI 治理能力**：基于 Rules + Skills + AGENTS 协议形成统一研发约束，覆盖架构规范、测试规范、CI 门禁、代码优化与协作流程。
- **自动化测试能力**：支持 Agentic `smoke/full/explore` 回归、结构化轨迹（`operation_trace.jsonl`）、真实截图/视频证据链、PyQt5 可视化工作台与 CI 同口径门禁。

## 应用国际化与软重启（App）

- **默认语言**：`en_US`；**界面支持**：`zh_CN`（标签归一化见 `lib/utils/app_lang_tag.dart`，翻译入口 `TranslationService` / `lib/services/langs/`）。
- **全局控制器**：`AppLocaleController`（`lib/services/app_locale_controller.dart`）在 `Global.init` 内 `Get.put(..., permanent: true)`；启动时 `syncLocaleFromStorageToGetX`（`lib/services/app_locale_bootstrap.dart`）对齐持久化与 `Get.locale`。
- **切换语言（对齐 mall-app）**：设置页通过 `HKDialog.showBottomSelectListPicker` 单选 → `applyLanguage`（更新 locale、持久化、`localeRevision`、Dio 语言头）；非测试环境调用 **`AppRestartService.restart()`**：`Get.reset()` → `await Global.init()` → **`RestartWidget`** 重建根树（`lib/services/app_restart_service.dart`、`lib/components/common/restart_widget.dart`）。`main.dart` 使用 `AppRestartService.wrapApp` 包裹根组件。
- **依赖就绪**：`Global.areDependenciesReady` 在 `Global.init` 完整成功后为 `true`；`MyApp` 仅在未就绪时执行 `Global.init()`，避免软重启后重复初始化；`AppLocaleController` 同步 Dio 前亦依赖该标志。
- **首页商品 Tab**：通过 `localeRevision` 触发分类/列表刷新，避免对整页加 `KeyedSubtree` 导致同一 `RefreshController` 被两个 `SmartRefresher` 复用的问题。
- **首页一级 Tab 壳层**：顶栏渐变与子页背景锚点见 `lib/pages/home/home_shell_theme.dart`；`HKCommonTab` 字号与顶栏/产线布局约定见 [`doc/features/home/README.md`](doc/features/home/README.md) 第 6 节。
- **请求层 locale**：首页 Banner/热词等接口统一透传 `locale`；客户端未设置时回退 `en_US`，仅语言码为 `zh` 时回退 `zh_CN`，其余可按 `*_US` 规则拼接（与 Dio/工具层一致）。

## 仓库布局（App + 后端）

- **Flutter App**：`lib/`、`test/`、`ios/`、`android/` 等。
- **Python 后端**：`backend/`（与 App **同一 Git 仓库**，便于接口契约、联调与同步修改）。本地启动与测试见该目录下 `README.md`、`Makefile`。
- **CI**：后端变更触发 [`.github/workflows/backend-ci.yml`](.github/workflows/backend-ci.yml)（路径过滤 `backend/**`）。

## 测试快速入口

- 测试 1 分钟上手与产物说明：[`doc/zh/content/测试快速上手.md`](doc/zh/content/测试快速上手.md)
- CI 对应关系与本地命令映射：见 `测试快速上手.md` 的“CI 对应命令映射”

## 最常用入口

- Flutter App 核心功能：[`plugins/hk_base/README.md`](plugins/hk_base/README.md)
- 首页 App/admin 边界与接口契约：
  - [`doc/features/home/BOUNDARY.md`](doc/features/home/BOUNDARY.md)
  - [`doc/features/home/API_CONTRACT.md`](doc/features/home/API_CONTRACT.md)
  - [`doc/features/home/FIELD_DICTIONARY.md`](doc/features/home/FIELD_DICTIONARY.md)
- Flutter App 接入指南：[`doc/zh/content/FlutterApp自动化测试功能接入指南.md`](doc/zh/content/FlutterApp自动化测试功能接入指南.md)
- AI 入口（Test Agent）：[`tool/test_agent/README.md`](tool/test_agent/README.md) — 快捷启动：`bash tool/test_agent/run_webui.sh`（默认 <http://127.0.0.1:8030/>）
- RAG 知识库（长期记忆 + 检索）：[`rag/README.md`](rag/README.md) — 初始化：`dart run tool/rag/rag_cli.dart init`
- 自动化测试总入口：[`doc/zh/content/测试快速上手.md`](doc/zh/content/测试快速上手.md)
- 自动化测试交付指南：[`doc/zh/content/自动化测试交付指南.md`](doc/zh/content/自动化测试交付指南.md)
- 测试工具链说明：[`tool/testing/README.md`](tool/testing/README.md)
- GUI（Flutter 测试工作台）：[`tool/gui_pyqt5/README.md`](tool/gui_pyqt5/README.md)

## `doc/zh` 中文文档中心

- 总览与上手：
  - 项目概述：[`doc/zh/content/项目概述.md`](doc/zh/content/项目概述.md)
  - 快速开始：[`doc/zh/content/快速开始.md`](doc/zh/content/快速开始.md)
  - 部署指南：[`doc/zh/content/部署指南.md`](doc/zh/content/部署指南.md)
- 测试与交付：
  - 测试快速上手：[`doc/zh/content/测试快速上手.md`](doc/zh/content/测试快速上手.md)
  - 自动化测试交付指南：[`doc/zh/content/自动化测试交付指南.md`](doc/zh/content/自动化测试交付指南.md)
  - Flutter App 接入指南：[`doc/zh/content/FlutterApp自动化测试功能接入指南.md`](doc/zh/content/FlutterApp自动化测试功能接入指南.md)
  - 测试策略：[`doc/zh/content/测试策略.md`](doc/zh/content/测试策略.md)
- 治理与优化：
  - AI 治理规则使用说明：[`doc/zh/content/AI治理规则使用说明.md`](doc/zh/content/AI治理规则使用说明.md)
  - 优化类任务关键词触发建议清单：[`doc/zh/content/优化类任务关键词触发建议清单.md`](doc/zh/content/优化类任务关键词触发建议清单.md)
  - 首页性能优化指南：[`doc/zh/content/首页性能优化指南.md`](doc/zh/content/首页性能优化指南.md)
- 架构与组件（按模块深入）：
  - 架构设计总览：[`doc/zh/content/架构设计/架构设计.md`](doc/zh/content/架构设计/架构设计.md)
  - 核心组件库：[`doc/zh/content/核心组件库/核心组件库.md`](doc/zh/content/核心组件库/核心组件库.md)
  - 页面功能模块：[`doc/zh/content/页面功能模块/页面功能模块.md`](doc/zh/content/页面功能模块/页面功能模块.md)
  - hk_base 模块文档：[`plugins/hk_base/README.md`](plugins/hk_base/README.md)
- Repowiki（IDE 内索引，与 `backend/` 同仓说明）：[`.qoder/repowiki/zh/content/架构设计/仓库布局与Python后端.md`](.qoder/repowiki/zh/content/架构设计/仓库布局与Python后端.md)

## AI 治理与协作

### 规则体系（Rules）
- 架构与编码规范：[`.cursor/rules/flutter-stack.mdc`](.cursor/rules/flutter-stack.mdc)
- 自动化测试规范：[`.cursor/rules/automated-tests.mdc`](.cursor/rules/automated-tests.mdc)
- CI/CD 规范：[`.cursor/rules/ci-cd.mdc`](.cursor/rules/ci-cd.mdc)
- 代码审查规范：[`.cursor/rules/code-review.mdc`](.cursor/rules/code-review.mdc)
- Bug 修复与 RAG：[`.cursor/rules/bug-fix-rag.mdc`](.cursor/rules/bug-fix-rag.mdc)
- Agent 行为规范：[`.cursor/rules/agents-guidelines.mdc`](.cursor/rules/agents-guidelines.mdc)
- 代码优化 Rules 入口（仅优化类任务触发）：[`.cursor/rules/flutter-code-optimization.mdc`](.cursor/rules/flutter-code-optimization.mdc)
- 优化类任务关键词触发建议清单：[`doc/zh/content/优化类任务关键词触发建议清单.md`](doc/zh/content/优化类任务关键词触发建议清单.md)
- 优化类任务提示词模板（四个示例）：[`doc/zh/content/优化类任务提示词模板（四个示例）.md`](doc/zh/content/优化类任务提示词模板（四个示例）.md)
- 任务场景提示词模板（五个示例）：[`doc/zh/content/任务场景提示词模板（五个示例）.md`](doc/zh/content/任务场景提示词模板（五个示例）.md)
- 规则使用说明与示例：[`doc/zh/content/AI治理规则使用说明.md`](doc/zh/content/AI治理规则使用说明.md)

### 代码优化 Rules 快速入口
- Rules 文件：[`/.cursor/rules/flutter-code-optimization.mdc`](.cursor/rules/flutter-code-optimization.mdc)
- 触发判定：[`doc/zh/content/优化类任务关键词触发建议清单.md`](doc/zh/content/优化类任务关键词触发建议清单.md)
- 提示词模板（模块专项）：[`doc/zh/content/优化类任务提示词模板（四个示例）.md`](doc/zh/content/优化类任务提示词模板（四个示例）.md)
- 提示词模板（通用场景）：[`doc/zh/content/任务场景提示词模板（五个示例）.md`](doc/zh/content/任务场景提示词模板（五个示例）.md)

### 30 秒模板选择
- 如果是“新增分页页面/修复线上崩溃/新增 CI 门禁/新增登录模块/通用优化任务”，直接用：[`doc/zh/content/任务场景提示词模板（五个示例）.md`](doc/zh/content/任务场景提示词模板（五个示例）.md)
- 如果是“模块专项优化（`hk_base` / `hk_net` / `lib/components` / `lib/base`）”，直接用：[`doc/zh/content/优化类任务提示词模板（四个示例）.md`](doc/zh/content/优化类任务提示词模板（四个示例）.md)
- 如果不确定是否触发优化规则，先看：[`doc/zh/content/优化类任务关键词触发建议清单.md`](doc/zh/content/优化类任务关键词触发建议清单.md)

### 一眼判定流程图（文字版）
1. 先判“任务主目标”：
   - 功能新增 / 缺陷修复 / CI 治理 -> 走“五个示例”对应场景。
   - 优化治理主目标 -> 进入第 2 步。
2. 再判“优化类型”：
   - 通用优化任务 -> 用“五个示例”示例 5。
   - 模块专项优化（`hk_base` / `hk_net` / `lib/components` / `lib/base`）-> 用“四个示例”对应模板。
3. 最后判“是否触发优化规则”：
   - 不确定时先看 `优化类任务关键词触发建议清单`，再填写 Issue/PR 优化触发证据。

### 常见误选纠偏
- 把“修复线上崩溃”误用成“优化类任务” -> 应改用“五个示例”的示例 2；否则会遗漏根因证据链与回归闭环。
- 把“新增登录模块/分页页面”误用成“优化模板” -> 应改用“五个示例”的示例 1/4；否则容易弱化功能验收与测试覆盖。
- 把“模块专项优化（如 `hk_base`）”误用成“通用五个示例” -> 应改用“四个示例”专项模板；否则优化范围与红线不够聚焦。

### 技能模板（Skills）
- Flutter 核心开发：[`SKILLS/flutter-core.skill.md`](SKILLS/flutter-core.skill.md)
- 分页专项开发：[`SKILLS/flutter-pagination.skill.md`](SKILLS/flutter-pagination.skill.md)
- 测试生成：[`SKILLS/test-generator.skill.md`](SKILLS/test-generator.skill.md)
- CI/CD 流程：[`SKILLS/ci-cd-workflow.skill.md`](SKILLS/ci-cd-workflow.skill.md)
- 代码审查：[`SKILLS/code-review.skill.md`](SKILLS/code-review.skill.md)
- 缺陷修复：[`SKILLS/bug-fix-assistant.skill.md`](SKILLS/bug-fix-assistant.skill.md)

### 多 Agent 协作入口
- 协作协议文档：[`AGENTS.md`](AGENTS.md)
- 推荐流程：Meta Architect 规划 -> Flutter Dev 实现 -> Test Agent 验证 -> Code Review 审查 -> Bug Fix 闭环。
- 优化类任务 Issue 模板： [`.github/ISSUE_TEMPLATE/optimization-task.yml`](.github/ISSUE_TEMPLATE/optimization-task.yml)
- Issue 模板配置（禁用空白 Issue）： [`.github/ISSUE_TEMPLATE/config.yml`](.github/ISSUE_TEMPLATE/config.yml)

### 与 CI 的对应关系
- Python 后端（同仓 `backend/`）： [`.github/workflows/backend-ci.yml`](.github/workflows/backend-ci.yml) — 仅 `backend/**` 变更触发；本地对齐：`cd backend && ./tool/testing/run_backend_tests.sh`
- PR/Push 基础验证： [`.github/workflows/verify-testing-toolchain.yml`](.github/workflows/verify-testing-toolchain.yml)
- 门禁策略（`verify-testing-toolchain.yml`）：
  - `Feature docs gate`：PR 为 warn 模式（`check_feature_docs.sh`），main/master 为 strict 模式（`check_feature_docs.sh --strict`）。
  - `Reuse hygiene check`：PR 为 warn 模式（`check_reuse_hygiene.sh`），main/master 为 strict 模式（`check_reuse_hygiene.sh --strict`）。
  - `Optimization trigger check`：PR 为 warn 模式（`check_optimization_trigger.sh`），main/master 为 strict 模式（`check_optimization_trigger.sh --strict`，非 PR 事件自动跳过；优先识别 PR 模板勾选，再关键词兜底）。
  - 规则配置入口：`tool/testing/config/reuse_hygiene_rules.txt`（`group|scope|severity|pattern|message`），豁免入口：`tool/testing/config/reuse_hygiene_ignore.txt`。
- PR 冒烟回归： [`.github/workflows/agentic-smoke-android.yml`](.github/workflows/agentic-smoke-android.yml)
- Nightly 全量回归： [`.github/workflows/agentic-full-android-nightly.yml`](.github/workflows/agentic-full-android-nightly.yml)

### 直接给 AI 的任务模板（登录模块）

```text
新增登录模块（账号密码登录）：
1) 按 Clean Architecture + GetX 实现 login 模块；
2) 目录放在 presentation/domain/data 分层；
3) 禁止 setState，UI 不直连网络；
4) 实现 loading/success/error 状态与输入校验；
5) 生成 unit + widget 测试（成功、空输入、异常、超时）；
6) 更新必要绑定与路由；
7) 执行并通过：
   - bash tool/testing/check_governance_docs.sh --strict
   - bash tool/testing/run_local_verification.sh
8) 输出变更清单、测试结果、风险与回归建议。
```

## 快捷命令

以下示例中的目录请替换为你本机项目根（本仓库常见为 `/Users/hujintao/Desktop/python/ai/flutter_components`）。

### 启动 Test Agent（可选）

```bash
cd "/Users/hujintao/Desktop/python/ai/flutter_components"
bash tool/test_agent/run_webui.sh
```

### 初始化 RAG 知识库（工程化长期记忆）

```bash
cd "/Users/hujintao/Desktop/python/ai/flutter_components"
dart run tool/rag/rag_cli.dart init
dart run tool/rag/rag_cli.dart query 首页 分页 异常 根因
```

### 启动 GUI（Flutter 测试工作台）

```bash
cd "/Users/hujintao/Desktop/python/ai/flutter_components"
bash tool/gui_pyqt5/run_gui.sh
```

启动后若已有 `test-artifacts/**/result.json`，工作台会自动加载最近一份；界面分区与配图说明见 [`tool/gui_pyqt5/README.md`](tool/gui_pyqt5/README.md)。

### 一键：后端 + Flutter（iOS，macOS）

```bash
cd "/Users/hujintao/Desktop/python/ai/flutter_components"
bash tool/dev/run_backend_and_flutter_ios.sh
```

后台启动 `backend`（默认 `http://127.0.0.1:8000`），再 `flutter run` 到本机 **第一个可用 iOS 设备**；若无 iOS 设备则 **boot 并打开 `iPhone 16 Plus` 模拟器**（可用环境变量 `IOS_SIMULATOR_NAME` 改名）。退出 Flutter 后默认结束后台 uvicorn，保留后端请设 `KEEP_BACKEND=1`。详见脚本头部注释。

### 生成交付报告（基于某次 result.json）

```bash
cd "/Users/hujintao/Desktop/python/ai/flutter_components"
dart run tool/testing/generate_delivery_reports.dart test-artifacts/<date>/run_<id>/result.json
```

## 设备准备（Android）

- 启动模拟器：`flutter emulators --launch <emulator_id>`
- 确认在线：`flutter devices`
- `--device-id` 请填 `flutter devices` 里看到的设备序列号（如 `emulator-5554`）

## 说明

- 本 README 保留“小白可用”主路径；深度排障、字段说明、CI 细节请看上面的专项文档。
- 系统边界声明：本仓库主线为 Flutter App 与自动化测试能力；admin 后台属于独立配置端能力，首页联调时请以 `doc/features/home/BOUNDARY.md` 的边界定义为准。
- 应用侧语言与软重启的代码入口与行为说明见上文 **「应用国际化与软重启（App）」**；接口 `locale` 回退规则与同节「请求层 locale」一致。
- **测试模块标注**：与自动化测试/集成测试相关的依赖与入口文件会用“**测试模块需要**”显式标注（如 `pubspec.yaml` 的 `dev_dependencies`、`integration_test/`、`tool/testing/` wrapper、`packages/agentic_integration_support`），避免被误当业务依赖清理或挪入 `lib/`。
- **生成物不入库**：`delivery/` 与 `tool/testing/delivery/` 下的报告/评论/检查结果等默认作为生成物落盘（便于本地查看与 CI artifact），但不会被纳入 git 变更，避免无意义 diff。