docs(product): add feedback documentation - #3406
Conversation
![fennoai[bot]](https://avatars.githubusercontent.com/in/1924301?s=60&v=4){kind=small}
There was a problem hiding this comment.
Review Summary
Docs-only PR adding a product design spec for the Feedback feature in English (docs/product/feedback.md) and Chinese (docs/product/feedback.zh.md). The two versions are well-mirrored — status table, transitions, terminal states, Submission ID semantics, permissions, and Reply/Notification atomicity all match. Findings below are documentation-quality and design-completeness items; none blocks merge. Inline comments cover the concrete line-level items.
Design-completeness items (no single reliable diff line — noted here):
- Context has no size bounds (
feedback.md:51-62,.zh.md:51-62):Title(100) andDescription(2000) are capped, butContext— which includes the Project Snapshot, a page screenshot, resource structure, and the latest 50 runtime outputs (each line uncapped) — has no stated total/per-field size limit or truncation behavior. Worth specifying, as it drives storage, request payload, and detail-view load cost. - Project Snapshot: embedded vs. referenced is unspecified (
feedback.md:61,94-96,.zh.md): if snapshots are stored inline in the Feedback record, the Feedback list (View Feedback lists) risks pulling large blobs. Recommend the design state that list views load only lightweight metadata and Context/Snapshot are fetched lazily on the detail view. - Retention / deletion policy for diagnostic Context (
feedback.md:51-68,.zh.md): access is scoped (submitter +feedbackAdmin), but there is no retention period, expiry, or purge mechanism for the sensitive diagnostic payload, including after a Feedback reaches a terminal state. - List/detail ownership check not stated (
feedback.md:68,.zh.md:68): the access rule ("only the submitting user andfeedbackAdmin") is stated for Context specifically. Recommend making the ownership check on the Feedback list/detail read paths explicit to avoid an IDOR-style gap at implementation time. - Submission ID scoping (
feedback.md:86-92,.zh.md): the idempotency/conflict rules are clear, but the doc does not state that Submission IDs are namespaced to the authenticated user. Worth specifying so "same Submission ID + different content = conflict" cannot collide across users.
There was a problem hiding this comment.
Review: Feedback design docs
Docs-only PR adding the Feedback product spec in English (docs/product/feedback.md) and Chinese (docs/product/feedback.zh.md). The two files mirror each other well and the concurrency/idempotency, Context capture-time, and Submission ID rules are precise and consistent. A few spec-consistency and translation issues are worth resolving before implementation; inline comments cover the concrete ones.
The most important is the artifact authorization model (see inline on the Permissions section): artifacts are described as protected by the "same ownership check," but the primary reader of the Project Snapshot/screenshot is the feedbackAdmin — a role, not the owner — and the Chinese text makes the contradiction explicit ("用户或管理员...归属校验"). Defining artifact authorization as "same authorization as the parent Feedback (owner OR feedbackAdmin)" would resolve it.
No blocking issues.
|
|
||
| Reply 是管理员针对 Feedback 给出的文字回复。 | ||
|
|
||
| ### 站内通知 In-Product Notification |
There was a problem hiding this comment.
虽然是为了 feedback 功能引入的，但站内信是个相对单独的功能模块（就像 Copilot 与 Tutorial 的关系），需要独立地说明它的定位、定义的业务概念等，甚至拆个单独的文档说都可以；这个说明应该是与 feedback 功能无关的
至于 feedback 这边，介绍在 feedback 流程中的什么时候会调用/触发站内信的什么功能就好
| 用户同意分享时，系统在确认提交时采集 Context。提交过程中显示进行中状态，避免用户重复操作。服务端确认 | ||
| Feedback 创建成功后，界面显示完成状态并关闭表单；提交失败时保留用户输入并允许重试。 | ||
|
|
||
| 同一次提交使用稳定的 Submission ID。Submission ID 以提交用户为作用域，不同用户使用相同值时视为不同提交： |
There was a problem hiding this comment.
为啥会有“Submission ID”的概念，它解决的是什么问题？
There was a problem hiding this comment.
Submission ID 是用于标识同一次 Feedback 创建请求、保证幂等处理
There was a problem hiding this comment.
明白了，这个是实现上的考虑，不是用户会感知到的概念吧？
不过感觉这个机制意义不大，按我们已有的实现习惯，新增业务数据的接口都没有做这个设计，以提交 feedback 为例，如果前端交互实现是合理的话，应该也几乎不会出现重复提交的情况？
|
|
||
| Copilot 生成的草稿不替代 Feedback 的 Context。用户确认提交时，Feedback 按上述规则采集 Context。 | ||
|
|
||
| Copilot 暂时不可用或额度耗尽时，提示中可以提供直接打开 Feedback 表单的操作。用户也始终可以从头像菜单进入 |
There was a problem hiding this comment.
Copilot 暂时不可用或额度耗尽时，提示中可以提供直接打开 Feedback 表单的操作。
这个我们讨论过，当提供这个操作入口的时候，我们针对的场景应该是用户想反馈“不可用或额度不够”这件事情（记为 A），所以跟“Copilot 协助用户去解决或反馈什么别的问题”（记为 B）是不一样的，以及跟 A 类似的还有像生成素材的时候额度不足（记为 C），也可以有反馈。把 A 和 C 放在一起说要比把 A 和 B 放在一起说更合适
|
|
||
| ### 查看 Project Snapshot | ||
|
|
||
| 管理员从 Feedback 详情选择“打开项目快照”。客户端从 Kodo 获取引用的 JSON，将其中的 `files` 集合交给编辑器的 |
There was a problem hiding this comment.
这里的“编辑器的本地加载能力”可能也是要说明一下的，它有点像是 Tutorial 需求中的 Effect-free mode，都是对现有的功能模块（编辑器）进行扩展
2 participants
What
Add the Chinese and English Feedback product documents for #1789.
The documents define the Feedback submission content as Title, Description, and Context. Context covers diagnostic details, the Project Snapshot, and the page screenshot captured at submission time. They also define the Feedback-details action and
feedbackAdminpermission for opening the Project Snapshot in the editor, while keepingFileCollectionimport and storage mechanics outside the Feedback document.The remaining sections document submission idempotency, Copilot assistance, administrator permissions, status transitions, repeated processing, reply and notification failure handling, and text-based administrator replies.
Why
Feedback behavior was previously mixed with implementation-specific editor and storage details, which made the ownership boundary unclear and left the Context model and reply behavior inconsistent. This PR gives the Feedback feature its own product definition while preserving the administrator workflow for inspecting the submitted project state.
Verification
git diff --checkdocs/product/feedback.mdanddocs/product/feedback.zh.md.index.mdandindex.zh.mdare not changed.Refs #1789