Files
tjhlp-gitea/scripts/README.md
T
jkljkluiouio 20d6d7eef5 docs: 更新README文档内容
- 移除邮件通知功能相关描述
- 修正用户创建时的密码策略说明
- 优化文档结构,删除重复内容
- 添加cmd环境下的命令示例
- 更新测试文件列表
2026-04-23 22:43:22 +08:00

290 lines
8.9 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 批量创建账号(初始密码与用户名相同)
│ ├── 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
```
`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`
- **初始密码与用户名(学号/工号)相同**
示例文件见 `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 # 全部测试
uv run pytest tests/test_models.py # 只运行模型测试
uv run pytest tests/ -k "password" # 按名称过滤
```
### 覆盖率报告
```bash
uv run pytest tests/ --cov=tjhlp --cov-report=term-missing
```
### 代码检查
```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/) | 代码检查与格式化 |