# electron_app

**Repository Path**: snow-lee/electron_app

## Basic Information

- **Project Name**: electron_app
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-09
- **Last Updated**: 2026-08-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 时间管理移动端

`app` 是时间管理应用的 Flutter 客户端工程，最终目标是让用户在手机上轻量完成“制定每日计划—记录实际投入—复盘差异—调整后续计划”。当前为方便开发只生成 Web 平台；桌面端位于相邻的 `electron/`，共享 REST 后端位于 `plan/`。

## 当前状态

本目录已完成 **Flutter Web 工程基座、账号闭环、BottomBar、类目管理、今天/明天日计划、单设备计时恢复、手动补录、今日计划/实际复盘、独立复盘摘要、日历热力图与重要日期、个人资料，以及 Electron 对照的统一移动端视觉系统**：

- 已使用 Flutter 3.44.9 stable、Dart 3.12.2 创建应用工程，`.metadata` 当前只登记 `web` 平台。
- 已使用 GoRouter、Riverpod 和 Dio 建立应用装配、主题、认证路由守卫、编译期环境配置、统一 HTTP 客户端、响应壳解析和稳定错误映射。
- `/health` 提供 `/api/health` 状态页，能够展示检查中、连接成功、后端业务失败、超时/无法连接和重试状态；当前本机后端未启动时会显示真实连接失败，而不是 Mock 成功。
- 已接入既有 `/api/auth/login` 与 `/api/auth/register`：支持手机号密码登录、手机号+用户名+密码注册、成功后直接建立会话、启动恢复、主动退出、Bearer Token 自动注入和受保护接口 401 统一清理并返回登录页。
- Token 与用户摘要通过 `flutter_secure_storage` 封装持久化，密码不保存；登录/注册请求明确跳过全局 401 会话失效处理，因此错误密码仍展示后端业务提示。
- 已使用 `StatefulShellRoute.indexedStack` 建立“今日、计划、复盘、我的”四入口 BottomBar；各入口保留独立导航栈，BottomBar 只出现在已登录业务区域。
- “我的 → 类目管理”已接入真实 `/api/categories`，支持加载、空状态、错误重试、下拉刷新、创建、编辑、累计时长展示和两种删除模式；删除前会明确提示关联日计划项清理及历史记录影响，存在尚未处理的关联计时时禁止删除。
- “我的 → 个人资料”已接入真实 `PUT /api/profile/display-name` 与 `PUT /api/profile/avatar`：支持修改最多 80 字符的展示名称、从系统选择 JPEG/PNG/WebP、在客户端居中裁剪并缩放为 256×256 JPEG、上传或替换头像，以及把服务端确认的最新资料与原 Token/过期时间一起写回安全会话。原图不上传；当前后端不支持移除头像，因此 App 不提供伪删除入口。
- “计划”已接入真实 `/api/plans` 与 `/api/plans/lock-state`：支持今天/明天切换、服务器自然日、锁定状态、计划摘要、完成进度、显式解锁、添加/移除类目、1～1440 分钟目标编辑、保存并重新锁定及取消草稿。
- 编辑计划时禁止切换日期；离开计划 BottomBar 分支会先确认是否放弃草稿，并在成功调用后端重新锁定后才离开，避免静默丢弃本地修改或长期遗留解锁状态。
- “今日”已提供真实类目快速开始、当前计时摘要、手动补录、今日计划/实际差异和按发生时间排列的实际记录列表；快速计时类目按今日计划/实际并集优先排列。今日总实际包含全部实际记录，计划完成率只使用已进入今日计划类目的实际投入，计划外投入单独标记且不虚增完成率。
- 计时详情支持暂停、继续、结束保存、取消和失败重试，四个主入口上方通过全局迷你计时条持续展示。活动状态按用户 ID 使用 `shared_preferences` 保存版本化本地 JSON，展示时长由整秒 UTC 运行区间重算，刷新、重新打开或生命周期恢复后不依赖周期定时器补算。
- 结束时复用既有 `POST /api/time-records/timer-sessions`：每个暂停前后的真实运行区间使用稳定且不同的幂等键逐段提交，暂停时长不写入实际记录；部分成功后只重试未保存区间。主动退出要求先返回处理或明确取消计时，401 导致的会话失效则保留该用户本地状态供同一账号重新登录恢复。
- 手动补录复用既有 `POST /api/time-records/manual`，支持类目、开始/结束日期时间、提交摘要、未来时间/七天上限/本地活动计时重叠预检、稳定幂等键失败重试和成功后跨功能刷新。补录不进入离线持久化队列，网络失败时保留当前页面输入供用户重试。
- 独立“复盘”主入口已复用 `GET /api/statistics`，展示今日、本周、本月、本年实际投入摘要和最近七天轻量趋势，支持加载、错误重试、下拉刷新、全零说明和数值读屏语义；页面明确标注服务端 Asia/Shanghai 自然日与周一起算口径。该复盘摘要已由用户完成真实后端联调。
- “复盘 → 日历与重要日期”已复用 `GET /api/calendar` 与 `/api/calendar/markers`：支持可用年份切换、12 个月逐日投入热力图、最长连续投入、今日/星标提示、点击日期查看投入与标记、今天及未来标记的服务端分页，以及重要日期增改删。年度多类目趋势等高级筛选仍未实现；本次日历客户端切片尚待真实后端联调。
- 已按 Electron 的固定浅色工作台风格重建全局视觉系统：使用冷灰画布、白色表面、近黑主操作、灰色正文、细边框、克制阴影与统一圆角，覆盖认证、会话恢复、BottomBar、今日、计划、计时、补录、复盘、日历、类目、我的、健康检查和通用弹层/反馈。类目与热力图继续使用数据颜色，错误和健康状态保留语义色。
- 页面统一使用“眉题—标题—说明”的移动端信息层级，主操作保持至少 48px 触控高度；没有机械复制 Electron 的 8～10px 桌面小字或 216px 侧栏，而是保留移动端可读字号、安全区、纵向滚动和底部导航交互。
- 当前没有 `android/`、`ios/` 或其他原生平台目录，也未验证移动端构建、权限、生命周期和真机行为。
- 已完成桌面端现有功能、后端真实接口和移动端取舍的文档盘点。
- 已形成移动端页面规划与分阶段实施方案；应用 ID、Android 优先、P0 范围、单设备计时、通知与有限离线边界已经记录在阶段文档，签名和最终移动适配仍待后续完成。

