create-windy 0.1.0

package/template/apps/server/src/data-access/context.ts

@@ -0,0 +1,162 @@
+import type { DataScope } from "@windy/shared";
+import type { GovernedExportScopeSnapshot } from "@windy/database";
+
+export interface DataAccessRolePolicy {
+  id: string;
+  code: string;
+  dataScope: DataScope;
+  departmentIds: string[];
+}
+
+const serverScopeContext = Symbol("server-scope-context");
+
+export type ScopeGrant =
+  | { scope: "all" | "tenant" }
+  | { scope: "self" }
+  | {
+      scope: "department" | "department-and-children";
+      departmentId?: string;
+    }
+  | { scope: "custom"; dimension: string; values: readonly string[] };
+
+export interface ScopeContext {
+  readonly [serverScopeContext]: true;
+  /** V1 固定单租户；保留稳定值用于后续模块 Query Specification。 */
+  readonly tenantId: "single-tenant";
+  readonly actorId: string;
+  readonly departmentId?: string;
+  readonly grants: readonly ScopeGrant[];
+  readonly roleIds: readonly string[];
+}
+
+export interface ActorScopeContexts {
+  /** 兼容既有认证与 Foundation Actor 快照。 */
+  readonly dataAccess: ScopeContext;
+  /** 服务端执行使用的不可伪造 ScopeContext。 */
+  readonly scopeContext: ScopeContext;
+}
+
+export function buildActorScopeContexts(
+  actorId: string,
+  departmentId: string | undefined,
+  roles: DataAccessRolePolicy[],
+  ownershipGrants: ReadonlyArray<Extract<ScopeGrant, { scope: "custom" }>> = [],
+): ActorScopeContexts {
+  const scopeContext = buildScopeContext(
+    actorId,
+    departmentId,
+    roles,
+    ownershipGrants,
+  );
+  return { dataAccess: scopeContext, scopeContext };
+}
+
+export function buildScopeContext(
+  actorId: string,
+  departmentId: string | undefined,
+  roles: DataAccessRolePolicy[],
+  ownershipGrants: ReadonlyArray<Extract<ScopeGrant, { scope: "custom" }>> = [],
+): ScopeContext {
+  const grants = roles.map((role): ScopeGrant => {
+    if (role.dataScope === "all" || role.dataScope === "tenant") {
+      return { scope: role.dataScope };
+    }
+    if (role.dataScope === "self") return { scope: "self" };
+    if (role.dataScope === "custom") {
+      return {
+        scope: "custom",
+        dimension: "departmentId",
+        values: unique(role.departmentIds),
+      };
+    }
+    return { scope: role.dataScope, departmentId };
+  });
+  const context = {
+    tenantId: "single-tenant",
+    actorId,
+    departmentId,
+    grants: Object.freeze(deduplicateGrants([...grants, ...ownershipGrants])),
+    roleIds: Object.freeze(unique(roles.map((role) => role.id))),
+  } as ScopeContext;
+  Object.defineProperty(context, serverScopeContext, { value: true });
+  return Object.freeze(context);
+}
+
+export function isServerScopeContext(value: unknown): value is ScopeContext {
+  return Boolean(
+    value &&
+    typeof value === "object" &&
+    (value as Record<PropertyKey, unknown>)[serverScopeContext] === true,
+  );
+}
+
+/**
+ * 仅持久化 Worker 重建 SQL Query Specification 所需的不可变范围投影。
+ * 该投影不包含 Permission、Plaintext Grant、Secret 或任何业务字段值。
+ */
+export function snapshotServerScopeContext(
+  value: unknown,
+): GovernedExportScopeSnapshot {
+  if (!isServerScopeContext(value)) {
+    throw new Error("治理任务缺少服务端 ScopeContext");
+  }
+  return structuredClone({
+    tenantId: value.tenantId,
+    actorId: value.actorId,
+    departmentId: value.departmentId,
+    grants: value.grants.map((grant) => {
+      if (grant.scope === "custom") {
+        return {
+          scope: grant.scope,
+          dimension: grant.dimension,
+          values: [...grant.values],
+        };
+      }
+      if (
+        grant.scope === "department" ||
+        grant.scope === "department-and-children"
+      ) {
+        return { scope: grant.scope, departmentId: grant.departmentId };
+      }
+      return { scope: grant.scope };
+    }),
+    roleIds: [...value.roleIds],
+  });
+}
+
+/** Worker 只从受控 Repository 读取投影并在服务端恢复 nominal context。 */
+export function restoreServerScopeContext(
+  snapshot: GovernedExportScopeSnapshot,
+): ScopeContext {
+  if (
+    snapshot.tenantId !== "single-tenant" ||
+    !snapshot.actorId.trim() ||
+    !Array.isArray(snapshot.grants) ||
+    !Array.isArray(snapshot.roleIds)
+  ) {
+    throw new Error("治理任务 ScopeContext 快照无效");
+  }
+  const context = {
+    tenantId: snapshot.tenantId,
+    actorId: snapshot.actorId,
+    departmentId: snapshot.departmentId,
+    grants: Object.freeze(structuredClone(snapshot.grants)),
+    roleIds: Object.freeze([...snapshot.roleIds]),
+  } as ScopeContext;
+  Object.defineProperty(context, serverScopeContext, { value: true });
+  return Object.freeze(context);
+}
+
+function deduplicateGrants(grants: ScopeGrant[]): ScopeGrant[] {
+  const seen = new Set<string>();
+  return grants.filter((grant) => {
+    const key = JSON.stringify(grant);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function unique(values: string[]): string[] {
+  return [...new Set(values)].sort();
+}

package/template/apps/server/src/data-access/department-tree.ts

@@ -0,0 +1,27 @@
+import type { ManagedDepartment } from "../system/entities.js";
+import type { EntityRepository } from "../system/repository.js";
+
+export function departmentDescendantResolver(
+  departments: EntityRepository<ManagedDepartment>,
+) {
+  return async (rootId: string): Promise<string[]> => {
+    const nodes = await departments.all();
+    const children = new Map<string, string[]>();
+    for (const node of nodes) {
+      if (!node.parentId) continue;
+      children.set(node.parentId, [
+        ...(children.get(node.parentId) || []),
+        node.id,
+      ]);
+    }
+    const resolved = new Set<string>();
+    const queue = [rootId];
+    while (queue.length) {
+      const id = queue.shift();
+      if (!id || resolved.has(id)) continue;
+      resolved.add(id);
+      queue.push(...(children.get(id) || []));
+    }
+    return [...resolved];
+  };
+}

package/template/apps/server/src/data-access/drizzle-predicate.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, test } from "bun:test";
+import { PgDialect, pgTable, varchar } from "drizzle-orm/pg-core";
+import {
+  compileDrizzleDataScopePredicate,
+  DataScopeBindingError,
+} from "./drizzle-predicate.js";
+import type { DataScopeQuerySpecification } from "./query-specification.js";
+
+const fixtureRecords = pgTable("fixture_records", {
+  tenantId: varchar("tenant_id", { length: 64 }),
+  ownerId: varchar("owner_id", { length: 64 }),
+  departmentId: varchar("department_id", { length: 64 }),
+  projectId: varchar("project_id", { length: 64 }),
+});
+
+describe("Drizzle data-scope predicate compiler", () => {
+  test("all 与固定单租户范围不额外限制当前租户", () => {
+    expect(compile({ branches: [{ kind: "all" }] })).toBeUndefined();
+    expect(
+      compileDrizzleDataScopePredicate(
+        specification([{ kind: "tenant", tenantId: "single-tenant" }]),
+        { tenant: { mode: "fixed", tenantId: "single-tenant" } },
+      ),
+    ).toBeUndefined();
+  });
+
+  test("本人、部门与显式 fixture projectId 维度编译为 SQL union", () => {
+    const predicate = compile({
+      branches: [
+        { kind: "owner", ownerId: "user_a" },
+        {
+          kind: "dimension",
+          dimension: "departmentId",
+          values: ["dept_a", "dept_b"],
+        },
+        {
+          kind: "dimension",
+          dimension: "projectId",
+          values: ["project_a"],
+        },
+      ],
+    });
+    const query = new PgDialect().sqlToQuery(predicate!);
+
+    expect(query.sql).toContain('"fixture_records"."owner_id" = $1');
+    expect(query.sql).toContain(
+      '"fixture_records"."department_id" in ($2, $3)',
+    );
+    expect(query.sql).toContain('"fixture_records"."project_id" in ($4)');
+    expect(query.params).toEqual(["user_a", "dept_a", "dept_b", "project_a"]);
+  });
+
+  test("无授权分支 fail closed，未绑定 ownership 维度在查询前失败", () => {
+    const denied = compile({ branches: [] });
+    expect(new PgDialect().sqlToQuery(denied!).sql).toBe("false");
+    expect(() =>
+      compileDrizzleDataScopePredicate(
+        specification([
+          {
+            kind: "dimension",
+            dimension: "projectId",
+            values: ["project_a"],
+          },
+        ]),
+        { dimensions: { departmentId: fixtureRecords.departmentId } },
+      ),
+    ).toThrow(DataScopeBindingError);
+  });
+});
+
+function compile(input: Pick<DataScopeQuerySpecification, "branches">) {
+  return compileDrizzleDataScopePredicate(specification(input.branches), {
+    tenant: { mode: "column", column: fixtureRecords.tenantId },
+    ownerId: fixtureRecords.ownerId,
+    dimensions: {
+      departmentId: fixtureRecords.departmentId,
+      projectId: fixtureRecords.projectId,
+    },
+  });
+}
+
+function specification(
+  branches: DataScopeQuerySpecification["branches"],
+): DataScopeQuerySpecification {
+  return { actorId: "user_a", branches };
+}

package/template/apps/server/src/data-access/drizzle-predicate.ts

@@ -0,0 +1,50 @@
+import { eq, inArray, or, sql, type AnyColumn, type SQL } from "drizzle-orm";
+import type { DataScopeQuerySpecification } from "./query-specification.js";
+
+export class DataScopeBindingError extends Error {}
+
+export interface DrizzleDataScopeBinding {
+  readonly ownerId?: AnyColumn;
+  readonly tenant?:
+    | { readonly mode: "column"; readonly column: AnyColumn }
+    | { readonly mode: "fixed"; readonly tenantId: string };
+  readonly dimensions?: Readonly<Record<string, AnyColumn>>;
+}
+
+export function compileDrizzleDataScopePredicate(
+  specification: DataScopeQuerySpecification,
+  binding: DrizzleDataScopeBinding,
+): SQL | undefined {
+  if (specification.branches.some(({ kind }) => kind === "all")) {
+    return undefined;
+  }
+  const predicates: SQL[] = [];
+  for (const branch of specification.branches) {
+    if (branch.kind === "tenant") {
+      const tenant = binding.tenant;
+      if (!tenant)
+        throw new DataScopeBindingError("scope binding missing tenant");
+      if (tenant.mode === "fixed") {
+        if (tenant.tenantId === branch.tenantId) return undefined;
+        continue;
+      }
+      predicates.push(eq(tenant.column, branch.tenantId));
+    }
+    if (branch.kind === "owner") {
+      if (!binding.ownerId) {
+        throw new DataScopeBindingError("scope binding missing ownerId");
+      }
+      predicates.push(eq(binding.ownerId, branch.ownerId));
+    }
+    if (branch.kind === "dimension") {
+      const column = binding.dimensions?.[branch.dimension];
+      if (!column) {
+        throw new DataScopeBindingError(
+          `scope binding missing dimension: ${branch.dimension}`,
+        );
+      }
+      if (branch.values.length) predicates.push(inArray(column, branch.values));
+    }
+  }
+  return or(...predicates) || sql<boolean>`false`;
+}

package/template/apps/server/src/data-access/errors.ts

@@ -0,0 +1,5 @@
+export class DataAccessDeniedError extends Error {
+  constructor() {
+    super("data-scope-denied");
+  }
+}

package/template/apps/server/src/data-access/platform-actor.ts

@@ -0,0 +1,25 @@
+import type { RequestActor } from "../guards.js";
+import { buildActorScopeContexts } from "./context.js";
+
+/** 仅供服务端平台任务使用；HTTP 输入不能选择或构造此 Actor。 */
+export function platformDataActor(
+  id: string,
+  name: string,
+  type: RequestActor["type"] = "service",
+): RequestActor {
+  return {
+    id,
+    type,
+    name,
+    roleCodes: ["system-data-task"],
+    permissionKeys: [],
+    ...buildActorScopeContexts(id, undefined, [
+      {
+        id: "role_system_data_task",
+        code: "system-data-task",
+        dataScope: "all",
+        departmentIds: [],
+      },
+    ]),
+  };
+}

package/template/apps/server/src/data-access/query-specification.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test } from "bun:test";
+import type { DataScope } from "@windy/shared";
+import {
+  buildScopeContext,
+  isServerScopeContext,
+  type DataAccessRolePolicy,
+} from "./context.js";
+import {
+  buildDataScopeQuerySpecification,
+  type DataScopeQueryBranch,
+} from "./query-specification.js";
+
+const departments = {
+  async descendants(id: string) {
+    return id === "dept_a" ? ["dept_a", "dept_a_child"] : [id];
+  },
+};
+
+describe("DataScope Query Specification", () => {
+  test.each([
+    ["all", [{ kind: "all" }]],
+    ["tenant", [{ kind: "tenant", tenantId: "single-tenant" }]],
+    ["self", [{ kind: "owner", ownerId: "user_a" }]],
+    [
+      "department",
+      [{ kind: "dimension", dimension: "departmentId", values: ["dept_a"] }],
+    ],
+    [
+      "department-and-children",
+      [
+        {
+          kind: "dimension",
+          dimension: "departmentId",
+          values: ["dept_a", "dept_a_child"],
+        },
+      ],
+    ],
+    [
+      "custom",
+      [{ kind: "dimension", dimension: "departmentId", values: ["dept_b"] }],
+    ],
+  ] as Array<[DataScope, DataScopeQueryBranch[]]>)(
+    "%s 范围编译为稳定查询分支",
+    async (scope, expected) => {
+      const specification = await buildDataScopeQuerySpecification(
+        buildScopeContext("user_a", "dept_a", [role(scope)]),
+        departments,
+      );
+      expect(specification.branches).toEqual(expected);
+    },
+  );
+
+  test("多角色以 union 分支表达，Core 不硬编码 fixture ownership 名称", async () => {
+    const context = buildScopeContext(
+      "user_a",
+      "dept_a",
+      [role("self"), role("department")],
+      [{ scope: "custom", dimension: "projectId", values: ["project_b"] }],
+    );
+    const specification = await buildDataScopeQuerySpecification(
+      context,
+      departments,
+    );
+
+    expect(specification.branches).toEqual([
+      { kind: "owner", ownerId: "user_a" },
+      { kind: "dimension", dimension: "departmentId", values: ["dept_a"] },
+      { kind: "dimension", dimension: "projectId", values: ["project_b"] },
+    ]);
+    expect(isServerScopeContext(context)).toBe(true);
+    expect(isServerScopeContext({ ...context })).toBe(false);
+  });
+});
+
+function role(scope: DataScope): DataAccessRolePolicy {
+  return {
+    id: `role_${scope}`,
+    code: scope,
+    dataScope: scope,
+    departmentIds: scope === "custom" ? ["dept_b"] : [],
+  };
+}

package/template/apps/server/src/data-access/query-specification.ts

@@ -0,0 +1,77 @@
+import type { ScopeContext } from "./context.js";
+
+export type DataScopeQueryBranch =
+  | { readonly kind: "all" }
+  | { readonly kind: "tenant"; readonly tenantId: string }
+  | { readonly kind: "owner"; readonly ownerId: string }
+  | {
+      readonly kind: "dimension";
+      readonly dimension: string;
+      readonly values: readonly string[];
+    };
+
+export interface DataScopeQuerySpecification {
+  readonly actorId: string;
+  readonly branches: readonly DataScopeQueryBranch[];
+}
+
+export interface DepartmentScopeResolver {
+  descendants(departmentId: string): Promise<readonly string[]>;
+}
+
+export async function buildDataScopeQuerySpecification(
+  context: ScopeContext,
+  departments: DepartmentScopeResolver,
+): Promise<DataScopeQuerySpecification> {
+  const branches: DataScopeQueryBranch[] = [];
+  for (const grant of context.grants) {
+    if (grant.scope === "all") branches.push({ kind: "all" });
+    if (grant.scope === "tenant") {
+      branches.push({ kind: "tenant", tenantId: context.tenantId });
+    }
+    if (grant.scope === "self") {
+      branches.push({ kind: "owner", ownerId: context.actorId });
+    }
+    if (grant.scope === "department" && grant.departmentId) {
+      branches.push({
+        kind: "dimension",
+        dimension: "departmentId",
+        values: [grant.departmentId],
+      });
+    }
+    if (grant.scope === "department-and-children" && grant.departmentId) {
+      branches.push({
+        kind: "dimension",
+        dimension: "departmentId",
+        values: unique(await departments.descendants(grant.departmentId)),
+      });
+    }
+    if (grant.scope === "custom" && grant.values.length) {
+      branches.push({
+        kind: "dimension",
+        dimension: grant.dimension,
+        values: unique(grant.values),
+      });
+    }
+  }
+  return {
+    actorId: context.actorId,
+    branches: deduplicateBranches(branches),
+  };
+}
+
+function deduplicateBranches(
+  branches: DataScopeQueryBranch[],
+): DataScopeQueryBranch[] {
+  const seen = new Set<string>();
+  return branches.filter((branch) => {
+    const key = JSON.stringify(branch);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function unique(values: readonly string[]): string[] {
+  return [...new Set(values)].sort();
+}