喵记账 · 开发手册

最后更新：2026-07-26

版本号规范

三端统一版本号格式：YYYYMMDD-HHMM（年月日-时分）。每次构建必须更新版本号。

后端版本号

文件：backend/MiaoJiZhang.Api/Program.cs
配置：Build:Version（未注入时默认为 dev）
显示位置：
- GET /api/ping 返回 JSON { "version": "...", "built": "..." }
- GET /api/version 同上
更新方法：通过环境变量或部署配置注入 Build__Version，重启后端

Flutter App 版本号

文件：frontend/lib/shared/version.dart
变量：通过 --dart-define=APP_VERSION=xxx 构建时注入，默认 "dev"
显示位置：
- 启动页（SplashPage）Logo 下方
- 登录页底部
- 「我的」页底部

构建命令：

flutter clean
flutter build apk --release --dart-define=APP_VERSION=20260821-135

⚠️ 必须加 --dart-define，否则 App 显示 vdev

Admin Web 版本号

Admin Web 不再维护独立硬编码版本号，以同次后端发布版本为准。

更新方法：重新构建并完整替换后端静态资源目录。

cd admin-web && npm run build
Copy-Item -Recurse -Force dist\* ..\backend\MiaoJiZhang.Api\wwwroot\

构建与部署

1. 后端

cd backend
export Admin__BootstrapUsername='admin'
export Admin__BootstrapPassword='replace-with-a-password-longer-than-5-characters'
dotnet build
# 重启
powershell -Command "Get-Process dotnet | Stop-Process -Force"
dotnet run --project MiaoJiZhang.Api

首次启动必须设置 Admin__BootstrapUsername 和 Admin__BootstrapPassword，用于创建第一个 super_admin。首次登录后后台会强制修改密码；管理员创建成功后可从运行环境中移除这两个引导变量。正式环境必须使用 HTTPS 并保持 Admin__CookieSecure=true。本地纯 HTTP 调试时才可临时设置 Admin__CookieSecure=false。

后台“AI 配置 → 模型服务”可以直接保存和替换 LLM API Key。实际 API Key 使用 AES-GCM 加密后写入配置表，加密密钥由服务端从必填的 Jwt__Secret 自动派生，无需增加部署变量；页面和接口只显示 API Key 尾号。旧的 LLM_API_KEY 仍作为回退配置，后台保存的密钥优先。

2. Admin Web

cd admin-web
npm run build
Copy-Item -Recurse -Force dist\* ..\backend\MiaoJiZhang.Api\wwwroot\

浏览器打开 http://localhost:5000/ 或 http://{电脑IP}:5000/。如界面未更新请 Ctrl+Shift+R 强制刷新。

3. Flutter APK

cd frontend
flutter clean
flutter pub get
flutter build apk --release --dart-define=APP_VERSION=20260821-135
adb install -r build/app/outputs/flutter-apk/app-release.apk

项目结构

jizhang/
├── backend/
│   └── MiaoJiZhang.sln
│       ├── MiaoJiZhang.Api/          # Web API 控制器、JWT、配置
│       │   ├── Program.cs            # ★ 启动入口 + 版本号
│       │   ├── Controllers/
│       │   │   ├── AuthController.cs
│       │   │   ├── ChatController.cs # ★ AI 聊天（LLM only）
│       │   │   ├── AdminController.cs
│       │   │   ├── UsersController.cs
│       │   │   ├── TransactionsController.cs
│       │   │   └── ...
│       │   ├── Services/
│       │   │   ├── OpenAiVisionClient.cs  # LLM 客户端
│       │   │   ├── AiServices.cs          # 规则版（已废弃）
│       │   │   └── ...
│       │   └── wwwroot/                   # Admin Web 发布目标
│       ├── MiaoJiZhang.Domain/            # 实体 + 枚举
│       └── MiaoJiZhang.Infrastructure/    # EF Core + MySQL
├── frontend/
│   └── lib/
│       ├── main.dart
│       ├── app/app.dart                  # 路由
│       ├── shared/
│       │   ├── version.dart              # ★ App 版本号
│       │   ├── api/                      # API 客户端
│       │   ├── theme/                    # 设计规范色
│       │   └── widgets/                  # 图标/组件
│       └── features/                     # 业务页面
├── admin-web/                            # Vue3 + Ant Design 后台
│   └── src/
│       ├── App.vue                       # Admin 壳与导航
│       └── views/                        # 管理页面
├── design/                                # UI 稿、UX 原型、配色探索
└── docs/                                  # 项目状态、设计、开发与客户端对接文档

验证构建是否生效

后端：浏览器访问 http://localhost:5000/api/ping，看返回的 version 字段
Admin Web：打开 http://localhost:5000/，看左下角版本号，对不上就 Ctrl+Shift+R
App：打开 App 看启动页 Logo 下方的版本号，或登录页/我的页底部

版本号对不上 = 没构建进去 = 代码没生效。不要继续测试其他功能，先排查构建问题。

常见错误

现象	原因	解决
修改了代码但 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 工具

5.9 KiB Raw Permalink Blame History Unescape Escape