2026-06-10 19:15:24 +08:00
|
|
|
# Output Contract
|
|
|
|
|
|
|
|
|
|
## Primary Files
|
|
|
|
|
|
|
|
|
|
Each rule generation task owns exactly one output folder:
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
output/rules-{task_id}/
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The folder should contain:
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
rules-{task_id}.xlsx
|
|
|
|
|
rules-{task_id}.md
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Task state remains under:
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
output/tasks/{task_id}.json
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## State Fields
|
|
|
|
|
|
|
|
|
|
Use these fields for task outputs:
|
|
|
|
|
|
|
|
|
|
- `output_dir`: task output directory.
|
|
|
|
|
- `output_file`: Excel file path, retained for compatibility.
|
|
|
|
|
- `markdown_file`: Markdown file path, retained for compatibility.
|
|
|
|
|
- `files.excel`: Excel file path.
|
|
|
|
|
- `files.markdown`: Markdown file path.
|
|
|
|
|
- `markdown_error`: Markdown write error string, or `null`.
|
|
|
|
|
|
|
|
|
|
## Error Handling
|
|
|
|
|
|
|
|
|
|
Excel is the primary generated artifact. If Excel writing succeeds but Markdown writing fails, keep the Excel file and record `markdown_error`.
|
|
|
|
|
|
|
|
|
|
Do not rerun `_write_excel([])` after a Markdown-only failure; that can overwrite a valid workbook.
|
|
|
|
|
|
|
|
|
|
## API Exposure
|
|
|
|
|
|
|
|
|
|
`POST /api/rules/generate` should return:
|
|
|
|
|
|
|
|
|
|
- `task_id`
|
|
|
|
|
- `status`
|
|
|
|
|
- `limit`
|
|
|
|
|
- `output_dir`
|
|
|
|
|
- `output_file`
|
|
|
|
|
- `markdown_file`
|
|
|
|
|
- `files`
|
|
|
|
|
- `started_at`
|
|
|
|
|
|
|
|
|
|
`GET /api/rules/status` returns the persisted state JSON.
|
