# 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"
```