create-react-admin-template 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# create-react-admin-template
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+创建企业级 React 管理后台项目。PageForm、Table、枚举、API 生成工具等能力最终都是项目
+本地源码，不作为内部运行时 npm 包引用。
+
+## 创建项目
+
+```bash
+pnpm create react-admin-template@latest my-admin
+cd my-admin
+pnpm dev
+```
+
+默认生成精简的 `core` 项目。添加 `--profile full` 可保留完整能力；添加 `--skip-install`
+可跳过安装。项目化配置见生成项目中的 `docs/scaffold-guide.md`。
+
+也可以使用等价命令 `pnpm dlx create-react-admin-template@latest my-admin`。
+
+## 维护与发布
+
+在源码仓库内进入本包目录，直接发布：
+
+```bash
+cd packages/create-react-admin-template
+pnpm publish
+```
+
+- `prepack` 自动从根应用复制模板到本包的 `template/`，不需要手动生成发布目录。
+- `prepublishOnly` 自动运行根仓库 `pnpm verify`，其中包含真实 tarball 安装与 core/full
+  创建测试；失败即停止发布。
+- 根应用继续保持 `private: true`。模板快照不提交 Git，维护脚本不进入生成项目。
+- 发布前确认 npm 登录有效、包名归属及许可证，并保持 Git 工作区干净；不会自动绕过
+  pnpm 的 Git 检查。
+
+只验证或生成 tarball、不发布：
+
+```bash
+pnpm test:package
+pnpm pack
+```
+
+发布版本由本目录的 `package.json#version` 声明，必须与根目录
+`scaffold.template.json#strAppliedVersion` 一致，否则 `prepack` 会报错。模板升级时同步
+更新这两个版本及 `docs/template-changelog.md`；派生应用自己的版本不受影响。
+
+本包作为新名称单独发布，不会改名、撤回或自动替换已发布的旧创建器。模板 ID 保持不变，
+已生成项目不需要因为创建器改名而迁移。

