{"record":{"id":"16a1ccaf885d40bd","repo":"jeecgboot/JeecgBoot","slug":"word","errorCode":null,"errorMessage":"生成word文档失败，请检查模版和数据是否正确","messagePattern":"生成word文档失败，请检查模版和数据是否正确","errorType":"exception","errorClass":"JeecgBootException","httpStatus":null,"severity":"error","filePath":"jeecg-boot/jeecg-boot-module/jeecg-boot-module-airag/src/main/java/org/jeecg/modules/airag/wordtpl/service/impl/AigcWordTemplateServiceImpl.java","lineNumber":63,"sourceCode":"    WordTplUtils wordTplUtils;\n\n    @Override\n    public void generateWordFromTpl(WordTplGenDTO wordTplGenDTO, ByteArrayOutputStream wordOutputStream) {\n        AssertUtils.assertNotEmpty(\"参数异常\", wordTplGenDTO);\n        AssertUtils.assertNotEmpty(\"模版ID不能为空\", wordTplGenDTO.getTemplateId());\n        String templateId = wordTplGenDTO.getTemplateId();\n        // 生成word模版 date:2025/7/10\n        AigcWordTemplate template = getById(templateId);\n        ByteArrayOutputStream wordTemplateOut = new ByteArrayOutputStream();\n        wordTplUtils.generateWordTemplate(template, wordTemplateOut);\n        //根据word模版和数据生成word文件\n        Map<String, Object> data = wordTplGenDTO.getData();\n        mergeSystemVarsToData(data);\n        try {\n            XWPFTemplate.compile(new ByteArrayInputStream(wordTemplateOut.toByteArray())).render(data).write(wordOutputStream);\n        }catch (Exception e){\n            log.error(e.getMessage(), e);\n            throw new JeecgBootException(\"生成word文档失败，请检查模版和数据是否正确\");\n        }\n\n    }\n\n    /**\n     * 将系统变量合并到数据中\n     *\n     * @param data\n     * @author chenrui\n     * @date 2025/7/3 17:43\n     */\n    private static void mergeSystemVarsToData(Map<String, Object> data) {\n        for (String key : SYSTEM_KEYS) {\n            if (!data.containsKey(key)) {\n                String value = JwtUtil.getUserSystemData(key, null);\n                if (value != null) {\n                    data.put(key, value);\n                }","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/jeecgboot/JeecgBoot/blob/96fb33f5ec68516da0b0147da06b2eb0419e063a/jeecg-boot/jeecg-boot-module/jeecg-boot-module-airag/src/main/java/org/jeecg/modules/airag/wordtpl/service/impl/AigcWordTemplateServiceImpl.java#L45-L81","documentation":"AigcWordTemplateServiceImpl.generateWordFromTpl() compiles a freshly-built template with poi-tl (XWPFTemplate.compile(...).render(data).write(...)). Any render or write exception is thrown as a JeecgBootException with a GENERIC message -- the cause is logged separately but not appended to the thrown text, so you must read the logs to learn why.","triggerScenarios":"The data map is missing a placeholder the template references; a placeholder tag is malformed; poi-tl config/grammar is unsupported; system variables (mergeSystemVarsToData) cannot resolve; the compiled template is structurally invalid.","commonSituations":"Template defines {{name}} but data has no 'name' key; loop/nested tags misformatted; poi-tl version doesn't support a used policy; the user context (JwtUtil.getUserSystemData) is missing in a background job.","solutions":["Read the 'log.error(e.getMessage(), e)' line -- the thrown message carries no detail.","Diff the data map keys against the template placeholders.","Render locally with XWPFTemplate.compile(...).render(data) using the same template bytes to reproduce.","Confirm the poi-tl version supports the tag policy used.","Ensure a LoginUser context exists so mergeSystemVarsToData can resolve system vars."],"exampleFix":"// before\ncatch (Exception e){\n    log.error(e.getMessage(), e);\n    throw new JeecgBootException(\"生成word文档失败，请检查模版和数据是否正确\");\n}\n// after - include the cause so callers can self-diagnose\nthrow new JeecgBootException(\"生成word文档失败，请检查模版和数据是否正确: \" + e.getMessage(), e);","handlingStrategy":"validation","validationCode":"// pre-flight: ensure every placeholder referenced by the template has a data key\nMap<String,Object> data = wordTplGenDTO.getData();\nif (data == null) { data = new HashMap<>(); }\nmergeSystemVarsToData(data);","typeGuard":null,"tryCatchPattern":"try {\n    XWPFTemplate.compile(new ByteArrayInputStream(wordTemplateOut.toByteArray())).render(data).write(wordOutputStream);\n} catch (Exception e) {\n    log.error(\"poi-tl 渲染失败, data keys={}, cause={}\", data.keySet(), e.getMessage(), e);\n    throw new JeecgBootException(\"生成word文档失败，请检查模版和数据是否正确: \" + e.getMessage(), e);\n}","preventionTips":["Document the required placeholders for each template.","Run a render in a test with a known-good data map before shipping a template.","Include the cause message in the thrown exception so callers can self-diagnose."],"tags":["word","poi-tl","template","render","configuration"],"backgroundTag":null,"analyzedSha":"96fb33f5ec68516da0b0147da06b2eb0419e063a","analyzedAt":"2026-08-14T00:04:16.786Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}