pda-kit-mcp-server 2.0.1

package/spec-data/scan-input.md

@@ -0,0 +1,304 @@
+---
+id: scan-input
+name: ScanInput 扫描输入框
+category: molecule
+version: 3.1.0
+tokens:
+  layout: "block w-[456px] h-[60px] flex-shrink-0 my-2 px-4"
+  theme: "bg-grey-1 border border-grey-3 rounded-4dp"
+  focus-theme: "border-main-6"
+  success-theme: "bg-green-1 border-green-6"
+  error-theme: "bg-red-1 border-red-6"
+composes:
+  - icon: "icons/icons-sprite.svg#common_ic_scanning_o"
+triggers:
+  - PDA 物理扫描键（主要触发方式）
+  - 键盘 Enter（桌面端调试 Fallback）
+---
+
+# ScanInput 扫描输入框规范
+
+> **🧠 AI 绝对死线（MANDATORY，任何违反视为不合格代码）：**
+>
+> - ⛔ **严禁生成任何形式的 Web 端"屏幕点击扫描按钮"**。PDA 扫描由物理硬件触发，右侧不准与任何按钮/图标并列。
+> - ⛔ **严禁自作聪明给左侧图标添加 onclick 点击事件**，必须锁死 `cursor: default`。
+> - ⛔ **严禁使用任何 `transition` 属性或动画过渡**，状态切换（如 focus/success/error）必须秒级闪切。
+> - ⛔ **严禁使用大圆角**，必须锁死在 `rounded-4dp` (4px)。
+> - ⛔ **严禁手写 SVG `<path>`**，必须严格通过 `<svg><use href="..."/></svg>` 结构从统一的全局 sprite 中调用。
+
+---
+
+## 1. 语义骨架 (Semantic Structure)
+
+AI 生成该组件时，必须 100% 像素级复刻以下 HTML DOM 结构与 Tailwind 基础类名，严禁更改嵌套关系：
+
+```html
+<div class="scan-container block w-[456px] h-[60px] flex-shrink-0 my-2 px-4 flex items-center bg-grey-1 border border-grey-3 rounded-4dp">
+  
+  <svg class="scan-status-icon w-6 h-6 flex-shrink-0 text-black-3 select-none" style="cursor: default;">
+    <use href="../icons/icons-sprite.svg#common_ic_scanning_o"/>
+  </svg>
+
+  <input 
+    type="text" 
+    class="scan-input flex-1 h-full mx-2 bg-transparent border-none outline-none font-sans text-[20px] font-normal text-black-6 placeholder-black-3" 
+    placeholder="扫描或输入运单号" 
+    autocomplete="off"
+  >
+  
+</div>
+```
+
+### 1.1 类名锁定表
+
+| 元素 | 类名 | 严禁修改 |
+|------|------|---------|
+| 容器 | `scan-container` | 必须，用于状态切换 |
+| 容器布局 | `block w-[456px] h-[60px] flex-shrink-0 my-2 px-4 flex items-center` | 必须 |
+| 容器主题 | `bg-grey-1 border border-grey-3 rounded-4dp` | idle 状态 |
+| 图标 | `scan-status-icon` | 必须 |
+| 图标布局 | `w-6 h-6 flex-shrink-0` | 必须 |
+| 图标主题 | `text-black-3 select-none` | idle: grey |
+| 输入框 | `scan-input` | 必须 |
+| 输入框布局 | `flex-1 h-full mx-2 bg-transparent border-none outline-none` | 必须 |
+| 输入框主题 | `font-sans text-[20px] font-normal text-black-6 placeholder-black-3` | 必须 |
+
+### 1.2 内联样式锁定
+
+```html
+<svg style="cursor: default;">
+```
+
+- ⛔ 严禁改为 `cursor: pointer`
+- ⛔ 严禁添加 `onclick` 事件
+- ✅ 必须锁死 `cursor: default`
+
+---
+
+## 2. 状态机 (State Machine)
+
+状态切换通过 JavaScript 动态添加/移除 Tailwind 类名实现，**严禁使用 CSS 伪类**（如 `:focus`, `:hover`）。
+
+### 2.1 状态映射表
+
+| 状态 | 容器类名变更 | 图标类名变更 | 触发条件 |
+|------|-------------|-------------|---------|
+| **idle** | `bg-grey-1 border-grey-3` | `text-black-3` | 页面初始 / 失焦 |
+| **focused** | `+ border-main-6` | `text-green-6` | 输入框聚焦 |
+| **success** | `bg-green-1 border-green-6` | `text-green-6` | 扫描/输入成功 |
+| **error** | `bg-red-1 border-red-6` | `text-red-6` | 扫描/输入失败 |
+
+### 2.2 状态切换实现
+
+```javascript
+/**
+ * 设置 ScanInput 状态
+ * @param {'idle'|'focused'|'success'|'error'} state
+ */
+function setScanState(state) {
+  const container = document.querySelector('.scan-container');
+  const icon = document.querySelector('.scan-status-icon');
+  
+  // 重置所有状态类
+  container.classList.remove(
+    'border-main-6', 'bg-green-1', 'border-green-6', 'bg-red-1', 'border-red-6'
+  );
+  icon.classList.remove('text-green-6', 'text-red-6');
+  
+  // 应用新状态
+  switch(state) {
+    case 'focused':
+      container.classList.add('border-main-6');
+      icon.classList.add('text-green-6');
+      break;
+    case 'success':
+      container.classList.add('bg-green-1', 'border-green-6');
+      icon.classList.add('text-green-6');
+      break;
+    case 'error':
+      container.classList.add('bg-red-1', 'border-red-6');
+      icon.classList.add('text-red-6');
+      break;
+    default: // idle
+      // 保持默认类名
+      break;
+  }
+}
+
+// 事件绑定
+document.querySelector('.scan-input').addEventListener('focus', () => {
+  setScanState('focused');
+});
+
+document.querySelector('.scan-input').addEventListener('blur', () => {
+  setScanState('idle');
+});
+
+document.querySelector('.scan-input').addEventListener('keydown', (e) => {
+  if (e.key === 'Enter') {
+    const value = e.target.value;
+    if (value) {
+      setScanState('success');
+      // 3秒后恢复 idle
+      setTimeout(() => setScanState('idle'), 3000);
+    }
+  }
+});
+```
+
+### 2.3 状态切换原则
+
+- ⛔ **严禁使用 CSS `:focus` 伪类** 实现聚焦状态
+- ⛔ **严禁使用 `transition`** 实现状态过渡
+- ✅ **必须使用 JavaScript 动态切换类名**
+- ✅ **状态切换必须是秒级闪切**，无渐变效果
+
+---
+
+## 3. 资源引用 (Asset References)
+
+### 3.1 图标引用（强制）
+
+```html
+<svg class="scan-status-icon ...">
+  <use href="../icons/icons-sprite.svg#common_ic_scanning_o"/>
+</svg>
+```
+
+**路径规则：**
+- HTML 在 `demos/` 目录：`../icons/icons-sprite.svg#common_ic_scanning_o`
+- HTML 在根目录：`./icons/icons-sprite.svg#common_ic_scanning_o`
+
+**严禁：**
+- ⛔ `<img src="...">` 引用 SVG
+- ⛔ 手写 `<svg><path d="..."/></svg>`
+- ⛔ 使用 `icons/assets/` 下的独立 SVG 文件
+
+### 3.2 依赖 Token
+
+```yaml
+colors:
+  - --color-grey-1:   #FFFFFF (idle 背景)
+  - --color-grey-3:   #E0E4F0 (idle 边框)
+  - --color-main-6:   #6445D1 (focused 边框)
+  - --color-green-1:  #F6FFED (success 背景)
+  - --color-green-6:  #52C41A (success 边框/图标)
+  - --color-red-1:    #FFF1F0 (error 背景)
+  - --color-red-6:    #FF4D4F (error 边框/图标)
+  - --color-black-3:  #BBBBBB (idle 图标)
+  - --color-black-6:  #333333 (输入文字)
+
+radius:
+  - --radius-4dp: 4px (唯一允许的圆角值)
+```
+
+---
+
+## 4. 反模式对照 (Anti-Patterns)
+
+| 反模式 | 错误代码 | 正确代码 | 后果 |
+|--------|---------|---------|------|
+| 右侧扫描按钮 | `<button class="scan-btn">扫描</button>` | 无，右侧必须为空 | P0-致命，代码废弃 |
+| 图标可点击 | `onclick="startScan()"` | 无 onclick，cursor: default | P0-致命，代码废弃 |
+| 使用 transition | `transition: border-color 0.3s` | 无 transition | P0-致命，代码废弃 |
+| 大圆角 | `rounded-lg (8px)` | `rounded-4dp (4px)` | P1-严重，必须修复 |
+| 手写 SVG path | `<svg><path d="..."/></svg>` | `<svg><use href="..."/></svg>` | P1-严重，必须修复 |
+| 裸 Hex 颜色 | `#333333` | `text-black-6` | P1-严重，必须修复 |
+| CSS :focus 伪类 | `.scan-input:focus {...}` | JS 动态切换类名 | P1-严重，必须修复 |
+
+---
+
+## 5. 完整示例 (Complete Example)
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <script src="https://cdn.tailwindcss.com"></script>
+  <script src="../tokens/tailwind.config.js"></script>
+</head>
+<body class="bg-grey-2">
+
+  <!-- ScanInput 组件 -->
+  <div class="scan-container block w-[456px] h-[60px] flex-shrink-0 my-2 px-4 flex items-center bg-grey-1 border border-grey-3 rounded-4dp">
+    
+    <svg class="scan-status-icon w-6 h-6 flex-shrink-0 text-black-3 select-none" style="cursor: default;">
+      <use href="../icons/icons-sprite.svg#common_ic_scanning_o"/>
+    </svg>
+
+    <input 
+      type="text" 
+      class="scan-input flex-1 h-full mx-2 bg-transparent border-none outline-none font-sans text-[20px] font-normal text-black-6 placeholder-black-3" 
+      placeholder="扫描或输入运单号" 
+      autocomplete="off"
+    >
+    
+  </div>
+
+  <script>
+    // 状态控制
+    function setScanState(state) {
+      const container = document.querySelector('.scan-container');
+      const icon = document.querySelector('.scan-status-icon');
+      
+      container.classList.remove(
+        'border-main-6', 'bg-green-1', 'border-green-6', 'bg-red-1', 'border-red-6'
+      );
+      icon.classList.remove('text-green-6', 'text-red-6');
+      
+      switch(state) {
+        case 'focused':
+          container.classList.add('border-main-6');
+          icon.classList.add('text-green-6');
+          break;
+        case 'success':
+          container.classList.add('bg-green-1', 'border-green-6');
+          icon.classList.add('text-green-6');
+          break;
+        case 'error':
+          container.classList.add('bg-red-1', 'border-red-6');
+          icon.classList.add('text-red-6');
+          break;
+      }
+    }
+
+    // 事件绑定
+    const input = document.querySelector('.scan-input');
+    
+    input.addEventListener('focus', () => setScanState('focused'));
+    input.addEventListener('blur', () => setScanState('idle'));
+    input.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter' && e.target.value) {
+        setScanState('success');
+        setTimeout(() => setScanState('idle'), 3000);
+      }
+    });
+  </script>
+
+</body>
+</html>
+```
+
+---
+
+## 6. AI 生成检查清单
+
+生成代码后必须逐项确认：
+
+- [ ] 容器类名包含 `block w-[456px] h-[60px] flex-shrink-0 my-2 px-4 flex items-center`
+- [ ] 容器主题类名包含 `bg-grey-1 border border-grey-3 rounded-4dp`
+- [ ] 图标使用 `<svg><use href="../icons/icons-sprite.svg#common_ic_scanning_o"/></svg>`
+- [ ] 图标类名包含 `w-6 h-6 flex-shrink-0 text-black-3 select-none`
+- [ ] 图标内联样式为 `cursor: default`
+- [ ] 输入框类名包含 `flex-1 h-full mx-2 bg-transparent border-none outline-none font-sans text-[20px] font-normal text-black-6 placeholder-black-3`
+- [ ] 右侧**无任何按钮/图标**
+- [ ] 无 `transition` / `animation` 属性
+- [ ] 圆角值为 `4px` (rounded-4dp)
+- [ ] 状态切换通过 JavaScript 实现，非 CSS 伪类
+
+---
+
+**文档版本：** v3.1.0  
+**最后更新：** 2024-01-01  
+**状态：** 强制生效  
+**适用范围：** AI 代码生成、人工编码、代码审查

package/spec-data/section-heading.md

@@ -0,0 +1,268 @@
+---
+id: section-heading
+name: 模块标题
+category: "布局/Layout"
+version: "1.0.0"
+source: PDAKit-基础组件
+source_url: https://mastergo.ky-tech.com.cn/goto/TY6b0Zcx
+source_doc_id: 103417331857122
+component_count: 3
+---
+
+# 模块标题 Section Heading
+
+页面/卡片模块标题栏，用于分割内容区块并提供标题 + 辅助说明 + 右侧操作入口。宽度撑满容器（480px），左对齐标题组 + 右对齐按钮组。
+
+> **颜色规则**：全部使用 Token（`--color-{色系}-{色阶}`），禁止 Hex。
+> **字体**：PingFang SC。
+
+---
+
+## 组件总览
+
+| 组件实例 | Node ID | 说明 |
+|----------|---------|------|
+| 模块标题/仅大标题 | `25383:09800` | 大标题 + 右侧操作，无辅助说明 |
+| 模块标题/大标题+辅助说明 | `25453:11158` | 大标题 + 辅助说明 + 右侧操作 |
+| 模块标题/大标题+辅助说明+按钮 | `25563:73521` | 大标题 + 辅助说明 + 右侧双按钮 |
+
+---
+
+## Props
+
+| Prop | 类型 | 值 | 默认 |
+|------|------|-----|------|
+| 类型 | enum | `大标题` / `小标题`（待补充） | `大标题` |
+| 标题名称 | string | 任意文字 | `请输入标题名称` |
+| 显示辅助说明 | boolean | `true` / `false` | `false` |
+| 辅助说明 | string | 任意文字（仅在 `显示辅助说明=true` 时生效） | `请输入输入辅助说明文本` |
+| 显示右侧操作 | boolean | `true` / `false` | `false` |
+| 显示分割线 | boolean | `true` / `false` | `false` |
+
+> 本次仅选中「大标题」类型。**小标题**类型存在但未选中导出，待后续补充。
+
+---
+
+## 规格
+
+### 容器
+
+| 属性 | 值 |
+|------|------|
+| 宽度 | `471px`（撑满 480px 页面减去内边距） |
+| 高度 | `68px`（无辅助说明） / `84px`（有辅助说明） |
+| 背景 | `--color-grey-1`（`#FFFFFF`） |
+| 内边距 | `16px` |
+| 布局 | `flex-row`，`space-between`，`align-items: flex-start` |
+
+### 标题文字
+
+| 属性 | 值 |
+|------|------|
+| 字体 | PingFang SC，`22px / 30px`，Semibold（`600`） |
+| 颜色 | `--color-black-6`（`#333333`） |
+| 对齐 | 左对齐 |
+
+### 辅助说明文字（可选）
+
+| 属性 | 值 |
+|------|------|
+| 字体 | PingFang SC，`16px / 22px`，Regular（`400`） |
+| 颜色 | `--color-black-5`（`#666666`） |
+| 对齐 | 左对齐 |
+
+### 右侧操作区（可选）
+
+| 属性 | 值 |
+|------|------|
+| 布局 | `flex-row`，`gap: 8px` |
+| 按钮类型 | 文字按钮 / Large（`20px / 28px`，颜色 `--color-main-6`） |
+| 按钮数量 | 1-2 个 |
+| 按钮尺寸 | 最小 `56×36`，最大 `168×40`，内边距 `4px 8px` |
+
+---
+
+## 布局结构
+
+### 大标题 + 辅助说明 + 右侧操作（高度 84px）
+
+```
+┌──────────────────────────────────────────────────────┐
+│  请输入标题名称                          按钮    按钮  │  ← padding: 16px
+│  请输入输入辅助说明文本                               │
+└──────────────────────────────────────────────────────┘
+```
+
+### 仅大标题 + 右侧操作（高度 68px）
+
+```
+┌──────────────────────────────────────────────────────┐
+│  请输入标题名称                          按钮    按钮  │  ← padding: 16px
+└──────────────────────────────────────────────────────┘
+```
+
+---
+
+## HTML 示例
+
+### 场景 A：大标题 + 辅助说明 + 右侧操作
+
+```html
+<div class="section-heading section-heading-large">
+  <div class="section-heading-inner">
+    <!-- 左侧标题组 -->
+    <div class="section-heading-text">
+      <h3 class="section-heading-title">运单管理</h3>
+      <p class="section-heading-subtitle">今日已处理 128 个运单</p>
+    </div>
+    <!-- 右侧操作 -->
+    <div class="section-heading-actions">
+      <span class="section-heading-btn">筛选</span>
+      <span class="section-heading-btn">一键签收</span>
+    </div>
+  </div>
+</div>
+```
+
+### 场景 B：仅大标题 + 右侧操作（无辅助说明）
+
+```html
+<div class="section-heading section-heading-large section-heading-no-subtitle">
+  <div class="section-heading-inner">
+    <div class="section-heading-text">
+      <h3 class="section-heading-title">运单管理</h3>
+    </div>
+    <div class="section-heading-actions">
+      <span class="section-heading-btn">筛选</span>
+    </div>
+  </div>
+</div>
+```
+
+### 场景 C：仅大标题（无辅助说明、无右侧操作）
+
+```html
+<div class="section-heading section-heading-large section-heading-no-subtitle">
+  <div class="section-heading-inner">
+    <div class="section-heading-text">
+      <h3 class="section-heading-title">运单管理</h3>
+    </div>
+  </div>
+</div>
+```
+
+---
+
+## CSS
+
+```css
+/* 容器 */
+.section-heading {
+  width: 100%;
+  background: var(--color-grey-1);
+}
+
+/* 高 84px（有辅助说明） */
+.section-heading-large {
+  height: 84px;
+}
+/* 高 68px（无辅助说明） */
+.section-heading-no-subtitle {
+  height: 68px;
+}
+
+/* 内层 */
+.section-heading-inner {
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-start;
+  padding: 16px;
+  height: 100%;
+}
+
+/* 左侧标题组 */
+.section-heading-text {
+  display: flex;
+  flex-direction: column;
+  justify-content: flex-start;
+  align-items: flex-start;
+  flex-shrink: 0;
+}
+
+/* 标题 */
+.section-heading-title {
+  color: var(--color-black-6);
+  font-size: 22px;
+  line-height: 30px;
+  font-weight: 600;
+  font-family: PingFang SC;
+  margin: 0;
+}
+
+/* 辅助说明 */
+.section-heading-subtitle {
+  color: var(--color-black-5);
+  font-size: 16px;
+  line-height: 22px;
+  font-family: PingFang SC;
+  margin: 0;
+}
+
+/* 右侧操作区 */
+.section-heading-actions {
+  display: flex;
+  justify-content: flex-start;
+  align-items: flex-start;
+  gap: 8px;
+  flex-shrink: 0;
+}
+
+/* 右侧按钮（文字按钮/Large） */
+.section-heading-btn {
+  min-width: 56px;
+  max-width: 168px;
+  min-height: 36px;
+  max-height: 40px;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  gap: 8px;
+  padding: 4px 8px;
+  border-radius: 4px;
+  border: none;
+  background: transparent;
+  color: var(--color-main-6);
+  font-size: 20px;
+  line-height: 28px;
+  font-family: PingFang SC;
+  text-align: right;
+  cursor: pointer;
+}
+```
+
+---
+
+## 颜色 Token
+
+| Token | 色值 | 使用场景 |
+|-------|------|---------|
+| `--color-grey-1` | `#FFFFFF` | 容器背景 |
+| `--color-black-6` | `#333333` | 标题文字 |
+| `--color-black-5` | `#666666` | 辅助说明文字 |
+| `--color-main-6` | `#6445D1` | 右侧操作按钮文字 |
+
+---
+
+## 使用规则（AI 必读）
+
+1. **场景选型**：
+   | 场景 | 配置 |
+   |------|------|
+   | 简单列表模块 | 仅大标题 + 右侧操作 |
+   | 需补充说明的模块 | 大标题 + 辅助说明 + 右侧操作 |
+   | 纯展示标题 | 仅大标题 |
+2. **高度自适应**：有辅助说明 `84px`，无辅助说明 `68px`，通过 class 控制
+3. **右侧按钮**：1-2 个文字按钮（Large），颜色 `--color-main-6`，按需显隐
+4. **宽度撑满**：容器宽度 100%，内边距 16px 由父级模块控制
+5. **颜色用 Token**：禁止裸 Hex，全部用 `--color-*` 引用
+6. **分割线按需**：`显示分割线=true` 时在容器底部追加 1px 分割线