feat: make core pages local-first offline
This commit is contained in:
+3
-1
@@ -1,6 +1,8 @@
|
||||
# 喵记账 · AI 记账 APP 设计文档
|
||||
|
||||
> 状态：UI/UX 设计阶段 · 更新于 2026-07-18
|
||||
> 状态：设计规范已落地，持续跟随实现迭代 · 更新于 2026-08-21
|
||||
|
||||
实现进度、已完成模块和当前风险见 [`STATUS.md`](STATUS.md)。本文保留产品决策、视觉规范和后台边界。
|
||||
|
||||
## 1. 产品概述
|
||||
|
||||
|
||||
+12
-13
@@ -8,11 +8,11 @@
|
||||
|
||||
### 后端版本号
|
||||
- 文件：`backend/MiaoJiZhang.Api/Program.cs`
|
||||
- 变量：`apiVersion = "20260718-1600"`（修改此行即可）
|
||||
- 配置：`Build:Version`（未注入时默认为 `dev`）
|
||||
- 显示位置：
|
||||
- `GET /api/ping` 返回 JSON `{ "version": "...", "built": "..." }`
|
||||
- `GET /api/version` 同上
|
||||
- 更新方法：修改 `apiVersion` 字符串，重启后端
|
||||
- 更新方法：通过环境变量或部署配置注入 `Build__Version`，重启后端
|
||||
|
||||
### Flutter App 版本号
|
||||
- 文件：`frontend/lib/shared/version.dart`
|
||||
@@ -22,9 +22,9 @@
|
||||
- 登录页底部
|
||||
- 「我的」页底部
|
||||
- 构建命令：
|
||||
```bash
|
||||
```powershell
|
||||
flutter clean
|
||||
flutter build apk --release --dart-define=APP_VERSION=20260718-1600
|
||||
flutter build apk --release --dart-define=APP_VERSION=20260821-135
|
||||
```
|
||||
⚠️ **必须加 `--dart-define`，否则 App 显示 `vdev`**
|
||||
|
||||
@@ -33,8 +33,7 @@
|
||||
- 更新方法：重新构建并完整替换后端静态资源目录。
|
||||
```bash
|
||||
cd admin-web && npm run build
|
||||
find ../backend/MiaoJiZhang.Api/wwwroot -mindepth 1 -delete
|
||||
cp -a dist/. ../backend/MiaoJiZhang.Api/wwwroot/
|
||||
Copy-Item -Recurse -Force dist\* ..\backend\MiaoJiZhang.Api\wwwroot\
|
||||
```
|
||||
|
||||
---
|
||||
@@ -58,11 +57,10 @@ dotnet run --project MiaoJiZhang.Api
|
||||
临时设置 `Admin__CookieSecure=false`。
|
||||
|
||||
### 2. Admin Web
|
||||
```bash
|
||||
```powershell
|
||||
cd admin-web
|
||||
npm run build
|
||||
find ../backend/MiaoJiZhang.Api/wwwroot -mindepth 1 -delete
|
||||
cp -a dist/. ../backend/MiaoJiZhang.Api/wwwroot/
|
||||
Copy-Item -Recurse -Force dist\* ..\backend\MiaoJiZhang.Api\wwwroot\
|
||||
```
|
||||
浏览器打开 `http://localhost:5000/` 或 `http://{电脑IP}:5000/`。如界面未更新请 **Ctrl+Shift+R** 强制刷新。
|
||||
|
||||
@@ -71,7 +69,7 @@ cp -a dist/. ../backend/MiaoJiZhang.Api/wwwroot/
|
||||
cd frontend
|
||||
flutter clean
|
||||
flutter pub get
|
||||
flutter build apk --release --dart-define=APP_VERSION=20260718-1600
|
||||
flutter build apk --release --dart-define=APP_VERSION=20260821-135
|
||||
adb install -r build/app/outputs/flutter-apk/app-release.apk
|
||||
```
|
||||
|
||||
@@ -111,10 +109,10 @@ jizhang/
|
||||
│ └── features/ # 业务页面
|
||||
├── admin-web/ # Vue3 + Ant Design 后台
|
||||
│ └── src/
|
||||
│ ├── App.vue # ★ 侧边栏版本号
|
||||
│ ├── App.vue # Admin 壳与导航
|
||||
│ └── views/ # 管理页面
|
||||
├── docs/ # 项目说明、设计规范、开发说明
|
||||
└── design/ # UI 稿、UX 原型、配色探索
|
||||
├── design/ # UI 稿、UX 原型、配色探索
|
||||
└── docs/ # 项目状态、设计、开发与客户端对接文档
|
||||
```
|
||||
|
||||
---
|
||||
@@ -136,5 +134,6 @@ jizhang/
|
||||
| 修改了代码但 App 不变 | 没有 clean 构建，或没加 dart-define | `flutter clean && flutter build apk --release --dart-define=APP_VERSION=...` |
|
||||
| 修改了代码但后台不变 | 后端还在跑旧进程 | 先 `Stop-Process -Name dotnet -Force` 再 `dotnet run` |
|
||||
| Admin Web 界面不变 | 浏览器缓存 | Ctrl+Shift+R 强制刷新，或用无痕模式打开 |
|
||||
| 数据库结构不一致 | 未执行最新 EF Migration | `dotnet ef database update` 后再启动服务 |
|
||||
| Windows 文件路径错误 | 中文路径编码 | 用 python3 读文件时加 `encoding='utf-8'` |
|
||||
| sed 破坏代码 | git-bash 的 sed 不兼容 | 禁止用 sed 改 dart/vue 源码，用 Write/Edit 工具 |
|
||||
|
||||
+13
-8
@@ -1,6 +1,8 @@
|
||||
# 喵记账 · 项目骨架
|
||||
|
||||
> Flutter 客户端 + .NET 9 后端 · 搭建于 2026-07-18
|
||||
> Flutter 客户端 + .NET 9 后端 · 当前状态更新于 2026-08-21
|
||||
|
||||
当前实现状态与待办以 [`STATUS.md`](STATUS.md) 为准；本文保留项目入口、运行方式和接口索引。
|
||||
|
||||
## 目录结构
|
||||
|
||||
@@ -50,7 +52,7 @@ jizhang/
|
||||
2. 改 `backend/MiaoJiZhang.Api/appsettings.json` 里的连接串（`your_password`）
|
||||
3. 改 `Jwt:Secret` 为 ≥32 字符的随机串
|
||||
4. `cd backend && dotnet run --project MiaoJiZhang.Api`
|
||||
- 开发期 `Program.cs` 会 `EnsureCreated` 建表 + 跑种子数据
|
||||
- 数据库结构通过 `MiaoJiZhang.Infrastructure/Persistence/Migrations` 维护；本地首次启动前执行 `dotnet ef database update`
|
||||
- OpenAPI 文档：`http://localhost:5000/openapi/v1.json`
|
||||
5. 测试注册：
|
||||
```bash
|
||||
@@ -93,15 +95,18 @@ flutter run
|
||||
9. ~~性格设置页~~ ✅（PUT /api/users/me/companion + CompanionPage，形象/性格/三滑杆）
|
||||
10. ~~分类管理~~ ✅（POST/DELETE /api/categories + CategoryManagePage，自定义分类增删）
|
||||
11. ~~语音/OCR 流程~~ ✅（POST /api/parse + ParseSheet 确认入账；ASR/OCR SDK 接入后自动填充文本）
|
||||
12. ~~LLM 接入层~~ ✅（ILlmClient 抽象 + NullLlmClient 回退规则版；对接真实 LLM 时实现该接口即可）
|
||||
12. ~~LLM 接入层~~ ✅（已有客户端抽象、权限/额度和回退路径；仍需真实环境联调）
|
||||
|
||||
13. ~~Admin Web 后台~~ ✅（配置、分类、AI 形象/性格、表情包、用户、推送、审计与管理员账号页面已存在）
|
||||
14. ~~EF Core Migration~~ ✅（已有多次迁移；发布前仍需执行全新库和升级库验证）
|
||||
|
||||
## 遗留（需要外部资源/发布前处理）
|
||||
|
||||
- ASR（语音转文字）与拍照 OCR 的 SDK 选型接入（ParseSheet 已留好入口，接入后把识别文本传入即可）
|
||||
- 真实 LLM 对接（实现 ILlmClient；性格 Prompt 已在 AiPersona 表可后台调）
|
||||
- SVG 图标（category_icon.dart / stickerStyle 集中管理，直接替换映射即可）
|
||||
- Admin Web 后台（`docs/DESIGN.md` 第 8 节；实体 AppConfig/AiPersona/AiAvatar/Sticker 已建好）
|
||||
- EF Migration 替代 EnsureCreated；Jwt Secret 换生产值；baseUrl 环境化
|
||||
- 真实 LLM、OCR/ASR、截图识别和推送供应商的生产配置与联调
|
||||
- JWT Secret、管理员引导变量、数据库连接串、API Base URL 和更新下载地址环境化
|
||||
|
||||
## 已完成的接口清单
|
||||
|
||||
@@ -129,6 +134,6 @@ flutter run
|
||||
|
||||
## 技术债 / 注意
|
||||
|
||||
- 后端用 `EnsureCreated` 跳过 Migration，便于快速起盘；正式环境前要切到 `dotnet ef migrations add Init`
|
||||
- `appsettings.json` 的 `Jwt:Secret` 是占位值，**生产必须换**
|
||||
- 前端 `main_shell.dart` 的 5 个 branch 暂用 `Placeholder()`，下一步逐个填真实页面
|
||||
- `Build:Version` 未注入时后端显示 `dev`；发布构建必须显式注入版本。
|
||||
- `appsettings.json` 的 JWT、数据库和外部服务配置不能直接用于生产。
|
||||
- Admin Web 的 `wwwroot/assets` 是构建生成物；本地构建后不要把临时 hashed 文件混入提交。
|
||||
|
||||
@@ -0,0 +1,71 @@
|
||||
# 记之 · 当前项目状态
|
||||
|
||||
> 更新时间：2026-08-21
|
||||
|
||||
## 总览
|
||||
|
||||
项目已经从 UI/接口骨架进入「客户端、后台和服务端能力联调」阶段。当前主干包含 Flutter 客户端、.NET 9 API、Vue 3 管理后台、数据库迁移和自动化测试；`main` 与 `origin/main` 当前指向同一提交 `8828851`。
|
||||
|
||||
## 已完成模块
|
||||
|
||||
### 后端 API
|
||||
|
||||
- 用户注册、登录、JWT、用户资料、引导和双模式切换。
|
||||
- 账本、系统/自定义分类、手动记账、月账单、统计、搜索和软删除回收站。
|
||||
- AI 聊天、意图识别、AI 直接入账、来源追溯、预算、月报、表情包和 AI 伙伴设置。
|
||||
- 文本解析入口、截图识别相关接口、识别幂等和 AI 权限/额度控制。
|
||||
- 管理后台 API：品牌配置、系统分类、AI 形象/性格、表情包、用户、推送、管理员账号、审计和密码变更。
|
||||
- 账户注销清理、数据导出/恢复、同步冲突和访客数据合并相关服务。
|
||||
- EF Core/MySQL 迁移已存在，覆盖初始模型、账户注销、分类颜色、AI 权限、额度、推送基础设施和转账/后台安全等变更。
|
||||
|
||||
### Flutter 客户端
|
||||
|
||||
- 启动、登录/注册、引导选模式和 AI 伙伴。
|
||||
- 普通模式首页、账本切换、手动记账、账单详情/编辑、聊天和全 AI 模式。
|
||||
- 统计、AI 月报、预算、搜索、分类管理、伙伴设置、回收站、数据管理和推送设置。
|
||||
- 语音/OCR 确认页、截图识别设置/批量导入、识别诊断、离线提示、同步冲突和本地数据导出。
|
||||
- 客户端更新检查、推送注册和本地数据库/会话恢复。
|
||||
|
||||
当前 `frontend/pubspec.yaml` 版本为 `1.2.5+135`；发布时仍需使用正式构建参数和发布说明。
|
||||
|
||||
### Admin Web
|
||||
|
||||
已具备登录、强制改密、仪表盘、系统设置、品牌配置、系统分类、AI 性格、AI 形象、表情包、用户、推送、管理员账号和审计页面。管理员角色权限由路由和后端共同控制。
|
||||
|
||||
### 测试
|
||||
|
||||
- 后端：API 集成测试、推送集成测试、推送供应商测试。
|
||||
- Flutter：模型、主题/时间、本地导出、本地转移数据库、更新流程、视觉契约和 Widget 测试。
|
||||
|
||||
## 当前待办
|
||||
|
||||
### P0：联调与发布阻塞项
|
||||
|
||||
- 在真实环境验证 LLM、OCR/ASR、截图识别和推送供应商配置。
|
||||
- 验证最新 EF Migration 在全新库、升级库和回滚/重试场景下的行为。
|
||||
- 将数据库连接串、JWT Secret、管理员引导变量、API Base URL 和更新下载地址全部改为部署环境注入。
|
||||
- 完成 Android 内部构建的截图权限、后台识别、证书和网络安全回归。
|
||||
|
||||
### P1：质量与体验
|
||||
|
||||
- 对核心流程做端到端回归：注册 → 引导 → 记账 → AI 解析 → 撤销 → 月报/预算。
|
||||
- 完善错误提示、离线待同步、同步冲突和外部服务失败时的降级行为。
|
||||
- 检查 Admin Web 发布资源生成策略，避免把本地 hashed 静态文件和构建目录带入工作区。
|
||||
|
||||
### P2：后续演进
|
||||
|
||||
- 完成正式 SVG/插画资源和更多运营内容配置。
|
||||
- 补充后台数据看板、脱敏意图失败样本和内容版本回滚。
|
||||
- 完成各平台正式签名、应用商店元数据和更新渠道配置。
|
||||
|
||||
## 工作区清理记录
|
||||
|
||||
2026-08-21 已清理未跟踪的完整备份、历史部署、`.codex-tools` 缓存、Codex 临时构建/补丁目录，以及后端 `wwwroot/assets` 的未跟踪生成资源。源码、`docs/`、设计原型、APK、Android 新代码和测试文件未删除。
|
||||
|
||||
## 建议验证顺序
|
||||
|
||||
1. 启动 MySQL，执行 `dotnet ef database update`。
|
||||
2. 配置后端外部服务和管理员引导变量，运行 API 集成测试。
|
||||
3. 构建 Admin Web，验证登录、权限、配置和发布资源。
|
||||
4. 运行 Flutter 测试，再构建 `1.2.5+135` 内部包。
|
||||
5. 用真实设备验证截图识别、推送、离线同步和更新检查。
|
||||
Reference in New Issue
Block a user