package com.njcn.rdms.module.project.service.product;

import com.njcn.rdms.framework.common.pojo.PageResult;
import com.njcn.rdms.module.project.controller.admin.product.vo.product.ProductContextRespVO;
import com.njcn.rdms.module.project.controller.admin.product.vo.product.ProductCreateWithTeamReqVO;
import com.njcn.rdms.module.project.controller.admin.product.vo.product.ProductDeleteReqVO;
import com.njcn.rdms.module.project.controller.admin.product.vo.product.ProductOptionRespVO;
import com.njcn.rdms.module.project.controller.admin.product.vo.product.ProductOverviewSummaryRespVO;
import com.njcn.rdms.module.project.controller.admin.product.vo.product.ProductPageReqVO;
import com.njcn.rdms.module.project.controller.admin.product.vo.product.ProductRespVO;
import com.njcn.rdms.module.project.controller.admin.product.vo.product.ProductSaveReqVO;
import com.njcn.rdms.module.project.controller.admin.product.vo.product.ProductStatusActionReqVO;
import com.njcn.rdms.module.project.controller.admin.product.vo.setting.ProductSettingBaseInfoUpdateReqVO;
import com.njcn.rdms.module.project.dal.dataobject.product.ProductDO;

import java.util.List;

/**
 * 产品 Service 接口
 */
public interface ProductService {

    /**
     * 创建产品
     *
     * @param createReqVO 创建请求
     * @return 产品编号
     */
    Long createProduct(ProductSaveReqVO createReqVO);

    /**
     * 创建产品并初始化团队（原子接口）。
     *
     * <p>由前端"产品两步向导"一次性提交，产品基础资料与全部初始团队成员
     * 必须在同一事务内完成写入；任一步失败整体回滚。
     *
     * <p>与 {@link #createProduct(ProductSaveReqVO)} 的关键差异：经理成员
     * 由前端在 {@code members} 中显式提交，后端不再根据
     * {@code product.managerUserId} 自动追加，因此需要校验
     * {@code members} 中必须存在 userId 等于 managerUserId 的记录。
     *
     * @param reqVO 创建请求（产品 + 初始团队）
     * @return 产品编号
     */
    Long createProductWithTeam(ProductCreateWithTeamReqVO reqVO);

    /**
     * 更新产品
     *
     * @param updateReqVO 更新请求
     */
    void updateProduct(ProductSaveReqVO updateReqVO);

    /**
     * 更新产品设置页基础信息
     *
     * @param productId 产品编号
     * @param reqVO 更新请求
     */
    void updateProductBaseInfo(Long productId, ProductSettingBaseInfoUpdateReqVO reqVO);

    /**
     * 获取产品详情
     *
     * @param id 产品编号
     * @return 产品信息
     */
    ProductDO getProduct(Long id);

    /**
     * 获取产品上下文
     *
     * @param id 产品编号
     * @return 产品上下文
     */
    ProductContextRespVO getProductContext(Long id);

    /**
     * 获取产品分页
     *
     * <p>每个列表项含「当前登录用户在该产品担任的角色」（{@code currentUserRoles}），无角色为空数组。
     *
     * @param pageReqVO 分页请求
     * @return 分页结果
     */
    PageResult<ProductRespVO> getProductPage(ProductPageReqVO pageReqVO);

    /**
     * 获取产品入口页概览统计
     *
     * @return 产品入口页概览统计
     */
    ProductOverviewSummaryRespVO getProductOverviewSummary();

    /**
     * 获取可绑定产品下拉选项。
     *
     * @return 产品下拉选项
     */
    List<ProductOptionRespVO> getProductOptions();

    /**
     * 变更产品状态
     *
     * @param reqVO 状态动作请求
     */
    void changeProductStatus(ProductStatusActionReqVO reqVO);

    /**
     * 删除产品
     *
     * @param reqVO 删除请求
     */
    void deleteProduct(ProductDeleteReqVO reqVO);

}
