@yarch/create-admin 0.1.0

package/README.md

@@ -0,0 +1,42 @@
+# @yarch/create-admin · yarch web 工程生成器
+
+> W6-W9（2026-09-03 拍板）：npm 分发 + 交互问答 + maven-archetype 式全量渲染 + 模板资产化。
+> golang 栈 `cmd/yarch-init` 的 web 对偶——模板是**声明式资产**（`{{var}}` 占位 + `archetype.json` 变量声明，不要求自身可安装），工程正确性由 CI「生成后冒烟」保证。
+
+## 创建工程（一行命令，零 clone）
+
+```bash
+# 标准路径：从 npm registry 拉取脚手架（三包已发版后即可用）——
+npm create @yarch/admin@latest ysaas-console          # 交互问答：工程名 → UI 档 → 描述 → 端口 → 代理 → GitLab 分组
+npm create @yarch/admin@latest ysaas-console -- --ui antd
+
+# 发版前/开发中（本地，等价 golang `go run ./cmd/yarch-init`）：
+node stacks/web/packages/create/bin/create-admin.mjs ysaas-console --deps file
+```
+
+工程名即一切标识（W7 标准化）：npm 包名 = registry.md 服务名，生成器强制 `^[a-z][a-z0-9-]{1,31}$` + 禁裸通用词（一-1/一-2，与 golang 侧同款校验）。
+
+## 问答变量（archetype.json 声明，渲染进目录/文件/内容）
+
+| 变量 | 问题 | 默认 |
+|---|---|---|
+| `packageName` | 工程名（= npm 包名 = registry 服务名） | 必填 |
+| `appName` | 展示名（index.html 标题） | = packageName |
+| `description` | 工程描述 | `<名>：基于 yarch web 脚手架生成的中后台工程` |
+| `port` | vite dev 端口 | 5173 |
+| `proxyTarget` | `/api/v1` 反向代理目标 | `http://localhost:8080` |
+| `yarchContractDep` / `yarchReactDep` | @yarch 底座依赖形态 | `--deps version`（默认，`^0.1.0`，标准形态）· `--deps file`（发版前本地过渡 = golang replace 行对偶） |
+
+CI 非交互：`--yes` + 全量 flags；渲染后扫描残留 `{{var}}`，有即报错（防模板与变量集漂移）。
+
+## 三档模板（templates/，W1 决策）
+
+| 档 | UI 库 |
+|---|---|
+| `admin-semi`（默认） | Semi Design（抖音系） |
+| `admin-antd` | antd（蚂蚁系） |
+| `admin-arco` | Arco Design（字节系） |
+
+## 发布（W6）
+
+推 tag `stacks/web/vX.Y.Z` 触发 [web-publish.yml](../../../.github/workflows/web-publish.yml)：发版前跑契约断言 + 依赖机检，随后按 contract → react → create 顺序发布三包（幂等：registry 已有同版本则跳过；需仓库 Secret `NPM_TOKEN`）——**golang「tag → module proxy」的 npm 对偶**。发布前自检：`pnpm --filter <包名> pack --dry-run`。

