# tools-requirement

**Repository Path**: devbigapp/tools-requirement

## Basic Information

- **Project Name**: tools-requirement
- **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-10-30
- **Last Updated**: 2026-10-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 需求分析与日志分析工具

[![项目架构](https://img.shields.io/badge/Architecture-MVC-blue.svg)](https://img.shields.io/badge/Architecture-MVC-blue.svg)
[![技术栈](https://img.shields.io/badge/Tech%20Stack-Spring%20Boot%20%2B%20Vue%203-green.svg)](https://img.shields.io/badge/Tech%20Stack-Spring%20Boot%20%2B%20Vue%203-green.svg)
[![License](https://img.shields.io/badge/License-Internal%20Use-yellow.svg)](https://img.shields.io/badge/License-Internal%20Use-yellow.svg)
[![Version](https://img.shields.io/badge/Version-v1.0.11-orange.svg)](https://img.shields.io/badge/Version-v1.0.11-orange.svg)

本项目包含**Web应用**和**Android应用**两部分：

- **Web应用**：基于 Web 的本地/内网部署应用，导入团队 Excel 需求数据与日志数据，自动计算多维度指标，生成交互式分析报告，并支持成本测算、预测、数据管理与备份恢复。全部数据留在本机或内网，不上传公网。
- **Android应用**：移动端需求分析与数据管理工具，支持离线使用。

| 项 | 说明 |
|----|------|
| 当前版本 | **v1.0.11**（`code/web/backend` / `code/web/frontend`） |
| 默认入口 | 报告中心 `/reports` |
| 适用环境 | 内网、本机 Docker、飞牛 NAS Docker、Android设备 |
| 鉴权 | 无登录（仅适合受控内网） |

---

## 目录

- [文档导航](#文档导航)
- [项目概述](#项目概述)
- [功能模块](#功能模块)
- [技术架构](#技术架构)
- [环境与端口](#环境与端口)
- [快速开始](#快速开始)
- [使用流程](#使用流程)
- [前端页面](#前端页面)
- [API 概览](#api-概览)
- [项目结构](#项目结构)
- [测试与质量](#测试与质量)
- [常见问题](#常见问题)
- [贡献与许可](#贡献与许可)
- [更新日志](#更新日志)

---

## 文档导航

本仓库采用 **`docs/` 01-09 主类目** 文档结构。日常开发以 `code/web/README.md` 为准。

| 你想… | 从这里开始 |
|--------|------------|
| 查业务 PRD | [docs/01-产品/](docs/01-产品/) |
| 查接口与功能细节 | [docs/04-开发/](docs/04-开发/) / [docs/03-核心功能/](docs/03-核心功能/) |
| Web工程运行说明 | [code/web/README.md](code/web/README.md) |
| 文档中心总览 | [docs/README.md](docs/README.md) |

**推荐接手路径**：`01-产品/` PRD → `03-核心功能/功能说明` → `04-开发/接口文档` → 源码 `code/web/frontend`、`code/web/backend`。

---

## 项目概述

### 📊 产品架构图

```mermaid
graph TB
    A[用户<br/>浏览器/移动端] -->|HTTP请求| B[前端层<br/>Vue3 + Element Plus]
    B -->|API调用| C[后端层<br/>Spring Boot 3.2]
    C -->|JDBC| D[数据层<br/>MySQL 8.0]
    C -->|文件处理| E[文件模块<br/>Excel/PDF/Markdown]
    C -->|分析引擎| F[分析服务<br/>21项核心指标]
    G[备份迁移模块] -->|数据导出导入| D
    H[配置管理模块] -->|规则配置| C
    
    style A fill:#e1f5ff
    style B fill:#fff4e1
    style C fill:#e8f5e9
    style D fill:#fce4ec
    style E fill:#f3e5f5
    style F fill:#e0f7fa
    style G fill:#f1f8e9
    style H fill:#fff3e0
```

### Web应用
系统面向团队管理的**需求分析**与**日志分析**场景：将 Excel 需求明细、任务关联、人工单价、人员成本等数据导入 MySQL，经分析引擎计算多维度核心指标，输出多类报告（综合分析、成本、预测、利润贡献等），并支持 Excel / HTML / Markdown / PDF / PNG 导出与历史留存。

### Android应用
移动端需求分析与数据管理工具，支持离线使用，内置数据种子，提供数据录入、分析、报告展示等功能。

### 🎯 核心价值

| 维度 | 说明 | 图标 |
|------|------|------|
| **自动化** | 导入 Excel → 选时间范围 → 一键分析，替代手工汇总 | ⚡ |
| **标准化** | 固化指标公式与校验规则，口径一致、可月度复用 | 📐 |
| **可扩展** | 除经典分析报告外，含成本分析、成本预测、数据 CRUD、备份迁移 | 🚀 |
| **可追溯** | 历史报告可查、可删、可导出；支持业务指标下钻 | 🔍 |
| **本地化** | 数据与计算均在本地/内网，无 SaaS 依赖 | 🔒 |

### 💼 典型场景

```mermaid
pie title 主要应用场景占比
    "月度需求质量汇报" : 35
    "任务关联率审计" : 25
    "人员利润测算" : 20
    "成本预测管理" : 15
    "其他场景" : 5
```

- 每月固定节点的需求填写质量与达标率汇报
- 任务预算关联率审计、未关联风险名单
- 人员收入/利润测算与排名
- 按周 / 月 / 季 / 年或自定义区间的分析
- 全年成本预测与目标测算（成本预测模块）

---

## 功能模块

### 📦 功能架构图

```mermaid
graph LR
    A[功能模块] --> B[数据导入<br/>📥]
    A --> C[配置管理<br/>⚙️]
    A --> D[报告中心<br/>📊]
    A --> E[数据管理<br/>🗂️]
    A --> F[备份迁移<br/>💾]
    A --> G[导出历史<br/>📋]
    
    B --> B1[需求明细<br/>导入]
    B --> B2[任务关联<br/>导入]
    B --> B3[成本数据<br/>导入]
    
    D --> D1[综合分析<br/>报告]
    D --> D2[核心指标<br/>报告]
    D --> D3[成本预测<br/>报告]
    D --> D4[利润贡献<br/>报告]
    
    E --> E1[数据CRUD]
    E --> E2[异常检测]
    E --> E3[需求数据<br/>管理]
    
    style A fill:#e3f2fd
    style B fill:#bbdefb
    style C fill:#90caf9
    style D fill:#64b5f6
    style E fill:#42a5f5
    style F fill:#2196f3
    style G fill:#1976d2
```

### 1. 数据导入与预览 📥

- 支持**需求明细**、**任务关联工时**、**人工单价**、**人员成本**、**离职补偿**等 Excel 上传（`.xlsx` / `.xls`）
- 追加 / 覆盖模式；导入后预览
- 表头自动映射与清洗（需符合约定模板，见 PRD）

```mermaid
flowchart TD
    A[上传Excel文件] --> B[校验文件格式]
    B -->|通过| C[解析Excel内容]
    B -->|失败| D[显示错误提示]
    C --> E[映射表头字段]
    E --> F[数据预览]
    F --> G[选择追加/覆盖模式]
    G --> H[写入数据库]
    H --> I[导入完成提示]
```

### 2. 配置管理（`/config`）⚙️

- 法定工作日、达标阈值、人员分类、工作日修正
- 小组管理、项目地区映射

### 3. 报告中心（`/reports`）📊

支持以下报告类型：

| 类型 | 说明 | 图标 |
|------|------|------|
| 综合分析 | 多维度指标汇总，9 章结构化输出 | 📈 |
| 核心指标 | 关键 KPI 快速查看 | 🎯 |
| 需求专项 | 需求质量与达标率专项分析 | ✅ |
| 成本分析 | 人员成本与工时成本核算 | 💰 |
| 成本预测 | 全年/季度成本目标测算 | 🔮 |
| 利润贡献 | 人员利润贡献排名与分析 | 📊 |

```mermaid
graph TB
    A[报告生成流程] --> B[选择时间范围]
    B --> C[选择报告类型]
    C --> D[触发分析引擎]
    D --> E[计算21项核心指标]
    E --> F[生成报告数据]
    F --> G[渲染报告页面]
    G --> H[支持多种格式导出]
```

### 4. 数据管理（`/data`）🗂️

对库内数据进行维护，无需重复导入 Excel 即可微调：

- 需求明细、任务关联、单价、法定工作日、人员成本、离职补偿
- 人员档案、改名、从需求初始化人员
- 异常检测、按月汇总、任务未关联下钻

### 5. 备份与迁移 💾

```mermaid
sequenceDiagram
    participant U as 用户
    participant S as 系统
    participant D as 数据库
    
    U->>S: 创建备份请求
    S->>D: 读取所有数据表
    D-->>S: 返回数据
    S->>S: 打包成ZIP文件
    S-->>U: 提供下载链接
    
    U->>S: 上传备份文件
    S->>S: 解压并校验数据
    S->>D: 恢复数据
    D-->>S: 确认恢复完成
    S-->>U: 显示恢复成功
```

- 按数据集导出 / 导入
- 备份创建、下载、恢复与完整性检查（`/api/data/transfer`）

### 6. 导出与历史 📋

- 导出：Excel（多工作表）、HTML、Markdown、PDF、PNG 等
- 历史报告列表、按条件筛选、重新打开、删除

---

## 技术架构

### 🛠️ 技术栈架构图

```text
┌───────────────────────────────────────────────────────────────────────────────────┐
│                               前端层 (Vue 3)                                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │
│  │   页面组件   │  │   路由管理   │  │  状态管理    │  │  API调用     │         │
│  │ (Views)      │  │ (Router)     │  │ (Store)      │  │ (Axios)      │         │
│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘         │
│  ┌───────────────────────────────────────────────────────────────────────────┐  │
│  │                         Vite 构建工具                                       │  │
│  │                     Element Plus UI组件库                                  │  │
│  └───────────────────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      │ HTTP/REST API
                                      ▼
┌───────────────────────────────────────────────────────────────────────────────────┐
│                             后端层 (Spring Boot)                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │
│  │ Controller  │  │   Service    │  │   Mapper     │  │  Entity/DTO  │         │
│  │  (接口层)    │  │  (业务层)    │  │  (数据层)    │  │  (模型层)    │         │
│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘         │
│  ┌───────────────────────────────────────────────────────────────────────────┐  │
│  │               分析引擎、文件处理、安全等核心服务                              │  │
│  │    MyBatis-Plus、Apache POI、PDFBox、Spring Security                      │  │
│  └───────────────────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      │ JDBC
                                      ▼
┌───────────────────────────────────────────────────────────────────────────────────┐
│                            数据层 (MySQL 8.0)                                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │
│  │需求明细表    │  │任务关联表    │  │成本数据表    │  │报告历史表    │         │
│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘         │
└───────────────────────────────────────────────────────────────────────────────────┘
```

| 层级 | 技术栈 | 版本 |
|------|--------|------|
| 前端 | Vue 3.4、Vue Router 4、Vite 5、Element Plus、Axios、Playwright | ^3.4.0 |
| 后端 | Java 17、Spring Boot 3.2.5、MyBatis-Plus 3.5.6、Apache POI、PDFBox | 3.2.5 |
| 数据 | MySQL 8.0 | 8.0+ |
| 部署 | Docker Compose、Nginx（前端静态）、可选飞牛 NAS 远程部署 | 20.10+ |

### 📊 技术选型说明

```mermaid
mindmap
  root((技术选型))
    前端
      Vue 3
        Composition API
        响应式系统
      Element Plus
        企业级组件
        主题定制
      Vite
        快速启动
        热更新
    后端
      Spring Boot
        自动配置
        内嵌容器
      MyBatis-Plus
        CRUD封装
        代码生成
      Java 17
        性能优化
        新特性
    数据库
      MySQL 8.0
        事务支持
        索引优化
    部署
      Docker
        容器化
        环境一致性
      Nginx
        反向代理
        静态资源
```

---

## 环境与端口

### 🔧 运行依赖

| 组件 | 版本要求 | 图标 |
|------|----------|------|
| JDK | 17+ | ☕ |
| MySQL | 8.0+ | 🐬 |
| Node.js | 18+ | 🟢 |
| Docker | 20.10+（部署态） | 🐳 |
| 浏览器 | Chrome / Edge / Firefox 最新版 | 🌐 |

### 🌐 双环境端口（可同时运行）

```mermaid
graph TD
    A[开发环境<br/>本地开发]
    B[部署环境<br/>Docker部署]
    C[飞牛NAS部署<br/>内网部署]
    
    A -->|前端端口:5281
    A -->|后端API:7181
    A -->|MySQL:3317
    
    B -->|前端访问:8281
    B -->|后端映射:8181
    B -->|MySQL映射:3318
    
    C -->|内网IP访问
    
    style A fill:#e3f2fd
    style B fill:#e8f5e9
    style C fill:#fff3e0
```

| 场景 | 前端 | 后端 API | MySQL | 说明 |
|------|------|----------|-------|------|
| **开发态** | `5281` | `7181` | `3317` | Vite 开发服务 |
| **部署态**（Docker） | `8281` | `8181`（映射容器内 `7181`） | `3318` | Docker 容器化部署 |

- 开发态访问：`http://localhost:5281`（Vite 代理 `/api` → `7181`）
- 本机 Docker：`http://localhost:8281`
- 飞牛 NAS：执行部署脚本后访问 `http://<NAS内网IP>:8281`

默认数据库：`analysis_requirement`，用户 `root` / `123456`（生产请修改）。

---

## 快速开始

### 🚀 启动流程图

```mermaid
graph TD
    A[开始] --> B{选择启动方式}
    B -->|本地开发| C[方式A:本地开发]
    B -->|Docker部署| D[方式B:Docker Compose]
    B -->|NAS部署| E[方式C:飞牛NAS部署]
    C --> F[启动成功!]
    D --> F
    E --> F
    F --> G[访问应用]
```

### 方式 A：本地开发（推荐日常开发）

```bash
# 1. 克隆
git clone <仓库地址>
cd tools_analysis-project/code/web

# 2. 初始化数据库（首次）
bash scripts/init-db.sh

# 3. 一键启动前后端
bash scripts/start-local-dev.sh
```

访问 `http://localhost:5281`

### 方式 B：Docker Compose（推荐部署）

```bash
cd code/web
docker volume create log-analysis-mysql-data
docker volume create log-analysis-backend-logs
bash scripts/deploy-local-docker.sh
```

访问 `http://localhost:8281`

### 方式 C：飞牛 NAS 部署

```bash
cd code/web
bash scripts/deploy-fn-nas-docker.sh
```

详细工程运行说明见 [code/web/README.md](code/web/README.md)。

---

## 使用流程

### 📝 业务流程图

```mermaid
graph LR
    A[导入数据] --> B[配置规则]
    B --> C[选择时间范围]
    C --> D[生成报告]
    D --> E[查看报告]
    E --> F{需要导出?}
    F -->|是| G[导出报告]
    F -->|否| H[留存历史]
    G --> H
```

1. **导入**：`/import` 上传 Excel 文件（需求明细必传，其余按需）
2. **配置**：`/config` 设置法定工作日、达标阈值等
3. **分析**：`/reports` 选择报告类型与时间范围，点击生成
4. **导出**：报告页内选择格式导出，或在历史列表重新打开

---

## 前端页面

### 🎨 页面导航图

```mermaid
graph TB
    A[首页<br/>/] --> B[报告中心<br/>/reports]
    A --> C[数据导入<br/>/import]
    A --> D[需求导入<br/>/requirement-import]
    A --> E[配置管理<br/>/config]
    A --> F[数据管理<br/>/data]
    A --> G[关于<br/>/about]
    
    B --> H[报告详情<br/>/report/:id]
    B --> I[历史报告<br/>/history]
    
    style A fill:#e3f2fd
    style B fill:#bbdefb
    style C fill:#90caf9
    style D fill:#64b5f6
    style E fill:#42a5f5
    style F fill:#2196f3
    style G fill:#1976d2
```

| 路由 | 页面 | 说明 | 图标 |
|------|------|------|------|
| `/import` | 数据导入 | Excel 上传与预览 | 📥 |
| `/requirement-import` | 需求导入 | 需求专项导入 | 📋 |
| `/config` | 配置管理 | 规则与参数配置 | ⚙️ |
| `/reports` | 报告中心 | 报告生成与历史 | 📊 |
| `/report/:id` | 报告详情 | 单份报告查看 | 📈 |
| `/data` | 数据管理 | 库内数据 CRUD | 🗂️ |
| `/requirement-data` | 需求数据 | 需求数据管理 | 📝 |
| `/history` | 历史报告 | 历史列表与管理 | 📚 |
| `/management` | 管理看板 | 综合管理视图 | 📊 |
| `/about` | 设置 | 运行环境与接口治理 | ℹ️ |

---

## API 概览

### 🔌 API 架构图

```mermaid
graph LR
    A[前端<br/>Vue3] -->|HTTP请求| B[后端API<br/>Spring Boot]
    B --> C[导入模块<br/>/api/import]
    B --> D[配置模块<br/>/api/config]
    B --> E[报告模块<br/>/api/reports]
    B --> F[数据模块<br/>/api/data]
    B --> G[系统模块<br/>/api/about]
    
    C --> H[Excel解析<br/>Apache POI]
    E --> I[分析引擎<br/>21项指标]
    F --> J[备份迁移<br/>数据导出/导入]
    G --> K[健康检查<br/>/health]
```

| 前缀 | 说明 | 主要功能 |
|------|------|----------|
| `/api/import` | 数据导入 | Excel上传、数据验证、预览 |
| `/api/config` | 配置读写 | 规则配置、参数管理 |
| `/api/reports` | 报告生成与查询 | 分析计算、报告生成、历史查询 |
| `/api/data` | 数据管理与备份迁移 | CRUD操作、备份恢复 |
| `/api/about` | 系统信息与健康检查 | 版本信息、健康状态 |

完整接口文档见 `docs/04-开发/`。

---

## 项目结构

### 📁 目录树

```mermaid
graph TB
    A[tools_analysis-project] --> B[code]
    A --> C[docs]
    A --> D[README.md]
    
    B --> B1[app]
    B --> B2[web]
    
    B1 --> B11[android<br/>Android应用]
    B1 --> B12[原型设计<br/>应用原型]
    
    B2 --> B21[backend<br/>Spring Boot]
    B2 --> B22[frontend<br/>Vue3]
    B2 --> B23[scripts<br/>部署脚本]
    B2 --> B24[deploy<br/>部署文件]
    B2 --> B25[doc<br/>工程文档]
    B2 --> B26[qa<br/>质量测试]
    B2 --> B27[docker-compose.yml]
    
    C --> C1[01-产品<br/>PRD文档]
    C --> C2[02-架构<br/>架构设计]
    C --> C3[03-核心功能<br/>功能说明]
    C --> C4[04-开发<br/>开发文档]
    C --> C5[05-测试<br/>测试文档]
```

```
tools_analysis-project/
├── code/
│   ├── app/
│   │   ├── android/      # Android 应用
│   │   └── 原型设计/     # 应用原型设计
│   └── web/              # Web 应用
│       ├── backend/      # Spring Boot 后端
│       ├── frontend/     # Vue 3 前端
│       ├── scripts/      # 部署与运维脚本
│       ├── deploy/       # 部署相关文件
│       ├── doc/          # 工程级文档
│       ├── qa/           # 质量保证测试
│       └── docker-compose.yml
├── docs/                 # 业务文档（01-09 主类目）
│   ├── 01-产品/
│   ├── 02-架构/
│   ├── 03-核心功能/
│   ├── 04-开发/
│   ├── 05-测试/
│   └── ...
└── README.md             # 本文件
```

---

## 测试与质量

### ✅ 测试策略图

```mermaid
graph TB
    A[测试策略] --> B[单元测试]
    A --> C[集成测试]
    A --> D[E2E测试]
    
    B --> B1[后端单元测试<br/>JUnit 5]
    B --> B2[前端单元测试<br/>Vitest]
    
    C --> C1[后端集成测试<br/>Spring Test]
    C --> C2[API接口测试]
    
    D --> D1[Playwright<br/>端到端测试]
```

| 类型 | 工具 | 命令 | 覆盖范围 |
|------|------|------|----------|
| 后端单元/集成测试 | JUnit 5 + Spring Test | `mvn test` | 业务逻辑、数据访问 |
| 前端单元测试 | Vitest | `npm run test` | 组件、工具函数 |
| E2E 测试 | Playwright | `npm run test:e2e` | 用户流程、关键功能 |

提交前需跑通 `mvn test` 与关键 E2E 用例。

---

## 常见问题

### ❓ FAQ 解答

| 问题 | 答案 |
|------|------|
| **启动后端报数据库连接失败？** | 确认 MySQL 已启动，数据库 `requirement_analysis` 已创建，`application.yml` 中连接配置与本机一致。 |
| **前端页面空白或接口 404？** | 开发态确认后端在 `7181` 端口运行；部署态确认 Docker 容器均已启动（`docker compose ps`）。 |
| **Excel 导入报错"表头不匹配"？** | 检查 Excel 列名是否符合约定模板，详见 `docs/01-产品/` PRD 中的字段说明。 |
| **如何修改默认密码？** | 修改 `code/docker-compose.yml` 中 MySQL 环境变量及 `backend/src/main/resources/application.yml` 中的数据源配置，保持一致后重新部署。 |

---

## 贡献与许可

### 🤝 开发约定

- 后端：阿里巴巴 Java 开发手册
- 前端：ESLint + Prettier（按项目配置）
- 提交前需跑通 `mvn test` 与关键 E2E

### 📋 协作流程

```mermaid
flowchart TD
    A[Fork仓库] --> B[创建特性分支]
    B --> C[编写代码]
    C --> D[运行测试]
    D --> E{测试通过?}
    E -->|是| F[提交代码]
    E -->|否| C
    F --> G[Push到远程]
    G --> H[创建Pull Request]
    H --> I[代码审查]
    I --> J{审查通过?}
    J -->|是| K[合并到主分支]
    J -->|否| C
```

1. Fork → 特性分支 → 提交 → Push → Pull Request
2. 文档变更同步更新 `docs/README.md` 或 `docs/` 对应主类目 README

### 📄 许可与联系

- **许可**：仅供内部使用
- **维护**：团队开发组

---

## 更新日志

### 📅 版本历史图

```mermaid
gantt
    title 项目版本历史
    dateFormat  YYYY-MM-DD
    section v1.0.x
    v1.0.0 :done, a1, 2026-05-11, 2d
    v1.0.10 :done, a2, 2026-05-15, 1d
    v1.0.11 :active, a3, 2026-05-18, 1d
```

### v1.0.11（当前）

- 新增需求数据管理模块（Excel 导入、分析、报告导出）
- 数据管理页面增强：需求数据 CRUD 与统计
- 后端新增 `RequirementController`、`RequirementAnalysisService`、`RequirementImportService`
- 前端新增需求导入页面 `/requirement-import` 与需求报告页面 `/requirement-reports`

### v1.0.10（2026-05-15）

- 成本预测、利润贡献、数据管理、备份迁移模块
- 报告中心多类型报告（business / core / log / cost / forecast）
- 开发/部署双端口；本机与飞牛 NAS Docker 脚本与 `deploy-lib.sh`
- 核心回归脚本与 Playwright 主链路

### v1.0.0（2026-05-11）

- 初始发布：Excel 导入、21 项指标、9 章综合分析、历史与导出

---

**最后更新**：2026-05-18