# 📚 闲言APP — 项目总览

> 更新: 2026-04-27 | 版本: v0.23.0 | 当前阶段: Phase 1 ✅ 核心完成 + Phase 2/5 ✅ 已归档

---

## 一、项目概述

| 项目 | 说明 |
|------|------|
| 名称 | 闲言（WordsLeisure） |
| Slogan | 文字阅读更纯粹 |
| 类型 | 句子阅读 + 壁纸制作 APP |
| 原技术栈 | Lua + AndroLua/AppLua 框架（65 文件 15000+ 行） |
| 目标技术栈 | Flutter 3.24+ / Dart 3.9+ / Riverpod / Drift / go_router |
| 设计规范 | iOS 26 Liquid Glass |
| 后端 | Supabase（迁移自 T1 后端云） |

### 纲领约束

- 暂不开发注册登录功能（优先级最低）
- 暂不开消息通知功能（后续可能使用邮箱实现）
- 所有页面必须使用统一设计系统变量
- 修改布局必须整体重构，禁止只改局部组件

---

## 二、原项目摘要（Lua 版）

| 项目 | 内容 |
|------|------|
| 应用名 | 字你太美应用程序 / 闲言APP |
| 技术栈 | Lua + AndroLua/AppLua（65 文件 ~15000 行） |
| 核心文件 | soup.lua ≈5500 行（主页面，承载 80% 功能） |
| 后端 | T1 后端云（aixinbiji.com） |

**关键问题与 Flutter 解决方案**：

| 问题 | 方案 |
|------|------|
| soup.lua 单文件 5500 行 | 拆分为独立页面 + Provider |
| 爬虫依赖（搜索/句子源） | 自建 RESTful API |
| 无类型安全 | Dart 强类型 + freezed |
| 本地文件存储 | Drift 数据库 |
| 无状态管理 | Riverpod |

**Lua → Flutter 映射**：soup.lua→home+editor页 / str.lua→utils+theme / t1.lua→core/network / favorite.lua→inspiration页

---

## 三、关键决策 (ADR)

| 决策 | 选择 | 理由 |
|------|------|------|
| 状态管理 | Riverpod 2.5+ | 编译时安全 + 依赖注入 |
| 路由 | go_router 14.0+ | 声明式路由 + 深链接 |
| 数据库 | Drift (SQLite) | 类型安全 SQL + 响应式查询 |
| 网络层 | Dio 5.4+ | 拦截器 + 请求取消 |
| UI 风格 | iOS 26 Liquid Glass | Cupertino 优先 + 液态玻璃效果 |
| 底部面板 | StupidSimpleGlassSheet | 弹簧动画 + 拖拽关闭 |
| Hero 动画 | Heroine | 弹簧物理效果替代 Hero |

---

## 四、架构分层

```
lib/
├── main.dart              # 入口
├── app/
│   ├── app.dart           # MaterialApp.router + GlassTheme + Riverpod
│   └── app_theme.dart     # AppThemeExtension + 日夜双主题
├── core/
│   ├── router/            # go_router + ShellRoute
│   ├── layout/            # AppShell + GlassBottomBar
│   ├── theme/             # 6 套设计令牌
│   ├── network/           # Dio + Interceptor + ApiException
│   ├── storage/           # KvStorage + SecureStorage + Database(4表)
│   └── utils/             # 动画/日志/扩展
├── features/
│   ├── home/              # 首页
│   ├── inspiration/       # 灵感/收藏
│   ├── editor/            # 编辑器 (核心模块)
│   ├── profile/           # 个人中心
│   ├── search/            # 搜索
│   ├── source/            # 来源
│   ├── member/            # 会员
│   └── settings/          # 设置/主题
└── shared/
    └── widgets/           # GlassContainer/Skeleton/EmptyState/BottomSheet
```

---

## 五、开发阶段总览

| Phase | 内容 | 状态 | 优先级 |
|-------|------|------|--------|
| Phase 0 | 项目基础设施搭建 | ✅ 100% | P0 |
| Phase 1 | 编辑器完善 + 首页句子流 | ✅ 核心完成 | P0 |
| Phase 2 | 内容发现 + 搜索 + 灵感 | 🔲 未开始 | P0 |
| Phase 3 | 壁纸 + 会员 + 通知 | 🔲 未开始 | P1 |
| Phase 4 | 设置 + 小组件 + 辅助功能 | 🔲 未开始 | P1 |
| Phase 5 | 优化 + 测试 + 上线 | 🔲 未开始 | P0 |

> **编辑器子Phase**: 图层管理 ✅ | 3D引擎 ✅核心归档 | 图片处理 ✅核心归档 | 3D修复 ✅ (v0.23.0)

---

## 六、Phase 0 完成情况 ✅

