From a8b2160ac18331079f9b4a4eb8b1f047f3e947e5 Mon Sep 17 00:00:00 2001
From: jhy <184825448@qq.com>
Date: Thu, 15 Oct 2026 20:07:26 +0800
Subject: [PATCH] docs: define frontend interaction design

---
 docs/FRONTEND_INTERACTION_DESIGN.md | 36 +++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)
 create mode 100644 docs/FRONTEND_INTERACTION_DESIGN.md

diff --git a/docs/FRONTEND_INTERACTION_DESIGN.md b/docs/FRONTEND_INTERACTION_DESIGN.md
new file mode 100644
index 0000000..e97d577
--- /dev/null
+++ b/docs/FRONTEND_INTERACTION_DESIGN.md
@@ -0,0 +1,36 @@
+# 前端页面与功能设计（阶段一）
+
+## 设计目标
+
+前端不是展示虚构文旅结论的门户，而是让团队能看清资料从来源登记、文档采集到知识审核的状态。所有列表均以接口返回为准；接口不可用时展示明确的连接状态，不使用模拟数据兜底。
+
+## 页面结构
+
+| 页面 | 已实现 | 下一步功能 | 验收标准 |
+|---|---|---|---|
+| 智能问答 | 输入、会话、来源链接、请求中与不可用提示 | 检索命中片段、追问、会话清空 | 每条回答显示后端状态和可打开来源 |
+| 知识库管理 | 新建条目、搜索、状态统计、来源跳转 | 审核抽屉、编辑、版本冲突提示、历史记录 | 通过审核前必须有来源网址与采集时间 |
+| 来源与更新 | 登记来源、检索来源、来源状态说明 | 文档列表、关联创建、编辑/软删除、历史记录 | 不自动抓取；来源登记不等同于事实核验 |
+| 实验评估 | 指标边界与对照方案说明 | 问题集、人工评分、结果导出 | 不展示未经真实实验产生的数值 |
+
+## 核心操作链路
+
+1. 资料负责人登记来源：填写名称、网址和可靠性备注。
+2. 采集文档：必须选定一个来源，记录正文、分类和真实采集时间。
+3. 前端创建知识条目：关联文档或填写可访问的来源网址，默认状态为 `pending`。
+4. 审核人核验：填写审核说明；仅在来源网址和采集时间齐全时可标为 `verified`。
+5. 检索阶段只使用已核验内容；问答页展示来源链接与“原型阶段”提示。
+
+## 交互与状态规范
+
+- 提交按钮在请求期间禁用，完成后刷新对应列表。
+- 接口错误显示后端返回的业务信息；网络错误提示检查 FastAPI 和 PostgreSQL。
+- 删除采用后端软删除；前端须在删除前显示关联文档/知识条目可能阻止删除的说明。
+- 并发修改以接口 `version` 为准；返回 409 时提示刷新列表后重试，禁止静默覆盖。
+- 移动端优先展示表格的标题、状态和主要动作，其他字段通过横向滚动查看。
+
+## 前端与后端边界
+
+- 前端不决定资料真实性、不生成审核结论，也不伪造统计结果。
+- 前端仅调用 `/api/health`、`/api/chat`、`/api/knowledge`、`/api/sources` 和后续 `/api/documents`；鉴权接入后统一由 API 层处理。
+- 网页抓取、Embedding、向量检索与定时更新属于后端后续阶段，当前页面只说明其规划状态。