144 lines
5.9 KiB
Markdown
144 lines
5.9 KiB
Markdown
# 喵记账 · 开发手册
|
||
|
||
> 最后更新：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 下方
|
||
- 登录页底部
|
||
- 「我的」页底部
|
||
- 构建命令：
|
||
```powershell
|
||
flutter clean
|
||
flutter build apk --release --dart-define=APP_VERSION=20260821-135
|
||
```
|
||
⚠️ **必须加 `--dart-define`，否则 App 显示 `vdev`**
|
||
|
||
### Admin Web 版本号
|
||
- Admin Web 不再维护独立硬编码版本号，以同次后端发布版本为准。
|
||
- 更新方法：重新构建并完整替换后端静态资源目录。
|
||
```bash
|
||
cd admin-web && npm run build
|
||
Copy-Item -Recurse -Force dist\* ..\backend\MiaoJiZhang.Api\wwwroot\
|
||
```
|
||
|
||
---
|
||
|
||
## 构建与部署
|
||
|
||
### 1. 后端
|
||
```bash
|
||
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
|
||
```powershell
|
||
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
|
||
```bash
|
||
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/ # 项目状态、设计、开发与客户端对接文档
|
||
```
|
||
|
||
---
|
||
|
||
## 验证构建是否生效
|
||
|
||
1. **后端**：浏览器访问 `http://localhost:5000/api/ping`，看返回的 `version` 字段
|
||
2. **Admin Web**：打开 `http://localhost:5000/`，看左下角版本号，对不上就 Ctrl+Shift+R
|
||
3. **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 工具 |
|