contract-archive-cli 0.2.7__py3-none-any.whl

contract_archive/archive/migrations/001_init.sql

@@ -0,0 +1,62 @@
+-- 档案库初始 schema (version 1)
+--
+-- 设计要点（来自多轮 review 仲裁）：
+-- 1. status / severity 不加 CHECK constraint：未来加状态要重建表（SQLite 限制），
+--    校验下沉到 Pydantic 层更灵活
+-- 2. amount 用 INTEGER 分（amount_cents），避免 REAL 累加精度漂移；
+--    同时保留 amount_text 原文供人工核对
+-- 3. 不用 FTS5：典型档案库规模千级，LIKE '%关键词%' 全表扫毫秒级；
+--    trigram 要求 ≥3 字符匹配，2 字中文人名/词（"车位"/"张三"）会全部 miss，
+--    unicode61 单字切分对中文精度太差。务实选择 LIKE。
+-- 4. ingested_at 加 DESC 索引：list 命令默认排序走索引
+-- 5. AUTOINCREMENT 保留：防止 delete 后 rowid 复用指向新合同
+
+CREATE TABLE schema_version (
+  version    INTEGER PRIMARY KEY,
+  applied_at TEXT NOT NULL
+);
+
+CREATE TABLE documents (
+  id                  INTEGER PRIMARY KEY AUTOINCREMENT,
+  sha256              TEXT NOT NULL UNIQUE,
+  source_path         TEXT NOT NULL,            -- 原始 PDF 绝对路径（用户引用）
+  output_dir          TEXT NOT NULL,            -- archive/documents/<sha-short>/ 绝对路径
+  ingested_at         TEXT NOT NULL,            -- ISO8601 UTC 'YYYY-MM-DDTHH:MM:SSZ'
+  mineru_duration_s   REAL,
+  llm_duration_s      REAL,
+  status              TEXT NOT NULL,            -- 'ok' | 'partial' | 'failed'
+  error_message       TEXT,
+
+  -- 合同字段（rule + LLM hybrid 抽取结果）
+  contract_name       TEXT,
+  party_a             TEXT,
+  party_b             TEXT,
+  amount_text         TEXT,                     -- "人民币壹佰万元整"，原文
+  amount_cents        INTEGER,                  -- 1000000 * 100 = 100000000，精确分
+  sign_date           TEXT,                     -- ISO 'YYYY-MM-DD'
+  expire_date         TEXT,
+  auto_renewal        INTEGER,                  -- 0/1/NULL
+  overall_confidence  REAL                      -- [0, 1]
+);
+
+CREATE INDEX idx_doc_party_a   ON documents(party_a);
+CREATE INDEX idx_doc_party_b   ON documents(party_b);
+CREATE INDEX idx_doc_sign_date ON documents(sign_date);
+CREATE INDEX idx_doc_expire    ON documents(expire_date);
+CREATE INDEX idx_doc_amount    ON documents(amount_cents);
+CREATE INDEX idx_doc_status    ON documents(status);
+CREATE INDEX idx_doc_ingested  ON documents(ingested_at DESC);
+
+CREATE TABLE risk_clauses (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  doc_id      INTEGER NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+  clause_text TEXT NOT NULL,
+  severity    TEXT                              -- 'low' | 'med' | 'high' | NULL
+);
+CREATE INDEX idx_risk_doc ON risk_clauses(doc_id);
+
+-- name / party 字符串字段加索引，加速 LIKE '%xxx%' 之外的等值/前缀查询。
+-- LIKE '%xxx%' 本身无法走 B-tree 索引（前置通配），但合同档案库规模小，
+-- 全表扫描完全可接受（1 万条 < 10ms）。
+
+INSERT INTO schema_version(version, applied_at) VALUES(1, strftime('%Y-%m-%dT%H:%M:%SZ', 'now'));

contract_archive/archive/migrations/002_obligations.sql

