SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillshap-frontend-project

hap-frontend-project

Frontend & websites

View repository

Updated 10-15 21:50

About this skill

HAP Frontend and Backend Project Setup Guide

Trigger Conditions (MANDATORY)

<EXTREMELY_IMPORTANT> This skill must be used when the user mentions any of the following situations:

  • ✅ "Build an official website with HAP"
  • ✅ "Use HAP to build a website"
  • ✅ "HAP frontend project"
  • ✅ "HAP as database" + "website"-related requirements
  • ✅ "Enterprise official website" + "HAP"-related requirements
  • ✅ "Build a website" + "HAP"-related requirements
  • ✅ "Official website" + "HAP"-related requirements
  • ✅ "HAP website"
  • ✅ "HAP official website"
  • ✅ "Frontend-backend separation" + "HAP"-related requirements
  • ✅ "Content management system" + "HAP"-related requirements

Skill priority:

  • If the user explicitly mentions "HAP" + "website/official website/frontend", this skill must be used first
  • If the user mentions "build a website" but does not mention the technology stack, you may ask whether to use HAP

This is MANDATORY. No exceptions. </EXTREMELY_IMPORTANT>

Overview

This skill provides a complete workflow for using **Mingdao Cloud HAP (Hyper Automation Platform)** as the backend content management system to build a complete frontend-backend separated project. It is suitable for various scenarios such as enterprise official websites, content management websites, data display platforms, form collection systems, and more.

Core capabilities:

  • ✅ HAP backend data structure design and configuration
  • ✅ Frontend project architecture setup (HTML/CSS/JS)
  • ✅ HAP API V3 integration and data interaction
  • ✅ Complete development workflow and best practices
  • ✅ Automatically start the local development server

Applicable scenarios:

  • Enterprise official website (product display, news and information, case display)
  • Content management website (blog, document library, knowledge base)
  • Data display platform (data dashboard, report display)
  • Form collection system (online booking, questionnaire survey, inquiry orders)
  • Marketing landing page (event page, promotion page)

HAP Product Line Description

🌐 Multi-product line support

HAP supports multiple product lines and private deployment. When calling the API in a frontend project, you need to configure the correct API Host：

Product line API Host Description
Mingdao Cloud HAP https://api.mingdao.com Official SaaS service
Nocoly HAP https://www.nocoly.com Nocoly SaaS service
Private deployment HAP https://your-domain.com/api ⚠️ Note: Private deployment requires adding /api

Examples：

  • Mingdao Cloud:https://api.mingdao.com/v3/open/worksheet/getFilterRows
  • Private deployment:https://p-demo.mingdaoyun.cn/api/v3/open/worksheet/getFilterRows ← Note /api

Configuration suggestions：

  • Set in the project configuration file API_BASE_URL
  • Automatically determine which host to use based on the user's MCP configuration
  • If the user does not provide it, ask which product line to use

Workflow

Phase 1: Requirement understanding and structure evaluation

Objective: Understand user requirements and evaluate the existing HAP application structure

Must execute:

  1. Read application structure

    // 获取应用工作表列表
mcp__hap_mcp____get_app_worksheets_list({
    responseFormat: 'md'
})

// 获取特定工作表结构
mcp__hap_mcp____get_worksheet_structure({
    worksheet_id: '工作表ID',
    responseFormat: 'md',
    ai_description: '工作表: <工作表名称>'
})

  2. Structure gap assessment

    • Identify business objects (products, cases, news, etc.)
    • Assess reusability of existing structures
    • Identify missing worksheets and fields

  3. Output assessment report

    • ✅ List of reusable structures
    • ➕ Suggested additions
    • 🚫 Actions not performed (analysis phase only)

Key principles:

  • ⚠️ This phaseis analysis only; no write operations may be performed
  • ✅ The app's existing structure must be read first
  • ✅ Must assess whether requirements are met

Phase 2: User confirmation (mandatory)

Objective: Obtain explicit user consent before executing structural changes

Trigger conditions:

  • 🔴 Need to add worksheets
  • 🔴 Need to add fields to existing worksheets
  • 🔴 Need to write sample data
  • 🔴 Need to modify existing field configurations

Confirmation method: Use AskUserQuestion tool to clearly list the proposed actions:

