create-aiaui-module 0.1.0 → 0.1.2-TEST

package/templates/JobInformation/CUSTOMIZATION.md

@@ -1,173 +1,123 @@
 # JobInformation customization
 
-This module ships with a built-in panel and exposes three customization
-levels. All of them keep the host-facing `mount(container, context)` /
-`unmount()` contract stable, so the Instance does not need to know which
-level you chose.
-
-## Customization entry
-
-Edit `resources/src/customization.ts`. It exports a single `customization`
-object:
-
-```ts
-import type { Customization } from "./contract";
-
-export const customization: Customization = { mode: "slots", slots: {} };
+This module ships a built-in job-information panel that reads two local
+endpoints and renders one card per job. Every part of a card can be replaced
+without touching the platform code; the host contract
+(`mount(container, context)` / `unmount()`) never changes.
+
+## Data contract (implement these two endpoints, get a working panel)
+
+`GET /jobs` — one entry per job (device + carriers + timeline + recipe):
+
+```json
+{
+  "items": [
+    {
+      "id": "job-001",
+      "name": "ASM3GM-PLUGIN-JOB-001",
+      "lot": "LOT-001",
+      "state": "Executing",
+      "carriers": { "input": [{"code": "CR-01"}], "output": [] },
+      "recipe": "RCP-CU-ETCH-O7",
+      "timeline": [
+        { "label": "Setup", "at": "2026-10-18T08:00:00", "state": "done" },
+        { "label": "Select", "at": "2026-10-18T08:01:05", "state": "done" },
+        { "label": "WaitingForStart", "at": "2026-10-18T08:02:30", "state": "active" },
+        { "label": "Executing", "at": "2026-10-18T08:05:12", "state": "pending" },
+        { "label": "Complete", "at": null, "state": "pending" }
+      ]
+    }
+  ],
+  "total": 1,
+  "page": 1,
+  "pageSize": 10
+}
 ```
 
-## Level 1 — default
-
-Leave `customization.ts` untouched. The module renders the built-in panel
-from `resources/src/defaults/`.
-
-## Level 2 — partial (replace boxes)
+- `{ id, name }` is the minimum; `lot/state/carriers/timeline/recipe` are all
+  optional and degrade to `—` / `No progress data`.
+- Durations between completed steps are computed on the frontend.
+- If `GET /jobs` fails, the module falls back to a built-in demo set.
+
+`GET /config` — the appearance contract:
+
+```json
+{
+  "display": {
+    "lotId": true,
+    "recipe": true,
+    "inputCarriers": true,
+    "outputCarriers": true,
+    "timeline": true
+  },
+  "states": [
+    { "name": "Executing", "color": "#1d4ed8", "icon": "activity" },
+    { "name": "Setup", "color": "#0369a1", "icon": "clock" },
+    { "name": "Complete", "color": "#166534", "icon": "flag" }
+  ]
+}
+```
 
-Set `mode: "slots"` and provide a `slots` map. Keys are the built-in slot
-names; values are Vue components that receive `context` as a prop.
+- Missing keys fall back to the built-in `config-defaults.ts` (all parts
+  visible, a sensible default state palette). Fields are merged shallowly, so
+  a backend may send only the fragments it wants to change.
+- The palette drives the status chip and the timeline step icons
+  (`clock / list / stop / activity / flag`). Unknown icons fall back to
+  `clock`.
+
+## Slots (what you can replace)
+
+Edit `resources/src/customization.ts`. Keys per card:
+
+| Slot | Replaces | Renders inside |
+| --- | --- | --- |
+| `board` | the entire job card | (replaces header + middle + bottom) |
+| `headerRegion` | the job-name / lot-id / state row | each card |
+| `jobName` | job name (italic + leading dot) | `headerRegion` |
+| `lotId` | `Lot ID  <value>` | `headerRegion` |
+| `status` | the state chip | `headerRegion` |
+| `middleRegion` | the input-carrier / timeline / output-carrier row | each card |
+| `inputCarriers` | the input-cards list | `middleRegion` |
+| `timeline` | the Setup → … → Complete stepper | `middleRegion` |
+| `outputCarriers` | the output-cards list | `middleRegion` |
+| `bottomRegion` | the recipe sub-card + footer | each card |
+| `recipe` | the `Recipe` + name line | `bottomRegion` |
+
+Every slot component receives `{ context, job, config }` as props; leaf
+slots ignore the region around them (which stays platform-owned). Replacing
+`board` (or any `*Region`) replaces the whole region — including its
+sub-slots if set.
 
 ```ts
