feat: 初始化高校人事请假考勤技能 (process-leave-attendance-default)

基于 skill-template 脚手架开发，包含：
- 5 张业务表（教职工、请假政策、考勤日历、请假记录、假期余额）
- 请假核算引擎（扣薪计算、审批层级判定、年假抵扣）
- CLI 入口（import-employees / calculate-leave / render-html）
- HTML 审批与扣薪报告生成
- 示例数据与完整测试套件（295 tests passed）

tests/samples/README.md

@@ -0,0 +1,128 @@
+# samples（业务测试样例，默认不执行）
+
+本目录存放**可复制到根目录的业务测试范式**，面向「企业数字员工技能」中 **ERP、TMS、WMS、船司、报关、邮件、LLM、RPA** 等外联场景下的 **service / golden** 测法说明。
+
+---
+
+## 作用
+
+- 这里的文件是 **`.py.sample`**：`python tests/run_tests.py` **不会**收集本目录（`run_tests.py` 只发现 `tests/` 根目录下的 `test_*.py`）。
+- 人类或 AI 需要启用范式时：**复制**到 `tests/test_<名称>.py`（去掉 `.sample`），再按业务改 import、断言与 fixture 路径。
+- **禁止**把真实联调、真实网络、真实 RPA 写进复制后的默认用例；此类内容应放在 `tests/integration/*.sample` 并配合环境变量开关。
+
+---
+
+## 样例文件
+
+### 1. `test_service_contract.py.sample`
+
+**适合：**
+
+- 技能有清晰的 **service 层入口**，例如 `run(...)`、`handle(...)`、`execute(...)`。
+- 需要验证：**成功路径**、**参数/校验错误**、**adapter 异常被转换为业务可读错误**。
+- 需要用 **`FakeAdapter`**（见 `tests/adapter_test_utils.py`）或自建 **stub** 替代 ERP、TMS、WMS、船司、报关、LLM、RPA 等，**不**发真实 HTTP、**不**开真实浏览器。
+
+### 2. `test_sync_contract.py.sample`
+
+**适合：** 外源 → 本地库的同步 / refresh / collect 能力。
+
+至少应覆盖：首次插入、第二次幂等、更新、失效数据处理、不可信空结果保护 vs 完整空快照失效、遗漏 `snapshot_complete` 立即失败、部分写入后故障注入与回滚（`fail_after_writes`）、统计字段 `inserted/updated/unchanged/removed`、同步路径不调用 CSV/Excel 导出器。`snapshot_complete` 为调用方**必须显式传入**的 keyword-only 参数（无默认值），禁止默认把结果当成完整快照，也禁止靠条数猜测完整性。使用通用表名（如 `business_key`），不要写具体平台业务名。
+
+### 3. `test_action_core_contract.py.sample`
+
+**适合：** 校验「单业务内核、多入口」——task/CLI/兼容命令调用同一 domain service；不按 toolbar/cron/agent 来源改变业务结果。
+
+### 4. `test_golden_cases.py.sample`
+
+**适合：**
+
+- **解析类**：邮件/单证/PDF/Excel 等结构化输出。
+- **计算类**：费用、税费、分摊、账单字段。
+- **校验类**：合规、字段一致性、状态机规则。
+
+推荐配合根目录下的 **`tests/fixtures/sample_request.json`** 与 **`tests/fixtures/expected_response.json`**（复制技能后按域替换字段，保持脱敏）。
+
+### 5. `test_logging_contract.py.sample`
+
+**适合：** 长任务 / RPA 技能，需断言统一文件日志含 `task_start`、`task_failed|task_success`、`error_code=` 等事件词（见 [`development/LOGGING.md`](../../development/LOGGING.md) §3）。复制后用 `IsolatedDataRoot` + mock 域 RPA，**不要**依赖真实企微/浏览器。
+
+---
+
+## 如何启用 service contract 样例
+
+1. **复制文件**  
+   `tests/samples/test_service_contract.py.sample`  
+   → `tests/test_service_contract.py`（或 `tests/test_<domain>_service_contract.py`，须符合根目录 `test_*.py` 命名以便 `run_tests.py` 收集）。
+
+2. **替换示例 import**  
+   把注释中的示意：  
+   `# from service.your_service import run`  
+   改为真实模块，例如：  
+   `from service.quote_service import run_quote`  
+   （具体路径以技能代码为准。）
+
+3. **注入假外部依赖**  
+   - **不要**在默认用例里直接 `requests` 访问 ERP/TMS/WMS 等。  
+   - **不要**打开真实网页或驱动真实 RPA。  
+   - **不要**调用真实 LLM；可 stub 返回固定 JSON。  
+   - 对 **timeout / unauthorized / invalid_response** 等分支，用 `FakeAdapter` 或自建 fake 模拟（与 `adapter_test_utils` 思路一致）。
+
+4. **至少保留三类断言习惯**  
+   - **成功路径**：返回 `success: true` 或与技能约定的成功结构。  
+   - **参数错误**：缺必填字段时返回**结构化** error（字段/码），而非未捕获裸异常。  
+   - **外部异常**：adapter 超时、鉴权失败、脏响应等被转换为**可读、可重试标识明确**的错误形态（按产品约定）。
+
+5. **给 AI 的提示**  
+   复制后全文搜索 `your_service`、`TODO`、`伪代码` 等占位符并替换；不要留下指向真实客户的示例数据。
+
+---
+
+## 如何启用 golden case 样例
+
+1. **复制文件**  
+   `tests/samples/test_golden_cases.py.sample`  
+   → `tests/test_golden_cases.py`（或 `tests/test_<domain>_golden.py`）。
+
+2. **按业务修改 fixtures**（仍须脱敏）  
+   - `tests/fixtures/sample_request.json`：请求或输入快照。  
+   - `tests/fixtures/expected_response.json`：期望摘要或关键字段。  
+   可新增多组文件，如 `case_valid_001.json`，并在测试中显式读取路径。
+
+3. **断言建议（避免脆弱用例）**  
+   - 比较**关键字段**，避免对整段 JSON 做机械全文 diff。  
+   - **忽略**时间戳、随机 id、`trace_id` 等非确定字段。  
+   - 对列表：断言**长度**、**关键元素**、**排序规则**（若业务保证顺序）。  
+   - 对金额/数量：断言 Decimal 字符串、或允许文档约定的小范围误差。
+
+4. **与 service 的关系**  
+   golden 用例仍应通过 **service 层**（或纯函数）得到输出，再与 fixture 对比，而不是从 CLI 字符串 scrape。
+
+---
+
+## 不应该写在 samples 复制件里的内容
+
+以下若出现，应移到 **`tests/integration/*.sample`** 或 **`tests/desktop/*.sample`**，并加环境变量授权说明：
+
+- 访问**真实** API 或内网服务。  
+- 打开**真实** RPA 页面或生产门户。  
+- 读取**真实**客户文件、生产数据库。  
+- 在测试中写入**真实**数据根或共享盘。  
+- 任何真实 **token / cookie / 密码** 字面量。  
+- 耗时极长、强依赖宿主 UI 抖动、无法在 CI 稳定复现的用例（不要塞进默认 `tests/test_*.py`）。
+
+---
+
+## 推荐命名（复制到根目录后）
+
+| 用途 | 示例文件名 |
+|------|------------|
+| Service 契约 | `tests/test_service_contract.py` |
+| 同步契约 | `tests/test_sync_contract.py` |
+| 单内核多入口 | `tests/test_action_core_contract.py` |
+| Golden / fixture 回归 | `tests/test_golden_cases.py` |
+| 领域规则 | `tests/test_<domain>_rules.py` |
+| 校验逻辑 | `tests/test_<domain>_validation.py` |
+
+命名需满足：`tests/` 根目录下 `test_*.py`，以便 `python tests/run_tests.py` 默认发现。
+
+更多分层说明见 **`tests/README.md`**（「我该把测试写在哪里？」与「新技能最小测试清单」）。

