@ai-partner-x/aiko-boot-cli 0.1.4

package/templates/feature-file/api/upload.controller.ts

@@ -0,0 +1,97 @@
+import 'reflect-metadata';
+import {
+  RestController,
+  PostMapping,
+  DeleteMapping,
+  GetMapping,
+  RequestParam,
+} from '@ai-partner-x/aiko-boot-starter-web';
+import { Autowired } from '@ai-partner-x/aiko-boot';
+import {
+  StorageService,
+  type UploadResult,
+} from '@ai-partner-x/aiko-boot-starter-storage';
+import type { Request } from 'express';
+
+/**
+ * 文件上传控制器
+ *
+ * 提供文件上传、删除、获取 URL 等接口
+ */
+@RestController({ path: '/upload' })
+export class UploadController {
+  @Autowired()
+  private storageService!: StorageService;
+
+  /**
+   * 上传单个文件
+   *
+   * @example
+   * curl -X POST http://localhost:3001/api/upload \
+   *   -F "file=@/path/to/image.png" \
+   *   -F "folder=images"
+   */
+  @PostMapping('/')
+  async upload(req: Request): Promise<UploadResult> {
+    const file = (req as Request & { file?: Express.Multer.File }).file;
+    if (!file) {
+      throw new Error('No file uploaded');
+    }
+
+    const folder = (req.body?.folder as string) || 'uploads';
+
+    return this.storageService.upload(file.buffer, file.originalname, {
+      folder,
+      maxSize: 10 * 1024 * 1024, // 10MB
+      allowedTypes: ['image/jpeg', 'image/png', 'image/gif', 'image/webp'],
+    });
+  }
+
+  /**
+   * 删除文件
+   *
+   * @example
+   * curl -X DELETE "http://localhost:3001/api/upload?key=images/xxx.png"
+   */
+  @DeleteMapping('/')
+  async delete(
+    @RequestParam('key') key: string,
+  ): Promise<{ success: boolean }> {
+    await this.storageService.delete(key);
+    return { success: true };
+  }
+
+  /**
+   * 获取文件 URL
+   *
+   * @example
+   * curl "http://localhost:3001/api/upload/url?key=images/xxx.png"
+   */
+  @GetMapping('/url')
+  async getUrl(@RequestParam('key') key: string): Promise<{ url: string }> {
+    const url = await this.storageService.getUrl(key);
+    return { url };
+  }
+
+  /**
+   * 获取图片预览 URL（支持 OSS/COS 的图片处理参数）
+   *
+   * @example
+   * curl "http://localhost:3001/api/upload/preview?key=images/xxx.png&width=200&height=200"
+   */
+  @GetMapping('/preview')
+  async getPreviewUrl(
+    @RequestParam('key') key: string,
+    @RequestParam('width') width?: string,
+    @RequestParam('height') height?: string,
+    @RequestParam('quality') quality?: string,
+  ): Promise<{ url: string }> {
+    const url = await this.storageService.getPreviewUrl(key, {
+      width: width ? parseInt(width, 10) : undefined,
+      height: height ? parseInt(height, 10) : undefined,
+      quality: quality ? parseInt(quality, 10) : undefined,
+    });
+    return { url };
+  }
+}
+

package/templates/feature-log/api/docs/log-integration-guide.md

@@ -0,0 +1,54 @@
+# Log Integration Guide
+
+本特性为 `aiko-boot` API 服务集成统一日志能力（基于 `@ai-partner-x/aiko-boot-starter-log`），包括：
+
+- 统一 logger（命名 logger、默认元数据、文件/控制台输出）
+- HTTP 请求日志中间件（记录请求/响应耗时、状态码等）
+- 全局错误日志（捕获未处理异常并记录上下文）
+
+## 1. 安装依赖
+
+在目标 API 服务的 `package.json` 中添加：
+
+- `@ai-partner-x/aiko-boot-starter-log`
+
+> 若你使用 `aiko-boot add-feature --feature log`，会自动完成依赖写入。
+
+## 2. 配置 `app.config.ts`
+
+增加 `logging` 配置节点（示例字段）：
+
+- `level`: 日志级别（`error|warn|info|http|verbose|debug|silly`）
+- `format`: 输出格式（`json|cli|pretty|simple`）
+- `transports`: 输出目标（console/file）
+
+> `add-feature` 会在检测到缺失 `logging:` 时注入一份默认配置。
+
+## 3. 在 `src/server.ts` 启用日志
+
+建议包含以下行为：
+
+- `autoInit()`：启动时初始化 logger
+- `getLogger('server')`：获取命名 logger
+- `expressApp.use(RequestLogService.requestLogMiddleware)`：启用请求日志
+- 全局 error middleware：记录未捕获错误并返回 500
+
+## 4. 使用方式
+
+你可以直接使用 starter 的 logger：
+
+```ts
+import { getLogger } from '@ai-partner-x/aiko-boot-starter-log';
+
+const logger = getLogger('module');
+logger.info('hello', { foo: 'bar' });
+```
+
+也可以使用本特性提供的适配器：
+
+```ts
+import { logService } from './service/log.service';
+
+logService.info('something happened', { id: 1 });
+```
+

