# 绿纤美业 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`，或联系开发团队。