tests/samples/test_action_core_contract.py.sample

@@ -0,0 +1,116 @@
+# -*- coding: utf-8 -*-
+# 样例：复制到 ``tests/test_action_core_contract.py`` 后按实际模块改名运行。
+# 默认不会被 ``python tests/run_tests.py`` 收集（扩展名为 .sample）。
+"""
+单业务内核、多入口契约范式（通用）。
+
+覆盖：
+- task / command adapter 调用唯一 domain service
+- 兼容命令复用同一个核心函数
+- CLI handler 不复制业务逻辑
+- 不根据 toolbar / cron / agent 来源改变业务处理
+
+复制后把示意函数换成真实 import；禁止按入口维护多套实现。
+"""
+from __future__ import annotations
+
+import unittest
+from typing import Any, Callable
+
+
+class DomainService:
+    """唯一业务内核示意。"""
+
+    def __init__(self) -> None:
+        self.calls: list[dict[str, Any]] = []
+
+    def sync_records(self, *, limit: int = 100) -> dict[str, Any]:
+        self.calls.append({"op": "sync_records", "limit": limit})
+        return {"ok": True, "limit": limit, "inserted": 1}
+
+
+def cmd_sync_records(domain: DomainService, *, limit: int = 100) -> dict[str, Any]:
+    """task_service 编排层：可加 job_context，但不按 source 分叉业务。"""
+    return domain.sync_records(limit=limit)
+
+
+def cmd_export_compat_refresh(domain: DomainService, *, limit: int = 100) -> dict[str, Any]:
+    """兼容旧 export：刷新必须复用同一 sync 内核，禁止另写采集逻辑。"""
+    sync_result = domain.sync_records(limit=limit)
+    return {"export": "delegated-to-host-or-report", "sync": sync_result}
+
+
+def cli_handle_sync(domain: DomainService, argv_limit: int) -> dict[str, Any]:
+    """CLI handler：只解析参数后转发，不内嵌业务。"""
+    return cmd_sync_records(domain, limit=argv_limit)
+
+
+def run_from_source(
+    domain: DomainService,
+    *,
+    source: str,
+    limit: int = 10,
+) -> dict[str, Any]:
+    """
+    宿主可能传入 source=toolbar|cron|agent|skill-detail。
+    正确实现：忽略 source，业务结果一致。
+    """
+    _ = source  # 不得用于分支业务语义
+    return cmd_sync_records(domain, limit=limit)
+
+
+class TestActionCoreContractSample(unittest.TestCase):
+    def test_task_adapter_calls_single_domain_service(self) -> None:
+        domain = DomainService()
+        out = cmd_sync_records(domain, limit=5)
+        self.assertTrue(out["ok"])
+        self.assertEqual(domain.calls, [{"op": "sync_records", "limit": 5}])
+
+    def test_compat_command_reuses_same_core(self) -> None:
+        domain = DomainService()
+        cmd_export_compat_refresh(domain, limit=3)
+        self.assertEqual(len(domain.calls), 1)
+        self.assertEqual(domain.calls[0]["op"], "sync_records")
+
+    def test_cli_handler_does_not_duplicate_business_logic(self) -> None:
+        domain = DomainService()
+        # CLI 与 task 编排应落到同一函数对象（示意）
+        self.assertIs(cli_handle_sync.__wrapped__ if hasattr(cli_handle_sync, "__wrapped__") else None, None)
+        out = cli_handle_sync(domain, 7)
+        self.assertEqual(out["limit"], 7)
+        self.assertEqual(domain.calls[-1], {"op": "sync_records", "limit": 7})
+
+        # 强化：CLI 路径与 cmd 路径结果一致
+        domain2 = DomainService()
+        a = cli_handle_sync(domain2, 2)
+        domain3 = DomainService()
+        b = cmd_sync_records(domain3, limit=2)
+        self.assertEqual(a, b)
+
+    def test_business_result_independent_of_entry_source(self) -> None:
+        domain = DomainService()
+        results = [
+            run_from_source(domain, source=src, limit=4)
+            for src in ("toolbar", "cron", "agent", "skill-detail")
+        ]
+        self.assertEqual(results[0], results[1])
+        self.assertEqual(results[1], results[2])
+        self.assertEqual(results[2], results[3])
+        self.assertEqual(len(domain.calls), 4)
+        self.assertTrue(all(c["op"] == "sync_records" and c["limit"] == 4 for c in domain.calls))
+
+    def test_entrypoint_wiring_points_to_same_callable(self) -> None:
+        """示意：manifest 多 placements 应对应同一 Python 入口函数。"""
+        domain = DomainService()
+        handlers: dict[str, Callable[..., dict[str, Any]]] = {
+            "toolbar": lambda: cmd_sync_records(domain, limit=1),
+            "cron": lambda: cmd_sync_records(domain, limit=1),
+            "agent": lambda: cmd_sync_records(domain, limit=1),
+        }
+        outs = [handlers[k]() for k in handlers]
+        self.assertEqual(outs[0], outs[1])
+        self.assertEqual(outs[1], outs[2])
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/samples/test_golden_cases.py.sample

