feat: 引入 Wiki 文档镜像流程 (#1)

2026-08-07 23:57:13 +08:00
parent 1337b5c894
commit b08a919fd7
13 changed files with 859 additions and 92 deletions
@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "scripts"))
+
+from new_task_archive import build_archive, safe_title  # noqa: E402
+from wiki_docs import (  # noqa: E402
+    Config,
+    Mapping,
+    WikiDocsError,
+    WikiPage,
+    dirty_mirror_paths,
+    load_config,
+    parse_mirror,
+    render_mirror,
+    validate_mappings,
+)
+
+
+class MappingTests(unittest.TestCase):
+    def test_rejects_path_outside_docs(self) -> None:
+        with self.assertRaisesRegex(WikiDocsError, "docs/"):
+            validate_mappings([{"page": "Home", "path": "README.md"}])
+
+    def test_rejects_duplicate_page(self) -> None:
+        with self.assertRaisesRegex(WikiDocsError, "重复映射"):
+            validate_mappings(
+                [
+                    {"page": "Home", "path": "docs/README.md"},
+                    {"page": "Home", "path": "docs/other.md"},
+                ]
+            )
+
+    def test_normalizes_api_suffix_from_environment(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "wiki-docs.json"
+            path.write_text(
+                json.dumps(
+                    {
+                        "schema_version": 1,
+                        "gitea_url": "http://configured.example",
+                        "owner": "owner",
+                        "repository": "repo",
+                        "mappings": [
+                            {"page": "Home", "path": "docs/README.md"}
+                        ],
+                    }
+                ),
+                encoding="utf-8",
+            )
+            with patch.dict(
+                os.environ, {"GITEA_URL": "http://gitea.example/api/v1"}, clear=False
+            ):
+                config = load_config(path)
+        self.assertEqual(config.gitea_url, "http://gitea.example")
+
+
+class MirrorTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.page = WikiPage(
+            title="Home",
+            sub_url="Home",
+            text="# 首页\n",
+            revision="a" * 40,
+            html_url="http://gitea.example/o/r/wiki/Home",
+        )
+
+    def test_render_includes_traceable_metadata(self) -> None:
+        rendered = render_mirror(self.page)
+        metadata, body = parse_mirror(rendered)
+        self.assertEqual(metadata["wiki_page"], "Home")
+        self.assertEqual(metadata["wiki_revision"], "a" * 40)
+        self.assertTrue(metadata["synchronized_at"].endswith("Z"))
+        self.assertEqual(body, "# 首页\n")
+
+    def test_unchanged_revision_preserves_sync_time(self) -> None:
+        first = render_mirror(self.page)
+        second = render_mirror(self.page, first)
+        self.assertEqual(first, second)
+
+    @patch("wiki_docs.subprocess.run")
+    def test_dirty_mirror_paths_are_reported(self, run) -> None:
+        run.return_value.stdout = " M docs/README.md\n"
+        config = Config(
+            path=Path("wiki-docs.json"),
+            gitea_url="http://gitea.example",
+            owner="o",
+            repository="r",
+            mappings=(Mapping("Home", "docs/README.md"),),
+        )
+        self.assertEqual(dirty_mirror_paths(config), [" M docs/README.md"])
+
+
+class ArchiveTests(unittest.TestCase):
+    def test_safe_title_handles_windows_characters(self) -> None:
+        self.assertEqual(safe_title(' 修复:"登录" / 超时 '), "修复-登录-超时")
+
+    def test_build_archive_replaces_known_fields(self) -> None:
+        template = "# <工单号> <标题>\nYYYY-MM-DD\n<链接>\n<页面名>\n"
+        result = build_archive(template, "12", "修复登录", "Task-12-login", "http://i/12")
+        self.assertIn("# 12 修复登录", result)
+        self.assertIn("http://i/12", result)
+        self.assertIn("Task-12-login", result)
+        self.assertNotIn("YYYY-MM-DD", result)
+
+
+if __name__ == "__main__":
+    unittest.main()