npm package: @jixuyu/daily-report
Description: 基于 Git 提交的日报生成与推送 CLI
Author: jixuyu
Latest version: 1.0.3

# daily-report-cli

基于 Git 提交记录生成日报并支持钉钉推送的命令行工具。

## 功能特点

- 自动从 Git 提交记录中提取当天工作内容
- 智能去重和格式化提交信息
- 支持发送到钉钉机器人（带签名验证）
- 多种配置方式：命令行参数、项目配置、用户配置、环境变量
- 支持 @ 指定成员或 @ 所有人
- 支持自定义时间范围和模板

## 安装

### 全局安装

```bash
npm install -g @jixuyu/daily-report
```

### 本地安装（推荐用于团队项目）

```bash
npm install --save-dev @jixuyu/daily-report
```

**注意**：本地安装后，`daily-report` 命令不在全局 PATH 中，需要通过以下方式之一运行：

#### 方式 1：使用 npx（推荐）

```bash
npx daily-report
```

#### 方式 2：使用 npm scripts

在 `package.json` 中添加：

```json
{
  "scripts": {
    "report": "daily-report --send"
  }
}
```

然后运行：

```bash
npm run report
```

#### 方式 3：使用相对路径

```bash
./node_modules/.bin/daily-report
```

## 快速开始

### 1. 基础使用

生成日报（仅在控制台显示）：

**全局安装：**
```bash
daily-report
```

**本地安装：**
```bash
npx daily-report
```

### 2. 发送到钉钉

首次使用时，初始化配置：

**全局安装：**
```bash
daily-report --init --webhook https://oapi.dingtalk.com/robot/send?access_token=xxx --secret SECxxx
```

**本地安装：**
```bash
npx daily-report --init --webhook https://oapi.dingtalk.com/robot/send?access_token=xxx --secret SECxxx
```

然后发送日报：

**全局安装：**
```bash
daily-report --send
```

**本地安装：**
```bash
npx daily-report --send
# 或使用 npm script
npm run report
```

### 3. 指定作者

```bash
daily-report --author "张三" --send
```

### 4. @ 指定成员

```bash
daily-report --send --mobile 13800138000,13900139000
```

## 配置方式

该工具支持多种配置方式，优先级从高到低：

1. **命令行参数** - 通过 `--webhook`、`--secret`、`--at-all` 等参数
2. **环境变量** - `DAILY_REPORT_WEBHOOK`、`DAILY_REPORT_SECRET`、`DAILY_REPORT_AT_ALL`
3. **项目配置** - `.daily-reportrc.json` 或 `package.json` 中的 `dailyReport` 字段
4. **用户配置** - `~/.daily-report/config.json`

### 方式一：用户级配置（推荐个人使用）

通过 `--init` 命令初始化：

```bash
daily-report --init --webhook https://oapi.dingtalk.com/robot/send?access_token=xxx --secret SECxxx
```

配置会保存在 `~/.daily-report/config.json`，后续使用时无需重复配置。

### 方式二：项目级配置（推荐团队使用）

在项目根目录创建 `.daily-reportrc.json`：

```json
{
  "webhook": "https://oapi.dingtalk.com/robot/send?access_token=xxx",
  "secret": "SECxxx",
  "atAll": false
}
```

或在 `package.json` 中添加：

```json
{
  "dailyReport": {
    "webhook": "https://oapi.dingtalk.com/robot/send?access_token=xxx",
    "secret": "SECxxx",
    "atAll": false
  }
}
```

### 方式三：环境变量

```bash
export DAILY_REPORT_WEBHOOK="https://oapi.dingtalk.com/robot/send?access_token=xxx"
export DAILY_REPORT_SECRET="SECxxx"
export DAILY_REPORT_AT_ALL="false"

daily-report --send
```

### 方式四：命令行参数

```bash
daily-report --send --webhook https://oapi.dingtalk.com/robot/send?access_token=xxx --secret SECxxx
```

## 命令行参数

| 参数 | 简写 | 说明 | 默认值 |
|------|------|------|--------|
| `--author` | `-a` | 指定 Git 提交作者 | 读取 `git config user.name` |
| `--mobile` | `-m` | @ 手机号，多个用逗号分隔 | - |
| `--template` | `-t` | 报告模板/标题 | `日报` |
| `--send` | - | 发送到钉钉 | `false` |
| `--dry-run` | - | 仅打印 payload，不实际发送 | `false` |
| `--since` | - | 提交时间范围 | `midnight` |
| `--no-team` | - | 个人提交为 0 时不显示团队提交 | `false` |
| `--webhook` | - | 钉钉机器人 webhook | 从配置读取 |
| `--secret` | - | 钉钉机器人密钥 | 从配置读取 |
| `--at-all` | - | @ 所有人 | `false` |
| `--init` | - | 初始化用户配置 | - |
| `--verbose` | `-v` | 显示详细信息（包括配置来源） | `false` |
| `--help` | `-h` | 显示帮助信息 | - |

### 时间范围示例

- `midnight` - 今天 00:00 至今（默认）
- `yesterday` - 昨天 00:00 至今
- `1.day` - 最近 1 天
- `1.week` - 最近 1 周
- `2024-12-20` - 指定日期至今