package/bin/create-admin.mjs

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+// @yarch/create-admin 工程生成器（W6-W9）—— maven archetype / cookiecutter 模式的 web 对偶，
+// 与 golang cmd/yarch-init 同构：
+//   模板资产（templates/admin-{semi,antd,arco}，{{var}} 占位，不要求自身可安装）
+//   + 交互问答（W7）+ 通用渲染引擎（W8：目录/文件/内容全量替换）+ archetype.json 变量声明（W9）。
+// 工程正确性由「生成后冒烟」保证（CI：生成 → install → tsc → build）。
+//
+// 用法（本仓未发版阶段，本地）：
+//
+//	node stacks/web/packages/create/bin/create-admin.mjs ysaas-console
+//	node stacks/web/packages/create/bin/create-admin.mjs ysaas-console --ui antd --yes
+//
+// @yarch/create-admin 发版后无需 clone 本仓（npm create = npm exec）：
+//
+//	npm create @yarch/admin@latest ysaas-console -- --ui semi
+
+import { readFileSync, writeFileSync, readdirSync, mkdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import readline from "node:readline/promises";
+
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const UI_TIERS = {
+  semi: "Semi Design（抖音系，默认档 W1）",
+  antd: "antd（蚂蚁系）",
+  arco: "Arco Design（字节系）",
+};
+
+const servicePattern = /^[a-z][a-z0-9-]{1,31}$/;
+// 禁裸通用词（registry.md 一-1/一-2 口径摘录，与 golang yarch-init 同款；完整表以 contract/registry.md 为准）。
+const genericWords = new Set([
+  "api", "app", "service", "server", "backend", "web", "admin",
+  "main", "common", "system", "demo", "user", "gateway",
+]);
+
+// 渲染时跳过的模板资产（变量声明不进生成物；构建产物与依赖不应存在于资产，防御性跳过）。
+const SKIP_FILES = new Set(["archetype.json"]);
+const SKIP_DIRS = new Set(["node_modules", "dist"]);
+const PLACEHOLDER = /\{\{\s*([a-zA-Z][a-zA-Z0-9]*)\s*\}\}/g;
+
+function usage() {
+  return [
+    "用法：create-admin <工程名|输出目录> [--name <名>] [--ui semi|antd|arco] [--desc <描述>]",
+    "              [--port <端口>] [--proxy <目标>] [--group <GitLab分组>] [--deps file|version]",
+    "              [--src <模板根>] [--out <目录>] [--yes]",
+    "  --yes     非交互：缺省项全走默认值（CI 用）",
+    "  --deps    @yarch 底座依赖形态：version（默认，^0.1.0，需 @yarch 已发 npm）| file（发版前本地过渡）",
+  ].join("\n");
+}
+
+function parseArgs(argv) {
+  const opts = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--yes" || a === "-y") {
+      opts.yes = true;
+    } else if (a.startsWith("--")) {
+      opts[a.slice(2)] = argv[i + 1];
+      i++;
+    } else {
+      opts._.push(a);
+    }
+  }
+  return opts;
+}
+
+function validateName(name) {
+  if (!servicePattern.test(name)) {
+    return "须过 registry.md 一-1 校验：^[a-z][a-z0-9-]{1,31}$（小写字母数字短横线，字母开头，2~32 字符）";
+  }
+  if (genericWords.has(name)) {
+    return "裸通用词禁止单独成名，须带项目/领域前缀或后缀消歧（如 ysaas-admin）——见 registry.md 一-2";
+  }
+  if (name.includes('"') || name.includes("\\")) {
+    return '不得包含双引号与反斜杠（要写进 package.json）';
+  }
+  return null;
+}
+
+async function askText(rl, question, { fallback = "", validate = null, optional = false } = {}) {
+  for (;;) {
+    const hint = fallback ? `（默认 ${fallback}）` : optional ? "（可空）" : "";
+    const answer = (await rl.question(`${question}${hint}: `)).trim();
+    const value = answer || fallback;
+    if (!value && !optional) {
+      console.log("  ✗ 必填，请输入");
+      continue;
+    }
+    if (value && validate) {
+      const err = validate(value);
+      if (err) {
+        console.log(`  ✗ ${err}`);
+        continue;
+      }
+    }
+    return value;
+  }
+}
+
+async function askSelect(rl, question, options, defaultIndex) {
+  console.log(question);
+  options.forEach((label, i) => console.log(`  ${i + 1}) ${label}${i === defaultIndex ? "（默认）" : ""}`));
+  for (;;) {
+    const answer = (await rl.question(`选择 [${defaultIndex + 1}]: `)).trim();
+    const idx = answer ? Number.parseInt(answer, 10) - 1 : defaultIndex;
+    if (Number.isInteger(idx) && idx >= 0 && idx < options.length) return idx;
+    console.log("  ✗ 无效选项");
+  }
+}
+
+function renderStr(text, vars) {
+  return text.replace(PLACEHOLDER, (_, key) => (key in vars ? vars[key] : `{{${key}}}`));
+}
+
+// 通用渲染引擎：遍历模板树，文件名与内容逐个 {{var}} 替换；未命中变量的占位符保留，
+// 由 render 后的残留扫描兜底报错（防模板与变量集漂移）。archetype.json 不进生成物。
+function renderTree(src, dst, vars, leftovers) {
+  let count = 0;
+  for (const entry of readdirSync(src, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      count += renderTree(join(src, entry.name), join(dst, renderStr(entry.name, vars)), vars, leftovers);
+    } else if (entry.isFile()) {
+      if (SKIP_FILES.has(entry.name)) continue;
+      const target = join(dst, renderStr(entry.name, vars));
+      mkdirSync(dirname(target), { recursive: true });
+      const rendered = renderStr(readFileSync(join(src, entry.name), "utf8"), vars);
+      for (const m of rendered.matchAll(PLACEHOLDER)) {
+        leftovers.push(`${target}: {{${m[1]}}}`);
+      }
+      writeFileSync(target, rendered);
+      count++;
+    }
+  }
+  return count;
+}
+
+function fatal(message) {
+  console.error(`create-admin: ${message}`);
+  process.exit(1);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const nameArg = args.name || (args._.length > 0 && !args._[0].startsWith("/") ? args._[0] : null);
+
+  const ui = args.ui ?? "semi";
+  if (!(ui in UI_TIERS)) fatal(`--ui 须为 ${Object.keys(UI_TIERS).join("|")}，当前：${ui}`);
+
+  const interactive = !args.yes && process.stdin.isTTY;
+  if (!nameArg && !interactive) fatal(`工程名必填（或用 --yes 走交互外模式）：\n${usage()}`);
+
+  const rl = interactive ? readline.createInterface({ input: process.stdin, output: process.stdout }) : null;
+  try {
+    let name = nameArg;
+    let description = args.desc;
+    let port = args.port;
+    let proxyTarget = args.proxy;
+    let group = args.group;
+
+    if (interactive) {
+      console.log("yarch web 工程生成器（@yarch/create-admin）\n");
+      if (!name) name = await askText(rl, "工程名（= npm 包名 = registry 服务名）", { validate: validateName });
+      else if (validateName(name)) fatal(validateName(name));
+      if (!description) {
+        description = await askText(rl, "工程描述", {
+          fallback: `${name}：基于 yarch web 脚手架生成的中后台工程`,
+          validate: (v) => (v.includes('"') || v.includes("\\") ? "不得包含双引号与反斜杠（要写进 package.json）" : null),
+        });
+      }
+      if (!port) {
+        port = await askText(rl, "dev 端口", {
+          fallback: "5173",
+          validate: (v) => (/^\d{4,5}$/.test(v) && Number(v) >= 1024 && Number(v) <= 65535 ? null : "1024~65535 的数字端口号"),
+        });
+      }
+      if (!proxyTarget) {
+        proxyTarget = await askText(rl, "API 反向代理目标（/api/v1）", {
+          fallback: "http://localhost:8080",
+          validate: (v) => (/^https?:\/\/.+/.test(v) ? null : "须为 http(s):// 开头"),
+        });
+      }
+      if (group === undefined) group = await askText(rl, "GitLab 分组（用于登记提示）", { optional: true });
+    }
+
+    if (!name) fatal(`工程名缺失。\n${usage()}`);
+    const nameErr = validateName(name);
+    if (nameErr) fatal(`工程名 ${JSON.stringify(name)} ${nameErr}`);
+    description ??= `${name}：基于 yarch web 脚手架生成的中后台工程`;
+    port ??= "5173";
+    proxyTarget ??= "http://localhost:8080";
+    group ??= "";
+    if (!/^\d{4,5}$/.test(port) || Number(port) < 1024 || Number(port) > 65535) {
+      fatal(`端口 ${port} 无效：须为 1024~65535 的数字`);
+    }
+    if (!/^https?:\/\/.+/.test(proxyTarget)) {
+      fatal(`代理目标 ${proxyTarget} 无效：须为 http(s):// 开头`);
+    }
+
+    // @yarch 底座依赖形态（W8）：version = ^0.1.0（标准形态，@yarch/contract、@yarch/react 已发 npm）；
+    // file: 绝对路径 = golang replace 行对偶（发版前本地过渡，yarch 源码变更后重跑 pnpm install 刷新）。
+    const depsMode = args.deps === "file" ? "file" : "version";
+    const yarchContractDep =
+      depsMode === "version" ? "^0.1.0" : `file:${resolve(PKG_ROOT, "../contract")}`;
+    const yarchReactDep = depsMode === "version" ? "^0.1.0" : `file:${resolve(PKG_ROOT, "../react")}`;
+
+    const vars = { packageName: name, appName: name, description, port, proxyTarget, yarchContractDep, yarchReactDep };
+
+    const outDir = resolve(args.out || (args._.length > 0 ? args._[args._.length - 1] : name));
+    let existing;
+    try {
+      existing = readdirSync(outDir);
+    } catch {
+      existing = null; // 不存在，直接生成
+    }
+    if (existing && existing.length > 0) fatal(`输出目录 ${outDir} 非空`);
+
+    const templateDir = resolve(args.src || join(PKG_ROOT, "templates", `admin-${ui}`));
+    try {
+      readFileSync(join(templateDir, "archetype.json"));
+    } catch {
+      fatal(`模板目录不可达或缺少 archetype.json：${templateDir}（在 yarch 仓 stacks/web 下运行，或用 --src 指定）`);
+    }
+
+    const leftovers = [];
+    const n = renderTree(templateDir, outDir, vars, leftovers);
+    if (leftovers.length > 0) {
+      fatal(`模板存在未声明变量（模板与变量集漂移）：\n  ${leftovers.join("\n  ")}`);
+    }
+
+    const tierDesc = JSON.parse(readFileSync(join(templateDir, "archetype.json"), "utf8")).description;
+    const groupHint = group ? `（属主建议：${group}/${name}）` : "";
+    console.log(`✅ 已生成 ${outDir}（${n} 个文件，admin-${ui} 档）—— ${tierDesc}
+
+下一步：
+  1. cd ${outDir} && pnpm install && pnpm dev        # http://localhost:${port}
+  2. 服务名已置为 ${JSON.stringify(name)}——去 yarch 仓 contract/registry.md 登记表登记${groupHint}
+  3. @yarch 底座为 ${depsMode === "version" ? "^0.1.0 版本依赖（升级 = pnpm update @yarch/contract @yarch/react）" : "file: 本地依赖（发版前过渡；正式发版后改用默认 version 形态重新生成或手动替换）"}
+`);
+  } finally {
+    if (rl) rl.close();
+  }
+}
+
+main().catch((err) => fatal(err.message));

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@yarch/create-admin",
+  "version": "0.1.0",
+  "description": "yarch web 工程生成器：交互问答 + archetype 全量渲染（maven-archetype/cookiecutter 模式，golang cmd/yarch-init 的 web 对偶）",
+  "type": "module",
+  "bin": {
+    "create-admin": "./bin/create-admin.mjs"
+  },
+  "files": [
+    "bin",
+    "templates",
+    "README.md"
+  ],
+  "publishConfig": { "access": "public" },
+  "repository": { "type": "git", "url": "git+https://github.com/yuandonghao/yarch.git", "directory": "stacks/web/packages/create" },
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20"
+  }
+}

