@h-ai/cli 1.0.0-beta.2 → 1.0.0-beta.20

package/templates/apps/fullstack/packages/{{projectName}}-contract/src/admin-contract.ts.hbs

@@ -22,54 +22,145 @@ import {
 /** mini 管理示例的业务路径；四类职责与权限由应用配置，可按项目需求调整。 */
 export const adminContract = {
   permissions: {
-    list: apiContract.route({ method: 'POST', path: '/admin/permissions/list', tags: ['admin'] }).input(z.object({ page: z.number().int().min(1).default(1), pageSize: z.number().int().min(1).max(100).default(20) })).output(apiContract.haiResultSchema(z.object({ items: z.array(AdminPermissionPolicySchema), total: z.number() }))),
-    update: apiContract.route({ method: 'POST', path: '/admin/permissions/update', tags: ['admin'] }).input(AdminPermissionPolicyInputSchema).output(apiContract.haiResultSchema(z.object({ saved: z.literal(true) }))),
+    list: apiContract.route({
+      method: 'POST',
+      path: '/admin/permissions/list',
+      tags: ['admin'],
+    }).input(z.object({
+      page: z.number().int().min(1).default(1),
+      pageSize: z.number().int().min(1).max(100).default(20),
+    })).output(apiContract.haiResultSchema(z.object({
+      items: z.array(AdminPermissionPolicySchema),
+      total: z.number(),
+    }))),
+    update: apiContract.route({
+      method: 'POST',
+      path: '/admin/permissions/update',
+      tags: ['admin'],
+    }).input(AdminPermissionPolicyInputSchema).output(apiContract.haiResultSchema(z.object({
+      saved: z.literal(true),
+    }))),
   },
   configuration: {
-    get: apiContract.route({ method: 'POST', path: '/admin/configuration/get', tags: ['admin'] }).output(apiContract.haiResultSchema(BusinessSettingsSchema)),
-    update: apiContract.route({ method: 'POST', path: '/admin/configuration/update', tags: ['admin'] }).input(BusinessSettingsSchema).output(apiContract.haiResultSchema(BusinessSettingsSchema)),
+    get: apiContract.route({
+      method: 'POST',
+      path: '/admin/configuration/get',
+      tags: ['admin'],
+    }).output(apiContract.haiResultSchema(BusinessSettingsSchema)),
+    update: apiContract.route({
+      method: 'POST',
+      path: '/admin/configuration/update',
+      tags: ['admin'],
+    }).input(BusinessSettingsSchema).output(apiContract.haiResultSchema(BusinessSettingsSchema)),
   },
   users: {
-    resetPassword: apiContract.route({ method: 'POST', path: '/admin/users/reset-password', tags: ['admin'] })
+    resetPassword: apiContract.route({
+      method: 'POST',
+      path: '/admin/users/reset-password',
+      tags: ['admin'],
+    })
       .input(IamAdminResetPasswordInputSchema.strict())
-      .output(apiContract.haiResultSchema(z.object({ reset: z.literal(true) }))),
-    invite: apiContract.route({ method: 'POST', path: '/admin/users/invite', tags: ['admin'] }).input(AdminInviteUserSchema).output(apiContract.haiResultSchema(AdminUserSchema)),
-    list: apiContract.route({ method: 'POST', path: '/admin/users/list', tags: ['admin'] })
+      .output(apiContract.haiResultSchema(z.object({
+        reset: z.literal(true),
+      }))),
+    invite: apiContract.route({
+      method: 'POST',
+      path: '/admin/users/invite',
+      tags: ['admin'],
+    }).input(AdminInviteUserSchema).output(apiContract.haiResultSchema(AdminUserSchema)),
+    list: apiContract.route({
+      method: 'POST',
+      path: '/admin/users/list',
+      tags: ['admin'],
+    })
       .input(AdminUsersInputSchema)
       .output(apiContract.haiResultSchema(AdminUsersSchema)),
-    create: apiContract.route({ method: 'POST', path: '/admin/users/create', tags: ['admin'] })
+    create: apiContract.route({
+      method: 'POST',
+      path: '/admin/users/create',
+      tags: ['admin'],
+    })
       .input(AdminCreateUserSchema)
       .output(apiContract.haiResultSchema(AdminUserSchema)),
-    update: apiContract.route({ method: 'POST', path: '/admin/users/update', tags: ['admin'] })
+    update: apiContract.route({
+      method: 'POST',
+      path: '/admin/users/update',
+      tags: ['admin'],
+    })
       .input(AdminUpdateUserSchema)
       .output(apiContract.haiResultSchema(AdminUserSchema)),
-    delete: apiContract.route({ method: 'POST', path: '/admin/users/delete', tags: ['admin'] })
-      .input(z.object({ id: z.string().min(1) }).strict())
-      .output(apiContract.haiResultSchema(z.object({ deleted: z.literal(true) }))),
-    avatar: apiContract.route({ method: 'POST', path: '/admin/users/avatar', tags: ['admin'] })
-      .input(AvatarUploadSchema.extend({ id: z.string().min(1) }))
+    delete: apiContract.route({
+      method: 'POST',
+      path: '/admin/users/delete',
+      tags: ['admin'],
+    })
+      .input(z.object({
+        id: z.string().min(1),
+      }).strict())
+      .output(apiContract.haiResultSchema(z.object({
+        deleted: z.literal(true),
+      }))),
+    avatar: apiContract.route({
+      method: 'POST',
+      path: '/admin/users/avatar',
+      tags: ['admin'],
+    })
+      .input(AvatarUploadSchema.extend({
+        id: z.string().min(1),
+      }))
       .output(apiContract.haiResultSchema(AvatarOutputSchema)),
   },
   roles: {
-    list: apiContract.route({ method: 'POST', path: '/admin/roles/list', tags: ['admin'] })
-      .output(apiContract.haiResultSchema(z.object({ items: z.array(AdminRoleSchema) }))),
-    update: apiContract.route({ method: 'POST', path: '/admin/roles/update', tags: ['admin'] })
-      .input(z.object({ id: z.string().min(1), description: z.string().max(300) }).strict())
+    list: apiContract.route({
+      method: 'POST',
+      path: '/admin/roles/list',
+      tags: ['admin'],
+    })
+      .output(apiContract.haiResultSchema(z.object({
+        items: z.array(AdminRoleSchema),
+      }))),
+    update: apiContract.route({
+      method: 'POST',
+      path: '/admin/roles/update',
+      tags: ['admin'],
+    })
+      .input(z.object({
+        id: z.string().min(1),
+        description: z.string().max(300),
+      }).strict())
       .output(apiContract.haiResultSchema(AdminRoleSchema)),
   },
   audit: {
-    backup: apiContract.route({ method: 'POST', path: '/admin/audit/backup', tags: ['admin'] }).input(z.object({ id: z.uuid() }).strict()).output(apiContract.haiResultSchema(AuditBackupReceiptSchema)),
-    list: apiContract.route({ method: 'POST', path: '/admin/audit/list', tags: ['admin'] })
+    backup: apiContract.route({
+      method: 'POST',
+      path: '/admin/audit/backup',
+      tags: ['admin'],
+    }).input(z.object({
+      id: z.uuid(),
+    }).strict()).output(apiContract.haiResultSchema(AuditBackupReceiptSchema)),
+    list: apiContract.route({
+      method: 'POST',
+      path: '/admin/audit/list',
+      tags: ['admin'],
+    })
       .input(AdminAuditInputSchema)
       .output(apiContract.haiResultSchema(AdminAuditSchema)),
   },
 }
 
 export const profileContract = {
-  update: apiContract.route({ method: 'POST', path: '/profile/update', tags: ['profile'] })
+  update: apiContract.route({
+    method: 'POST',
+    path: '/profile/update',
+    tags: ['profile'],
+  })
     .input(ProfileUpdateSchema)
     .output(apiContract.haiResultSchema(AdminUserSchema)),
-  avatar: apiContract.route({ method: 'POST', path: '/profile/avatar', tags: ['profile'] })
+  avatar: apiContract.route({
+    method: 'POST',
+    path: '/profile/avatar',
+    tags: ['profile'],
+  })
     .input(AvatarUploadSchema)
     .output(apiContract.haiResultSchema(AvatarOutputSchema)),
 }

package/templates/apps/fullstack/packages/{{projectName}}-contract/src/admin-schemas.ts.hbs

@@ -2,13 +2,26 @@ import { IamListUsersInputSchema, IamPermissionSchema } from '@h-ai/api-contract
 import { z } from 'zod'
 
 /** 权限的敏感操作配置复用框架字段；职责授权仍由应用控制。 */
-export const AdminPermissionPolicySchema = IamPermissionSchema.pick({ id: true, code: true, name: true, sensitiveOperations: true })
+export const AdminPermissionPolicySchema = IamPermissionSchema.pick({
+  id: true,
+  code: true,
+  name: true,
+  sensitiveOperations: true,
+})
 export const AdminPermissionPolicyInputSchema = AdminPermissionPolicySchema.pick({ id: true, sensitiveOperations: true })
 export type AdminPermissionPolicy = z.infer<typeof AdminPermissionPolicySchema>
 
-export const BusinessSettingsSchema = z.object({ notice: z.string().trim().max(200) }).strict()
+export const BusinessSettingsSchema = z.object({
+  notice: z.string().trim().max(200),
+}).strict()
 
-export const AdminRoleCodeSchema = z.enum(['admin', 'audit_admin', 'config_admin', 'business_operator', 'user'])
+export const AdminRoleCodeSchema = z.enum([
+  'admin',
+  'audit_admin',
+  'config_admin',
+  'business_operator',
+  'user',
+])
 export const AdminPageInputSchema = z.object({
   page: z.number().int().min(1).default(1),
   pageSize: z.number().int().min(1).max(100).default(20),
@@ -49,10 +62,16 @@ export const AdminCreateUserSchema = z.object({
   accountStatus: z.enum(['active', 'dormant', 'closed']).default('active'),
   accountExpiresAt: z.string().datetime().nullable().optional(),
 }).strict()
-export const AdminInviteUserSchema = AdminCreateUserSchema.omit({ password: true }).extend({ phone: z.string().trim().min(1).max(32).optional(), accountStatus: z.literal('active').default('active') })
+export const AdminInviteUserSchema = AdminCreateUserSchema.omit({ password: true }).extend({
+  phone: z.string().trim().min(1).max(32).optional(),
+  accountStatus: z.literal('active').default('active'),
+})
 export const AdminUpdateUserSchema = z.object({
   id: z.string().min(1),
-  email: z.union([z.email(), z.literal('')]).optional(),
+  email: z.union([
+    z.email(),
+    z.literal(''),
+  ]).optional(),
   displayName: z.string().max(100).optional(),
   accountType: z.enum(['permanent', 'temporary']).optional(),
   accountStatus: z.enum(['active', 'dormant', 'closed']).optional(),
@@ -73,7 +92,14 @@ export const AdminAuditInputSchema = AdminPageInputSchema.extend({
   scopeId: z.string().max(256).optional(),
   requestId: z.string().max(256).optional(),
   traceId: z.string().max(256).optional(),
-  sortBy: z.enum(['createdAt', 'action', 'resource', 'category', 'outcome', 'severity']).optional(),
+  sortBy: z.enum([
+    'createdAt',
+    'action',
+    'resource',
+    'category',
+    'outcome',
+    'severity',
+  ]).optional(),
   sortDirection: z.enum(['asc', 'desc']).optional(),
   userId: z.string().max(100).optional(),
   action: z.string().max(50).optional(),
@@ -88,7 +114,12 @@ export const AdminAuditLogSchema = z.object({
   scopeId: z.string().nullish(),
   requestId: z.string().nullish(),
   traceId: z.string().nullish(),
-  actorSnapshot: z.object({ id: z.string(), username: z.string().optional(), displayName: z.string().optional(), roles: z.array(z.string()).optional() }).nullish(),
+  actorSnapshot: z.object({
+    id: z.string(),
+    username: z.string().optional(),
+    displayName: z.string().optional(),
+    roles: z.array(z.string()).optional(),
+  }).nullish(),
   id: z.string(),
   userId: z.string().nullable(),
   username: z.string().nullable(),
@@ -100,10 +131,20 @@ export const AdminAuditLogSchema = z.object({
   userAgent: z.string().nullable(),
   createdAt: z.string().datetime(),
 })
-export const AuditBackupReceiptSchema = z.object({ id: z.string(), key: z.string(), recordCount: z.number(), sha256: z.string(), createdAt: z.string().datetime(), cutoff: z.string().datetime() })
+export const AuditBackupReceiptSchema = z.object({
+  id: z.string(),
+  key: z.string(),
+  recordCount: z.number(),
+  sha256: z.string(),
+  createdAt: z.string().datetime(),
+  cutoff: z.string().datetime(),
+})
 export const AdminAuditSchema = z.object({
   backupEnabled: z.boolean(),
-  stats: z.array(z.object({ action: z.string(), count: z.number() })),
+  stats: z.array(z.object({
+    action: z.string(),
+    count: z.number(),
+  })),
   items: z.array(AdminAuditLogSchema),
   total: z.number(),
   page: z.number(),
@@ -111,7 +152,10 @@ export const AdminAuditSchema = z.object({
 })
 export const ProfileUpdateSchema = z.object({
   displayName: z.string().max(100).optional(),
-  email: z.union([z.email(), z.literal('')]).optional(),
+  email: z.union([
+    z.email(),
+    z.literal(''),
+  ]).optional(),
   locale: z.enum([{{#each fullstack.i18n.locales}}'{{this}}'{{#unless @last}}, {{/unless}}{{/each}}]).optional(),
   theme: z.string().min(1).max(40).regex(/^[\w-]+$/).optional(),
 }).strict()
@@ -120,7 +164,9 @@ export const AvatarUploadSchema = z.object({
   contentType: z.enum(['image/png', 'image/jpeg', 'image/webp']),
   base64: z.string().min(1).max(699052).regex(/^[A-Z\d+/]+={0,2}$/i),
 }).strict()
-export const AvatarOutputSchema = z.object({ avatarUrl: z.string().describe('Generated relative asset path') })
+export const AvatarOutputSchema = z.object({
+  avatarUrl: z.string().describe('Generated relative asset path'),
+})
 
 export type AdminUser = z.infer<typeof AdminUserSchema>
 export type AdminRole = z.infer<typeof AdminRoleSchema>

package/templates/apps/fullstack/packages/{{projectName}}-contract/tsup.config.ts.hbs

@@ -3,7 +3,9 @@ import { defineConfig } from 'tsup'
 export default defineConfig({
   entry: ['src/index.ts'],
   format: ['esm'],
-  dts: { compilerOptions: { ignoreDeprecations: '6.0' } },
+  dts: {
+    compilerOptions: { ignoreDeprecations: '6.0' },
+  },
   sourcemap: true,
   clean: true,
 })

package/templates/apps/fullstack/packages/{{projectName}}-serv/README.md.hbs

@@ -14,14 +14,23 @@
 
 ### 默认功能与配置
 
+| 操作场景 | 输入示例 | 可观察结果 |
+| --- | --- | --- |
+| 服务元信息 | 客户端app.info() | 公告、Core名称/版本/环境及启用前端列表，不下发服务端秘密 |
+| Echo演示 | app.echo({ message: 'hello' }) | 原消息、echoedAt和requestId，不写业务表 |
+| 用户/角色/个人资料 | 已认证身份及对应contract参数 | 服务端核验权限与目标，失败保持客户端草稿，成功返回明确结果 |
+| 审计/公告/反馈 | 各职责允许的筛选或处理参数 | 持久记录、私有备份回执或反馈处理状态；通知受理不等于送达 |
+
+从工程根启动本服务后，再启动所需客户端。接口地址、认证与传输按实际 `_serv.yml/_iam.yml` 配置，通过shared typed client调用并检查success。
+
 以下是可运行示例的初始实现，角色/权限、管理流程、头像限额、分页、审计策略及部署方案均可按用户需求调整。需求与代码或模板规则不一致时，以需求为业务基线同步实现、测试与过期说明；实际框架 API 契约和服务端安全校验仍需满足。
 
 - `config/_core.yml`：应用元信息（名称 / 版本 / 环境 / 语言），启动时由 `core.config` 加载。
 - `config/_serv.yml`：服务端运行时设置（CORS 来源等）。
 - `config/_db.yml` / `_cache.yml` / `_iam.yml` / `_storage.yml` / `_audit.yml` / `_reach.yml`：管理及开发通知配置，初始化前使用模块公开 Schema 验证。Reach 默认控制台 Provider，生产按注释替换为 SMTP/短信/API。
-- `config/_ai.yml` / `_vecdb.yml` / `_payment.yml` / `_scheduler.yml`：保留未启用模块的完整注释示例；配置文件存在不代表模块已接入。先在本 workspace 安装对应依赖，再在 `src/server/runtime.ts` 按公开 Schema 校验、初始化并反序关闭，接入实际业务后按需取消注释。整份注释先去掉一层外层注释，可选字段继续按需开启。
-- `src/index.ts`：进程入口，先 `core.init({ configDir: './config' })`，再初始化 reldb → cache → crypto → storage → reach（有配置时）→ audit → iam → scheduler（有任务时）；启动失败及退出反序释放。
-- 选择 AI 时自动安装 reldb/vecdb/AI，并在 reldb/cache 之后初始化 vecdb、在其余依赖之后初始化 AI；关闭时先释放 AI，最后释放 vecdb/关系库，关闭失败会返回错误并保留重试义务。生产环境必须使用共享后端，根 `.env.prod` 默认连接 Compose `db/cache/storage/vecdb`，凭据和真实 Reach Provider JSON 私有注入。
+- `config/_ai.yml` / `_vecdb.yml` / `_payment.yml` / `_kit.yml`：保留未启用模块的完整注释示例；配置文件存在不代表模块已接入。先在本 workspace 安装对应依赖，再在 `src/server/runtime.ts` 按公开 Schema 校验、初始化并反序关闭，接入实际业务后按需取消注释。整份注释先去掉一层外层注释，可选字段继续按需开启。scheduler 已用于审计任务，配置位于 `_scheduler.yml`。
+- `src/index.ts`：进程入口，通过 `src/server/runtime.ts` 先向 Core 注册各模块公开 Schema 并加载配置，再初始化 reldb → cache → crypto → storage → reach（有配置时）→ audit → iam → scheduler（有任务时）；YAML 未声明的合法可选字段同样支持细项环境变量，启动失败及退出反序释放。
+- 默认不安装 AI、vecdb、payment 和 datapipe。后续接入 AI 时安装对应依赖，在 reldb/cache 之后初始化 vecdb、在其余依赖之后初始化 AI；关闭时先释放 AI，最后释放 vecdb/关系库。生产环境必须使用共享后端，根 `.env.prod` 默认连接 Compose `db/cache/storage`，新增 vecdb 后补充共享向量库配置；凭据和真实 Reach Provider JSON 私有注入。
 - `src/app-server.ts`：服务装配入口，挂载健康检查、OpenAPI、docs 与 procedures；应用名称 / 版本与 CORS 来源均取自上述配置。
 - `src/server/procedures/app-procedures.ts`：app 领域 procedures，对应 contract 中的 `app.info` / `app.echo` 路由。
 - `src/server/procedures/admin-procedures.ts`：认证、管理员用户/角色/审计管理和个人设置，使用 `.auth()` / `.permission(...)` 守卫。每个请求读取用户最新启用状态、角色和权限。
@@ -29,7 +38,7 @@
 - `src/server/admin-service.ts`：角色分配、头像上传和审计编排，全部底层操作复用 hai 模块。初始使用 admin、audit_admin、config_admin、business_operator 和 user 五种角色，四类职责及基础成员权限由 security-roles.ts 配置；锁内重新鉴权，默认禁止管理员自删、自禁用、自降级，并补偿用户更新失败后的角色变更。业务规则可按需求替换，保留的不变量需验证并发与失败路径。
 - `tests/app-server.test.ts`：真实加密 HTTP 测试，覆盖 Cookie/受信原生刷新、RBAC、旧会话权限、并发管理操作、补偿、头像安全、偏好、审计及会话失效。
 
-CLI 已在根目录 `.env.dev/.env.test/.env.prod` 为每个环境的 admin、audit_admin、config_admin、business_operator 分别生成独立随机强密码，对应 `HAI_ADMIN_DEFAULT_PASSWORD`、`HAI_AUDIT_ADMIN_PASSWORD`、`HAI_CONFIG_ADMIN_PASSWORD`、`HAI_BUSINESS_OPERATOR_PASSWORD`。已有账号不改密或重新分配职责；未配置密码的独立职责账号不创建；`dev`/`start` 自动读取，首次登录使用用户名 `admin` 和该密码。仅在没有用户时创建管理员，不重设已有用户密码。密码不符合 `_iam.yml` 策略时，启动日志显示具体原因及错误码。环境文件随项目提交供克隆后共享；私有文件或进程变量可覆盖，`.env.example` 不含真实密码。所有业务 JSON 请求和响应强制加密；健康检查和随机路径的只读头像图片可直接访问。头像支持 PNG/JPEG/WebP，最大 512 KiB，校验内容特征和大小后由服务端生成 key，不能指定任意文件路径。
+CLI 已在根目录 `.env.dev.local/.env.test.local/.env.prod.local` 为每个环境的 admin、audit_admin、config_admin、business_operator 分别生成独立随机强密码，对应 `HAI_ADMIN_DEFAULT_PASSWORD`、`HAI_AUDIT_ADMIN_PASSWORD`、`HAI_CONFIG_ADMIN_PASSWORD`、`HAI_BUSINESS_OPERATOR_PASSWORD`。已有账号不改密或重新分配职责；未配置密码的独立职责账号不创建；`dev`/`start` 自动读取，首次登录使用用户名 `admin` 和该密码。仅在没有用户时创建管理员，不重设已有用户密码。密码不符合 `_iam.yml` 策略时，启动日志显示具体原因及错误码。这些私有文件不提交 Git，克隆后通过受保护配置分发对应环境秘密；私有文件或进程变量可覆盖，`.env.example` 不含真实密码。所有业务 JSON 请求和响应强制加密；健康检查和随机路径的只读头像图片可直接访问。头像支持 PNG/JPEG/WebP，最大 512 KiB，校验内容特征和大小后由服务端生成 key，不能指定任意文件路径。
 
 默认 SQLite + 本地 storage + memory cache 仅适合本地开发与显式测试，管理写入仅支持单写实例：进程内保护无过期时间，共享 cache 锁定期续租，丢失锁或释放失败会记录错误。多实例读取可使用共享数据库、Redis cache 和 S3 storage，但管理写请求必须统一路由到同一写实例；仅更换 Redis 不提供任意多写副本的最后管理员原子保证。传输在所有节点共享受管版本化密钥环与 registry，不依赖会话粘性；重启加载原 ring，轮换先分发新旧版本再切 activeKeyId。Web 使用 HttpOnly refresh Cookie + 内存 access token；仅同时满足客户端标识、body 通道头与受信原生 Origin 的 App/Desktop 请求返回 refresh token body。
 
@@ -37,9 +46,9 @@ CLI 已在根目录 `.env.dev/.env.test/.env.prod` 为每个环境的 admin、au
 
 ### 开发
 
-所有配置字段以模块 Schema 为准；未使用字段和替代 Provider 用注释保留。叶子环境变量只覆盖已有 YAML 路径，先取消相应键的注释，或用 `HAI_DB` / `HAI_CACHE` 等整体对象覆盖；`connectTimeout` 对应 `HAI_CACHE_CONNECTTIMEOUT`。凭据示例在根 `.env.example`，初始管理员密码和传输密钥环按环境生成到 `.env.dev/.env.test/.env.prod`；其他私有值或覆盖值保存在忽略的 `.env.local` 或部署环境。`.gitignore` 的 `**/data/` 忽略所有运行数据及 `.gitkeep`；运行时会创建目录。`crypto.init()` 无配置参数，datapipe 为纯函数，不提供虚构配置。
+所有配置字段以模块 Schema 为准；未使用字段和替代 Provider 用注释保留。宿主显式提供模块 Schema 后，合法可选路径可直接用细项配置；同源 `HAI_DB` / `HAI_CACHE` JSON 为基础，细项继续覆盖；`connectTimeout` 对应 `HAI_CACHE_CONNECTTIMEOUT`。凭据示例在根 `.env.example`，初始管理员密码和传输密钥环按环境生成到 `.env.dev.local/.env.test.local/.env.prod.local`；其他私有值或覆盖值保存在忽略的 `.env.local` 或部署环境。`.gitignore` 的 `**/data/` 忽略所有运行数据及 `.gitkeep`；运行时会创建目录。`crypto.init()` 无配置参数，datapipe 为纯函数，不提供虚构配置。
 
-CLI 同时在根 `.env.dev/.env.test/.env.prod` 分别生成独立的 `HAI_CRYPTO_TRANSPORT_SERVERKEYRING`，结构为 `{activeKeyId,keys:{id:{publicKey,privateKey}}}`，运行时不隐式生成。同一环境所有节点从环境文件加载相同 ring，也可由 Secret Manager 统一覆盖，客户端 registry 复用共享 reldb。私钥不进入普通 YAML、PUBLIC_/VITE_、日志或公开响应。轮换先分发含新旧版本的 ring，再切 activeKeyId 并滚动重建；过渡期后删除旧 ID，旧客户端 destroy 后重协商。没有 sticky session 依赖。
+CLI 同时在根 `.env.dev.local/.env.test.local/.env.prod.local` 分别生成独立的 `HAI_CRYPTO_TRANSPORT_SERVERKEYRING`，结构为 `{activeKeyId,keys:{id:{publicKey,privateKey}}}`，运行时不隐式生成。同一环境所有节点从环境文件加载相同 ring，也可由 Secret Manager 统一覆盖，客户端 registry 复用共享 reldb。私钥不进入普通 YAML、PUBLIC_/VITE_、日志或公开响应。轮换先分发含新旧版本的 ring，再切 activeKeyId 并滚动重建；过渡期后删除旧 ID，旧客户端 destroy 后重协商。没有 sticky session 依赖。
 
 自动生成的 `.env` 包含已启用模块的环境参数；YAML 显式引用相同变量并保留本地回退。使用 `start:test` / `start:prod` 加载对应环境覆盖。
 
@@ -48,11 +57,12 @@ CLI 同时在根 `.env.dev/.env.test/.env.prod` 分别生成独立的 `HAI_CRYPT
 
 ### 容器运行
 
-从工程根运行 `pnpm build --target docker` 导出镜像。默认带部署工具，可运行 `pnpm run deploy --env test --build` 一次完成构建发布，或 `pnpm run deploy --env prod --bundle-only` 交付已有镜像及跨平台脚本。完整包包含自建中间件，人工部署与按服务更新见工程根 README。
+从工程根运行 `pnpm build --target image` 导出镜像。默认带部署工具，可运行 `pnpm run deploy --env test --build` 一次完成构建发布，或 `pnpm run deploy --env prod --bundle-only` 交付已有镜像及跨平台脚本。完整包包含自建中间件，人工部署与按服务更新见工程根 README。
 
 - 服务镜像直接由 `@h-ai/serv` 对外监听，配置挂载点为 `/app/config`，数据目录为 `/app/data`，不包含额外转发进程。
 - Web 镜像不烘焙 API 地址；启动时使用 `-e PUBLIC_API_BASE=https://api.example.com` 注入，同一镜像可部署到不同环境。未设置时 Web 默认请求自身 origin。
 - YAML 配置使用 `${ENV_NAME:default}` 接收运行时环境变量；不要把密钥写入镜像。
+- 受控内网或 VPN 的生产 HTTP 入口可在 `.env.prod.local` 设置 `HAI_SERV_REFRESH_COOKIE_SECURE=false` 和实际 `HAI_SERV_CORS_ORIGIN`，重新部署后端后重新登录。刷新凭据会经 HTTP 明文传输。
 
 ### IAM 认证配置
 

package/templates/apps/fullstack/packages/{{projectName}}-serv/config/_reach.yml.hbs

@@ -4,7 +4,10 @@ providers:
     type: console
   - name: sms
     type: console
-  # SMTP 替换 email 控制台 Provider；同名 Provider 只保留一个。
+# 生产示例：用下面 providers 整段替换上方控制台列表；保留需要的项。
+# 数组索引从 0 开始，删掉某项后同步修改其余环境变量中的索引。
+# providers:
+  # SMTP 邮件；名称 email 与下方通知模板对应。
   # - name: email
   #   type: smtp
   #   host: ${HAI_REACH_PROVIDERS_0_HOST:smtp.example.com}
@@ -16,19 +19,22 @@ providers:
   # 阿里云短信替换 sms 控制台 Provider。
   # - name: sms
   #   type: aliyun-sms
-  #   accessKeyId: ${HAI_REACH_PROVIDERS_0_ACCESSKEYID}
-  #   accessKeySecret: ${HAI_REACH_PROVIDERS_0_ACCESSKEYSECRET}
+  #   accessKeyId: ${HAI_REACH_PROVIDERS_1_ACCESSKEYID}
+  #   accessKeySecret: ${HAI_REACH_PROVIDERS_1_ACCESSKEYSECRET}
   #   signName: MyApp
   #   endpoint: dysmsapi.aliyuncs.com
+  #   gateway: # 可选；配置后向完整 URL 发送 POST
+  #     url: https://sms-gateway.example.com/dx
+  #     body: {}
   # 自有发送服务：按需将 template.provider 改为 custom。
   # - name: custom
   #   type: api
   #   url: https://notify.example.com/send
   #   method: POST # POST | PUT
   #   headers:
-  #     Authorization: '${HAI_REACH_PROVIDERS_0_HEADERS_AUTHORIZATION}'
+  #     Authorization: '${HAI_REACH_PROVIDERS_2_HEADERS_AUTHORIZATION}'
   #   timeout: 10000
-  #   idempotent: ${HAI_REACH_PROVIDERS_0_IDEMPOTENT:false} # 仅接收端具备原子持久去重时启用；默认在途不明结果转 unknown
+  #   idempotent: ${HAI_REACH_PROVIDERS_2_IDEMPOTENT:false} # 仅接收端具备原子持久去重时启用；默认在途不明结果转 unknown
 templates:
   - name: otp_email
     provider: email
@@ -52,8 +58,8 @@ templates:
 #   start: '22:00'
 #   end: '08:00'
 
-# 延迟队列策略随每条消息保存；最多领取 5 次，指数退避 1 分钟至 1 小时。
-# 超限 dead 只经可信服务端人工恢复；unknown 不允许自动重发。
+# 消息发送失败后最多尝试 5 次。首次重试等待 1 分钟，以后每次加倍，最长等待 1 小时。
+# 尝试次数用完后停止，交给管理员处理；若无法确认对方是否已收到，先核对结果，避免重复发送。
 queue:
   maxAttempts: ${HAI_REACH_QUEUE_MAXATTEMPTS:5}
   retryDelayMs: ${HAI_REACH_QUEUE_RETRYDELAYMS:60000}

package/templates/apps/fullstack/packages/{{projectName}}-serv/config/_serv.yml.hbs

@@ -16,22 +16,24 @@ http:
   access: false
   # access:
   #   file: ./config/security/request-access.yml
+  # 或将 access: false 替换为下列内联配置；与 file 二选一。
+  # access:
+  #   global:
+  #     timezone: UTC # 可用 HAI_SERV_HTTP_ACCESS_GLOBAL_TIMEZONE=Asia/Shanghai
+  #     allowIps: []
+  #     denyIps: []
+  #     windows: []
+  #   rules: []
   apiPrefix: /api/v1
   openapi:
     path: /openapi.json
+  # HAI_SERV_HTTP_DOCS=false 关闭文档；开启时再配置 path/requireAuth。
   docs:
     path: /docs
     # requireAuth: true
   health:
     path: /health
     readyPath: /ready
-  rpc: false
-  # 内部 RPC 可选；启用时用对象替换 false，gateway-only 必须配置网关密钥。
-  # rpc:
-  #   prefix: /api/rpc
-  #   access: gateway-only # loopback | private-network | gateway-only
-  #   gatewayHeader: X-Gateway-Key
-  #   gatewaySecret: ${HAI_SERV_HTTP_RPC_GATEWAYSECRET}
 
 cors:
   origin: ${HAI_SERV_CORS_ORIGIN:*}
@@ -60,5 +62,13 @@ transport:
 {{else}}
   maxPlaintextBytes: ${HAI_SERV_TRANSPORT_MAXPLAINTEXTBYTES:1048576}
 {{/if}}
+  # 传输时钟窗口，单位秒；允许领先 0～300 秒，请求有效期 1～600 秒。
+  maxFutureSkewSeconds: ${HAI_SERV_TRANSPORT_MAXFUTURESKEWSECONDS:30}
+  maxRequestAgeSeconds: ${HAI_SERV_TRANSPORT_MAXREQUESTAGESECONDS:300}
+  # HAI_SERV_TRANSPORT_ROUTEPLAINTEXTBYTES 可填 JSON，例如 {"/api/v1/uploads/*":8388608}。
+  routePlaintextBytes: {}
   keyExchangePath: /_hai/key-exchange
   # excludePaths: [/health, /ready]
+  # 单条路径需要更大请求体时填写字节数，* 只匹配一段路径。
+  # routePlaintextBytes: # HAI_SERV_TRANSPORT_ROUTEPLAINTEXTBYTES 可填 JSON 路径映射
+  #   /api/v1/uploads/*: 8388608

package/templates/apps/fullstack/packages/{{projectName}}-serv/package.json.hbs

@@ -27,11 +27,11 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "clean": "rimraf dist .turbo",
-    "dev": "pnpm build && node --env-file=../../.env --env-file=../../.env.dev --env-file-if-exists=../../.env.local dist/index.js",
-    "start": "node --env-file=../../.env --env-file=../../.env.prod --env-file-if-exists=../../.env.local dist/index.js",
-    "dev:test": "pnpm build && node --env-file=../../.env --env-file=../../.env.test --env-file-if-exists=../../.env.local dist/index.js",
+    "dev": "pnpm build && node ../../scripts/run-node.mjs dev ../.. dist/index.js",
+    "start": "node ../../scripts/run-node.mjs prod ../.. dist/index.js",
+    "dev:test": "pnpm build && node ../../scripts/run-node.mjs test ../.. dist/index.js",
     "dev:prod": "pnpm build && pnpm start",
-    "start:test": "node --env-file=../../.env --env-file=../../.env.test --env-file-if-exists=../../.env.local dist/index.js",
+    "start:test": "node ../../scripts/run-node.mjs test ../.. dist/index.js",
     "start:prod": "pnpm start"
   },
   "dependencies": {
@@ -43,11 +43,17 @@
     "@h-ai/cache": "{{haiPackageSpecifier}}",
     "@h-ai/core": "{{haiPackageSpecifier}}",
     "@h-ai/crypto": "{{haiPackageSpecifier}}",
+{{#if features.datapipe}}
+    "@h-ai/datapipe": "{{haiPackageSpecifier}}",
+{{/if}}
 {{#if features.feedback}}
     "@h-ai/api-contract": "{{haiPackageSpecifier}}",
     "@h-ai/feedback": "{{haiPackageSpecifier}}",
 {{/if}}
     "@h-ai/iam": "{{haiPackageSpecifier}}",
+{{#if features.payment}}
+    "@h-ai/payment": "{{haiPackageSpecifier}}",
+{{/if}}
     "@h-ai/reach": "{{haiPackageSpecifier}}",
     "@h-ai/reldb": "{{haiPackageSpecifier}}",
     "@h-ai/scheduler": "{{haiPackageSpecifier}}",

package/templates/apps/fullstack/packages/{{projectName}}-serv/src/app-server.ts.hbs

@@ -1,8 +1,10 @@
 import type { CoreConfig } from '@h-ai/core'
 import type { {{#if features.feedback}}CreateServContext, {{/if}}ServHttpApp } from '@h-ai/serv'
 import process from 'node:process'
-{{#if features.feedback}}import { resolveFeedbackBudget } from '@h-ai/api-contract/feedback'
-{{/if}}import { core } from '@h-ai/core'
+{{#if features.feedback}}
+import { resolveFeedbackBudget } from '@h-ai/api-contract/feedback'
+{{/if}}
+import { core } from '@h-ai/core'
 import { createReldbTransportKeyStore, crypto, parseTransportServerKeyRing } from '@h-ai/crypto'
 {{#if features.feedback}}
 import { FeedbackConfigSchema } from '@h-ai/feedback'
@@ -25,19 +27,29 @@ export function createServerApp(): ServHttpApp {
   const ring = parseTransportServerKeyRing(process.env.HAI_CRYPTO_TRANSPORT_SERVERKEYRING)
   if (!ring.success)
     throw new Error(`HAI_CRYPTO_TRANSPORT_SERVERKEYRING: ${ring.error.message} (${ring.error.code})`)
-{{#if features.feedback}}  // 可选反馈故障重试期间仍使用配置预算，避免缓存默认容量。
+{{#if features.feedback}}
+  // 可选反馈故障重试期间仍使用配置预算，避免缓存默认容量。
   const feedbackSettings = FeedbackConfigSchema.safeParse(core.config.get('feedback'))
-  const feedbackBudget = resolveFeedbackBudget(feedbackSettings.success ? feedbackSettings.data : {})
-{{/if}}  const security = serv.createRuntimeSecurityPolicy({
+  const feedbackBudget = resolveFeedbackBudget(feedbackSettings.success
+    ? feedbackSettings.data
+    : {})
+{{/if}}
+  const security = serv.createRuntimeSecurityPolicy({
     environment: coreConfig.env,
     corsOrigin: servConfig.cors.origin,
     nativeOrigins: servConfig.cors.nativeOrigins,
   })
   const publicPaths = [
     `${servConfig.http.apiPrefix}/assets`,
-    ...(servConfig.http.health ? [servConfig.http.health.path, servConfig.http.health.readyPath].filter((path): path is `/${string}` => Boolean(path)) : []),
-    ...(servConfig.http.openapi && security.exposeApiDocs ? [servConfig.http.openapi.path] : []),
-    ...(servConfig.http.docs && security.exposeApiDocs ? [servConfig.http.docs.path] : []),
+    ...(servConfig.http.health
+      ? [servConfig.http.health.path, servConfig.http.health.readyPath].filter((path): path is `/${string}` => Boolean(path))
+      : []),
+    ...(servConfig.http.openapi && security.exposeApiDocs
+      ? [servConfig.http.openapi.path]
+      : []),
+    ...(servConfig.http.docs && security.exposeApiDocs
+      ? [servConfig.http.docs.path, `${servConfig.http.docs.path.slice(0, servConfig.http.docs.path.lastIndexOf('/') + 1)}_hai/scalar.js`]
+      : []),
   ]
 {{#if features.feedback}}
   // 普通业务日志与反馈使用同一可信应用范围；身份仍由 IAM 验证。
@@ -67,9 +79,11 @@ export function createServerApp(): ServHttpApp {
 {{/if}}
     refreshCookie: {
       secure: security.secureRefreshCookie,
-      nativeTokenTransport: { isRequest: request => request.headers.get('x-hai-token-transport') === 'body'
-        && ['{{projectName}}-app', '{{projectName}}-desktop'].includes(request.headers.get('x-request-client') ?? '')
-        && security.isNativeOrigin(request.headers.get('origin') ?? '') },
+      nativeTokenTransport: {
+        isRequest: request => request.headers.get('x-hai-token-transport') === 'body'
+          && ['{{projectName}}-app', '{{projectName}}-desktop'].includes(request.headers.get('x-request-client') ?? '')
+          && security.isNativeOrigin(request.headers.get('origin') ?? ''),
+      },
     },
     // 管理业务默认强制双向加密；各节点复用受管服务端密钥环与共享 reldb 客户端 registry。
     transport: {
@@ -83,7 +97,12 @@ export function createServerApp(): ServHttpApp {
         ...servConfig.transport.routePlaintextBytes,
       },
 {{/if}}
-      excludePaths: [...new Set([...publicPaths, ...servConfig.transport.excludePaths])],
+      excludePaths: [
+        ...new Set([
+          ...publicPaths,
+          ...servConfig.transport.excludePaths,
+        ]),
+      ],
       crypto,
       serverKeyRing: ring.data,
       keyStore: createReldbTransportKeyStore({ reldb, ttlSeconds: 3600 }),
@@ -93,23 +112,39 @@ export function createServerApp(): ServHttpApp {
       openapi: security.exposeApiDocs ? servConfig.http.openapi : false,
       docs: security.exposeApiDocs ? servConfig.http.docs : false,
     },
-    middlewares: [{
-      middleware: serv.cors({
-        origin: security.allowOrigin,
-        credentials: servConfig.cors.credentials,
-        allowedHeaders: [...new Set([...servConfig.cors.allowedHeaders, 'X-Client-Id', 'X-Encrypted', 'X-Hai-Transport', 'X-Request-Client', 'X-HAI-Token-Transport', 'X-Hai-Reauthentication', 'X-Hai-Terminal'])],
-        exposedHeaders: [...new Set([...servConfig.cors.exposedHeaders, 'X-Encrypted', 'X-Hai-Transport'])],
-      }),
-    }, {
-      path: `${servConfig.http.apiPrefix}/assets/*`,
-      middleware: serv.storageAssets({
-        storage,
-        pathPrefix: `${servConfig.http.apiPrefix}/assets/`,
-        keyPattern: /^avatars\/[\w-]+\/[\w-]+\.(png|jpg|webp)$/,
-        allowedContentTypes: ['image/png', 'image/jpeg', 'image/webp'],
-        cacheControl: 'public, max-age=31536000, immutable',
-        crossOriginResourcePolicy: 'cross-origin',
-      }),
-    }],
+    middlewares: [
+      {
+        middleware: serv.cors({
+          origin: security.allowOrigin,
+          credentials: servConfig.cors.credentials,
+          allowedHeaders: [
+            ...new Set([
+              ...servConfig.cors.allowedHeaders,
+              'X-Client-Id',
+              'X-Encrypted',
+              'X-Hai-Transport',
+              'X-Request-Client',
+              'X-HAI-Token-Transport',
+              'X-Hai-Reauthentication',
+              'X-Hai-Terminal',
+            ]),
+          ],
+          exposedHeaders: [
+            ...new Set([...servConfig.cors.exposedHeaders, 'X-Encrypted', 'X-Hai-Transport']),
+          ],
+        }),
+      },
+      {
+        path: `${servConfig.http.apiPrefix}/assets/*`,
+        middleware: serv.storageAssets({
+          storage,
+          pathPrefix: `${servConfig.http.apiPrefix}/assets/`,
+          keyPattern: /^avatars\/[\w-]+\/[\w-]+\.(png|jpg|webp)$/,
+          allowedContentTypes: ['image/png', 'image/jpeg', 'image/webp'],
+          cacheControl: 'public, max-age=31536000, immutable',
+          crossOriginResourcePolicy: 'cross-origin',
+        }),
+      },
+    ],
   })
 }