140 lines
7.6 KiB
Markdown
140 lines
7.6 KiB
Markdown
# 喵记账 · 项目骨架
|
||
|
||
> Flutter 客户端 + .NET 9 后端 · 当前状态更新于 2026-08-21
|
||
|
||
当前实现状态与待办以 [`STATUS.md`](STATUS.md) 为准；本文保留项目入口、运行方式和接口索引。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
jizhang/
|
||
├── docs/ # 项目说明、设计规范、开发说明
|
||
│ ├── PROJECT.md # 本文档
|
||
│ ├── DESIGN.md # 设计文档（规范 + 决策 + 后台方案）
|
||
│ ├── DEVELOPER.md # 开发交接与构建说明
|
||
│ └── app-client-integration.md
|
||
├── design/ # 静态 UI 稿、可交互原型、配色探索
|
||
│ ├── ui-mockup.html # 静态 UI 稿（24 屏）
|
||
│ └── ux-prototype.html # 可交互 UX 原型
|
||
├── backend/ # .NET 解决方案
|
||
│ └── MiaoJiZhang.sln
|
||
│ ├── MiaoJiZhang.Api/ # Web API（控制器、JWT、Program）
|
||
│ │ ├── Controllers/AuthController.cs # /api/auth/register|login
|
||
│ │ ├── Services/JwtService.cs
|
||
│ │ ├── Contracts/AuthContracts.cs
|
||
│ │ ├── Program.cs # 启动 + 自动建库 + 种子
|
||
│ │ └── appsettings.json # 连接串 + JWT 配置
|
||
│ ├── MiaoJiZhang.Domain/ # 领域层（实体 + 枚举）
|
||
│ │ ├── Entities/User.cs # ★ 含 email/phone/wechat 预留字段
|
||
│ │ ├── Entities/Ledger.cs # 账本/分类/账单/预算/聊天
|
||
│ │ ├── Entities/AdminContent.cs # AppConfig/AiPersona/AiAvatar/Sticker
|
||
│ │ └── Enums/Enums.cs
|
||
│ └── MiaoJiZhang.Infrastructure/ # EF Core + MySQL
|
||
│ └── Persistence/
|
||
│ ├── AppDbContext.cs # ★ 账单软删除全局过滤
|
||
│ └── DbSeeder.cs # 默认分类/形象/性格/品牌配置
|
||
└── frontend/ # Flutter 客户端
|
||
└── lib/
|
||
├── main.dart
|
||
├── app/app.dart # 路由（go_router）
|
||
├── shared/theme/app_theme.dart # v0.5 设计规范色
|
||
└── features/
|
||
├── auth/pages/ # login_page / register_page
|
||
├── onboarding/pages/ # 选模式 + 选 AI 伙伴
|
||
├── home/pages/main_shell.dart # TabBar 壳（5 tab）
|
||
└── ai_mode/pages/ai_mode_page.dart # 全 AI 模式主界面
|
||
```
|
||
|
||
## 运行
|
||
|
||
### 后端
|
||
1. 本地装 MySQL，建库：`CREATE DATABASE miaoji;`
|
||
2. 改 `backend/MiaoJiZhang.Api/appsettings.json` 里的连接串（`your_password`）
|
||
3. 改 `Jwt:Secret` 为 ≥32 字符的随机串
|
||
4. `cd backend && dotnet run --project MiaoJiZhang.Api`
|
||
- 数据库结构通过 `MiaoJiZhang.Infrastructure/Persistence/Migrations` 维护；本地首次启动前执行 `dotnet ef database update`
|
||
- OpenAPI 文档：`http://localhost:5000/openapi/v1.json`
|
||
5. 测试注册：
|
||
```bash
|
||
curl -X POST http://localhost:5000/api/auth/register \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"username":"demo","password":"123456"}'
|
||
```
|
||
|
||
### 前端
|
||
```bash
|
||
cd frontend
|
||
flutter pub get
|
||
flutter run
|
||
```
|
||
当前路由：`/login → /register → /onboarding → /home 或 /ai-mode`
|
||
|
||
## 已落地的设计决策（代码层）
|
||
|
||
| 决策 | 落地位置 |
|
||
|---|---|
|
||
| 仅用户名密码，预留 email/phone/wechat 字段 | `User.cs`（字段+唯一索引齐全，控制器不开放） |
|
||
| App 名称后台可配 | `AppConfig.brand.app_name` + `DbSeeder` 初始化 |
|
||
| 口癖跟随形象 | `AiAvatar.SpeechTic` + `AiPersona.PromptTemplate` 的 `{tic}` 占位 |
|
||
| AI 记账直接入账+可撤销 | `Transaction.IsDeleted/DeletedAt` + `AppDbContext` 软删除全局过滤 |
|
||
| AI 来源追溯 | `Transaction.Source/SourceText/SourceChatMessageId` |
|
||
| 后台可调性格 Prompt 不发版 | `AiPersona.PromptTemplate` 存库 |
|
||
| 限流阈值后台可配 | `AppConfig.limit.daily_ai_messages` |
|
||
| 离线边界 | 前端 `shared_preferences`/`secure_storage` 已装；后端软删除保证撤销幂等 |
|
||
|
||
## 下一步 TODO（按优先级）
|
||
|
||
1. ~~前端接通注册登录 API~~ ✅
|
||
2. ~~前端 onboarding 落库~~ ✅
|
||
3. ~~后端业务控制器~~ ✅
|
||
4. ~~五个 tab 真实页面~~ ✅
|
||
5. ~~预算模块~~ ✅（GET/PUT /api/budgets + BudgetPage，总预算环+分类进度+超支变色）
|
||
6. ~~表情包系统~~ ✅（Sticker 种子 + GET /api/stickers + 聊天表情包面板，AI 会回表情包）
|
||
7. ~~AI 月报~~ ✅（GET /api/reports/monthly + ReportPage，含性格化点评）
|
||
8. ~~搜索~~ ✅（GET /api/search + SearchPage，可搜 AI 记账原话，仅AI筛选）
|
||
9. ~~性格设置页~~ ✅（PUT /api/users/me/companion + CompanionPage，形象/性格/三滑杆）
|
||
10. ~~分类管理~~ ✅（POST/DELETE /api/categories + CategoryManagePage，自定义分类增删）
|
||
11. ~~语音/OCR 流程~~ ✅（POST /api/parse + ParseSheet 确认入账；ASR/OCR SDK 接入后自动填充文本）
|
||
12. ~~LLM 接入层~~ ✅（已有客户端抽象、权限/额度和回退路径；仍需真实环境联调）
|
||
|
||
13. ~~Admin Web 后台~~ ✅（配置、分类、AI 形象/性格、表情包、用户、推送、审计与管理员账号页面已存在）
|
||
14. ~~EF Core Migration~~ ✅（已有多次迁移；发布前仍需执行全新库和升级库验证）
|
||
|
||
## 遗留（需要外部资源/发布前处理）
|
||
|
||
- ASR（语音转文字）与拍照 OCR 的 SDK 选型接入（ParseSheet 已留好入口，接入后把识别文本传入即可）
|
||
- 真实 LLM 对接（实现 ILlmClient；性格 Prompt 已在 AiPersona 表可后台调）
|
||
- SVG 图标（category_icon.dart / stickerStyle 集中管理，直接替换映射即可）
|
||
- 真实 LLM、OCR/ASR、截图识别和推送供应商的生产配置与联调
|
||
- JWT Secret、管理员引导变量、数据库连接串、API Base URL 和更新下载地址环境化
|
||
|
||
## 已完成的接口清单
|
||
|
||
| 接口 | 说明 |
|
||
|---|---|
|
||
| POST /api/auth/register, /login | 用户名密码注册登录，JWT |
|
||
| GET /api/users/me | 用户资料 + AI 伙伴 + onboardingDone |
|
||
| POST /api/users/me/onboarding | 引导落库（模式/形象/性格） |
|
||
| PUT /api/users/me/mode | 双模式切换 |
|
||
| GET /api/ledgers | 账本列表 |
|
||
| GET /api/categories?type= | 分类（系统+自定义） |
|
||
| POST /api/transactions | 手动记账 |
|
||
| DELETE /api/transactions/{id} | 撤销/删除（软删除） |
|
||
| GET /api/transactions/month | 月账单按日分组（首页） |
|
||
| GET /api/transactions/stats | 月统计：分类占比+每日趋势 |
|
||
| GET /api/chat/messages | 聊天历史 |
|
||
| POST /api/chat/messages | 发消息 → 意图识别 → 记账/查询/闲聊，AI 记账直接入账并返回账单卡片；表情包消息 AI 回文案+表情包 |
|
||
| GET/PUT /api/budgets | 预算查询（含已用）与设置（Amount<=0 删除） |
|
||
| GET /api/stickers | 表情包列表（后台可配） |
|
||
| GET /api/reports/monthly | AI 月报（数据+亮点+性格化点评） |
|
||
| GET /api/search | 账单搜索（关键词/金额区间/仅AI，可搜原话） |
|
||
| PUT /api/users/me/companion | AI 伙伴设置（形象/性格/滑杆） |
|
||
| POST /api/categories, DELETE /api/categories/{id} | 自定义分类增删 |
|
||
| POST /api/parse | 语音/OCR 文本 → 账单草稿（确认后走 POST /api/transactions） |
|
||
|
||
## 技术债 / 注意
|
||
|
||
- `Build:Version` 未注入时后端显示 `dev`；发布构建必须显式注入版本。
|
||
- `appsettings.json` 的 JWT、数据库和外部服务配置不能直接用于生产。
|
||
- Admin Web 的 `wwwroot/assets` 是构建生成物；本地构建后不要把临时 hashed 文件混入提交。
|