{"record":{"id":"4cbeb22a8d63d2a7","repo":"666ghj/MiroFish","slug":"suffix","errorCode":null,"errorMessage":"不支持的文件格式: {suffix}","messagePattern":"不支持的文件格式: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"backend/app/utils/file_parser.py","lineNumber":99,"sourceCode":"    def extract_text(cls, file_path: str) -> str:\n        \"\"\"\n        从文件中提取文本\n        \n        Args:\n            file_path: 文件路径\n            \n        Returns:\n            提取的文本内容\n        \"\"\"\n        path = Path(file_path)\n        \n        if not path.exists():\n            raise FileNotFoundError(f\"文件不存在: {file_path}\")\n        \n        suffix = path.suffix.lower()\n        \n        if suffix not in cls.SUPPORTED_EXTENSIONS:\n            raise ValueError(f\"不支持的文件格式: {suffix}\")\n        \n        if suffix == '.pdf':\n            return cls._extract_from_pdf(file_path)\n        elif suffix in {'.md', '.markdown'}:\n            return cls._extract_from_md(file_path)\n        elif suffix == '.txt':\n            return cls._extract_from_txt(file_path)\n        \n        raise ValueError(f\"无法处理的文件格式: {suffix}\")\n    \n    @staticmethod\n    def _extract_from_pdf(file_path: str) -> str:\n        \"\"\"从PDF提取文本\"\"\"\n        try:\n            import fitz  # PyMuPDF\n        except ImportError:\n            raise ImportError(\"需要安装PyMuPDF: pip install PyMuPDF\")\n        ","sourceCodeStart":81,"sourceCodeEnd":117,"githubUrl":"https://github.com/666ghj/MiroFish/blob/b5b53acc57189a4a42e44a23e149dc655c98fe82/backend/app/utils/file_parser.py#L81-L117","documentation":"ValueError raised by FileParser.extract_text when the lowercased file suffix is not in SUPPORTED_EXTENSIONS. The parser supports only a fixed set (pdf, md/markdown, txt and dispatch equivalents), and rejects anything else before attempting extraction.","triggerScenarios":"Calling extract_text on a file like document.docx, file.json, or archive.zip — any extension outside the supported set. Also a file with no suffix at all (path.suffix is ''), which is likewise not in the set.","commonSituations":"User uploads a format the backend never planned to support (docx, html, epub), frontend validation gap letting unsupported types through, or double extensions where the final suffix is the unsupported one.","solutions":["Restrict uploads at the API boundary to SUPPORTED_EXTENSIONS so the error never reaches the parser","Convert unsupported documents to pdf/txt/md before extraction (e.g. external converter)","Extend SUPPORTED_EXTENSIONS plus add a matching _extract_from_* branch if a new format is genuinely needed"],"exampleFix":"# before\ntext = FileParser.extract_text(str(upload))  # .docx -> ValueError\n\n# after\nALLOWED = set(FileParser.SUPPORTED_EXTENSIONS)\nif upload.suffix.lower() not in ALLOWED:\n    raise HTTPException(415, f\"unsupported file type: {upload.suffix}\")\ntext = FileParser.extract_text(str(upload))","handlingStrategy":"validation","validationCode":"suffix = Path(file_path).suffix.lower()\nif suffix not in FileParser.SUPPORTED_EXTENSIONS:\n    raise ValueError(f\"reject early: {suffix} not supported\")","typeGuard":null,"tryCatchPattern":"try:\n    text = FileParser.extract_text(path)\nexcept ValueError as e:\n    return http_error(415, str(e))","preventionTips":["Enforce the extension allow-list at the upload endpoint, not only in the parser","Keep frontend accepted-types list in sync with SUPPORTED_EXTENSIONS","Return 415 Unsupported Media Type for unsupported uploads"],"tags":["file-io","validation","file-format"],"backgroundTag":null,"analyzedSha":"b5b53acc57189a4a42e44a23e149dc655c98fe82","analyzedAt":"2026-08-14T22:29:33.146Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}