Skip to content

Commit 73c2769

Browse files
author
Ma,Yutao
committed
Add the demand description document
1 parent a846d3a commit 73c2769

File tree

1 file changed

+52
-0
lines changed

1 file changed

+52
-0
lines changed

ISSUE_DESCRIPTION.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
## OpenMetadata 功能需求文档:词汇表术语的永久链接 (Stable URL)
2+
3+
### 1. 核心问题 (Problem Statement)
4+
5+
当前 OpenMetadata 词汇表术语 (Glossary Term) 的 URL 严重依赖其 FQN (完全限定名称)。这导致了三个主要痛点:
6+
7+
* **链接稳定性差:** 当术语的`name`或其在词汇表中的**层级结构**发生变更时,FQN 会随之改变。这导致所有从外部系统(如 Confluence, Google Docs, Word, Notion 等)引用的 URL 全部失效,破坏了知识库的链接完整性。
8+
* **国际化支持不佳:** 对于使用非拉丁语系(如俄语/西里尔字母)的用户,术语的`name`在 URL 中会被编码为不可读的字符串 (例如 `%D0%B3%D0%BB...`),严重影响了 URL 的可读性和可用性。
9+
* **用户体验混乱:** 在创建术语时,用户普遍不理解为何需要同时填写 `name``displayName` 两个字段,尤其是在两者内容几乎重复的情况下,这增加了不必要的操作摩擦。
10+
11+
### 2. 核心需求 (Core Feature Request)
12+
13+
为了解决链接失效问题,我们必须引入一种独立于 FQN 的、**永久稳定**的链接机制。
14+
15+
核心需求是:**词汇表术语的 URL 必须支持通过其唯一的 ID (UUID) 进行解析。**
16+
17+
### 3. 具体功能点 (Acceptance Criteria)
18+
19+
为实现此核心需求,需要满足以下功能点:
20+
21+
1. **路由逻辑 (Routing):**
22+
* 系统路由必须支持解析格式为 `https://[host-name]/glossary-term/[UUID]` 的 URL。
23+
2. **版本解析 (Version Resolution):**
24+
* 当用户访问一个仅包含 UUID 的词汇表 URL 时,系统必须**自动解析并重定向到该术语的“最新版本” (Latest Version) 的概览页面**
25+
* 这解决了当前使用“特定版本 URL” (`.../versions/0.5`) 作为变通方案时,链接会过时的问题。
26+
3. **UI 界面增强 (UI Enhancement):**
27+
* 在词汇表术语的 UI 界面上,必须提供一个清晰的“复制 URL”功能。
28+
* 点击此按钮后,应允许用户至少选择“按 ID 复制 URL”(获取新的稳定链接),也可以保留“按 FQN 复制 URL”(当前行为)。
29+
30+
### 4. 相关讨论与备选方案 (Related Issues & Alternatives)
31+
32+
在相关的讨论中,还提出了两个旨在解决“URL 不可读”和“`name`/`displayName` 混淆”问题的补充方案:
33+
34+
* **方案 1: 自动生成 `name` (音译)**
35+
* **描述:** 用户在表单中只填写 `displayName`。系统通过音译(例如使用 `slugify` 库将西里尔字母转为拉丁字母)自动生成一个 URL 友好且唯一的 `name`
36+
* **优点:** 简化用户操作;生成的 URL 可读性强;不破坏现有的 FQN 路由逻辑。
37+
* **缺点:** 需要引入额外的转写库;可能存在命名冲突(需要处理)。
38+
* **方案 2: 在 URL 中(完全)使用 `id` 替代 `name`**
39+
* **描述:** 在 UI 表单中移除 `name` 字段,只保留 `displayName`。URL 结构完全切换为 `.../glossary/<UUID>`
40+
* **优点:** 链接绝对稳定;UI 极致简化;无命名冲突。
41+
* **缺点:** 需要在整个项目中进行重大更改;URL 丧失了可读性;无法从 URL 中直观看出术语的层级结构。
42+
43+
### 5. 总结建议 (Summary of Feedback)
44+
45+
所有讨论均指向一个明确的共识:**启用 ID 作为 URL 的一部分以确保链接的永久稳定性是必须的**,这对依赖外部文档引用的用户至关重要。
46+
47+
同时,“自动从 `displayName` 生成 `name`”(方案 1)的提议也获得了支持,它可以作为解决 UI 混淆和非拉丁字符 URL 可读性问题的补充优化。
48+
49+
**建议的实施路径:**
50+
优先实现**核心需求 (第 2、3 点)**,解决链接失效的痛点。然后,将**方案 1 (自动生成 `name`)** 作为一个独立的改进点进行评估,以优化新术语的创建体验和 URL 可读性。
51+
52+
---

0 commit comments

Comments
 (0)