declare namespace Api {
  /**
   * namespace Project
   *
   * backend api module: "project/project"
   */
  namespace Project {
    /** 项目状态编码 */
    type ProjectStatusCode = 'pending' | 'active' | 'paused' | 'completed' | 'cancelled' | 'archived';

    /** 项目状态动作编码 */
    type ProjectStatusActionCode = 'auto_start' | 'pause' | 'resume' | 'complete' | 'cancel' | 'reopen' | 'archive';

    /** 项目设置基础信息 */
    interface ProjectSettingBaseInfo {
      /** 项目 ID */
      id: string;
      /** 项目编码 */
      projectCode: string;
      /** 项目名称 */
      projectName: string;
      /** 项目方向字典值 */
      directionCode: string;
      /** 项目类型字典值 */
      projectType: string;
      /** 所属产品 ID */
      productId: string | null;
      /** 所属产品名称 */
      productName: string | null;
      /** 项目负责人用户昵称 */
      managerUserNickname: string | null;
      /** 项目负责人用户 ID */
      managerUserId: string | null;
      /** 项目状态编码 */
      statusCode: ProjectStatusCode;
      /** 计划开始日期 */
      plannedStartDate: string | null;
      /** 计划结束日期 */
      plannedEndDate: string | null;
      /** 实际开始日期 */
      actualStartDate: string | null;
      /** 实际结束日期 */
      actualEndDate: string | null;
      /** 项目说明 */
      projectDesc: string | null;
      /** 最近一次状态动作原因 */
      lastStatusReason: string | null;
    }

    /** 项目生命周期动作 */
    interface ProjectLifecycleAction {
      actionCode: Exclude<ProjectStatusActionCode, 'auto_start'>;
      actionName: string;
      needReason: boolean;
    }

    /** 项目生命周期信息 */
    interface ProjectLifecycleInfo {
      statusCode: ProjectStatusCode;
      lastStatusReason: string | null;
      availableActions: ProjectLifecycleAction[];
    }

    /** 执行状态编码 */
    type ProjectExecutionStatusCode = 'pending' | 'active' | 'paused' | 'completed' | 'cancelled';

    /** 执行动作编码 */
    type ProjectExecutionActionCode = 'start' | 'pause' | 'resume' | 'cancel';

    /** 任务状态编码 */
    type ProjectTaskStatusCode = 'pending' | 'active' | 'paused' | 'completed' | 'cancelled';

    /** 任务动作编码 */
    type ProjectTaskActionCode = 'auto_start' | 'pause' | 'resume' | 'complete' | 'cancel';

    interface LifecycleAction<ActionCode extends string = string> {
      actionCode: ActionCode;
      actionName: string;
      needReason: boolean;
    }

    interface StatusBoardItem {
      statusCode: string;
      statusName: string;
      count: number;
      sort: number;
      terminal?: boolean;
    }

    interface StatusBoard {
      total: number;
      items: StatusBoardItem[];
    }

    interface ProjectExecution {
      id: string;
      projectId: string;
      projectRequirementId: string | null;
      executionName: string;
      executionType: string | null;
      ownerId: string;
      ownerNickname?: string | null;
      statusCode: ProjectExecutionStatusCode;
      statusName: string | null;
      terminal: boolean;
      allowEdit: boolean;
      availableActions: LifecycleAction<ProjectExecutionActionCode>[];
      plannedStartDate: string | null;
      plannedEndDate: string | null;
      actualStartDate: string | null;
      actualEndDate: string | null;
      progressRate: number;
      executionDesc: string | null;
      lastStatusReason: string | null;
      createTime: string;
      updateTime: string;
    }

    interface ExecutionAssignee {
      id: string;
      executionId: string;
      userId: string;
      userNickname?: string | null;
      joinedAt: string | null;
      removedAt: string | null;
      removedReason: string | null;
    }

    /** 执行协办人变更事件类型 */
    type ExecutionAssigneeActionType = 'join' | 'inactive' | 'owner_transfer_in' | 'owner_transfer_out';