未实现能力必须继续标注为规划、Mock 或待决策，不能因桌面端已有相同页面就描述为移动端已完成。

## 当前平台策略

- 业务开发阶段只维护 Flutter Web，使用浏览器快速完成页面、状态、接口与核心领域测试。
- Android/iOS 平台目录、签名、权限和原生配置等到核心业务开发完成后再按用户指示创建和适配；当前任务不得自行补生成移动平台。
- 业务代码应保持平台无关。安全存储、后台计时、系统通知、相册/相机、文件分享和深链等能力通过明确接口隔离；Web 阶段可以使用受控替代实现或显示“待移动端适配”，不能伪装成真机已支持。
- Web 通过不代表移动端完成。进入发布前必须在 Android 优先的目标平台补做生命周期、权限、性能和真机测试，并允许为平台限制调整实现。

## 视觉与交互基线

- 当前只提供固定浅色主题，设计事实位于 `lib/app/theme/app_theme.dart`：画布 `#F7F7F8`、表面 `#FFFFFF`、主文字/主操作 `#111111`/`#050505`、正文 `#4B5563`、弱文字 `#6F7885`、分隔线 `#E4E5E7`、危险色 `#E12831`。
- 卡片使用 18px 圆角和 1px 细边框，输入与主要按钮使用 12px 圆角；常规页面弱化阴影，仅认证卡片、BottomBar 和弹层使用轻微层级阴影。
- 黑色用于主操作和活动计时，灰阶用于框架与选中反馈。类目色、热力图强度、健康和危险色只承载对应业务语义，不能扩散为页面主题色，也不能成为唯一状态提示。
- BottomBar 保持“今日、计划、复盘、我的”四入口，选中项使用浅灰胶囊与黑色图标；全局计时条使用黑底白字，与主要业务操作形成一致的强焦点。
- 新页面优先复用 `PlanPageIntro`、`PlanSectionHeader`、`PlanInfoPanel` 和主题组件配置。移动端正文通常不低于 12px，主要触控目标不低于 44px，主要按钮高度不低于 48px。

## 产品定位与首版范围

移动端不逐页复制桌面端，首版优先缩短手机上的高频路径：

1. 登录或注册并安全恢复会话。
2. 查看今天的计划与实际摘要，快速选择类目开始计时。
3. 在前后台切换后恢复计时展示，结束并保存实际记录；也可手动补录。
4. 查看和调整今天或明天的日计划。
5. 查看今日计划/实际差异，以及日、周、月实际投入摘要。

