package jnpf.limsService;

import jnpf.base.service.SuperService;
import jnpf.limsEntity.LimsModifySignPasswordParam;
import jnpf.limsEntity.LimsSignEntity;
import jnpf.limsEntity.LimsSignUsageTarget;
import jnpf.limsEntity.LimsSignVerifyParam;
import jnpf.limsEntity.SignOpType;

import java.util.Collection;

/**
 * LIMS 电子签名服务。
 * 校验账户 + 签名密码后落一条 lims_sign，返回主键作为 biz_sign 凭证给前端。
 */
public interface LimsSignService extends SuperService<LimsSignEntity> {

    /**
     * 校验签名并落 lims_sign 一条，返回新记录的主键 id（即给前端的 biz_sign）。
     *
     * <p>校验链：
     * <ol>
     *   <li>opType 必须在 {@link jnpf.limsEntity.SignOpType} 枚举内</li>
     *   <li>accountName 必须等于当前 session 用户的 account（防代签）</li>
     *   <li>note 非空（前端可填 "N/A"）</li>
     *   <li>查 lims_user_sign_password by user_id；无记录 → 抛 "未初始化签名密码"</li>
     *   <li>password_hash = Md5(password + secretkey.toLowerCase()) 比对</li>
     *   <li>校验全通过后插入 lims_sign，返回 id</li>
     * </ol>
     *
     * @return lims_sign 主键 id
     * @throws jnpf.exception.DataException 校验失败
     */
    String verifyAndRecord(LimsSignVerifyParam param);

    /**
     * 校验指定用户签名并落 lims_sign 一条。
     *
     * <p>与 {@link #verifyAndRecord(LimsSignVerifyParam)} 的差异：
     * <ul>
     *   <li>allowSelf 不为 yes 时，accountName 对应的用户不能是当前 session 用户</li>
     *   <li>按 accountName 查询目标用户，并校验目标用户的签名密码</li>
     *   <li>签名记录的 creatorUserId 写入目标用户 id</li>
     * </ul>
     *
     * @return 校验通过后新建的签名记录
     */
    LimsSignEntity verifyUserAndRecord(LimsSignVerifyParam param);

    /**
     * 给所有未软删 base_user 批量初始化签名密码 = "123456"。
     * 已有 lims_user_sign_password 记录的跳过。每个用户独立生成 secretkey。
     *
     * @return [插入条数, 跳过条数]
     */
    int[] initAllUsers();

    /**
     * 修改 / 初始化当前登录用户的签名密码。
     *
     * <p>校验链：
     * <ol>
     *   <li>code + timestamp 命中图形验证码缓存（不区分大小写）</li>
     *   <li>当前 session 用户存在</li>
     *   <li>accountPassword 通过 Md5(accountPassword + secretkey) 比对 base_user.f_password</li>
     *   <li>password / repeatPassword 均非空且相等</li>
     *   <li>生成新的 secretkey 与 hash，写入 / 更新 lims_user_sign_password，刷新 last_reset_time</li>
     * </ol>
     *
     * <p>用户首次设置签名密码（未存在 lims_user_sign_password 记录）和后续修改走同一接口，
     * 行为分别为 INSERT 与 UPDATE。
     *
     * @throws jnpf.exception.DataException 任一校验失败
     */
    void modifySignPassword(LimsModifySignPasswordParam param);

    /**
     * 校验业务侧传入的 biz_sign（即 lims_sign 主键）真实有效。
     *
     * <p>op_type 与 data_id 各自独立支持 lazy / eager（自方案 C 起）：
     * <ul>
     *   <li>字段为空 → 仅在返回实体中补全业务期望值，暂不写库</li>
     *   <li>字段已有值 → 严格校验与业务期望匹配，不符抛 DataException</li>
     * </ul>
     * 真正认领由 {@link #recordSignUsage} 在业务成功后原子完成，避免状态冲突时提前消费签名。
     * 已有 {@code extra_json} 的签名视为已消费，必须重新签名，不能跨业务周期复用。
     *
     * <p>expectedDataId 传 null = 业务接口不需要 data_id 锚点（如 jiance-task 批量类），
     * 此时完全跳过 data_id 校验，保留 verify 时的原值不动。
     *
     * <p>签名人始终校验：必须等于当前 session 用户（防别人签的被偷用）。
     *
     * @param signId         前端回传的 biz_sign（lims_sign 主键）
     * @param expectedOpType 业务期望的操作类型
     * @param expectedDataId 业务期望的 data_id；传 null 表示不锚 data_id
     * @return 校验通过的签名记录
     */
    LimsSignEntity requireValidSign(String signId, SignOpType expectedOpType, String expectedDataId);

    /**
     * 在业务写库成功后记录签名被实际使用的事实。
     *
     * <p>只接受业务 service 返回的实际成功目标；请求中因状态、权限或并发被跳过的目标不得传入。
     * 实际目标为空时不认领签名、不更新 {@code lims_sign.extra_json}，也不生成 {@code SIGN_USED}。
     * 非空时先通过条件更新一次性原子认领签名，再将事件交给 AuditTxHolder 在事务提交后发布；
     * 已消费签名、认领冲突或结果保存失败会标记当前事务回滚。
     */
    void recordSignUsage(LimsSignEntity sign,
                         SignOpType opType,
                         Collection<String> requestedTargetIds,
                         Collection<LimsSignUsageTarget> actualTargets);

    /**
     * 只做签名的原子认领，<b>不发审计事件</b>。
     *
     * <p>给「签名事实由别处记录」的调用方用——当前是在线表单路径：表单保存本身已经产生层 0
     * 事件，层 0 会据表单里的签名字段补写一条签名事件；这里再发一条 {@code SIGN_USED}
     * 就是同一次签名两条证据。
     *
     * <p><b>认领逻辑必须保留</b>：它是「签名单次消费」的防重放护栏（ed4d908），
     * 去掉等于同一个签名可以反复使用。
     *
     * <p>与 {@link #recordSignUsage} 的关系是「同一段认领 + 是否再发事件」：
     * {@code recordSignUsage} 内部就调本方法，两处认领逻辑只有一份，不会各自漂移。
     * 认领的全部前置条件（空目标不认领、认领冲突标记事务回滚）与 {@code recordSignUsage} 完全一致。
     */
    void claimSignUsageOnly(LimsSignEntity sign,
                            SignOpType opType,
                            Collection<String> requestedTargetIds,
                            Collection<LimsSignUsageTarget> actualTargets);

    /**
     * 把任意结构数据序列化为 JSON 后回写到 lims_sign.extra_json。
     *
     * <p>典型用法：
     * <ul>
     *   <li>jiance-task 批量类把 ids 包成 {"targets":[...]} 落库</li>
     *   <li>业务想加结构化操作日志：{"targets":[...],"comments":"..."}</li>
     * </ul>
     *
     * <p>extra 为 null 时不更新。重复调用会覆盖（业务最新一次最权威）。
     *
     * @param signId 签名记录主键（即 biz_sign）
     * @param extra  任意可序列化对象（Map / List / POJO 都可）
     */
    void attachExtra(String signId, Object extra);
}