| # | 任务 | 状态 |
|---|------|------|
| 0.1 | 项目目录树 (core/features/shared) | ✅ |
| 0.2 | pubspec.yaml + 版本冲突解决 | ✅ |
| 0.3 | 设计系统令牌 (颜色/间距/圆角/阴影/字体/Glass) | ✅ |
| 0.4 | 主题系统 (AppThemeExtension + 日夜双主题) | ✅ |
| 0.5 | 网络层 (Dio + Interceptor + ApiException) | ✅ |
| 0.6 | 路由配置 (go_router + ShellRoute) | ✅ |
| 0.7 | 本地存储 (KV + SecureStorage + Drift 4表) | ✅ |
| 0.8 | 共享组件 (GlassContainer/Skeleton/EmptyState/BottomSheet) | ✅ |
| 0.9 | 主入口 + App | ✅ |
| 0.10 | 动画库集成 (lottie/confetti/animate_do/custom_refresh) | ✅ |
| 0.11 | Lint 全量修复 | ✅ |
| 0.12 | 三端权限配置 (Android/HarmonyOS/iOS) | ✅ |

---

## 七、Phase 1 进行中 🔄

### 7.1 已完成

| # | 任务 | 状态 |
|---|------|------|
| 1.1 | 编辑器数据模型 (freezed) | ✅ |
| 1.2 | 编辑器 Provider (Riverpod StateNotifier) | ✅ |
| 1.3 | 编辑器主页面 (5Tab工具栏) | ✅ |
| 1.4 | 文字/背景/效果/水印/图层面板 | ✅ |
| 1.5 | 模板选择弹窗 (6个预设) | ✅ |
| 1.6 | 首页句子流 + Hitokoto API | ✅ |
| 1.7 | 灵感/搜索/来源/会员页 | ✅ |
| 1.8 | 液态玻璃全面迁移 | ✅ |
| 1.9 | 导出功能 (保存相册/分享/.xycard) | ✅ |
| 1.10 | 主题个性化设置页 | ✅ |
| 1.11 | 迷你编辑器 (极简6项 + 3种部署模式) | ✅ |
| 1.12 | flex_color_picker 鸿蒙适配 (本地化) | ✅ |
| 1.13 | 全局黄色双下划线修复 (OHOS平台) | ✅ |
| 1.14 | **画布比例切换** (9:16/3:4/1:1/4:3/16:9) | ✅ |
| 1.15 | **网格参考线** (三等分法 + 点阵网格) | ✅ |
| 1.16 | **图层锁定** (locked字段 + 锁定UI + 拖拽拦截) | ✅ |
| 1.17 | **ProEditor重构** (pro_image_editor + FrostedGlass主题) | ✅ |
| 1.18 | **液态玻璃贴纸** (liquid_glass_widgets/easy 4种预设) | ✅ |
| 1.19 | **SVG贴纸** (flutter_svg 8种本地SVG) | ✅ |
| 1.20 | **Lottie动画贴纸** (6种本地动画) | ✅ |
| 1.21 | **Google Fonts** (15种字体 中6+英9) | ✅ |
| 1.22 | **自适应主题色** (adaptive_palette 流体背景) | ✅ |
| 1.23 | **水印系统** (平铺/单点 4种预设) | ✅ |
| 1.24 | **一言API集成** (HitokotoService 12种类型) | ✅ |
| 1.25 | **.xycard导出** (archive压缩/解压) | ✅ |
| 1.26 | **自定义颜色选择器** (XianyanColorPicker + flex_color_picker) | ✅ |
| 1.27 | **网络贴纸** (6类36张 cached_network_image) | ✅ |
| 1.28 | **权限管理** (PermissionService 相机/相册/存储) | ✅ |
| 1.29 | **编辑器动画** (flutter_animate入场 + confetti庆祝) | ✅ |
| 1.30 | **主题切换** (EditorThemeService system/light/dark) | ✅ |
| 1.31 | **数据接收** (EditorDataReceiver) | ✅ |

### 7.2 进行中 / 待完成

| # | 任务 | 状态 | 优先级 |
|---|------|------|--------|
| 1.32 | 智能对齐吸附 (SnapHelper + 辅助线) | ✅ v0.16.0 | P1 |
| 1.33 | 取色器 (EyeDropper + 像素读取) | ✅ v0.16.0 | P1 |
| 1.34 | 渐变自定义 (多节点 + 角度编辑器) | ✅ v0.16.0 | P1 |
| 1.35 | 玻璃卡片 WidgetLayer 导出渲染 (RepaintBoundary) | ✅ v0.16.0 | P1 |
| 1.36 | image 库集成 (高级导出处理) | ✅ v0.22.0 | P2 |
| 1.37 | flutter_shaders_ui 集成 (Shader 效果贴纸) | ✅ v0.20.0 | P2 |
| 1.38 | 首页句子卡片流完善 | 🔲 | P0 |
| 1.39 | 收藏/历史 Drift 持久化 | ✅ v0.15.0 | P0 |
| 1.40 | services 目录文件重组 (13 > 8) | ✅ v0.14.3 | P2 |

---

## 八、Phase 2-5 规划概要