    /** 执行协办人变更历史 */
    interface ExecutionAssigneeLog {
      id: string;
      executionId: string;
      actionType: ExecutionAssigneeActionType;
      userId: string;
      userNicknameSnapshot: string | null;
      operatorUserId: string;
      operatorNicknameSnapshot: string | null;
      actionTime: string;
      reason: string | null;
    }

    type ExecutionAssigneeLogSearchParams = CommonType.RecordNullable<
      Pick<PageParams, 'pageNo' | 'pageSize'> & {
        actionTypes: ExecutionAssigneeActionType[];
        userId: string;
        startTime: string;
        endTime: string;
      }
    >;

    /** 通用附件元数据（任务 / 工时等域共用，规则见 AttachmentValidator） */
    interface AttachmentItem {
      /**
       * 文件 ID（infra_file.id 字符串形式）。
       * 用于会话级清理时调用 DELETE /system/file/delete?id=xxx 删除孤儿文件。
       */
      fileId: string;
      url: string;
      name: string;
      size?: number;
      contentType?: string;
    }

    /** 任务详情 / 分页响应里嵌入的活跃协办人引用（按加入时间正序） */
    interface TaskAssigneeRef {
      id: string;
      userId: string;
      nickname: string;
      /** 加入时间，5.6 路径返；5.3 嵌入路径不返，留 undefined */
      joinedAt?: string | null;
    }

    /** 协办人变更事件类型（5.9 actionType） */
    type TaskAssigneeActionType = 'join' | 'inactive';

    /** 协办人变更日志 */
    interface TaskAssigneeLog {
      id: string;
      taskId: string;
      actionType: TaskAssigneeActionType;
      userId: string;
      userNicknameSnapshot: string | null;
      operatorUserId: string;
      operatorNicknameSnapshot: string | null;
      actionTime: string;
      reason: string | null;
    }

    type TaskAssigneeLogSearchParams = CommonType.RecordNullable<
      Pick<PageParams, 'pageNo' | 'pageSize'> & {
        actionTypes: TaskAssigneeActionType[];
        userId: string;
        startTime: string;
        endTime: string;
      }
    >;

    /** 5.7 加入协办人入参 */
    interface CreateTaskAssigneeParams {
      userId: string;
    }

    /** 5.8 退出协办人入参 */
    interface InactiveTaskAssigneeParams {
      reason: string;
    }

    interface ProjectTask {
      id: string;
      projectId: string;
      executionId: string;
      parentTaskId: string | null;
      taskTitle: string;
      ownerId: string;
      ownerNickname?: string | null;
      /** 所属执行的负责人 userId（按钮可见度公式用） */
      executionOwnerId: string;
      /** 父任务负责人 userId（一级任务为 null） */
      parentTaskOwnerId: string | null;
      statusCode: ProjectTaskStatusCode;
      statusName: string | null;
      terminal: boolean;
      allowEdit: boolean;
      availableActions: LifecycleAction<ProjectTaskActionCode>[];
      progressRate: number;
      plannedStartDate: string | null;
      plannedEndDate: string | null;
      actualStartDate: string | null;
      actualEndDate: string | null;
      taskDesc: string | null;
      lastStatusReason: string | null;
      assignees?: TaskAssigneeRef[] | null;
      attachments?: AttachmentItem[] | null;
      /** 已填报工时合计，单位小时（0.5 颗粒，BigDecimal）。逻辑删除的工时不计入。 */
      totalSpentHours?: number | null;
      createTime: string;
      updateTime: string;
    }

    type ProjectExecutionSearchParams = CommonType.RecordNullable<
      Pick<PageParams, 'pageNo' | 'pageSize'> & {
        keyword: string;
        executionType: string;
        ownerId: string;
        statusCode: string;
        updateTime: string[];
      }
    >;

    type ProjectExecutionStatusBoardParams = CommonType.RecordNullable<{
      keyword: string;
      executionType: string;
      ownerId: string;
      updateTime: string[];
    }>;