更多格式参考 [git log --since](https://git-scm.com/docs/git-log#Documentation/git-log.txt---sinceltdategt)。

## 使用场景

### 场景 1：个人日报（全局安装）

```bash
# 全局安装
npm install -g @jixuyu/daily-report

# 初始化配置（仅首次）
daily-report --init --webhook YOUR_WEBHOOK --secret YOUR_SECRET

# 每天下班前运行
daily-report --send
```

### 场景 2：团队项目（本地安装）

1. 安装依赖：

```bash
npm install --save-dev @jixuyu/daily-report
```

2. 在项目中添加 `.daily-reportrc.json`：

```json
{
  "webhook": "https://oapi.dingtalk.com/robot/send?access_token=xxx",
  "secret": "SECxxx"
}
```

3. 在 `package.json` 添加脚本：

```json
{
  "scripts": {
    "report": "daily-report --send",
    "report:init": "daily-report --init"
  },
  "devDependencies": {
    "@jixuyu/daily-report": "^1.0.1"
  }
}
```

4. 团队成员使用：

```bash
# 首次使用（如果没有项目配置文件）
npm run report:init -- --webhook YOUR_WEBHOOK --secret YOUR_SECRET

# 每天提交日报
npm run report

# 或使用 npx
npx daily-report --send
```

### 场景 3：定时任务（CI/CD）

在 GitHub Actions、GitLab CI 或 crontab 中配置：

```yaml
# .github/workflows/daily-report.yml
name: Daily Report
on:
  schedule:
    - cron: '0 10 * * *'  # 每天 18:00 (UTC+8)
  workflow_dispatch:

jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0  # 获取完整 Git 历史
      - uses: actions/setup-node@v3
      - run: npm install -g @jixuyu/daily-report
      - run: daily-report --send
        env:
          DAILY_REPORT_WEBHOOK: ${{ secrets.DINGTALK_WEBHOOK }}
          DAILY_REPORT_SECRET: ${{ secrets.DINGTALK_SECRET }}
```

### 场景 4：查看团队日报

当个人提交为空时，默认会展示团队所有成员的提交：

```bash
daily-report --author "张三"
```

如果不想看团队提交：

```bash
daily-report --author "张三" --no-team
```

## 钉钉机器人配置

1. 在钉钉群中添加自定义机器人
2. 选择安全设置 - 加签
3. 复制 webhook 地址和加签密钥（Secret）
4. 配置到工具中

## 常见问题

### Q: 本地安装后提示"daily-report 命令不存在"怎么办？

A: 本地安装（`npm install --save-dev`）的包不会添加到全局 PATH 中，需要使用以下方式之一：

**方式 1：使用 npx（推荐）**
```bash
npx daily-report --init --webhook URL --secret SECxxx
npx daily-report --send
```

**方式 2：使用 npm scripts**

在 `package.json` 中添加：
```json
{
  "scripts": {
    "report:init": "daily-report --init",
    "report": "daily-report --send"
  }
}
```

然后运行：
```bash
npm run report:init -- --webhook URL --secret SECxxx
npm run report
```

**方式 3：使用相对路径**
```bash
./node_modules/.bin/daily-report --init --webhook URL --secret SECxxx
```

### Q: 如何获取钉钉 webhook 和 secret？

A: 在钉钉群设置 → 智能群助手 → 添加机器人 → 自定义，选择"加签"安全方式，复制 webhook URL 和 SEC 开头的密钥。

### Q: 提示"缺少提交人"怎么办？

A: 确保在 Git 仓库中运行，或通过 `--author` 参数指定作者名称。

### Q: 如何测试配置是否正确？

A: 使用 `--dry-run` 参数查看将要发送的内容：

```bash
daily-report --send --dry-run
```

### Q: 如何查看配置是从哪里读取的？

A: 使用 `--verbose` 或 `-v` 参数查看配置来源：

```bash
daily-report --send --dry-run --verbose
```

输出示例：
```
[配置信息]
Webhook: https://oapi.dingtalk.com/robot/send?access_token=... (来源: 项目配置)
Secret: SECxxx... (来源: 项目配置)
@所有人: false (来源: 项目配置)
```

配置优先级：命令行参数 > 环境变量 > 项目配置 > 用户配置

### Q: 团队项目推荐使用哪种配置方式？

A: **推荐使用项目配置**（`.daily-reportrc.json` 或 `package.json`），这样团队成员无需单独配置：

**方式 1：创建 `.daily-reportrc.json`（推荐）**
```json
{
  "webhook": "https://oapi.dingtalk.com/robot/send?access_token=xxx",
  "secret": "SECxxx",
  "atAll": false
}
```

**方式 2：在 `package.json` 中添加**
```json
{
  "dailyReport": {
    "webhook": "https://oapi.dingtalk.com/robot/send?access_token=xxx",
    "secret": "SECxxx",
    "atAll": false
  }
}
```

然后团队成员只需运行：
```bash
npx daily-report --send
# 或
npm run report
```

### Q: 支持哪些环境变量？

A: 支持以下环境变量（优先级高于项目配置，低于命令行参数）：

- `DAILY_REPORT_WEBHOOK` 或 `DINGTALK_WEBHOOK` - webhook 地址
- `DAILY_REPORT_SECRET` 或 `DINGTALK_SECRET` - 密钥
- `DAILY_REPORT_AT_ALL` - 是否 @ 所有人（true/false/1/0/yes/no/y/n）

示例：
```bash
export DAILY_REPORT_WEBHOOK="https://oapi.dingtalk.com/robot/send?access_token=xxx"
export DAILY_REPORT_SECRET="SECxxx"
npx daily-report --send
```

## License

MIT

## 贡献

欢迎提交 Issue 和 Pull Request！

## 更新日志

### 1.0.1

- **修复**：项目配置文件（`.daily-reportrc.json` 或 `package.json`）未生效的问题
- **新增**：`--verbose/-v` 参数，显示配置来源，方便调试
- **改进**：更清晰的错误提示信息，列出所有配置方式
- **改进**：配置优先级逻辑优化，确保按预期顺序读取配置
- **文档**：完善本地安装使用说明（npx、npm scripts）
- **文档**：新增配置调试和故障排查指南

### 1.0.0

- 初始版本
- 基础日报生成和钉钉推送功能
- 支持多种配置方式