docs: 更新 API 文档和 AI 能力集成页面

2026-01-20 17:53:22 +08:00
parent f6195ee17a
commit 4bb9333b37
28 changed files with 1393 additions and 1305 deletions
@@ -1,85 +1,155 @@
 <!--
-  ApiConceptDemo.vue
-  目标：互动演示 API 必须写清楚的 4 个要点
+  ApiConceptDemo.vue - 互动点餐版
+  目标：通过"点菜"的过程演示 API 的三个核心要素
 -->
 <template>
  <div class="demo">
-    <div class="title">📋 API 必须写清楚的 4 件事</div>
-    <p class="subtitle">点每一项看看是什么意思</p>
-
-    <div class="cards">
-      <div
-        v-for="item in items"
-        :key="item.id"
-        :class="['card', { active: selectedId === item.id }]"
-        @click="select(item.id)"
-      >
-        <div class="card-icon">{{ item.icon }}</div>
-        <div class="card-title">{{ item.title }}</div>
-        <div class="card-hint">{{ item.hint }}</div>
-      </div>
+    <div class="header">
+      <span class="icon">🍳</span>
+      <span class="title">互动演示：向 AI 厨房点菜</span>
    </div>

-    <div class="detail" v-if="selected">
-      <div class="detail-header">
-        <span class="detail-icon">{{ selected.icon }}</span>
-        <span class="detail-title">{{ selected.title }}</span>
+    <div class="stepper">
+      <!-- Step 1: Endpoint -->
+      <div class="step-group">
+        <div class="step-label">1. 跟谁说？(Endpoint)</div>
+        <select v-model="endpoint" class="control">
+          <option value="/kitchen/chef">👨‍🍳 主厨 (/kitchen/chef)</option>
+          <option value="/kitchen/bar">🍸 调酒师 (/kitchen/bar)</option>
+        </select>
      </div>
-      <div class="detail-body">
-        <div class="detail-desc">{{ selected.desc }}</div>
-        <div class="detail-example">
-          <strong>例子：</strong>
-          <code>{{ selected.example }}</code>
+
+      <!-- Step 2: Method -->
+      <div class="step-group">
+        <div class="step-label">2. 怎么说？(Method)</div>
+        <div class="toggle-group">
+          <button 
+            :class="['toggle-btn', { active: method === 'GET' }]"
+            @click="method = 'GET'"
+          >
+            GET (看看有什么)
+          </button>
+          <button 
+            :class="['toggle-btn', { active: method === 'POST' }]"
+            @click="method = 'POST'"
+          >
+            POST (我要下单)
+          </button>
        </div>
      </div>
+
+      <!-- Step 3: Params -->
+      <div class="step-group" v-if="method === 'POST'">
+        <div class="step-label">3. 点什么？(Body)</div>
+        <div class="params-editor">
+          { "food": 
+          <select v-model="food" class="inline-select">
+            <option value="steak">🥩 牛排</option>
+            <option value="pasta">🍝 意面</option>
+            <option value="salad">🥗 沙拉</option>
+          </select>
+          }
+        </div>
+      </div>
+      <div class="step-group" v-else>
+        <div class="step-label">3. 查什么？(Params)</div>
+        <div class="params-editor">
+          ?type=
+          <select v-model="menuType" class="inline-select">
+            <option value="today">📅 今日特供</option>
+            <option value="all">📜 全部菜单</option>
+          </select>
+        </div>
+      </div>
+
+      <!-- Action -->
+      <button class="send-btn" @click="sendRequest" :disabled="loading">
+        {{ loading ? '🍳 正在做...' : '🚀 发送请求' }}
+      </button>
+    </div>
+
+    <!-- Result -->
+    <div class="result-box" v-if="response">
+      <div class="result-header">
+        <span class="badge" :class="response.status === 200 ? 'success' : 'error'">
+          {{ response.status }} {{ response.statusText }}
+        </span>
+      </div>
+      <div class="result-content">
+        {{ response.data }}
+      </div>
+      <div class="result-explanation">
+        💡 <strong>解释：</strong> {{ response.explanation }}
+      </div>
    </div>
  </div>
 </template>

 <script setup>
-import { ref, computed } from 'vue'
+import { ref, watch } from 'vue'

-const selectedId = ref('entry')
+const endpoint = ref('/kitchen/chef')
+const method = ref('GET')
+const food = ref('steak')
+const menuType = ref('today')
+const loading = ref(false)
+const response = ref(null)

