create-windy 0.2.4 → 0.2.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-windy",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "创建单组织、单租户、私有部署优先的 Windy 企业 Dashboard Starter",
   "type": "module",
   "bin": {

package/template/.dockerignore

@@ -4,6 +4,7 @@
 .gitignore
 .husky
 .DS_Store
+.env
 docs
 *.log
 docker-compose*.yml

package/template/.windy-template.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "templateCommit": "d4279d35adf20612a17b6d41128ce5852bfb4116",
-  "generatorVersion": "0.2.4",
+  "templateCommit": "8b44208f73dcd5879232b3151c5344abfaeff53e",
+  "generatorVersion": "0.2.6",
   "modules": [
     {
       "name": "system",

package/template/AGENTS.md

@@ -33,6 +33,7 @@
 
 ## 常用入口
 
+- `bun run dev`：通过 Docker Compose 启动 PostgreSQL、自动 migration、Server 与 Web。
 - `bun run dev:web`：启动 Web 开发服务。
 - `bun run dev:server`：启动 Server 开发服务。
 - `bun run lint`、`bun run typecheck`、`bun run test`、`bun run build`：执行基础验证；未选择 Oxc 时没有 lint 脚本。

package/template/README.md

@@ -19,29 +19,36 @@ windy-starter 是由 create-windy 生成的单组织、单租户企业应用项
 不要使用 npm、Yarn 或 pnpm 安装本项目依赖，也不要提交它们产生的 lockfile；唯一的
 依赖锁文件是 `bun.lock`。
 
-## 第一次运行
+## 第一次运行：完整开发环境
 
 ```bash
 bun install
-cp .env.example .env
-# 为 POSTGRES_PASSWORD 和 WINDY_BOOTSTRAP_ADMIN_PASSWORD 设置本地值
-docker compose up --build
+bun run dev
 ```
 
+create-windy 已创建仅供本机使用且被 Git 忽略的 `.env`，其中两个开发密码均为随机值，
+文件权限为 `0600`。`bun run dev` 会通过 Docker Compose 等待 PostgreSQL、执行
+Drizzle migration，再启动 Server 与 Web；不要跳过 migration 后直接把 Server 连接到
+空数据库。首次启动需要本机已经安装并启动 Docker 与 Docker Compose，并可能需要下载
+基础镜像。
+
 | 服务 | 地址 |
 | ---- | ---- |
 | Web | http://localhost:9746 |
 | Server 健康检查 | http://localhost:3000/api/health |
 | PostgreSQL | localhost:5432 |
 
-Docker Web 固定使用 `9746`。只在宿主机运行 Web 时使用：
+Docker Web 固定使用 `9746`。只启动单个应用时使用：
 
 ```bash
 bun run dev:web
+bun run dev:server
 ```
 
-本地 Web 从 `8746` 开始探测。同一项目已经运行时会直接输出已有地址；其它服务占用
-时会自动使用后续端口，最多检查 100 个。实际地址始终以终端输出为准。
+`dev:web` 不会隐式启动后端；本地 Web 从 `8746` 开始探测。同一项目已经运行时会
+直接输出已有地址，其它服务占用时会自动使用后续端口，最多检查 100 个。实际地址始终
+以终端输出为准。`dev:server` 不会自动启动 PostgreSQL 或执行 migration；未配置
+`DATABASE_URL` 时使用内存模式。
 
 ## 页面与登录
 
@@ -96,6 +103,7 @@ bun run dev:web
 ## 常用命令
 
 ```bash
+bun run dev
 bun run dev:web
 bun run dev:server
 bun run typecheck

package/template/apps/server/src/persistence.ts

@@ -102,6 +102,7 @@ export function createServerPersistence(
   };
 }
 
+// @windy-module system.audit begin
 function readPositiveInteger(
   value: string | undefined,
   fallback: number,
@@ -116,3 +117,4 @@ function readSensitiveFields(value: string | undefined): string[] | undefined {
     .map((field) => field.trim())
     .filter(Boolean);
 }
+// @windy-module system.audit end

package/template/apps/web/src/composables/usePlatformSettings.ts

@@ -25,6 +25,7 @@ async function load(force = false): Promise<PlatformBrandingSettings> {
   if (!force && loaded) return branding.value;
   loading.value = true;
   error.value = "";
+  // oxlint-disable-next-line prefer-const -- 精简项目会裁剪下面的远端加载分支
   let operation = Promise.resolve(applyBranding(branding.value));
   // @windy-module system.settings begin
   operation = loadPublicBranding()
@@ -70,9 +71,11 @@ function applyBranding(next: PlatformBrandingSettings) {
   return branding.value;
 }
 
+// @windy-module system.settings begin
 function message(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
+// @windy-module system.settings end
 
 export function usePlatformSettings() {
   return {

package/template/apps/web/src/pages/ServiceUnavailablePage.vue

@@ -0,0 +1,38 @@
+<script setup lang="ts">
+import { computed } from "vue";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+
+const props = defineProps<{
+  reason: string;
+  from: string;
+}>();
+
+const message = computed(() =>
+  props.reason === "session-unavailable"
+    ? "暂时无法连接后端服务，无法确认当前登录状态。请启动或恢复后端服务后重试。"
+    : "暂时无法获取服务端数据。请确认后端服务正常运行后重试。",
+);
+</script>
+
+<template>
+  <div class="mx-auto flex min-h-96 max-w-xl items-center">
+    <Card class="w-full">
+      <CardHeader>
+        <CardTitle>后端服务暂不可用</CardTitle>
+      </CardHeader>
+      <CardContent class="space-y-4">
+        <p class="text-sm text-muted-foreground">{{ message }}</p>
+        <p class="text-xs text-muted-foreground">原请求地址：{{ from }}</p>
+        <div class="flex flex-wrap gap-3">
+          <Button as-child>
+            <RouterLink :to="from">重新连接</RouterLink>
+          </Button>
+          <Button as-child variant="outline">
+            <RouterLink to="/login">进入登录页</RouterLink>
+          </Button>
+        </div>
+      </CardContent>
+    </Card>
+  </div>
+</template>

package/template/apps/web/src/pages/system/resource-config.ts

@@ -50,7 +50,9 @@ export interface SystemResourceConfig {
   createDefaults: () => Record<string, unknown>;
 }
 
+// @windy-module system.audit begin
 const emptyDefaults = () => ({});
+// @windy-module system.audit end
 
 export const systemResourceConfigs: Record<
   SystemResourceKey,

package/template/apps/web/src/router/auth-guard.webtest.ts

@@ -0,0 +1,146 @@
+import { describe, expect, test } from "vitest";
+import { createMemoryHistory } from "vue-router";
+import { ApiError } from "@/services/http";
+import { createAppRouter } from "./index";
+import {
+  accessSnapshot,
+  authProvider,
+  // @windy-module system.license begin
+  licenseProvider,
+  // @windy-module system.license end
+  provider,
+} from "./router-test-fixtures";
+
+describe("Web 认证与服务异常导航", () => {
+  test("未认证直访受保护页面会保存安全 returnTo 并进入登录页", async () => {
+    const router = createAppRouter(
+      createMemoryHistory(),
+      provider(accessSnapshot()),
+      // @windy-module system.license begin
+      licenseProvider(),
+      // @windy-module system.license end
+      authProvider("anonymous"),
+    );
+
+    await router.push("/admin/system/users?page=2");
+
+    expect(router.currentRoute.value.name).toBe("login");
+    expect(router.currentRoute.value.query.returnTo).toBe(
+      "/admin/system/users?page=2",
+    );
+  });
+
+  test("已认证用户访问登录页只接受站内绝对 returnTo", async () => {
+    const router = createAppRouter(
+      createMemoryHistory(),
+      provider(accessSnapshot()),
+      // @windy-module system.license begin
+      licenseProvider(),
+      // @windy-module system.license end
+      authProvider(),
+    );
+
+    await router.push({
+      name: "login",
+      query: { returnTo: "https://evil.test" },
+    });
+
+    expect(router.currentRoute.value.path).toBe("/");
+  });
+
+  test("管理员重置后的账号只能进入强制改密页且不会重定向循环", async () => {
+    const session = authProvider();
+    session.actor.credentialState = "must-change-password";
+    const router = createAppRouter(
+      createMemoryHistory(),
+      provider(accessSnapshot()),
+      // @windy-module system.license begin
+      licenseProvider(),
+      // @windy-module system.license end
+      session,
+    );
+
+    await router.push("/admin/system/users");
+    expect(router.currentRoute.value.name).toBe("change-password");
+
+    await router.push("/change-password");
+    expect(router.currentRoute.value.name).toBe("change-password");
+  });
+
+  test("后端未启动时登录页仍是可恢复的公开入口", async () => {
+    const router = createAppRouter(
+      createMemoryHistory(),
+      provider(accessSnapshot()),
+      // @windy-module system.license begin
+      licenseProvider(),
+      // @windy-module system.license end
+      offlineAuthProvider(new ApiError("Bad Gateway", 502)),
+    );
+
+    await router.push("/login");
+
+    expect(router.currentRoute.value.name).toBe("login");
+    expect(router.currentRoute.value.query).toEqual({});
+  });
+
+  test("后端未启动时首页进入服务恢复页而非无权限页", async () => {
+    const router = createAppRouter(
+      createMemoryHistory(),
+      provider(accessSnapshot()),
+      // @windy-module system.license begin
+      licenseProvider(),
+      // @windy-module system.license end
+      offlineAuthProvider(new TypeError("Failed to fetch")),
+    );
+
+    await router.push("/");
+
+    expect(router.currentRoute.value.name).toBe("service-unavailable");
+    expect(router.currentRoute.value.query.reason).toBe("session-unavailable");
+    expect(router.currentRoute.value.query.from).toBe("/");
+  });
+
+  test("权限快照网络异常与 403 权限拒绝使用不同页面", async () => {
+    const router = createAppRouter(
+      createMemoryHistory(),
+      { refresh: async () => Promise.reject(new Error("offline")) },
+      // @windy-module system.license begin
+      licenseProvider(),
+      // @windy-module system.license end
+      authProvider(),
+    );
+
+    await router.push("/admin");
+
+    expect(router.currentRoute.value.name).toBe("service-unavailable");
+    expect(router.currentRoute.value.query).toMatchObject({
+      reason: "snapshot-unavailable",
+      from: "/admin",
+    });
+  });
+
+  // @windy-module system.license begin
+  test("License 快照 401 会清退到登录页", async () => {
+    const router = createAppRouter(
+      createMemoryHistory(),
+      provider(accessSnapshot()),
+      { refresh: async () => Promise.reject(new ApiError("expired", 401)) },
+      authProvider(),
+    );
+
+    await router.push("/admin/system/license");
+
+    expect(router.currentRoute.value.name).toBe("login");
+    expect(router.currentRoute.value.query.returnTo).toBe(
+      "/admin/system/license",
+    );
+  });
+  // @windy-module system.license end
+});
+
+function offlineAuthProvider(error: Error) {
+  return {
+    ensureInitialized: async () => Promise.reject(error),
+    clear() {},
+  };
+}

package/template/apps/web/src/router/auth-navigation.webtest.ts

@@ -0,0 +1,14 @@
+import { describe, expect, test } from "vitest";
+import { safeReturnTo } from "./auth-navigation";
+
+describe("安全 returnTo", () => {
+  test("只接受应用内绝对路径并排除登录页自身", () => {
+    expect(safeReturnTo("/admin/system/users?tab=active#top")).toBe(
+      "/admin/system/users?tab=active#top",
+    );
+    expect(safeReturnTo("https://evil.test/admin/system/users")).toBe("/");
+    expect(safeReturnTo("//evil.test/admin/system/users")).toBe("/");
+    expect(safeReturnTo("/\\evil.test/admin/system/users")).toBe("/");
+    expect(safeReturnTo("/login?returnTo=/admin/system/users")).toBe("/");
+  });
+});

package/template/apps/web/src/router/index.ts

@@ -7,6 +7,7 @@ import {
 import DashboardPage from "@/pages/dashboard/DashboardPage.vue";
 import HomePage from "@/app/home/HomePage.vue";
 import AccessDeniedPage from "@/pages/AccessDeniedPage.vue";
+import ServiceUnavailablePage from "@/pages/ServiceUnavailablePage.vue";
 import LoginPage from "@/pages/auth/LoginPage.vue";
 import ChangePasswordPage from "@/pages/auth/ChangePasswordPage.vue";
 // @windy-module system.license begin
@@ -106,6 +107,16 @@ export const routes: RouteRecordRaw[] = [
     }),
     meta: { title: "无法访问", layout: "auth" },
   },
+  {
+    path: "/service-unavailable",
+    name: "service-unavailable",
+    component: ServiceUnavailablePage,
+    props: (route) => ({
+      reason: String(route.query.reason || "snapshot-unavailable"),
+      from: safeReturnTo(String(route.query.from || "/")),
+    }),
+    meta: { title: "服务暂不可用", layout: "auth", public: true },
+  },
   systemRoute("system.user", "users"),
   systemRoute("system.role", "roles"),
   systemRoute("system.department", "departments"),
@@ -157,10 +168,8 @@ export function createAppRouter(
     try {
       session = await authProvider.ensureInitialized();
     } catch {
-      return to.name === "access-denied" &&
-        to.query.reason === "session-unavailable"
-        ? true
-        : deniedRoute(to.fullPath, "session-unavailable");
+      if (to.name === "login") return true;
+      return serviceUnavailableRoute(to.fullPath, "session-unavailable");
     }
     if (to.name === "login") {
       if (session.phase !== "authenticated") return true;
@@ -191,12 +200,9 @@ export function createAppRouter(
         authProvider.clear();
         return loginRoute(to.fullPath);
       }
-      return deniedRoute(
-        to.fullPath,
-        isApiErrorStatus(error, 403)
-          ? "admin-access-denied"
-          : "snapshot-unavailable",
-      );
+      return isApiErrorStatus(error, 403)
+        ? deniedRoute(to.fullPath, "admin-access-denied")
+        : serviceUnavailableRoute(to.fullPath, "snapshot-unavailable");
     }
 
     // @windy-module system.license begin
@@ -208,7 +214,7 @@ export function createAppRouter(
         authProvider.clear();
         return loginRoute(to.fullPath);
       }
-      return deniedRoute(to.fullPath, "snapshot-unavailable");
+      return serviceUnavailableRoute(to.fullPath, "snapshot-unavailable");
     }
     if (licenseSnapshot.restricted && to.name !== "runtime-license") {
       return {
@@ -243,4 +249,12 @@ function deniedRoute(from: string, reason: string) {
   };
 }
 
+function serviceUnavailableRoute(from: string, reason: string) {
+  return {
+    name: "service-unavailable",
+    query: { from, reason },
+    replace: true,
+  };
+}
+
 export const router = createAppRouter();