Metadata-Version: 2.4
Name: qzhuli-hr-cli
Version: 0.0.4
Summary: Local QR authorization CLI for Qzhuli HR workflows
Author: Qzhuli HR
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: cryptography>=41

# Q助理 HR CLI

`qzhuli-hr-cli` 是 Q助理 HR 的命令行桥接工具。支持本地扫码授权、第三方 middleware UID 登录、加密保存本地凭据，以及安全提交和查询 HR 审批。

## 功能

- 使用 Q助理扫码登录，凭据用 Fernet 加密保存在本地。
- 上游环境已提供 middleware token 和 Q助理 uid 时，可用 `middleware-login` 登录。
- 从标准输入读取 JSON，校验并提交审批。
- 上传报销附件。
- 查询员工、假期余额、零散余额、工资、补贴、排班、部门、公司和审批状态。
- 默认操作账号最后使用的公司，可用 `switch-company --company-id <id>` 切换。

## 支持的审批类型

- 请假（`leave`），含运营部零散请假
- 加班（`overtime`）
- 补贴（`subsidy`）
- 离职（`resignation`）
- 转正（`regularization`）
- 付款（`payment`）
- 用印（`seal`）
- 报销（`reimbursement`）

补贴类型支持 AI 工具补贴、拍摄补贴、办税补贴。审批通过后，HR 服务会同步到月度补贴和工资数据。

完整命令和表单字段见仓库根目录 [`docs/cli.md`](../docs/cli.md)。

## 安装

```bash
pip install qzhuli-hr-cli
```

要求 Python 3.10 或更高版本。

本地开发可在 `qzhuli-hr-cli` 目录安装：

```bash
python -m pip install -e .
```

## 使用

查看当前 API 配置：

```bash
qzhuli-hr-cli config
```

扫码登录：

```bash
qzhuli-hr-cli login
```

校验审批 JSON：

```bash
qzhuli-hr-cli validate < approval.json
```

提交审批：

```bash
qzhuli-hr-cli submit < approval.json
```

查询本人发起的审批：

```bash
qzhuli-hr-cli approvals --status pending --limit 10
```

查询假期余额、零散余额、工资和补贴：

```bash
qzhuli-hr-cli leave-balances --year 2026
qzhuli-hr-cli scattered-balance
qzhuli-hr-cli payroll --month 2026-07
qzhuli-hr-cli subsidies --month 2026-06
```

Windows PowerShell 从文件提交示例：

```powershell
Get-Content .\leave.json -Raw | qzhuli-hr-cli submit
```

## 补贴申请示例

```json
{
  "type": "subsidy",
  "form": {
    "subsidyType": "ai_tool",
    "amount": 200,
    "occurredOn": "2026-06-23",
    "description": "AI 工具订阅"
  }
}
```

`subsidyType` 支持 `ai_tool`、`shooting`、`tax_clerk`，也可用中文 `AI工具补贴`、`拍摄补贴`、`办税补贴`。

## 配置

常用环境变量：

- `QZHULI_HR_API_ENV`：`production` 或 `test`。
- `QZHULI_HR_API_BASE_URL`：自定义 HR API 地址。
- `QZHULI_HR_CREDENTIAL_DIR`：可选。未设置时，凭据目录是当前工作目录下的 `.qzhuli-hr-cli`。
- `QZHULI_HR_MIDDLEWARE_TOKEN`：middleware 登录 token。

默认连接正式环境 `https://hr.qzhuli.com/api/v1`。测试环境设置 `QZHULI_HR_API_ENV=test`。

## 安全

不要把 access token 写进审批 JSON。CLI 会读取本地加密凭据，并在内部发送鉴权请求头。

## 发布到 PyPI

在 `qzhuli-hr-cli` 目录执行。发布前先改版本号，并确认工作区没有未提交的关键改动。

1. 同步版本号：同时修改 `pyproject.toml` 的 `version` 和 `src/qzhuli_hr_cli/__init__.py` 的 `__version__`。PyPI 不允许覆盖已发布版本。
2. 安装构建和上传工具：

   ```bash
   python -m pip install --upgrade build twine
   ```

3. 清理旧的构建产物。PowerShell：

   ```powershell
   Remove-Item -Recurse -Force dist, build -ErrorAction SilentlyContinue
   Get-ChildItem -Recurse -Filter "*.egg-info" | Remove-Item -Recurse -Force
   ```

   bash：

   ```bash
   rm -rf dist build src/*.egg-info
   ```

4. 构建 sdist 和 wheel：

   ```bash
   python -m build
   ```

5. 检查包元数据和 README：

   ```bash
   python -m twine check dist/*
   ```

6. 建议先发到 TestPyPI 验证：

   ```bash
   python -m twine upload --repository testpypi dist/*
   python -m pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple qzhuli-hr-cli
   ```

7. 确认无误后再发布到正式 PyPI：

   ```bash
   python -m twine upload dist/*
   ```

上传需要 PyPI API token。用户名固定为 `__token__`，密码为 `pypi-` 开头的 token：

```bash
python -m twine upload dist/* -u __token__ -p pypi-你的token
```

也可以写入用户目录下的 `.pypirc`，或设置环境变量 `TWINE_USERNAME=__token__` 和 `TWINE_PASSWORD`。TestPyPI 的 token 需要在 <https://test.pypi.org> 单独创建。