package/templates/feature-log/api/src/service/log.request.service.ts

@@ -0,0 +1,112 @@
+import type { Request, Response, NextFunction } from 'express';
+import { getLogger } from '@ai-partner-x/aiko-boot-starter-log';
+
+const logger = getLogger('http');
+
+/**
+ * HTTP 请求日志服务
+ * 提供 HTTP 请求日志记录功能
+ */
+export class RequestLogService {
+  /** 统一的 HTTP 请求日志中间件（包含开始/结束/错误/提前断开） */
+  static requestLogMiddleware(req: Request, res: Response, next: NextFunction): void {
+    const startTime = Date.now();
+
+    const requestInfo = RequestLogService.buildRequestInfo(req);
+    logger.http('Request started', requestInfo);
+
+    // 监听响应完成事件
+    res.on('finish', () => {
+      const duration = Date.now() - startTime;
+
+      const responseInfo = RequestLogService.buildResponseInfo(
+        requestInfo,
+        res,
+        duration,
+      );
+      RequestLogService.logByStatus('Request completed', res.statusCode, responseInfo);
+    });
+
+    // 监听响应关闭事件（客户端提前断开连接）
+    res.on('close', () => {
+      if (!res.writableFinished) {
+        const duration = Date.now() - startTime;
+        RequestLogService.logClientDisconnect(req, duration);
+      }
+    });
+
+    next();
+  }
+
+  /**
+   * 记录 HTTP 请求信息（直接调用，非中间件）
+   */
+  static logRequest(req: Request, res: Response, duration: number) {
+    const requestInfo = RequestLogService.buildRequestInfo(req);
+    const responseInfo = RequestLogService.buildResponseInfo(
+      requestInfo,
+      res,
+      duration,
+    );
+    RequestLogService.logByStatus(
+      'Request completed (manual log)',
+      res.statusCode,
+      responseInfo,
+    );
+  }
+
+  /**
+   * 记录客户端提前断开连接
+   */
+  static logClientDisconnect(req: Request, duration: number) {
+    logger.warn('Request closed by client before completion', {
+      ...RequestLogService.buildRequestInfo(req),
+      duration: `${duration}ms`,
+      timestamp: new Date().toISOString(),
+    });
+  }
+
+  private static buildRequestInfo(req: Request) {
+    return {
+      method: req.method,
+      url: req.url,
+      path: req.path,
+      query: req.query,
+      ip: req.ip || req.connection.remoteAddress,
+      userAgent: req.get('user-agent') || 'unknown',
+      contentType: req.get('content-type'),
+      contentLength: req.get('content-length'),
+      referer: req.get('referer'),
+    };
+  }
+
+  private static buildResponseInfo(
+    requestInfo: ReturnType<typeof RequestLogService.buildRequestInfo>,
+    res: Response,
+    duration: number,
+  ) {
+    return {
+      ...requestInfo,
+      status: res.statusCode,
+      statusMessage: res.statusMessage,
+      duration: `${duration}ms`,
+      responseTime: duration,
+      timestamp: new Date().toISOString(),
+    };
+  }
+
+  private static logByStatus(
+    prefix: string,
+    statusCode: number,
+    payload: Record<string, unknown>,
+  ): void {
+    if (statusCode >= 500) {
+      logger.error(`${prefix} with server error`, payload);
+    } else if (statusCode >= 400) {
+      logger.warn(`${prefix} with client error`, payload);
+    } else {
+      logger.http(`${prefix} successfully`, payload);
+    }
+  }
+}
+

package/templates/feature-log/api/src/service/log.service.ts

