# 报告模板管理模块

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

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`，已存在则跳过）。

## 运行

```bash
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` | 健康检查 |

### 上传示例

```bash
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`。