-import MyHeader from "./custom/MyHeader.vue";
+// resources/src/customization.ts
+import MyJobName from "./custom/MyJobName.vue";
 import type { Customization } from "./contract";
 
 export const customization: Customization = {
-  mode: "slots",
-  slots: { header: MyHeader },
+  slots: { jobName: MyJobName },
 };
 ```
 
-### Built-in slots
-
-- `header` — job/lot identity and current state
-- `inputCarriers` — input carriers
-- `outputCarriers` — output carriers
-- `timeline` — progress steps
-- `recipe` — recipe/tool summary and actions
-
-### Slot component contract
+Slot contract:
 
 ```vue
 <script setup lang="ts">
-import type { ModuleContext } from "../contract";
+import type { ModuleSlotProps } from "../contract";
 
-defineProps<{ context: ModuleContext }>();
+defineProps<ModuleSlotProps>();
 </script>
-
 <template>
-  <section class="aiaji-slot">…</section>
+  <span class="my-custom">— {{ job.state }} · {{ job.name }} —</span>
 </template>
 ```
 
-`context.api.call(method, path, options)` reaches this module's backend
-router. `context.signal` is aborted when the host unmounts the module, so
-long-running requests should observe it.
-
-
-## Communicating between slots
-
-Every slot component in one mount — built-in or custom — receives the same
-`context` object. On top of `api` and `signal`, `context` carries a **bus**
-created fresh on each `mount` and dead on `unmount` (so switching Instance
-gets you a clean bus automatically). It never crosses module or Instance
-boundaries.
-
-### 1. Events (recommended for most cases)
-
-Decoupled one-to-many communication:
-
-```ts
-// MyInput.vue — sender
-const props = defineProps<{ context: ModuleContext }>();
-
-function onSelect(id: string) {
-  props.context.bus.emit("lot:selected", { id });
-}
-
-onBeforeUnmount(() => props.context.bus.off("lot:selected", onSelect));
-```
-
-```ts
-// MyOutput.vue — receiver
-const props = defineProps<{ context: ModuleContext }>();
-
-onMounted(() =>
-  props.context.bus.on("lot:selected", (payload) => {
-    // `payload` is whatever the emitter passed; type it locally if you like
-    console.log("lot picked:", payload?.id);
-  }),
-);
-onBeforeUnmount(() => props.context.bus.off("lot:selected", someHandler));
-```
-
-- `emit` with no listeners is a no-op (safe).
-- Always `off` what you `on` in `onBeforeUnmount`, or old listeners fire on remount.
-- Type the payload where you need it; the bus signature is loose by design.
-
-### 2. Imperative handles (when you must call into a sibling)
+## Rebuild
 
-For `expose/peer` — e.g. OutputCarriers telling InputCarriers to focus a lot:
-
-```ts
-// MyInput.vue — publisher
-const handle = {
-  focusLot(id: string) {
-    /* imperative action inside InputCarriers */
-  },
-};
-onMounted(() => props.context.bus.expose("inputCarriers", handle));
-onUnmounted(() => props.context.bus.release("inputCarriers"));
+```bash
+cd resources
+npm install
+npm run build
 ```
 