@@ -0,0 +1,124 @@
+import { getLogger, type ILogger } from '@ai-partner-x/aiko-boot-starter-log';
+
+/**
+ * 日志服务适配器
+ * 提供统一的日志接口，封装 aiko-boot-starter-log 的功能
+ */
+export class LogService {
+  private static instance: LogService;
+  private logger: ILogger;
+
+  private constructor() {
+    // 使用命名 logger，便于区分不同模块
+    this.logger = getLogger('scaffold-api');
+  }
+
+  /**
+   * 获取日志服务单例
+   */
+  static getInstance(): LogService {
+    if (!LogService.instance) {
+      LogService.instance = new LogService();
+    }
+    return LogService.instance;
+  }
+
+  /**
+   * 记录错误日志
+   * @param message 错误消息
+   * @param error 错误对象（可选）
+   * @param meta 附加元数据（可选）
+   */
+  error(message: string, error?: Error, meta?: Record<string, any>) {
+    this.logger.error(message, error, meta);
+  }
+
+  /**
+   * 记录警告日志
+   * @param message 警告消息
+   * @param meta 附加元数据（可选）
+   */
+  warn(message: string, meta?: Record<string, any>) {
+    this.logger.warn(message, meta);
+  }
+
+  /**
+   * 记录信息日志
+   * @param message 信息消息
+   * @param meta 附加元数据（可选）
+   */
+  info(message: string, meta?: Record<string, any>) {
+    this.logger.info(message, meta);
+  }
+
+  /**
+   * 记录调试日志
+   * @param message 调试消息
+   * @param meta 附加元数据（可选）
+   */
+  debug(message: string, meta?: Record<string, any>) {
+    this.logger.debug(message, meta);
+  }
+
+  /**
+   * 记录 HTTP 请求日志
+   * @param message HTTP 消息
+   * @param meta 附加元数据（可选）
+   */
+  http(message: string, meta?: Record<string, any>) {
+    this.logger.http(message, meta);
+  }
+
+  /**
+   * 记录详细日志
+   * @param message 详细消息
+   * @param meta 附加元数据（可选）
+   */
+  verbose(message: string, meta?: Record<string, any>) {
+    this.logger.verbose(message, meta);
+  }
+
+  /**
+   * 记录最详细日志
+   * @param message 最详细消息
+   * @param meta 附加元数据（可选）
+   */
+  silly(message: string, meta?: Record<string, any>) {
+    this.logger.silly(message, meta);
+  }
+
+  /**
+   * 检查是否启用指定级别的日志
+   * @param level 日志级别
+   */
+  isLevelEnabled(level: string): boolean {
+    return this.logger.isLevelEnabled(level);
+  }
+
+  /**
+   * 获取原始 logger 实例
+   */
+  getLogger(): ILogger {
+    return this.logger;
+  }
+
+  /**
+   * 创建子 logger（用于模块划分）
+   * @param name 子 logger 名称
+   */
+  createChildLogger(name: string): ILogger {
+    return this.logger.child(name);
+  }
+
+  /**
+   * 添加上下文信息
+   * @param context 上下文对象
+   */
+  withContext(context: Record<string, any>): ILogger {
+    return this.logger.withContext(context);
+  }
+}
+
+// 导出单例实例
+export const logService = LogService.getInstance();
+

package/templates/feature-mq/api/src/controller/mq.controller.ts

@@ -0,0 +1,35 @@
+import 'reflect-metadata';
+import { RestController, PostMapping, RequestBody } from '@ai-partner-x/aiko-boot-starter-web';
+import { Autowired } from '@ai-partner-x/aiko-boot';
+import { MqTemplate } from '@ai-partner-x/aiko-boot-starter-mq';
+import type { SendUserEventDto, UserEventDto } from '../dto/mq.dto.js';
+
+@RestController({ path: '/mq' })
+export class MqController {
+  @Autowired(MqTemplate)
+  private mqTemplate!: MqTemplate;
+
+  /**
+   * 发送用户相关消息到 MQ
+   * POST /api/mq/send
+   */
+  @PostMapping('/send')
+  async send(@RequestBody() dto: SendUserEventDto): Promise<{ ok: boolean; topic: string }> {
+    if (dto.tag) {
+      await this.mqTemplate.send(dto.topic, dto.tag, dto.body);
+    } else {
+      await this.mqTemplate.send(dto.topic, dto.body);
+    }
+    return { ok: true, topic: dto.topic };
+  }
+
+  /**
+   * 快捷发送 user.created 事件（复用 User 实体字段）
+   * POST /api/mq/send-user-created
+   */
+  @PostMapping('/send-user-created')
+  async sendUserCreated(@RequestBody() body: UserEventDto): Promise<{ ok: boolean }> {
+    await this.mqTemplate.send('user.created', 'add', body);
+    return { ok: true };
+  }
+}

package/templates/feature-mq/api/src/dto/mq.dto.ts

