# 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 └── labels ├── sync 同步预定义 Label 到仓库 └── list 列出仓库 Label ``` ## 典型工作流 ### 学期初始化 ```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 ``` ## 典型工作流 ### 学期初始化 ```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 # 4. 发送账号密码邮件 uv run tjhlp notify send-credentials --file credentials_20250901_120000.csv # 5. (可选)先预览邮件, 不实际发送 uv run tjhlp notify send-credentials --file credentials_*.csv --dry-run ``` ### 每次布置作业 ```bash 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 ``` ### 显示名维护(学号-姓名) Issue 页显示的是 `full_name`。OIDC 登录时会把 `full_name` 覆盖成认证源 `FullNameClaimName` 对应的 claim(`display_name` = `学号-姓名`),因此**存量用户 需要重新登录**才会刷新。若不想等用户重登,用 `tools/fix_full_name.py` 直接刷一遍: ```bash export TJHLP_GITEA_TOKEN= # 或建 scripts/.secrets.toml uv run python tools/fix_full_name.py # dry-run,只打印 uv run python tools/fix_full_name.py --apply # 实际写入 ``` 脚本只改 `full_name`(成 `学号-姓名`),不动用户名/邮箱和团队归属;默认跳过 `admin`。 ### 学期结束清理 ```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_pure_functions.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/) | 代码检查与格式化 |