docs: precipitate HTML report contract for data management

tests/test_html_page_service.py

@@ -0,0 +1,66 @@
+# -*- coding: utf-8 -*-
+"""HTML 报告页薄写入 helper。"""
+
+from __future__ import annotations
+
+import os
+import unittest
+
+from _support import IsolatedDataRoot
+
+from service.html_page_service import (
+    HOST_HTML_RENDER_ACTION_ID,
+    load_html_template,
+    render_html_placeholders,
+    write_html_page,
+)
+
+
+class TestHtmlPageService(unittest.TestCase):
+    def test_host_action_id_is_stable(self) -> None:
+        self.assertEqual(HOST_HTML_RENDER_ACTION_ID, "render-html")
+
+    def test_write_html_page_atomic_under_html_dir(self) -> None:
+        with IsolatedDataRoot() as tmp:
+            path = write_html_page(
+                "example-report.html",
+                "<!DOCTYPE html><html><head><title>示例</title></head><body>ok</body></html>",
+            )
+            self.assertTrue(os.path.isfile(path))
+            norm = path.replace("\\", "/")
+            self.assertIn("/html/example-report.html", norm)
+            self.assertTrue(os.path.normcase(os.path.normpath(path)).startswith(
+                os.path.normcase(os.path.normpath(tmp)),
+            ))
+            self.assertFalse(os.path.isfile(path + ".tmp"))
+            with open(path, encoding="utf-8") as f:
+                self.assertIn("<title>示例</title>", f.read())
+
+    def test_load_and_fill_example_template(self) -> None:
+        with IsolatedDataRoot():
+            template = load_html_template("assets/html/example-report.html")
+            page = render_html_placeholders(
+                template,
+                {
+                    "TITLE": "示例报告",
+                    "GENERATED_AT": "2026-08-14 15:49:00",
+                    "BODY": "<p>hello</p>",
+                },
+            )
+            self.assertIn("<title>示例报告</title>", page)
+            self.assertIn("报告生成于 · 2026-08-14 15:49:00", page)
+            self.assertIn("<p>hello</p>", page)
+            self.assertNotIn("{{TITLE}}", page)
+            dest = write_html_page("example-report.html", page)
+            self.assertTrue(os.path.isfile(dest))
+
+    def test_rejects_unsafe_filename(self) -> None:
+        with IsolatedDataRoot():
+            with self.assertRaises(ValueError):
+                write_html_page("../x.html", "<html></html>")
+            with self.assertRaises(ValueError):
+                write_html_page("note.txt", "<html></html>")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_runtime_paths.py

@@ -136,11 +136,14 @@ class TestRuntimePaths(unittest.TestCase):
             importlib.reload(rp)
             input_dir = rp.get_input_dir(create=True)
             output_dir = rp.get_output_dir(create=True)
+            html_dir = rp.get_html_dir(create=True)
             norm_tmp = os.path.normcase(os.path.normpath(tmp))
             self.assertTrue(os.path.normcase(os.path.normpath(input_dir)).startswith(norm_tmp))
             self.assertTrue(os.path.normcase(os.path.normpath(output_dir)).startswith(norm_tmp))
+            self.assertTrue(os.path.normcase(os.path.normpath(html_dir)).startswith(norm_tmp))
             self.assertTrue(input_dir.replace("\\", "/").endswith("/input"))
             self.assertTrue(output_dir.replace("\\", "/").endswith("/output"))
+            self.assertTrue(html_dir.replace("\\", "/").endswith("/html"))
 
     def test_list_resolved_data_paths_keys(self) -> None:
         with IsolatedDataRoot():
@@ -154,6 +157,7 @@ class TestRuntimePaths(unittest.TestCase):
                 "skill_data_dir",
                 "input_dir",
                 "output_dir",
+                "html_dir",
             ):
                 self.assertIn(key, paths)
                 self.assertTrue(paths[key])
@@ -161,6 +165,5 @@ class TestRuntimePaths(unittest.TestCase):
             self.assertNotIn("imports_dir", paths)
             self.assertNotIn("exports_dir", paths)
 
-
 if __name__ == "__main__":
     unittest.main()