{"record":{"id":"5390fd350fedcb06","repo":"iflytek/astron-agent","slug":"database-table-field-import-default","errorCode":"DATABASE_TABLE_FIELD_IMPORT_DEFAULT","errorMessage":"DATABASE_TABLE_FIELD_IMPORT_DEFAULT","messagePattern":"DATABASE_TABLE_FIELD_IMPORT_DEFAULT","errorType":"error_code","errorClass":"BusinessException","httpStatus":null,"severity":"error","filePath":"console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/service/database/DBTableExcelReadListener.java","lineNumber":57,"sourceCode":"\n    /**\n     * Validate header format before parsing rows.\n     *\n     * @param headMap the header map from Excel\n     * @param context analysis context\n     * @throws BusinessException if the header format does not match expected\n     */\n    @Override\n    public void invokeHeadMap(Map<Integer, String> headMap, AnalysisContext context) {\n        List<String> actualHeaders = new ArrayList<>(headMap.values());\n        List<String> expectedHeadersFormat;\n        if (LanguageContext.isEn()) {\n            expectedHeadersFormat = expectedHeadersEn;\n        } else {\n            expectedHeadersFormat = expectedHeaders;\n        }\n        if (!expectedHeadersFormat.equals(actualHeaders)) {\n            throw new BusinessException(ResponseEnum.DATABASE_TABLE_FIELD_IMPORT_DEFAULT);\n        }\n    }\n\n    /**\n     * Parse and validate each row, then convert to {@link DbTableFieldDto}.\n     *\n     * @param row the row data, key is column index, value is cell content\n     * @param context analysis context\n     * @throws BusinessException if required fields are empty, type is illegal, or default value is\n     *         invalid\n     */\n    @Override\n    public void invoke(Map<Integer, String> row, AnalysisContext context) {\n        // Validate required fields are not empty\n        DbTableFieldDto dbTableFieldDto = new DbTableFieldDto();\n        if (row.get(0) == null || row.get(1) == null || row.get(2) == null || row.get(4) == null) {\n            throw new BusinessException(ResponseEnum.DATABASE_CANNOT_EMPTY);\n        }","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/service/database/DBTableExcelReadListener.java#L39-L75","documentation":"DBTableExcelReadListener.invokeHeadMap throws BusinessException(DATABASE_TABLE_FIELD_IMPORT_DEFAULT) when the first row of the uploaded Excel does not exactly match the expected header list — Chinese headers (字段名*, 数据类型*, 描述*, 默认值, 是否必填*) when LanguageContext is not English, or English headers (Field Name*, Data Type*, Description*, Default Value, Required*) when it is. The comparison is strict ordered equality, so any rename, reorder, extra, or missing column fails.","triggerScenarios":"Uploading a table-field import template whose header row was edited, translated, or reordered; the file uses Chinese headers while the session language context is English (or vice versa); extra leading/trailing columns or whitespace in header cells.","commonSituations":"Users modify or delete template headers; a template from a different locale (Chinese vs English UI) is uploaded; headers copied with extra spaces; columns rearranged in Excel.","solutions":["Re-download the import template from the UI matching the current interface language and import it unmodified.","Restore the exact header row: 字段名*, 数据类型*, 描述*, 默认值, 是否必填* (or the English equivalents), in that order, with no extra columns.","Check the session/request language context (LanguageContext) matches the template language being uploaded."],"exampleFix":"// before (header row)\n// name | type | desc | default | required\n// after (exact template headers)\n// 字段名* | 数据类型* | 描述* | 默认值 | 是否必填*","handlingStrategy":"validation","validationCode":"// pre-flight header check against the template for the active language\nList<String> expected = LanguageContext.isEn()\n    ? List.of(\"Field Name*\", \"Data Type*\", \"Description*\", \"Default Value\", \"Required*\")\n    : List.of(\"字段名*\", \"数据类型*\", \"描述*\", \"默认值\", \"是否必填*\");\n// read row 0 and compare with expected.equals(actualHeaders) before invoking the listener","typeGuard":null,"tryCatchPattern":"try {\n    EasyExcel.read(file, listener).sheet().doRead();\n} catch (BusinessException e) {\n    if (\"DATABASE_TABLE_FIELD_IMPORT_DEFAULT\".equals(e.getCode())) {\n        // instruct user to re-download the template for their UI language\n    }\n}","preventionTips":["Re-download the template from the UI each time instead of reusing edited copies.","Keep headers in the exact template order with no added/removed columns.","Match the template language to the current interface language context."],"tags":["excel","header-validation","template-mismatch","java"],"backgroundTag":"schema-validation-failed","analyzedSha":"5e758547a83371a5a4b29dadf4ac03e8dd527635","analyzedAt":"2026-09-12T08:03:51.356Z","contentChangedAt":"2026-09-12T08:03:51.356Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}