From ba386929de370339c97ad794d424718aeca175d0 Mon Sep 17 00:00:00 2001 From: “wangming” <“wangming@antissoft.com”> Date: Tue, 10 Feb 2026 13:54:52 +0800 Subject: [PATCH] docs: update README.md for project overview and structure --- README.md | 479 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- netcore/src/Modularity/Extend/NCC.Extend/LqDailyReportService.cs | 4 ++-- 2 files changed, 116 insertions(+), 367 deletions(-) diff --git a/README.md b/README.md index 739ffcd..fea5925 100644 --- a/README.md +++ b/README.md @@ -1,432 +1,181 @@ -# 绿纤美业ERP管理系统 - -## 📋 项目简介 - -绿纤美业ERP管理系统是一个基于现代化技术栈开发的企业资源规划系统，专为绿纤美业行业量身定制。系统采用前后端分离架构，提供完整的门店管理、业绩统计、工资核算、报表分析、客户管理等业务管理功能。 - -**项目状态**：✅ 生产环境运行中 | 📅 最后更新：2025年1月 - -## 🎯 核心功能模块 - -### 📊 业绩统计系统 -- **个人业绩统计** - 健康师个人业绩统计，包含首单业绩、升单业绩等 -- **门店总业绩统计** - 门店整体业绩统计，包含总业绩、欠款金额等 -- **金三角业绩统计** - 金三角团队业绩统计和分析 -- **部门消耗业绩统计** - 部门消耗业绩统计，包含人头数、人次等 -- **科技部业绩统计** - 科技部老师业绩统计 -- **门店消耗业绩统计** - 门店消耗业绩统计 - -### 💰 工资核算系统 -- **健康师工资核算** - 健康师底薪、提成、奖励等自动计算 -- **店长工资核算** - 店长工资计算，包含底薪、提成、奖励等 -- **主任工资核算** - 主任工资计算，包含底薪、提成、奖励等 -- **大项目主管工资核算** - 大项目主管工资计算 -- **科技部总经理工资核算** - 科技部总经理工资计算 -- **事业部总经理工资核算** - 事业部总经理工资计算 - -### 📈 报表分析系统 -- **门店业绩趋势** - 门店业绩时间趋势分析 -- **门店业绩排行榜** - 门店业绩排名统计 -- **健康师业绩趋势** - 健康师个人业绩趋势 -- **健康师业绩排行榜** - 健康师业绩排名统计 -- **金三角业绩趋势** - 金三角团队业绩趋势 -- **综合仪表盘** - 多维度数据汇总展示 - -### 🏪 门店管理系统 -- **门店信息管理** - 门店基础信息维护 -- **门店归属管理** - 门店归属事业部、教育部、科技部等 -- **新店保护时间** - 新店保护期管理 -- **门店股份统计** - 门店股份统计和分析 - -### 👥 人员管理系统 -- **金三角设定** - 金三角团队配置管理 -- **金三角用户绑定** - 用户与金三角团队绑定关系 -- **顾问身份管理** - 根据金三角绑定自动设置顾问身份 - -### 📋 客户管理系统 -- **客户信息管理** - 客户档案管理 -- **拓客记录管理** - 拓客活动记录 -- **拓客活动管理** - 拓客活动配置 -- **会员权益管理** - 历史会员权益数据管理 -- **用户画像** - 会员画像数据分析和展示 - -### 🔧 其他业务模块 -- **合同管理系统** - 合同信息管理 -- **合作成本管理** - 合作成本表管理 -- **店内支出管理** - 店内支出表管理 -- **库存使用审批** - 库存使用审批流程 -- **年度汇总统计** - 年度经营统计分析 - -## 🛠 技术栈 - -### 后端技术 -- **.NET Core 3.1/5.0** - 跨平台Web框架 -- **SqlSugar** - 轻量级ORM框架 -- **MySQL** - 关系型数据库 -- **JWT** - 身份认证 -- **Serilog** - 结构化日志 -- **Swagger** - API文档 - -### 前端技术 -- **Vue 2.6** - 渐进式JavaScript框架 -- **Element UI** - 企业级UI组件库 -- **Vuex** - 状态管理 -- **Vue Router** - 路由管理 -- **Axios** - HTTP客户端 -- **SCSS** - CSS预处理器 -- **ECharts** - 数据可视化图表库 - -### 移动端 -- **uni-app** - 跨平台移动应用框架 -- **微信小程序** - 支持微信小程序平台 - -## 📁 项目结构 +# 绿纤美业 ERP -``` -lvqianmeiye_ERP/ -├── netcore/ # 后端.NET Core项目 -│ └── src/ -│ ├── Application/ # 应用层 -│ ├── Infrastructure/ # 基础设施层 -│ └── Modularity/ # 业务模块层 -│ ├── System/ # 系统管理模块 -│ ├── Extend/ # 🎯 核心业务模块（绿纤ERP业务逻辑） -│ │ ├── NCC.Extend/ # 业务服务层 -│ │ ├── NCC.Extend.Entitys/ # 实体模型层 -│ │ └── NCC.Extend.Interfaces/ # 接口定义层 -│ ├── OAuth/ # 身份认证模块 -│ ├── Message/ # 消息中心模块 -│ ├── Order/ # 订单管理模块 -│ ├── VisualDev/ # 可视化开发模块 -│ └── Tenant/ # 多租户支持模块 -├── antis-ncc-admin/ # 前端Vue管理后台 -│ ├── src/ -│ │ ├── api/ # API接口 -│ │ ├── components/ # 公共组件 -│ │ ├── views/ # 页面视图 -│ │ │ ├── salaryStatistics/ # 工资统计页面 -│ │ │ ├── personalPerformanceStatistics/ # 个人业绩统计 -│ │ │ ├── storeTotalPerformanceStatistics/ # 门店总业绩统计 -│ │ │ ├── departmentConsumePerformanceStatistics/ # 部门消耗业绩统计 -│ │ │ ├── techPerformanceStatistics/ # 科技部业绩统计 -│ │ │ ├── storeConsumePerformanceStatistics/ # 门店消耗业绩统计 -│ │ │ ├── report/ # 报表分析页面 -│ │ │ └── extend/ # 其他业务页面 -│ │ ├── router/ # 路由配置 -│ │ └── store/ # 状态管理 -│ ├── package.json # 前端依赖配置 -│ └── vue.config.js # Vue构建配置 -├── 绿纤uni-app/ # 移动端uni-app项目 -│ ├── pages/ # 页面文件 -│ ├── components/ # 组件 -│ ├── apis/ # API接口 -│ └── service/ # 服务层 -├── 绿纤html/ # 静态HTML页面 -│ ├── appointment.html # 预约页面 -│ ├── expansion.html # 拓客页面 -│ ├── member-consume.html # 会员消耗页面 -│ └── ... # 其他页面 -├── docs/ # 📚 项目文档 -│ ├── 数据库说明.md # 数据库文档 -│ ├── 工资计算规则梳理.md # 工资计算规则文档 -│ ├── 接口文档.md # API接口文档 -│ └── ... # 其他需求文档 -├── scripts/ # 🔧 脚本工具 -│ ├── sh/ # Shell测试脚本 -│ │ ├── test_*.sh # 接口测试脚本 -│ │ └── verify_*.sh # 数据验证脚本 -│ └── py/ # Python工具脚本 -│ ├── export_*.py # 数据导出脚本 -│ └── generate_*.py # 数据生成脚本 -├── sql/ # 📊 SQL脚本 -│ ├── 表结构.sql # 数据库表结构 -│ ├── 初始化数据.sql # 初始化数据脚本 -│ └── ... # 其他SQL脚本 -├── excel/ # 📄 Excel模板文件 -│ ├── 健康师额外数据模板.xlsx -│ ├── 合作成本表.xlsx -│ └── ... # 其他模板文件 -├── ExportFiles/ # 📤 导出文件目录 -├── PROJECT_RULES.md # 项目开发规范 -└── README.md # 项目说明文档 -``` +> 面向绿纤美业的企业资源规划系统，前后端分离，覆盖门店管理、业绩统计、工资核算、报表分析与客户管理等核心业务。 -## 🎯 核心业务模块说明 +**状态**：生产环境运行中 · **版本**：v2.5.0 · **更新**：2025年1月 -**Extend模块**是系统的核心业务模块，包含绿纤ERP的所有业务逻辑。该模块采用三层架构设计： +--- -### NCC.Extend（业务服务层） +## 功能概览 -#### 📊 业绩统计类 -- `LqStatisticsService` - 核心统计服务（个人业绩、门店业绩、金三角业绩等） -- `LqReportService` - 报表分析服务（趋势图、排行榜、仪表盘） +| 模块 | 说明 | +|--------------|------| +| **业绩统计** | 个人 / 门店总 / 金三角 / 部门消耗 / 科技部 / 门店消耗业绩统计 | +| **工资核算** | 健康师、店长、主任、大项目主管、科技部总经理、事业部总经理工资计算 | +| **报表分析** | 门店/健康师/金三角业绩趋势、排行榜、综合仪表盘 | +| **门店管理** | 门店信息、归属管理、新店保护、股份统计 | +| **人员管理** | 金三角设定与用户绑定、顾问身份管理 | +| **客户管理** | 客户档案、拓客记录与活动、会员权益、用户画像 | +| **其他** | 合同、合作成本、店内支出、库存使用审批、年度汇总 | -#### 💰 工资核算类 -- `LqGzService` - 健康师工资核算服务 -- `LqStoreManagerSalaryService` - 店长工资核算服务 -- `LqDirectorSalaryService` - 主任工资核算服务 -- `LqMajorProjectDirectorSalaryService` - 大项目主管工资核算服务 -- `LqTechGeneralManagerSalaryService` - 科技部总经理工资核算服务 -- `LqBusinessUnitManagerSalaryService` - 事业部总经理工资核算服务 +--- -#### 🏪 门店管理类 -- `LqMdxxService` - 门店信息管理服务 -- `LqMdXdbhsjService` - 门店新店保护时间管理 +## 技术栈 -#### 👥 人员管理类 -- `LqYcsdJsjService` - 金三角设定管理服务 -- `LqJinsanjiaoUserService` - 金三角用户绑定管理 +| 端 | 技术 | +|--------|------| +| **后端** | .NET Core 3.1/5.0 · SqlSugar · MySQL · JWT · Serilog · Swagger | +| **前端** | Vue 2.6 · Element UI · Vuex · Vue Router · Axios · SCSS · ECharts | +| **移动端** | uni-app（支持微信小程序） | -#### 📋 客户管理类 -- `LqKhxxService` - 客户信息管理服务 -- `LqTkjlbService` - 拓客记录管理服务 -- `LqEventService` - 拓客活动管理服务 +--- -#### 🔧 系统工具类 -- `EmailService` - 邮件服务 -- `DocumentService` - 文档管理服务 -- `BigDataService` - 大数据分析服务 -- `WorkLogService` - 工作日志服务 +## 项目结构 -### NCC.Extend.Entitys（实体模型层） -- **Entity/** - 数据库实体模型 -- **Dto/** - 数据传输对象 -- **Mapper/** - 对象映射配置 -- **Model/** - 业务模型类 +``` +lvqianmeiye_ERP/ +├── netcore/ # 后端 +│ └── src/ +│ ├── Application/ # 应用入口（NCC.API） +│ ├── Infrastructure/ # 基础设施（SqlSugar、JWT、日志等） +│ └── Modularity/ +│ ├── Extend/ # 绿纤 ERP 核心业务（NCC.Extend / Entitys / Interfaces） +│ ├── System/ # 系统管理 +│ ├── OAuth/ # 认证 +│ └── ... +├── antis-ncc-admin/ # 前端管理后台（Vue） +│ └── src/ +│ ├── api/ # 接口封装 +│ ├── views/ # 页面（业绩、工资、报表、门店、客户等） +│ ├── components/ # 公共组件 +│ └── router/、store/ +├── 绿纤uni-app/ # 移动端 +├── docs/ # 项目文档（数据库说明、工资规则、接口文档等） +├── scripts/ # Shell 测试脚本、Python 工具脚本 +├── sql/ # 表结构、初始化、迁移、统计等 SQL +├── excel/ # Excel 模板 +└── PROJECT_RULES.md # 开发规范（必读） +``` -## 🚀 快速开始 +--- -### 环境要求 +## 快速开始 -#### 开发环境 -- **Node.js**: 16.20.2 (⚠️ 必须使用此版本，其他版本可能不兼容) -- **.NET Core SDK**: 3.1 或 5.0 -- **MySQL**: 5.7 或 8.0 -- **Visual Studio 2019/2022** 或 **VS Code** +### 环境要求 -#### 浏览器支持 -- Chrome 70+ -- Firefox 65+ -- Safari 12+ -- Edge 79+ +- **Node.js**：16.20.2（必须，其他版本可能不兼容） +- **.NET Core SDK**：3.1 或 5.0 +- **MySQL**：5.7 或 8.0 +- **IDE**：Visual Studio 2019/2022 或 VS Code -### 1. 克隆项目 +### 克隆与启动 ```bash git clone [项目地址] cd lvqianmeiye_ERP ``` -### 2. 后端启动 - -#### 方式一：Visual Studio -1. 打开 `netcore/smart.agriculture.platform.NET.sln` -2. 设置 `NCC.API` 为启动项目 -3. 按 F5 运行 +**后端** -#### 方式二：命令行 ```bash cd netcore/src/Application/NCC.API dotnet restore dotnet run ``` -### 3. 前端启动 +或使用 Visual Studio：打开 `netcore/smart.agriculture.platform.NET.sln`，将 `NCC.API` 设为启动项目，F5 运行。 + +**前端** ```bash cd antis-ncc-admin - -# 安装依赖 npm install - -# 启动开发服务器 npm run dev ``` -### 4. 访问系统 -- 前端地址：http://localhost:3000 -- 后端API：http://localhost:5000 -- API文档：http://localhost:5000/antis.doc +### 访问与默认账号 -### 默认账号 -- **管理员账号**：admin -- **默认密码**：123456 - -## 📚 项目文档 - -项目文档统一存放在 `docs/` 目录下，包含： - -### 核心文档 -- **数据库说明.md** - 数据库表结构、字段说明、关联关系 -- **PROJECT_RULES.md** - 项目开发规范、编码规范、最佳实践 - -### 业务文档 -- **工资计算规则梳理.md** - 各类工资计算规则说明 - - 健康师工资计算规则 - - 店长工资计算规则 - - 主任工资计算规则 - - 大项目主管工资计算规则 - - 科技部总经理工资计算规则 - - 事业部总经理工资计算规则 -- **接口文档.md** - API接口调用说明 -- **需求分析文档** - 各类业务需求分析文档 - -### 查看文档 -```bash -# 查看所有文档 -ls docs/ +| 项 | 地址/信息 | +|--------|-----------| +| 前端 | http://localhost:3000 | +| 后端 API | http://localhost:5000 | +| API 文档 | http://localhost:5000/antis.doc | +| 默认账号 | admin / 123456 | -# 查看特定文档 -cat docs/数据库说明.md -``` - -## 🔧 脚本工具 - -项目提供了丰富的脚本工具，位于 `scripts/` 目录下： - -### Shell测试脚本 (`scripts/sh/`) -用于接口测试和数据验证： -```bash -# 测试个人业绩统计接口 -./scripts/sh/test_personal_performance_api.sh - -# 测试门店总业绩统计接口 -./scripts/sh/test_store_total_performance_statistics.sh - -# 验证门店总业绩数据 -./scripts/sh/verify_store_total_performance_data.sh -``` - -### Python工具脚本 (`scripts/py/`) -用于数据导出和生成： -```bash -# 导出所有会员剩余权益数据 -python scripts/py/export_all_member_remaining_rights.py - -# 生成客户Excel数据 -python scripts/py/generate_november_customer_excel.py -``` - -## 📊 SQL脚本 - -数据库相关SQL脚本存放在 `sql/` 目录下： - -- **表结构脚本** - 数据库表结构定义 -- **初始化数据脚本** - 系统初始化数据 -- **数据迁移脚本** - 数据库版本升级脚本 -- **统计脚本** - 统计数据生成脚本 +--- -## ⚙️ 配置说明 +## 配置 -### 数据库配置 -修改 `netcore/src/Application/NCC.API/appsettings.json` 中的连接字符串： +**数据库**：修改 `netcore/src/Application/NCC.API/appsettings.json` 中的 `ConnectionStrings.DefaultConnection`： ```json -{ - "ConnectionStrings": { - "DefaultConnection": "Database=lqerp;Data Source=localhost;Port=3306;User Id=root;Password=yourpassword;Charset=utf8;" - } -} -``` - -### 前端代理配置 -修改 `antis-ncc-admin/vue.config.js` 中的代理地址： - -```javascript -proxy: { - '/dev': { - target: 'http://localhost:5000', // 后端API地址 - changeOrigin: true, - pathRewrite: { - '^/dev': '' - } - } -} +"DefaultConnection": "Database=lqerp;Data Source=localhost;Port=3306;User Id=root;Password=你的密码;Charset=utf8;" ``` -## 📦 部署说明 +**前端代理**：修改 `antis-ncc-admin/vue.config.js` 中 `proxy['/dev'].target` 为实际后端地址（默认 `http://localhost:5000`）。 -### 后端部署 -1. 发布项目：`dotnet publish -c Release` -2. 配置数据库连接字符串 -3. 部署到IIS或Linux服务器 +--- -### 前端部署 -1. 构建项目：`npm run build` -2. 将 `dist` 目录部署到Web服务器 -3. 配置Nginx或IIS反向代理 +## 文档与脚本 -## 📋 开发规范 +- **文档**：`docs/` 目录 + - `数据库说明.md`：表结构、字段、关联与弃用表说明 + - `工资计算规则梳理.md`：各类工资计算规则 + - `接口文档.md`：API 说明 -详细的开发规范请参考 [PROJECT_RULES.md](./PROJECT_RULES.md)，主要规范包括： +- **脚本**：`scripts/sh/`（接口测试、数据验证）、`scripts/py/`（导出、生成等）。Shell 脚本需执行权限：`chmod +x scripts/sh/*.sh`。 -### 核心规范 -- **ID生成规范**: 必须使用 `YitIdHelper.NextId().ToString()` 生成ID -- **API接口规范**: GET请求使用data字段传参，不使用params -- **权限控制**: 所有数据查询必须添加园区权限过滤 -- **数据一致性**: 统计数据和列表数据必须使用相同的过滤条件 -- **SQL查询验证**: 统计类型SQL查询必须先使用MCP MySQL工具验证 +- **SQL**：`sql/` 内存放表结构、初始化、迁移及统计相关脚本。 -### 前端规范 -- **组件开发**: views 与 components 分离，弹窗、二级页面必须单独创建 Vue 文件 -- **文件命名**: 使用 kebab-case (如: user-dialog.vue) -- **UI规范**: 统一使用 NCC-table，标签右对齐，卡片高度100px，内边距12px，圆角12px +--- -### 后端规范 -- **分层架构**: Entitys → Interfaces → Services -- **异常处理**: 全局捕获，统一 JSON 格式返回 -- **XML注释**: 关键方法必须添加 XML 注释 +## 核心业务模块（Extend） -## ❓ 常见问题 +业务逻辑集中在 `netcore/src/Modularity/Extend/`，服务通过动态 API 暴露为 `api/Extend/[ServiceName]`。 -### Q: 前端启动失败 -**A**: 确保使用Node.js 16.20.2版本，其他版本可能不兼容 +| 业务 | 主要服务类 | +|------------|------------| +| 业绩统计 | `LqStatisticsService`、`LqReportService` | +| 工资核算 | `LqGzService`、`LqStoreManagerSalaryService`、`LqDirectorSalaryService`、`LqMajorProjectDirectorSalaryService`、`LqTechGeneralManagerSalaryService`、`LqBusinessUnitManagerSalaryService` | +| 门店管理 | `LqMdxxService`、`LqMdXdbhsjService` | +| 人员/金三角 | `LqYcsdJsjService`、金三角用户绑定相关服务 | +| 客户管理 | `LqKhxxService`、`LqTkjlbService`、`LqEventService` | +| 工具 | `EmailService`、`DocumentService`、`BigDataService`、`WorkLogService` | -### Q: 后端连接数据库失败 -**A**: 检查数据库连接字符串和MySQL服务状态 +实体与 DTO 在 `NCC.Extend.Entitys`（Entity、Dto、Mapper、Model）。 -### Q: 权限验证失败 -**A**: 检查JWT配置和Token有效期设置 +--- -### Q: 统计SQL执行失败 -**A**: 使用MCP MySQL工具先验证SQL语法和字段名是否正确 +## 开发规范 -### Q: 接口测试脚本无法运行 -**A**: 确保脚本有执行权限：`chmod +x scripts/sh/*.sh` +完整规范见 **[PROJECT_RULES.md](./PROJECT_RULES.md)**（或仓库内 `.cursor/rules/project_rules.mdc`），开发前请阅读。要点包括： -## 📈 项目状态 +- **后端**：ID 使用 `YitIdHelper.NextId().ToString()`；分层 Entitys → Interfaces → Services；关键方法写 XML 注释；统一异常与返回格式。 +- **前端**：GET 请求用 `data` 传参；表格用 NCC-table；弹窗/二级页单独组件；文件命名 kebab-case。 +- **数据**：统计与列表使用相同筛选条件；涉及人员/门店归属等见「已弃用表」说明，使用约定表与字段。 -### ✅ 已完成功能 -- [x] 业绩统计系统（个人、门店、金三角、部门消耗、科技部、门店消耗） -- [x] 工资核算系统（健康师、店长、主任、大项目主管、科技部总经理、事业部总经理） -- [x] 报表分析系统（趋势图、排行榜、仪表盘） -- [x] 门店管理系统（门店信息、归属管理、新店保护） -- [x] 客户管理系统（客户信息、拓客记录、会员权益） -- [x] 合同管理系统 -- [x] 合作成本和店内支出管理 -- [x] 库存使用审批流程 -- [x] 年度汇总统计 +--- -### 🔄 持续优化 -- 性能优化 -- 代码重构 -- 文档完善 -- 测试覆盖 +## 部署 -## 📞 技术支持 +- **后端**：`dotnet publish -c Release`，配置生产环境连接字符串，部署至 IIS 或 Linux。 +- **前端**：`npm run build`，将 `antis-ncc-admin/dist` 部署至 Web 服务器，并配置反向代理（如 Nginx）指向后端 API。 -如有技术问题，请： -1. 查看项目文档：`docs/` 目录 -2. 查看开发规范：`PROJECT_RULES.md` -3. 联系开发团队 +--- -## 📝 版本信息 +## 常见问题 -- **当前版本**：v2.5.0 -- **最后更新**：2025年1月 -- **维护状态**：✅ 生产环境运行中 -- **主要特性**：完整的业绩统计、工资核算、报表分析等核心功能 +| 问题 | 处理建议 | +|--------------------|----------| +| 前端启动失败 | 确认 Node.js 为 16.20.2（`nvm use 16.20.2` 或安装该版本）。 | +| 后端连不上数据库 | 检查 `appsettings.json` 连接字符串及 MySQL 服务是否启动。 | +| 权限/Token 报错 | 检查 JWT 配置与 Token 有效期。 | +| 统计类 SQL 报错 | 先用 MCP MySQL 工具验证 SQL 语法与表名字段名。 | +| 脚本无法执行 | 执行 `chmod +x scripts/sh/*.sh`。 | --- -**注意**：本项目仅供学习和内部使用，请勿用于商业用途。 +## 许可证与说明 + +本项目仅供学习与内部使用，请勿用于商业用途。 +技术问题可先查阅 `docs/` 与 `PROJECT_RULES.md`，或联系开发团队。 diff --git a/netcore/src/Modularity/Extend/NCC.Extend/LqDailyReportService.cs b/netcore/src/Modularity/Extend/NCC.Extend/LqDailyReportService.cs index 39ee3c8..6022566 100644 --- a/netcore/src/Modularity/Extend/NCC.Extend/LqDailyReportService.cs +++ b/netcore/src/Modularity/Extend/NCC.Extend/LqDailyReportService.cs @@ -1538,8 +1538,8 @@ namespace NCC.Extend // 3. 查询指定日期的有效开单记录（有金额的） // 使用 lq_md_target 表获取门店归属，替代已弃用的 lq_mdxx.syb 字段 var billingQuery = _db.Queryable( - (billing, target, store, org) => - billing.Djmd == target.StoreId + (billing, target, store, org) => + billing.Djmd == target.StoreId && target.Month == month && target.BusinessUnit == org.Id && billing.Djmd == store.Id) -- libgit2 0.21.4