Files
tjhlp-gitea/scripts
jkljkluiouio b8220a97c4 feat(users): 为用户创建命令添加随机密码生成和凭据导出功能
- 将初始密码从固定用户名改为随机生成
- 添加 CredentialRecord 数据结构记录创建结果
- 实现凭据 CSV 自动导出功能
- 更新相关文档说明
2026-04-29 13:44:00 +08:00
..
2026-04-12 23:24:13 +08:00
2026-04-12 23:24:13 +08:00
2026-04-12 23:24:13 +08:00
2026-04-12 23:24:13 +08:00

Python CLI 管理工具

tjhlp 是课程答疑平台的命令行管理工具, 通过 Gitea REST API 批量管理用户、组织、仓库、Webhook、Label, 并提供 Issue 统计功能。

前置要求

  • Python >= 3.14
  • uv

安装

cd scripts
uv sync

安装后即可使用 uv run tjhlp 调用。

配置

基础配置 (settings.toml)

已随项目提供, 包含默认值和预定义 Label 集合。一般无需修改。

敏感配置 (.secrets.toml)

cp .secrets.toml.example .secrets.toml

编辑 .secrets.toml, 填入实际值:

[default.gitea]
token = "your-gitea-api-token"    # 必填

API Token 获取方式: 登录 Gitea -> 设置 -> 应用 -> 生成令牌(勾选所有权限)。

.secrets.toml 已在 .gitignore 中排除, 不会被提交。

环境变量覆盖

所有配置项均可通过 TJHLP_ 前缀的环境变量覆盖:

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

典型工作流

学期初始化

# 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 可直接复制的写法:

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

每次布置作业

uv run tjhlp repos create-homework \
  --org tjhlp-2025f \
  --number 3 \
  --desc "作业3: 链表操作" \
  --webhook-url http://notify-server:8080/webhook

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 团队。

日常管理

# 查看 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

学期结束清理

uv run tjhlp users delete --file members.csv --yes

CSV 格式

输入: members.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 蓝色 常见问题
课程内容 粉紫 课程知识点相关
编程作业 浅红 编程作业相关
环境配置 浅青 环境配置相关
紧急 红色 需要尽快回复

测试

安装开发依赖

uv sync --extra dev

运行测试

uv run pytest tests/ -v              # 全部测试
uv run pytest tests/test_models.py   # 只运行模型测试
uv run pytest tests/ -k "password"   # 按名称过滤

覆盖率报告

uv run pytest tests/ --cov=tjhlp --cov-report=term-missing

代码检查

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 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 CLI 框架
httpx HTTP 客户端(调用 Gitea API)
Rich 终端美化(表格、颜色、进度)
Pydantic 数据校验、配置模型
Dynaconf 配置管理(TOML + 环境变量 + secrets 分离)
pytest 测试框架
respx httpx mock 库(API 客户端测试)
ruff 代码检查与格式化