AskUserQuestion({
    questions: [{
        question: "根据业务需求分析，当前应用缺少「新闻资讯」相关数据表。是否允许创建新的工作表？",
        header: "新增工作表",
        multiSelect: false,
        options: [
            {
                label: "同意创建(推荐)",
                description: "创建「新闻资讯」工作表，包含标题、封面图、发布时间、内容等字段，并添加 5 条示例数据"
            },
            {
                label: "仅创建表结构",
                description: "只创建工作表和字段，不添加示例数据。前端页面可能显示为空"
            },
            {
                label: "暂不创建",
                description: "跳过此工作表，使用现有数据完成开发。新闻模块将无法展示"
            }
        ]
    }]
})

Prohibited actions:

  • ❌ Adding worksheets without confirmation
  • ❌ Adding fields without confirmation
  • ❌ Writing data without confirmation
  • ❌ Assuming user intent

Phase 3: HAP backend configuration

Objective: Create/supplement the data structure and sample data in HAP

Execution order:

  1. Create new worksheets(if the user agrees)

    mcp__hap_mcp____create_worksheet({
    name: '新闻资讯',
    alias: 'news',
    fields: [
        { name: '标题', type: 'Text', isTitle: true, required: true },
        { name: '封面图', type: 'Attachment', required: false },
        { name: '发布时间', type: 'Date', required: false },
        { name: '内容', type: 'Text', required: false },
        { name: '是否发布', type: 'Checkbox', required: false }
    ],
    ai_description: '工作表: 新闻资讯'
})

  2. Add fields to existing worksheets(if the user agrees)

    mcp__hap_mcp____update_worksheet({
    worksheet_id: '现有工作表ID',
    addFields: [
        { name: '封面图', type: 'Attachment' },
        { name: '详情', type: 'Text' }
    ],
    ai_description: '工作表: <工作表名称>'
})

  3. Add sample data(if the user agrees)

    // 🔴 重要：附件字段必须填充图片 URL
mcp__hap_mcp____batch_create_records({
    worksheet_id: '工作表ID',
    rows: [
        {
            fields: [
                { id: '标题字段ID', value: '示例新闻标题' },
                { id: '封面图字段ID', value: [{
                    name: 'news.jpg',
                    url: 'https://m1.mingdaoyun.cn/doc/20251205/095p6B8tbW3x9v1A5lc41O8QdYaua101bM8Wb7442Q2ZfKb21m8deM1U0r4UaC9h.png?e=1765001146299&token=...'
                }] },
                { id: '发布时间字段ID', value: '2024-12-01' },
                { id: '内容字段ID', value: '新闻内容...' },
                { id: '是否发布字段ID', value: '1' }
            ]
        }
        // ... 至少 5 条示例数据
    ],
    triggerWorkflow: false,
    ai_description: '工作表: 新闻资讯'
})

Key requirements:

  • ✅ Each new worksheet must have at least 5 pieces of sample data added
  • 🔴 Attachment fields must be populated with image URLs(use the test image URL provided in the documentation)
  • ❌ Attachment fields must never be left as an empty array [] or an empty string ''
  • ⚠️ SingleSelect/MultipleSelect filtering must use the key (UUID), not the display text

Test image URLs (8): See references/hap-as-database-guide.md Section 1.3

Phase 4: Obtain API credentials

Objective: Obtain HAP API authentication information

Method 1: Extract via MCP configuration (recommended)

{
  "mcpServers": {
    "hap-mcp-应用名": {
      "url": "https://api.mingdao.com/mcp?HAP-Appkey=xxx&HAP-Sign=xxx"
    }
  }
}

Extract from URL parameters:

  • HAP-Appkey: Extract from URL parameters
  • HAP-Sign: Extract from URL parameters

Method 2: Manual retrieval

  1. Log in to Mingdao Cloud → App → Settings → API Key
  2. Copy the Appkey and Sign

Obtain worksheet ID and field ID:

  • Via MCP: get_worksheet_structure
  • Via API: /v3/app/worksheets/{worksheetId}/structure
  • Browser inspect element: Find the data-controlid attribute

Phase 5: Frontend project setup

Objective: Create a complete frontend project structure

Project structure:

project-name/
├── index.html          # 主页面
├── css/
│   └── style.css       # 样式文件
├── js/
│   ├── config.js       # HAP 配置（Appkey、Sign、字段映射）
│   ├── api.js          # API 封装（请求、分页、筛选）
│   └── main.js         # 应用逻辑（渲染、事件处理）
├── images/             # 图片资源（可选）
└── README.md           # 项目说明

Core file templates:

1. js/config.js

