hap-api-website

HAP Frontend-Backend Project Setup Guide

Trigger Conditions (MANDATORY)

<EXTREMELY_IMPORTANT> When the user mentions any of the following situations, this skill must be used:

• ✅ "Build an official website through HAP"
• ✅ "Use HAP to make a website"
• ✅ "HAP frontend project"
• ✅ "HAP as database" + "website"-related requirements
• ✅ "Corporate 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 tech 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 (Advanced Application Platform)** as the backend content management system to build a complete frontend-backend separated project. It is suitable for various scenarios such as corporate official websites, content management websites, data display platforms, and form collection systems.

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:

• Corporate 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 appointment, questionnaire survey, inquiry order)
• Marketing landing page (event page, promotion page)

---

Workflow

Phase 1: Requirements understanding and structure assessment

Objective: Understand user requirements and assess 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.)
   • Determine the reusability of the existing structure
   • Identify missing worksheets and fields

3. Output assessment report

   • ✅ List of reusable structures
   • ➕ Suggested additions
   • 🚫 Operations not to execute (analysis phase only)

Key principles:

• ⚠️ This phaseonly performs analysis and must not execute any write operations
• ✅ Must first read the existing application structure
• ✅ Must assess whether it meets the requirements

---

Phase 2: User confirmation (mandatory)

Objective: Obtain explicit user consent before executing structural changes

Trigger conditions:

• 🔴 Need to create a new worksheet
• 🔴 Need to add fields to an existing worksheet
• 🔴 Need to write sample data
• 🔴 Need to modify existing field configuration

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

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

Prohibited actions:

• ❌ Creating a worksheet without confirmation
• ❌ Adding fields without confirmation
• ❌ Writing data without confirmation
• ❌ Assuming user intent

---

Phase 3: HAP backend configuration

Objective: Create/supplement data structures and sample data in HAP

Execution order:

1. Create a new worksheet(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 an existing worksheet(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://你的图片URL/示例.png'
                   }] },
                   { 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
• 🔴 Attachment fields must be populated with image URLs(use the test image URLs provided in the documentation)
• ❌ Attachment fields must never be 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: Obtain manually

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

Obtain the worksheet ID and field ID:

• Via MCP: get_worksheet_structure
• Via API: /v3/app/worksheets/{worksheetId}/structure
• Browser element inspection: 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

   • Attachment field: use downloadUrl
   • Option field: extract value attribute
   • Related record: extract name or sid
   • Checkbox: determine === '1'

Detailed API usage specification: Reference references/hap-api-usage-guide.md

---

Stage 7: Data Rendering

Objective: Implement dynamic data rendering and user interaction

Core requirements:

• ✅ Dynamically generate DOM (using template strings)
• ✅ Handle empty data state (friendly prompt)
• ✅ Handle image loading failure (placeholder image)
• ✅ Data formatting (price, date, etc.)
• ✅ Responsive layout
• ✅ Loading state prompt
• ✅ 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();
    }
}

---

Stage 8: Start Development Server

Objective: Automatically start the local development server for user preview

Startup method (by 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 run_in_background: true parameter
• ✅ Immediately output the access address to the user
• ✅ Try other ports if the port is occupied (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 titles

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

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

2. Add-only, never delete principle (red line)

✅ Allowed operations:

• Add worksheet (requires confirmation)
• Add field (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 add at least 5 sample data entries
• 🔴 Attachment fields must be filled with image URLs(most important!)
• ✅ Sample data must conform to field types
• ✅ Sample data must be directly usable for frontend preview

4. SingleSelect/MultipleSelect Filtering Specification

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

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

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

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

---

Frequently Asked Questions

Q1: How to 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 element
• Find data-controlid attributes

Q2: How should attachment fields be 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 can API keys be kept secure?

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

Production environment:

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

Q4: How can performance be optimized when the data volume is large?

1. Paginated loading: Set a reasonable pageSize (20-50 recommended)
2. Field filtering: Only retrieve the fields that are needed
3. Frontend caching: Use localStorage or in-memory caching
4. Lazy loading: Load more when scrolling to the bottom
5. Debounce handling: 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 view plugin development guide - If you need to develop a HAP view plugin (different from this skill)

---

Workflow checklist

When executing this skill, please ensure that all of the following steps are completed:

• Phase 1: Read the application structure and assess the gaps
• Phase 2: Obtain user confirmation (if new structure needs to be added)
• Phase 3: Create/supplement the HAP data structure
• Phase 3: Add sample data (attachment fields must be filled 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 the API wrapper (api.js)
• Phase 5: Write the 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 address

---

Notes

1. Data must be retrieved dynamically: Business data must be obtained 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 filling: Attachment fields in 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 front-end and back-end separated project setup