create-windy 0.2.5 → 0.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-windy",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "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": "ba9482c741b6e00bd3a31d5a12653db05f65eba0",
-  "generatorVersion": "0.2.5",
+  "templateCommit": "93d68f895e71560c1f85d283dce5d8b94edfd09f",
+  "generatorVersion": "0.2.7",
   "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,32 +19,47 @@ 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` 时使用内存模式。
 
 ## 页面与登录
 
+全新数据库的初始平台账号为 `admin`。初始密码不是所有项目共用的固定值，而是
+create-windy 在本机 `.env` 中随机生成的 `WINDY_BOOTSTRAP_ADMIN_PASSWORD`；该文件已
+被 Git 忽略，请在本机直接查看，不要把密码提交到仓库或复制到文档。首次登录会要求
+立即修改密码，新密码必须为 12-128 个字符，且不能与当前密码相同。
+
+`.env` 只负责全新数据库的首次初始化。账号密码写入数据库后，重启不会用环境变量
+覆盖已有密码；如果已经完成首次改密，应使用修改后的密码登录。
+
 | 路径 | 访问要求 | 说明 |
 | ---- | -------- | ---- |
 | `/login` | 公开 | 登录成功后回到安全的站内目标，默认进入 `/` |
@@ -96,6 +111,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/auth/password.ts

@@ -1,9 +1,7 @@
 import argon2, { argon2id } from "argon2";
+import { PASSWORD_POLICY } from "@windy/shared";
 
-export const PASSWORD_POLICY = {
-  minLength: 12,
-  maxLength: 128,
-} as const;
+export { PASSWORD_POLICY } from "@windy/shared";
 
 const ARGON2_OPTIONS = {
   type: argon2id,

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/components/auth/PasswordChangeForm.vue

@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import { computed, shallowRef } from "vue";
 import { KeyRoundIcon, LoaderCircleIcon } from "@lucide/vue";
+import { PASSWORD_POLICY } from "@windy/shared";
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import type { PasswordChangeInput } from "@/services/auth-api";
@@ -11,7 +12,20 @@ const emit = defineEmits<{ submit: [input: PasswordChangeInput] }>();
 const currentPassword = shallowRef("");
 const newPassword = shallowRef("");
 const confirmation = shallowRef("");
-const localError = computed(() => {
+const newPasswordError = computed(() => {
+  if (!newPassword.value) return "";
+  if (newPassword.value.length < PASSWORD_POLICY.minLength) {
+    return `新密码至少需要 ${PASSWORD_POLICY.minLength} 个字符，当前为 ${newPassword.value.length} 个。`;
+  }
+  if (newPassword.value.length > PASSWORD_POLICY.maxLength) {
+    return `新密码不能超过 ${PASSWORD_POLICY.maxLength} 个字符。`;
+  }
+  if (currentPassword.value && newPassword.value === currentPassword.value) {
+    return "新密码不能与当前密码相同。";
+  }
+  return "";
+});
+const confirmationError = computed(() => {
   if (confirmation.value && confirmation.value !== newPassword.value) {
     return "两次输入的新密码不一致";
   }
@@ -21,7 +35,9 @@ const canSubmit = computed(
   () =>
     !props.loading &&
     currentPassword.value.length > 0 &&
-    newPassword.value.length >= 12 &&
+    newPassword.value.length > 0 &&
+    !newPasswordError.value &&
+    !confirmationError.value &&
     newPassword.value === confirmation.value,
 );
 
@@ -54,12 +70,31 @@ function submit() {
         v-model="newPassword"
         type="password"
         autocomplete="new-password"
-        minlength="12"
-        maxlength="128"
+        :minlength="PASSWORD_POLICY.minLength"
+        :maxlength="PASSWORD_POLICY.maxLength"
+        :aria-describedby="
+          newPasswordError
+            ? 'new-password-help new-password-error'
+            : 'new-password-help'
+        "
+        :aria-invalid="Boolean(newPasswordError)"
         :disabled="loading"
         required
       />
-      <p class="text-xs text-muted-foreground">请输入 12-128 个字符。</p>
+      <p id="new-password-help" class="text-xs text-muted-foreground">
+        密码要求：{{ PASSWORD_POLICY.minLength }}-{{
+          PASSWORD_POLICY.maxLength
+        }}
+        个字符，且不能与当前密码相同。
+      </p>
+      <p
+        v-if="newPasswordError"
+        id="new-password-error"
+        class="text-sm text-destructive"
+        role="alert"
+      >
+        {{ newPasswordError }}
+      </p>
     </div>
     <div class="space-y-2">
       <label for="confirm-password" class="text-sm font-medium"
@@ -70,12 +105,22 @@ function submit() {
         v-model="confirmation"
         type="password"
         autocomplete="new-password"
+        :aria-describedby="confirmationError ? 'confirmation-error' : undefined"
+        :aria-invalid="Boolean(confirmationError)"
         :disabled="loading"
         required
       />
+      <p
+        v-if="confirmationError"
+        id="confirmation-error"
+        class="text-sm text-destructive"
+        role="alert"
+      >
+        {{ confirmationError }}
+      </p>
     </div>
-    <p v-if="localError || error" class="text-sm text-destructive" role="alert">
-      {{ localError || error }}
+    <p v-if="error" class="text-sm text-destructive" role="alert">
+      {{ error }}
     </p>
     <Button type="submit" class="w-full" :disabled="!canSubmit">
       <LoaderCircleIcon

package/template/apps/web/src/components/auth/PasswordChangeForm.webtest.ts

@@ -0,0 +1,43 @@
+import { mount } from "@vue/test-utils";
+import { describe, expect, test } from "vitest";
+import PasswordChangeForm from "./PasswordChangeForm.vue";
+
+describe("首次改密表单", () => {
+  test("输入过短密码时立即说明原因并保持提交禁用", async () => {
+    const wrapper = mount(PasswordChangeForm);
+
+    await wrapper.get("#current-password").setValue("initial-password");
+    await wrapper.get("#new-password").setValue("weak");
+    await wrapper.get("#confirm-password").setValue("weak");
+
+    expect(wrapper.get("[role='alert']").text()).toBe(
+      "新密码至少需要 12 个字符，当前为 4 个。",
+    );
+    expect(wrapper.get("button[type='submit']").attributes()).toHaveProperty(
+      "disabled",
+    );
+    expect(wrapper.emitted("submit")).toBeUndefined();
+  });
+
+  test("满足规则且两次一致后允许提交", async () => {
+    const wrapper = mount(PasswordChangeForm);
+
+    await wrapper.get("#current-password").setValue("initial-password");
+    await wrapper.get("#new-password").setValue("new-password-2026");
+    await wrapper.get("#confirm-password").setValue("new-password-2026");
+
+    expect(wrapper.find("[role='alert']").exists()).toBe(false);
+    expect(
+      wrapper.get("button[type='submit']").attributes("disabled"),
+    ).toBeUndefined();
+    await wrapper.get("form").trigger("submit");
+    expect(wrapper.emitted("submit")).toEqual([
+      [
+        {
+          currentPassword: "initial-password",
+          newPassword: "new-password-2026",
+        },
+      ],
+    ]);
+  });
+});

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();