@@ -0,0 +1,37 @@
+# -*- coding: utf-8 -*-
+# 样例：复制为 ``tests/test_golden_cases.py`` 后运行；默认不收集。
+"""
+Golden fixture 回归（示意）。
+
+- 从 ``tests/fixtures/`` 读取脱敏 JSON。
+- 调用 service 层（复制后替换为真实 import）。
+- 断言关键字段，而非全文 diff（外部系统常带时间戳/非确定性字段）。
+"""
+from __future__ import annotations
+
+import json
+import os
+import unittest
+
+
+def _fixtures_dir() -> str:
+    return os.path.join(os.path.dirname(__file__), "..", "fixtures")
+
+
+class TestGoldenCasesSample(unittest.TestCase):
+    def test_sample_request_matches_expected_shape(self) -> None:
+        req_path = os.path.join(_fixtures_dir(), "sample_request.json")
+        exp_path = os.path.join(_fixtures_dir(), "expected_response.json")
+        with open(req_path, encoding="utf-8") as f:
+            req = json.load(f)
+        with open(exp_path, encoding="utf-8") as f:
+            exp = json.load(f)
+        self.assertEqual(req["request_id"], "req_test_001")
+        self.assertTrue(req["parameters"]["options"]["dry_run"])
+        # 示意：out = run(req); 然后 assert out["success"] == exp["success"] 等关键字段
+        self.assertTrue(exp["success"])
+        self.assertEqual(exp["data"]["status"], "ok")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/samples/test_logging_contract.py.sample

