SHA256
deploy / deploy (push) Successful in 25s
Issue 页的作者名走 User.GetDisplayName(), 默认返回 login(学号), 看不到老师/助教认得的姓名。打开站点级开关 [ui] DEFAULT_SHOW_FULL_NAME 后改为显示 full_name, 未填姓名的用户回退学号。 配合 OIDC 侧把 full_name 覆盖成 display_name(学号-姓名), 即可同时 显示学号与姓名; 存量用户需重新登录才会刷新, 见 scripts/README.md。 - deploy/compose.yaml: GITEA__ui__DEFAULT_SHOW_FULL_NAME=true - customization/preview/compose.yaml: 同步, 便于预览验证 - customization/README.md: 配置表 / 环境变量片段 / 已验证清单 - scripts/settings.toml: CLI 调 API 的地址改为宿主回环 127.0.0.1:2080 (10.80.42.185:3000 未对外开放, 上层反代返回 502) 已在预览实例(Gitea 1.27.3)验证: 「由 X 创建」与正文/评论作者 均显示 full_name。
319 lines
9.9 KiB
Markdown
319 lines
9.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
|
|
└── 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=<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/) | 代码检查与格式化 |
|