# 喵记账 · 开发手册

> 最后更新：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-random-password-of-at-least-12-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`。

### 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 工具 |