package com.ruoyi.common.utils.translation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * 额外字典翻译字段注解, 用来代替无法使用Excel注解的情况, 优先级大于Excel注解
 * 优先级(5种):
 *     sql [+ referenceProperty]: 单条SQL语句: 建议加上LIMIT 1, 多条时取第一条, 必须指定占位符?. 例如: @Translate(sql = "SELECT * FROM t_finance_book WHERE id = ? LIMIT 1")
 *     table + tableKeyColumn + tableValueColumn [+ referenceProperty]: 拼接为 SELECT `tableValueColumn` FROM `table` WHERE `tableKeyColumn` = ? LIMIT 1. 例如: @Translate(table = "t_finance_book", tableValueColumn = "book_name", tableKeyColumn = "id")
 *
 *     dictSql + tableKeyColumn + tableValueColumn: 执行查询SQL后, 取tableKeyColumn(), tableValueColumn()作为字典键值. 例如: @Translate(dictSql = "SELECT * FROM t_finance_book", tableValueColumn = "book_name", tableKeyColumn = "id")
 *     readConverterExp
 *     dictType
 *
 * 前两种方式使用待翻译字段值直查
 * 后三种都是加载对应键值字典, 然后用待翻译字段值匹配. 如果都指定了, 会按优先级混合在一起, 优先级高的覆盖优先级低的
 *
 * 关于referenceProperty
 *     如果带翻译字段为Long的其他表ID, 如:
 *     private Long bookId;
 *     如果需要翻译bookId
 *         一种方法是将bookId设为String类型
 *         还有一种方法是声明String类型的属性辅助翻译bookId, 该新属性不需要原来本身就有bookId的值, 如
 *         @Translate(table = "t_finance_book", tableKeyColumn = "id", tableValueColumn = "book_name", referenceProperty = "bookId") // 引用bookId属性的值
 *         // @Translate(sql = "SELECT * FROM t_finance_book WHERE id = ? LIMIT 1", referenceProperty = "bookId") // 也可以写成这样
 *         private String bookName; // bookName的值不需要读取, 只写入
 *     private Long typeId;
 *         @Translate(dictType = "dict_xxx_type", referenceProperty = "typeId") // 引用typeId属性的值
 *         private String typeName; // typeName的值不需要读取, 只写入
 *
 * @author zhao
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
public @interface Translate
{
    /**
     * 如果是字典类型，请设置字典的type值 (如: sys_user_sex)
     */
    public String dictType() default "";

    /**
     * 读取内容转表达式 (如: 0=男,1=女,2=未知)
     */
    public String readConverterExp() default "";

    // 查询数据库字典, 字段必须为String, 不能为Long/Integer等数字型
    // 方式1: SQL, ?号占位
    public String sql() default "";
    // 方式2: 表名 + 对应列名 + 名称列
    // 拼接为 SELECT tableValueColumn() FROM table() WHERE tableKeyColumn() = ? LIMIT 1
    public String table() default ""; // 表名
    public String tableKeyColumn() default "id"; // 键的列名
    public String tableValueColumn() default "name"; // 值的列名
    public String referenceProperty() default ""; // 引用其他类成员属性
    // 方式3: SQL + 对应列名 + 名称列: 无占位符, 从数据库加载键值对
    // 执行查询SQL后, 取tableKeyColumn(), tableValueColumn()作为字典键值
    public String dictSql() default "";
}