Docs: quick-start guide, progress archive, and codebuddy gitignore
This commit is contained in:
@@ -2,61 +2,60 @@
|
||||
|
||||
基于主干信息 F8 农产品收购业务的产品化网页版（Browser/Server）平台，服务于**收购公司、收购站、收购个体**，向**农户**收购农产品，覆盖"农户管理 → 过磅称重 → 电子支付 → 反向开票 → 统计报表 → 可视化大屏"全业务链路。
|
||||
|
||||
> ⚡ **快速启动请直接阅读《项目说明》**（项目根目录），含完整启动命令、端口约定、常见坑与关键文件索引。
|
||||
|
||||
## 技术栈
|
||||
|
||||
| 端 | 技术 |
|
||||
| --- | --- |
|
||||
| 后端 | C# / .NET 10（ASP.NET Core Web API、EF Core 10、JWT、BCrypt） |
|
||||
| 数据库 | 在线 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 与触摸屏（触摸屏过磅页大按钮 + 数字键盘） |
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
backend/AgriculturalPlatform.Api/ # 后端 API
|
||||
├── Models/ # 实体模型（组织/用户/农户/品种/收购单/支付/发票）
|
||||
├── Data/ # DbContext 与种子数据
|
||||
backend/AgriculturalPlatform.Api/ # 后端 API（端口 9002）
|
||||
├── Models/ # 实体模型（组织/用户/农户/品种/收购单/支付/发票/菜单字典）
|
||||
├── Data/ # DbContext、种子数据、幂等 Schema 迁移
|
||||
├── Dtos/ # 接口传输对象
|
||||
├── Services/ # JWT、数据权限、单号生成、当前用户
|
||||
└── Controllers/ # Auth/Orgs/Users/Farmers/Products/Purchases/Payments/Invoices/Reports/Dashboard
|
||||
frontend/ # 前端
|
||||
├── Services/ # JWT、数据权限、单号生成、当前用户、OCR、OSS 存储、天气
|
||||
└── Controllers/ # Auth/Orgs/Users/Farmers/Products/Purchases/Payments/Invoices/Reports/Dashboard/Menus/Dicts/...
|
||||
frontend/ # 前端（dev server 端口 9000）
|
||||
└── src/
|
||||
├── api/ # Axios 封装与全部接口
|
||||
├── views/ # 登录、工作台、大屏、各业务模块页面
|
||||
├── layouts/ # 主布局（侧边菜单）
|
||||
├── layouts/ # 主布局（侧边菜单、顶栏日历/天气/Logo）
|
||||
├── composables/ # 共享 composable（useWeather 等）
|
||||
└── stores/ # Pinia 状态
|
||||
scripts/ # 启动/测试脚本（start-backend.ps1 等）
|
||||
docker-compose.yml # 可选：本地 MySQL 8 开发环境
|
||||
```
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 准备数据库（在线 MySQL 或本地）
|
||||
> 全部命令在**项目根目录**的 PowerShell 中执行。详见《项目说明》。
|
||||
|
||||
- **在线 MySQL**：将下方连接串改为你的在线数据库地址（首次启动会自动建库建表并写入演示数据）。
|
||||
### 后端（端口 9002）
|
||||
|
||||
### 2. 后端
|
||||
|
||||
```bash
|
||||
cd backend/AgriculturalPlatform.Api
|
||||
# 修改 appsettings.json 中 ConnectionStrings:Default 为你的 MySQL 连接串
|
||||
dotnet restore
|
||||
dotnet run
|
||||
```powershell
|
||||
dotnet build backend/AgriculturalPlatform.Api/AgriculturalPlatform.Api.csproj -c Debug
|
||||
powershell -ExecutionPolicy Bypass -File scripts/start-backend.ps1
|
||||
```
|
||||
|
||||
后端默认地址：`http://localhost:5246`（OpenAPI 文档：`http://localhost:5246/openapi/v1.json`）。
|
||||
> ⚠️ 启动脚本为 `--no-build`，**修改后端代码后必须先 build**，否则运行的是旧 DLL（曾因此导致登录权限接口 401）。
|
||||
|
||||
### 3. 前端
|
||||
### 前端（端口 9000）
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev
|
||||
```powershell
|
||||
Start-Process -FilePath "npm.cmd" -ArgumentList @("run","dev") -WorkingDirectory "frontend" -WindowStyle Hidden
|
||||
```
|
||||
|
||||
前端默认地址：`http://localhost:5173`，已配置 `/api` 代理到后端。
|
||||
浏览器访问 `http://localhost:9000`，`/api`、`/uploads` 已代理到 `http://localhost:9002`。
|
||||
|
||||
### 4. 登录
|
||||
### 登录
|
||||
|
||||
| 账号 | 密码 | 角色 |
|
||||
| --- | --- | --- |
|
||||
@@ -67,22 +66,25 @@ npm run dev
|
||||
|
||||
## 功能清单
|
||||
|
||||
- **农户管理**：农户档案（身份证/联系方式/村组/银行账户）、信用评分、冻结/启用、交易统计。
|
||||
- **过磅称重**：一次过磅（毛重）→ 二次回皮（皮重）自动计算净重与金额；支持 PC 列表操作与**触摸屏大字键盘**过磅；进行中单据实时展示。
|
||||
- **农户管理**：农户档案（身份证 OCR 识别/联系方式/村组/银行账户）、信用评分、冻结/启用、交易统计、手机传图上传。
|
||||
- **过磅称重**：一次过磅（毛重）→ 二次回皮（皮重）自动计算净重与金额；支持 PC 列表操作与**触摸屏大字键盘**过磅（`/weighing/touch`）；进行中单据实时展示；金额大额自动以万元显示。
|
||||
- **电子支付**：按收购单或批量结算，微信/支付宝/银行转账/现金四种方式，支付确认与退款，农户应收/已付/未付汇总。
|
||||
- **反向开票**：收购方向农户开具"农产品收购发票"（自产农产品免税，税率 0%），支持按已结算收购单一键开票、发票作废（红冲）。
|
||||
- **统计报表**：收购汇总（按日/月/品种/农户/收购方）、付款统计（方式/状态）、开票统计，支持图表与 CSV 导出。
|
||||
- **可视化大屏**：今日/本月 KPI、14 天趋势、品种占比、农户排行、收购方对比、实时过磅，30 秒自动刷新。
|
||||
- **统计报表**：收购汇总（按日/月/品种/农户/收购方）、付款统计（方式/状态）、开票统计，支持图表与 CSV 导出（月份分组在内存中排序，避免 SQLite/MySQL 字符串排序问题）。
|
||||
- **可视化大屏**：今日/本月 KPI、14 天趋势、品种占比、农户排行、收购方对比、实时过磅，30 秒自动刷新；日期区间选择器深色主题。
|
||||
- **组织与用户**：公司 / 收购站 / 收购个体三级组织；四类角色；**数据权限隔离**（公司只看本公司及旗下站点数据）。
|
||||
- **系统管理**：角色权限、菜单管理、数据字典（含系统 Logo 图标 `system_logo` 配置）。
|
||||
- **通知公告**：站内公告发布与列表；**关于系统** 页面。
|
||||
- **顶栏**：动态日历（农历/节气）、天气（IP 定位 + Open-Meteo，全局共享 composable）、Logo 图标按字典配置。
|
||||
|
||||
## 数据库配置说明
|
||||
|
||||
后端启动时会执行 `EnsureCreated + Seed`：数据库不存在则自动建表，空库自动写入演示数据（组织、账号、品种、农户及近 30 天收购/付款/发票历史）。
|
||||
|
||||
生产建议改用 EF Core Migration 管理表结构。
|
||||
在线 MySQL 连接串见 `backend/AgriculturalPlatform.Api/appsettings.json` 的 `ConnectionStrings:Default`。后端启动时执行 `EnsureCreated + Seed + SchemaMigrator`：数据库不存在则自动建表，空库自动写入演示数据（组织、账号、品种、农户及近 30 天收购/付款/发票历史），迁移补丁幂等可重复执行。
|
||||
|
||||
## 常见问题
|
||||
|
||||
- **后端启动报数据库连接失败**：检查 `appsettings.json` 的 `ConnectionStrings:Default`，MySQL 需允许远程连接（主机防火墙/云数据库白名单放行）。
|
||||
- **前端接口 401**：登录过期，重新登录即可。
|
||||
- **想换端口**：后端在 `Properties/launchSettings.json` 修改后，同步修改 `frontend/vite.config.ts` 的代理 target 与后端 `appsettings.json` 的 `FrontendUrl`。
|
||||
- **登录后立刻被弹回登录页**：多为 `/api/menus/my` 返回 401。若后端代码有改动而**未重新编译**，会命中旧 DLL 问题——执行 `dotnet build` 后重启后端。
|
||||
- **想换端口**：后端 `Properties/launchSettings.json`、`appsettings.json` 的 `Server:LanPort` 与前端 `vite.config.ts` 的 proxy target 需同步修改。
|
||||
- **PowerShell 中文路径乱码 / git commit 中文报错**：使用相对路径、英文提交信息。
|
||||
- **git 推送要认证**：远程 `https://github.bbitcn.net/fanhongcai/F8WebAI.git`，自动化终端用内嵌凭据 URL 推送（见《项目说明》）。
|
||||
|
||||
Reference in New Issue
Block a user