类目管理是以上闭环的必要支撑。个人资料、日历/重要日期已进入首轮完整业务；联系人、通知和提醒继续补齐。年度高级图表、导出、历史删除、二维码/小组件等可按优先级后置。

## 页面划分

建议采用四个底部主入口，避免把桌面侧栏机械缩小到手机上：

| 主入口 | 主要内容 |
| --- | --- |
| 今日 | 今日计划/实际摘要、快速计时、补录、按类目时间线、通知入口 |
| 计划 | 今天/明天切换、锁定/解锁、计划项编辑与保存 |
| 复盘 | 日/周/月摘要、年度趋势高级筛选、日历热力图、重要日期 |
| 我的 | 资料、类目、联系人、提醒、语言、数据与隐私、关于 |

登录/注册、计时详情、补录表单和通知中心使用独立路由。计时开始后通过全局迷你计时条跨主入口持续展示，不复制 Electron 的悬浮窗和托盘方案。

完整功能移植矩阵、移动端新增能力和路由树见 [`AIOptions/mobile-product-scope.md`](AIOptions/mobile-product-scope.md)。

## 推荐开发路线

“环境 → 空项目 → 基础框架 → 后端接入 → 核心闭环 → 完整业务 → 测试优化 → 打包发布”方向可行，但调整为以下九个可验收阶段：

1. **范围、平台与契约决策**：已记录 Android 优先、应用 ID、MVP、计时/通知/离线边界；签名和最终平台参数后补。
2. **开发环境与空项目**：Web 创建、浏览器运行、分析、测试和构建已验证。
3. **工程基座与质量基线**：应用装配、主题、路由、配置、网络、安全存储抽象、认证守卫和持续测试已完成。
4. **最小后端联调与账号闭环**：已完成；用户已使用真实 Java/MySQL 后端验证正确密码、错误密码、重复手机号和真实 Token 恢复。
5. **核心时间管理闭环**：进行中；BottomBar、类目管理、今天/明天日计划、单设备计时恢复、手动补录和今日计划/实际复盘客户端实现已完成，下一门槛是一次完整真实后端联调。
6. **配套完整业务**：进行中；基础复盘摘要、最近七天趋势、日历热力图/重要日期和个人资料客户端切片已完成，联系人、通知和设置继续按移动端价值补齐。
7. **移动端增强与后端缺口**：按已确认范围处理记录维护、时区、Push、多端计时或离线同步。
8. **发布级测试与优化**：汇总自动化、真机、性能、无障碍和安全验收；测试从工程基座起持续进行。
9. **打包、灰度与发布**：签名、隐私材料、测试渠道、发布产物和回滚方案。

逐阶段任务、退出条件和当前进展见 [`AIOptions/stage.md`](AIOptions/stage.md)。

## 当前技术基线与方案候选

SDK、平台和当前基础依赖来自真实工程；未安装项仍是后续候选：

| 关注点 | 推荐候选 | 使用原则 |
| --- | --- | --- |
| SDK | Flutter 3.44.9 stable、Dart 3.12.2 | 当前工程实际基线，升级前单独验证 |
| 当前平台 | Web | 仅代表开发和浏览器验证平台，不代表移动端已支持 |
| 路由 | `go_router` 17.4.0 | 已用于认证守卫、公开健康检查、四分支 StatefulShellRoute 与类目子路由 |
| 状态 | `flutter_riverpod` 3.4.2 | 已用于依赖装配和健康检查异步状态 |
| HTTP | Dio 5.11.0 | 已统一 Base URL、超时、响应解析、错误映射、Bearer Token 与 401 处理 |
| 安全存储 | `flutter_secure_storage` 11.0.0 | 已保存 Token 和用户摘要，密码不持久化；移动平台后续真机复验 |
| 普通本地状态 | `shared_preferences` 2.5.5 | 已按用户保存版本化活动计时状态，不存 Token、密码或完整后端明细；移动平台后续真机复验 |
| 头像选择 | `image_picker` 1.2.3 | 当前 Web 从系统文件选择器读取图片；Android/iOS 相册权限、丢失数据恢复与真机行为后续复验 |
| 图片处理 | `image` 4.9.1 | 在客户端居中裁剪、缩放并编码 256×256 JPEG，不上传原始本地文件 |
| 测试 | `flutter_test`、`integration_test` | 单元、Widget 和关键流程分层覆盖 |

