docs: 更新README文档内容

- 移除邮件通知功能相关描述
- 修正用户创建时的密码策略说明
- 优化文档结构,删除重复内容
- 添加cmd环境下的命令示例
- 更新测试文件列表
This commit is contained in:
2026-04-23 22:43:22 +08:00
parent 45dc819fda
commit 20d6d7eef5
+19 -34
View File
@@ -1,6 +1,6 @@
# Python CLI 管理工具 # Python CLI 管理工具
`tjhlp` 是课程答疑平台的命令行管理工具, 通过 Gitea REST API 批量管理用户、组织、仓库、Webhook、Label, 并提供 Issue 统计和邮件通知功能。 `tjhlp` 是课程答疑平台的命令行管理工具, 通过 Gitea REST API 批量管理用户、组织、仓库、Webhook、Label, 并提供 Issue 统计功能。
## 前置要求 ## 前置要求
@@ -28,7 +28,7 @@ uv sync
cp .secrets.toml.example .secrets.toml cp .secrets.toml.example .secrets.toml
``` ```
编辑 `.secrets.toml`, 填入实际值: 编辑 `.secrets.toml`, 填入实际值:
```toml ```toml
[default.gitea] [default.gitea]
@@ -41,7 +41,7 @@ API Token 获取方式: 登录 Gitea -> 设置 -> 应用 -> 生成令牌(勾选
### 环境变量覆盖 ### 环境变量覆盖
所有配置项均可通过 `TJHLP_` 前缀的环境变量覆盖: 所有配置项均可通过 `TJHLP_` 前缀的环境变量覆盖:
```bash ```bash
export TJHLP_GITEA_URL=http://192.168.1.100:3000 export TJHLP_GITEA_URL=http://192.168.1.100:3000
@@ -56,7 +56,7 @@ tjhlp
│ ├── init 一键初始化: 创建组织/团队/仓库/Labels/Webhook │ ├── init 一键初始化: 创建组织/团队/仓库/Labels/Webhook
│ └── status 检查 Gitea 连接状态 │ └── status 检查 Gitea 连接状态
├── users ├── users
│ ├── create 从 CSV 批量创建账号(随机密码) │ ├── create 从 CSV 批量创建账号(初始密码与用户名相同)
│ ├── list 列出所有用户 │ ├── list 列出所有用户
│ └── delete 批量删除用户 │ └── delete 批量删除用户
├── orgs ├── orgs
@@ -77,12 +77,9 @@ tjhlp
├── labels ├── labels
│ ├── sync 同步预定义 Label 到仓库 │ ├── sync 同步预定义 Label 到仓库
│ └── list 列出仓库 Label │ └── list 列出仓库 Label
├── stats └── stats
│ ├── summary Issue 统计摘要 ├── summary Issue 统计摘要
│ └── export 导出 Issue 数据到 CSV └── export 导出 Issue 数据到 CSV
└── labels
├── sync 同步预定义 Label 到仓库
└── list 列出仓库 Label
``` ```
## 典型工作流 ## 典型工作流
@@ -103,29 +100,12 @@ uv run tjhlp setup init \
uv run tjhlp users create --file members.csv --org tjhlp-2025f uv run tjhlp users create --file members.csv --org tjhlp-2025f
``` ```
`cmd` 可直接复制的写法:
## 典型工作流 ```cmd
### 学期初始化
```bash
# 1. 检查连接
uv run tjhlp setup status uv run tjhlp setup status
uv run tjhlp setup init --org tjhlp-2025f --webhook-url http://notify-server:8080/webhook --webhook-secret mysecret
# 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 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
``` ```
### 每次布置作业 ### 每次布置作业
@@ -138,6 +118,12 @@ uv run tjhlp repos create-homework \
--webhook-url http://notify-server:8080/webhook --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 团队。 这会自动完成: 创建 `hw03` 仓库 -> 推送作业 Issue Template -> 同步 Labels -> 配置 Webhook -> 添加到 ta/students 团队。
### 日常管理 ### 日常管理
@@ -174,16 +160,16 @@ id,name,role
``` ```
- `id` - 学号或工号, 同时作为 Gitea 用户名 - `id` - 学号或工号, 同时作为 Gitea 用户名
- `name` - 姓名, 作为 Gitea 的 full_name - `name` - 姓名, 作为 Gitea 的 `full_name`
- `role` - `student` 或 `ta`, 决定分配到哪个团队 - `role` - `student` 或 `ta`, 决定分配到哪个团队
- 邮箱自动生成为 `{id}@tongji.edu.cn` - 邮箱自动生成为 `{id}@tongji.edu.cn`
- **初始密码与用户名(学号/工号)相同**。 - **初始密码与用户名(学号/工号)相同**
示例文件见 `example/members.csv`。 示例文件见 `example/members.csv`。
## 预定义 Label ## 预定义 Label
通过 `settings.toml` 配置, `setup init` 和 `labels sync` 时自动创建: 通过 `settings.toml` 配置, `setup init` 和 `labels sync` 时自动创建:
| Label | 颜色 | 用途 | | Label | 颜色 | 用途 |
|-------|------|------| |-------|------|------|
@@ -271,7 +257,6 @@ scripts/
│ ├── test_models.py 数据模型测试 │ ├── test_models.py 数据模型测试
│ ├── test_config.py 配置校验测试 │ ├── test_config.py 配置校验测试
│ ├── test_utils.py 工具函数测试 │ ├── test_utils.py 工具函数测试
│ ├── test_pure_functions.py 纯函数测试
│ ├── test_client.py API 客户端测试 │ ├── test_client.py API 客户端测试
│ └── test_commands.py 命令集成测试 │ └── test_commands.py 命令集成测试
└── src/tjhlp/ └── src/tjhlp/