-const items = [
-  {
-    id: 'entry',
-    icon: '📍',
-    title: '入口在哪',
-    hint: '网址 / 函数名',
-    desc: '你要调用的"按钮"在哪里。是 HTTP 网址，还是代码里的函数名？',
-    example: 'GET /api/users/{id}'
-  },
-  {
-    id: 'params',
-    icon: '📝',
-    title: '要填什么',
-    hint: '需要哪些参数',
-    desc: '调用这个 API 时，你需要提供哪些信息？哪些是必填的，哪些是可选的？',
-    example: 'id（必填）、page（可选）'
-  },
-  {
-    id: 'response',
-    icon: '✅',
-    title: '会得到什么',
-    hint: '返回什么数据',
-    desc: '成功的时候，API 会返回什么数据？有哪些字段，分别代表什么意思？',
-    example: '{ id, name, email }'
-  },
-  {
-    id: 'error',
-    icon: '⚠️',
-    title: '失败怎么说',
-    hint: '错误提示',
-    desc: '调用失败的时候会返回什么错误信息？你应该怎么处理这些错误？',
-    example: '401 没权限、404 找不到、429 太频繁'
-  }
-]
+// Reset response when inputs change
+watch([endpoint, method, food, menuType], () => {
+  response.value = null
+})

-const selected = computed(() => items.find(i => i.id === selectedId.value))
+function sendRequest() {
+  loading.value = true
+  response.value = null

-function select(id) {
-  selectedId.value = id
+  setTimeout(() => {
+    loading.value = false
+    
+    // Logic for different combinations
+    if (endpoint.value === '/kitchen/bar') {
+      if (method.value === 'GET') {
+        response.value = {
+          status: 200,
+          statusText: 'OK',
+          data: { menu: ['Mojito', 'Martini', 'Beer'] },
+          explanation: '你问调酒师有哪些酒，他给了你酒单。'
+        }
+      } else {
+        response.value = {
+          status: 400,
+          statusText: 'Bad Request',
+          data: { error: "Bar only serves drinks, not food!" },
+          explanation: '你试图向调酒师点菜（牛排/意面），他拒绝了你。你应该去 /kitchen/chef 点菜，或者只点酒。'
+        }
+      }
+      return
+    }
+
+    // Chef logic
+    if (method.value === 'GET') {
+      response.value = {
+        status: 200,
+        statusText: 'OK',
+        data: { specials: ['Spicy Chicken', 'Tofu Soup'] },
+        explanation: '你问主厨今天有什么特供，他告诉了你。'
+      }
+    } else {
+      // POST to Chef
+      const foodMap = {
+        steak: '🥩 滋滋作响的牛排',
+        pasta: '🍝 香气扑鼻的意面',
+        salad: '🥗 新鲜健康的沙拉'
+      }
+      response.value = {
+        status: 200,
+        statusText: 'Created',
+        data: { dish: foodMap[food.value], message: "Enjoy your meal!" },
+        explanation: `你向主厨下了单 (${food.value})，主厨为你做好了菜。`
+      }
+    }
+  }, 600)
 }
 </script>

@@ -87,136 +157,148 @@ function select(id) {
 .demo {
  border: 1px solid var(--vp-c-divider);
  border-radius: 12px;
-  padding: 20px;
  background: var(--vp-c-bg-soft);
-  margin: 16px 0;
+  margin: 24px 0;
+  overflow: hidden;
 }

-.title {
-  font-size: 18px;
-  font-weight: bold;
-  margin-bottom: 8px;
-  color: var(--vp-c-text-1);
-}
-
-.subtitle {
-  color: var(--vp-c-text-2);
-  margin-bottom: 20px;
-}
-
-.cards {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
-  gap: 12px;
-  margin-bottom: 20px;
-}
-
-.card {
+.header {
+  padding: 12px 20px;
  background: var(--vp-c-bg);
-  border: 2px solid var(--vp-c-divider);
-  border-radius: 12px;
-  padding: 16px;
+  border-bottom: 1px solid var(--vp-c-divider);
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  font-weight: 600;
+}
+
+.stepper {
+  padding: 20px;
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+
+.step-group {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.step-label {
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--vp-c-text-2);
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+}
+
+.control, .inline-select {
+  padding: 8px 12px;
+  border-radius: 6px;
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
+  font-size: 14px;
+  cursor: pointer;
+}
+
+.toggle-group {
+  display: flex;
+  background: var(--vp-c-divider);
+  padding: 2px;
+  border-radius: 8px;
+  width: fit-content;
+}
+
+.toggle-btn {
+  padding: 6px 16px;
+  border-radius: 6px;
+  border: none;
+  background: transparent;
+  color: var(--vp-c-text-2);
+  font-size: 14px;
  cursor: pointer;
  transition: all 0.2s;
 }

-.card:hover {
-  border-color: var(--vp-c-brand-1);
-  transform: translateY(-2px);
-}
-
-.card.active {
-  border-color: var(--vp-c-brand-1);
-  background: #f0f9ff;
-  box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);
-}
-
-.card-icon {
-  font-size: 32px;
-  margin-bottom: 8px;
-}
-
-.card-title {
-  font-weight: bold;
-  font-size: 16px;
-  margin-bottom: 4px;
-  color: var(--vp-c-text-1);
-}
-
-.card-hint {
-  font-size: 13px;
-  color: var(--vp-c-text-2);
-}
-
-.detail {
+.toggle-btn.active {
  background: var(--vp-c-bg);
-  border: 2px solid var(--vp-c-brand-1);
-  border-radius: 12px;
-  padding: 20px;
-  animation: fadeIn 0.3s ease;
+  color: var(--vp-c-brand-1);
+  font-weight: 600;
+  box-shadow: 0 1px 3px rgba(0,0,0,0.1);
 }

-@keyframes fadeIn {
-  from {
-    opacity: 0;
-    transform: translateY(10px);
-  }
-  to {
-    opacity: 1;
-    transform: translateY(0);
-  }
-}
-
-.detail-header {
-  display: flex;
-  align-items: center;
-  gap: 12px;
-  margin-bottom: 16px;
-}
-
-.detail-icon {
-  font-size: 28px;
-}
-
-.detail-title {
-  font-size: 20px;
-  font-weight: bold;
-  color: var(--vp-c-text-1);
-}
-
-.detail-body {
-  line-height: 1.8;
-}
-
-.detail-desc {
-  font-size: 15px;
-  color: var(--vp-c-text-1);
-  margin-bottom: 16px;
-}
-
-.detail-example {
-  background: var(--vp-c-bg-soft);
-  padding: 16px;
-  border-radius: 8px;
-  border-left: 4px solid var(--vp-c-brand-1);
-}
-
-.detail-example strong {
-  display: block;
-  margin-bottom: 8px;
-  font-size: 14px;
-  color: var(--vp-c-text-1);
-}
-
-.detail-example code {
-  display: block;
-  background: #1e293b;
-  color: #e2e8f0;
+.params-editor {
+  font-family: monospace;
+  background: var(--vp-c-bg);
  padding: 12px;
  border-radius: 6px;
-  font-family: 'Monaco', 'Menlo', monospace;
-  font-size: 13px;
-  line-height: 1.6;
+  border: 1px solid var(--vp-c-divider);
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.send-btn {
+  margin-top: 8px;
+  background: var(--vp-c-brand-1);
+  color: white;
+  border: none;
+  padding: 12px;
+  border-radius: 8px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: opacity 0.2s;
+}
+
+.send-btn:disabled {
+  opacity: 0.7;
+  cursor: not-allowed;
+}
+
+.result-box {
+  margin: 0 20px 20px;
+  background: #1e293b;
+  border-radius: 8px;
+  overflow: hidden;
+  color: #e2e8f0;
+  font-family: monospace;
+  animation: slideDown 0.3s ease;
+}
+
+.result-header {
+  padding: 8px 12px;
+  background: rgba(0,0,0,0.3);
+  display: flex;
+  align-items: center;
+}
+
+.badge {
+  font-size: 12px;
+  padding: 2px 6px;
+  border-radius: 4px;
+  font-weight: bold;
+}
+
+.badge.success { background: #22c55e; color: #fff; }
+.badge.error { background: #ef4444; color: #fff; }
+
+.result-content {
+  padding: 16px;
  white-space: pre-wrap;
 }
+
+.result-explanation {
+  padding: 12px;
+  background: #334155;
+  font-family: var(--vp-font-family-base);
+  font-size: 13px;
+  border-top: 1px solid rgba(255,255,255,0.1);
+}
+
+@keyframes slideDown {
+  from { opacity: 0; transform: translateY(-10px); }
+  to { opacity: 1; transform: translateY(0); }
+}
 </style>