SHA256
- 在测试中增加对凭据导出的验证 - 使用更安全的随机密码生成 - 添加对创建失败情况的测试覆盖 - 更新文档中的测试命令以包含临时目录参数 - 将临时测试目录添加到.gitignore
292 lines
9.1 KiB
Markdown
292 lines
9.1 KiB
Markdown
# Python CLI 管理工具
|
|
|
|
`tjhlp` 是课程答疑平台的命令行管理工具, 通过 Gitea REST API 批量管理用户、组织、仓库、Webhook、Label, 并提供 Issue 统计功能。
|
|
|
|
## 前置要求
|
|
|
|
- Python >= 3.14
|
|
- [uv](https://docs.astral.sh/uv/)
|
|
|
|
## 安装
|
|
|
|
```bash
|
|
cd scripts
|
|
uv sync
|
|
```
|
|
|
|
安装后即可使用 `uv run tjhlp` 调用。
|
|
|
|
## 配置
|
|
|
|
### 基础配置 (`settings.toml`)
|
|
|
|
已随项目提供, 包含默认值和预定义 Label 集合。一般无需修改。
|
|
|
|
### 敏感配置 (`.secrets.toml`)
|
|
|
|
```bash
|
|
cp .secrets.toml.example .secrets.toml
|
|
```
|
|
|
|
编辑 `.secrets.toml`, 填入实际值:
|
|
|
|
```toml
|
|
[default.gitea]
|
|
token = "your-gitea-api-token" # 必填
|
|
```
|
|
|
|
API Token 获取方式: 登录 Gitea -> 设置 -> 应用 -> 生成令牌(勾选所有权限)。
|
|
|
|
`.secrets.toml` 已在 `.gitignore` 中排除, 不会被提交。
|
|
|
|
### 环境变量覆盖
|
|
|
|
所有配置项均可通过 `TJHLP_` 前缀的环境变量覆盖:
|
|
|
|
```bash
|
|
export TJHLP_GITEA_URL=http://192.168.1.100:3000
|
|
export TJHLP_GITEA_TOKEN=your-token
|
|
```
|
|
|
|
## 命令一览
|
|
|
|
```
|
|
tjhlp
|
|
├── setup
|
|
│ ├── init 一键初始化: 创建组织/团队/仓库/Labels/Webhook
|
|
│ └── status 检查 Gitea 连接状态
|
|
├── users
|
|
│ ├── create 从 CSV 批量创建账号(随机初始密码, 自动导出凭据 CSV)
|
|
│ ├── list 列出所有用户
|
|
│ └── delete 批量删除用户
|
|
├── orgs
|
|
│ ├── create 创建组织
|
|
│ ├── create-team 创建团队
|
|
│ ├── add-members 批量添加成员到团队
|
|
│ └── list-teams 列出组织下的团队
|
|
├── repos
|
|
│ ├── create 创建仓库
|
|
│ ├── create-homework 创建作业仓库(自动推送模板/Labels/Webhook)
|
|
│ ├── init-templates 推送 Issue Templates 到仓库
|
|
│ └── configure 配置仓库设置
|
|
├── webhooks
|
|
│ ├── create 创建 Webhook
|
|
│ ├── list 列出 Webhook
|
|
│ ├── test 测试 Webhook
|
|
│ └── delete 删除 Webhook
|
|
├── labels
|
|
│ ├── sync 同步预定义 Label 到仓库
|
|
│ └── list 列出仓库 Label
|
|
└── stats
|
|
├── summary Issue 统计摘要
|
|
└── export 导出 Issue 数据到 CSV
|
|
```
|
|
|
|
## 典型工作流
|
|
|
|
### 学期初始化
|
|
|
|
```bash
|
|
# 1. 检查连接
|
|
uv run tjhlp setup status
|
|
|
|
# 2. 一键初始化(创建组织 + 团队 + general 仓库 + Labels + Webhook)
|
|
uv run tjhlp setup init \
|
|
--org tjhlp-2025f \
|
|
--webhook-url http://notify-server:8080/webhook \
|
|
--webhook-secret mysecret
|
|
|
|
# 3. 批量创建用户并分配到团队
|
|
uv run tjhlp users create --file members.csv --org tjhlp-2025f
|
|
```
|
|
|
|
执行完成后会自动生成 `credentials_YYYYMMDD_HHMMSS.csv`, 包含账号、随机初始密码和处理状态。
|
|
|
|
`cmd` 可直接复制的写法:
|
|
|
|
```cmd
|
|
uv run tjhlp setup status
|
|
uv run tjhlp setup init --org tjhlp-2025f --webhook-url http://notify-server:8080/webhook --webhook-secret mysecret
|
|
uv run tjhlp users create --file members.csv --org tjhlp-2025f
|
|
```
|
|
|
|
### 每次布置作业
|
|
|
|
```bash
|
|
uv run tjhlp repos create-homework \
|
|
--org tjhlp-2025f \
|
|
--number 3 \
|
|
--desc "作业3: 链表操作" \
|
|
--webhook-url http://notify-server:8080/webhook
|
|
```
|
|
|
|
`cmd` 可直接复制的写法:
|
|
|
|
```cmd
|
|
uv run tjhlp repos create-homework --org tjhlp-2025f --number 3 --desc "作业3: 链表操作" --webhook-url http://notify-server:8080/webhook
|
|
```
|
|
|
|
这会自动完成: 创建 `hw03` 仓库 -> 推送作业 Issue Template -> 同步 Labels -> 配置 Webhook -> 添加到 ta/students 团队。
|
|
|
|
### 日常管理
|
|
|
|
```bash
|
|
# 查看 Issue 统计
|
|
uv run tjhlp stats summary tjhlp-2025f/general
|
|
|
|
# 导出 Issue 数据
|
|
uv run tjhlp stats export tjhlp-2025f/hw03 --output hw03_issues.csv
|
|
|
|
# 同步 Label 到新仓库
|
|
uv run tjhlp labels sync tjhlp-2025f/hw03
|
|
|
|
# 查看 Webhook 状态
|
|
uv run tjhlp webhooks list tjhlp-2025f/general
|
|
```
|
|
|
|
### 学期结束清理
|
|
|
|
```bash
|
|
uv run tjhlp users delete --file members.csv --yes
|
|
```
|
|
|
|
## CSV 格式
|
|
|
|
### 输入: `members.csv`
|
|
|
|
```csv
|
|
id,name,role
|
|
2659999,赵一伤,student
|
|
2659876,钱二败,student
|
|
10001,李四催,ta
|
|
```
|
|
|
|
- `id` - 学号或工号, 同时作为 Gitea 用户名
|
|
- `name` - 姓名, 作为 Gitea 的 `full_name`
|
|
- `role` - `student` 或 `ta`, 决定分配到哪个团队
|
|
- 邮箱自动生成为 `{id}@tongji.edu.cn`
|
|
- 初始密码由程序随机生成, `users create` 执行后会自动导出凭据 CSV
|
|
|
|
示例文件见 `example/members.csv`。
|
|
|
|
## 预定义 Label
|
|
|
|
通过 `settings.toml` 配置, `setup init` 和 `labels sync` 时自动创建:
|
|
|
|
| Label | 颜色 | 用途 |
|
|
|-------|------|------|
|
|
| `duplicate` | 灰色 | 助教标记重复问题 |
|
|
| `invalid` | 黄色 | 不符合提问规范 |
|
|
| `resolved` | 绿色 | 已解决 |
|
|
| `wontfix` | 白色 | 不予处理 |
|
|
| `good-question` | 紫色 | 优质问题 |
|
|
| `FAQ` | 蓝色 | 常见问题 |
|
|
| `课程内容` | 粉紫 | 课程知识点相关 |
|
|
| `编程作业` | 浅红 | 编程作业相关 |
|
|
| `环境配置` | 浅青 | 环境配置相关 |
|
|
| `紧急` | 红色 | 需要尽快回复 |
|
|
|
|
## 测试
|
|
|
|
### 安装开发依赖
|
|
|
|
```bash
|
|
uv sync --extra dev
|
|
```
|
|
|
|
### 运行测试
|
|
|
|
```bash
|
|
uv run pytest tests/ -v --basetemp .pytest_tmp # 全部测试
|
|
uv run pytest tests/test_models.py --basetemp .pytest_tmp # 只运行模型测试
|
|
uv run pytest tests/ -k "password" --basetemp .pytest_tmp # 按名称过滤
|
|
```
|
|
|
|
### 覆盖率报告
|
|
|
|
```bash
|
|
uv run pytest tests/ --cov=tjhlp --cov-report=term-missing --basetemp .pytest_tmp
|
|
```
|
|
|
|
### 代码检查
|
|
|
|
```bash
|
|
uv run ruff check src/
|
|
uv run ruff format --check src/
|
|
```
|
|
|
|
### 测试套件结构
|
|
|
|
```
|
|
tests/
|
|
├── conftest.py 公共 fixtures(mock config、client、样本数据)
|
|
├── test_models.py 数据模型(MemberRecord、Gitea API 模型、枚举)
|
|
├── test_config.py 配置校验(LabelDef 颜色、GiteaConfig 必填字段)
|
|
├── test_utils.py 工具函数(parse_repo、compute_issue_stats)
|
|
├── test_client.py API 客户端(respx mock HTTP, 分页、错误处理、CRUD)
|
|
└── test_commands.py 命令集成(CliRunner + mock, setup/users/repos 流程)
|
|
```
|
|
|
|
### 测试分层
|
|
|
|
| 层级 | 测试对象 | 方法 | 速度 |
|
|
| ------ | ---------- | ------ | ------ |
|
|
| 单元测试 | models, config, 纯函数 | 直接调用, 无 mock | 极快 |
|
|
| API 客户端测试 | client.py | [respx](https://lundberg.github.io/respx/) mock HTTP 层 | 快 |
|
|
| 命令集成测试 | commands/*.py | Typer CliRunner + mock GiteaClient | 快 |
|
|
| 端到端测试 | 完整流程 | 需要运行中的 Gitea 实例 | 慢(手动) |
|
|
|
|
当前 93 个测试用例, 核心模块覆盖率:
|
|
|
|
| 模块 | 覆盖率 | 说明 |
|
|
| ------ | -------- | ------ |
|
|
| `models.py` | 100% | 全部模型和 computed fields |
|
|
| `config.py` | 87% | Pydantic 校验逻辑(未覆盖 Dynaconf 加载函数) |
|
|
| `users.py` | 79% | 创建/跳过/删除流程 |
|
|
| `client.py` | 67% | 核心 HTTP 方法和分页(未覆盖所有 API endpoint) |
|
|
|
|
## 项目结构
|
|
|
|
```
|
|
scripts/
|
|
├── pyproject.toml 项目配置(Python >=3.14, 依赖声明)
|
|
├── settings.toml 默认配置 + 预定义 Label
|
|
├── .secrets.toml.example 敏感配置示例
|
|
├── example/
|
|
│ └── members.csv 示例成员名单
|
|
├── tests/ 测试套件
|
|
│ ├── conftest.py 公共 fixtures
|
|
│ ├── test_models.py 数据模型测试
|
|
│ ├── test_config.py 配置校验测试
|
|
│ ├── test_utils.py 工具函数测试
|
|
│ ├── test_client.py API 客户端测试
|
|
│ └── test_commands.py 命令集成测试
|
|
└── src/tjhlp/
|
|
├── cli.py Typer 主入口
|
|
├── config.py Dynaconf 加载 + Pydantic 校验
|
|
├── client.py Gitea REST API 客户端(自动分页/错误处理)
|
|
├── models.py 数据模型
|
|
├── utils.py 共享工具函数(parse_repo, push_templates 等)
|
|
└── commands/
|
|
├── setup.py 初始化命令
|
|
├── users.py 用户管理
|
|
├── orgs.py 组织/团队管理
|
|
├── repos.py 仓库管理
|
|
├── webhooks.py Webhook 管理
|
|
├── labels.py Label 管理
|
|
└── stats.py Issue 统计
|
|
```
|
|
|
|
## 技术选型
|
|
|
|
| 库 | 用途 |
|
|
| ---- | ------ |
|
|
| [Typer](https://typer.tiangolo.com/) | CLI 框架 |
|
|
| [httpx](https://www.python-httpx.org/) | HTTP 客户端(调用 Gitea API) |
|
|
| [Rich](https://rich.readthedocs.io/) | 终端美化(表格、颜色、进度) |
|
|
| [Pydantic](https://docs.pydantic.dev/) | 数据校验、配置模型 |
|
|
| [Dynaconf](https://www.dynaconf.com/) | 配置管理(TOML + 环境变量 + secrets 分离) |
|
|
| [pytest](https://docs.pytest.org/) | 测试框架 |
|
|
| [respx](https://lundberg.github.io/respx/) | httpx mock 库(API 客户端测试) |
|
|
| [ruff](https://docs.astral.sh/ruff/) | 代码检查与格式化 |
|