package/templates/admin-antd/README.md

@@ -0,0 +1,29 @@
+# {{appName}}
+
+> {{description}}
+>
+> 由 `@yarch/create-admin` 从 **admin-antd 档**（Vite + React + antd）生成。
+
+## 起跑
+
+```bash
+pnpm install
+pnpm dev        # http://localhost:{{port}}
+pnpm build      # tsc --noEmit + vite build
+```
+
+## 与后端联调
+
+`vite.config.ts` 已把 `/api/v1` 反代到 `{{proxyTarget}}`，改 target 即可指向你的后端。
+接口走 `@yarch/contract` 的信封解包（RestResponse / 错误码 / traceId / 401 跳转）。
+
+## 登记与升级
+
+1. **服务名登记**：`{{packageName}}` 须去 yarch 仓 `contract/registry.md` 二、服务名登记表登记（PR 即登记）；
+2. **@yarch 底座依赖**：若 package.json 中为 `^x.y.z` 版本依赖——升级底座 = `pnpm update @yarch/contract @yarch/react`；若为 `file:…` 本地路径（yarch 发版前的过渡形态）——正式发版后替换为 `^x.y.z` 并重跑 `pnpm install`。
+
+## 结构纪律（depcruise 同款口径）
+
+- `pages/` 薄入口：只组合 `features/`，不得直调 `features/*/api.ts`；
+- `ui/`、`components/` 不得反向依赖 `features/`、`pages/`；
+- 有 JSX 用 `.tsx`，纯逻辑/类型 `.ts`。

