fanhongcai/F8WebAI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
fanhongcai
2026-08-23 11:06:51 +08:00
parent c7a902833c
commit 5b7707aa3d
4 changed files with 182 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+3
View File
@@ -37,3 +37,6 @@ build-check/
generated-images/ generated-images/
test.png test.png
test-avatar.png test-avatar.png
# CodeBuddy 项目数据（memory/automations 等，含敏感信息）
.codebuddy/
README.md
+36 -34
View File
@@ -2,61 +2,60 @@
基于主干信息 F8 农产品收购业务的产品化网页版（Browser/Server）平台，服务于**收购公司、收购站、收购个体**，向**农户**收购农产品，覆盖"农户管理 → 过磅称重 → 电子支付 → 反向开票 → 统计报表 → 可视化大屏"全业务链路。 基于主干信息 F8 农产品收购业务的产品化网页版（Browser/Server）平台，服务于**收购公司、收购站、收购个体**，向**农户**收购农产品，覆盖"农户管理 → 过磅称重 → 电子支付 → 反向开票 → 统计报表 → 可视化大屏"全业务链路。
> ⚡ **快速启动请直接阅读《项目说明》**（项目根目录），含完整启动命令、端口约定、常见坑与关键文件索引。
## 技术栈 ## 技术栈
| 端 | 技术 | | 端 | 技术 |
| --- | --- | | --- | --- |
| 后端 | C# / .NET 10（ASP.NET Core Web API、EF Core 10、JWT、BCrypt） | | 后端 | C# / .NET 10（ASP.NET Core Web API、EF Core 10、JWT、BCrypt） |
| 数据库 | 在线 MySQL 8（Pomelo 官方分支 `Microting.EntityFrameworkCore.MySql`，支持 EF Core 10） | | 数据库 | 在线 MySQL 8（Pomelo 官方分支 `Microting.EntityFrameworkCore.MySql`，支持 EF Core 10） |
| 前端 | Vue 3（最新版）+ Vite + TypeScript + Pinia + Vue Router + Element Plus + ECharts + Axios | | 前端 | Vue 3 + Vite + TypeScript + Pinia + Vue Router + Element Plus + ECharts + Axios + dayjs + lunar-javascript |
| 云服务 | 阿里云 OSS 附件存储（`Storage:UseOss`）、阿里云市场身份证 OCR（`Ocr:Provider=aliyun`） |
| 适配 | 电脑 PC 与触摸屏（触摸屏过磅页大按钮 + 数字键盘） | | 适配 | 电脑 PC 与触摸屏（触摸屏过磅页大按钮 + 数字键盘） |
## 目录结构 ## 目录结构
``` ```
backend/AgriculturalPlatform.Api/ # 后端 API backend/AgriculturalPlatform.Api/ # 后端 API（端口 9002）
├── Models/ # 实体模型（组织/用户/农户/品种/收购单/支付/发票） ├── Models/ # 实体模型（组织/用户/农户/品种/收购单/支付/发票/菜单字典）
├── Data/ # DbContext 与种子数据 ├── Data/ # DbContext、种子数据、幂等 Schema 迁移
├── Dtos/ # 接口传输对象 ├── Dtos/ # 接口传输对象
├── Services/ # JWT、数据权限、单号生成、当前用户 ├── Services/ # JWT、数据权限、单号生成、当前用户、OCR、OSS 存储、天气
└── Controllers/ # Auth/Orgs/Users/Farmers/Products/Purchases/Payments/Invoices/Reports/Dashboard └── Controllers/ # Auth/Orgs/Users/Farmers/Products/Purchases/Payments/Invoices/Reports/Dashboard/Menus/Dicts/...
frontend/ # 前端 frontend/ # 前端（dev server 端口 9000）
└── src/ └── src/
├── api/ # Axios 封装与全部接口 ├── api/ # Axios 封装与全部接口
├── views/ # 登录、工作台、大屏、各业务模块页面 ├── views/ # 登录、工作台、大屏、各业务模块页面
├── layouts/ # 主布局（侧边菜单） ├── layouts/ # 主布局（侧边菜单、顶栏日历/天气/Logo）
├── composables/ # 共享 composable（useWeather 等）
└── stores/ # Pinia 状态 └── stores/ # Pinia 状态
scripts/ # 启动/测试脚本（start-backend.ps1 等）
docker-compose.yml # 可选：本地 MySQL 8 开发环境 docker-compose.yml # 可选：本地 MySQL 8 开发环境
``` ```
## 快速开始 ## 快速开始
### 1. 准备数据库（在线 MySQL 或本地） > 全部命令在**项目根目录**的 PowerShell 中执行。详见《项目说明》。
- **在线 MySQL**：将下方连接串改为你的在线数据库地址（首次启动会自动建库建表并写入演示数据）。 ### 后端（端口 9002）
### 2. 后端 ```powershell
dotnet build backend/AgriculturalPlatform.Api/AgriculturalPlatform.Api.csproj -c Debug
```bash powershell -ExecutionPolicy Bypass -File scripts/start-backend.ps1
cd backend/AgriculturalPlatform.Api
# 修改 appsettings.json 中 ConnectionStrings:Default 为你的 MySQL 连接串
dotnet restore
dotnet run
``` ```
后端默认地址：`http://localhost:5246`（OpenAPI 文档：`http://localhost:5246/openapi/v1.json`）。 > ⚠️ 启动脚本为 `--no-build`，**修改后端代码后必须先 build**，否则运行的是旧 DLL（曾因此导致登录权限接口 401）。
### 3. 前端 ### 前端（端口 9000）
```bash ```powershell
cd frontend Start-Process -FilePath "npm.cmd" -ArgumentList @("run","dev") -WorkingDirectory "frontend" -WindowStyle Hidden
npm install
npm run dev
``` ```
前端默认地址：`http://localhost:5173`，已配置 `/api` 代理到后端。 浏览器访问 `http://localhost:9000`，`/api`、`/uploads` 已代理到 `http://localhost:9002`。
### 4. 登录 ### 登录
| 账号 | 密码 | 角色 | | 账号 | 密码 | 角色 |
| --- | --- | --- | | --- | --- | --- |
@@ -67,22 +66,25 @@ npm run dev
## 功能清单 ## 功能清单
- **农户管理**：农户档案（身份证/联系方式/村组/银行账户）、信用评分、冻结/启用、交易统计。 - **农户管理**：农户档案（身份证 OCR 识别/联系方式/村组/银行账户）、信用评分、冻结/启用、交易统计、手机传图上传。
- **过磅称重**：一次过磅（毛重）→ 二次回皮（皮重）自动计算净重与金额；支持 PC 列表操作与**触摸屏大字键盘**过磅；进行中单据实时展示。 - **过磅称重**：一次过磅（毛重）→ 二次回皮（皮重）自动计算净重与金额；支持 PC 列表操作与**触摸屏大字键盘**过磅（`/weighing/touch`）；进行中单据实时展示；金额大额自动以万元显示。
- **电子支付**：按收购单或批量结算，微信/支付宝/银行转账/现金四种方式，支付确认与退款，农户应收/已付/未付汇总。 - **电子支付**：按收购单或批量结算，微信/支付宝/银行转账/现金四种方式，支付确认与退款，农户应收/已付/未付汇总。
- **反向开票**：收购方向农户开具"农产品收购发票"（自产农产品免税，税率 0%），支持按已结算收购单一键开票、发票作废（红冲）。 - **反向开票**：收购方向农户开具"农产品收购发票"（自产农产品免税，税率 0%），支持按已结算收购单一键开票、发票作废（红冲）。
- **统计报表**：收购汇总（按日/月/品种/农户/收购方）、付款统计（方式/状态）、开票统计，支持图表与 CSV 导出。 - **统计报表**：收购汇总（按日/月/品种/农户/收购方）、付款统计（方式/状态）、开票统计，支持图表与 CSV 导出（月份分组在内存中排序，避免 SQLite/MySQL 字符串排序问题）。
- **可视化大屏**：今日/本月 KPI、14 天趋势、品种占比、农户排行、收购方对比、实时过磅，30 秒自动刷新。 - **可视化大屏**：今日/本月 KPI、14 天趋势、品种占比、农户排行、收购方对比、实时过磅，30 秒自动刷新；日期区间选择器深色主题。
- **组织与用户**：公司 / 收购站 / 收购个体三级组织；四类角色；**数据权限隔离**（公司只看本公司及旗下站点数据）。 - **组织与用户**：公司 / 收购站 / 收购个体三级组织；四类角色；**数据权限隔离**（公司只看本公司及旗下站点数据）。
- **系统管理**：角色权限、菜单管理、数据字典（含系统 Logo 图标 `system_logo` 配置）。
- **通知公告**：站内公告发布与列表；**关于系统** 页面。
- **顶栏**：动态日历（农历/节气）、天气（IP 定位 + Open-Meteo，全局共享 composable）、Logo 图标按字典配置。
## 数据库配置说明 ## 数据库配置说明
后端启动时会执行 `EnsureCreated + Seed`：数据库不存在则自动建表，空库自动写入演示数据（组织、账号、品种、农户及近 30 天收购/付款/发票历史）。 在线 MySQL 连接串见 `backend/AgriculturalPlatform.Api/appsettings.json` 的 `ConnectionStrings:Default`。后端启动时执行 `EnsureCreated + Seed + SchemaMigrator`：数据库不存在则自动建表，空库自动写入演示数据（组织、账号、品种、农户及近 30 天收购/付款/发票历史），迁移补丁幂等可重复执行。
生产建议改用 EF Core Migration 管理表结构。
## 常见问题 ## 常见问题
- **后端启动报数据库连接失败**：检查 `appsettings.json` 的 `ConnectionStrings:Default`，MySQL 需允许远程连接（主机防火墙/云数据库白名单放行）。 - **后端启动报数据库连接失败**：检查 `appsettings.json` 的 `ConnectionStrings:Default`，MySQL 需允许远程连接（主机防火墙/云数据库白名单放行）。
- **前端接口 401**：登录过期，重新登录即可。 - **登录后立刻被弹回登录页**：多为 `/api/menus/my` 返回 401。若后端代码有改动而**未重新编译**，会命中旧 DLL 问题——执行 `dotnet build` 后重启后端。
- **想换端口**：后端在 `Properties/launchSettings.json` 修改后，同步修改 `frontend/vite.config.ts` 的代理 target 与后端 `appsettings.json` 的 `FrontendUrl`。 - **想换端口**：后端 `Properties/launchSettings.json`、`appsettings.json` 的 `Server:LanPort` 与前端 `vite.config.ts` 的 proxy target 需同步修改。
- **PowerShell 中文路径乱码 / git commit 中文报错**：使用相对路径、英文提交信息。
- **git 推送要认证**：远程 `https://github.bbitcn.net/fanhongcai/F8WebAI.git`，自动化终端用内嵌凭据 URL 推送（见《项目说明》）。
开发进度存档.md
+46
View File
@@ -0,0 +1,46 @@
# 农易富 · 开发进度存档
> 供重装环境 / 换目录后快速恢复上下文。最近更新：2026-08-23。
## 一、版本里程碑
| 时间 | 提交 | 内容 |
| --- | --- | --- |
| 2026-08-13 | `8099eba`（首次推送） | 平台全量代码上线：登录修复（JWT `uid` claim + 控制器统一 `ClaimTypes.NameIdentifier`）、收购菜单层级修正（过磅/触摸屏过磅归入收购业务）、版权信息移至框架底部、顶栏动态日历图标、天气数据源统一（`useWeather.ts`）、农易富® 商标、`system_logo` 数据字典（Logo 图标可配）、大屏日期选择器深色化、OCR/OSS 上传接入 |
| 2026-08-20 | `c7a9028` | 端口统一：后端 **9002**、前端 **9000**（此前 5246/5173）；报表按月/日分组排序修复（内存拼 Key 避免字典序错位）；过磅金额超 100 万自动转万元显示 |
## 二、当前运行状态
- 后端：`backend/AgriculturalPlatform.Api`，端口 **9002**，`scripts/start-backend.ps1` 启动（`dotnet run --no-build`）
- 前端：Vite dev server 端口 **9000**（`frontend/vite.config.ts` 代理 `/api`、`/uploads` → 9002）
- 数据库：在线 MySQL（`server=116.198.221.105;port=3306;database=F8Web`），启动自动建表+种子
- 管理员：`admin / 123456`
- Git 远程：`https://github.bbitcn.net/fanhongcai/F8WebAI.git`（origin，已推送 `8099eba`、`c7a9028`）
## 三、已完成功能
- 登录认证（JWT + BCrypt）、四级组织角色与数据权限隔离
- 农户档案管理（含身份证 OCR 识别、手机传图、信用分、冻结）
- 过磅称重（一次/二次过磅、净重金额计算、触摸屏大字键盘 `/weighing/touch`、实时进行中单据）
- 电子支付（微信/支付宝/银行/现金、退款、应收汇总）
- 反向开票（自产免税 0%、一键开票、作废红冲）
- 统计报表（收购/付款/开票，按日/月/品种/农户/收购方，图表 + CSV 导出）
- 可视化大屏 `/dashboard`（KPI、趋势、占比、排行、实时过磅、30s 刷新、深色日期选择器）
- 系统管理（角色/菜单/数据字典，Logo 图标字典 `system_logo`）
- 通知公告、关于系统、个人中心
- 顶栏：动态日历（农历）、天气（IP 定位 + Open-Meteo）、商标®
## 四、已知问题 / 注意事项
1. **旧 DLL 陷阱（最重要）**：改后端代码后必须先 `dotnet build` 再启动，否则 `--no-build` 加载旧产物 → 表现为接口行为异常（曾致 `/menus/my` 401 登录失败）。详见《项目说明》§6。
2. **PowerShell 中文乱码**：命令用相对路径，git commit 用英文信息。
3. **git 自动化终端认证**：无法弹登录窗，推送需内嵌凭据 URL（见《项目说明》§7）；本机 GCM 配置名有告警（`credential-manager-core`），暂不影响已缓存凭据推送。
4. **冗余远程已清理**：`F8Web`（地址无效）、`F8WebAI`（与 origin 重复）已删除，仅留 `origin`。
5. 数据库连接串、OSS、OCR 密钥均在 `appsettings.json`（已提交远程，属私有仓库，注意勿外泄）。
## 五、待办 / 建议
- [ ] `start-backend.ps1` 建议改为"先 build 再 run"，从根上消除旧 DLL 陷阱
- [ ] 修复本机 GCM 凭据助手配置告警（`git config --global credential.helper manager`）
- [ ] 生产环境建议引入 EF Core Migration 管理表结构（当前为 EnsureCreated + SchemaMigrator 补丁）
- [ ] 大屏 / 报表如需多数据源可接入更多统计维度
项目说明
+97 -2
View File
@@ -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`。