Wang1rrr opened a new issue, #4858: URL: https://github.com/apache/rocketmq-dashboard/issues/4858
### Before Creating the Doc Report - [x] I have searched the [open issues](https://github.com/apache/rocketmq-dashboard/issues) and found no similar issue. ### Which Documentation `docs/api-spec.md` §9 死信队列 Dead Letter Queue (lines 1510-1570 on `rocketmq-studio` @ `4c697f07`), and the §接口速查 index rows 51-52. ### What Is Wrong §9 documents two of the six endpoints `DLQController` actually exposes. `server/src/main/java/org/apache/rocketmq/studio/instance/dlq/DLQController.java` declares: | endpoint | source | documented? | | --- | --- | --- | | `GET /api/dlq` | `:62` | yes - §9.1 | | `POST /api/dlq/resend` | `:70` | yes - §9.2 | | `POST /api/dlq/resend-selected` | `:77` | **no** | | `GET /api/dlq/{groupName}/messages` | `:85` | **no** | | `GET /api/dlq/export-excel` | `:98` | **no** | | `GET /api/dlq/export` | `:117` | **no** | The four missing ones are not internal: they are what the console's DLQ drawer calls (`web/src/api/message.ts` - `listDLQMessages` `:274`, `resendDLQSelected` `:289`, `exportDLQMessages` `:229`, `exportDLQExcel` `:299`), so an integrator reading the spec cannot reproduce the page and has to reverse-engineer the TypeScript. Behaviour that is only discoverable from source today: - **The two exports do not use the `Result` envelope.** They return a raw `application/json` array / an `.xlsx` byte stream with a `Content-Disposition: attachment` header, unlike every other endpoint in the document. - **Scan completeness travels in response headers**, not in the body: `X-DLQ-Export-Truncated`, `X-DLQ-Export-FailedQueues`, `X-DLQ-Export-Limit` (`common/util/DlqExportHeaders.java`). They are readable cross-origin only because `common/config/CorsConfig.java:49` lists them in `Access-Control-Expose-Headers` - none of which is written down. - **`msgIds` on `/export-excel` must be a repeated parameter** (`msgIds=a&msgIds=b`). `web/src/api/message.ts:309` carries a comment explaining that axios's default bracketed form (`msgIds[]=a`) is not bound by Spring's `@RequestParam List<String>` and the request then *silently* exports the whole time window. That trap is exactly what an API spec should carry. - **Caps and defaults**: `maxCount` clamps to `min(maxCount, 5000)` and `<= 0` means `5000`; `/export-excel` always scans at `5000` and filters `msgIds` afterwards, so its `X-DLQ-Export-Limit` is always `5000`; `{groupName}/messages` paginates in memory over that same bounded scan, so `total` is the scan hit count, not the size of the DLQ topic. - **Default time window**: omitting `startTime`/`endTime` scans `[now - 1h, now]`; the pair must be supplied together and `endTime` must be strictly greater than `startTime` (`DLQService.validateTimeRange`). - **Vendor restriction**: all six endpoints return `501 DLQ operations are not supported for cloud instances` for Aliyun / Tencent instances (`DLQService.requireApacheInstance`), matching the fact that only `ApacheInstanceProvider` declares `InstanceCapability.DLQ_MANAGEMENT`. - **`DLQMessage` is undocumented**, including the `body` / `bodyBase64` pair (best-effort UTF-8 text plus the exact bytes, so binary dead letters survive an export) and `properties` / `propertiesTruncated`, whose caps come from `common/util/MessagePropertyDisplay.java` (64 entries, 1024 code points per value, broker system properties stripped). - **Excel sheet layout** (`instance/dlq/DLQMessageExcelRow.java`): sheet `DLQ`, columns `Message ID` / `Topic` / `Queue ID` / `Offset` / `Store Time` / `Reconsume Times` / `Keys` / `Body`, with `Store Time` formatted `yyyy-MM-dd HH:mm:ss` in the **server's** default zone. - **Filename handling** (`DLQController.attachmentDisposition` / `.sanitizeForFilename`): `"`, backslash, control characters and `0x7F` become `_`, and a non-ASCII group name is emitted as an RFC 5987 `filename*` parameter. The index compounds it: rows 51-52 are the only DLQ entries, so the four endpoints are invisible in the quick-reference table too. ### Suggested Change Add §9.3-§9.6 to `docs/api-spec.md` covering the four missing endpoints, in the format the rest of the document uses (`#### TypeName` for the response shape, a parameter table, and the non-`Result` response described explicitly): - §9.3 分页获取死信消息明细 - `GET /api/dlq/{groupName}/messages`, plus a `#### DLQMessage` type block - §9.4 重发选中的死信消息 - `POST /api/dlq/resend-selected`, including the `targetTopic` validation it shares with §9.2 - §9.5 导出死信消息（JSON） - `GET /api/dlq/export` - §9.6 导出死信消息（Excel） - `GET /api/dlq/export-excel`, including the repeated-`msgIds` requirement plus a shared block documenting the three `X-DLQ-Export-*` response headers and the filename sanitisation, a note block for the time-window / scan-cap / Apache-only rules that apply to all four, and index rows 99-102 appended to §接口速查 (the table already appends new endpoints at the end rather than renumbering - rows 90-98 are out of section order for that reason). Separately, and not part of this change: `.github/ISSUE_TEMPLATE/doc.yml` still tells contributors to "Base the branch on `master`", which is the same stale-trunk wording #4801 removed from `PULL_REQUEST_TEMPLATE.md`. ### Are You Willing to Submit a Pull Request? - [x] Yes, I am willing to submit a pull request. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
