# 农易富 · 农产品收购交易平台 — 快速启动手册

> 本文档是**唯一权威的快速启动入口**。重新安装 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`。