package/templates/admin-antd/archetype.json

@@ -0,0 +1,12 @@
+{
+  "description": "yarch 中后台工程模板 · antd 档（蚂蚁系）：Vite + React 19 + react-router 7 + @yarch 契约底座",
+  "variables": [
+    { "name": "packageName", "desc": "工程名（= npm 包名 = registry.md 服务名，一-1 校验）", "required": true, "default": "" },
+    { "name": "appName", "desc": "展示名（index.html 标题）", "required": false, "default": "= packageName" },
+    { "name": "description", "desc": "工程描述（package.json）", "required": false, "default": "" },
+    { "name": "port", "desc": "vite dev 端口", "required": false, "default": "5173" },
+    { "name": "proxyTarget", "desc": "/api/v1 反向代理目标", "required": false, "default": "http://localhost:8080" },
+    { "name": "yarchContractDep", "desc": "@yarch/contract 依赖（发版前 file: 本地路径，发版后 ^x.y.z）", "required": false, "default": "" },
+    { "name": "yarchReactDep", "desc": "@yarch/react 依赖（同上）", "required": false, "default": "" }
+  ]
+}

package/templates/admin-antd/index.html

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8"/>
+<title>{{appName}}</title>
+</head>
+<body>
+<div id="root"></div>
+<script type="module" src="/src/main.tsx"></script>
+</body>
+</html>