    /** 创建执行入参（含 ownerId + assigneeUserIds） */
    interface CreateProjectExecutionParams {
      executionName: string;
      executionType: string;
      ownerId: string;
      projectRequirementId: string | null;
      plannedStartDate: string | null;
      plannedEndDate: string | null;
      executionDesc: string | null;
      assigneeUserIds?: string[];
    }

    /** 执行创建/编辑弹层 emit 的统一 payload（创建时含 ownerId + assigneeUserIds；编辑时不含） */
    type SaveProjectExecutionParams = CreateProjectExecutionParams;

    /** 编辑执行入参（不含 ownerId / assigneeUserIds） */
    interface UpdateProjectExecutionParams {
      executionName: string;
      executionType: string;
      projectRequirementId: string | null;
      plannedStartDate: string | null;
      plannedEndDate: string | null;
      executionDesc: string | null;
    }

    interface ChangeExecutionOwnerParams {
      newOwnerId: string;
      reason: string | null;
    }

    interface ChangeExecutionStatusParams {
      actionCode: ProjectExecutionActionCode;
      reason: string | null;
    }

    interface CreateExecutionAssigneeParams {
      userId: string;
    }

    interface InactiveExecutionAssigneeParams {
      reason: string;
    }

    type ProjectTaskSearchParams = CommonType.RecordNullable<
      Pick<PageParams, 'pageNo' | 'pageSize'> & {
        keyword: string;
        parentTaskId: string;
        ownerId: string;
        statusCode: string;
        updateTime: string[];
      }
    >;

    type ProjectTaskStatusBoardParams = CommonType.RecordNullable<{
      keyword: string;
      parentTaskId: string;
      ownerId: string;
      updateTime: string[];
    }>;

    interface SaveProjectTaskParams {
      parentTaskId: string | null;
      taskTitle: string;
      ownerId: string | null;
      progressRate?: number;
      plannedStartDate: string | null;
      plannedEndDate: string | null;
      taskDesc: string | null;
      /** 仅创建任务时生效，编辑接口静默忽略；userId 必须是当前有效执行协办人且不能等于 ownerId */
      assigneeUserIds?: string[];
      /** 编辑语义：null 保留原值 / [] 清空 / [...] 整体替换 */
      attachments?: AttachmentItem[] | null;
    }

    interface ChangeTaskStatusParams {
      actionCode: ProjectTaskActionCode;
      reason: string | null;
    }

    /** 任务工时记录 */
    interface TaskWorklog {
      id: string;
      taskId: string;
      userId: string;
      userNickname: string | null;
      /** 段起始日期（含），YYYY-MM-DD；单天=与 endDate 相等 */
      startDate: string;
      /** 段结束日期（含），YYYY-MM-DD；单天=与 startDate 相等 */
      endDate: string;
      /** 本次填报小时数（BigDecimal，0.5 颗粒，> 0） */
      durationHours: number;
      /** 本次填报进度（0~100，scale=2） */
      progressRate: number;
      workContent: string | null;
      attachments?: AttachmentItem[] | null;
      createTime: string;
      updateTime: string;
    }

    type TaskWorklogSearchParams = CommonType.RecordNullable<
      Pick<PageParams, 'pageNo' | 'pageSize'> & {
        userId: string;
        startDate: string;
        endDate: string;
      }
    >;

    interface SaveTaskWorklogParams {
      /** 段起始日期（含），YYYY-MM-DD */
      startDate: string;
      /** 段结束日期（含），YYYY-MM-DD；不得早于 startDate */
      endDate: string;
      /** 本次填报小时数，> 0 且 0.5 整数倍 */
      durationHours: number;
      /** 本次填报进度（0~100，scale=2，必填） */
      progressRate: number;
      workContent?: string | null;
      /** 编辑语义：null 保留原值 / [] 清空 / [...] 替换 */
      attachments?: AttachmentItem[] | null;
    }

