Initial project import

2026-07-24 23:11:20 +08:00
commit 6396eabb87
372 changed files with 49682 additions and 0 deletions
@@ -0,0 +1,134 @@
+# 喵记账 · 开发手册
+
+> 最后更新：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 工具 |