magicbase

# MagicBase for HTML Micro-apps

Use this skill when an HTML micro-app needs persistent data, current-user identity, ownership, permissions, or runtime row-level database operations.

MagicBase has three operation surfaces:

- Schema work is done by agent tools before HTML generation: `query_magicbase_tables`, `get_magicbase_table`, `create_magicbase_table`, `create_magicbase_column`, `update_magicbase_table_permissions`, `delete_magicbase_table`, `update_magicbase_column`, and `delete_magicbase_column`.
- Explicit agent-side data maintenance uses `query_magicbase_rows`, `create_magicbase_row`, `batch_create_magicbase_rows`, `delete_magicbase_row`, and `batch_delete_magicbase_rows`.
- Runtime row operations are done inside HTML with `window.Magic.db`, using real table IDs returned by MagicBase tools.

Do not expose schema creation inside HTML pages. HTML code should only read and write rows on tables that already exist.

Project memory uses `MICRO-APP.md` for the latest human-readable app memory and MagicBase data model. Do not edit it directly with file-editing tools. MagicBase schema tools maintain `.magicbase/migrations.json`; after successful table or column changes, they refresh the latest MagicBase data model in `MICRO-APP.md`. If tools report a `Pending` migration at the start of a later task, query MagicBase first so confirmable records can be repaired before more schema work. If a legacy `HTML-APP.md` exists, read it for context and migrate the memory to `MICRO-APP.md` before finishing.

MagicBase exposes a simplified MySQL-like column model. Use only these `data_type` values when creating tables or columns: `text`, `number`, `datetime`, `boolean`, `json`.

### Datetime Values

For `datetime` columns, MagicBase accepts only these input formats:

- `YYYY-MM-DD`, normalized to `YYYY-MM-DD 00:00:00`.
- `YYYY-MM-DD HH:mm`.
- `YYYY-MM-DD HH:mm:ss`.
- `YYYY-MM-DDTHH:mm`.
- `YYYY-MM-DDTHH:mm:ss`.
- ISO 8601 values with a UTC or numeric timezone, with optional fractional seconds, such as `2026-08-04T03:12:18.582Z` or `2026-08-04T11:12:18.582+08:00`.

Use the raw value from `<input type="date">` or `<input type="datetime-local">` when it matches one of these formats. `Date.prototype.toISOString()` output is also accepted. MagicBase converts timezone-aware values to the service timezone and normalizes all accepted values to `YYYY-MM-DD HH:mm:ss` for storage and responses. Fractional seconds are discarded because MagicBase currently stores datetime values with second precision. Date and datetime filter values follow the same format rules.

Do not manually remove `Z` or a numeric timezone offset before calling `createRow`, `batchCreateRows`, `updateRow`, or a query filter. Removing timezone information changes the represented instant instead of converting it correctly.

Model UI choices with MySQL-like columns:

- Single-choice UI values use `text`.
- Multiple-choice UI values use `json` and write an array, such as `["office", "gaming"]`.
- User IDs, department IDs, attachment IDs/URLs, and foreign-key values use `text` unless the app truly needs a JSON array/object.
- Do not use low-code field types such as `single_select`, `multi_select`, `user`, `department`, `attachment`, or `reference`; MagicBase no longer exposes them as column types.
- Relations are separate metadata. Create ordinary key columns such as `customer_id: text`, then create a MagicBase relation between source and target columns when joined reads are needed.

## Current User Context (`window.Magic.getContext`)

Use `window.Magic.getContext()` whenever a micro-app needs current-user display, creators, owners, assignees, collaborators, "my data versus all data", or edit/delete permission checks.

`getContext()` is hosted by the parent application. It uses the current login state to query magic-service user information and returns a normalized current-user profile. HTML business code should not call `/api/v1/contact/users/queries` directly for the current user, should not hard-code tokens, and should not read `.credentials` files.

```javascript
const context = await window.Magic.getContext();
// context: {
//   userId: "usi_xxx",
//   userName: "Alice",
//   user: { user_id, real_name, nickname, avatar_url, phone, email, ... },
//   organizationCode: "org_xxx",
//   language: "zh-CN"
// }
```

For data apps with ownership or collaboration:

- Ensure `app.json.anonymous` matches the permission model. Apps that depend on real current-user identity, `created_by`, owner-only editing, departments, organizations, or team collaboration must set `anonymous:false`. Anonymous apps can only use identity-independent public flows such as public display or anonymous intake.
- Call `window.Magic.getContext()` during initialization before user-dependent reads or writes.
- Prefer MagicBase system fields for ownership. MagicBase automatically records `created_by` for every row, and backend `private_user` permissions are based on this system field.
- Do not create a dynamic `creator_user_id` column just to enforce creator permissions. Create business identity fields only when the app needs UI display, filtering, assignment, or domain-specific ownership beyond the system creator, such as `creator_name`, `owner_user_id`, `owner_name`, `assignee_user_id`, or `updated_by_user_id`.
- When creating a row, write only real business fields. Do not write system fields such as `created_by`, `organization_code`, `created_at`, or `updated_at`.
- When rendering edit/delete/archive/transfer buttons for creator-owned rows, request `created_by` through `select` and compare it with `context.userId`. Display names are not permission keys.
- If `getContext()` fails, disable user-dependent create, edit, delete, ownership, and transfer operations and show an understandable error. Never write fake identities such as `unknown`, `guest`, `visitor`, `访客`, or `未命名用户` into MagicBase.

## Micro-app Administrator Pages

Use this pattern when a micro-app has pages such as