    /** 项目设置参数 */
    interface ProjectSettings {
      baseInfo: ProjectSettingBaseInfo;
      lifecycle: ProjectLifecycleInfo;
    }

    /** 项目设置基础信息参数 */
    interface UpdateProjectSettingBaseInfoParams {
      projectName: string;
      directionCode: string;
      projectType: string;
      plannedStartDate: string | null;
      plannedEndDate: string | null;
      projectDesc: string | null;
    }

    /** 项目成员状态 */
    type ProjectMemberStatus = 0 | 1;

    interface PageParams {
      pageNo: number;
      pageSize: number;
    }

    interface PageResult<T = any> {
      total: number;
      list: T[];
    }

    /** 项目入口页概览统计 */
    interface ProjectOverviewSummary {
      /** 项目状态数量映射，key 为后端状态编码 */
      statusCounts: Record<string, number>;
    }

    interface Project {
      /** 项目 ID */
      id: string;
      /** 项目编码 */
      projectCode: string;
      /** 项目名称 */
      projectName: string;
      /** 项目方向字典值 */
      directionCode: string;
      /** 项目类型字典值 */
      projectType: string;
      /** 所属产品 ID */
      productId: string | null;
      /** 所属产品名称 */
      productName?: string | null;
      /** 项目负责人用户 ID */
      managerUserId: string;
      /** 项目负责人用户昵称 */
      managerUserNickname?: string | null;
      /** 项目状态编码 */
      statusCode: ProjectStatusCode;
      /** 计划开始日期 */
      plannedStartDate: string | null;
      /** 计划结束日期 */
      plannedEndDate: string | null;
      /** 实际开始日期 */
      actualStartDate: string | null;
      /** 实际结束日期 */
      actualEndDate: string | null;
      /** 进度百分比 */
      progressRate: number;
      /** 项目说明 */
      projectDesc: string | null;
      /** 最近一次状态动作原因 */
      lastStatusReason: string | null;
      /** 创建时间 */
      createTime: string;
      /** 更新时间 */
      updateTime: string;
    }

    interface ProjectContext {
      currentProject: {
        id: string;
        projectCode: string;
        projectName: string;
        projectType: string;
        productId: string | null;
        managerUserId: string;
        statusCode: ProjectStatusCode;
      };
      currentRole: {
        roleId: string | null;
        roleCode: string | null;
        roleName: string | null;
        guestFlag: boolean;
      };
      navs: Array<{
        id: string;
        name: string;
        path: string;
        icon: string;
        sort: number;
      }>;
      buttons: string[];
    }

    interface ProjectMember {
      /** 成员关系 ID */
      id: string;
      /** 用户 ID */
      userId: string;
      /** 用户昵称 */
      userNickname: string;
      /** 角色 ID */
      roleId: string;
      /** 角色名称 */
      roleName: string;
      /** 角色编码 */
      roleCode: string;
      /** 是否项目负责人 */
      managerFlag: boolean;
      /** 成员状态 */
      status: ProjectMemberStatus;
      /** 加入时间 */
      joinedTime: string;
      /** 退出时间 */
      leftTime: string | null;
      /** 备注 */
      remark: string | null;
    }

    /** 项目搜索参数 */
    type ProjectSearchParams = CommonType.RecordNullable<
      Pick<PageParams, 'pageNo' | 'pageSize'> & {
        keyword: string;
        directionCode: string;
        projectType: string;
        productId: string;
        managerUserId: string;
        statusCode: ProjectStatusCode;
        updateTime: string[];
      }
    >;

    /** 创建/保存项目参数 */
    type SaveProjectParams = Pick<Project, 'projectName' | 'directionCode' | 'projectType' | 'projectDesc'> & {
      projectCode: string | null;
      productId: string | null;
      managerUserId: string;
      plannedStartDate: string | null;
      plannedEndDate: string | null;
      actualStartDate?: string | null;
      actualEndDate?: string | null;
    };