package/bin/create.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { fnRunCli } from '../template/tools/scaffold/create-project.mjs'
+
+await fnRunCli()

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "create-react-admin-template",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "创建企业级 React 管理后台项目，组件与工程能力均以源码交付。",
+  "type": "module",
+  "bin": {
+    "create-react-admin-template": "bin/create.mjs"
+  },
+  "files": [
+    "bin",
+    "template"
+  ],
+  "scripts": {
+    "prepack": "node scripts/buildTemplate.mjs",
+    "prepublishOnly": "pnpm --dir ../.. verify",
+    "test:package": "node scripts/smokePackage.mjs"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.13.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/template/.dockerignore

@@ -0,0 +1,12 @@
+**
+!Dockerfile
+!deploy/
+deploy/**
+!deploy/nginx.conf
+!.artifacts/
+!.artifacts/release/
+.artifacts/release/*
+!.artifacts/release/site/
+!.artifacts/release/site/**
+!.artifacts/release/artifact-manifest.sha256
+!.artifacts/release/artifact-metadata.json

package/template/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false

package/template/.env

@@ -0,0 +1,14 @@
+# 品牌、运行模式和认证公开参数由 public/runtime-config.json 在浏览器启动时加载。
+# 所有 VITE_ 变量都会进入构建产物，请勿在此存放密钥。
+
+# Vite 开发服务器端口。
+VITE_PORT=8848
+# 本地 HTTPS 证书可在 .env.local 中按需配置；两项必须同时提供。
+VITE_DEV_HTTPS_CERT_PATH=
+VITE_DEV_HTTPS_KEY_PATH=
+
+# 部署基础路径。
+VITE_PUBLIC_PATH=/
+
+# 默认使用同源 API，由具体环境按需覆盖。
+VITE_API_PROXY=/api

package/template/.env.development

@@ -0,0 +1,5 @@
+# 开发环境后端地址，沿用参考项目的联调服务。
+VITE_API_BASE_URL=https://192.168.1.225:18084
+
+# 上游为内网自签 HTTPS 证书，dev 代理跳过 TLS 校验；目标换成证书可信的后端时改回 false
+VITE_DEV_API_INSECURE_TLS = true

package/template/.env.production

@@ -0,0 +1,2 @@
+# 生产品牌、API 与认证参数通过部署时替换 runtime-config.json，不重新构建镜像。
+VITE_DEV_API_INSECURE_TLS=false

package/template/.env.test

@@ -0,0 +1,5 @@
+# API 与 Swagger 共用的后端 origin；供 Vite 代理和 pnpm api 使用，浏览器运行时不直接读取。
+VITE_API_BASE_URL = "https://api.example.com"
+
+# 上游为内网自签 HTTPS 证书，dev 代理跳过 TLS 校验；目标换成证书可信的后端时改回 false
+VITE_DEV_API_INSECURE_TLS = true

package/template/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v6
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Install browser
+        run: pnpm exec playwright install --with-deps chromium
+
+      - name: Verify repository
+        run: pnpm verify

package/template/.gitlab-ci.yml

@@ -0,0 +1,208 @@
+variables:
+  DOCKER_BUILDKIT: '1'
+  ADMIN_PUBLIC_URL: ''
+  ADMIN_RUNTIME_CONFIG_FILE: ''
+  ADMIN_WEB_HOST_PORT: '8084'
+  ENABLE_PRODUCTION_DEPLOY: 'false'
+  RELEASE_IMAGE_TAG: '$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA'
+
+stages:
+  - verify
+  - package
+  - deploy
+
+workflow:
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+    - if: '$CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS'
+      when: never
+    - if: '$CI_COMMIT_BRANCH'
+    - when: never
+
+verify:
+  stage: verify
+  image: mcr.microsoft.com/playwright:v1.59.1-noble
+  variables:
+    HUSKY: '0'
+  cache:
+    key:
+      files:
+        - pnpm-lock.yaml
+    paths:
+      - .pnpm-store/
+  before_script:
+    - corepack enable
+    - pnpm config set store-dir .pnpm-store
+    - pnpm install --frozen-lockfile
+  script:
+    - pnpm verify
+    - pnpm security:audit
+    - pnpm release:prepare
+    - pnpm release:verify --commit "$CI_COMMIT_SHA"
+  artifacts:
+    name: 'react-admin-release-$CI_COMMIT_SHA'
+    expire_in: 7 days
+    when: on_success
+    paths:
+      - .artifacts/release/
+
+package:
+  stage: package
+  image: docker:27@sha256:aa3df78ecf320f5fafdce71c659f1629e96e9de0968305fe1de670e0ca9176ce
+  needs:
+    - job: verify
+      artifacts: true
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main" && $ENABLE_PRODUCTION_DEPLOY == "true"'
+    - when: never
+  script:
+    - |
+      tar -cf - tools/release/artifact.mjs .artifacts/release | \
+        docker run --rm -i -e CI_COMMIT_SHA="$CI_COMMIT_SHA" node:22-bookworm-slim \
+          sh -c 'mkdir /workspace && tar -C /workspace -xf - && cd /workspace && node tools/release/artifact.mjs verify --commit "$CI_COMMIT_SHA"'
+    - echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
+    - >-
+      docker build
+      --build-arg APP_COMMIT_SHA="$CI_COMMIT_SHA"
+      -t "$RELEASE_IMAGE_TAG"
+      .
+    - docker push "$RELEASE_IMAGE_TAG"
+    - RELEASE_IMAGE_DIGEST="$(docker inspect --format='{{index .RepoDigests 0}}' "$RELEASE_IMAGE_TAG")"
+    - >-
+      case "$RELEASE_IMAGE_DIGEST" in
+        "$CI_REGISTRY_IMAGE"@sha256:*) ;;
+        *) echo '无法解析不可变镜像摘要。' >&2; exit 1 ;;
+      esac
+    - printf 'RELEASE_IMAGE_DIGEST=%s\n' "$RELEASE_IMAGE_DIGEST" > release.env
+    - printf '%s\n' "$RELEASE_IMAGE_DIGEST" > release-image.txt
+  artifacts:
+    expire_in: 30 days
+    reports:
+      dotenv: release.env
+    paths:
+      - release-image.txt
+  after_script:
+    - docker logout "$CI_REGISTRY" 2>/dev/null || true
+
+deploy:
+  stage: deploy
+  image: docker:27@sha256:aa3df78ecf320f5fafdce71c659f1629e96e9de0968305fe1de670e0ca9176ce
+  needs:
+    - job: package
+      artifacts: true
+  resource_group: enterprise-react-admin-production
+  environment:
+    name: production
+    url: $ADMIN_PUBLIC_URL
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main" && $ENABLE_PRODUCTION_DEPLOY == "true"'
+      when: manual
+      allow_failure: false
+    - when: never
+  script:
+    - |
+      case "$ADMIN_PUBLIC_URL" in
+        https://*) ;;
+        *) echo 'ADMIN_PUBLIC_URL 必须使用 HTTPS。' >&2; exit 1 ;;
+      esac
+      case "$ADMIN_PUBLIC_URL" in
+        *example.com*) echo 'ADMIN_PUBLIC_URL 不能使用示例域名。' >&2; exit 1 ;;
+      esac
+      test -f "$ADMIN_RUNTIME_CONFIG_FILE" || {
+        echo 'ADMIN_RUNTIME_CONFIG_FILE 必须是 GitLab File 类型变量。' >&2
+        exit 1
+      }
+      case "$ADMIN_WEB_HOST_PORT" in
+        ''|*[!0-9]*) echo 'ADMIN_WEB_HOST_PORT 必须是有效端口。' >&2; exit 1 ;;
+      esac
+      test "$ADMIN_WEB_HOST_PORT" -ge 1 && test "$ADMIN_WEB_HOST_PORT" -le 65535 || {
+        echo 'ADMIN_WEB_HOST_PORT 必须位于 1 到 65535。' >&2
+        exit 1
+      }
+    - |
+      docker run --rm -i node:22-bookworm-slim \
+        node -e "JSON.parse(require('fs').readFileSync(0, 'utf8'))" \
+        < "$ADMIN_RUNTIME_CONFIG_FILE"
+    - echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
+    - docker pull "$RELEASE_IMAGE_DIGEST"
+    - |
+      test "$(docker inspect --format='{{index .Config.Labels "org.opencontainers.image.revision"}}' "$RELEASE_IMAGE_DIGEST")" = "$CI_COMMIT_SHA" || {
+        echo '镜像提交身份与当前流水线不一致。' >&2
+        exit 1
+      }
+    - >-
+      docker run --rm "$RELEASE_IMAGE_DIGEST"
+      sh -c 'cd /usr/share/nginx/html && sha256sum -c /opt/react-admin-release/artifact-manifest.sha256 && test ! -e runtime-config.json'
+    - >-
+      docker create
+      --name "$CI_PROJECT_NAME-candidate-${CI_COMMIT_SHORT_SHA}"
+      "$RELEASE_IMAGE_DIGEST"
+    - >-
+      docker cp
+      "$ADMIN_RUNTIME_CONFIG_FILE"
+      "$CI_PROJECT_NAME-candidate-${CI_COMMIT_SHORT_SHA}:/usr/share/nginx/html/runtime-config.json"
+    - docker start "$CI_PROJECT_NAME-candidate-${CI_COMMIT_SHORT_SHA}"
+    - >-
+      docker run --rm -i
+      --network "container:$CI_PROJECT_NAME-candidate-${CI_COMMIT_SHORT_SHA}"
+      mcr.microsoft.com/playwright:v1.59.1-noble
+      sh -s -- http://127.0.0.1/sign-in
+      < tools/deployment/browser-smoke.sh
+    - |
+      strCandidateName="$CI_PROJECT_NAME-candidate-${CI_COMMIT_SHORT_SHA}"
+      strRollbackName="$CI_PROJECT_NAME-rollback-${CI_COMMIT_SHORT_SHA}"
+      bReplacementCreated='false'
+      bPreviousRenamed='false'
+
+      if docker inspect "$strRollbackName" >/dev/null 2>&1; then
+        echo "发现未处理的回滚容器 $strRollbackName，请先核查上一次发布状态。" >&2
+        exit 1
+      fi
+
+      fnRollbackPromotion() {
+        nStatus=$?
+        trap - EXIT HUP INT TERM
+        if [ "$nStatus" -eq 0 ]; then
+          return
+        fi
+        if [ "$bReplacementCreated" = 'true' ]; then
+          docker rm -f "$CI_PROJECT_NAME" 2>/dev/null || true
+        fi
+        if [ "$bPreviousRenamed" = 'true' ]; then
+          docker rename "$strRollbackName" "$CI_PROJECT_NAME"
+          docker start "$CI_PROJECT_NAME"
+        fi
+        echo '正式发布失败，已恢复上一版容器。' >&2
+        exit "$nStatus"
+      }
+
+      trap fnRollbackPromotion EXIT HUP INT TERM
+      docker rm -f "$strCandidateName"
+
+      if docker inspect "$CI_PROJECT_NAME" >/dev/null 2>&1; then
+        docker rename "$CI_PROJECT_NAME" "$strRollbackName"
+        bPreviousRenamed='true'
+        docker stop "$strRollbackName"
+      fi
+
+      docker create \
+        --name "$CI_PROJECT_NAME" \
+        --restart unless-stopped \
+        -p "127.0.0.1:${ADMIN_WEB_HOST_PORT}:80" \
+        "$RELEASE_IMAGE_DIGEST"
+      bReplacementCreated='true'
+      docker cp \
+        "$ADMIN_RUNTIME_CONFIG_FILE" \
+        "$CI_PROJECT_NAME:/usr/share/nginx/html/runtime-config.json"
+      docker start "$CI_PROJECT_NAME"
+      wget -q --spider "$ADMIN_PUBLIC_URL/sign-in"
+
+      trap - EXIT HUP INT TERM
+      if [ "$bPreviousRenamed" = 'true' ]; then
+        docker rm -f "$strRollbackName"
+      fi
+  after_script:
+    - >-
+      docker rm -f "$CI_PROJECT_NAME-candidate-${CI_COMMIT_SHORT_SHA}"
+      2>/dev/null || true
+    - docker logout "$CI_REGISTRY" 2>/dev/null || true

package/template/.husky/commit-msg

@@ -0,0 +1 @@
+pnpm exec commitlint --edit "$1"

package/template/.husky/pre-commit

@@ -0,0 +1 @@
+pnpm exec lint-staged

package/template/.nvmrc

@@ -0,0 +1 @@
+v22.20.0

package/template/.prettierignore

@@ -0,0 +1,11 @@
+node_modules
+dist
+packages/create-react-admin-template/template
+coverage
+.vitest-attachments
+pnpm-lock.yaml
+src/api/generated
+.claude
+.gitnexus
+AGENTS.md
+CLAUDE.md

package/template/.prettierrc

@@ -0,0 +1,47 @@
+{
+  "arrowParens": "always",
+  "semi": false,
+  "tabWidth": 2,
+  "printWidth": 80,
+  "singleQuote": true,
+  "jsxSingleQuote": true,
+  "trailingComma": "es5",
+  "bracketSpacing": true,
+  "endOfLine": "lf",
+  "plugins": [
+    "@trivago/prettier-plugin-sort-imports",
+    "prettier-plugin-tailwindcss"
+  ],
+  "tailwindFunctions": ["cn", "clsx"],
+  "tailwindStylesheet": "./src/styles/index.css",
+  "importOrder": [
+    "^path$",
+    "^vite$",
+    "^@vitejs/(.*)$",
+    "^react$",
+    "^react-dom/client$",
+    "^react/(.*)$",
+    "^globals$",
+    "^zod$",
+    "^react-hook-form$",
+    "^@radix-ui/(.*)$",
+    "^@hookform/resolvers/zod$",
+    "^@tanstack/react-query$",
+    "^@tanstack/react-router$",
+    "<THIRD_PARTY_MODULES>",
+    "^@/assets/(.*)",
+    "^@/api/(.*)$",
+    "^@/stores/(.*)$",
+    "^@/lib/(.*)$",
+    "^@/utils/(.*)$",
+    "^@/constants/(.*)$",
+    "^@/context/(.*)$",
+    "^@/hooks/(.*)$",
+    "^@/components/layouts/(.*)$",
+    "^@/components/ui/(.*)$",
+    "^@/components/errors/(.*)$",
+    "^@/components/(.*)$",
+    "^@/features/(.*)$",
+    "^[./]"
+  ]
+}

package/template/Dockerfile

@@ -0,0 +1,16 @@
+# syntax=docker/dockerfile:1.20
+
+FROM nginx:stable-alpine@sha256:97d490c12ba55b4946b01546d1c3ed324e8d41ab1c9fcb2a616aa470620e5b46 AS production
+
+ARG APP_COMMIT_SHA=unknown
+
+LABEL org.opencontainers.image.revision=$APP_COMMIT_SHA
+
+COPY deploy/nginx.conf /etc/nginx/conf.d/default.conf
+COPY .artifacts/release/site /usr/share/nginx/html
+COPY .artifacts/release/artifact-manifest.sha256 /opt/react-admin-release/artifact-manifest.sha256
+COPY .artifacts/release/artifact-metadata.json /opt/react-admin-release/artifact-metadata.json
+
+RUN cd /usr/share/nginx/html \
+  && sha256sum -c /opt/react-admin-release/artifact-manifest.sha256 \
+  && test ! -e runtime-config.json