package/templates/admin-antd/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "{{packageName}}",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "description": "{{description}}",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build"
+  },
+  "dependencies": {
+    "react": "^19",
+    "react-dom": "^19",
+    "react-router-dom": "^7",
+    "@yarch/contract": "{{yarchContractDep}}",
+    "@yarch/react": "{{yarchReactDep}}",
+    "antd": "^5"
+  },
+  "devDependencies": {
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "@vitejs/plugin-react": "^4",
+    "typescript": "^5.6",
+    "vite": "^6"
+  }
+}

package/templates/admin-antd/src/app/router.tsx

@@ -0,0 +1,28 @@
+import { useNavigate, Routes, Route } from "react-router-dom";
+import { useEffect } from "react";
+import { setupReactNavigator } from "@yarch/react";
+import BasicLayout from "../layouts/basic-layout";
+import Dashboard from "../pages/dashboard";
+import Login from "../pages/login";
+import Products from "../pages/products";
+
+function NavigatorSetup() {
+  const navigate = useNavigate();
+  useEffect(() => { setupReactNavigator(navigate); }, [navigate]);
+  return null;
+}
+
+export default function App() {
+  return (
+    <>
+      <NavigatorSetup />
+      <Routes>
+        <Route path="/login" element={<Login />} />
+        <Route path="/" element={<BasicLayout />}>
+          <Route index element={<Dashboard />} />
+          <Route path="products" element={<Products />} />
+        </Route>
+      </Routes>
+    </>
+  );
+}

package/templates/admin-antd/src/components/page-container.tsx

@@ -0,0 +1,10 @@
+import type { ReactNode } from "react";
+
+export function PageContainer({ title, children }: { title: string; children: ReactNode }) {
+  return (
+    <div>
+      <h2>{title}</h2>
+      {children}
+    </div>
+  );
+}

package/templates/admin-antd/src/features/products/api.ts

@@ -0,0 +1,13 @@
+import { createClient } from "@yarch/contract";
+import type { PageData } from "@yarch/contract";
+import type { Product } from "../../types";
+import { authStore } from "../../stores/auth";
+
+const api = createClient({
+  baseUrl: "/api/v1",
+  getHeaders: () => ({ Authorization: `Bearer ${authStore.token}` }),
+});
+
+export function fetchProducts(page = 1, pageSize = 20): Promise<PageData<Product>> {
+  return api.get<PageData<Product>>(`/products?page=${page}&pageSize=${pageSize}`);
+}