序列化代码生成、本地数据库、图表和 Push 等依赖只在真实功能进入实施时选择，避免空项目阶段堆叠包。

## 当前工程结构与演进方向

当前已经存在 Flutter Web 最小工程，后续按真实纵向功能逐步扩展：

```text
app/
├─ lib/
│  ├─ app/             # 应用启动、主题、路由和依赖装配
│  ├─ core/            # 当前已有配置、网络、响应解析和错误边界
│  ├─ features/        # 当前已有 auth、categories、plans、timer、manual_record、today、review 等真实切片
│  └─ main.dart
├─ test/               # 单元与 Widget 测试
├─ integration_test/   # 关键用户流程，出现真实流程后建立
├─ web/                # 当前唯一的平台启动资源
├─ AIOptions/          # 产品范围、阶段计划、验证与遗留边界
├─ pubspec.yaml
├─ README.md
└─ AGENTS.md
```

这不是预创建清单。没有调用方的目录、DTO、Repository、Service 或通用组件不应批量生成。

### 给 Flutter 初学者的调用链地图

阅读代码时先从下面几条主链进入；箭头右侧通常是更靠近数据或平台边界的一层：

- 应用启动：`main` → `ProviderScope` → `PlanApp.build` → `appRouterProvider` → `GoRouter` → 各页面 Widget。
- 登录/注册：`LoginPage` / `RegisterPage` → `SessionController.login` / `register` → `AuthRepository` → `AuthApi` → `Dio` → `plan` 后端。
- 会话恢复：`SessionController.build` → `SessionStore` → `SecureSessionStore`；恢复结果驱动 `appRouterProvider` 的认证重定向。
- 受保护请求的 401：`_SessionInterceptor.onError` → `AuthSessionAccess.handleUnauthorized` → `SessionController.handleUnauthorized` → 清理安全存储 → 路由返回登录页。
- 一般业务页面：`XxxPage` → `XxxController` → `XxxRepository` → `XxxApi` → `Dio` → `plan` 后端；响应再按相反方向变成领域对象和页面状态。
- 计时：`TimerPage` / `TimerMiniBar` → `TimerController` → `TimerSessionStore`（本机恢复）与 `TimerRepository` / `TimerApi`（保存实际记录）→ 刷新今日复盘相关 Provider。
- 个人资料：`ProfilePage` → `ProfileController` → `ProfileRepository` / `ProfileApi`；成功后再调用 `SessionController.updateProfile`，把后端确认的资料写回当前安全会话。

源码采用中文 DartDoc：类级注释说明职责、上游调用方和下游依赖，关键方法注释说明状态变化、校验和失败边界。标准框架覆写与简单 getter 不重复写无信息量注释；详细门槛见 [`AGENTS.md`](AGENTS.md) 的“Dart 与 Flutter 代码要求”。

## 当前开发命令

当前只面向 Web 开发，常用命令为：

```powershell
flutter doctor -v
flutter pub get
flutter run -d chrome --dart-define=API_BASE_URL=http://localhost:8080/api
flutter analyze
flutter test
flutter build web --dart-define=API_BASE_URL=http://localhost:8080/api
```

未传 `API_BASE_URL` 时默认使用 `http://localhost:8080/api`。该值必须是有效的 HTTP(S) 地址，末尾斜杠会被统一移除；生产构建必须显式注入经过验证的 HTTPS 地址。

2026-08-10 已验证：`flutter analyze` 无问题；当前完整测试共 92 项通过，覆盖配置、视觉令牌与移动触控尺寸、账号/会话资料写回、BottomBar 与个人资料子路由、资料 API、头像裁剪编码、资料页面、类目 CRUD、日计划、计时恢复、补录与今日复盘、独立复盘摘要，以及日历接口、完整年度/舍入边界、未来分页和重要日期增改删。Web 发布构建已通过；本地生产构建在 390×844 与 1280×800 浏览器视口完成登录页、健康诊断页视觉检查，未发现溢出或控制台错误。账号闭环和独立复盘摘要已由用户使用真实 Java/MySQL 后端完成手工验证；个人资料展示名称/头像真实上传、类目/日计划/计时/补录/今日复盘集中闭环、日历真实操作，以及已登录业务页窄屏/动态字体仍待手工联调。Android 工具链、相册权限、图片选择丢失数据恢复、后台行为、本地存储与生命周期真机表现留待移动适配阶段处理。

