jizhi/docs/PROJECT.md

喵记账 · 项目骨架

Flutter 客户端 + .NET 9 后端 · 当前状态更新于 2026-08-21

当前实现状态与待办以 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. 测试注册：

   curl -X POST http://localhost:5000/api/auth/register \
     -H "Content-Type: application/json" \
     -d '{"username":"demo","password":"123456"}'
   

前端

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