@@ -0,0 +1,16 @@
+/**
+ * MQ 消息 DTO（复用 User 实体字段，不包含敏感信息）
+ */
+export interface UserEventDto {
+  id: number;
+  username: string;
+  email: string;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+export interface SendUserEventDto {
+  topic: string;
+  tag?: string;
+  body: UserEventDto;
+}

package/templates/feature-mq/api/src/service/mq.consumer.service.ts

@@ -0,0 +1,26 @@
+import 'reflect-metadata';
+import { Service } from '@ai-partner-x/aiko-boot';
+import { MqListener, type MqListenerMeta } from '@ai-partner-x/aiko-boot-starter-mq';
+import type { UserEventDto } from '../dto/mq.dto.js';
+
+/**
+ * MQ 消费者服务 - 订阅 user 相关消息
+ * 复用 User 实体字段结构（id, username, email, createdAt, updatedAt）
+ */
+@Service()
+export class MqConsumerService {
+  static readonly MQ_LISTENERS: MqListenerMeta[] = [
+    { topic: 'user.created', tag: 'add', group: 'scaffold-user-group', method: 'onUserCreated' },
+    { topic: 'user.updated', tag: 'update', group: 'scaffold-user-group', method: 'onUserUpdated' },
+  ];
+
+  @MqListener({ topic: 'user.created', tag: 'add', group: 'scaffold-user-group' })
+  async onUserCreated(event: UserEventDto): Promise<void> {
+    console.log('[MqConsumer] user.created:', JSON.stringify(event));
+  }
+
+  @MqListener({ topic: 'user.updated', tag: 'update', group: 'scaffold-user-group' })
+  async onUserUpdated(event: UserEventDto): Promise<void> {
+    console.log('[MqConsumer] user.updated:', JSON.stringify(event));
+  }
+}

package/templates/feature-redis/api/src/controller/cache.controller.ts

@@ -0,0 +1,107 @@
+import 'reflect-metadata';
+import { RestController, PostMapping, DeleteMapping, GetMapping, RequestBody, RequestParam } from '@ai-partner-x/aiko-boot-starter-web';
+import { Autowired } from '@ai-partner-x/aiko-boot';
+import { CacheService } from '../service/cache.service.js';
+import type { CachePutDto } from '../dto/cache.dto.js';
+
+/**
+ * Cache 控制器
+ *
+ * 提供缓存的 CRUD 操作接口，仅在非生产环境下可用。
+ * 注意：需要在 app.config.ts 中启用 cache 并配置 Redis 连接
+ * 
+ * 当 NODE_ENV=production 时，所有端点会直接抛出错误拒绝访问，
+ * 防止数据泄露、缓存投毒或拒绝服务。
+ */
+@RestController({ path: '/cache' })
+export class CacheController {
+  @Autowired()
+  private cacheService!: CacheService;
+
+  private assertNonProduction(): void {
+    if (process.env.NODE_ENV === 'production') {
+      throw new Error('Cache management endpoints are disabled in production.');
+    }
+  }
+
+  /**
+   * 获取缓存值
+   * 
+   * @example
+   * curl "http://localhost:3001/api/cache/get?name=user&key=1"
+   */
+  @GetMapping('/get')
+  async get(
+    @RequestParam('name') name: string,
+    @RequestParam('key') key: string,
+  ): Promise<string | null> {
+    this.assertNonProduction();
+    return this.cacheService.get({ name, key });
+  }
+
+  /**
+   * 设置缓存值
+   * 
+   * @example
+   * curl -X POST http://localhost:3001/api/cache/put \
+   *   -H "Content-Type: application/json" \
+   *   -d '{"name":"user","key":"1","value":{"id":1,"name":"张三"},"ttlSeconds":300}'
+   */
+  @PostMapping('/put')
+  async put(@RequestBody() dto: CachePutDto): Promise<{ ok: boolean }> {
+    this.assertNonProduction();
+    await this.cacheService.put(dto);
+    return { ok: true };
+  }
+
+  /**
+   * 删除缓存条目
+   * 
+   * @example
+   * # 删除单个 key
+   * curl -X DELETE "http://localhost:3001/api/cache/evict?name=user&key=1"
+   * 
+   * # 删除命名空间下所有条目（无需传 key）
+   * curl -X DELETE "http://localhost:3001/api/cache/evict?name=user&allEntries=true"
+   */
+  @DeleteMapping('/evict')
+  async evict(
+    @RequestParam('name') name: string,
+    @RequestParam('key') key?: string,
+    @RequestParam('allEntries') allEntries?: string,
+  ): Promise<{ ok: boolean }> {
+    this.assertNonProduction();
+    const isAllEntries = allEntries === 'true';
+    if (!isAllEntries && !key) {
+      throw new Error('Query parameter "key" is required when "allEntries" is not true.');
+    }
+
+    await this.cacheService.evict({ name, key, allEntries: isAllEntries });
+    return { ok: true };
+  }
+
+  /**
+   * 清空缓存命名空间
+   * 
+   * @example
+   * curl -X DELETE "http://localhost:3001/api/cache/clear?name=user"
+   */
+  @DeleteMapping('/clear')
+  async clear(@RequestParam('name') name: string): Promise<{ ok: boolean }> {
+    this.assertNonProduction();
+    await this.cacheService.clear({ name });
+    return { ok: true };
+  }
+
+  /**
+   * 检查缓存状态
+   * 
+   * @example
+   * curl "http://localhost:3001/api/cache/status"
+   */
+  @GetMapping('/status')
+  async status(): Promise<{ initialized: boolean }> {
+    this.assertNonProduction();
+    return { initialized: this.cacheService.isInitialized() };
+  }
+}

package/templates/feature-redis/api/src/dto/cache.dto.ts

@@ -0,0 +1,24 @@
+/**
+ * Cache 操作 DTO
+ */
+export interface CacheGetDto {
+  name: string;
+  key: string;
+}
+
+export interface CachePutDto {
+  name: string;
+  key: string;
+  value: unknown;
+  ttlSeconds?: number;
+}
+
+export interface CacheEvictDto {
+  name: string;
+  key?: string;
+  allEntries?: boolean;
+}
+
+export interface CacheClearDto {
+  name: string;
+}

package/templates/feature-redis/api/src/service/cache.service.ts

@@ -0,0 +1,80 @@
+import 'reflect-metadata';
+import { Service } from '@ai-partner-x/aiko-boot';
+import type { CacheManager } from '@ai-partner-x/aiko-boot-starter-cache';
+import { getCacheManager, isCacheManagerInitialized } from '@ai-partner-x/aiko-boot-starter-cache';
+import type { CacheGetDto, CachePutDto, CacheEvictDto, CacheClearDto } from '../dto/cache.dto.js';
+
+@Service()
+export class CacheService {
+  private getCacheManagerInstance(): CacheManager {
+    if (!isCacheManagerInitialized()) {
+      throw new Error('Cache is not initialized. Enable cache in app.config.ts and ensure Redis is running.');
+    }
+    return getCacheManager();
+  }
+
+  /**
+   * 获取缓存值
+   * @param name 缓存命名空间
+   * @param key 缓存键
+   * @returns 缓存值（JSON 字符串），未命中返回 null
+   */
+  async get(dto: CacheGetDto): Promise<string | null> {
+    const cache = this.getCacheManagerInstance().getCache(dto.name);
+    const value = await cache.get(dto.key);
+    return value;
+  }
+
+  /**
+   * 设置缓存值
+   * @param name 缓存命名空间
+   * @param key 缓存键
+   * @param value 缓存值（任意类型，会自动序列化为 JSON 字符串存储）
+   * @param ttlSeconds 可选过期时间（秒）
+   */
+  async put(dto: CachePutDto): Promise<void> {
+    if (dto.value === undefined) {
+      throw new Error('Cache value is required and must be JSON-serializable.');
+    }
+
+    let value: string;
+    try {
+      value = JSON.stringify(dto.value);
+    } catch (err) {
+      throw new Error('Cache value is not JSON-serializable.');
+    }
+    const cache = this.getCacheManagerInstance().getCache(dto.name);
+    await cache.put(dto.key, value, dto.ttlSeconds);
+  }
+
+  /**
+   * 删除缓存条目
+   * @param name 缓存命名空间
+   * @param key 缓存键
+   * @param allEntries 是否清除所有条目
+   */
+  async evict(dto: CacheEvictDto): Promise<void> {
+    const cache = this.getCacheManagerInstance().getCache(dto.name);
+    if (dto.allEntries) {
+      await cache.clear();
+    } else {
+      await cache.evict(dto.key);
+    }
+  }
+
+  /**
+   * 清空缓存命名空间
+   * @param name 缓存命名空间
+   */
+  async clear(dto: CacheClearDto): Promise<void> {
+    const cache = this.getCacheManagerInstance().getCache(dto.name);
+    await cache.clear();
+  }
+
+  /**
+   * 检查缓存是否已初始化
+   */
+  isInitialized(): boolean {
+    return isCacheManagerInitialized();
+  }
+}