cn-rdms-web/src/typings/api/product.d.ts

declare namespace Api {
  /**
   * namespace Product
   *
   * backend api module: "project/product"
   */
  namespace Product {
    type ProductStatusCode = 'active' | 'paused' | 'archived' | 'abandoned';

    type ProductStatusActionCode = 'pause' | 'resume' | 'archive' | 'abandon';

    type ProductMemberStatus = 0 | 1;

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

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

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

    interface Product {
      /** 产品 ID */
      id: string;
      /** 产品编码 */
      code: string;
      /** 产品方向字典值 */
      directionCode: string;
      /** 产品名称 */
      name: string;
      /** 产品经理用户 ID */
      managerUserId: string;
      /** 产品描述 */
      description?: string | null;
      /** 产品状态编码 */
      statusCode: ProductStatusCode;
      /** 最近一次状态动作原因 */
      lastStatusReason?: string | null;
      /** 备注 */
      remark?: string | null;
      /** 创建时间 */
      createTime: string;
      /** 更新时间 */
      updateTime: string;
    }

    interface ProductSettingBaseInfo {
      /** 产品 ID */
      id: string;
      /** 产品编码 */
      code: string;
      /** 产品方向字典值 */
      directionCode: string;
      /** 产品名称 */
      name: string;
      /** 产品经理用户 ID */
      managerUserId: string;
      /** 产品经理昵称 */
      managerUserNickname: string;
      /** 产品描述 */
      description?: string | null;
      /** 当前产品状态 */
      statusCode: ProductStatusCode;
      /** 最近一次状态动作原因 */
      lastStatusReason?: string | null;
    }

    interface ProductLifecycleAction {
      actionCode: ProductStatusActionCode;
      actionName: string;
      needReason: boolean;
    }

    interface ProductLifecycleInfo {
      statusCode: ProductStatusCode;
      lastStatusReason?: string | null;
      availableActions: ProductLifecycleAction[];
    }

    interface ProductSettings {
      baseInfo: ProductSettingBaseInfo;
      lifecycle: ProductLifecycleInfo;
    }

    interface ProductMember {
      /** 团队关系 ID */
      id: string;
      /** 用户 ID */
      userId: string;
      /** 用户昵称 */
      userNickname: string;
      /** 角色 ID */
      roleId: string;
      /** 角色名称 */
      roleName: string;
      /** 角色编码 */
      roleCode: string;
      /** 是否当前产品经理 */
      managerFlag: boolean;
      /** 成员状态 */
      status: ProductMemberStatus;
      /** 加入时间 */
      joinedTime: string;
      /** 退出时间 */
      leftTime?: string | null;
      /** 备注 */
      remark?: string | null;
    }

    type ProductActivityType = 'status' | 'product' | 'member';

    type ProductActivityActionType =
      | 'create'
      | 'change_manager'
      | 'pause'
      | 'resume'
      | 'archive'
      | 'abandon'
      | 'add_member'
      | 'update_member'
      | 'remove_member';

    interface ProductActivityTimelinePageParams extends PageParams {
      /** 分类 */
      activityType?: ProductActivityType | null;
      /** 动作编码数组，多选时按重复 query 参数传递 */
      actionTypes?: ProductActivityActionType[] | null;
      /** 开始时间，格式 yyyy-MM-dd HH:mm:ss */
      startTime?: string | null;
      /** 结束时间，格式 yyyy-MM-dd HH:mm:ss */
      endTime?: string | null;
    }

    interface ProductActivityTimelineItem {
      /** 动态唯一标识 */
      id: string;
      /** 动态类型 */
      type: ProductActivityType;
      /** 动作编码 */
      actionType: ProductActivityActionType;
      /** 动作中文名称 */
      actionName: string;
      /** 操作人用户 ID */
      operatorUserId?: string | null;
      /** 操作人名称 */
      operatorName: string;
      /** 目标用户 ID，成员类动态使用 */
      targetUserId?: string | null;
      /** 目标用户名称，成员类动态使用 */
      targetUserName?: string | null;
      /** 动态发生时间，毫秒时间戳 */
      occurredAt: number;
      /** 可直接展示的摘要文案 */
      summary: string;
      /** 原因说明 */
      reason?: string | null;
      /** 原状态编码 */
      fromStatus?: ProductStatusCode | null;
      /** 目标状态编码 */
      toStatus?: ProductStatusCode | null;
      /** 补充明细，当前为 JSON 字符串 */
      details?: string | null;
    }

    type ProductSearchParams = CommonType.RecordNullable<
      Pick<PageParams, 'pageNo' | 'pageSize'> &
        Pick<Product, 'directionCode' | 'managerUserId' | 'statusCode'> & {
          keyword: string;
          updateTime: string[];
        }
    >;

    type SaveProductParams = Pick<Product, 'directionCode' | 'name' | 'managerUserId'> & {
      code?: string | null;
      description?: string | null;
      remark?: string | null;
    };

    type UpdateProductParams = { id: string } & SaveProductParams;

