Metadata-Version: 2.4
Name: tsjiratool
Version: 1.3.0
Summary: JIRA 变更监控与报告导出工具 · 多实例同时监控 · SSO 浏览器登录 · 日报/周报导出
Author: hemin0721
License-Expression: MIT
Project-URL: Homepage, https://github.com/hemin0721/tsjiratool
Keywords: jira,monitor,notification,report
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Bug Tracking
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: schedule>=1.2.0
Requires-Dist: PySide6>=6.5.0
Requires-Dist: rookiepy>=0.5.6
Requires-Dist: pycryptodome>=3.19.0
Requires-Dist: secretstorage>=3.3.0; sys_platform == "linux"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: pytest; extra == "dev"

# JiraTool

JIRA 变更监控与报告导出工具。支持多实例同时监控、SSO 浏览器登录、飞书/企业微信/桌面通知、日报/周报 Markdown/CSV 导出。

## 安装

```bash
pip install jiratool
```

从源码安装:

```bash
git clone <repo-url>
cd jiratool
pip install .
```

## 使用

### GUI 模式（默认）

```bash
jiratool
# 或
python -m jiratool
```

### CLI 模式（无界面后台轮询，单实例）

```bash
jiratool --no-gui -c /path/to/config.yaml
```

## 功能

- **多 JIRA 实例同时监控**：所有启用实例并行轮询，Issue 列表增加实例来源列，可用下拉框按实例筛选
- **SSO 浏览器登录**：走公司 SSO 认证的 JIRA 无需 PAT，在系统浏览器完成登录后自动捕获会话 Cookie；后台定期保活避免频繁重新登录
- **实例启用/停用**：临时离开某项目时可停用实例（配置保留），随时重新启用
- **退出登录**：一键清除实例的 SSO 会话；菜单栏"文件 → 退出程序"提供明确的退出入口
- 实时变更监控（状态、评论、指派、优先级），通知按实例分组、链接指向对应 JIRA
- 桌面通知 (Linux notify-send / macOS osascript)
- 飞书 Webhook 通知
- 企业微信 Webhook 通知
- 日报/周报/自定义范围报告导出（Markdown / CSV，支持多实例分节）
- 本周任务一键查询（覆盖全部启用实例）
- 双击 Issue 直接跳转浏览器（使用该行所属实例的 URL）
- 系统托盘常驻

## 配置

首次运行前，在工作目录创建 `config.yaml`（参考 `config.yaml.example`）:

```yaml
jira_instances:
  # PAT 认证实例（默认）
  - name: "MyJira"
    base_url: "https://jira.example.com"
    auth_mode: "pat"            # pat | sso，缺省 pat
    api_token: "YOUR_TOKEN"
    username: "your_username"
    poll_interval: 120
    enabled: true               # 停用后保留配置但不监控
    jql_filters:
      - "assignee = %USERNAME% AND updated >= -1d ORDER BY updated DESC"

  # SSO 认证实例（Cookie 会话保存在 ~/.tsjiratool/sessions/，不写入本文件）
  - name: "SSOJira"
    base_url: "https://jira.company.com"
    auth_mode: "sso"
    username: ""                # 登录成功后自动获取
    poll_interval: 300
    enabled: true
    jql_filters:
      - "assignee = %USERNAME% AND updated >= -1d ORDER BY updated DESC"
```

## SSO 登录说明

适用于 JIRA 前面有公司 SSO（如 Okta / Azure AD / 钉钉等）、无法使用 Personal Access Token 的场景：

1. 设置页选中实例，"认证方式"选择 **SSO 浏览器登录**，填写 Base URL；
2. 点击 **浏览器登录…**，工具会打开系统默认浏览器；
3. 在浏览器中完成 SSO 登录，回到工具等待自动检测（每 2 秒检查一次，最多 10 分钟）；
4. 检测成功后会话自动保存到 `~/.tsjiratool/sessions/{实例名}.json`（权限 600），重启无需重新登录；
5. SSO 会话过期时状态栏提示，并可一键重新登录；**退出登录**按钮清除会话（实例配置保留）。

### SSO 会话保活（避免频繁重新登录）

工具运行期间默认每 5 分钟对所有已登录的 SSO 实例发送一次轻量请求（`GET /rest/api/2/myself`），避免服务端会话因闲置过期；同时把服务器轮换/续期后的最新 Cookie 自动同步回会话文件。**即使没有启动监控，保活也在后台运行**（对停用的实例同样生效，回到旧项目时无需重新登录）。

设置页"保持 SSO 会话活跃"可开关该功能并调整间隔；配置文件对应：

```yaml
sso:
  keepalive: true          # 关闭后不再后台保活
  keepalive_interval: 300  # 保活间隔（秒），需小于服务端会话闲置超时
```

> 注意：保活对"闲置超时"型会话（滑动过期）有效；若公司 SSO 配置了强制绝对过期时间（无论是否活跃到点必失效），则到期仍需重新登录，可用"手动粘贴 Cookie"快速恢复。

Cookie 自动捕获在 Linux 上使用工具内置的读取器（不依赖 rookiepy），支持 Firefox / Chrome / Edge / Chromium / Brave / Vivaldi / Opera 等，全程静默读取：密钥环只读已解锁的集合，**不访问 KDE 钱包、不弹出任何系统窗口**。可在设置页选择 **Cookie 浏览器**（配置 `sso.browser`）：

- **自动检测（默认）**：按 Firefox → Chrome → Edge → … 顺序探测，**哪个浏览器的 Cookie 能通过 JIRA 认证就用哪个**（某浏览器里只有过期 Cookie 也不会挡住其他浏览器）
- **指定浏览器**（如 Chrome / Edge / Firefox）：只从该浏览器读取，并且登录页也优先用该浏览器打开

其他平台（Windows / macOS）回退 [rookiepy](https://pypi.org/project/rookiepy/)。

注意事项：

- **Linux / Chrome / Edge**：Cookie 加密密钥存在系统密钥环（GNOME Keyring / KWallet）。桌面登录时密钥环通常已自动解锁，工具**静默**读取，无任何弹窗；若密钥环处于锁定状态，工具会放弃读取（不触发解锁弹窗），此时可用"手动粘贴 Cookie"兜底
- **macOS / Windows**：走 Keychain / DPAPI，无额外弹窗
- 自动捕获失败时可用 **手动粘贴 Cookie** 兜底：浏览器 F12 → Network → 任选请求 → 复制请求头中 `cookie:` 的整行值粘贴

## 退出程序

- 关闭主窗口时若系统托盘可用，会询问"最小化到托盘 / 退出程序"；
- 托盘不可用的桌面环境（如 GNOME 未装托盘扩展）关闭窗口即退出；
- 也可使用菜单栏 **文件 → 退出程序**（Ctrl+Q）或托盘菜单 **退出**。

## 依赖

- Python >= 3.9
- PySide6 >= 6.5.0
- requests >= 2.28.0
- PyYAML >= 6.0
- schedule >= 1.2.0
- rookiepy >= 0.5.6（SSO Cookie 自动捕获，可选）

## License

MIT
