antissoft / lvqianmeiye_ERP

  # 绿纤美业 ERP

  > 面向绿纤美业的企业资源规划系统，前后端分离，覆盖门店管理、业绩统计、工资核算、报表分析与客户管理等核心业务。

  **状态**：生产环境运行中 · **版本**：v2.5.0 · **更新**：2025年1月

  ---

  ## 功能概览

  | 模块         | 说明 |
  |--------------|------|
  | **业绩统计** | 个人 / 门店总 / 金三角 / 部门消耗 / 科技部 / 门店消耗业绩统计 |
  | **工资核算** | 健康师、店长、主任、大项目主管、科技部总经理、事业部总经理工资计算 |
  | **报表分析** | 门店/健康师/金三角业绩趋势、排行榜、综合仪表盘 |
  | **门店管理** | 门店信息、归属管理、新店保护、股份统计 |
  | **人员管理** | 金三角设定与用户绑定、顾问身份管理 |
  | **客户管理** | 客户档案、拓客记录与活动、会员权益、用户画像 |
  | **其他**      | 合同、合作成本、店内支出、库存使用审批、年度汇总 |

  ---

  ## 技术栈

  | 端     | 技术 |
  |--------|------|
  | **后端** | .NET Core 3.1/5.0 · SqlSugar · MySQL · JWT · Serilog · Swagger |

  | **管理后台** | Vue 2.6 · Element UI · Vuex · Vue Router · Axios · SCSS · ECharts（antis-ncc-admin） |
  | **门店 PC 端** | Vue 2.6 · Element UI · Vuex · Vue Router · Axios（store-pc，门店侧使用） |

  | **移动端** | uni-app（支持微信小程序） |

  ---

  ## 项目结构

  ```
  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/

  ├── store-pc/                   # 门店 PC 端（Vue，门店侧使用，见 store-pc/README.md）

  ├── 绿纤uni-app/                # 移动端
  ├── docs/                       # 项目文档（数据库说明、工资规则、接口文档等）
  ├── scripts/                    # Shell 测试脚本、Python 工具脚本
  ├── sql/                        # 表结构、初始化、迁移、统计等 SQL
  ├── excel/                      # Excel 模板
  └── PROJECT_RULES.md            # 开发规范（必读）
  ```

  **说明**：**store-pc** 为门店的 PC 端应用，供门店侧使用；**antis-ncc-admin** 为管理后台，供运营/总部使用。二者为不同前端工程。
  

  ---

  ## 快速开始

  ### 环境要求

  - **Node.js**：16.20.2（必须，其他版本可能不兼容）
  - **.NET Core SDK**：3.1 或 5.0
  - **MySQL**：5.7 或 8.0
  - **IDE**：Visual Studio 2019/2022 或 VS Code

  ### 克隆与启动

  ```bash
  git clone [项目地址]
  cd lvqianmeiye_ERP
  ```
  

  **后端**

  ```bash
  cd netcore/src/Application/NCC.API
  dotnet restore
  dotnet run
  ```
  

  或使用 Visual Studio：打开 `netcore/smart.agriculture.platform.NET.sln`，将 `NCC.API` 设为启动项目，F5 运行。
  

  **前端（管理后台）**

  
  ```bash
  cd antis-ncc-admin

  npm install

  npm run dev
  ```
  

  **门店 PC 端（store-pc）**
  
  ```bash
  cd store-pc
  npm install
  npm run dev
  ```
  
  默认端口：管理后台 3000，门店 PC 端 3100。详见各目录下 README。
  

  ### 访问与默认账号

  | 项     | 地址/信息 |
  |--------|-----------|

  | 管理后台 | http://localhost:3000 |
  | 门店 PC 端 | http://localhost:3100（store-pc） |

  | 后端 API | http://localhost:5000 |
  | API 文档 | http://localhost:5000/antis.doc |
  | 默认账号 | admin / 123456 |

  ---

  ## 配置

  **数据库**：修改 `netcore/src/Application/NCC.API/appsettings.json` 中的 `ConnectionStrings.DefaultConnection`：

  
  ```json

  "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`）。

  ---

  ## 文档与脚本

  - **文档**：`docs/` 目录  
    - `数据库说明.md`：表结构、字段、关联与弃用表说明  
    - `工资计算规则梳理.md`：各类工资计算规则  
    - `接口文档.md`：API 说明  

  - **脚本**：`scripts/sh/`（接口测试、数据验证）、`scripts/py/`（导出、生成等）。Shell 脚本需执行权限：`chmod +x scripts/sh/*.sh`。

  - **SQL**：`sql/` 内存放表结构、初始化、迁移及统计相关脚本。

  ---

  ## 核心业务模块（Extend）

  业务逻辑集中在 `netcore/src/Modularity/Extend/`，服务通过动态 API 暴露为 `api/Extend/[ServiceName]`。

  | 业务       | 主要服务类 |
  |------------|------------|
  | 业绩统计   | `LqStatisticsService`、`LqReportService` |
  | 工资核算   | `LqGzService`、`LqStoreManagerSalaryService`、`LqDirectorSalaryService`、`LqMajorProjectDirectorSalaryService`、`LqTechGeneralManagerSalaryService`、`LqBusinessUnitManagerSalaryService` |
  | 门店管理   | `LqMdxxService`、`LqMdXdbhsjService` |
  | 人员/金三角 | `LqYcsdJsjService`、金三角用户绑定相关服务 |
  | 客户管理   | `LqKhxxService`、`LqTkjlbService`、`LqEventService` |
  | 工具       | `EmailService`、`DocumentService`、`BigDataService`、`WorkLogService` |

  实体与 DTO 在 `NCC.Extend.Entitys`（Entity、Dto、Mapper、Model）。

  ---

  ## 开发规范

  完整规范见 **[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。
  - **数据**：统计与列表使用相同筛选条件；涉及人员/门店归属等见「已弃用表」说明，使用约定表与字段。

  ---

  ## 部署

  - **后端**：`dotnet publish -c Release`，配置生产环境连接字符串，部署至 IIS 或 Linux。
  - **前端**：`npm run build`，将 `antis-ncc-admin/dist` 部署至 Web 服务器，并配置反向代理（如 Nginx）指向后端 API。

  ---

  ## 常见问题

  | 问题               | 处理建议 |
  |--------------------|----------|
  | 前端启动失败       | 确认 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`，或联系开发团队。