-```ts
-// MyOutput.vue — caller
-props.context.bus
-  .peer<{ focusLot(id: string): void }>("inputCarriers")
-  ?.focusLot("CR-01"); // always `?.` — peer returns undefined if the slot
-                        // was replaced away or hasn't mounted yet
-```
-
-### 3. Module-scope shared state (no bus needed)
-
-For pure data sync between two custom slots, a `reactive()` in a
-module-scope file also works with zero coupling:
-
-```ts
-// resources/src/custom/shared.ts
-import { reactive } from "vue";
-export const shared = reactive({ selectedLot: null as string | null });
-```
-
-```ts
-// both MyInput.vue and MyOutput.vue
-import { shared } from "./shared";
-shared.selectedLot = "CR-01"; // set in one, read in the other
-```
-
-Rule of thumb: defaults → events; only reach for `expose/peer` when the
-caller genuinely needs the peer's imperative API and accepts a
-not-yet-mounted/null risk.
-
-
-## Level 3 — full override
-
-Set `mode: "full"` and implement both entry points. The shell skips the
-built-in panel entirely.
-
-```ts
-export const customization: Customization = {
-  mode: "full",
-  mount(container, context) {
-    // render anything you want into `container`
-  },
-  unmount() {
-    // tear down your renderer
-  },
-};
-```
-
-## Styling
-
-The built-in styles are bundled into `modules.js`, so no separate CSS asset
-is required. Slot components can reuse the built-in `aiaji-*` classes and the
-`--aia-*` CSS variables (`--aia-text`, `--aia-border`, `--aia-accent`), or
-bring their own inline styles.
+For quick iteration, `npm run dev` runs `vite build --watch` and keeps
+`dist/manifest.json` valid on every rebuild.

package/templates/JobInformation/README.md

@@ -28,8 +28,16 @@ router at `/modules/JobInformation`. You receive:
 
 Everything else about how to fetch or present data is yours to implement.
 
+## 前端契约（默认面板与数据）
+
+默认面板消费模块自带两个接口：`GET /jobs`（返回每张卡片的数据，任选可选
+字段，最少 `{id, name}`）和 `GET /config`（面板显示开关 + 状态颜色/图标；缺
+失字段回退内置 `config-defaults.ts`，后端失败则显示 demo 数据）。实现这两个
+接口 + `AIAUI.start()` 即可，无需改前端文件。
+
 ## Frontend
 
+
 The frontend is organized around a small customization contract:
 
 - `resources/src/index.ts` — the stable `mount` / `unmount` bridge the host loads.
@@ -40,6 +48,11 @@ The frontend is organized around a small customization contract:
 
 Slot components also communicate through `context.bus` (events or imperative handles); see CUSTOMIZATION.md for the patterns.
 
+Slot components receive `{ context, job }`; the default layout only
+allows replacing individual regions (`header`, `inputCarriers`,
+`outputCarriers`, `timeline`, `bottom` [nested `recipe`]). Use `full` to
+replace the whole board.
+
 Three levels are supported without changing `index.ts`:
 
 1. **Default** — do nothing; the built-in panel renders.
@@ -84,16 +97,17 @@ For quick iteration, `npm run dev` runs `vite build --watch` and keeps
 Call the generated entry point from your Instance's own startup method:
 
 ```python
-from PyAIAUI import start, stop
+from PyAIAUI import AIAUI
 
 
-host = start(services={
+aiaui = AIAUI.start(services={
     "secs_server": secs_server,
     "job_repository": job_repository,
 })
+# aiaui is None when no modules are enabled
 
 # ... later, during shutdown ...
-stop()
+aiaui.stop()
 ```
 
 `start()` returns `None` when `JobInformation` is disabled in

package/templates/JobInformation/api.py

@@ -8,38 +8,57 @@ from fastapi import APIRouter
 def create_api(context) -> APIRouter:
     """Entry point invoked by the generated PyAIAUI host.
 
-    The Instance injects its live objects via ``PyAIAUI.start(services={...})``
+    The Instance injects its live objects via ``PyAIAUI.AIAUI.start(services={...})``
     and they arrive here through ``context.services``.
     """
     router = APIRouter()
 
