# 喵记账 · 开发手册

> 最后更新：2026-07-18

## 版本号规范

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

### 后端版本号
- 文件：`backend/MiaoJiZhang.Api/Program.cs`
- 变量：`apiVersion = "20260718-1600"`（修改此行即可）
- 显示位置：
  - `GET /api/ping` 返回 JSON `{ "version": "...", "built": "..." }`
  - `GET /api/version` 同上
- 更新方法：修改 `apiVersion` 字符串，重启后端

### Flutter App 版本号
- 文件：`frontend/lib/shared/version.dart`
- 变量：通过 `--dart-define=APP_VERSION=xxx` 构建时注入，默认 `"dev"`
- 显示位置：
  - 启动页（SplashPage）Logo 下方
  - 登录页底部
  - 「我的」页底部
- 构建命令：
  ```bash
  flutter clean
  flutter build apk --release --dart-define=APP_VERSION=20260718-1600
  ```
  ⚠️ **必须加 `--dart-define`，否则 App 显示 `vdev`**

### Admin Web 版本号
- 文件：`admin-web/src/App.vue`
- 变量：侧边栏底部的硬编码版本文字 `<div>v20260718-1600</div>`
- 更新方法：修改 `<div>` 内的版本号，重新构建部署
  ```bash
  cd admin-web && npm run build
  cp dist/index.html ../backend/MiaoJiZhang.Api/wwwroot/
  cp -r dist/assets ../backend/MiaoJiZhang.Api/wwwroot/
  ```

---

## 构建与部署

### 1. 后端
```bash
cd backend
dotnet build
# 重启
powershell -Command "Get-Process dotnet | Stop-Process -Force"
dotnet run --project MiaoJiZhang.Api
```

### 2. Admin Web
```bash
cd admin-web
npm run build
cp dist/index.html ../backend/MiaoJiZhang.Api/wwwroot/
cp -r dist/assets ../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=20260718-1600
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                       # ★ 侧边栏版本号
│       └── views/                        # 管理页面
├── docs/                                  # 项目说明、设计规范、开发说明
└── design/                                # UI 稿、UX 原型、配色探索
```

---

## 验证构建是否生效

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 强制刷新，或用无痕模式打开 |
| Windows 文件路径错误 | 中文路径编码 | 用 python3 读文件时加 `encoding='utf-8'` |
| sed 破坏代码 | git-bash 的 sed 不兼容 | 禁止用 sed 改 dart/vue 源码，用 Write/Edit 工具 |