const CONFIG = {
    API_BASE_URL: 'https://api.mingdao.com',
    HAP_APPKEY: '你的HAP_APPKEY',
    HAP_SIGN: '你的HAP_SIGN',
    WORKSHEETS: {
        PRODUCTS: '产品表ID',
        NEWS: '新闻表ID'
    },
    PRODUCT_FIELDS: {
        NAME: '产品名称字段ID',
        IMAGE: '产品图片字段ID',
        PRICE: '参考价格字段ID'
    }
};

2. js/api.js

  • Generic request method (handles authentication and errors)
  • getRows() - Get record list (supports pagination, filtering, and sorting)
  • getRecord() - Get single record details
  • getFieldValue() - Generic field value parsing function (supports all field types)

3. js/main.js

  • App initialization
  • Data Loading and Rendering
  • Event Handling
  • Error Handling

4. index.html

  • Semantic HTML Structure
  • Responsive Design Support
  • SEO Optimization

5. css/style.css

  • Modern, Professional Visual Design
  • Responsive Layout
  • Micro-interactions and Animations

Detailed Code Templates: Refer to references/hap-as-database-guide.md Sections 2-6

Phase 6: API Integration

Objective: Implement data interaction between the frontend and HAP API V3

Key Points:

  1. CORS Cross-Origin Requests

    headers: {
    'HAP-Appkey': CONFIG.HAP_APPKEY,
    'HAP-Sign': CONFIG.HAP_SIGN,
    'Content-Type': 'application/json'
}

  2. Paginated Queries

    API.getRows(worksheetId, {
    pageIndex: 1,
    pageSize: 20,
    includeTotalCount: true,
    filter: { /* 筛选条件 */ },
    sorts: [ /* 排序 */ ]
})

  3. Field Value Parsing

    • File Fields: Use downloadUrl
    • Option Fields: Extract the value property
    • Related Records: Extract name or sid
    • Checkbox: Check === '1'

Detailed API Usage Specifications: Refer to references/hap-api-usage-guide.md

Phase 7: Data Rendering

Objective: Implement dynamic data rendering and user interaction

Core Requirements:

  • ✅ Dynamically generate DOM (using template strings)
  • ✅ Handle empty data states (friendly prompts)
  • ✅ Handle image loading failures (placeholder images)
  • ✅ Data formatting (prices, dates, etc.)
  • ✅ Responsive layout
  • ✅ Loading state prompts
  • ✅ Error handling and user prompts

Example:

async loadProducts() {
    try {
        this.showLoading();
        const data = await API.getRows(CONFIG.WORKSHEETS.PRODUCTS, {
            pageSize: 20,
            filter: {
                type: 'group',
                logic: 'AND',
                children: [{
                    type: 'condition',
                    field: CONFIG.PRODUCT_FIELDS.PUBLISHED,
                    operator: 'eq',
                    value: ['1']
                }]
            }
        });
        this.renderProducts(data.rows);
    } catch (error) {
        this.showError('加载失败，请刷新重试');
    } finally {
        this.hideLoading();
    }
}

Phase 8: Start the Development Server

Objective: Automatically start a local development server for user preview

Startup Methods (in order of priority):

  1. Python HTTP Server (recommended)

    python -m http.server 8000

  2. npx serve

    npx serve -p 8000

  3. PHP Built-in Server

    php -S localhost:8000

Execution Requirements:

  • ✅ Use the run_in_background: true parameter
  • ✅ Immediately output the access address to the user
  • ✅ If the port is occupied, try other ports (8001, 8080, 3000)

Output Example:

✅ 项目搭建完成！
🚀 本地服务器已启动
📍 访问地址: http://localhost:8000
💡 提示: 在浏览器中打开上述地址即可预览网站

Core Principles (Must Be Followed)

1. Data Source Principle (Must Be Dynamic)

✅ Allowed static content:

  • Navigation menu text
  • Footer information
  • UI placeholder text
  • Fixed display headings

❌ Prohibited static content (must be obtained from HAP):

  • Product lists and details
  • Case showcases
  • News and information
  • Carousel content
  • Price information
  • Any business-related display data

2. Add-Only, Never Delete Principle (Red Line)

✅ Allowed operations:

  • Add worksheets (requires confirmation)
  • Add fields (requires confirmation)
  • Add sample data (requires confirmation)

❌ Strictly prohibited operations:

  • Delete any existing worksheet
  • Delete any existing field
  • Modify the alias of an existing field (unless explicitly requested by the user)
  • Modify existing data (unless explicitly requested by the user)

