miot-calendar

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ModularIoT Calendar Skill

Prerequisites

前提条件

The

miot

CLI must be available. Run commands via:

```
npx @microboxlabs/miot-cli <command>
```
(no install needed), or
```
miot <command>
```
(if globally installed)

Configuration requires one of:

```
--base-url
```
and
```
--token
```
flags on every call
```
MIOT_BASE_URL
```
and
```
MIOT_TOKEN
```
environment variables
A
```
~/.miotrc.json
```
profile (selected via
```
--profile <name>
```
)

Always add

--output json

to CLI calls and parse the JSON result.

必须具备

miot

CLI环境。可通过以下方式运行命令：

```
npx @microboxlabs/miot-cli <command>
```
（无需安装），或
```
miot <command>
```
（若已全局安装）

配置需满足以下条件之一：

每次调用时添加
```
--base-url
```
和
```
--token
```
参数
设置
```
MIOT_BASE_URL
```
和
```
MIOT_TOKEN
```
环境变量
使用
```
~/.miotrc.json
```
配置文件（通过
```
--profile <name>
```
选择）

始终在CLI调用中添加

--output json

参数并解析JSON结果。

Domain Model

领域模型

Organization
 └── Groups          ← organize calendars by category
      └── Calendars  ← represent a bookable resource (room, vehicle, service)
           ├── Time Windows  ← define when slots are available (hours, days, capacity)
           ├── Slots         ← generated from time windows; bookable time units
           │    └── status: OPEN | CLOSED
           ├── Bookings      ← consume a slot, linked to a resource (vehicle, room…)
           └── Slot Managers ← automate slot generation on a rolling basis

Key relationships:

Time windows define the rules; slots are the instances generated from those rules.

A slot has

capacity

and

currentOccupancy

;

availableCapacity = capacity - currentOccupancy

A booking ties a resource to a specific slot. It requires the slot to be OPEN with remaining capacity.

Organization
 └── Groups          ← 按类别组织日历
      └── Calendars  ← 代表可预订资源（会议室、车辆、服务）
           ├── Time Windows  ← 定义时段可用规则（时段、日期、容量）
           ├── Slots         ← 由时间窗口生成的可预订时间单元
           │    └── status: OPEN | CLOSED
           ├── Bookings      ← 占用时段，关联至某一资源（车辆、会议室等）
           └── Slot Managers ← 自动滚动生成时段

核心关系：

时间窗口定义规则；时段是根据这些规则生成的实例。
每个时段包含
```
capacity
```
（容量）和
```
currentOccupancy
```
（当前占用量）；
```
availableCapacity = capacity - currentOccupancy
```
（可用容量=容量-当前占用量）。
预订会将资源与特定时段绑定，要求该时段状态为OPEN且仍有剩余可用容量。

Common Workflows

常见工作流

"What's available next week for X?"

“X资源下周有哪些可用时段？”

Find the calendar:
```
miot calendar list --output json
```

List available slots:

miot calendar slots list --calendar <id> --from <monday> --to <friday> --available --output json

Present results grouped by date with times and remaining capacity.

查找日历：
```
miot calendar list --output json
```

列出可用时段：

miot calendar slots list --calendar <id> --from <monday> --to <friday> --available --output json

按日期分组展示结果，包含时段和剩余容量。

"Book a slot for resource Y"

“为Y资源预订一个时段”

Find available slots (workflow above).
Present options to the user — let them choose.

Create the booking:

miot calendar bookings create --calendar <id> --resource-id <rid> --date <date> --hour <h> --minutes <m> --output json

查找可用时段（参考上述工作流）。
为用户展示选项并让其选择。

创建预订：

miot calendar bookings create --calendar <id> --resource-id <rid> --date <date> --hour <h> --minutes <m> --output json

"How full is calendar X this month?"

“X日历本月的占用情况如何？”

List all slots for the date range:

miot calendar slots list --calendar <id> --from <start> --to <end> --output json

Compute: total slots, occupied (capacity - availableCapacity), available, occupancy %.

列出指定日期范围内的所有时段：

miot calendar slots list --calendar <id> --from <start> --to <end> --output json

计算：总时段数、已占用时段数（容量-可用容量）、可用时段数、占用率。

"Generate slots for the next 2 weeks"

“生成未来2周的时段”

miot calendar slots generate --calendar <id> --from <today> --to <today+14> --output json

miot calendar slots generate --calendar <id> --from <today> --to <today+14> --output json

"What bookings does resource Z have?"

“Z资源有哪些预订记录？”

miot calendar bookings by-resource <resourceId> --output json

miot calendar bookings by-resource <resourceId> --output json

"Run the slot managers"

“运行时段管理器”

miot calendar slot-managers run --output json

Run a specific one:

miot calendar slot-managers run <managerId> --output json

miot calendar slot-managers run --output json

运行指定的管理器：

miot calendar slot-managers run <managerId> --output json

"Show me the calendar setup"

“展示日历配置”

```
miot calendar get <id> --output json
```

miot calendar time-windows list --calendar <id> --output json

Summarize: calendar details + active time windows with their schedules.

```
miot calendar get <id> --output json
```

miot calendar time-windows list --calendar <id> --output json

汇总展示：日历详情 + 生效的时间窗口及其规则。

Error Handling

错误处理

CLI errors return

{ "error": { "statusCode": N, "message": "..." } }

. Common codes:

Code	Meaning
400	Invalid parameters (date range > 90 days, invalid hours, etc.)
404	Resource not found
409	Slot full / no capacity remaining

Explain the error in plain language to the user.

CLI错误会返回

{ "error": { "statusCode": N, "message": "..." } }

。常见状态码：

状态码	含义
400	参数无效（日期范围超过90天、小时值无效等）
404	资源未找到
409	时段已满/无剩余容量

需用通俗易懂的语言向用户解释错误原因。

Business Rules

业务规则

Slot generation is limited to 90-day ranges.
Time window hours:
```
startHour < endHour
```
, both 0–23.
Days of week:
```
"1,2,3,4,5"
```
where 1 = Monday, 7 = Sunday.
Slot status:
```
OPEN
```
or
```
CLOSED
```
.
Booking requires an OPEN slot with
```
availableCapacity > 0
```
.
Hour: 0–23, Minutes: 0–59.

时段生成的范围限制为90天。
时间窗口小时数：
```
startHour < endHour
```
，取值范围均为0–23。
星期几：
```
"1,2,3,4,5"
```
，其中1=周一，7=周日。
时段状态：
```
OPEN
```
或
```
CLOSED
```
。
预订需要状态为OPEN且
```
availableCapacity > 0
```
的时段。
小时：0–23，分钟：0–59。

Full CLI Reference

完整CLI参考

For the complete list of commands, flags, and JSON output shapes, read references/reference.md.

有关命令、参数和JSON输出格式的完整列表，请查看references/reference.md。