# SoftMeter

**Repository Path**: cms05/soft-meter

## Basic Information

- **Project Name**: SoftMeter
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-17
- **Last Updated**: 2026-04-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 自动化软件度量平台（SoftMeter）

本仓库包含一个前后端分离的自动化软件度量平台：

- 前端：Vue 3 + Vite + Tailwind CSS，负责文件上传、指标展示与图表渲染
- 后端：Spring Boot（Maven），负责解析上传内容并计算各类度量指标

## 目录结构

```
SoftMeter/
├── The-software-metrics-platform-front-end/   # 前端（Vue3 + Vite）
└── backend/
    └── smproject/                             # 后端（Spring Boot）
```

## 环境要求

- Node.js 18+（用于前端）
- Java 8（后端 pom.xml 指定 `java.version=1.8`）
- Maven 3.6+（用于后端构建/运行）

## 快速开始

### 1) 启动后端（默认端口 8080）

```bash
cd backend/smproject
mvn spring-boot:run
```

如果你更想使用 Maven Wrapper（mvnw），请先确保有执行权限：

```bash
cd backend/smproject
chmod +x mvnw
./mvnw spring-boot:run
```

### 2) 启动前端（默认端口 5173）

```bash
cd The-software-metrics-platform-front-end
npm ci
npm run dev
```

浏览器打开：

- http://localhost:5173/

## 前后端联调说明

前端会自动探测后端地址（按顺序尝试）：

- `http://localhost:8081` → `http://localhost:8080` → `http://127.0.0.1:8081` → `http://127.0.0.1:8080`

因此后端运行在 8080 或 8081 都可联调；如果你用到其他端口/域名，需要同步调整前端探测逻辑。

后端 Controller 已开启跨域（`@CrossOrigin`）。

## 后端接口概览

接口集中在 `backend/smproject/src/main/java/.../controller/SscController.java`：

- `POST /CKMetrics`（Content-Type: application/xml）
- `POST /LKMetrics`（Content-Type: application/xml）
- `POST /UCPMetrics`（Content-Type: application/xml）
- `POST /FPMetrics`（Content-Type: application/xml）
- `POST /VGMetrics`（Content-Type: application/xml）
- `POST /countCode`（multipart/form-data，参数名：`files`）

AI 建议接口在 `backend/smproject/src/main/java/.../controller/AiInsightsController.java`：

- `POST /ai/insights`（application/json，返回结构化 JSON）
- `POST /ai/insights/stream`（text/plain，按行 JSON 流：meta/result/delta/done）
- `GET /ai/insights/{id}`（查询历史记录）
- `POST /ai/insights/{id}/feedback`（提交反馈）

说明：

- 后端没有定义 `GET /`，访问根路径出现 404 属于正常现象
- `/VGMetrics`、`/CKMetrics`、`/LKMetrics`、`/UCPMetrics`、`/FPMetrics` 需要传入符合后端模型的 XML；随意 XML 可能会返回 500

## AI 建议（后端接入真实大模型）

当前 AI 链路支持两种模式：

- rules（默认）：后端本地规则引擎生成 findings/recommendations 与解读文本
- OpenAI 兼容大模型（可选）：保留 rules 产生的 findings/recommendations，调用真实大模型生成“解读文本”，并在 `/ai/insights/stream` 里真正流式返回

### 可直接使用的模型服务

只要你的模型服务支持 OpenAI 兼容的 Chat Completions 接口即可（推荐）：

- `POST {AI_BASE_URL}/v1/chat/completions`
- 支持 `stream: true`（SSE：`data: {json}` ... `data: [DONE]`）
- 增量文本位于：`choices[0].delta.content`

云端（示例）：OpenAI、Azure OpenAI（兼容模式）、多数提供 OpenAI-compatible 网关的厂商/自建网关。

本地（示例）：Ollama（需确保其 OpenAI 兼容路由可用）。

### 配置方式（环境变量优先）

在启动后端前配置：

```bash
export AI_ENABLED=true
export AI_BASE_URL="https://api.openai.com"
export AI_API_KEY="YOUR_KEY"
export AI_MODEL="gpt-4o-mini"
export AI_TEMPERATURE="0.2"
```

配置项定义见：

- `backend/smproject/src/main/resources/application.properties`

不启用大模型时保持默认（`AI_ENABLED=false`），系统仍可正常工作。

### 流式接口返回协议（前端部分已经基本完成）

`POST /ai/insights/stream` 返回 `text/plain`，每行一个 JSON：

- `meta`：包含 id/provider/model 等
- `result`：包含 findings/recommendations
- `delta`：模型/规则解读文本增量
- `done`：结束

### 快速自测

```bash
curl -N -H 'Content-Type: application/json' \
  -d '{"metricKey":"codelines","summary":{},"items":[{"fileName":"A.java","codeLines":900,"commentLines":10,"blankLines":20}],"context":{}}' \
  http://127.0.0.1:8080/ai/insights/stream
```

### 代码入口

- Controller（流式输出协议）：`backend/smproject/src/main/java/cn/edu/csu/smproject/controller/AiInsightsController.java`
- Service（OpenAI compatible + SSE 解析/透传）：`backend/smproject/src/main/java/cn/edu/csu/smproject/ai/service/AiInsightsService.java`
- Rules 引擎（保底输出）：`backend/smproject/src/main/java/cn/edu/csu/smproject/ai/service/AiInsightsEngine.java`

### 注意事项

- 不要在日志中打印 `AI_API_KEY`
- 如果 8080 端口被其他进程占用，浏览器会误打到错误服务导致 CORS；建议后端固定使用 8080 或 8081 之一
- 
## 前端说明

前端更详细的功能与截图见：

- `The-software-metrics-platform-front-end/README.md`