liumangmang
254 lines
6.0 KiB
Markdown
254 lines
6.0 KiB
Markdown
# SVN/Git 日报周报月报一键生成 - 用户手册
|
||
|
||
## 目录
|
||
|
||
1. [产品简介](#1-产品简介)
|
||
2. [环境要求](#2-环境要求)
|
||
3. [安装与启动](#3-安装与启动)
|
||
4. [功能说明](#4-功能说明)
|
||
5. [AI 工作量分析](#5-ai-工作量分析)
|
||
6. [常见问题](#6-常见问题)
|
||
|
||
---
|
||
|
||
## 1. 产品简介
|
||
|
||
「SVN/Git 日报周报月报一键生成」是一款本地离线运行的代码仓库报表生成工具。
|
||
|
||
**核心能力：**
|
||
|
||
- 连接 SVN 远程仓库或 Git 本地仓库，自动抓取提交日志
|
||
- 支持日报、周报、月报三种统计周期
|
||
- 自动生成 Markdown 格式提交报表
|
||
- 可选集成 DeepSeek AI，自动分析工作量并导出 Excel
|
||
- Web 工作台操作，无需命令行
|
||
|
||
**适用场景：**
|
||
|
||
- 团队周报/月报编写，快速汇总代码提交记录
|
||
- 项目经理查看团队成员工作量
|
||
- 个人开发者整理工作日志
|
||
- 外包项目交付工作量证明
|
||
|
||
**数据安全：**
|
||
|
||
- 所有数据本地处理，不上传任何服务器
|
||
- AI 分析仅发送提交摘要（非源码），且可选关闭
|
||
|
||
---
|
||
|
||
## 2. 环境要求
|
||
|
||
### 方式一：Docker 部署（推荐）
|
||
|
||
- Docker 20.10+
|
||
- Docker Compose v2+
|
||
- 无需安装 Java
|
||
|
||
### 方式二：本机 Java 运行
|
||
|
||
- Java 8 或更高版本（JRE 即可）
|
||
- Windows 7+ / macOS 10.12+ / Linux
|
||
|
||
**Java 安装指引：**
|
||
|
||
| 系统 | 安装方式 |
|
||
|------|----------|
|
||
| Windows | 访问 https://adoptium.net/ 下载 JRE 8 (LTS) |
|
||
| macOS | `brew install openjdk@8` |
|
||
| Ubuntu/Debian | `sudo apt install openjdk-8-jre` |
|
||
| CentOS/RHEL | `sudo yum install java-1.8.0-openjdk` |
|
||
|
||
---
|
||
|
||
## 3. 安装与启动
|
||
|
||
### 3.1 Docker 方式
|
||
|
||
```bash
|
||
# 进入 docker 发行包目录
|
||
cd release/docker
|
||
|
||
# 一键启动
|
||
docker compose up -d
|
||
|
||
# 查看状态
|
||
docker compose ps
|
||
|
||
# 停止服务
|
||
docker compose down
|
||
```
|
||
|
||
启动后浏览器访问：**http://localhost:18088**
|
||
|
||
### 3.2 Windows 方式
|
||
|
||
1. 解压发行包到任意目录
|
||
2. 双击 `start.bat`
|
||
3. 等待控制台显示启动成功
|
||
4. 浏览器访问：**http://localhost:18088**
|
||
|
||
### 3.3 macOS / Linux 方式
|
||
|
||
```bash
|
||
# 进入 unix 发行包目录
|
||
cd release/unix
|
||
|
||
# 启动
|
||
./start.sh
|
||
```
|
||
|
||
浏览器访问：**http://localhost:18088**
|
||
|
||
---
|
||
|
||
## 4. 功能说明
|
||
|
||
### 4.1 工作台
|
||
|
||
首页展示系统概览：
|
||
|
||
- **任务统计**：总任务数、执行中、失败数
|
||
- **系统状态**：输出目录可写性、API Key 配置状态
|
||
- **报表模板**：可用的报表模板列表
|
||
- **最近文件**：最新生成的报表文件，可直接下载
|
||
|
||
### 4.2 报表生成
|
||
|
||
这是核心功能页面，操作步骤：
|
||
|
||
**第一步：选择仓库类型**
|
||
|
||
- **SVN**：需要填写 SVN 预设项目、用户名、密码
|
||
- **Git**：需要填写本地 Git 仓库路径（如 `/home/user/my-project`）
|
||
|
||
**第二步：选择报表周期**
|
||
|
||
- **日报**：统计指定日期当天的提交
|
||
- **周报**：统计指定日期所在周（周一至周日）的提交
|
||
- **月报**：统计指定日期所在月的全部提交
|
||
|
||
**第三步：填写参数**
|
||
|
||
- **基准日期**：报表统计的参考日期（默认今天）
|
||
- **周期标签**：报表标题中的周期描述（自动生成，可修改）
|
||
- **作者过滤**：只统计包含指定关键词的作者（留空不过滤）
|
||
- **输出名称**：生成文件的名称前缀（自动生成，可修改）
|
||
|
||
**第四步：可选 AI 增强**
|
||
|
||
- 勾选「启用 AI 摘要」可让 DeepSeek 自动生成工作摘要
|
||
- 需要先在系统设置中配置 API Key
|
||
|
||
**第五步：点击生成**
|
||
|
||
- 点击「测试连接」验证仓库可访问
|
||
- 点击「生成 Markdown + Excel」开始生成
|
||
- 执行日志区域会实时显示进度
|
||
- 完成后自动下载 Excel 文件
|
||
|
||
### 4.3 任务历史
|
||
|
||
查看所有历史任务：
|
||
|
||
- 支持按状态（PENDING/RUNNING/SUCCESS/FAILED/CANCELLED）筛选
|
||
- 支持按类型筛选
|
||
- 支持关键词搜索
|
||
- 分页浏览
|
||
- 可直接下载任务产物
|
||
|
||
### 4.4 系统设置
|
||
|
||
- **DeepSeek API Key**：配置 AI 分析所需的密钥
|
||
- **默认 SVN 项目**：设置默认选中的 SVN 预设
|
||
- **输出目录**：自定义报表输出路径（默认 `outputs`）
|
||
|
||
---
|
||
|
||
## 5. AI 工作量分析
|
||
|
||
### 5.1 获取 API Key
|
||
|
||
1. 访问 https://platform.deepseek.com
|
||
2. 注册账号并登录
|
||
3. 进入「API Keys」页面
|
||
4. 创建新的 API Key
|
||
5. 复制 Key（格式为 `sk-...`）
|
||
|
||
### 5.2 配置 API Key
|
||
|
||
**方式一：Web 设置页**
|
||
|
||
在「系统设置」页面填入 API Key 并保存。
|
||
|
||
**方式二：环境变量**
|
||
|
||
```bash
|
||
export DEEPSEEK_API_KEY=sk-your-key-here
|
||
```
|
||
|
||
Docker 方式可在 `docker-compose.yml` 中配置：
|
||
|
||
```yaml
|
||
environment:
|
||
- DEEPSEEK_API_KEY=sk-your-key-here
|
||
```
|
||
|
||
### 5.3 使用说明
|
||
|
||
- AI 分析会将提交记录摘要发送给 DeepSeek API
|
||
- 不会发送源代码内容，仅发送提交信息
|
||
- 每次分析消耗少量 Token（通常 < 0.01 元）
|
||
- 不配置 API Key 也可正常使用基础报表功能
|
||
|
||
---
|
||
|
||
## 6. 常见问题
|
||
|
||
### Q: 启动后无法访问 http://localhost:18088？
|
||
|
||
- 确认服务已启动（控制台无报错）
|
||
- 检查端口 18088 是否被其他程序占用
|
||
- 尝试使用 http://127.0.0.1:18088
|
||
|
||
### Q: SVN 连接失败？
|
||
|
||
- 检查 SVN 地址格式是否正确（以 `http://` 或 `https://` 开头）
|
||
- 确认用户名和密码正确
|
||
- 确认网络可以访问 SVN 服务器
|
||
- 如果是 HTTPS，可能存在证书问题
|
||
|
||
### Q: Git 仓库路径无效？
|
||
|
||
- 确认路径指向 `.git` 所在的目录（不是 `.git` 本身）
|
||
- 路径必须是本地绝对路径
|
||
- Docker 模式下需要将 Git 仓库目录挂载到容器中
|
||
|
||
### Q: AI 分析报错？
|
||
|
||
- 检查 API Key 是否正确
|
||
- 确认网络可以访问 api.deepseek.com
|
||
- 检查 DeepSeek 账户余额是否充足
|
||
|
||
### Q: 生成的报表在哪里？
|
||
|
||
- 默认在程序目录下的 `outputs/` 文件夹
|
||
- `outputs/md/` 存放 Markdown 报表
|
||
- `outputs/excel/` 存放 Excel 工作量统计
|
||
- 也可在 Web 工作台的「任务历史」页面直接下载
|
||
|
||
### Q: 如何修改端口？
|
||
|
||
在 jar 同目录下创建 `application.properties` 文件：
|
||
|
||
```properties
|
||
server.port=8080
|
||
```
|
||
|
||
Docker 方式修改 `docker-compose.yml` 中的端口映射：
|
||
|
||
```yaml
|
||
ports:
|
||
- "8080:18088"
|
||
```
|