### Phase 2 — 内容发现 + 搜索 + 灵感
- 自建句子 API (Supabase Edge Functions)
- 搜索 API (MeiliSearch)
- 灵感收藏本地持久化
- 多句子源切换 + 离线句库

### Phase 3 — 壁纸 + 会员 + 通知
- 必应壁纸模块
- 会员系统 (Supabase Auth)
- 通知推送 (邮箱方案)

### Phase 4 — 设置 + 小组件 + 辅助
- 设置页完善
- 桌面小组件 (home_widget)
- 数据备份恢复

### Phase 5 — 优化 + 测试 + 上线
- 性能优化 / 全量测试 / 商店上架

---

## 九、可扩展功能

| 优先级 | 功能 | 提及次数 |
|--------|------|---------|
| 5 | 壁纸编辑器增强 | 8次 |
| 5 | 句子浏览/卡片流 | 7次 |
| 4 | 收藏管理 / 搜索 / 主题 / 分享 | 4-5次 |
| 3 | 会员系统 / 小组件 / 通知推送 | 3次 |
| 2 | AI推荐 / 登录注册 | 2次 |

---

## 十、数据库表 (Drift/SQLite)

| 表名 | 用途 | 状态 |
|------|------|------|
| sentences | 句子缓存 | ✅ |
| favorites | 收藏记录 | ✅ |
| reading_history | 阅读历史 | ✅ |
| card_templates | 卡片模板 | ✅ |
| user_quotes | 个人语录 | 🔲 |
| search_history | 搜索历史 | 🔲 |

---

## 十一、版本历史 (CHANGELOG 详细记录)

| 版本 | 日期 | 关键变更 |
|------|------|---------|
| v0.23.0 | 04-27 | 3D修复统一flutter_3d_controller + 图层模型统一 + pro_editor_bridge拆分 + 3D模型扩展 |
| v0.22.0 | 04-25 | 图片压缩+大图预览+裁剪编辑器+图片信息+内存优化 |
| v0.21.0 | 04-24 | 3D模型贴纸+3D预览页+平台3D调度 |
| v0.20.0 | 04-24 | 图层管理面板+撤销/重做增强+Shader效果 |
| v0.16.0 | 04-24 | WidgetLayer导出+智能对齐+取色器+渐变编辑+操作历史 |
| v0.15.0 | 04-24 | 首页句子卡片流+收藏/历史持久化 |
| v0.14.1 | 04-24 | 修复编译错误 + Lottie/SVG本地资源下载 + 文档更新 |
| v0.14.0 | 04-23 | ProEditor主编辑器重构 + FrostedGlass主题 + 跨平台适配 |

> 完整变更记录见 [CHANGELOG.md](../CHANGELOG.md)

---

## 十二、归档列表

> 已完成/已归档的Phase和子功能，便于交接和追溯

| 归档项 | 版本 | 完成日期 | 核心产出 | 状态 |
|--------|------|---------|---------|------|
| Phase 0 — 基础设施搭建 | v0.1.0 | 2026-04 | 项目结构+设计系统+网络+存储+路由 | ✅ 100% |
| Phase 1 — 编辑器核心+首页 | v0.9~v0.16 | 2026-04 | ProEditor+贴纸系统+导出+句子流+收藏 | ✅ 核心 |
| 编辑器子Phase: 图层管理 | v0.20.0 | 2026-04-24 | LayerPanel+UndoRedo+图层CRUD+快照 | ✅ 92% |
| 编辑器子Phase: 3D引擎 | v0.21.0 | 2026-04-24 | flutter_3d_controller集成+3D贴纸+预览页 | ✅ 核心71% |
| 编辑器子Phase: 图片处理增强 | v0.22.0 | 2026-04-25 | 压缩+预览+裁剪+信息读取+内存优化 | ✅ 95% |
| 编辑器子Phase: 3D修复+架构优化 | v0.23.0 | 2026-04-27 | 统一3D渲染+图层模型统一+bridge拆分+模型扩展 | ✅ 完成 |
| flutter_advanced_canvas_editor 适配 | v0.20.0 | 2026-04-24 | LayerManagerService+LayerSnapshotService | ✅ 已归档 |
| flutter_scene 移除 | v0.23.0 | 2026-04-27 | 移除useScene分支，统一flutter_3d_controller | ✅ 已归档 |
| flutter_3d_controller 集成 | v0.21.0 | 2026-04-24 | Model3DPreviewPage+Sticker3DPanel | ✅ 已归档 |
| image_size_getter 集成 | v0.22.0 | 2026-04-25 | ImageInfoService+ImageInfoPanel | ✅ 已归档 |
| extended_image 集成 | v0.22.0 | 2026-04-25 | ImageCropPage+ExtendedResizeImage | ✅ 已归档 |
| photo_view 集成 | v0.22.0 | 2026-04-25 | ImagePreviewPage+ImageGalleryPage | ✅ 已归档 |
| flutter_image_compress 集成 | v0.22.0 | 2026-04-25 | ImageCompressService | ✅ 已归档 |