3. Mandatory Sample Data Requirements

  • ✅ Each new worksheet must have at least 5 sample data entries
  • 🔴 Attachment fields must be populated with image URLs(Most important!)
  • ✅ Example data must match the field types
  • ✅ Example data must be directly usable for frontend preview

4. SingleSelect/MultipleSelect filtering specification

🔴 Important warning: Filtering must use key (UUID), not display text!

// ❌ 错误：使用显示文本
value: ['现代简约']  // 筛选失败！

// ✅ 正确：使用 key
value: ['a1b2c3d4-e5f6-7890-abcd-ef1234567890']  // 筛选成功

// 获取 key 的方法：
// 1. 调用 get_worksheet_structure 获取字段的 options
// 2. 从 options 中找到匹配的 key

Frequently Asked Questions

Q1: How do I get the field ID?

Method 1: Use MCP (recommended)

mcp__hap_mcp____get_worksheet_structure({
    worksheet_id: '工作表ID',
    responseFormat: 'md'
})

Method 2: API query

fetch('https://api.mingdao.com/v3/app/worksheets/{worksheetId}/structure', {
    headers: {
        'HAP-Appkey': 'xxx',
        'HAP-Sign': 'xxx'
    }
})

Method 3: Browser inspect element

  • Open the HAP worksheet
  • F12 to inspect elements
  • Find the data-controlid attribute

Q2: How are attachment fields handled?

// 附件字段返回格式
const attachments = row[fieldId]; // Array
// [{downloadUrl: 'https://...', fileName: '图片.jpg'}]

// 获取第一个附件 URL
const imageUrl = attachments[0]?.downloadUrl || '';

// 使用 HAP CDN 参数优化
const thumbnailUrl = `${imageUrl}?imageView2/2/w/300`;

Q3: How do I keep the API key secure?

Development environment: can be used directly (localhost will not leak it)

Production environment:

  • Option 1: Use a backend proxy (Node.js, PHP, etc.)
  • Option 2: Use Serverless Functions (Vercel, Netlify)
  • Option 3: Restrict the HAP API key permissions (read-only permission)

Q4: How do I optimize performance when there is a large amount of data?

  1. Paginated loading: Set a reasonable pageSize (20-50 recommended)
  2. Field filtering: Only retrieve the fields you need
  3. Frontend caching: Use localStorage or in-memory caching
  4. Lazy loading: Load more when scrolling to the bottom
  5. Debouncing: Use debounce for the search box

Reference Resources

Core Documentation

  • references/hap-as-database-guide.md - Complete guide to building a HAP frontend and backend project

    • Project overview and architecture description
    • Detailed steps (HAP configuration, frontend setup, API integration)
    • Core concepts and best practices
    • Common issues and solutions

  • references/hap-api-usage-guide.md - HAP API V3 usage specification

    • API endpoints and authentication configuration
    • Detailed explanation of Filter syntax
    • Field type handling and data format conversion
    • Complete code examples

Related Skills

  • HAP MCP Usage Guide - Learn how to use HAP MCP for application management and data operations
  • HAP View Plugin Development Guide - If you need to develop a HAP view plugin (different from this skill)

Workflow Checklist

When executing this skill, make sure to complete all of the following steps:

  • Phase 1: Read the application structure and assess gaps
  • Phase 2: Obtain user confirmation (if new structures need to be added)
  • Phase 3: Create/supplement the HAP data structure
  • Phase 3: Add example data (attachment fields must be populated with image URLs)
  • Phase 4: Obtain API credentials (Appkey, Sign, worksheet ID, field ID)
  • Phase 5: Create the frontend project structure (HTML, CSS, JS)
  • Phase 5: Write the configuration file (config.js)
  • Phase 5: Write API wrapper (api.js)
  • Phase 5: Write application logic (main.js)
  • Phase 6: Implement API integration and data interaction
  • Phase 7: Implement data rendering and user interaction
  • Phase 8: Start the local development server and provide the access URL

Notes

  1. Data must be retrieved dynamically: Business data must be retrieved from the HAP API and must not be hardcoded in the code
  2. User confirmation mechanism: Any structural change must obtain the user's explicit consent
  3. Add-only, no-delete principle: Never delete existing worksheets, fields, or data
  4. Attachment field population: The attachment fields of sample data must be populated with image URLs
  5. Filtering uses key: SingleSelect/MultipleSelect filtering must use the option's key (UUID)
  6. Automatically start the server: After completing project setup, the local development server must be started automatically

Skill version: v1.0
Last updated: 2026-01-11
Applicable scenarios: HAP frontend-backend separated project setup