@@ -0,0 +1,25 @@
+-- 档案库 schema v2：合同双方义务/动作清单
+--
+-- 设计要点：
+-- 1. 独立表：典型合同有 5-15 条义务，每条带 actor + deadline，独立表才能走
+--    `WHERE deadline < ?` 索引做"近 30 天待办看板"
+-- 2. 不加 actor/severity 的 CHECK constraint（v1 同样的理由：未来加新值
+--    免重建表，Pydantic 层校验更灵活）
+-- 3. ordering 列保留原文出现顺序，show 命令展示时按顺序好读
+
+CREATE TABLE obligations (
+  id         INTEGER PRIMARY KEY AUTOINCREMENT,
+  doc_id     INTEGER NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+  actor      TEXT NOT NULL,        -- 'party_a' | 'party_b' | 'both'
+  action     TEXT NOT NULL,        -- "递交审贷资料"
+  deadline   TEXT,                  -- ISO 'YYYY-MM-DD' 或 NULL
+  evidence   TEXT,                  -- 原文片段
+  ordering   INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE INDEX idx_obligations_doc      ON obligations(doc_id);
+CREATE INDEX idx_obligations_deadline ON obligations(deadline);
+CREATE INDEX idx_obligations_actor    ON obligations(actor);
+
+INSERT INTO schema_version(version, applied_at)
+  VALUES(2, strftime('%Y-%m-%dT%H:%M:%SZ', 'now'));

contract_archive/archive/migrations/003_document_types.sql

@@ -0,0 +1,31 @@
+-- 档案库 schema v3：多文档类型支持（合同 → 通用文档档案库）
+--
+-- 设计要点：
+-- 1. 加法式迁移——保留全部合同列（party_a/b、amount_*、sign/expire_date、
+--    auto_renewal、risk_clauses、obligations 不动），合同的查询/统计照常工作。
+-- 2. 新增"通用信封"列：任何文档类型都填这几列，list/show/搜索走通用列即可
+--    跨类型统一展示，类型专属字段整体存 details_json。
+-- 3. doc_type 不加 CHECK constraint（沿用 v1/v2 理由：未来加类型免重建表，
+--    校验下沉到 Pydantic/LLM 层）。规范取值见 schemas.DOC_TYPES。
+-- 4. 回填：现存行都是历史合同，把合同字段映射到通用列，保证老数据在新
+--    list/show 里不空白。
+
+ALTER TABLE documents ADD COLUMN doc_type TEXT NOT NULL DEFAULT '合同协议';
+ALTER TABLE documents ADD COLUMN title TEXT;                  -- 通用标题（合同名/证明抬头/发票号…）
+ALTER TABLE documents ADD COLUMN summary TEXT;                -- 一句话摘要（可追溯钩子）
+ALTER TABLE documents ADD COLUMN details_json TEXT;          -- 类型专属字段（parties/amounts/fields/key_dates）整体 JSON
+ALTER TABLE documents ADD COLUMN primary_date TEXT;          -- 主日期 ISO（合同=签订日，证明=出具日）
+ALTER TABLE documents ADD COLUMN primary_amount_cents INTEGER;  -- 主金额（分），跨类型金额排序/过滤
+
+-- 回填历史合同行 → 通用列
+UPDATE documents SET title = contract_name WHERE title IS NULL;
+UPDATE documents SET summary = contract_name WHERE summary IS NULL AND contract_name IS NOT NULL;
+UPDATE documents SET primary_date = sign_date WHERE primary_date IS NULL;
+UPDATE documents SET primary_amount_cents = amount_cents WHERE primary_amount_cents IS NULL;
+
+CREATE INDEX idx_doc_type         ON documents(doc_type);
+CREATE INDEX idx_doc_primary_date ON documents(primary_date);
+CREATE INDEX idx_doc_primary_amt  ON documents(primary_amount_cents);
+
+INSERT INTO schema_version(version, applied_at)
+  VALUES(3, strftime('%Y-%m-%dT%H:%M:%SZ', 'now'));

contract_archive/archive/migrations/004_seals_subjects.sql

@@ -0,0 +1,36 @@
+-- 档案库 schema v4：印章(seals) + 主体(subjects) 可索引子表
+--
+-- 设计要点（沿用 002/003 的既定取向）：
+-- 1. 一类一表：印章和主体各自独立子表，承载各自的可索引列。这是项目既有风格
+--    （risk_clauses / obligations 同构），让数据结构贴合查询，不上泛化 entities 表。
+-- 2. 双存合理冗余：seals/subjects 既进 details_json（envelope 整体 dump，供展示），
+--    又进子表（供 EXISTS 过滤 / 聚合）。写库三处（insert/update/replace）先 DELETE
+--    再批量 INSERT 保证一致——和 obligations/risk_clauses 完全一致。
+-- 3. ON DELETE CASCADE：删主表行时子表自动清，依赖 connect() 里的 PRAGMA foreign_keys=ON。
+-- 4. subjects 来源是信封 parties（合同另并入 party_a/b），让"按主体检索"覆盖所有文档类型，
+--    补上"证明类主体此前搜不到"的缺口。
+-- 5. 不加 CHECK constraint（沿用 v1-v3 理由：未来加值免重建表，校验下沉到 Pydantic/LLM）。
+
+CREATE TABLE document_seals (
+  id        INTEGER PRIMARY KEY AUTOINCREMENT,
+  doc_id    INTEGER NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+  owner     TEXT,                 -- 盖章主体（公司/机构全称），认不出为 NULL
+  seal_type TEXT,                 -- "公章" / "合同专用章" / "财务专用章" ...
+  raw_text  TEXT NOT NULL,        -- 印章 OCR 原文（可能残缺），可追溯
+  ordering  INTEGER NOT NULL DEFAULT 0
+);
+CREATE INDEX idx_seals_doc   ON document_seals(doc_id);
+CREATE INDEX idx_seals_owner ON document_seals(owner);
+CREATE INDEX idx_seals_type  ON document_seals(seal_type);
+
+CREATE TABLE document_subjects (
+  id       INTEGER PRIMARY KEY AUTOINCREMENT,
+  doc_id   INTEGER NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+  subject  TEXT NOT NULL,         -- 主体名（人/机构全称）
+  ordering INTEGER NOT NULL DEFAULT 0
+);
+CREATE INDEX idx_subjects_doc  ON document_subjects(doc_id);
+CREATE INDEX idx_subjects_name ON document_subjects(subject);
+
+INSERT INTO schema_version(version, applied_at)
+  VALUES(4, strftime('%Y-%m-%dT%H:%M:%SZ', 'now'));

contract_archive/archive/migrations/005_completeness.sql

@@ -0,0 +1,18 @@
+-- 档案库 schema v5：合同完整性核查状态（可索引）
+--
+-- 设计要点（沿用 003/004 的既定取向）：
+-- 1. 加法式：只新增一列，不动任何现有列/表，老数据照常工作。
+-- 2. 双存合理冗余：完整性详情（status + issues）已随 envelope 整体进 details_json
+--    （供 show 展示），这里只把 status 镜像成一列，让 `list --incomplete` 能走
+--    WHERE 过滤——details_json 无法高效查询。和 003 的 primary_date 同构。
+-- 3. 取值：NULL=未判定/非合同（老数据、证明发票等），'complete'|'incomplete'|'unknown'。
+--    不加 CHECK constraint（沿用 v1-v4 理由：未来加值免重建表，校验下沉到 Pydantic/LLM）。
+-- 4. 加索引：--incomplete 是等值过滤，索引命中即可；档案库规模虽小，但这是查询
+--    入口列，加索引零代价（与 003 给 primary_date 加索引同理）。
+
+ALTER TABLE documents ADD COLUMN completeness_status TEXT;  -- NULL=未判定/非合同, 'complete'|'incomplete'|'unknown'
+
+CREATE INDEX idx_doc_completeness ON documents(completeness_status);
+
+INSERT INTO schema_version(version, applied_at)
+  VALUES(5, strftime('%Y-%m-%dT%H:%M:%SZ', 'now'));

contract_archive/archive/party_registry.py

@@ -0,0 +1,276 @@
+"""
+主体身份基准库（known_parties）：跨文档核对主体的固有标识。
+
+为什么独立于 db.sqlite：这是"基本信息基准"而非"文档档案"——它跨文档累积
+（某主体的身份证号一次录入、之后每份文档都拿来核对），生命周期与单份文档解耦。
+存档案库根目录 known_parties.json，含真实 PII，故文件权限 0600、列入 .gitignore。
+
+核对模型（用户要的"首见入库、再见校对"）：
+  - 某主体的某标识首次出现 → 录入为基准，记首见出处。
+  - 之后同主体同标识再出现 → 与基准比对，不一致即报 identity 缺陷（不覆盖基准，
+    基准保持稳定；要修正基准用 `party set`）。
+  - 不分自然人/机构：身份证、电话、银行账号、开户行、税号一律核对。
+
+归一化：比较时去除空白与常见分隔符（OCR 把"；"读成"："、夹空格等不算差异），
+但保留真实数字差异（多一位/少一位/改一位）——后者正是要抓的 OCR 读错/篡改。
+
+实体对齐（key 不是字面 name，而是"实体"）：同一实体在不同文档/同一文档内常被
+识别成不同名字（LLM 幻觉改字、称谓差异、OCR 误读），若按字面 name 作 key 就会
+分裂、跨文档核对不到一起。故归位规则：
+  - 主体名先规范化（剥离"甲方：/出卖人："等分隔符门控的称谓前缀）。
+  - 强标识（身份证/银行账号/印章/统一社会信用代码/税号）实体唯一，同值必同实体——
+    本次某强标识值若已登记在另一 name 下，即归并到那个已有 key，并把本次 name 记入
+    别名表，今后即使只带弱标识也能归位。
+  - 弱标识（电话、开户行）多人共用（公司总机、银行支行），绝不据此合并，避免误并。
+"""
+from __future__ import annotations
+
+import json
+import logging
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from ..schemas import CompletenessIssue, PersonIdentity
+
+logger = logging.getLogger(__name__)
+
+REGISTRY_VERSION = 2  # v2 起新增 aliases（实体归并别名表）；v1 文件仍可读，缺则按空表
+
+# 比较前剥离的噪声字符：空白 + 常见分隔/标点。不动数字、字母、汉字本身。
+_NOISE_RE = re.compile(r"[\s;；,，、:：.。\-—_／/]")
+
+# 称谓前缀：name 开头的"甲方/乙方/出卖人…"+ 分隔符，规范化时剥离，使
+# "甲方：示例置业"与"示例置业"归到同一 key。仅当前缀后紧跟分隔符才剥离，
+# 避免误伤"甲方物流有限公司"这类前缀恰是名字一部分的合法名。
+_ROLE_PREFIXES = (
+    "甲方", "乙方", "丙方", "出卖人", "买受人", "出租方", "承租方",
+    "转让方", "受让方", "委托方", "受托方", "持证人", "卖方", "买方",
+)
+# 前缀后须接"分隔标点"或"一段空白"才剥离；二者皆无（如"甲方物流"）则前缀属名字本身，不剥。
+_ROLE_PREFIX_RE = re.compile(
+    r"^(?:" + "|".join(_ROLE_PREFIXES) + r")(?:\s*[:：、|/\\\-]+\s*|\s+)"
+)
+
+# 强标识 label 关键字：这些标识实体唯一（同值必同实体），可据此把同实体的不同
+# name 变体归并到一个 key。电话/开户行是弱标识（多人共用），故意不在此列。
+_STRONG_LABEL_KEYS = ("身份证", "银行账", "印章", "信用代码", "税号")
+
+
+def _canon(value: str) -> str:
+    """归一化用于比较：去首尾空白 + 剥离分隔/标点噪声。
+
+    使 OCR 分隔符差异（空格、"；"读成"："等）不误报；但多一位/少一位/改一位
+    这类真实数字差异会保留下来——那正是要抓的 OCR 读错或信息被改。
+    """
+    return _NOISE_RE.sub("", value.strip())
+
+
+def _canon_name(name: str) -> str:
+    """主体名规范化作 registry key：去首尾空白 + 剥离分隔符门控的称谓前缀。"""
+    return _ROLE_PREFIX_RE.sub("", name.strip())
+
+
+def group_by_value(ids: dict) -> list[tuple[str, dict]]:
+    """把同一主体下『归一化值相同』的多个 label 折叠成一组，供人读展示去冗余。
+
+    同一个号被不同文档写成不同 label（如『电话』『联系电话』）时，在 party list/show
+    里并排堆着是纯噪声、零信息。canon 值相等即视为同一事实，标签并成『电话/联系电话』，
+    rec 取首个（即基准首见那条）。值不同的 label（如公司总机 vs 联系人线）各自独立、
+    绝不合并——与 reconcile『弱标识不据此并实体』同一立场：这里只折叠展示、不动数据。
+
+    判等用 reconcile 同一套 _canon，保证『展示折叠』与『一致性校对』口径一致：
+    凡 reconcile 视作"无差异"的两值，这里才折叠；有真实数字差异的不会被并掉。
+    保持各组首次出现的插入顺序。
+
+    Args:
+        ids: 某主体的标识基准，label -> rec（rec 含 value/first_seen_doc/role 等）。
+    Returns:
+        [(合并后标签, 首个rec), ...]，按各组首次出现顺序排列。
+    """
+    labels_of: dict[str, list[str]] = {}   # canon(value) -> 同值的 label 列表
+    rep_rec: dict[str, dict] = {}          # canon(value) -> 首个 rec（基准首见那条）
+    order: list[str] = []                  # canon(value) 首次出现顺序，定输出顺序
+    for label, rec in ids.items():
+        key = _canon(rec.get("value") or "")
+        if key not in labels_of:
+            labels_of[key] = []
+            rep_rec[key] = rec
+            order.append(key)
+        labels_of[key].append(label)
+    return [("/".join(labels_of[key]), rep_rec[key]) for key in order]
+
+
+def _is_strong_label(label: str) -> bool:
+    """该标识是否为实体唯一的强标识（可据此把不同 name 归并为同一实体）。"""
+    return any(k in label for k in _STRONG_LABEL_KEYS)
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+class PartyRegistry:
+    """known_parties.json 的读写 + 首见入库/再见校对。"""
+
+    def __init__(self, path: Path, data: Optional[dict] = None) -> None:
+        self._path = path
+        self._data = data if data is not None else {
+            "version": REGISTRY_VERSION, "parties": {}, "aliases": {},
+        }
+        self._dirty = False
+
+    # ---------- 加载 / 保存 ----------
+
+    @classmethod
+    def load(cls, path: Path) -> "PartyRegistry":
+        """读基准库；文件不存在/损坏/结构非法一律返回空库——只读路径必须健壮，坏文件不能让入库崩。"""
+        if not path.exists():
+            return cls(path)
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError) as e:
+            logger.warning("known_parties 读取失败，按空库处理: %s", e)
+            return cls(path)
+        if not isinstance(payload, dict) or not isinstance(payload.get("parties"), dict):
+            logger.warning("known_parties 结构非法，按空库处理: %s", path)
+            return cls(path)
+        return cls(path, payload)
+
+    def save(self) -> Path:
+        """写基准库；文件 0600（含 PII，仅本人可读，每次都 chmod 防 umask 宽松）。"""
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        self._path.write_text(
+            json.dumps(self._data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
+        )
+        self._path.chmod(0o600)
+        self._dirty = False
+        return self._path
+
+    @property
+    def dirty(self) -> bool:
+        """自上次 load/save 以来是否有录入改动（调用方据此决定要不要 save）。"""
+        return self._dirty
+
+    # ---------- 核对（首见入库 / 再见校对）----------
+
+    def reconcile(self, identities: list[PersonIdentity], doc_sha: str) -> list[CompletenessIssue]:
+        """
+        把一份文档抽到的 person_identities 与基准库比对（按实体对齐，非字面 name）。
+
+        每个主体先经 _resolve_entity 定位 canonical key（别名/强标识归并）：
+        首见（canonical 无此标识）→ 录入基准并记首见出处；
+        再见（canonical 已有）→ 比对，不一致返回 identity 缺陷（不覆盖基准）。
+        就地修改基准库（录入首见 + 学到的别名），是否落盘由调用方 save 决定（看 dirty）。
+        """
+        issues: list[CompletenessIssue] = []
+        parties = self._data["parties"]
+        aliases = self._data.setdefault("aliases", {})   # name 变体 → canonical（v1 文件无此键）
+        for person in identities:
+            if not person.name.strip():
+                continue
+            name = _canon_name(person.name)
+            canonical = self._resolve_entity(name, person, parties, aliases)
+            if canonical != name and aliases.get(name) != canonical:
+                aliases[name] = canonical            # 记下别名，今后只带弱标识也能归位
+                self._dirty = True
+            slot = parties.setdefault(canonical, {})
+            for idv in person.identifiers:
+                label, value = idv.label.strip(), idv.value.strip()
+                if not label or not value:
+                    continue
+                known = slot.get(label)
+                if known is None:
+                    slot[label] = {
+                        "value": value,
+                        "first_seen_doc": doc_sha,
+                        "first_seen_at": _now_iso(),
+                        "role": person.role or "",
+                    }
+                    self._dirty = True
+                elif _canon(known.get("value", "")) != _canon(value):
+                    base = known.get("value", "")
+                    src = str(known.get("first_seen_doc", ""))[:12]
+                    issues.append(CompletenessIssue(
+                        item=f"{canonical}·{label}",
+                        category="identity",
+                        detail=(
+                            f"与基准不一致：基准『{base}』(首见于 {src})，"
+                            f"本次『{value}』——疑似 OCR 读错或信息被改，请人工核对"
+                        ),
+                        evidence=f"本次文档 {doc_sha[:12]}",
+                    ))
+        return issues
+
+    def _resolve_entity(
+        self, name: str, person: PersonIdentity, parties: dict, aliases: dict
+    ) -> str:
+        """
+        定位本主体应归入的 canonical key（实体对齐，而非字面 name）：
+          1. 已是已知别名 → 直达其 canonical；
+          2. 已是现有 key → 用自己；
+          3. 本次某强标识值已登记在另一 name 下 → 同实体，归并到那个已有 key；
+          4. 都不是 → 新实体，用规范化后的 name。
+
+        只用强标识（身份证/银行账号/印章/信用代码/税号）归并——它们实体唯一，
+        同值必同实体；弱标识（电话/开户行）多人共用，绝不据此合并。
+        """
+        if name in aliases:
+            return aliases[name]
+        if name in parties:
+            return name
+        for idv in person.identifiers:
+            if not _is_strong_label(idv.label):
+                continue
+            value = _canon(idv.value.strip())
+            if not value:
+                continue
+            for existing_name, slot in parties.items():
+                for label, info in slot.items():
+                    if _is_strong_label(label) and _canon(info.get("value", "")) == value:
+                        return existing_name
+        return name
+
+    # ---------- 管理（party 命令组用）----------
+
+    def all_parties(self) -> dict:
+        """全部基准：name → {label → {value, first_seen_doc, first_seen_at, role}}。"""
+        return self._data["parties"]
+
+    def get(self, name: str) -> Optional[dict]:
+        """某主体的全部标识基准；无则 None。"""
+        return self._data["parties"].get(name.strip())
+
+    def set(self, name: str, label: str, value: str) -> None:
+        """手动录入/修正基准（覆盖既有值，来源标记为 manual，便于 show 区分）。"""
+        name, label, value = name.strip(), label.strip(), value.strip()
+        if not name or not label or not value:
+            raise ValueError("name/label/value 均不能为空")
+        slot = self._data["parties"].setdefault(name, {})
+        slot[label] = {
+            "value": value,
+            "first_seen_doc": "(manual)",
+            "first_seen_at": _now_iso(),
+            "role": slot.get(label, {}).get("role", ""),
+        }
+        self._dirty = True
+
+    def remove(self, name: str, label: Optional[str] = None) -> bool:
+        """删某主体的某标识；label 省略则删整个主体。返回是否真的删到。"""
+        name = name.strip()
+        parties = self._data["parties"]
+        if name not in parties:
+            return False
+        if label is None:
+            del parties[name]
+            self._dirty = True
+            return True
+        label = label.strip()
+        if label in parties[name]:
+            del parties[name][label]
+            if not parties[name]:        # 主体下已无任何标识，清掉空壳
+                del parties[name]
+            self._dirty = True
+            return True
+        return False

contract_archive/archive/paths.py

@@ -0,0 +1,113 @@
+"""
+档案库路径约定 + 文件操作小工具。
+
+archive/
+  db.sqlite (+ -wal, -shm)
+  ingest.jsonl                # 总 log，每次 ingest 一行 JSON
+  documents/
+    <sha-short>/              # sha256 前 12 位
+      source.pdf              # 留档源 PDF（硬链接优先，跨盘 fallback copy）
+      mineru/                 # MinerU 原始产物（markdown.md / layout.json / images/...）
+      extracted.json          # 抽取结果 + 置信度（复跑 extract 命令的输入）
+      ingest.log              # 单合同详细 stderr
+  tmp/                        # ingest 过程暂存区，全成功后 os.rename 到 documents/
+"""
+from __future__ import annotations
+
+import hashlib
+import os
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+
+SHA_SHORT_LEN = 12
+
+# XDG 数据目录下的应用子目录名（跟 CLI / repo 名对齐）
+APP_DIR_NAME = "contract-archive"
+
+
+def default_archive_root() -> Path:
+    """
+    无 --archive / CONTRACT_ARCHIVE_DIR 时的默认档案库根，遵循 XDG Base Directory 约定。
+
+    数据类文件（db + 文档产物 + 日志）属于 XDG "data"：
+      $XDG_DATA_HOME/contract-archive  （默认 ~/.local/share/contract-archive）
+
+    按 XDG 规范：$XDG_DATA_HOME 仅在被设置且为绝对路径时生效，否则回退默认值。
+    """
+    xdg_data = os.getenv("XDG_DATA_HOME", "").strip()
+    base = Path(xdg_data) if xdg_data and os.path.isabs(xdg_data) else Path.home() / ".local" / "share"
+    return base / APP_DIR_NAME
+
+
+@dataclass(frozen=True)
+class ArchivePaths:
+    """档案库根目录 + 派生路径。"""
+
+    root: Path
+
+    @property
+    def db_path(self) -> Path:
+        return self.root / "db.sqlite"
+
+    @property
+    def documents_dir(self) -> Path:
+        return self.root / "documents"
+
+    @property
+    def tmp_dir(self) -> Path:
+        return self.root / "tmp"
+
+    @property
+    def ingest_log(self) -> Path:
+        return self.root / "ingest.jsonl"
+
+    @property
+    def known_parties_path(self) -> Path:
+        """主体身份基准库（known_parties.json）。含真实 PII，存档案库根、权限 0600。"""
+        return self.root / "known_parties.json"
+
+    def doc_dir(self, sha256: str) -> Path:
+        return self.documents_dir / sha256[:SHA_SHORT_LEN]
+
+    def ensure(self) -> None:
+        """启动时调用：建立根目录骨架。tmp/ 不立即建（按需创建并清理）。"""
+        self.root.mkdir(parents=True, exist_ok=True)
+        self.documents_dir.mkdir(exist_ok=True)
+
+
+def sha256_of_file(path: Path, chunk_size: int = 1 << 20) -> str:
+    """流式 SHA256（避免大文件全文件读入）。"""
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        while True:
+            chunk = f.read(chunk_size)
+            if not chunk:
+                break
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def link_or_copy(src: Path, dst: Path) -> str:
+    """
+    优先硬链接（省空间，inode 共享），跨盘失败回退到 copy。
+    返回实际使用的策略，"link" 或 "copy"。
+    dst 已存在则先删除（reingest 场景）。
+    """
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    if dst.exists() or dst.is_symlink():
+        dst.unlink()
+    try:
+        os.link(src, dst)
+        return "link"
+    except OSError:
+        # 跨盘 / 不支持硬链接的文件系统（exFAT 等）
+        shutil.copy2(src, dst)
+        return "copy"
+
+
+def safe_rmtree(path: Path) -> None:
+    """删除目录（不存在则忽略）。仅用于已知是本工具创建的目录。"""
+    if path.exists():
+        shutil.rmtree(path)