    interface ChangeProductStatusParams {
      id: string;
      actionCode: ProductStatusActionCode;
      reason?: string | null;
    }

    interface DeleteProductParams {
      id: string;
      productName: string;
      reason: string;
    }

    type UpdateProductSettingBaseInfoParams = Pick<ProductSettingBaseInfo, 'directionCode' | 'name'> & {
      description?: string | null;
    };

    interface CreateProductMemberParams {
      userId: string;
      roleId: string;
      remark?: string | null;
      previousManagerUserId?: string | null;
      previousManagerRoleId?: string | null;
    }

    /**
     * 批量新增产品成员参数
     *
     * 刻意不复用 CreateProductMemberParams：批量接口不承担「产品经理交接」语义，
     * 后端兜底拒绝 roleId 为产品经理角色的项。
     */
    interface BatchCreateProductMembersParams {
      members: Array<{
        userId: string;
        roleId: string;
        remark?: string | null;
      }>;
    }

    /**
     * 产品创建（含初始团队）原子接口参数
     *
     * 新增产品两步向导提交的载荷。经理成员也由前端聚合到 members 数组中。
     */
    interface CreateProductWithTeamParams {
      product: SaveProductParams;
      members: CreateProductMemberParams[];
      /** 关注人 user_id 数组（选填）；后端按 (user, object, role) 三元组幂等写入 product_watcher 角色 */
      watcherUserIds?: string[];
    }

    interface UpdateProductMemberParams {
      roleId: string;
      remark?: string | null;
      reason?: string | null;
      previousManagerUserId?: string | null;
      previousManagerRoleId?: string | null;
    }

    interface InactiveProductMemberParams {
      reason?: string | null;
    }

    interface BatchInactiveProductMembersParams {
      memberIds: string[];
      reason?: string | null;
    }

    // ========== 产品需求相关类型定义 ==========
    /** 需求状态编码 */
    type RequirementStatusCode =
      | 'pending_claim'
      | 'pending_review'
      | 'pending_dispatch'
      | 'reviewed'
      | 'review_rejected'
      | 'implementing'
      | 'accepted'
      | 'closed'
      | 'rejected'
      | 'cancelled';

    /** 需求状态动作编码 */
    type RequirementStatusActionCode =
      | 'claim_to_review'
      | 'claim_to_dispatch'
      | 'pass_review'
      | 'reject_review'
      | 'dispatch'
      | 'cancel'
      | 'accept'
      | 'close'
      | 'reject';

    /** 需求来源类型 */
    type RequirementSourceType = 'manual' | 'work_order';

    /** 需求优先级 */
    type RequirementPriority = 0 | 1 | 2 | 3;

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

    // ========== 需求实体 ==========

    interface Requirement {
      /** 需求编号 */
      id: string;
      /** 产品 ID */
      productId: string;
      /** 父需求编号（0表示顶级需求） */
      parentId: string;
      /** 所属模块编号 */
      moduleId: string;
      /** 是否需要评审（0不需要；1需要） */
      reviewRequired: RequirementReviewRequired;
      /** 需求名称 */
      title: string;
      /** 需求内容（富文本） */
      description?: string | null;
      /** 附件列表 */
      attachments?: Api.Project.AttachmentItem[] | null;
      /** 需求类型字典值 */
      category: string;
      /** 需求类型名称 */
      categoryName?: string | null;
      /** 需求来源类型 */
      sourceType: RequirementSourceType;
      /** 需求来源业务ID */
      sourceBizId?: string | null;
      /** 优先级（0低 1中 2高 3紧急） */
      priority: RequirementPriority;
      /** 优先级名称 */
      priorityName?: string | null;
      /** 当前状态编码 */
      statusCode: RequirementStatusCode;
      /** 当前状态名称 */
      statusName?: string | null;
      /** 最近一次状态动作原因 */
      lastStatusReason?: string | null;
      /** 提出人用户编号 */
      proposerId: string;
      /** 提出人用户姓名 */
      proposerNickname?: string | null;
      /** 当前处理人用户编号 */
      currentHandlerUserId?: string | null;
      /** 当前处理人姓名 */
      currentHandlerUserNickname?: string | null;
      /** 默认关联项目编号 */
      implementProjectId?: string | null;
      /** 默认关联项目名称 */
      implementProjectName?: string | null;
      /** 预期完成日期 */
      expectedTime?: string | null;
      /** 排序值 */
      sort: number;
      /** 创建时间 */
      createTime: string;
      /** 更新时间 */
      updateTime: string;
      /** 子需求列表（树形结构） */
      children?: Requirement[];
    }

    // ========== 需求模块实体 ==========

    interface RequirementModule {
      /** 模块编号 */
      id: string | undefined;
      /** 父模块编号（0表示顶级） */
      parentId: string | undefined;
      /** 所属产品编号 */
      productId: string;
      /** 模块名称 */
      moduleName: string;
      /** 模块说明 */
      remark?: string | null;
      /** 图标 */
      icon?: string | null;
      /** 排序值 */
      sort: number;
      /** 子模块列表 */
      children?: RequirementModule[];
    }

