# SPC

**Repository Path**: jamesbluegun/spc

## Basic Information

- **Project Name**: SPC
- **Description**: SPC是一个专注于软件性能优化的开源团队，致力于开发高效、稳定的代码优化工具和解决方案，帮助开发者提升应用性能。
- **Primary Language**: Java
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-01-07
- **Last Updated**: 2026-01-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 亨通数科SPC系统 (Statistical Process Control System)

<div align="center">

![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)
![Spring Boot](https://img.shields.io/badge/Spring%20Boot-2.4.3-brightgreen.svg)
![Spring Cloud](https://img.shields.io/badge/Spring%20Cloud-2021.0.x-green.svg)
![License](https://img.shields.io/badge/license-Proprietary-red.svg)

**智能质量管理平台 | 实时过程控制 | 预防性质量管理**

[功能特性](#功能特性) • [快速开始](#快速开始) • [技术架构](#技术架构) • [API文档](#api文档) • [部署指南](#部署指南)

</div>

---

## 📖 项目简介

亨通数科SPC系统（Statistical Process Control System）是一个基于Spring Cloud微服务架构的智能质量管理平台。系统通过集成IOT设备和MES系统的实时数据采集，运用统计过程控制方法自动生成多种控制图（X-R图、P图、C图等），实时监控生产过程的质量稳定性，并通过WebSocket推送、邮件和短信等多渠道告警机制，帮助企业及时发现和预防质量异常，实现从被动质量检验到主动过程控制的转变。

### 核心价值

- 🎯 **预防性控制**: 从事后检验转向事前预防，降低不良品率
- 📊 **实时监控**: 7x24小时实时监控生产过程质量状态
- 🔔 **智能告警**: 多渠道告警机制，第一时间发现质量异常
- 📈 **数据驱动**: 基于统计分析的科学决策支持
- 🔗 **系统集成**: 无缝对接IOT、MES等企业系统
- 📱 **移动友好**: 支持移动端访问和实时推送

---

## ✨ 功能特性

### 1. 外部数据接入 🔌

- **多源数据采集**: 支持IOT设备、MES系统等多种数据源
- **RESTful API**: 标准化的数据提交接口
- **批量处理**: 单次最多支持1000条数据提交
- **API认证**: 基于API Key的安全认证机制
- **QPS限流**: 默认100次/秒，防止系统过载

### 2. 绑定关系配置 🔗

- **灵活映射**: 外部方案/检测项与本地方案/检测项的灵活绑定
- **唯一性校验**: 
  - 本地路径唯一性 - 一个本地检测项只能配置一次
  - 外部配置唯一性 - 一个外部数据源只能配置一次
- **级联查询**: 支持多条件查询和关联数据查询
- **批量操作**: 支持批量创建、更新、删除配置

### 3. 自动化数据消费 ⚙️

- **独立定时任务**: 每个绑定配置创建独立的数据消费任务
- **可配置间隔**: 默认60秒，可根据业务需求调整
- **状态管理**: 支持启动、停止、暂停消费任务
- **错误处理**: 完善的异常处理和日志记录机制
- **消费追踪**: 记录消费时间和消费状态

### 4. 统计过程控制 📊

- **多种控制图**: 
  - 计量型: X-R图、X-S图、X-MR图
  - 计数型: P图、NP图、C图、U图
- **过程能力分析**: 自动计算Cp、Cpk、Pp、Ppk指标
- **控制限计算**: 自动计算UCL、LCL、CL
- **异常判定**: 基于8大判异准则的自动判定
- **趋势分析**: 识别过程趋势和周期性变化

### 5. 实时监控与告警 🔔

- **WebSocket推送**: 实时推送质量数据更新
- **多渠道告警**: 
  - 页面通知
  - 邮件告警
  - 短信通知（阿里云短信服务）
- **告警规则**: 可配置的告警阈值和规则
- **监控看板**: 实时展示关键质量指标
- **外部推送**: 支持向芜湖等外部系统推送异常数据

### 6. 失效模式分析 (FACA) 🔍

- **FACA文件管理**: 上传、下载、删除FACA分析文件
- **控制图快照**: 自动生成和管理控制图快照
- **分析报告**: 生成详细的失效模式分析报告
- **数据导入导出**: 支持Excel格式的数据交换
- **消息推送**: FACA分析结果实时推送

### 7. 数据查询与报表 📑

- **多维查询**: 按时间、方案、检测项等多条件查询
- **分页查询**: 高效的分页查询机制
- **Excel导出**: 支持导出质量数据和分析报表
- **历史追溯**: 90天数据保留，支持历史数据追溯
- **统计分析**: 提供丰富的统计分析功能

### 8. 权限管理与安全 🔐

- **统一认证**: 集成企业统一认证服务
- **RBAC权限**: 基于角色的访问控制
- **数据加密**: 敏感数据加密存储
- **操作审计**: 完整的用户操作日志
- **会话管理**: 会话超时自动登出

---

## 🏗️ 技术架构

### 技术栈

#### 后端框架
- **Spring Boot**: 2.4.3
- **Spring Cloud**: 2021.0.x
- **Spring Cloud Alibaba**: Nacos服务发现与配置中心
- **MyBatis Plus**: 3.5.4.1 - ORM框架
- **Druid**: 1.2.20 - 数据库连接池

#### 数据存储
- **MySQL**: 8.0+ - 主数据库
- **Redis**: 6.0+ - 缓存和会话存储

#### 消息队列
- **Kafka**: 2.8+ - 异步消息处理

#### 工具库
- **Hutool**: 5.8.26 - Java工具类库
- **EasyExcel**: 4.0.3 - Excel处理
- **Redisson**: 3.43.0 - 分布式锁
- **QLExpress**: 3.3.3 - 规则引擎
- **JDistLib**: 0.4.5 - 统计计算

#### 接口文档
- **Knife4j**: 4.4.0 - API文档增强
- **Swagger**: 2.10.5 - API文档生成

#### 其他组件
- **WebSocket**: 实时通信
- **MQTT**: 1.2.5 - IOT设备通信
- **Feign**: 服务间调用
- **阿里云短信**: 短信告警

### 系统架构

```
┌─────────────────────────────────────────────────────────────┐
│                        前端层 (Web/Mobile)                    │
│                    Vue.js / React / 移动端                    │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                        API Gateway                           │
│                    统一认证 / 路由 / 限流                      │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                      微服务层                                 │
├─────────────────┬─────────────────┬─────────────────────────┤
│  htsk-serv-sspc │ htsk-serv-auth  │  htsk-serv-system       │
│  (SPC核心服务)   │  (认证服务)      │  (系统管理服务)          │
└─────────────────┴─────────────────┴─────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                      基础设施层                               │
├──────────────┬──────────────┬──────────────┬───────────────┤
│    Nacos     │    MySQL     │    Redis     │     Kafka     │
│  (注册/配置)  │   (数据库)    │    (缓存)     │   (消息队列)   │
└──────────────┴──────────────┴──────────────┴───────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                      外部系统集成                             │
├──────────────┬──────────────┬──────────────┬───────────────┤
│  IOT设备     │  MES系统     │  邮件服务     │   短信服务     │
└──────────────┴──────────────┴──────────────┴───────────────┘
```

### 核心模块

```
htsk-serv-sspc/
├── aspect/          # AOP切面（日志、权限等）
├── bean/            # 数据传输对象
├── component/       # 组件（WebSocket、MQTT等）
├── config/          # 配置类
├── constant/        # 常量定义
├── consumer/        # Kafka消费者
├── controller/      # REST控制器
├── entity/          # 实体类
├── enums/           # 枚举类
├── exception/       # 异常处理
├── handler/         # 处理器（类型转换等）
├── listener/        # 事件监听器
├── mapper/          # MyBatis Mapper
├── service/         # 业务逻辑层
├── task/            # 定时任务
└── util/            # 工具类
```

---

## 🚀 快速开始

### 环境要求

- **JDK**: 1.8+
- **Maven**: 3.6+
- **MySQL**: 8.0+
- **Redis**: 6.0+
- **Nacos**: 2.0+
- **Kafka**: 2.8+ (可选)

### 本地开发

#### 1. 克隆项目

```bash
git clone <repository-url>
cd htsk-serv-sspc
```

#### 2. 配置数据库

```sql
-- 创建数据库
CREATE DATABASE sspc DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 导入数据库脚本
source database_migration_bind_data_item.sql
```

#### 3. 配置Nacos

在Nacos中创建配置文件 `htsk-serv-sspc.yml`:

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/sspc?useUnicode=true&characterEncoding=utf8
    username: root
    password: your_password
  redis:
    host: localhost
    port: 6379
    password: your_redis_password
```

#### 4. 修改本地配置

编辑 `htsk-serv-sspc/src/main/resources/application.yml`:

```yaml
spring:
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848
      config:
        server-addr: localhost:8848
```

#### 5. 启动服务

```bash
# 使用Maven启动
cd htsk-serv-sspc
mvn spring-boot:run

# 或者使用IDE直接运行 HtskSspcApplication.java
```

#### 6. 访问服务

- **API文档**: http://localhost:8080/doc.html
- **健康检查**: http://localhost:8080/actuator/health

---

## 📚 API文档

### 在线文档

启动服务后访问: http://localhost:8080/doc.html

### 核心接口

#### 1. 外部数据接入

```http
POST /api/external/data/submit
Content-Type: application/json
X-API-Key: your-api-key

{
  "sourceSystem": "IOT系统",
  "solutionPlan": "冲压方案A",
  "detectionItem": "压力检测",
  "records": [
    {
      "collectTime": "2023-10-26 10:30:00",
      "data": {
        "values": [25.5, 101.3, 65.2]
      }
    }
  ]
}
```

#### 2. 绑定配置管理

```http
# 创建配置
POST /api/binding-config
Content-Type: application/json

{
  "externalSource": "IOT系统",
  "externalScenario": "冲压方案A",
  "externalItem": "压力检测",
  "localScenarioId": 1,
  "localItemId": 100,
  "consumeInterval": 60
}

# 查询配置列表
GET /api/binding-config/list?pageNum=1&pageSize=10

# 启动消费
POST /api/binding-config/start-consume
Content-Type: application/json

{
  "configId": 1
}

# 停止消费
POST /api/binding-config/stop-consume/1
```

#### 3. 数据查询

```http
# 查询未消费数据统计
GET /api/external/data/unconsumed-stats?configId=1

# 查询数据列表
GET /api/external/data/list?pageNum=1&pageSize=10&startTime=2023-10-01&endTime=2023-10-31
```

### 详细文档

- [前端接口文档](./.kiro/specs/external-data-api/前端接口文档-完整版.md)
- [外部数据API说明](./.kiro/specs/external-data-api/README.md)
- [快速参考](./QUICK_REFERENCE.md)

---

## 🗄️ 数据库设计

### 核心表结构

#### 1. det_external_scenario (外部方案表)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT | 主键 |
| external_source | VARCHAR(100) | 外部来源 |
| scenario_name | VARCHAR(200) | 方案名称 |
| create_time | DATETIME | 创建时间 |

#### 2. det_external_item (外部检测项表)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT | 主键 |
| scenario_id | BIGINT | 外部方案ID |
| item_name | VARCHAR(200) | 检测项名称 |
| create_time | DATETIME | 创建时间 |

#### 3. det_external_data (外部数据表)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT | 主键 |
| scenario_id | BIGINT | 外部方案ID |
| item_id | BIGINT | 外部检测项ID |
| data_values | TEXT | 数据值（JSON） |
| collect_time | DATETIME | 采集时间 |
| is_consumed | TINYINT | 是否已消费 |
| consume_time | DATETIME | 消费时间 |

#### 4. det_binding_config (绑定配置表)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT | 主键 |
| external_source | VARCHAR(100) | 外部来源 |
| external_scenario | VARCHAR(200) | 外部方案 |
| external_item | VARCHAR(200) | 外部检测项 |
| local_scenario_id | BIGINT | 本地方案ID |
| local_item_id | BIGINT | 本地检测项ID |
| consume_interval | INT | 消费间隔(秒) |
| is_consuming | TINYINT | 是否正在消费 |
| last_consume_time | DATETIME | 最后消费时间 |

### 数据库迁移

```bash
# 执行迁移脚本
mysql -u username -p sspc < database_migration_bind_data_item.sql

# 验证表结构
mysql -u username -p sspc -e "DESC det_binding_config;"
```

---

## 🔧 配置说明

### application.yml 核心配置

```yaml
# 外部数据接口配置
external-api:
  enabled: true                    # 是否启用外部数据接口
  default-qps: 100                 # 默认QPS限制
  max-batch-size: 1000             # 批量提交最大数量
  encryption-key: your-secret-key  # API Key加密密钥
  log-retention-days: 90           # 日志保留天数

# SPC系统配置
sspc:
  remote:
    user: 0                        # 远程用户模式
  mode:
    debug: false                   # 调试模式

# 芜湖接口配置
wuhu:
  abnormalOpen: false              # 异常推送开关
  abnormalStartUrl: http://...     # 异常开始推送URL
  abnormalEndUrl: http://...       # 异常结束推送URL

# FACA文件路径
faca-file-path: faca/file/

# 分析Excel路径
analysis-excel-path: analysis/excel/
```

### Nacos配置

在Nacos配置中心创建以下配置:

- **Data ID**: htsk-serv-sspc.yml
- **Group**: DEFAULT_GROUP
- **配置格式**: YAML

---

## 📦 部署指南

### Docker部署

#### 1. 构建镜像

```bash
# 构建项目
mvn clean package -DskipTests

# 构建Docker镜像
docker build -t htsk-sspc:1.0.0 .
```

#### 2. 运行容器

```bash
docker run -d \
  --name htsk-sspc \
  -p 8080:8080 \
  -e SPRING_PROFILES_ACTIVE=prod \
  -e NACOS_SERVER_ADDR=nacos:8848 \
  -e MYSQL_HOST=mysql \
  -e REDIS_HOST=redis \
  htsk-sspc:1.0.0
```

### Docker Compose部署

```yaml
version: '3.8'

services:
  sspc:
    image: htsk-sspc:1.0.0
    ports:
      - "8080:8080"
    environment:
      - SPRING_PROFILES_ACTIVE=prod
      - NACOS_SERVER_ADDR=nacos:8848
    depends_on:
      - mysql
      - redis
      - nacos

  mysql:
    image: mysql:8.0
    environment:
      - MYSQL_ROOT_PASSWORD=password
      - MYSQL_DATABASE=sspc
    volumes:
      - mysql-data:/var/lib/mysql

  redis:
    image: redis:6.0
    command: redis-server --requirepass password

  nacos:
    image: nacos/nacos-server:2.0.3
    environment:
      - MODE=standalone

volumes:
  mysql-data:
```

### 生产环境部署

#### 1. 准备工作

```bash
# 打包项目
mvn clean package -DskipTests

# 上传到服务器
scp target/htsk-serv-sspc-1.0.0.jar user@server:/opt/htsk/
```

#### 2. 启动脚本

创建 `start.sh`:

```bash
#!/bin/bash

APP_NAME=htsk-serv-sspc
JAR_FILE=/opt/htsk/${APP_NAME}-1.0.0.jar
LOG_DIR=/opt/htsk/logs
PID_FILE=/opt/htsk/${APP_NAME}.pid

# JVM参数
JAVA_OPTS="-Xms2g -Xmx4g -XX:+UseG1GC -XX:MaxGCPauseMillis=200"

# 启动应用
nohup java ${JAVA_OPTS} \
  -Dspring.profiles.active=prod \
  -jar ${JAR_FILE} \
  > ${LOG_DIR}/${APP_NAME}.log 2>&1 &

echo $! > ${PID_FILE}
echo "${APP_NAME} started with PID: $(cat ${PID_FILE})"
```

#### 3. 停止脚本

创建 `stop.sh`:

```bash
#!/bin/bash

APP_NAME=htsk-serv-sspc
PID_FILE=/opt/htsk/${APP_NAME}.pid

if [ -f ${PID_FILE} ]; then
  PID=$(cat ${PID_FILE})
  kill -15 ${PID}
  echo "${APP_NAME} stopped (PID: ${PID})"
  rm ${PID_FILE}
else
  echo "${APP_NAME} is not running"
fi
```

---

## 🧪 测试

### 单元测试

```bash
# 运行所有测试
mvn test

# 运行指定测试类
mvn test -Dtest=BindingConfigServiceTest

# 生成测试报告
mvn test jacoco:report
```

### 集成测试

```bash
# 运行集成测试
mvn verify -P integration-test
```

### API测试

使用Postman导入测试集合:

1. 导入 `postman/SPC-API-Tests.json`
2. 配置环境变量
3. 运行测试集合

---

## 📊 监控与运维

### 健康检查

```bash
# 检查服务状态
curl http://localhost:8080/actuator/health

# 检查详细信息
curl http://localhost:8080/actuator/info
```

### 日志管理

```bash
# 查看实时日志
tail -f /opt/htsk/logs/htsk-serv-sspc.log

# 查看错误日志
grep ERROR /opt/htsk/logs/htsk-serv-sspc.log

# 日志轮转配置（logback-spring.xml）
<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
  <fileNamePattern>logs/htsk-sspc.%d{yyyy-MM-dd}.log</fileNamePattern>
  <maxHistory>30</maxHistory>
</rollingPolicy>
```

### 性能监控

- **Druid监控**: http://localhost:8080/druid/index.html
- **Actuator端点**: http://localhost:8080/actuator
- **Nacos控制台**: http://nacos:8848/nacos

---

## 🔍 故障排查

### 常见问题

#### 1. 服务启动失败

```bash
# 检查端口占用
netstat -ano | findstr 8080

# 检查Nacos连接
curl http://nacos:8848/nacos/v1/ns/operator/metrics

# 检查数据库连接
mysql -h localhost -u root -p sspc
```

#### 2. 数据消费任务未执行

```bash
# 检查定时任务状态
curl http://localhost:8080/api/binding-config/list

# 查看任务日志
grep "DataConsumeTask" /opt/htsk/logs/htsk-serv-sspc.log

# 检查Redis连接
redis-cli -h localhost -p 6379 -a password ping
```

#### 3. API调用失败

```bash
# 检查API Key
curl -H "X-API-Key: your-key" http://localhost:8080/api/external/data/submit

# 查看限流日志
grep "RateLimiter" /opt/htsk/logs/htsk-serv-sspc.log
```

### 日志级别调整

在Nacos中动态调整日志级别:

```yaml
logging:
  level:
    com.htsk.sspc: DEBUG
    com.htsk.sspc.service: TRACE
```

---

## 📖 开发指南

### 代码规范

- 遵循阿里巴巴Java开发手册
- 使用Lombok简化代码
- 统一使用MyBatis Plus进行数据库操作
- Controller层只做参数校验和转发
- Service层实现业务逻辑
- 异常统一使用全局异常处理

### 分支管理

```
master    - 生产环境分支
develop   - 开发环境分支
feature/* - 功能开发分支
hotfix/*  - 紧急修复分支
```

### 提交规范

```
feat: 新功能
fix: 修复bug
docs: 文档更新
style: 代码格式调整
refactor: 重构
test: 测试相关
chore: 构建/工具链相关
```

### 开发流程

1. 从develop分支创建feature分支
2. 开发并提交代码
3. 创建Pull Request
4. 代码审查
5. 合并到develop分支
6. 测试通过后合并到master分支

---

## 🤝 贡献指南

### 如何贡献

1. Fork本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建Pull Request

### 代码审查

所有代码提交都需要经过代码审查:

- 代码符合规范
- 单元测试覆盖率 > 80%
- 无安全漏洞
- 性能测试通过

---

## 📄 许可证

本项目为亨通数科内部项目，版权所有。未经授权不得复制、分发或修改。

---

## 📞 联系方式

- **项目负责人**: [nico]
- **技术支持**: [liangzx@hengtonggroup.com.cn]
- **问题反馈**: [issue tracker]

---

## 🙏 致谢

感谢以下开源项目:

- [Spring Boot](https://spring.io/projects/spring-boot)
- [Spring Cloud](https://spring.io/projects/spring-cloud)
- [MyBatis Plus](https://baomidou.com/)
- [Hutool](https://hutool.cn/)
- [Knife4j](https://doc.xiaominfo.com/)

---

<div align="center">

**亨通数科 © 2025**

Made with ❤️ by HTSK Team

</div>