From 5b7707aa3d429dbaceb5294409fcd00c0c66bb5f Mon Sep 17 00:00:00 2001 From: fanhongcai Date: Sun, 23 Aug 2026 11:06:51 +0800 Subject: [PATCH] Docs: quick-start guide, progress archive, and codebuddy gitignore --- .gitignore | 3 ++ README.md | 70 +++++++++++++++++----------------- 开发进度存档.md | 46 +++++++++++++++++++++++ 项目说明 | 99 ++++++++++++++++++++++++++++++++++++++++++++++++- 4 files changed, 182 insertions(+), 36 deletions(-) create mode 100644 开发进度存档.md diff --git a/.gitignore b/.gitignore index 71e30a4..952ceb1 100644 --- a/.gitignore +++ b/.gitignore @@ -37,3 +37,6 @@ build-check/ generated-images/ test.png test-avatar.png + +# CodeBuddy 项目数据（memory/automations 等，含敏感信息） +.codebuddy/ diff --git a/README.md b/README.md index 2af79ea..44a1a6b 100644 --- a/README.md +++ b/README.md @@ -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 推送（见《项目说明》）。 diff --git a/开发进度存档.md b/开发进度存档.md new file mode 100644 index 0000000..b8aa07a --- /dev/null +++ b/开发进度存档.md @@ -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 补丁） +- [ ] 大屏 / 报表如需多数据源可接入更多统计维度 diff --git a/项目说明 b/项目说明 index ede9d2d..ac6bf79 100644 --- a/项目说明 +++ b/项目说明 @@ -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 -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`。