Docs: quick-start guide, progress archive, and codebuddy gitignore

2026-08-23 11:06:51 +08:00
parent c7a902833c
commit 5b7707aa3d
4 changed files with 182 additions and 36 deletions
@@ -1,2 +1,97 @@
-这是基于主干信息F8项目网页版的项目说明
-开发语言：后台C#，前端Vue，数据库MySQL
+# 农易富 · 农产品收购交易平台 — 快速启动手册
+
+> 本文档是**唯一权威的快速启动入口**。重新安装 CodeBuddy / 更换目录后，把本文件夹整体拷贝过去，在**新项目根目录**打开终端执行下列命令即可启动，无需任何额外配置。
+
+## 1. 项目一句话
+
+BS 版农产品收购平台，业务链路：**农户管理 → 过磅称重 → 电子支付 → 反向开票 → 统计报表 → 可视化大屏**。后端 C#/.NET，前端 Vue3，数据库在线 MySQL，图片存阿里云 OSS，身份证识别走阿里云市场 OCR。
+
+## 2. 端口约定（全局固定，勿乱改）
+
+| 服务 | 端口 | 说明 |
+| --- | --- | --- |
+| 后端 API | **9002** | `appsettings.json` 的 `Server:LanPort`、`launchSettings.json` |
+| 前端 dev server | **9000** | `frontend/vite.config.ts`，代理 `/api`、`/uploads` → `http://localhost:9002` |
+
+## 3. 快速启动（PowerShell，在项目根目录执行）
+
+### 后端（必须先编译，再启动）
+
+```powershell
+# 1) 编译（改过后端代码必须执行；未改过可跳过）
+dotnet build backend/AgriculturalPlatform.Api/AgriculturalPlatform.Api.csproj -c Debug
+
+# 2) 启动（脚本用 dotnet run --no-build，加载的是第 1 步编译产物）
+powershell -ExecutionPolicy Bypass -File scripts/start-backend.ps1
+```
+
+### 前端
+
+```powershell
+Start-Process -FilePath "npm.cmd" -ArgumentList @("run","dev") -WorkingDirectory "frontend" -RedirectStandardOutput "frontend-dev.log" -RedirectStandardError "frontend-dev.err.log" -WindowStyle Hidden
+```
+
+### 验证启动成功
+
+```powershell
+Get-NetTCPConnection -LocalPort 9002,9000 -ErrorAction SilentlyContinue | Where-Object State -eq Listen
+```
+
+- 后端健康检查：`http://localhost:9002/api/auth/login`（POST `{"username":"admin","password":"123456"}`）应返回 token
+- 浏览器打开 `http://localhost:9000` 登录
+
+## 4. 登录账号
+
+| 账号 | 密码 | 角色 |
+| --- | --- | --- |
+| admin | 123456 | 系统管理员 |
+| company | 123456 | 公司管理员 |
+| station1 / station2 | 123456 | 收购站员工 |
+| individual | 123456 | 收购个体 |
+
+## 5. 数据库（在线 MySQL，无需本地部署）
+
+连接串在 `backend/AgriculturalPlatform.Api/appsettings.json` 的 `ConnectionStrings:Default`：
+
+```
+server=116.198.221.105;port=3306;database=F8Web;user=f8web;charset=utf8mb4
+```
+
+首次启动自动 `EnsureCreated + Seed` 建表并写入演示数据（幂等，可重复启动）。数据库连接失败时检查该连接串与 MySQL 白名单。
+
+## 6. 常见坑（务必先看）
+
+1. **改后端代码后必须 `dotnet build` 再启动**：`start-backend.ps1` 是 `--no-build`，会加载旧 DLL，导致"改了半天没生效"（历史踩坑：`/menus/my` 401 登录失败即因此）。
+2. **PowerShell 中文路径乱码**：所有命令用**相对路径**并在项目根执行，不要拼写绝对中文路径。
+3. **git commit 中文消息报"字符串缺少终止符"**：PowerShell 编码问题，提交信息用英文。
+4. **浏览器自动化**：`playwright-cli` 默认找 Chrome，本机需用 Edge（路径 `C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe`）；快速排查接口问题时直接用 PowerShell `Invoke-WebRequest` 测 API 更快。
+5. **停服务**：`Get-NetTCPConnection -LocalPort 9002,9000` 找到 OwningProcess 后 `Stop-Process -Id <pid> -Force`。
+
+## 7. Git 私有仓库
+
+- 远程：`https://github.bbitcn.net/fanhongcai/F8WebAI.git`（`origin`）
+- 账号：`fanhongcai@bbitcn.net`
+- 自动化终端无法弹出 Git 登录窗时，用内嵌凭据 URL 推送：
+  `git push https://fanhongcai%40bbitcn.net:<密码>@github.bbitcn.net/fanhongcai/F8WebAI.git main`
+- 注意：`F8Web` 远程（缺仓库路径）与 `F8WebAI`（与 origin 重复）均已清理，只剩 `origin`
+
+## 8. 关键文件索引
+
+| 用途 | 路径 |
+| --- | --- |
+| 后端入口 / 服务注册 | `backend/AgriculturalPlatform.Api/Program.cs` |
+| 后端配置（DB/OSS/OCR/JWT/端口） | `backend/AgriculturalPlatform.Api/appsettings.json` |
+| 数据模型 / DbContext / 种子数据 | `backend/AgriculturalPlatform.Api/Models`、`Data/` |
+| JWT 签发 / 当前用户 / 数据权限 | `Services/JwtService.cs`、`CurrentUser.cs`、`DataScopeService.cs` |
+| 登录接口 / 登录页 | `Controllers/AuthController.cs`、`frontend/src/views/Login.vue` |
+| 菜单权限 | `Controllers/MenusController.cs` |
+| 前端 API 封装 / 请求拦截 | `frontend/src/api/` |
+| 主布局 / 顶栏（日历+天气+Logo 字典） | `frontend/src/layouts/MainLayout.vue`、`HeaderCalendar.vue`、`HeaderWeather.vue` |
+| 天气数据（全局共享 composable） | `frontend/src/composables/useWeather.ts` |
+| 可视化大屏 | `frontend/src/views/Dashboard.vue`（路由 `/dashboard`） |
+| 前端代理配置 | `frontend/vite.config.ts` |
+| 启动脚本 | `scripts/start-backend.ps1` |
+
+## 9. 开发进度存档
+
+见同目录文档 `开发进度存档.md`。