@@ -0,0 +1,56 @@
+# -*- coding: utf-8 -*-
+"""日志契约样例：复制为 tests/test_logging_contract.py 后按业务改入口。
+
+验证主任务 mock/离线路径写入统一日志事件词（见 development/LOGGING.md §3）。
+默认套件不收集本文件（.sample）。
+"""
+from __future__ import annotations
+
+import io
+import logging
+import unittest
+from contextlib import redirect_stderr, redirect_stdout
+from unittest.mock import patch
+
+# 复制到 tests/ 根目录后取消下一行注释，并按技能改 import
+# from _support import IsolatedDataRoot
+
+
+class TestLoggingContractSample(unittest.TestCase):
+    """示范：捕获 skill logger，断言关键事件词出现。"""
+
+    def test_main_path_emits_task_start_and_terminal_event(self) -> None:
+        self.skipTest(
+            "复制本文件为 tests/test_logging_contract.py 后："
+            "用 IsolatedDataRoot + patch 域 RPA，调用 cmd_run/cmd_add_one，"
+            "对 logging.Handler 断言消息含 task_start 与 task_success|task_failed"
+        )
+        # 示例骨架（复制后实现）：
+        # with IsolatedDataRoot():
+        #     log = logging.getLogger("openclaw.skill.process_leave_attendance_default")
+        #     records: list[str] = []
+        #     class _H(logging.Handler):
+        #         def emit(self, record):
+        #             records.append(record.getMessage())
+        #     h = _H()
+        #     log.addHandler(h)
+        #     try:
+        #         with patch(...), redirect_stdout(io.StringIO()), redirect_stderr(io.StringIO()):
+        #             rc = cmd_add_one(...)  # 或 cmd_run
+        #     finally:
+        #         log.removeHandler(h)
+        #     blob = "\n".join(records)
+        #     self.assertIn("task_start", blob)
+        #     self.assertTrue("task_failed" in blob or "task_success" in blob)
+        #     if "task_failed" in blob:
+        #         self.assertIn("error_code=", blob)
+
+    def test_failure_path_logs_error_code_before_print(self) -> None:
+        self.skipTest(
+            "复制后：注入业务错误（如 ELEMENT_NOT_FOUND），断言 logger 含 "
+            "task_failed error_code=...，且 stdout 含 ERROR:CODE"
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/samples/test_service_contract.py.sample

@@ -0,0 +1,46 @@
+# -*- coding: utf-8 -*-
+# 本文件为样例：复制到 ``tests/test_service_contract.py``（或业务仓 tests 根）后按实际 service 改名运行。
+# 默认 **不会** 被 ``python tests/run_tests.py`` 收集（扩展名为 .sample）。
+"""
+Service 层契约测试范式（示意）。
+
+复制为真实技能后：
+1. 将 ``from service.your_service import run`` 替换为实际模块与入口函数。
+2. 用 ``FakeAdapter`` / 内存 stub 替代真实 ERP/TMS/WMS 等外呼。
+3. 需要真实外网或真实 RPA 时，勿在本文件直接写死凭证；改用 ``tests/integration/*.sample`` + 环境开关。
+"""
+from __future__ import annotations
+
+import unittest
+
+from adapter_test_utils import FakeAdapter
+
+
+# from service.your_service import run  # noqa: ERA001 — 复制后取消注释并实现
+
+
+class TestServiceContractSample(unittest.TestCase):
+    """三类常见契约：成功路径、结构化错误、上游超时转可重试错误。"""
+
+    def test_success_path_returns_success_true(self) -> None:
+        # 示意：run(payload, adapter=FakeAdapter("success")) -> {"success": True, ...}
+        ad = FakeAdapter("success")
+        out = ad.call({"op": "ping"})
+        self.assertTrue(out.get("success"))
+
+    def test_missing_required_field_returns_structured_error_not_bare_exception(self) -> None:
+        # 示意：业务层应对必填字段做校验，返回 {"success": False, "error": {"code": "...", "message": "..."}}
+        err = {"success": False, "error": {"code": "VALIDATION", "message": "missing shipment_id"}}
+        self.assertFalse(err["success"])
+        self.assertIn("code", err["error"])
+
+    def test_adapter_timeout_maps_to_retriable_error(self) -> None:
+        # 示意：捕获 TimeoutError 后映射为业务可重试错误码，而不是让裸异常穿透 CLI
+        ad = FakeAdapter("timeout")
+        with self.assertRaises(TimeoutError):
+            ad.call({})
+        # 真实实现中：except TimeoutError: return {"success": False, "error": {"code": "UPSTREAM_TIMEOUT", "retriable": True}}
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/samples/test_sync_contract.py.sample

@@ -0,0 +1,274 @@
+# -*- coding: utf-8 -*-
+# 样例：复制到 ``tests/test_sync_contract.py`` 后按实际 domain service 改名运行。
+# 默认不会被 ``python tests/run_tests.py`` 收集（扩展名为 .sample）。
+"""
+外源 → 本地库同步契约范式（通用，无具体平台业务名）。
+
+覆盖：
+- 首次同步插入
+- 第二次同步幂等
+- 更新已有数据
+- 处理失效数据
+- 不可信空结果保护 vs 完整空快照失效（``snapshot_complete`` 必填，无默认值）
+- 遗漏 ``snapshot_complete`` 立即失败（TypeError）
+- 事务在部分写入后失败并回滚
+- 返回 inserted/updated/unchanged/removed
+- sync Action 不调用 CSV/Excel 文件导出器
+
+复制后把内存仓库与 stub 外源换成真实 repository / reader；禁止访问真实网络或用户数据目录。
+"""
+from __future__ import annotations
+
+import unittest
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class SyncStats:
+    total: int = 0
+    inserted: int = 0
+    updated: int = 0
+    unchanged: int = 0
+    removed: int = 0
+
+    def as_dict(self) -> dict[str, int]:
+        return {
+            "total": self.total,
+            "inserted": self.inserted,
+            "updated": self.updated,
+            "unchanged": self.unchanged,
+            "removed": self.removed,
+        }
+
+
+@dataclass
+class MemoryRecordStore:
+    """内存库：演示幂等 upsert + 全量失效（is_active 标记）。"""
+
+    rows: dict[str, dict[str, Any]] = field(default_factory=dict)
+    in_transaction: bool = False
+    _tx_snapshot: dict[str, dict[str, Any]] | None = None
+
+    def begin(self) -> None:
+        self._tx_snapshot = {k: dict(v) for k, v in self.rows.items()}
+        self.in_transaction = True
+
+    def commit(self) -> None:
+        self._tx_snapshot = None
+        self.in_transaction = False
+
+    def rollback(self) -> None:
+        if self._tx_snapshot is not None:
+            self.rows = {k: dict(v) for k, v in self._tx_snapshot.items()}
+        self._tx_snapshot = None
+        self.in_transaction = False
+
+    def upsert_snapshot(
+        self,
+        records: list[dict[str, Any]],
+        *,
+        fail_after_writes: int | None = None,
+    ) -> SyncStats:
+        """全量快照：按 business_key 对齐；缺失标 is_active=0。
+
+        ``fail_after_writes``：在成功完成该次数的 insert/update 之后抛错，用于验证回滚。
+        """
+        self.begin()
+        try:
+            stats = SyncStats(total=len(records))
+            seen: set[str] = set()
+            write_count = 0
+            for rec in records:
+                key = str(rec["business_key"])
+                seen.add(key)
+                existing = self.rows.get(key)
+                payload = {
+                    "business_key": key,
+                    "title": rec["title"],
+                    "is_active": 1,
+                }
+                if existing is None:
+                    self.rows[key] = payload
+                    stats.inserted += 1
+                    write_count += 1
+                elif existing.get("title") == payload["title"] and existing.get("is_active") == 1:
+                    stats.unchanged += 1
+                else:
+                    self.rows[key] = payload
+                    stats.updated += 1
+                    write_count += 1
+                if fail_after_writes is not None and write_count >= fail_after_writes:
+                    raise RuntimeError(
+                        f"simulated write failure after {write_count} insert/update write(s)"
+                    )
+            for key, existing in list(self.rows.items()):
+                if key not in seen and existing.get("is_active") == 1:
+                    existing["is_active"] = 0
+                    stats.removed += 1
+            self.commit()
+            return stats
+        except Exception:
+            self.rollback()
+            raise
+
+
+class ExportSpy:
+    """若 sync 路径误调导出器，测试应失败。"""
+
+    def __init__(self) -> None:
+        self.calls: list[str] = []
+
+    def write_csv(self, *_a: Any, **_k: Any) -> None:
+        self.calls.append("csv")
+
+    def write_excel(self, *_a: Any, **_k: Any) -> None:
+        self.calls.append("excel")
+
+
+def sync_records(
+    store: MemoryRecordStore,
+    external_rows: list[dict[str, Any]],
+    *,
+    snapshot_complete: bool,
+    exporter: ExportSpy | None = None,
+    fail_after_writes: int | None = None,
+) -> dict[str, int]:
+    """领域同步内核示意：只写库，不导出文件。
+
+    ``snapshot_complete`` 为 keyword-only **必填**参数（无默认值）：
+      - False：读取失败/分页不完整/不可信结果 → 不得清库或失效旧数据
+      - True：外源完整快照（可为空）→ 允许按全量策略 upsert / 标记失效
+    调用方必须显式传入，禁止默认当作完整快照，也禁止靠条数猜测完整性。
+    """
+    if external_rows is None:
+        raise ValueError("external_rows required")
+    if not snapshot_complete:
+        active = sum(1 for r in store.rows.values() if r.get("is_active") == 1)
+        return SyncStats(total=0, unchanged=active).as_dict()
+    stats = store.upsert_snapshot(external_rows, fail_after_writes=fail_after_writes)
+    if exporter is not None:
+        # 正确实现不得调用；本示意刻意不调用，供测试断言
+        pass
+    return stats.as_dict()
+
+
+class TestSyncContractSample(unittest.TestCase):
+    def test_first_sync_inserts(self) -> None:
+        store = MemoryRecordStore()
+        stats = sync_records(
+            store,
+            [{"business_key": "a", "title": "A"}, {"business_key": "b", "title": "B"}],
+            snapshot_complete=True,
+        )
+        self.assertEqual(stats["inserted"], 2)
+        self.assertEqual(stats["total"], 2)
+        self.assertEqual(len(store.rows), 2)
+
+    def test_second_sync_is_idempotent(self) -> None:
+        store = MemoryRecordStore()
+        rows = [{"business_key": "a", "title": "A"}]
+        sync_records(store, rows, snapshot_complete=True)
+        stats = sync_records(store, rows, snapshot_complete=True)
+        self.assertEqual(stats["unchanged"], 1)
+        self.assertEqual(stats["inserted"], 0)
+        self.assertEqual(stats["updated"], 0)
+
+    def test_updates_existing_row(self) -> None:
+        store = MemoryRecordStore()
+        sync_records(store, [{"business_key": "a", "title": "A"}], snapshot_complete=True)
+        stats = sync_records(
+            store, [{"business_key": "a", "title": "A2"}], snapshot_complete=True
+        )
+        self.assertEqual(stats["updated"], 1)
+        self.assertEqual(store.rows["a"]["title"], "A2")
+
+    def test_marks_removed_inactive_on_full_sync(self) -> None:
+        store = MemoryRecordStore()
+        sync_records(
+            store,
+            [{"business_key": "a", "title": "A"}, {"business_key": "b", "title": "B"}],
+            snapshot_complete=True,
+        )
+        stats = sync_records(
+            store, [{"business_key": "a", "title": "A"}], snapshot_complete=True
+        )
+        self.assertEqual(stats["removed"], 1)
+        self.assertEqual(store.rows["b"]["is_active"], 0)
+        self.assertEqual(store.rows["a"]["is_active"], 1)
+
+    def test_incomplete_empty_snapshot_does_not_wipe_existing(self) -> None:
+        store = MemoryRecordStore()
+        sync_records(store, [{"business_key": "a", "title": "A"}], snapshot_complete=True)
+        stats = sync_records(store, [], snapshot_complete=False)
+        self.assertEqual(store.rows["a"]["is_active"], 1)
+        self.assertEqual(stats["removed"], 0)
+        self.assertEqual(stats["unchanged"], 1)
+
+    def test_complete_empty_snapshot_marks_existing_inactive(self) -> None:
+        store = MemoryRecordStore()
+        sync_records(
+            store,
+            [{"business_key": "a", "title": "A"}, {"business_key": "b", "title": "B"}],
+            snapshot_complete=True,
+        )
+        stats = sync_records(store, [], snapshot_complete=True)
+        self.assertEqual(stats["removed"], 2)
+        self.assertEqual(store.rows["a"]["is_active"], 0)
+        self.assertEqual(store.rows["b"]["is_active"], 0)
+
+    def test_omitting_snapshot_complete_raises_type_error(self) -> None:
+        store = MemoryRecordStore()
+        with self.assertRaises(TypeError):
+            sync_records(store, [{"business_key": "a", "title": "A"}])  # type: ignore[call-arg]
+
+    def test_transaction_failure_after_partial_writes_rolls_back(self) -> None:
+        store = MemoryRecordStore()
+        sync_records(store, [{"business_key": "a", "title": "A"}], snapshot_complete=True)
+        with self.assertRaises(RuntimeError) as ctx:
+            sync_records(
+                store,
+                [
+                    {"business_key": "a", "title": "A2"},
+                    {"business_key": "b", "title": "B"},
+                ],
+                snapshot_complete=True,
+                fail_after_writes=1,
+            )
+        self.assertIn("after 1", str(ctx.exception))
+        self.assertEqual(store.rows["a"]["title"], "A")
+        self.assertNotIn("b", store.rows)
+        self.assertFalse(store.in_transaction)
+        self.assertIsNone(store._tx_snapshot)
+
+    def test_stats_keys_cover_inserted_updated_unchanged_removed(self) -> None:
+        store = MemoryRecordStore()
+        sync_records(
+            store,
+            [{"business_key": "a", "title": "A"}, {"business_key": "b", "title": "B"}],
+            snapshot_complete=True,
+        )
+        stats = sync_records(
+            store,
+            [{"business_key": "a", "title": "A2"}],
+            snapshot_complete=True,
+        )
+        for key in ("total", "inserted", "updated", "unchanged", "removed"):
+            self.assertIn(key, stats)
+        self.assertEqual(stats["updated"], 1)
+        self.assertEqual(stats["removed"], 1)
+
+    def test_sync_does_not_call_file_exporters(self) -> None:
+        store = MemoryRecordStore()
+        spy = ExportSpy()
+        sync_records(
+            store,
+            [{"business_key": "a", "title": "A"}],
+            snapshot_complete=True,
+            exporter=spy,
+        )
+        self.assertEqual(spy.calls, [])
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/samples/test_table_deprecation_migration.py.sample

@@ -0,0 +1,66 @@
+# -*- coding: utf-8 -*-
+"""旧库废弃表迁移样例（复制到 tests/ 并按技能改写）。
+
+验收：给定旧库含废弃物理表 + 元数据 + 历史行 → init_db() 后表与元数据均清除。
+见 references/SCHEMA.md「表增删改与退役」。
+"""
+from __future__ import annotations
+
+import unittest
+
+from _support import IsolatedDataRoot
+
+
+class TestTableDeprecationMigration(unittest.TestCase):
+  def test_init_db_drops_legacy_task_logs(self) -> None:
+    with IsolatedDataRoot():
+      from db.connection import get_conn, init_db
+      from db.display_metadata import iter_user_tables
+
+      # 1) 模拟升级前的旧库
+      init_db()
+      conn = get_conn()
+      try:
+        cur = conn.cursor()
+        cur.execute(
+          """
+          CREATE TABLE task_logs (
+            id INTEGER PRIMARY KEY,
+            task_type TEXT,
+            status TEXT
+          )
+          """
+        )
+        cur.execute(
+          """
+          INSERT INTO _jiangchang_tables
+          (table_name, display_name, visible, readonly)
+          VALUES ('task_logs', '任务日志', 1, 0)
+          """
+        )
+        cur.execute("INSERT INTO task_logs (task_type, status) VALUES ('run', 'ok')")
+        conn.commit()
+      finally:
+        conn.close()
+
+      # 2) 新代码 init_db() 应幂等清除（在 connection.init_db 中调用 drop_deprecated_user_table）
+      init_db()
+
+      conn = get_conn()
+      try:
+        cur = conn.cursor()
+        cur.execute(
+          "SELECT 1 FROM sqlite_master WHERE type='table' AND name='task_logs'"
+        )
+        self.assertIsNone(cur.fetchone())
+        cur.execute(
+          "SELECT COUNT(*) FROM _jiangchang_tables WHERE table_name='task_logs'"
+        )
+        self.assertEqual(int(cur.fetchone()[0]), 0)
+        self.assertNotIn("task_logs", list(iter_user_tables(cur)))
+      finally:
+        conn.close()
+
+
+if __name__ == "__main__":
+  unittest.main()