@pylonts/dsl 1.1.16 → 1.1.17

package/src/index.ts

@@ -31,6 +31,7 @@ export * from './aggregate.js';
 export * from './repository.js';
 export * from './domain-event.js';
 export * from './third-service.js';
+export * from './token.js';
 export * from './field-rule.js';
 export * from './exception.js';
 export * from './page.js';

package/src/mysql-driver.ts

@@ -1,109 +1,109 @@
-import { Field, rateScale } from './dsl.js';
-import { ForeignKey, Index, TableSchema } from './db.js';
-
-// MySQL driver: converts a TableSchema into a CREATE TABLE statement.
-
-/** Default value constant for created_at columns. */
-export const CURRENT_TIMESTAMP = 'CURRENT_TIMESTAMP';
-/** Default value constant for updated_at columns (with auto-update). */
-export const CURRENT_TIMESTAMP_ON_UPDATE = 'CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP';
-
-function columnType(field: Field): string {
-  switch (field.type) {
-    case 'string':
-      if (!field.maxLength) throw new Error(`field ${field.name} (string) requires maxLength`);
-      return `VARCHAR(${field.maxLength})`;
-    case 'text':
-      return 'TEXT';
-    case 'integer':
-      return 'INT';
-    case 'bigint':
-      return 'BIGINT';
-    case 'decimal':
-      return `DECIMAL(${field.precision}, ${field.scale})`;
-    case 'rate':
-      return `DECIMAL(5, ${rateScale(field.unit)})`;
-    case 'boolean':
-      return 'TINYINT(1)';
-    case 'date':
-      return 'DATE';
-    case 'time':
-      return 'TIME';
-    case 'datetime':
-      return 'DATETIME';
-    case 'enum':
-      // Enum is stored as a plain column: string -> VARCHAR(20), integer -> TINYINT.
-      return field.enum.valueType === 'integer' ? 'TINYINT' : 'VARCHAR(20)';
-    case 'json':
-      return 'JSON';
-    case 'array':
-    case 'object':
-      // Nested fields are wire-format only (third-party messages); table columns cannot nest.
-      throw new Error(`field ${field.name} (${field.type}): nested fields are not supported on table columns`);
-    case 'aggregate':
-      // Aggregate fields are query outputs, never table columns.
-      throw new Error(`field ${field.name} (aggregate): aggregate fields are not supported on table columns`);
-  }
-}
-
-function renderDefault(field: Field): string {
-  if (field.default === undefined) return '';
-  // MySQL keyword expressions (CURRENT_TIMESTAMP, CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
-  // NULL, etc.) — render bare, no quotes.
-  if (/^[A-Z]/.test(field.default)) return ` DEFAULT ${field.default}`;
-  // Numeric columns take a bare literal, not a quoted one.
-  if (field.type === 'integer' || field.type === 'bigint' || field.type === 'decimal' || field.type === 'rate' || field.type === 'boolean') {
-    return ` DEFAULT ${field.default}`;
-  }
-  return ` DEFAULT '${field.default}'`;
-}
-
-function columnDef(field: Field, autoIncrement?: Field): string {
-  const parts = [field.name, columnType(field)];
-  if (field.optional === false) parts.push('NOT NULL');
-  parts.push(renderDefault(field));
-  if (field === autoIncrement) parts.push('AUTO_INCREMENT');
-  if (field.description) parts.push(`COMMENT '${field.description.replace(/'/g, "\\'")}'`);
-  return parts.join(' ');
-}
-
-function primaryKeyClause(schema: TableSchema): string | null {
-  if (!schema.primaryKey) return null;
-  const fields = Array.isArray(schema.primaryKey) ? schema.primaryKey : [schema.primaryKey];
-  return `PRIMARY KEY (${fields.map((f) => f.name).join(', ')})`;
-}
-
-function indexClause(index: Index): string {
-  const fields = Array.isArray(index.columns) ? index.columns : [index.columns];
-  const kind = index.unique ? 'UNIQUE KEY' : 'KEY';
-  const name = index.name ?? fields.map((f) => f.name).join('_');
-  return `${kind} ${name} (${fields.map((f) => f.name).join(', ')})`;
-}
-
-function foreignKeyClause(name: string, fk: ForeignKey): string {
-  const fields = Array.isArray(fk.columns) ? fk.columns : [fk.columns];
-  const refs = Array.isArray(fk.references) ? fk.references : [fk.references];
-  const refTable = refs[0].schema?.name;
-  if (!refTable) throw new Error(`foreign key ${name}: references field has no schema`);
-  const fkCols = fields.map((f) => f.name).join(', ');
-  const refCols = refs.map((r) => r.name).join(', ');
-  return `CONSTRAINT \`${name}\` FOREIGN KEY (${fkCols}) REFERENCES \`${refTable}\` (${refCols})`;
-}
-
-export interface BuildCreateTableSqlOptions {
-  /** 是否生成外键约束，默认 false（不生成） */
-  generateForeignKeys?: boolean;
-}
-
-export function buildCreateTableSql(schema: TableSchema, options: BuildCreateTableSqlOptions = {}): string {
-  const lines = Object.values(schema.columns).map((field) => columnDef(field, schema.autoIncrement));
-  const pk = primaryKeyClause(schema);
-  if (pk) lines.push(pk);
-  for (const index of schema.indexes ?? []) lines.push(indexClause(index));
-  if (options.generateForeignKeys) {
-    for (const [name, fk] of Object.entries(schema.foreignKeys ?? {})) {
-      lines.push(foreignKeyClause(name, fk));
-    }
-  }
-  return `CREATE TABLE IF NOT EXISTS \`${schema.name}\` (\n  ${lines.join(',\n  ')}\n);`;
+import { Field, rateScale } from './dsl.js';
+import { ForeignKey, Index, TableSchema } from './db.js';
+
+// MySQL driver: converts a TableSchema into a CREATE TABLE statement.
+
+/** Default value constant for created_at columns. */
+export const CURRENT_TIMESTAMP = 'CURRENT_TIMESTAMP';
+/** Default value constant for updated_at columns (with auto-update). */
+export const CURRENT_TIMESTAMP_ON_UPDATE = 'CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP';
+
+function columnType(field: Field): string {
+  switch (field.type) {
+    case 'string':
+      if (!field.maxLength) throw new Error(`field ${field.name} (string) requires maxLength`);
+      return `VARCHAR(${field.maxLength})`;
+    case 'text':
+      return 'TEXT';
+    case 'integer':
+      return 'INT';
+    case 'bigint':
+      return 'BIGINT';
+    case 'decimal':
+      return `DECIMAL(${field.precision}, ${field.scale})`;
+    case 'rate':
+      return `DECIMAL(5, ${rateScale(field.unit)})`;
+    case 'boolean':
+      return 'TINYINT(1)';
+    case 'date':
+      return 'DATE';
+    case 'time':
+      return 'TIME';
+    case 'datetime':
+      return 'DATETIME';
+    case 'enum':
+      // Enum is stored as a plain column: string -> VARCHAR(20), integer -> TINYINT.
+      return field.enum.valueType === 'integer' ? 'TINYINT' : 'VARCHAR(20)';
+    case 'json':
+      return 'JSON';
+    case 'array':
+    case 'object':
+      // Nested fields are wire-format only (third-party messages); table columns cannot nest.
+      throw new Error(`field ${field.name} (${field.type}): nested fields are not supported on table columns`);
+    case 'aggregate':
+      // Aggregate fields are query outputs, never table columns.
+      throw new Error(`field ${field.name} (aggregate): aggregate fields are not supported on table columns`);
+  }
+}
+
+function renderDefault(field: Field): string {
+  if (field.default === undefined) return '';
+  // MySQL keyword expressions (CURRENT_TIMESTAMP / CURRENT_TIMESTAMP ON UPDATE
+  // CURRENT_TIMESTAMP) render bare; any other value is a literal and gets quoted.
+  if (field.default.startsWith(CURRENT_TIMESTAMP)) return ` DEFAULT ${field.default}`;
+  // Numeric columns take a bare literal, not a quoted one.
+  if (field.type === 'integer' || field.type === 'bigint' || field.type === 'decimal' || field.type === 'rate' || field.type === 'boolean') {
+    return ` DEFAULT ${field.default}`;
+  }
+  return ` DEFAULT '${field.default}'`;
+}
+
+function columnDef(field: Field, autoIncrement?: Field): string {
+  const parts = [field.name, columnType(field)];
+  if (field.optional === false) parts.push('NOT NULL');
+  parts.push(renderDefault(field));
+  if (field === autoIncrement) parts.push('AUTO_INCREMENT');
+  if (field.description) parts.push(`COMMENT '${field.description.replace(/'/g, "\\'")}'`);
+  return parts.join(' ');
+}
+
+function primaryKeyClause(schema: TableSchema): string | null {
+  if (!schema.primaryKey) return null;
+  const fields = Array.isArray(schema.primaryKey) ? schema.primaryKey : [schema.primaryKey];
+  return `PRIMARY KEY (${fields.map((f) => f.name).join(', ')})`;
+}
+
+function indexClause(index: Index): string {
+  const fields = Array.isArray(index.columns) ? index.columns : [index.columns];
+  const kind = index.unique ? 'UNIQUE KEY' : 'KEY';
+  const name = index.name ?? fields.map((f) => f.name).join('_');
+  return `${kind} ${name} (${fields.map((f) => f.name).join(', ')})`;
+}
+
+function foreignKeyClause(name: string, fk: ForeignKey): string {
+  const fields = Array.isArray(fk.columns) ? fk.columns : [fk.columns];
+  const refs = Array.isArray(fk.references) ? fk.references : [fk.references];
+  const refTable = refs[0].schema?.name;
+  if (!refTable) throw new Error(`foreign key ${name}: references field has no schema`);
+  const fkCols = fields.map((f) => f.name).join(', ');
+  const refCols = refs.map((r) => r.name).join(', ');
+  return `CONSTRAINT \`${name}\` FOREIGN KEY (${fkCols}) REFERENCES \`${refTable}\` (${refCols})`;
+}
+
+export interface BuildCreateTableSqlOptions {
+  /** 是否生成外键约束，默认 false（不生成） */
+  generateForeignKeys?: boolean;
+}
+
+export function buildCreateTableSql(schema: TableSchema, options: BuildCreateTableSqlOptions = {}): string {
+  const lines = Object.values(schema.columns).map((field) => columnDef(field, schema.autoIncrement));
+  const pk = primaryKeyClause(schema);
+  if (pk) lines.push(pk);
+  for (const index of schema.indexes ?? []) lines.push(indexClause(index));
+  if (options.generateForeignKeys) {
+    for (const [name, fk] of Object.entries(schema.foreignKeys ?? {})) {
+      lines.push(foreignKeyClause(name, fk));
+    }
+  }
+  return `CREATE TABLE IF NOT EXISTS \`${schema.name}\` (\n  ${lines.join(',\n  ')}\n);`;
 }

package/src/service.ts

@@ -31,6 +31,11 @@ export function defineService(options: {
   methods: Record<string, ServiceMethodDef>;
   description?: string;
 }): ServiceSchema {
+  if (!/(Service|Handler)$/.test(options.name)) {
+    throw new Error(
+      `service ${options.name}: name must end with 'Service' (or 'Handler' for handler-style services)`,
+    );
+  }
   if (options.app && !options.api.apps.includes(options.app)) {
     throw new Error(`service ${options.name}: api '${options.api.name}' does not serve app '${options.app.name}'`);
   }

package/src/third-service.ts

@@ -1,7 +1,7 @@
 import type { SchemaBase } from './dsl.js';
 import type { DtoMessage } from './dto.js';
 import type { ExceptionSchema } from './exception.js';
-import type { ThirdApiSchema } from './project.js';
+import type { ProjectApiSchema, ThirdApiSchema } from './project.js';
 
 // Third-party integration services.
 // A third-party method's args/results are plain DtoMessages — the same POJO
@@ -13,13 +13,27 @@ import type { ThirdApiSchema } from './project.js';
 /** A third-party integration service (e.g. tenpay wechat pay).
  *  Distinct from ServiceSchema (backend service bound to an app) and
  *  ThirdApiSchema (project topology: the dir the integration lives in).
- *  Describes the adapter class contract: constructor config + methods. */
+ *  Describes the adapter class contract: constructor config + methods.
+ *  `callbacks` are the inbound half — push messages the third party sends to
+ *  this platform (e.g. audit-result notify), rendered as @Public controllers. */
+/** Wire data format of the third-party gateway. 'form' (urlencoded) and
+ *  'json' are built-in in @pylonts/sandbox; any other string is a custom
+ *  format the sandbox encoder parses itself. The client and the sandbox are
+ *  mirror images of one protocol — the format declared here is the single
+ *  source both generated sides read. */
+export type ThirdServiceFormat = 'form' | 'json' | string;
+
 export interface ThirdServiceSchema extends SchemaBase {
   type: 'thirdService';
   /** The third-party system this service integrates (topology reference). */
   schema: ThirdApiSchema;
+  /** Wire data format of the gateway (see ThirdServiceFormat). Default 'json'. */
+  format?: ThirdServiceFormat;
   /** Methods keyed by name — the map key is written back as the method name. */
   methods: Record<string, ThirdServiceMethodSchema>;
+  /** Callbacks (third-party push → platform) keyed by name. Empty when the
+   *  integration is outbound-only. */
+  callbacks: Record<string, ThirdCallbackSchema>;
 }
 
 /** A method of a third-party integration service. Same contract shape as
@@ -29,6 +43,11 @@ export interface ThirdServiceSchema extends SchemaBase {
 export interface ThirdServiceMethodSchema extends SchemaBase {
   type: 'method';
   schema: ThirdServiceSchema;
+  /** Wire service name sent to the third-party gateway. Defaults to the method
+   *  key — declare explicitly when the wire value differs (e.g. camelCase key
+   *  vs snake_case wire: uploadImage → 'pic_upload'). Both the client and the
+   *  sandbox read this field, so the mirror pair stays in sync. */
+  service?: string;
   /** Input message. */
   args: DtoMessage;
   /** Output message. */
@@ -40,10 +59,59 @@ export interface ThirdServiceMethodSchema extends SchemaBase {
 /** Method input for defineThirdService: name/schema are set by the builder. */
 export type ThirdServiceMethodDef = Omit<ThirdServiceMethodSchema, 'type' | 'schema' | 'name'>;
 
+/** An inbound callback of a third-party service. The third party pushes a
+ *  payload (e.g. audit-result notify) to a platform endpoint; the platform
+ *  verifies the third party's own signature/decrypts (hand-written in the
+ *  generated controller body) and answers with `response`.
+ *  `api` selects the backend the endpoint is generated into:
+ *  {api}/src/modules/{thirdApi.name}/controller/ — the only module location
+ *  whitelisted for @Public (lint controller), because a third party never
+ *  holds an appKey. */
+export interface ThirdCallbackSchema extends SchemaBase {
+  type: 'thirdCallback';
+  schema: ThirdServiceSchema;
+  /** Backend API the callback controller is generated into. */
+  api: ProjectApiSchema;
+  /** The third-party push service name (e.g. 'apply_notify', 'alter_notify'). */
+  service: string;
+  /** Push message (third party → platform). */
+  payload: DtoMessage;
+  /** Platform answer message (platform → third party). */
+  response: DtoMessage;
+}
+
+/** Callback input for defineThirdService: name/schema are set by the builder. */
+export type ThirdCallbackDef = Omit<ThirdCallbackSchema, 'type' | 'schema' | 'name'>;
+
+/** Builds one callback entry for `defineThirdService({ callbacks })`. The
+ *  callback name (map key in the callbacks object) becomes the controller
+ *  method name; everything else is declared here. */
+export function defineThirdCallback(options: {
+  /** Backend API the callback controller is generated into. */
+  api: ProjectApiSchema;
+  /** The third-party push service name (e.g. 'apply_notify', 'alter_notify'). */
+  service: string;
+  /** Push message (third party → platform). */
+  payload: DtoMessage;
+  /** Platform answer message (platform → third party). */
+  response: DtoMessage;
+  description?: string;
+}): ThirdCallbackDef {
+  return {
+    description: options.description,
+    api: options.api,
+    service: options.service,
+    payload: options.payload,
+    response: options.response,
+  };
+}
+
 export function defineThirdService(options: {
   schema: ThirdApiSchema;
   name: string;
+  format?: ThirdServiceFormat;
   methods: Record<string, ThirdServiceMethodDef>;
+  callbacks?: Record<string, ThirdCallbackDef>;
   description?: string;
 }): ThirdServiceSchema {
   const schema: ThirdServiceSchema = {
@@ -51,7 +119,9 @@ export function defineThirdService(options: {
     name: options.name,
     description: options.description,
     schema: options.schema,
+    format: options.format,
     methods: {},
+    callbacks: {},
   };
   for (const key of Object.keys(options.methods)) {
     const method = options.methods[key];
@@ -60,10 +130,24 @@ export function defineThirdService(options: {
       name: key,
       description: method.description,
       schema,
+      service: method.service,
       args: method.args,
       results: method.results,
       throws: method.throws,
     };
   }
+  for (const key of Object.keys(options.callbacks ?? {})) {
+    const callback = options.callbacks![key];
+    schema.callbacks[key] = {
+      type: 'thirdCallback',
+      name: key,
+      description: callback.description,
+      schema,
+      api: callback.api,
+      service: callback.service,
+      payload: callback.payload,
+      response: callback.response,
+    };
+  }
   return schema;
 }

package/src/token.ts

@@ -0,0 +1,139 @@
+import type { CollectionSchemaBase, Field } from './dsl.js';
+import { stringField } from './dsl.js';
+import { dtoField } from './dto.js';
+import type { DtoField } from './dto.js';
+import type { TableSchema } from './db.js';
+import type { FrontAppSchema, ProjectApiSchema } from './project.js';
+
+// Token = the server-side user identity object (login principal), a two-state
+// object: `security` (built-in secret/cipher, present from get-token on) +
+// `identity` (projected from table columns, attached at login). The client
+// holds a pure random hash token referencing this object — never the object
+// itself. Storage: token_schema/{api.name}/{app.name}/token/{name}.token.ts
+// (one token per file), same layout as service_schema / dao_schema.
+
+/** Session-credential columns the identity table must carry (hard constraint,
+ *  decision #13): the token system writes token + refresh_token + login_at to
+ *  the account table at login/refresh time. A table missing them cannot host
+ *  an identity. */
+export const TOKEN_CREDENTIAL_COLUMNS = ['token', 'refresh_token', 'login_at'] as const;
+
+/** Built-in security-section field names: secret (signing, required) and
+ *  cipher (channel encryption, optional). Generated at get-token time and
+ *  stored in the Redis object — never backed by a table. */
+export const TOKEN_SECURITY_FIELDS = ['secret', 'cipher'] as const;
+
+export interface TokenSchema extends CollectionSchemaBase {
+  type: 'token';
+  /** The backend api module this token belongs to (shared instance from
+   *  project.config.ts apis). Tokens are always backend-side. */
+  api: ProjectApiSchema;
+  /** The frontend app this token belongs to (shared instance from
+   *  project.config). Required — an identity always belongs to one module. */
+  app: FrontAppSchema;
+  /** Security materials (present from get-token on): built-in secret
+   *  (required, signing) + cipher (optional, channel encryption). Not backed
+   *  by any table. */
+  security: Record<string, DtoField>;
+  /** Identity data (attached at login): fields projected from table columns
+   *  via from(table, ...). Every source table must carry the session
+   *  credential columns (TOKEN_CREDENTIAL_COLUMNS). */
+  identity: Record<string, DtoField>;
+}
+
+/** Built-in security section: secret (required) + cipher (optional). */
+function builtInSecurity(): Record<string, DtoField> {
+  return {
+    secret: dtoField(stringField({ minLength: 32, maxLength: 64, optional: false, label: '签名密钥' })),
+    cipher: dtoField(stringField({ optional: true, label: '加密密钥' })),
+  };
+}
+
+function validateIdentityFields(tokenName: string, identity: Record<string, DtoField>): void {
+  const sourceTables = new Set<TableSchema>();
+  for (const [key, f] of Object.entries(identity)) {
+    const source = f.field.schema;
+    if (source?.type !== 'table') {
+      throw new Error(
+        `token ${tokenName}: identity field '${key}' must be projected from a table column (from(table, ...)), got a non-column field`,
+      );
+    }
+    if ((TOKEN_SECURITY_FIELDS as readonly string[]).includes(key)) {
+      throw new Error(
+        `token ${tokenName}: identity field '${key}' collides with the built-in security field of the same name`,
+      );
+    }
+    sourceTables.add(source as TableSchema);
+  }
+  // Hard constraint (decision #13): every identity source table must carry
+  // the session credential columns — the token system writes them at
+  // login/refresh time, a table without them breaks the whole system.
+  for (const table of sourceTables) {
+    for (const col of TOKEN_CREDENTIAL_COLUMNS) {
+      if (table.columns[col] === undefined) {
+        throw new Error(
+          `token ${tokenName}: identity table '${table.name}' must contain column '${col}' (hard constraint — the token system writes session credentials to the account table)`,
+        );
+      }
+    }
+    // Identity anchor (decision): every identity source table's primary key
+    // must be fully projected into identity — a partial key cannot uniquely
+    // locate the row (composite keys project every member).
+    const pkFields: Field[] =
+      table.primaryKey === undefined
+        ? []
+        : Array.isArray(table.primaryKey)
+          ? table.primaryKey
+          : [table.primaryKey];
+    for (const pk of pkFields) {
+      const projected = Object.values(identity).some((f) => f.field === pk);
+      if (!projected) {
+        throw new Error(
+          `token ${tokenName}: identity must include the primary key column '${pk.name}' of table '${table.name}' (identity anchor — the user id is required)`,
+        );
+      }
+    }
+  }
+}
+
+/** Write back the DTO field name from the map key (same convention as
+ *  buildMessage — TokenSchema is a field container, consumers rely on
+ *  field.name). */
+function writeBackNames(segments: Record<string, DtoField>[]): void {
+  for (const segment of segments) {
+    for (const [key, df] of Object.entries(segment)) df.name = key;
+  }
+}
+
+export function defineToken(options: {
+  name: string;
+  api: ProjectApiSchema;
+  app: FrontAppSchema;
+  identity: Record<string, DtoField>;
+  description?: string;
+}): TokenSchema {
+  const { name, api, app, identity, description } = options;
+  if (!api.apps.includes(app)) {
+    throw new Error(`token ${name}: api '${api.name}' does not serve app '${app.name}'`);
+  }
+  validateIdentityFields(name, identity);
+  const security = builtInSecurity();
+  writeBackNames([security, identity]);
+  return {
+    type: 'token',
+    name,
+    description,
+    api,
+    app,
+    security,
+    identity,
+  };
+}
+
+/** Structural check — TokenSchema instances may come from a different module
+ *  copy, so instanceof is unreliable. */
+export function isTokenSchema(v: unknown): v is TokenSchema {
+  if (typeof v !== 'object' || v === null) return false;
+  const vv = v as Record<string, unknown>;
+  return vv.type === 'token' && typeof vv.name === 'string';
+}