    /** 更新项目参数 */
    type UpdateProjectParams = { id: string } & SaveProjectParams;

    /** 变更项目状态参数 */
    interface ChangeProjectStatusParams {
      id: string;
      actionCode: ProjectStatusActionCode;
      reason: string | null;
    }

    /** 删除项目参数 */
    interface DeleteProjectParams {
      id: string;
      projectName: string;
      confirmText: string;
      reason: string;
    }

    /** 删除执行入参 */
    interface DeleteProjectExecutionParams {
      /** 二次确认：必须与当前执行名称完全一致 */
      executionName: string;
      /** 删除确认口令：接受 "删除" 或 "DELETE" */
      confirmText: string;
      /** 删除原因，写入审计日志 */
      reason: string;
    }

    /** 删除任务入参 */
    interface DeleteProjectTaskParams {
      /** 二次确认：必须与当前任务名称完全一致 */
      taskName: string;
      /** 删除确认口令：接受 "删除" 或 "DELETE" */
      confirmText: string;
      /** 删除原因，写入审计日志 */
      reason: string;
    }

    /** 创建项目成员参数 */
    interface CreateProjectMemberParams {
      userId: string;
      roleId: string;
      remark: string | null;
      previousManagerUserId?: string | null;
      previousManagerRoleId?: string | null;
    }

    /** 更新项目成员参数 */
    interface UpdateProjectMemberParams {
      roleId: string;
      reason: string | null;
      remark: string | null;
      previousManagerUserId?: string | null;
      previousManagerRoleId?: string | null;
    }

    /** 移出项目成员参数 */
    interface InactiveProjectMemberParams {
      reason: string | null;
    }

    /**
     * 项目创建（含初始团队）原子接口参数
     *
     * 新增项目两步向导提交的载荷。经理成员也由前端聚合到 members 数组中。
     */
    interface CreateProjectWithTeamParams {
      project: SaveProjectParams;
      members: CreateProjectMemberParams[];
    }

    // ========== 项目需求相关类型定义 ==========
    /** 项目需求状态编码 */
    type ProjectRequirementStatusCode =
      | 'pending_confirm'
      | 'pending_review'
      | 'implementing'
      | 'accepted'
      | 'closed'
      | 'rejected'
      | 'cancelled';

    /** 项目需求来源类型 */
    type ProjectRequirementSourceType = 'manual' | 'work_order' | 'product_requirement';

    /** 项目需求优先级 */
    type ProjectRequirementPriority = 0 | 1 | 2 | 3;

    /** 是否需要评审 */
    type ProjectRequirementReviewRequired = 0 | 1;

    interface ProjectRequirement {
      /** 需求 ID */
      id: string;
      /** 所属项目 ID */
      projectId: string;
      /** 父需求 ID，0 表示顶级需求 */
      parentId: string;
      /** 所属模块 ID */
      moduleId: string;
      /** 是否需要评审 */
      reviewRequired: ProjectRequirementReviewRequired;
      /** 需求标题 */
      title: string;
      /** 需求描述 */
      description?: string | null;
      /** 需求分类字典值 */
      category: string;
      /** 需求分类名称 */
      categoryName?: string | null;
      /** 需求来源类型 */
      sourceType: ProjectRequirementSourceType;
      /** 来源业务 ID */
      sourceBizId?: string | null;
      /** 优先级 */
      priority: ProjectRequirementPriority;
      /** 优先级名称 */
      priorityName?: string | null;
      /** 当前状态编码 */
      statusCode: ProjectRequirementStatusCode;
      /** 当前状态名称 */
      statusName?: string | null;
      /** 最近一次状态动作原因 */
      lastStatusReason?: string | null;
      /** 提出人用户 ID */
      proposerId: string;
      /** 提出人昵称 */
      proposerNickname?: string | null;
      /** 当前处理人用户 ID */
      currentHandlerUserId?: string | null;
      /** 当前处理人昵称 */
      currentHandlerUserNickname?: string | null;
      /** 所需工时 */
      workHours: number;
      /** 排序值 */
      sort: number;
      /** 创建时间 */
      createTime: string;
      /** 更新时间 */
      updateTime: string;
      /** 子需求列表 */
      children?: ProjectRequirement[];
      /** 是否终态 */
      terminal?: boolean;
    }

