LiuMangMang/svn-log-tool

Fork 0

Files

T

liumangmang e9a75c14dd refactor: remove frontend and keep backend-only build

2026-04-22 14:55:24 +08:00

6.0 KiB

Raw Blame History

SVN/Git 日报周报月报一键生成 - 用户手册

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 方式

# 进入 docker 发行包目录
cd release/docker

# 一键启动
docker compose up -d

# 查看状态
docker compose ps

# 停止服务
docker compose down

启动后浏览器访问：http://localhost:18088

3.2 Windows 方式

解压发行包到任意目录
双击 start.bat
等待控制台显示启动成功
浏览器访问：http://localhost:18088

3.3 macOS / Linux 方式

# 进入 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

访问 https://platform.deepseek.com
注册账号并登录
进入「API Keys」页面
创建新的 API Key
复制 Key（格式为 sk-...）

5.2 配置 API Key

方式一：Web 设置页

在「系统设置」页面填入 API Key 并保存。

方式二：环境变量

export DEEPSEEK_API_KEY=sk-your-key-here

Docker 方式可在 docker-compose.yml 中配置：

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 文件：

server.port=8080

Docker 方式修改 docker-compose.yml 中的端口映射：

ports:
  - "8080:18088"

6.0 KiB Raw Blame History Unescape Escape