# -*- coding: utf-8 -*-
"""
仓库治理只读审计 — 共享数据模型

定义审计脚本各模块共用的 dataclass 和枚举类型。
"""

from __future__ import annotations

from dataclasses import dataclass, field
from enum import Enum


# ---------------------------------------------------------------------------
# 文件元信息
# ---------------------------------------------------------------------------

@dataclass
class FileEntry:
    """单个文件/目录的元信息。"""

    rel_path: str          # 相对于仓库根目录的路径
    is_dir: bool           # 是否为目录
    size_bytes: int        # 文件大小（目录为 0）
    extension: str         # 文件扩展名（小写，含点号）
    is_empty_dir: bool     # 是否为空目录


# ---------------------------------------------------------------------------
# 用途分类与处置标签
# ---------------------------------------------------------------------------

class Category(str, Enum):
    """文件用途分类。"""

    CORE_CODE = "核心代码"
    CONFIG = "配置"
    DATABASE_DEF = "数据库定义"
    TEST = "测试"
    DOCS = "文档"
    SCRIPTS = "脚本工具"
    GUI = "GUI"
    BUILD_DEPLOY = "构建与部署"
    LOG_OUTPUT = "日志与输出"
    TEMP_DEBUG = "临时与调试"
    OTHER = "其他"


class Disposition(str, Enum):
    """处置标签。"""

    KEEP = "保留"
    CANDIDATE_DELETE = "候选删除"
    CANDIDATE_ARCHIVE = "候选归档"
    NEEDS_REVIEW = "待确认"


# ---------------------------------------------------------------------------
# 文件清单条目
# ---------------------------------------------------------------------------

@dataclass
class InventoryItem:
    """清单条目：路径 + 分类 + 处置 + 说明。"""

    rel_path: str
    category: Category
    disposition: Disposition
    description: str


# ---------------------------------------------------------------------------
# 流程树节点
# ---------------------------------------------------------------------------

@dataclass
class FlowNode:
    """流程树节点。"""

    name: str                              # 节点名称（模块名/类名/函数名）
    source_file: str                       # 所在源文件路径
    node_type: str                         # 类型：entry / module / class / function
    children: list[FlowNode] = field(default_factory=list)


# ---------------------------------------------------------------------------
# 文档对齐
# ---------------------------------------------------------------------------

@dataclass
class DocMapping:
    """文档与代码的映射关系。"""

    doc_path: str              # 文档文件路径
    doc_topic: str             # 文档主题
    related_code: list[str]    # 关联的代码文件/模块
    status: str                # 状态：aligned / stale / conflict / orphan


@dataclass
class AlignmentIssue:
    """对齐问题。"""

    doc_path: str              # 文档路径
    issue_type: str            # stale / conflict / missing
    description: str           # 问题描述
    related_code: str          # 关联代码路径