# 喵记账 · 项目骨架

> 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 文件混入提交。