    // ========== 需求状态字典 ==========

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

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

    interface RequirementBatchReqVO {
      productId: string;
      requirementIds: string[];
    }

    interface RequirementAllowedTransitionBatchRespVO {
      requirementId: string;
      transitions: RequirementLifecycleAction[];
    }

    interface RequirementHasDispatchedBatchRespVO {
      requirementId: string;
      hasDispatched: boolean;
    }

    type ProductRequirementDashboardRecentChangeActionType = 'create' | 'delete' | 'status_terminal';

    interface ProductRequirementDashboardSummary {
      /** 当前产品下所有未删除需求数，包括根需求和子需求 */
      total: number;
      /** 待认领、待评审、待指派的需求数 */
      todo: number;
      /** 待认领需求数 */
      pendingClaim: number;
      /** 待评审需求数 */
      pendingReview: number;
      /** 待指派需求数 */
      pendingDispatch: number;
      /** 已验收或已关闭需求数 */
      completed: number;
      /** 完成率，0-100 */
      completionRate: number;
      /** P0/P1 且待处理的需求数 */
      highPriorityTodo: number;
    }

    interface ProductRequirementDashboardRecentChange {
      id: string;
      requirementId?: string | null;
      title: string;
      actionType: ProductRequirementDashboardRecentChangeActionType;
      actionLabel: string;
      content: string;
      occurredAt: string;
      operatorUserId?: string | null;
      operatorName?: string | null;
    }

    interface ProductRequirementDashboard {
      summary: ProductRequirementDashboardSummary;
      recentChanges: ProductRequirementDashboardRecentChange[];
    }

    type RequirementReviewConclusion = 0 | 1;

    interface RequirementReviewAttendeeItem {
      userId: string;
      nickname: string;
    }

    interface RequirementReview {
      id: string;
      objectType: 'product_requirement';
      requirementId: string;
      operatorId: string;
      conclusion: RequirementReviewConclusion;
      reviewContent?: string | null;
      requirementEstimatedHours?: number | string | null;
      attendees?: RequirementReviewAttendeeItem[];
      attachments?: Api.Project.AttachmentItem[] | null;
      reviewTime?: string | null;
      createTime?: string;
      updateTime?: string;
    }

    interface RequirementReviewSubmitParams {
      productId: string;
      requirementId: string;
      operatorId: string;
      conclusion: RequirementReviewConclusion;
      reviewContent?: string | null;
      requirementEstimatedHours?: number | string | null;
      attendees?: RequirementReviewAttendeeItem[];
      attachments?: Api.Project.AttachmentItem[] | null;
      reviewTime?: string | null;
    }

    // ========== 请求参数类型 ==========

    /** 需求分页查询参数 */
    type RequirementSearchParams = CommonType.RecordNullable<
      Pick<PageParams, 'pageNo' | 'pageSize'> &
        Pick<
          Requirement,
          'moduleId' | 'category' | 'priority' | 'statusCode' | 'currentHandlerUserId' | 'sourceType'
        > & {
          productId: string;
          title?: string;
        }
    >;

    /** 创建需求参数 */
    type SaveRequirementParams = Pick<
      Requirement,
      | 'productId'
      | 'moduleId'
      | 'reviewRequired'
      | 'title'
      | 'description'
      | 'attachments'
      | 'category'
      | 'priority'
      | 'proposerId'
      | 'proposerNickname'
      | 'currentHandlerUserId'
      | 'currentHandlerUserNickname'
      | 'implementProjectId'
      | 'expectedTime'
      | 'sort'
    >;

    /** 更新需求参数 */
    type UpdateRequirementParams = { id: string } & SaveRequirementParams;

    /** 变更需求状态参数 */
    interface ChangeRequirementStatusParams {
      id: string;
      productId: string;
      actionCode: string;
      reason?: string | null;
      implementProjectId?: string | null;
    }

    /** 关闭需求参数 */
    interface CloseRequirementParams {
      id: string;
      productId: string;
      reason: string;
    }

    /** 拆分需求参数 */
    type SplitRequirementParams = Pick<
      Requirement,
      | 'parentId'
      | 'productId'
      | 'moduleId'
      | 'reviewRequired'
      | 'title'
      | 'description'
      | 'attachments'
      | 'category'
      | 'priority'
      | 'proposerId'
      | 'proposerNickname'
      | 'currentHandlerUserId'
      | 'currentHandlerUserNickname'
      | 'expectedTime'
      | 'sort'
    >;

    /** 删除需求参数 */
    interface DeleteRequirementParams {
      id: string;
      productId: string;
    }

    // ========== 模块请求参数 ==========

    /** 保存模块参数 */
    type SaveRequirementModuleParams = Pick<
      RequirementModule,
      'id' | 'productId' | 'parentId' | 'moduleName' | 'remark' | 'icon' | 'sort'
    >;

    /** 删除模块参数 */
    interface DeleteRequirementModuleParams {
      id: string | undefined;
      productId: string;
    }
  }
}