@_tc/template-core 0.0.1-bate.46 → 0.0.1-bate.48

package/.skills/tc-generator/reference/example.md

@@ -0,0 +1,357 @@
+# Complete Product CRUD Example
+
+This example creates a minimal TemplateCore business project with a product Schema CRUD page.
+
+## Structure
+
+```text
+my-admin/
+├── app/
+│   ├── controller/
+│   │   └── product.js
+│   └── router/
+│       └── product.js
+├── config/
+│   └── config.default.js
+├── model/
+│   └── product/
+│       ├── mode.js
+│       └── project/
+│           └── default.js
+└── index.js
+```
+
+## index.js
+
+```js
+const { join } = require("path");
+const { serverStart } = require("@_tc/template-core");
+const { buildFE } = require("@_tc/template-core/bundler");
+
+async function main() {
+  await serverStart({
+    name: "my-admin",
+    baseDir: join(__dirname, "."),
+  });
+
+  buildFE("dev");
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
+```
+
+## config/config.default.js
+
+```js
+module.exports = {
+  port: 9000,
+};
+```
+
+## app/controller/product.js
+
+```js
+const { baseFn } = require("@_tc/template-core");
+
+const products = [
+  {
+    product_id: "1",
+    product_name: "Product A",
+    price: 100,
+    inventory: 30,
+    status: "enabled",
+    create_time: "2026-05-18 10:00:00",
+  },
+  {
+    product_id: "2",
+    product_name: "Product B",
+    price: 199,
+    inventory: 12,
+    status: "disabled",
+    create_time: "2026-05-18 11:00:00",
+  },
+];
+
+module.exports = (app) => {
+  const BaseController = baseFn.baseControllerFn(app);
+
+  return class ProductController extends BaseController {
+    list = async (ctx) => {
+      const { product_name, status } = ctx.request.query;
+      const page = Number(ctx.request.query.page || 1);
+      const pageSize = Number(ctx.request.query.pageSize || 10);
+
+      const filtered = products.filter((item) => {
+        if (product_name && !item.product_name.includes(product_name)) return false;
+        if (status && item.status !== status) return false;
+        return true;
+      });
+
+      this.success(ctx, {
+        data: filtered.slice((page - 1) * pageSize, page * pageSize),
+        page,
+        pageSize,
+        total: filtered.length,
+      });
+    };
+
+    detail = async (ctx) => {
+      const item = products.find((product) => {
+        return product.product_id === ctx.request.query.product_id;
+      });
+
+      this.success(ctx, item || null);
+    };
+
+    create = async (ctx) => {
+      const item = {
+        ...ctx.request.body,
+        product_id: `${Date.now()}`,
+        create_time: new Date().toISOString(),
+      };
+
+      products.unshift(item);
+      this.success(ctx, item);
+    };
+
+    update = async (ctx) => {
+      const data = ctx.request.body;
+      const item = products.find((product) => product.product_id === data.product_id);
+
+      if (item) Object.assign(item, data);
+      this.success(ctx, item || data);
+    };
+
+    remove = async (ctx) => {
+      const index = products.findIndex((product) => {
+        return product.product_id === ctx.request.query.product_id;
+      });
+
+      if (index !== -1) products.splice(index, 1);
+      this.success(ctx, {});
+    };
+  };
+};
+```
+
+## app/router/product.js
+
+```js
+module.exports = (app, router) => {
+  const { product } = app.controller;
+
+  router.get("/api/product/list", product.list);
+  router.get("/api/product", product.detail);
+  router.post("/api/product", product.create);
+  router.put("/api/product", product.update);
+  router.delete("/api/product", product.remove);
+};
+```
+
+## model/product/mode.js
+
+```js
+module.exports = {
+  mode: "MB",
+  name: "Product Admin",
+  desc: "Product management example",
+  icon: "",
+  homePage: "/_sidebar_/product",
+  menu: [
+    {
+      key: "product",
+      name: "Products",
+      menuType: "module",
+      moduleType: "schema",
+      schemaConfig: {
+        api: "/api/product",
+        schema: {
+          type: "object",
+          properties: {
+            product_id: {
+              type: "string",
+              label: "Product ID",
+              tableOption: {
+                width: "180",
+              },
+              editFormOption: {
+                comType: "input",
+                disabled: true,
+              },
+              detailPanelOption: {},
+            },
+            product_name: {
+              type: "string",
+              label: "Product Name",
+              minLength: 2,
+              tableOption: {
+                width: "220",
+              },
+              searchOption: {
+                comType: "input",
+              },
+              createFormOption: {
+                comType: "input",
+              },
+              editFormOption: {
+                comType: "input",
+              },
+              detailPanelOption: {},
+            },
+            price: {
+              type: "number",
+              label: "Price",
+              tableOption: {
+                width: "120",
+                toFixed: 2,
+              },
+              createFormOption: {
+                comType: "inputNumber",
+              },
+              editFormOption: {
+                comType: "inputNumber",
+              },
+              detailPanelOption: {},
+            },
+            inventory: {
+              type: "number",
+              label: "Inventory",
+              tableOption: {
+                width: "120",
+              },
+              createFormOption: {
+                comType: "inputNumber",
+                default: 0,
+              },
+              editFormOption: {
+                comType: "inputNumber",
+              },
+              detailPanelOption: {},
+            },
+            status: {
+              type: "string",
+              label: "Status",
+              tableOption: {
+                width: "120",
+              },
+              searchOption: {
+                comType: "select",
+                options: [
+                  { label: "Enabled", value: "enabled" },
+                  { label: "Disabled", value: "disabled" },
+                ],
+              },
+              createFormOption: {
+                comType: "select",
+                default: "enabled",
+                options: [
+                  { label: "Enabled", value: "enabled" },
+                  { label: "Disabled", value: "disabled" },
+                ],
+              },
+              editFormOption: {
+                comType: "select",
+                options: [
+                  { label: "Enabled", value: "enabled" },
+                  { label: "Disabled", value: "disabled" },
+                ],
+              },
+              detailPanelOption: {
+                options: [
+                  { label: "Enabled", value: "enabled" },
+                  { label: "Disabled", value: "disabled" },
+                ],
+              },
+            },
+            create_time: {
+              type: "string",
+              label: "Created At",
+              tableOption: {
+                width: "180",
+              },
+              detailPanelOption: {},
+            },
+          },
+          required: ["product_name", "price"],
+        },
+        componentConfig: {
+          createForm: {
+            title: "Create Product",
+            saveBtnText: "Create",
+          },
+          editForm: {
+            title: "Edit Product",
+            saveBtnText: "Save",
+            fetchKey: "product_id",
+          },
+          detailPanel: {
+            title: "Product Detail",
+            fetchKey: "product_id",
+          },
+        },
+        tableConfig: {
+          headerButtons: [
+            {
+              label: "Create Product",
+              eventKey: "callComponent",
+              variant: "primary",
+              eventOption: {
+                comName: "createForm",
+              },
+            },
+          ],
+          rowButtons: [
+            {
+              label: "Edit",
+              eventKey: "callComponent",
+              eventOption: {
+                comName: "editForm",
+              },
+            },
+            {
+              label: "Detail",
+              eventKey: "callComponent",
+              eventOption: {
+                comName: "detailPanel",
+              },
+            },
+            {
+              label: "Delete",
+              eventKey: "remove",
+              eventOption: {
+                params: {
+                  product_id: "$schema::product_id",
+                },
+              },
+            },
+          ],
+        },
+      },
+    },
+  ],
+};
+```
+
+## model/product/project/default.js
+
+```js
+module.exports = {
+  name: "Default Product Project",
+  desc: "Project-level overrides can be added here.",
+};
+```
+
+## Run
+
+```bash
+node index.js
+```
+
+Open:
+
+```text
+http://localhost:9000/dash?projk=default
+```