-    @router.get("/server")
-    async def server():
-        secs_server = context.services.get("secs_server")
-        if secs_server is None:
-            return {"available": False, "name": None, "connected": None}
-        driver = getattr(secs_server, "driver", None)
-        check = getattr(driver, "is_connected", None)
-        connected = check() if callable(check) else None
-        if inspect.isawaitable(connected):
-            connected = await connected
-        return {
-            "available": True,
-            "name": getattr(secs_server, "name", None),
-            "connected": connected,
-        }
-
     @router.get("/jobs")
     async def jobs(name: str = "", page: int = 1, pageSize: int = 20):
+        """Job list for the default panel.
+
+        Each item renders one job card:
+        ``{ name, lot, state, carriers.input[]/output[], timeline[], recipe }``.
+        ``state`` drives the chip colour from ``GET /config``'s state list;
+        durations between timeline steps are computed by the frontend.
+        """
         repository = context.services.get("job_repository")
         if repository is not None:
             result = repository.list_jobs(name=name, page=page, page_size=pageSize)
             return await result if inspect.isawaitable(result) else result
 
-        # Sample data is used only until the Instance injects a repository.
+        # Fixed demo data; replace when a real repository is injected.
         items = [
-            {"id": "demo-1", "name": "DEMO-JOB-001", "state": "Running"},
-            {"id": "demo-2", "name": "DEMO-JOB-002", "state": "Queued"},
+            {
+                "id": "job-001",
+                "name": "ASM3GM-PLUGIN-JOB-001",
+                "lot": "LOT-001",
+                "state": "Executing",
+                "carriers": {"input": [{"code": "CR-01"}, {"code": "CR-02"}], "output": []},
+                "recipe": "RCP-CU-ETCH-O7",
+                "timeline": [
+                    {"label": "Setup", "at": "2026-10-18T08:00:00", "state": "done"},
+                    {"label": "Select", "at": "2026-10-18T08:01:05", "state": "done"},
+                    {"label": "WaitingForStart", "at": "2026-10-18T08:02:30", "state": "active"},
+                    {"label": "Executing", "at": "2026-10-18T08:05:12", "state": "pending"},
+                    {"label": "Complete", "at": None, "state": "pending"},
+                ],
+            },
+            {
+                "id": "job-002",
+                "name": "ASM3GM-PLUGIN-JOB-002",
+                "lot": None,
+                "state": "Setup",
+                "carriers": {"input": [], "output": []},
+                "recipe": "RCP-CU-ETCH-O7",
+                "timeline": [
+                    {"label": "Setup", "at": "2026-10-18T08:00:00", "state": "active"},
+                    {"label": "Select", "at": None, "state": "pending"},
+                    {"label": "WaitingForStart", "at": None, "state": "pending"},
+                    {"label": "Executing", "at": None, "state": "pending"},
+                    {"label": "Complete", "at": None, "state": "pending"},
+                ],
+            },
         ]
         matched = [item for item in items if name.casefold() in item["name"].casefold()]
         start = (page - 1) * pageSize
@@ -50,4 +69,29 @@ def create_api(context) -> APIRouter:
             "pageSize": pageSize,
         }
 
+    @router.get("/config")
+    async def config():
+        """Panel appearance contract: which parts to display + the state
+        colour/icon map. The template already ships a built-in default copy
+        (``config-defaults.ts``), so this endpoint can stay absent.
+        """
+        return {
+            "display": {
+                "lotId": True,
+                "recipe": True,
+                "inputCarriers": True,
+                "outputCarriers": True,
+                "timeline": True,
+            },
+            "states": [
+                {"name": "Setup", "color": "#0369a1", "icon": "clock"},
+                {"name": "Select", "color": "#526176", "icon": "list"},
+                {"name": "WaitingForStart", "color": "#8b95a5", "icon": "stop"},
+                {"name": "Executing", "color": "#1d4ed8", "icon": "activity"},
+                {"name": "Running", "color": "#1d4ed8", "icon": "activity"},
+                {"name": "Complete", "color": "#166534", "icon": "flag"},
+                {"name": "Finished", "color": "#166534", "icon": "flag"},
+            ],
+        }
+
     return router