package/templates/admin-antd/src/features/products/hooks/use-products.ts

@@ -0,0 +1,19 @@
+import { useCallback, useEffect, useState } from "react";
+import type { PageData } from "@yarch/contract";
+import type { Product } from "../../../types";
+import { fetchProducts } from "../api";
+
+export function useProducts() {
+  const [data, setData] = useState<PageData<Product> | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [page, setPage] = useState(1);
+
+  const load = useCallback(async (p: number) => {
+    setLoading(true); setError(null);
+    try { setData(await fetchProducts(p)); } catch (e) { setError(e as Error); } finally { setLoading(false); }
+  }, []);
+
+  useEffect(() => { load(page); }, [page, load]);
+  return { data, loading, error, page, setPage, reload: () => load(page) };
+}

package/templates/admin-antd/src/layouts/basic-layout.tsx

@@ -0,0 +1,27 @@
+import { Layout, Menu, Table, Button } from "antd";
+import { Outlet, useLocation, useNavigate } from "react-router-dom";
+
+export default function BasicLayout() {
+  const navigate = useNavigate();
+  const location = useLocation();
+  const { Sider, Header, Content } = Layout;
+
+  return (
+    <Layout style={{ minHeight: "100vh" }}>
+      <Sider>
+        <Menu selectedKeys={[location.pathname]}
+          items={[
+            { key: "/", label: "首页" },
+            { key: "/products", label: "商品" },
+          ]}
+          onClick={({ key }: { key: string }) => navigate(key)} />
+      </Sider>
+      <Layout>
+        <Header style={{ background: "#fff", padding: "0 24px" }} />
+        <Content style={{ padding: 24 }}>
+          <Outlet />
+        </Content>
+      </Layout>
+    </Layout>
+  );
+}

package/templates/admin-antd/src/main.tsx

@@ -0,0 +1,12 @@
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { BrowserRouter } from "react-router-dom";
+import App from "./app/router";
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <BrowserRouter>
+      <App />
+    </BrowserRouter>
+  </React.StrictMode>
+);

package/templates/admin-antd/src/pages/dashboard.tsx

@@ -0,0 +1,8 @@
+export default function Dashboard() {
+  return (
+    <div>
+      <h2>Dashboard</h2>
+      <p>yarch-admin (antd) — 契约 SDK 已注入</p>
+    </div>
+  );
+}

package/templates/admin-antd/src/pages/login.tsx

@@ -0,0 +1,16 @@
+import { Layout, Menu, Table, Button } from "antd";
+import { useNavigate } from "react-router-dom";
+import { authStore } from "../stores/auth";
+
+export default function Login() {
+  const navigate = useNavigate();
+  return (
+    <div style={{ display: "flex", justifyContent: "center", alignItems: "center", height: "100vh" }}>
+      <form onSubmit={(e: React.FormEvent) => { e.preventDefault(); authStore.token = "demo"; navigate("/"); }}>
+        <h2>登录</h2>
+        <p>演示——真实认证走 yarch-auth JWT</p>
+        <Button type="primary" htmlType="submit" block>登录</Button>
+      </form>
+    </div>
+  );
+}

package/templates/admin-antd/src/pages/products.tsx

@@ -0,0 +1,19 @@
+import { Layout, Menu, Table, Button } from "antd";
+import { useProducts } from "../features/products/hooks/use-products";
+
+export default function Products() {
+  const { data, loading, page, setPage } = useProducts();
+  const columns = [
+    { title: "ID", dataIndex: "id", key: "id" },
+    { title: "名称", dataIndex: "name", key: "name" },
+    { title: "价格(分)", dataIndex: "priceCents", key: "priceCents" },
+    { title: "库存", dataIndex: "stock", key: "stock" },
+  ];
+
+  return (
+    <div>
+      <h2>商品列表</h2>
+      <Table columns={columns} dataSource={data?.list ?? []} rowKey="id" loading={loading} pagination={{ current: page, total: data?.total ?? 0, onChange: setPage }} />
+    </div>
+  );
+}