package/.skills/tc-generator/reference/model-schema.md

@@ -0,0 +1,328 @@
+# TemplateCore Model Schema Reference
+
+## File Layout
+
+The model loader reads the business root:
+
+```text
+model/{modelKey}/mode.js
+model/{modelKey}/project/{projectKey}.js
+```
+
+`model/index.js` and `model/index.ts` are ignored.
+
+Loader output shape:
+
+```js
+[
+  {
+    model: {
+      key: "product",
+      ...modeConfig,
+    },
+    project: {
+      default: {
+        key: "default",
+        modelKey: "product",
+        ...mergedProjectConfig,
+      },
+    },
+  },
+]
+```
+
+Project config inherits the model config. Arrays are merged by stable `key`:
+
+- same `key`: recursively merge, project overrides model
+- only in model: inherited
+- only in project: appended
+
+## Top-Level Model
+
+```js
+module.exports = {
+  mode: "MB",
+  name: "Product Admin",
+  desc: "Product management",
+  icon: "",
+  homePage: "/_sidebar_/product",
+  menuLayout: "left",
+  menu: [],
+};
+```
+
+Fields:
+
+| Field | Required | Notes |
+| --- | --- | --- |
+| `mode` | yes | Currently `"MB"` for admin backend. |
+| `homePage` | no | Default page path. If omitted or not matched to a renderable menu route, Dashboard redirects to the first available menu item. |
+| `name` | no | Model display name. |
+| `desc` | no | Model description. Header title prefers `desc`, then falls back to `name`. |
+| `icon` | no | Header brand icon. Image URL/path/data image renders as a logo; plain string renders as text; omitted uses the built-in default icon. |
+| `menuLayout` | no | `"left"` default, or `"top"`. |
+| `menu` | yes | Menu tree. |
+
+For `left` layout, built-in menu routes are under `/_sidebar_/{menuKey}`. For `top` layout, built-in menu routes are `/{menuKey}`. Keep shared model `homePage` project-neutral when multiple projects inherit the same model; put project-specific query values, such as `projk`, in the project override when they differ per project.
+
+## Menu Types
+
+Group menu:
+
+```js
+{
+  key: "catalog",
+  name: "Catalog",
+  menuType: "group",
+  subMenu: [],
+}
+```
+
+Schema module:
+
+```js
+{
+  key: "product",
+  name: "Products",
+  menuType: "module",
+  moduleType: "schema",
+  schemaConfig: {},
+}
+```
+
+Custom module:
+
+```js
+{
+  key: "custom-dashboard",
+  name: "Dashboard",
+  menuType: "module",
+  moduleType: "custom",
+  customConfig: {
+    path: "/dashboard",
+  },
+}
+```
+
+Iframe module:
+
+```js
+{
+  key: "docs",
+  name: "Docs",
+  menuType: "module",
+  moduleType: "iframe",
+  iframeConfig: {
+    path: "https://example.com",
+  },
+}
+```
+
+Sidebar module is only for top menu layouts:
+
+```js
+{
+  key: "workspace",
+  name: "Workspace",
+  menuType: "module",
+  moduleType: "sidebar",
+  sidebarConfig: {
+    menuLayout: "left",
+    menu: [],
+  },
+}
+```
+
+## Schema CRUD Config
+
+Basic shape:
+
+```js
+schemaConfig: {
+  api: "/api/product",
+  schema: {
+    type: "object",
+    properties: {},
+    required: [],
+  },
+  componentConfig: {},
+  tableConfig: {},
+}
+```
+
+`api` maps to:
+
+| Action | Request |
+| --- | --- |
+| table list | `GET {api}/list` |
+| detail | `GET {api}` |
+| create | `POST {api}` |
+| update | `PUT {api}` |
+| remove | `DELETE {api}` |
+
+Table list should return:
+
+```js
+{
+  data: rows,
+  page: Number(page),
+  pageSize: Number(pageSize),
+  total: rows.length,
+}
+```
+
+Framework response wrapper is handled by `this.success(ctx, data)`.
+
+Controllers can use `app.extends.db` for simple persisted data instead of in-memory arrays. See `reference/runtime-extensions.md` for the default DB contract and override pattern.
+
+## Field Schema
+
+Each field is JSON Schema plus TemplateCore options:
+
+```js
+product_name: {
+  type: "string",
+  label: "Product Name",
+  minLength: 2,
+  tableOption: {
+    width: "220",
+  },
+  searchOption: {
+    comType: "input",
+  },
+  createFormOption: {
+    comType: "input",
+  },
+  editFormOption: {
+    comType: "input",
+  },
+  detailPanelOption: {},
+}
+```
+
+Option meaning:
+
+| Option | Render target |
+| --- | --- |
+| `tableOption` | Table column. Omit to hide from table. |
+| `searchOption` | Search form field. Omit to hide from search. |
+| `createFormOption` | Create modal form field. Omit to hide from create. |
+| `editFormOption` | Edit modal form field. Omit to hide from edit. |
+| `detailPanelOption` | Detail drawer field. Omit to hide from detail. |
+
+Common form `comType` values:
+
+```text
+input
+inputNumber
+select
+textarea
+switch
+date
+checkbox
+```
+
+Useful option fields:
+
+```js
+{
+  comType: "select",
+  default: "enabled",
+  visible: true,
+  disabled: false,
+  options: [
+    { label: "Enabled", value: "enabled" },
+    { label: "Disabled", value: "disabled" },
+  ],
+}
+```
+
+Note: the type file contains a misspelled `disbaled`, but runtime form props use `disabled` in examples and should be preferred.
+
+## Component Config
+
+Built-in call components:
+
+```js
+componentConfig: {
+  createForm: {
+    title: "Create Product",
+    saveBtnText: "Create",
+  },
+  editForm: {
+    title: "Edit Product",
+    saveBtnText: "Save",
+    fetchKey: "product_id",
+  },
+  detailPanel: {
+    title: "Product Detail",
+    fetchKey: "product_id",
+  },
+}
+```
+
+`editForm` and `detailPanel` use `fetchKey` to request detail data. Optional fetch override:
+
+```js
+fetchConfig: {
+  url: "/api/product/detail",
+  method: "get",
+}
+```
+
+## Buttons
+
+Header button opens a component:
+
+```js
+{
+  label: "Create",
+  eventKey: "callComponent",
+  variant: "primary",
+  eventOption: {
+    comName: "createForm",
+  },
+}
+```
+
+Row buttons:
+
+```js
+rowButtons: [
+  {
+    label: "Edit",
+    eventKey: "callComponent",
+    eventOption: {
+      comName: "editForm",
+    },
+  },
+  {
+    label: "Detail",
+    eventKey: "callComponent",
+    eventOption: {
+      comName: "detailPanel",
+    },
+  },
+  {
+    label: "Delete",
+    eventKey: "remove",
+    eventOption: {
+      params: {
+        product_id: "$schema::product_id",
+      },
+    },
+  },
+]
+```
+
+`$schema::product_id` reads `product_id` from the current table row.
+
+## Practical Checklist
+
+- Use `mode: "MB"`.
+- Keep every menu `key` unique and stable.
+- Use `menuType: "module"` with `moduleType: "schema"` for CRUD pages.
+- Use `schema.type: "object"` and `schema.properties`.
+- Put primary key in table/detail/edit schemas; hide it in create if generated server-side.
+- Set `required` to match create/edit validation.
+- Make backend query/body param names match schema field keys.