    interface ProjectRequirementModule {
      /** 模块 ID */
      id: string;
      /** 父模块 ID，0 表示顶级 */
      parentId: string;
      /** 所属项目 ID */
      projectId: string;
      /** 模块名称 */
      moduleName: string;
      /** 模块说明 */
      remark?: string | null;
      /** 图标 */
      icon?: string | null;
      /** 排序值 */
      sort: number;
      /** 子模块列表 */
      children?: ProjectRequirementModule[];
    }

    interface ProjectRequirementStatusDict {
      /** 状态编码 */
      statusCode: string;
      /** 状态名称 */
      statusName: string;
      /** 排序值 */
      sort: number;
      /** 是否初始状态 */
      initialFlag: boolean;
      /** 是否终态 */
      terminalFlag: boolean;
    }

    interface ProjectRequirementLifecycleAction {
      actionCode: string;
      actionName: string;
      toStatusCode: string;
      toStatusName: string;
      needReason: boolean;
    }

    interface ProjectRequirementLifecycleInfo {
      statusCode: ProjectRequirementStatusCode;
      statusName?: string | null;
      lastStatusReason?: string | null;
      terminal: boolean;
      allowEdit: boolean;
      availableActions: ProjectRequirementLifecycleAction[];
    }

    /** 项目需求分页查询参数 */
    type ProjectRequirementSearchParams = CommonType.RecordNullable<
      Pick<PageParams, 'pageNo' | 'pageSize'> &
        Pick<
          ProjectRequirement,
          'moduleId' | 'parentId' | 'category' | 'priority' | 'statusCode' | 'currentHandlerUserId' | 'sourceType'
        > & {
          projectId: string;
          title: string;
        }
    >;

    /** 创建项目需求参数 */
    type SaveProjectRequirementParams = Pick<
      ProjectRequirement,
      | 'projectId'
      | 'moduleId'
      | 'reviewRequired'
      | 'title'
      | 'description'
      | 'category'
      | 'priority'
      | 'proposerId'
      | 'proposerNickname'
      | 'currentHandlerUserId'
      | 'currentHandlerUserNickname'
      | 'workHours'
      | 'sort'
    >;

    /** 更新项目需求参数 */
    type UpdateProjectRequirementParams = { id: string } & SaveProjectRequirementParams;

    /** 变更项目需求状态参数 */
    interface ChangeProjectRequirementStatusParams {
      id: string;
      projectId: string;
      actionCode: string;
      reason?: string | null;
    }

    /** 关闭项目需求参数 */
    interface CloseProjectRequirementParams {
      id: string;
      projectId: string;
      reason: string;
    }

    /** 拆分项目需求参数 */
    type SplitProjectRequirementParams = Pick<
      ProjectRequirement,
      | 'parentId'
      | 'projectId'
      | 'moduleId'
      | 'reviewRequired'
      | 'title'
      | 'description'
      | 'category'
      | 'priority'
      | 'proposerId'
      | 'proposerNickname'
      | 'currentHandlerUserId'
      | 'currentHandlerUserNickname'
      | 'workHours'
      | 'sort'
    >;

    /** 删除项目需求参数 */
    interface DeleteProjectRequirementParams {
      id: string;
      projectId: string;
    }

    /** 保存项目需求模块参数 */
    interface SaveProjectRequirementModuleParams {
      id?: string;
      projectId: string;
      parentId?: string | null;
      moduleName: string;
      remark?: string | null;
      icon?: string | null;
      sort?: number;
    }

    /** 删除项目需求模块参数 */
    interface DeleteProjectRequirementModuleParams {
      id?: string;
      projectId: string;
    }
  }
}