`flutter_secure_storage` 的 Web 实现依赖 Web Crypto，当前可在 `localhost` 开发环境使用；正式 Web 部署必须使用 HTTPS，并配置 HSTS 等安全响应头。Web 构建通过只证明插件可编译，不能替代 Android Keystore/iOS Keychain 真机验证。

## 跨端与数据约定

- 移动端通过 Java 后端 API 共享业务数据，不直接依赖 Electron 的 IPC、Main、Preload、窗口或托盘实现。
- API 响应壳、错误码、鉴权头、分页、幂等和时间字段必须与既有调用端保持兼容。
- 计划和实际记录是独立实体；计划只绑定单个自然日，周/月只汇总实际记录。
- 时间点使用带偏移量的 ISO 8601 值，时长使用含单位的整数；当前后端自然日固定为 Asia/Shanghai，这在跨时区发布前需要专项解决。
- 当前活动计时只在本设备、本账号下恢复，不上云，也不与 Electron 同步；两端同时计时可能在保存时触发后端重叠校验。暂停期间拆为区间间隙，不伪造为实际学习时间。
- 手动补录只在线提交，不加入计时离线队列；相同页面输入失败重试沿用同一幂等键，修改类目或时间后生成新键。客户端预检不能替代后端对类目归属、区间和既有记录重叠的最终校验。
- 复盘日/周/月/年数据是服务端实际记录汇总；历史日期的 `0` 表示已发生但无投入，未来日期的空值表示尚未发生，客户端不得混用。周、月摘要不派生周计划或月计划。
- 日历热力图包含所选年份每个自然日及该年的全部重要日期标记；“今天及未来的重要日期”是独立的服务端分页视图。过去标记继续显示在对应年份热力图，但不混入未来事项列表；同一天允许存在多条标记。
- Token 和用户摘要使用安全存储封装，密码不持久化；日志不记录凭据、验证码、完整时间明细或消息正文。当前 Web 存储仍受浏览器与部署安全策略约束，正式环境必须使用 HTTPS。
- 个人资料接口返回完整用户摘要；App 只有在资料用户 ID 与当前会话一致时才保留原 Token/过期时间并写回安全存储。头像源文件限制为 10MB，客户端只上传居中裁剪后的 256×256 JPEG Data URL；当前没有头像删除接口。
- Mock、未同步和已同步数据必须可区分。离线编辑、多端计时和冲突策略未确认前不得采用隐藏的“最后写入获胜”。

## 跨项目保护边界

- 移动端任务默认只修改 `app/`。可只读检查 `electron/` 和 `plan/` 以核对真实行为。
- 如需修改 `electron/` 的代码、配置或测试，必须先说明原因、影响和替代方案，并得到用户明确确认。
- App 可复用现有 `plan/` 接口；确需新增后端能力时优先采用兼容性新增，并检查 Electron 的真实调用方。
- 任何可能改变 Electron 使用的端点、字段、错误码、时间口径、权限、数据库约束或既有数据的 `plan/`/Flyway 改动，必须在实施前取得用户确认。

详细执行门禁见 [`AGENTS.md`](AGENTS.md)。

## 文档导航与维护

- 本文件：当前状态、入口、真实命令、技术栈和文档导航。
- [`AGENTS.md`](AGENTS.md)：长期协作规则、跨项目修改门禁和最低验收。
- [`AIOptions/mobile-product-scope.md`](AIOptions/mobile-product-scope.md)：功能移植、新增能力、页面划分和后端依赖。
- [`AIOptions/stage.md`](AIOptions/stage.md)：阶段任务、退出条件、实际验证和遗留项。

实现状态或命令变化时更新本文件；产品范围变化时更新 `mobile-product-scope.md`；阶段推进和验证结果更新 `stage.md`；长期协作约束变化时才更新 `AGENTS.md`。

## 进入移动平台适配前待确认

- Android 首发的最低系统版本，以及 iOS 补齐时点。
- 已选应用 ID/组织标识对应的多环境包名规则、签名主体和发布渠道。
- 已实现的 `shared_preferences` 单设备计时恢复方案在 Android/iOS 上的进程回收、后台限制、存储可靠性和真机迁移验证。
- 系统公告和好友短信息采用应用内、本地调度还是服务端 Push 投递。
- 当前“以服务器时间为准”的展示细节，以及未来若扩展用户时区时的迁移边界。