report_generation/README.md

报告模板管理模块

上传一个文档，自动完成：

1. 远程解析：调用 http://192.168.4.194:8000/convert（表单字段 file + engine=auto）将文档转换为 Markdown。
2. 抽取目录：从 Markdown 中识别章节标题层级（目录）。
3. 生成声明：为每个目录（章节）生成一段"章节声明"（撰写指引），存入模板。
4. 脱敏入库：按标题拆分正文，对每个章节正文脱敏（去掉精确数字/金额/日期/百分比等），再按远程 MySQL report_section_references 表格式写入，得到可复用的模板化范文。

解析、目录抽取、正文拆分逻辑参考 eval_report/routers/template.py 与 routers/reference.py。

目录结构

config.py                     全局配置（DB / 解析服务 / LLM）
main.py                       FastAPI 入口
database/                     连接、ORM 模型、建表
  models.py                   report_templates / report_template_sections / report_section_references
schemas/template.py           接口出入参
services/
  file_parse_client.py        调用远程 /convert → Markdown
  section_extractor.py        目录抽取 + 正文按标题拆分（共用同一遍历）
  desensitize_service.py      章节正文脱敏（去精确数字等）
  declaration_service.py      为每个目录生成"声明"（LLM 可选 + 兜底模板）
  llm_client.py               OpenAI 兼容 Chat 客户端（可选）
routers/template.py           上传/列表/详情/删除

配置

复制 .env.example 为 .env 并修改：

• DATABASE_URL：远程 MySQL（章节内容入库目标）。
• FILE_PARSE_API_URL：远程文档解析服务（默认 http://192.168.4.194:8000/convert，文件字段 FILE_PARSE_FIELD_NAME=file，引擎 FILE_PARSE_ENGINE=auto）。
• LLM_*：可选。配置后用 LLM 生成更贴合的章节声明；留空则使用确定性兜底模板。

启动时会按需在远程库中创建本模块用到的三张表（DB_AUTO_CREATE_TABLES=true，已存在则跳过）。

运行

pip install -r requirements.txt
python main.py
# 或
uvicorn main:app --host 0.0.0.0 --port 8100

打开 http://localhost:8100/docs 查看接口文档。

主要接口

方法	路径	说明
POST	/templates/upload	上传文档，解析为模板（目录+声明）并将章节内容入库
GET	/templates	模板列表
GET	/templates/{id}	模板详情（含目录与各章节声明）
DELETE	/templates/{id}	删除模板
GET	/health	健康检查

上传示例

curl -X POST "http://localhost:8100/templates/upload" \
  -F "file=@/path/to/报告.docx"

返回包含：模板信息（每个目录的 sectionDeclaration 即声明）、入库章节数与各章节摘要。

日志

启动即初始化日志系统（log/logger.py），输出到控制台（强制 UTF-8，避免 Windows 中文乱码）并写入 logs/：

文件	内容
logs/app.log	全量日志（按大小轮转）
logs/error.log	WARNING 及以上
logs/upload.log	上传/解析/入库链路（routers.template、services.*）

• 每个 HTTP 请求会记录方法、路径、状态码、耗时，并在响应头返回 X-Request-ID。
• uvicorn 的 access/error 日志也统一汇入上述文件。
• 可在 .env 调整：LOG_LEVEL、LOG_DIR、LOG_TO_CONSOLE、LOG_MAX_BYTES、LOG_BACKUP_COUNT、LOG_HTTP_ACCESS。

数据落点

• report_templates：一条模板记录。
• report_template_sections：每个目录一条，section_prompt 字段存放该目录的声明。
• report_section_references：每个章节一条，存放该章节脱敏后的正文内容（与远程库现有格式一致）。

脱敏规则

services/desensitize_service.py：

• 阿拉伯数字串（含小数/千分位/全角）→ 占位符（默认 X）：总投资10.5亿元 → 总投资X亿元、85.3% → X%、2020年3月 → X年X月。
• 标题行（# 开头）整行保留，不动章节编号与标题。
• 行首枚举序号（1）、（2） 等）保留，仅脱敏正文数字。
• 表格分隔行保留；数据格数字默认脱敏（DESENSITIZE_MASK_TABLE_NUMBERS）。
• 中文数字（一二三…）默认保留（多为序数/层级）。
• 可在 .env 调整：DESENSITIZE_ENABLED、DESENSITIZE_PLACEHOLDER、DESENSITIZE_MASK_TABLE_NUMBERS。