diff --git a/issue-templates/README.md b/issue-templates/README.md index 740a079..743f285 100644 --- a/issue-templates/README.md +++ b/issue-templates/README.md @@ -17,16 +17,35 @@ issue-templates/ ├── general/ general 仓库使用 │ └── .gitea/ISSUE_TEMPLATE/ -│ ├── config.yaml 禁止空白 Issue + 外部链接 +│ ├── config.yaml 禁止空白 Issue + 课程官网/提问规范链接 │ ├── course-question.yaml 课程内容 / 知识点答疑 │ ├── homework-help.yaml 编程作业问题 │ └── env-setup.yaml 环境配置问题 └── homework/ hwXX 作业仓库使用 └── .gitea/ISSUE_TEMPLATE/ - ├── config.yaml 禁止空白 Issue + 引导到 general + ├── config.yaml 禁止空白 Issue + 引导到 general + 课程官网链接 └── homework-help.yaml 编程作业问题(无作业编号字段) ``` +## config.yaml 里的链接与占位符 + +`config.yaml` 的 `contact_links` 是「新建 Issue」页面上的引导入口, 目前指向**课程官网** +(学会提问 / 课程信息 / 常见问题), 把答疑平台和官网串起来。课程官网地址是硬编码常量 +(`http://10.80.42.185/Website/`), 换域名时两个 `config.yaml` 要一起改。 + +平台自身的链接用占位符, 避免把学期组织名写死: + +| 占位符 | 替换为 | 来源 | +|--------|--------|------| +| `{{BASE_URL}}` | 面向同学的平台地址 | `scripts/settings.toml` 的 `gitea.public_url` | +| `{{ORG}}` | 组织名(如 `tjhlp-2025f`) | 推送时的目标仓库 | +| `{{REPO}}` | 仓库名(如 `hw01`) | 推送时的目标仓库 | + +> 换学期只要新建组织、重跑 `setup init` / `create-homework`, 模板里的链接会自动跟着走。 +> `public_url` 没配时会保留占位符并打印警告, 不会推上一条坏链接。 +> 注意 `gitea.url`(CLI 调 API 用, 带内部端口)与 `public_url`(Apache 反代后的对外地址) +> 是两回事, 写进模板的必须是后者。 + ## 模板说明 ### general 仓库(3 个模板) @@ -97,10 +116,15 @@ uv run tjhlp repos init-templates tjhlp-2025f/hw01 --type homework ## 自定义 -如需调整模板内容(如添加新的问题分类、修改引导文案), 直接编辑对应的 YAML 文件, 然后重新推送: +如需调整模板内容(如添加新的问题分类、修改引导文案、更新 `config.yaml` 里的链接), +直接编辑对应的 YAML 文件, 然后重新推送: ```bash +# 已有仓库原地更新(general 与各 hwNN 都要推一次) uv run tjhlp repos init-templates tjhlp-2025f/general --type general +uv run tjhlp repos init-templates tjhlp-2025f/hw01 --type homework ``` +推送会覆盖远端同名文件(走 API 的 create-or-update), 不需要重建仓库。 + YAML 模板语法参考 [Gitea 文档](https://docs.gitea.com/usage/issue-pull-request-templates#syntax-for-yaml-template)。 diff --git a/issue-templates/general/.gitea/ISSUE_TEMPLATE/config.yaml b/issue-templates/general/.gitea/ISSUE_TEMPLATE/config.yaml index d27d095..1ecd6a9 100644 --- a/issue-templates/general/.gitea/ISSUE_TEMPLATE/config.yaml +++ b/issue-templates/general/.gitea/ISSUE_TEMPLATE/config.yaml @@ -1,8 +1,11 @@ blank_issues_enabled: false contact_links: - - name: 课程主页 - url: https://example.com - about: 访问课程主页获取有关资源 - - name: 常见问题汇总 - url: https://example.com/faq - about: 提问前请先查阅常见问题汇总 + - name: 提问前必读 · 学会提问 + url: http://10.80.42.185/Website/ask-question/ + about: 课程官网上的提问规范。不合规范的提问很可能不会得到回答 + - name: 课程官网 + url: http://10.80.42.185/Website/ + about: 课程信息、作业说明、环境配置要求、常见问题 + - name: 答疑平台提问指南 + url: "{{BASE_URL}}/assets/tjhlp/ask-guide.html" + about: 搜索 Issue、选择模板、填写信息、关闭 Issue 的平台内速查 diff --git a/issue-templates/homework/.gitea/ISSUE_TEMPLATE/config.yaml b/issue-templates/homework/.gitea/ISSUE_TEMPLATE/config.yaml index 5d2c238..a94277e 100644 --- a/issue-templates/homework/.gitea/ISSUE_TEMPLATE/config.yaml +++ b/issue-templates/homework/.gitea/ISSUE_TEMPLATE/config.yaml @@ -1,5 +1,11 @@ blank_issues_enabled: false contact_links: - name: 一般性问题请到 general 仓库提问 - url: https://example.com + url: "{{BASE_URL}}/{{ORG}}/general/issues/new/choose" about: 课程内容答疑、环境配置等非作业特定问题请到 general 仓库 + - name: 提问前必读 · 学会提问 + url: http://10.80.42.185/Website/ask-question/ + about: 课程官网上的提问规范。不合规范的提问很可能不会得到回答 + - name: 课程官网 + url: http://10.80.42.185/Website/ + about: 课程信息、作业说明、环境配置要求、常见问题 diff --git a/scripts/settings.toml b/scripts/settings.toml index bb99f20..91b2bef 100644 --- a/scripts/settings.toml +++ b/scripts/settings.toml @@ -1,5 +1,8 @@ [default.gitea] url = "http://10.80.42.185:3000" +# 同学实际访问的平台地址(Apache 反代 /QA -> 127.0.0.1:2080)。 +# 用于 Issue Template 等面向用户的链接; url 只用于 CLI 调 API。 +public_url = "http://10.80.42.185/QA" email_domain = "tongji.edu.cn" default_org = "" diff --git a/scripts/src/tjhlp/commands/repos.py b/scripts/src/tjhlp/commands/repos.py index dc39dd4..60c3452 100644 --- a/scripts/src/tjhlp/commands/repos.py +++ b/scripts/src/tjhlp/commands/repos.py @@ -9,7 +9,7 @@ from rich.console import Console from tjhlp.client import GiteaClient, GiteaClientError from tjhlp.config import get_gitea_config -from tjhlp.utils import parse_repo, push_templates, sync_labels +from tjhlp.utils import parse_repo, push_templates, sync_labels, web_base_url app = typer.Typer(no_args_is_help=True) console = Console() @@ -69,7 +69,7 @@ def create_homework( # 推送作业 Issue Templates console.print("\n推送 Issue Templates...") hw_tpl_dir = _TEMPLATES_DIR / "homework" - n = push_templates(client, org, repo_name, hw_tpl_dir) + n = push_templates(client, org, repo_name, hw_tpl_dir, web_base_url(cfg)) console.print(f" 共推送 {n} 个模板文件") # 同步 Labels @@ -120,7 +120,7 @@ def init_templates( cfg = get_gitea_config() with GiteaClient(cfg) as client: - n = push_templates(client, org_name, repo_name, tpl_dir) + n = push_templates(client, org_name, repo_name, tpl_dir, web_base_url(cfg)) console.print(f"\n共推送 {n} 个模板文件到 {repo}") diff --git a/scripts/src/tjhlp/commands/setup.py b/scripts/src/tjhlp/commands/setup.py index 8026f39..ac6754b 100644 --- a/scripts/src/tjhlp/commands/setup.py +++ b/scripts/src/tjhlp/commands/setup.py @@ -9,7 +9,7 @@ from rich.console import Console from tjhlp.client import GiteaClient, GiteaClientError from tjhlp.config import get_gitea_config -from tjhlp.utils import push_templates, sync_labels +from tjhlp.utils import push_templates, sync_labels, web_base_url app = typer.Typer(no_args_is_help=True) console = Console() @@ -86,7 +86,7 @@ def init( console.print("\n[bold]4. 推送 Issue Templates 到 general 仓库[/bold]") general_tpl_dir = _TEMPLATES_DIR / "general" if general_tpl_dir.exists(): - n = push_templates(client, org, "general", general_tpl_dir) + n = push_templates(client, org, "general", general_tpl_dir, web_base_url(cfg)) console.print(f" 共推送 {n} 个模板文件") else: console.print(f" [red]模板目录不存在: {general_tpl_dir}[/red]") diff --git a/scripts/src/tjhlp/config.py b/scripts/src/tjhlp/config.py index 0c8b49d..e2ddfff 100644 --- a/scripts/src/tjhlp/config.py +++ b/scripts/src/tjhlp/config.py @@ -55,6 +55,10 @@ class GiteaConfig(BaseModel): token: SecretStr email_domain: str = "tongji.edu.cn" default_org: str = "" + # 面向用户的访问地址(Apache 反代后的地址, 如 http://10.80.42.185/QA)。 + # url 是 CLI 调 API 用的地址, 可能带内部端口, 不能直接写进 Issue Template 等 + # 给同学看的链接里; 留空时回退到 url。 + public_url: str = "" labels: list[LabelDef] = [] diff --git a/scripts/src/tjhlp/utils.py b/scripts/src/tjhlp/utils.py index aef5422..316edbe 100644 --- a/scripts/src/tjhlp/utils.py +++ b/scripts/src/tjhlp/utils.py @@ -34,11 +34,38 @@ def parse_repo(repo: str) -> tuple[str, str]: # --------------------------------------------------------------------------- # Issue Template 推送 # --------------------------------------------------------------------------- +# 模板占位符: 让 Issue Template 不必硬编码学期组织名/访问地址 +# {{BASE_URL}} -> gitea.public_url(面向同学的地址) +# {{ORG}} / {{REPO}} -> 推送目标 +TEMPLATE_PLACEHOLDERS = ("{{BASE_URL}}", "{{ORG}}", "{{REPO}}") + + +def web_base_url(cfg: GiteaConfig) -> str: + """面向同学的平台访问地址: 优先 gitea.public_url, 否则退回 gitea.url。""" + return (cfg.public_url or str(cfg.url)).rstrip("/") + + +def render_template_placeholders(text: str, org: str, repo: str, web_base: str = "") -> str: + """替换 Issue Template 中的占位符, 返回渲染后的文本。""" + base = (web_base or "").rstrip("/") + if base: + text = text.replace("{{BASE_URL}}", base) + text = text.replace("{{ORG}}", org).replace("{{REPO}}", repo) + left = [p for p in TEMPLATE_PLACEHOLDERS if p in text] + if left: + console.print( + f"[yellow]警告: 模板中仍有未替换的占位符 {', '.join(left)}" + f"(检查 settings.toml 的 gitea.public_url)[/yellow]" + ) + return text + + def push_templates( client: GiteaClient, org: str, repo: str, template_dir: Path, + web_base: str = "", ) -> int: """将本地 issue template 目录推送到远端仓库, 返回推送的文件数。""" count = 0 @@ -51,7 +78,13 @@ def push_templates( if not filepath.is_file(): continue remote_path = f".gitea/ISSUE_TEMPLATE/{filepath.name}" - content_b64 = base64.b64encode(filepath.read_bytes()).decode() + text = render_template_placeholders( + filepath.read_text(encoding="utf-8"), + org=org, + repo=repo, + web_base=web_base, + ) + content_b64 = base64.b64encode(text.encode("utf-8")).decode() existing = client.get_file_contents(org, repo, remote_path) if existing: diff --git a/scripts/tests/test_utils.py b/scripts/tests/test_utils.py index 96e3414..af31e10 100644 --- a/scripts/tests/test_utils.py +++ b/scripts/tests/test_utils.py @@ -1,10 +1,17 @@ -"""utils.py 单元测试: parse_repo, compute_issue_stats""" +"""utils.py 单元测试: parse_repo, compute_issue_stats, render_template_placeholders""" from __future__ import annotations import pytest +from pydantic import SecretStr -from tjhlp.utils import compute_issue_stats, parse_repo +from tjhlp.config import GiteaConfig +from tjhlp.utils import ( + compute_issue_stats, + parse_repo, + render_template_placeholders, + web_base_url, +) # typer.Exit 在非 CLI 上下文中抛出 click.exceptions.Exit _EXIT_EXCEPTIONS = (SystemExit, Exception) @@ -103,3 +110,44 @@ class TestComputeIssueStats: ] stats = compute_issue_stats(issues) assert stats["no_reply"] == 1 + + +class TestRenderTemplatePlaceholders: + def test_replaces_all_placeholders(self): + out = render_template_placeholders( + 'url: "{{BASE_URL}}/{{ORG}}/{{REPO}}/issues"', + org="tjhlp-2025f", + repo="hw01", + web_base="http://10.80.42.185/QA/", + ) + assert out == 'url: "http://10.80.42.185/QA/tjhlp-2025f/hw01/issues"' + + def test_strips_trailing_slash_of_web_base(self): + out = render_template_placeholders( + "{{BASE_URL}}/assets/x.html", "org", "repo", "http://h/QA//" + ) + assert out == "http://h/QA/assets/x.html" + + def test_leaves_base_url_when_not_configured(self): + # public_url 没配时应保留占位符(由 push_templates 打警告), 而不是生成坏链接 + out = render_template_placeholders("{{BASE_URL}}/x", "org", "repo") + assert "{{BASE_URL}}" in out + + def test_text_without_placeholders_is_unchanged(self): + text = "blank_issues_enabled: false\n" + assert render_template_placeholders(text, "org", "repo", "http://h") == text + + +class TestWebBaseUrl: + def _cfg(self, **kw): + base = {"url": "http://10.80.42.185:3000", "token": SecretStr("x")} + return GiteaConfig(**{**base, **kw}) + + def test_prefers_public_url(self): + assert ( + web_base_url(self._cfg(public_url="http://10.80.42.185/QA/")) + == "http://10.80.42.185/QA" + ) + + def test_falls_back_to_url(self): + assert web_base_url(self._cfg()) == "http://10.80.42.185:3000"