135 lines
7.2 KiB
Markdown
135 lines
7.2 KiB
Markdown
# 喵记账 · 项目骨架
|
||
|
||
> Flutter 客户端 + .NET 9 后端 · 搭建于 2026-07-18
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
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`
|
||
- 开发期 `Program.cs` 会 `EnsureCreated` 建表 + 跑种子数据
|
||
- 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 接入层~~ ✅（ILlmClient 抽象 + NullLlmClient 回退规则版；对接真实 LLM 时实现该接口即可）
|
||
|
||
## 遗留（需要外部资源/发布前处理）
|
||
|
||
- 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 环境化
|
||
|
||
## 已完成的接口清单
|
||
|
||
| 接口 | 说明 |
|
||
|---|---|
|
||
| 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） |
|
||
|
||
## 技术债 / 注意
|
||
|
||
- 后端用 `EnsureCreated` 跳过 Migration，便于快速起盘；正式环境前要切到 `dotnet ef migrations add Init`
|
||
- `appsettings.json` 的 `Jwt:Secret` 是占位值，**生产必须换**
|
||
- 前端 `main_shell.dart` 的 5 个 branch 暂用 `Placeholder()`，下一步逐个填真实页面
|