package/templates/admin-antd/src/stores/auth.ts

@@ -0,0 +1,7 @@
+const TOKEN_KEY = "yarch_token";
+
+export const authStore = {
+  get token() { return localStorage.getItem(TOKEN_KEY) ?? ""; },
+  set token(v: string) { localStorage.setItem(TOKEN_KEY, v); },
+  clear() { localStorage.removeItem(TOKEN_KEY); },
+};

package/templates/admin-antd/src/types/index.ts

@@ -0,0 +1,7 @@
+export interface Product {
+  id: number;
+  name: string;
+  priceCents: number;
+  stock: number;
+  createdAt: string;
+}

package/templates/admin-antd/src/ui/theme.ts

@@ -0,0 +1,3 @@
+export const themeConfig = {
+  // antd theme tokens
+};

package/templates/admin-antd/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "jsx": "react-jsx",
+    "noEmit": true
+  },
+  "include": [
+    "src"
+  ]
+}

package/templates/admin-antd/vite.config.ts

@@ -0,0 +1,16 @@
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: {{port}},
+    proxy: {
+      // 后端 API 反向代理（对接 yarch java/golang 栈的信封接口）
+      "/api/v1": {
+        target: "{{proxyTarget}}",
+        changeOrigin: true,
+      },
+    },
+  },
+});

package/templates/admin-arco/README.md

@@ -0,0 +1,29 @@
+# {{appName}}
+
+> {{description}}
+>
+> 由 `@yarch/create-admin` 从 **admin-arco 档**（Vite + React + Arco Design）生成。
+
+## 起跑
+
+```bash
+pnpm install
+pnpm dev        # http://localhost:{{port}}
+pnpm build      # tsc --noEmit + vite build
+```
+
+## 与后端联调
+
+`vite.config.ts` 已把 `/api/v1` 反代到 `{{proxyTarget}}`，改 target 即可指向你的后端。
+接口走 `@yarch/contract` 的信封解包（RestResponse / 错误码 / traceId / 401 跳转）。
+
+## 登记与升级
+
+1. **服务名登记**：`{{packageName}}` 须去 yarch 仓 `contract/registry.md` 二、服务名登记表登记（PR 即登记）；
+2. **@yarch 底座依赖**：若 package.json 中为 `^x.y.z` 版本依赖——升级底座 = `pnpm update @yarch/contract @yarch/react`；若为 `file:…` 本地路径（yarch 发版前的过渡形态）——正式发版后替换为 `^x.y.z` 并重跑 `pnpm install`。
+
+## 结构纪律（depcruise 同款口径）
+
+- `pages/` 薄入口：只组合 `features/`，不得直调 `features/*/api.ts`；
+- `ui/`、`components/` 不得反向依赖 `features/`、`pages/`；
+- 有 JSX 用 `.tsx`，纯逻辑/类型 `.ts`。

package/templates/admin-arco/archetype.json

@@ -0,0 +1,12 @@
+{
+  "description": "yarch 中后台工程模板 · Arco 档（字节系）：Vite + React 19 + react-router 7 + @yarch 契约底座",
+  "variables": [
+    { "name": "packageName", "desc": "工程名（= npm 包名 = registry.md 服务名，一-1 校验）", "required": true, "default": "" },
+    { "name": "appName", "desc": "展示名（index.html 标题）", "required": false, "default": "= packageName" },
+    { "name": "description", "desc": "工程描述（package.json）", "required": false, "default": "" },
+    { "name": "port", "desc": "vite dev 端口", "required": false, "default": "5173" },
+    { "name": "proxyTarget", "desc": "/api/v1 反向代理目标", "required": false, "default": "http://localhost:8080" },
+    { "name": "yarchContractDep", "desc": "@yarch/contract 依赖（发版前 file: 本地路径，发版后 ^x.y.z）", "required": false, "default": "" },
+    { "name": "yarchReactDep", "desc": "@yarch/react 依赖（同上）", "required": false, "default": "" }
+  ]
+}