/**
 * 实例控制器
 * 
 * 表单实例管理 API
 */

import {
  Controller,
  Get,
  Post,
  Patch,
  Delete,
  Body,
  Param,
  Query,
  UseGuards,
  Logger,
} from '@nestjs/common';
import {
  ApiTags,
  ApiOperation,
  ApiResponse,
  ApiBearerAuth,
  ApiHeader,
  ApiParam,
} from '@nestjs/swagger';
import { InstanceService } from '../services/instance.service';
import { RegionGuard } from '../guards/region.guard';
import { Region, RegionRequired } from '../decorators/region.decorator';
import type { RegionId } from '../decorators/region.decorator';
import { RequirePermissions } from '@common/decorators/permissions.decorator';
import { CurrentUser } from '@common/decorators/current-user.decorator';
import { PermissionsGuard } from '@modules/organization/auth/guards/permissions.guard';
import { Auditable, Sensitive, Financial } from '@core/observability/audit/decorators/auditable.decorator';
import { 
  CreateInstanceDto,
  UpdateInstanceDto,
  SubmitInstanceDto,
  QueryMyInstancesDto,
  WithdrawInstanceDto,
} from '../dto/instance.dto';

@ApiTags('实例管理')
@ApiBearerAuth()
@ApiHeader({
  name: 'X-Region-Id',
  description: '区域标识（CN / US / ME）',
  required: true,
})
@Controller('form-management')
@UseGuards(RegionGuard, PermissionsGuard)
@RegionRequired(true)
export class InstanceController {
  private readonly logger = new Logger(InstanceController.name);

  constructor(private readonly instanceService: InstanceService) {}

  // ============================================
  // 实例管理
  // ============================================

  @Post('instances')
  @Auditable()
  @Sensitive()
  @ApiOperation({ summary: '创建实例（表单 + 流程）' })
  @ApiResponse({ status: 201, description: '创建成功' })
  @ApiResponse({ status: 404, description: '表单不存在或没有激活版本' })
  @ApiResponse({ status: 422, description: '表单数据验证失败' })
  @RequirePermissions('form:use')
  async create(
    @Body() dto: CreateInstanceDto,
    @Region() regionId: RegionId,
    @CurrentUser('userId') userId: string,
  ) {
    this.logger.log(`POST /instances - region: ${regionId}, user: ${userId}`);
    return this.instanceService.create(dto, regionId, userId);
  }

  @Get('instances/my')
  @ApiOperation({ summary: '获取我的实例列表' })
  @ApiResponse({ status: 200, description: '成功获取列表' })
  @RequirePermissions('form:use')
  async getMyInstances(
    @Query() query: QueryMyInstancesDto,
    @Region() regionId: RegionId,
    @CurrentUser('userId') userId: string,
  ) {
    this.logger.log(`GET /instances/my - region: ${regionId}, user: ${userId}`);
    return this.instanceService.getMyInstances(query, regionId, userId);
  }

  @Get('instances/:id')
  @ApiOperation({ summary: '获取实例详情' })
  @ApiParam({ name: 'id', description: '实例 ID' })
  @ApiResponse({ status: 200, description: '成功获取实例' })
  @ApiResponse({ status: 404, description: '实例不存在或当前用户不可见' })
  @RequirePermissions('form:use')
  async getInstance(
    @Param('id') id: string,
    @Region() regionId: RegionId,
    @CurrentUser() user: any,
  ) {
    this.logger.log(`GET /instances/${id} - region: ${regionId}`);
    return this.instanceService.getInstance(id, regionId, user);
  }

  @Patch('instances/:id')
  @Auditable()
  @Sensitive()
  @ApiOperation({ summary: '更新实例' })
  @ApiParam({ name: 'id', description: '实例 ID' })
  @ApiResponse({ status: 200, description: '更新成功' })
  @ApiResponse({ status: 404, description: '实例不存在' })
  @ApiResponse({ status: 422, description: '数据验证失败' })
  @RequirePermissions('form:use')
  async updateInstance(
    @Param('id') id: string,
    @Body() dto: UpdateInstanceDto,
    @Region() regionId: RegionId,
    @CurrentUser('userId') userId: string,
  ) {
    this.logger.log(`PATCH /instances/${id} - region: ${regionId}`);
    return this.instanceService.updateInstance(id, dto, regionId, userId);
  }

  @Post('instances/:id/submit')
  @Auditable()
  @Sensitive()
  @ApiOperation({ summary: '提交实例（发起审批）' })
  @ApiParam({ name: 'id', description: '实例 ID' })
  @ApiResponse({ status: 200, description: '提交成功' })
  @ApiResponse({ status: 404, description: '实例不存在' })
  @ApiResponse({ status: 409, description: '实例已提交' })
  @RequirePermissions('form:use')
  async submitInstance(
    @Param('id') id: string,
    @Body() dto: SubmitInstanceDto,
    @Region() regionId: RegionId,
    @CurrentUser('userId') userId: string,
  ) {
    this.logger.log(`POST /instances/${id}/submit - region: ${regionId}`);
    return this.instanceService.submitInstance(id, dto, regionId, userId);
  }

  @Post('instances/:id/withdraw')
  @Auditable()
  @Sensitive()
  @ApiOperation({ summary: '撤回实例（发起人主动撤回）' })
  @ApiParam({ name: 'id', description: '实例 ID' })
  @ApiResponse({ status: 200, description: '撤回成功' })
  @ApiResponse({ status: 404, description: '实例不存在' })
  @ApiResponse({ status: 403, description: '无权撤回此实例' })
  @ApiResponse({ status: 400, description: '当前状态不允许撤回' })
  @RequirePermissions('form:use')
  async withdrawInstance(
    @Param('id') id: string,
    @Body() dto: WithdrawInstanceDto,
    @Region() regionId: RegionId,
    @CurrentUser('userId') userId: string,
  ) {
    this.logger.log(`POST /instances/${id}/withdraw - region: ${regionId}`);
    return this.instanceService.withdrawInstance(id, dto, regionId, userId);
  }

  @Delete('instances/:id')
  @Auditable()
  @Sensitive()
  @ApiOperation({ summary: '删除实例（软删除）' })
  @ApiParam({ name: 'id', description: '实例 ID' })
  @ApiResponse({ status: 200, description: '删除成功' })
  @ApiResponse({ status: 404, description: '实例不存在' })
  @RequirePermissions('form:use')
  async deleteInstance(
    @Param('id') id: string,
    @Region() regionId: RegionId,
    @CurrentUser('userId') userId: string,
  ) {
    this.logger.log(`DELETE /instances/${id} - region: ${regionId}`);
    return this.instanceService.deleteInstance(id, regionId, userId);
  }

  @Get('instances/:id/field-access')
  @ApiOperation({ summary: '获取当前节点字段权限' })
  @ApiParam({ name: 'id', description: '实例 ID' })
  @ApiResponse({ status: 200, description: '成功获取字段权限' })
  @ApiResponse({ status: 404, description: '实例不存在' })
  @RequirePermissions('form:use')
  async getFieldAccess(
    @Param('id') id: string,
    @Region() regionId: RegionId,
    @CurrentUser() user: any,
  ) {
    this.logger.log(`GET /instances/${id}/field-access - region: ${regionId}`);
    return this.instanceService.getFieldAccess(id, regionId, user);
  }
}