Overview

The basic guide showed the simplest scenario: the user says one sentence and the AI creates a requirement. But in B2B business, many operations go far beyond single-table CRUD — changing a requirement status, for example, must update the main table, write a history record, and notify stakeholders, with no step optional.

Using "requirement status change" as the example, this case shows how the dev team builds a function endpoint when the business logic involves multi-table writes, state-transition validation, and transactional consistency — so an AI with the Skill loaded completes the entire flow from a single sentence.

---

The business scenario: why function endpoints

In the basic example, letting the AI operate the database directly is enough. Real business operations often demand more:

Strict validation: statuses must flow in order (new → assigned → in progress → testing → completed → closed); you can't jump from new straight to completed.

Data consistency: a status change must also record who changed it, when, and from what to what — the main table and the history table must update together, never one succeeding while the other fails.

Transactional integrity: one operation touches several tables; a write failure on any of them must roll everything back.

For scenarios like these, the dev team builds function endpoints that encapsulate the validation logic and transactional guarantees, registers them on the platform, and exposes them to the AI. Business users never need to know what SQL the function runs or how many writes it makes — they call the endpoint, and engineering guarantees consistency.

---

Implementation: building the function

Registered path

Standalone endpoint scripts (ENDPOINT) are reachable at the following path after registration:

POST /api/endpoint/{appCode}/{scriptName}

This case uses:

• Script name: update_requirement_status
• App: app-173e8652 (Qizhi Yuntu)
• Full path: POST /api/endpoint/app-173e8652/update_requirement_status

Prerequisites

Before development, the dev team confirms:

• The app app-173e8652 exists and contains the two data models yt_requirements (requirements main table) and yt_requirement_history (status history table)
• The operator has write permission on both models

Function code

The dev team implements the status change, updating the main table and writing the history record together:

/**
 * 需求状态变更（双写主表 + 历史表）
 * 脚本名称: update_requirement_status
 * 所属应用: app-173e8652
 */
export default async function updateRequirementStatus(params, context) {
  const { id, new_status, operator_id, reason } = params;

  // -------- 第一部分：查询校验 --------
  
  // 1. 查询需求当前信息
  const requirement = await context.client.models.yt_requirements.findOne({
    id: id
  });

  if (!requirement) {
    throw new Error("需求不存在");
  }

  const oldStatus = requirement.status;

  // 2. 校验状态流转是否合法
  const validTransitions = {
    "new": ["assigned", "closed"],
    "assigned": ["in_progress", "closed"],
    "in_progress": ["testing", "closed"],
    "testing": ["completed", "in_progress"],
    "completed": ["closed"],
    "closed": []
  };

  if (!validTransitions[oldStatus]?.includes(new_status)) {
    throw new Error(`状态不允许从 ${oldStatus} 直接变更为 ${new_status}`);
  }

  // -------- 第二部分：双写（事务保证） --------
  // 系统检测到写操作，自动开启 Best Effort 1PC 事务
  // 无需手动 commit/rollback，脚本正常返回即提交，抛异常即回滚

  // 3. 更新主表：需求状态
  await context.client.models.yt_requirements.update({
    id: id,
    status: new_status
  });

  // 4. 写入历史表：变更记录
  await context.client.models.yt_requirement_history.create({
    requirement_id: id,
    user_id: operator_id,
    field_name: "status",
    old_value: oldStatus,
    new_value: new_status,
    created_at: new Date().toISOString()
  });

  // -------- 第三部分：返回结果 --------
  return {
    success: true,
    requirement_id: id,
    old_status: oldStatus,
    new_status: new_status,
    operator_id: operator_id,
    message: "状态变更成功，历史记录已同步"
  };
}

How transactions work

The Lovrabet platform uses a Best Effort 1PC transaction model, so the dev team never manages transactions by hand:

When	Behavior
Read operations (findOne / getList)	No transaction opened, no connection held
First write operation (update / create)	Transaction opens automatically
Subsequent writes	Join the same transaction automatically
Script returns normally	All transactions commit automatically
Script throws	All transactions roll back automatically

The dev team just writes the logic in business order — the platform manages transactions.

---

Skill packaging: one sentence from a business user completes the operation

Once the function endpoint is built, how do business users use it?

Package the flow as a Skill; the AI then runs automatically: confirm the requirement exists → call the function → notify stakeholders.

Skill template

---
name: update_requirement_status
version: 0.1.0
description: "需求状态变更。触发词：标记为已完成、把需求改为、变更需求状态。"
---

# 需求状态变更

## 第一步：确认需求存在

根据用户提供的需求 ID，查询该需求是否存在、当前状态是什么。如果不存在，告知用户并终止。

## 第二步：变更状态并记录历史

调用 `update_requirement_status` 接口，同时完成：
- 修改需求状态为用户指定的状态
- 在历史记录中新增一条状态变更记录（记录原状态、新状态、操作人、操作时间）

如果接口返回失败，告知用户失败原因，终止流程。

## 第三步：通知需求提出人

查询该需求的创建人，向其发送邮件或飞书消息，告知：
- 哪个需求的状态发生了变更
- 变更后的状态是什么

## 注意事项

- 状态值必须在合法范围内（new / assigned / in_progress / testing / completed / closed）
- 如果用户没有指定变更原因，询问后再继续
- 第三步的通知仅需告知结果，无需额外操作
- 禁止直接调用数据集原始接口

---

Example

User input

把需求 App主题根据用户手机壳颜色自动适配 标记为已完成

What the AI does

Loads the Skill → confirms the requirement exists → calls the function endpoint (main-table update + history write in one) → notifies the requirement creator

Sample result

✅ 状态更新完成
━━━━━━━━━━━━━━━━━━
需求 ID：305
标题：App主题根据用户手机壳颜色自动适配
状态：进行中 → 已完成
操作人：梓骞
变更历史：已记录
━━━━━━━━━━━━━━━━━━
通知：已发送邮件给需求提出人

---

FAQ

Q: Do I need to build infrastructure myself for function endpoints?

A: No. Develop and register scripts under an existing Lovrabet app — transactions, connection management, and permission control all come from the platform. You can use the Rabetbase-CLI developer suite.

Q: Are transition rules inside the function hard to change?

A: It's far safer than exposing the database to the AI directly. When rules change, only the dev team edits the function code; the Skill and the AI prompt stay untouched.

Q: What if the endpoint returns an error?

A: Check the error message — common causes include a missing requirement ID, an illegal status transition, or insufficient permissions. Errors pass straight through to the AI, which reports them to the user.

Q: Do business users need to know the status values?

A: No. The Skill already defines the legal values. Users just say "mark it completed", and the AI maps it to the right status code.

Q: What if we add a new dimension later — say, priority-change history?

A: Add a history-table field in the function. The Skill describes business steps, not concrete field names.