docs: Mattermost edit_post 403 troubleshooting for Hyperflux Gateway guide

[zlcnju]

Summary

• 根因:bot 角色缺 Edit Own Posts (edit_post) 权限时,worker 的 update_post(编辑占位帖回写答案)返回 403 api.context.permissions.app_error,回复一直卡在 "Thinking, please wait…"。原 bug 已由用户改 Mattermost 权限解决,本次只补文档沉淀。
• 改了 docs/en/solutions/How_to_Deploy_Hyperflux_Gateway_for_Mattermost.md:
  • Environment 加一条前提:bot 角色需 edit_post 权限;
  • Troubleshoot common issues 加一条 "stays on Thinking…" 排障项(现象 / 日志特征 / 根因 / System Scheme → Posts 修复步骤 / 验证)。

Tests

• 文档改动,无代码。本地校验:code fence 平衡(56 个 ``` 偶数);Markdown 列表/链接渲染正常。
• 未覆盖部分的安全论证:纯 .md 单文件新增段落,未触碰任何代码路径与其它文档;新增内容与既有 Troubleshoot 条目同结构,无破坏面。

Auto-resolve metadata

• Triggered from: support-triage auto-resolve daily run 2026-06-04
• Source issue: aml/smart-doc#4 (GitLab hub) — 项目 owner 在 issue 上明确要求"修改文档即可,文档修改也要提 PR 到 alauda/knowledge"
• Sibling MR(gateway 内部文档同款改动): https://gitlab-ce.alauda.cn/aml/hyperflux/hyperflux-gateway/-/merge_requests/7
• Resume this session: claude --resume c8c0f016

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added environment prerequisite: Mattermost bot role must have Edit Own Posts permission so streaming replies can edit a placeholder post.
  • Expanded troubleshooting with a new "Thinking, please wait…" section showing example request/response flow, diagnosing missing edit permission as a common cause, and step-by-step guidance to grant and verify post-edit permissions (including edit time-limit advice).

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 903360c1-e008-4d23-b1e0-faa57b1589cb

📥 Commits

Reviewing files that changed from the base of the PR and between 6174d70 and ff50df5.

📒 Files selected for processing (1)

• docs/en/solutions/How_to_Deploy_Hyperflux_Gateway_for_Mattermost.md

✅ Files skipped from review due to trivial changes (1)

• docs/en/solutions/How_to_Deploy_Hyperflux_Gateway_for_Mattermost.md

---

Walkthrough

Documentation adds a prerequisite that the Mattermost bot role must have Edit Own Posts (edit_post) and a troubleshooting subsection explaining the “Thinking, please wait…” failure when placeholder edits return 403 Forbidden, with steps to grant and verify post-edit permissions.

Changes

Mattermost Deployment Documentation

Layer / File(s)	Summary
Permission prerequisite and troubleshooting guidance docs/en/solutions/How_to_Deploy_Hyperflux_Gateway_for_Mattermost.md	Added a prerequisite requiring the bot edit_post permission. Expanded troubleshooting with an example where placeholder POST succeeds but the PUT /api/v4/posts/{post_id} edit returns 403 Forbidden, identifies missing edit_post as the cause, and provides step-by-step guidance to grant post-edit permissions, adjust edit time limits, and verify by manual edit retries.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

A rabbit hops through docs so bright,
Adds one small flag to make replies light—
No more messages stuck in wait,
Edit permission clears their state. 🐰✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding Mattermost edit_post 403 troubleshooting documentation to the Hyperflux Gateway deployment guide.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch auto-resolve/issue-4-mattermost-edit-post-faq

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/en/solutions/How_to_Deploy_Hyperflux_Gateway_for_Mattermost.md`:
- Around line 310-312: Update the documentation bullets to clarify that
Mattermost's permission key edit_post corresponds to editing your own posts by
changing the line to "Edit Posts (Own) (edit_post) — required so the worker can
edit its own placeholder post," and keep the separate bullet for "Edit Others'
Posts (edit_others_posts)" only for setups where the placeholder author differs
from the editor; ensure both permission keys edit_post and edit_others_posts are
shown exactly as identifiers in the text.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 0cb345f3-3959-4b05-ad78-5b633488c5a2

📥 Commits

Reviewing files that changed from the base of the PR and between b952bf6 and 6174d70.

📒 Files selected for processing (1)

• docs/en/solutions/How_to_Deploy_Hyperflux_Gateway_for_Mattermost.md