Extract attachment text in bulk with the manage command

# Batch Extract Attachment Text Content Using the manage Command

Command: `extract_attachment_content`

## 1. Command Introduction

Populates searchable text content for existing historical attachments on the site, for use in attachment preview, site search, and AI knowledge base Q&A.

| Item | Description |
| --- | --- |
| Target | Sites that have been upgraded to the new version and contain historical attachments |
| Number of runs | Once is sufficient; already-processed attachments are skipped automatically |
| Execution location | MrDoc installation directory |
| Execution time | Off-peak hours |
| Service status | Keep running; no need to stop the service |
| Data safety | A database backup is recommended beforehand |

Constraints:

- Supported types for text extraction: pdf, doc, docx, xls, xlsx, pptx; other types are skipped.
- `.doc` depends on LibreOffice on the server (converted before reading): the Docker image includes it; source deployments must install it themselves,
  and specify the path to its executable in the `preview.libreoffice_path` setting in the `config.ini` configuration file (default `soffice`).
  If not installed, `.doc` will be extracted as empty; `.docx` is unaffected.
- Attachments on cloud storage (Qiniu, MinIO, etc.) are not processed.
- Overly long content is truncated at the limit; the complete content is subject to the original attachment.
- Already-processed attachments are not read again; add `--force` to re-read them.
- The AI index must be rebuilt before AI knowledge base Q&A will read the attachment content.
- Do not interrupt the process while the command is running.

## 2. Usage Syntax

```sh
python manage.py extract_attachment_content [参数]
```

Docker deployment (the container name is subject to what `docker ps` actually shows):

```sh
docker exec -it mrdoc python manage.py extract_attachment_content [参数]
```

## 3. Parameter Description

| Parameter | Description |
| --- | --- |
| No parameter | Process all attachments without content |
| `--dry-run` | Inventory only, no writes |
| `--limit N` | Process at most N attachments |
| `--force` | Re-read attachments that already have content |
| `--attachment-id 1,2,3` | Process only the specified attachments, comma-separated |
| `--doc-id N` | Process only attachments referenced by the specified document |
| `--reindex` | Rebuild the AI index of affected documents after completion |

## 4. Usage Examples

### Example 1: Inventory attachments to be processed

```sh
python manage.py extract_attachment_content --dry-run
```

Check the number of "attachments to be processed" in the output, and continue once it matches expectations.

### Example 2: Full completion (AI Q&A not enabled)

```sh
python manage.py extract_attachment_content
```

### Example 3: Full completion and AI index rebuild (AI Q&A enabled)

```sh
python manage.py extract_attachment_content --reindex
```

### Example 4: Targeted processing of attachments for a single document

```sh
python manage.py extract_attachment_content --doc-id 43090
```

### Output Reference

```
待处理附件：70 个
  提取成功：12 | attachment/2025/03/xxx.pdf | 长度=12345
  跳过(不支持格式)：13 | xxx.zip
  跳过(非本地存储/文件缺失)：14 | http://...

========== 提取完成 ==========
处理附件: 70
提取成功: 67
仍为空(提取失败): 1
跳过-不支持的格式: 2
跳过-非本地存储/文件缺失: 0
```

Additional output when using `--reindex`:

```
开始重建AI索引，受影响文档 5 篇
  索引重建成功：DocID=43090 | xxx
AI索引重建完成：成功=5 失败=0
```

| Output item | Action |
| --- | --- |
| Extraction succeeded | No action needed |
| Still empty (extraction failed) | No action needed (scanned PDFs, encrypted or corrupted files) |
| Skipped - unsupported format | No action needed |
| Skipped - non-local storage/file missing | Record the count and contact technical support to confirm the attachment storage configuration |

| Message | Meaning |
| --- | --- |
| No attachments to be processed | No attachments to be completed |
| AI index scope is an empty whitelist | The knowledge scope is not set in the backend "AI Configuration"; it must be set first |
| No published documents referencing these attachments found | No need to rebuild the index |

### Verification

1. Open a document containing attachments and check whether the attachment preview displays the body text;
2. Search for a passage of text within the attachment in site search and confirm it can be found;
3. On sites with AI Q&A enabled, search for the attachment content in AI Q&A and confirm it can be found.

### Reporting Anomalies

If the command errors out and is interrupted or produces output that cannot be interpreted, record the following information and contact technical support:

1. The complete error output;
2. The execution time and the parameters used;
3. The information of the last attachment being processed.