unis-oa/frontend/src/utils/optionSource.ts

916 lines
49 KiB
TypeScript
Raw Permalink Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

/**
* 「这一格的候选项从哪儿来、用什么姿势挑」——唯一一处口径。
*
* 以前这两件事散在三处:选项要么手填在 `options`、要么绑一张 `dictCode`;关联审批单
* 另起一炉(`relationProcess` + 一个能搜索、能显示单号与状态的弹窗);外部数据源想当选项
* 来源,只能先同步进字典再绕一圈。于是「下拉框想要一个带搜索、带副标题的弹出框」没有入口,
* 「关联审批单想挂一张物料字典」也没有入口——可这两件事本质上是同一件:**候选有一批来源,
* 挑选有多种姿势**。这里把两头收成一份配置,字段类型只回答「这一格装单个值还是一串值」。
*
* 存下来的仍然是那几个老字段(`dictCode` / `relationProcess` / `options`),
* `optionSource` 只是把「这一格用的是哪条路」写明;没写的一律按老表单推,
* 于是历史表单一个字节都不用改,读出来的行为跟今天完全一样。
* 后端镜像在 `service/dicts.py`(`source_kind_of` / `effective_options`)。
*/
import { OPTION_ARGS_AT, OPTION_ARGS_KEY, argRefProblems, sourceProblem } from '@/utils/binding'
import { optionMapProblems, pickerDisplayProblems } from '@/utils/optionMap'
import { fetchEntries } from '@/utils/formFetch'
// 浏览器口径:这一层不押 Set 迭代器与 flat,去重/取值走 utils/legacyCompat 那一份(全站规矩)
import { objValues, uniqTexts } from '@/utils/legacyCompat'
// 条件判定用的是联动那一份(后端同一句在 ``service/dicts.condition_ok``)。这两层互相引用,
// 但都在函数体里用对方,模块初始化时谁都不读谁的值——多一份 ``conditionOk`` 实现才是这里的坑。
import { conditionOk } from '@/utils/formLinkage'
import type {
DataSource,
FetchSourceEntry,
FormFieldDef,
OptionSourceKind,
OptionSourceRoute,
PickerConfig,
PickerStyle,
RouteFill
} from '@/types'
/**
* 四种来源与三种姿势的文案 key。界面自己 ``t``,工具层不碰 i18n:
* 单测好写,主表和明细列那两处也能共用同一套说法。
*/
export const OPTION_SOURCE_LABEL_KEYS: Record<OptionSourceKind, string> = {
manual: 'form.optionSourceKindManual',
dict: 'form.optionSourceKindDict',
process: 'form.optionSourceKindProcess',
dataSource: 'form.optionSourceKindDataSource'
}
/** 每种来源一句解释,说清「选了它,这一格存的到底是什么值」。 */
export const OPTION_SOURCE_HINT_KEYS: Record<OptionSourceKind, string> = {
manual: 'form.optionSourceKindHintManual',
dict: 'form.optionSourceKindHintDict',
process: 'form.optionSourceKindHintProcess',
dataSource: 'form.optionSourceKindHintDataSource'
}
export const PICKER_STYLE_LABEL_KEYS: Record<Exclude<PickerStyle, 'auto'>, string> = {
dropdown: 'form.optionSourceStyleDropdown',
dialog: 'form.optionSourceStyleDialog',
inline: 'form.optionSourceStyleInline'
}
export const PICKER_STYLE_HINT_KEYS: Record<Exclude<PickerStyle, 'auto'>, string> = {
dropdown: 'form.optionSourceStyleHintDropdown',
dialog: 'form.optionSourceStyleHintDialog',
inline: 'form.optionSourceStyleHintInline'
}
/** 能配候选来源的字段类型:三种选择类 + 两类下拉 + 关联审批单。 */
export const OPTION_SOURCE_TYPES: string[] = ['select', 'picker', 'radio', 'checkbox', 'relation']
/**
* 设计器左侧那两格下拉组件各自的本事(同一只挑选器,两种定位):
*
* - 下拉框(`select`)挂**表单自己的数据**:选项手填,或引一本数据字典;
* - 下拉选择(`picker`)挂**别处的数据**:一张外部数据源、或本平台别的流程的单据。
*
* 这是产品定位,不是技术边界——`sourceKindsOf` 那一份才是这一类字段技术上装得下的来源,
* 老表单里「下拉框挂了数据源」这类配法照旧读得出、渲染得动(见 sourceKindChoicesOf:
* 已经用上的那一条永远留在设计器下拉里,不会凭空消失)。
*/
export const OFFERED_SOURCE_KINDS: Record<string, OptionSourceKind[]> = {
select: ['manual', 'dict'],
picker: ['dataSource', 'process']
}
/** 四种来源,顺序就是设计器里下拉的顺序。 */
export const OPTION_SOURCE_KINDS: OptionSourceKind[] = ['manual', 'dict', 'process', 'dataSource']
/** 挑候选的姿势,`auto` 表示交给 `autoStyleOf` 决定。 */
export const PICKER_STYLES: PickerStyle[] = ['auto', 'dropdown', 'dialog', 'inline']
/** 天生就是平铺的一排点选:平铺是它们的本来的样子。 */
const INLINE_BY_DEFAULT: string[] = ['radio', 'checkbox']
/** 天生存一串值的类型:多选与关联审批单(两格下拉组件由字段上的 `multiple` 开关说了算)。 */
const LIST_VALUE_TYPES: string[] = ['checkbox', 'relation']
/** 能勾「可以选好几个」的两格下拉组件;与后端 `dicts.MULTIPLE_PICKER_TYPES` 同一份清单。 */
export const MULTIPLE_PICKER_TYPES: string[] = ['select', 'picker']
/** 候选是「搜出来」而不是「列出来」的来源:平铺铺不开,只给下拉和弹出框。 */
const SEARCHED_KINDS: OptionSourceKind[] = ['process', 'dataSource']
// ---------------------------------------------------------------------------
// 来源=流程单据:这一格能挂哪几种状态的单据
// ---------------------------------------------------------------------------
//
// 单据只活两张表:在办表只有 `running`,归档表里躺着 `completed`(走完并归档通过)、
// `terminated`(被终止)、`canceled`(作废)。以前「关联已审批流程」把两张表混着给人挑,
// 于是挑得到一张走到一半被终止的单子——挂一张没走完的单当依据,审批人点开对照才发现对不上。
// 现在默认只列归档通过的。三档的说法与后端 `service/dicts.py` 同一份,改一边要改另一边。
/** 归档通过 / 还在办 / 半路停下(终止与作废算一档:它们都不是「审批通过」)。 */
export type RelationStatus = 'completed' | 'running' | 'closed'
/** 界面上能勾的三档,顺序就是那一排复选框的顺序。 */
export const RELATION_STATUSES: RelationStatus[] = ['completed', 'running', 'closed']
/** 每档一句 i18n key;界面自己 `t`,工具层不碰词条。 */
export const RELATION_STATUS_LABEL_KEYS: Record<RelationStatus, string> = {
completed: 'form.relationStatusCompleted',
running: 'form.relationStatusRunning',
closed: 'form.relationStatusClosed'
}
/** 没配过这一格的表单:只给归档通过的单子。与后端 `RELATION_STATUS_DEFAULT` 同一句。 */
export const RELATION_STATUS_DEFAULT: RelationStatus[] = ['completed']
// ---------------------------------------------------------------------------
// 来源=流程单据:候选按「这是谁发起的」收
// ---------------------------------------------------------------------------
//
// 上面那三档问的是**这张单走到哪儿了**,这一档问的是**这张单算不算你的**。
// 以前只有一条路:我发起 / 我办过 / 我被抄送的并集,于是「关联流程」的下拉里一大半是
// 别人发起、我只是顺手批过的单子(原话:**「选择流程范围不应该是已办,而是只有我发起的流程」**)。
// 现在默认只给自已发起的,想要老口径就在设计器里换回「与我相关」。
// 两档的说法与后端 `service/dicts.py` 同一份,改一边要改另一边。
/** 只列我发起的 / 与我相关(我发起、我办过、我被抄送)。 */
export type RelationScope = 'created' | 'related'
/** 只给自已发起的那一档 / 与我相关的那一档(与后端同名两个常量一字不差)。 */
export const RELATION_SCOPE_CREATED: RelationScope = 'created'
export const RELATION_SCOPE_RELATED: RelationScope = 'related'
/** 界面上那一只下拉列两档,顺序就是下拉的顺序。 */
export const RELATION_SCOPES: RelationScope[] = [RELATION_SCOPE_CREATED, RELATION_SCOPE_RELATED]
/** 每一档一句 i18n key;界面自己 `t`,工具层不碰词条。 */
export const RELATION_SCOPE_LABEL_KEYS: Record<RelationScope, string> = {
created: 'form.relationScopeCreated',
related: 'form.relationScopeRelated'
}
/** 每一档那句解释,摆在下拉底下。 */
export const RELATION_SCOPE_HINT_KEYS: Record<RelationScope, string> = {
created: 'form.relationScopeHintCreated',
related: 'form.relationScopeHintRelated'
}
/** 没配过这一格的表单:只给自已发起的。与后端 `RELATION_SCOPE_DEFAULT` 同一句。 */
export const RELATION_SCOPE_DEFAULT: RelationScope = RELATION_SCOPE_CREATED
/** 这一格允许挂哪几种状态的单据;没配、配空了、配认不出的都退回默认那一档。 */
export function relationStatusesOf(field: FormFieldDef): RelationStatus[] {
const raw = field.relationStatuses
if (!Array.isArray(raw)) return [...RELATION_STATUS_DEFAULT]
const tokens = new Set(raw.map((item) => String(item).trim()))
const picked = RELATION_STATUSES.filter((item) => tokens.has(item))
return picked.length ? picked : [...RELATION_STATUS_DEFAULT]
}
/** 问候选列表时那句 `status`:三档全勾等于不限(后端把这句摊成「两张表都查、不加状态条件」)。 */
export function relationStatusQueryOf(field: FormFieldDef): string {
return relationStatusesOf(field).join(',')
}
/** 这一格的状态收窄过了没有:三档全勾就不必在弹窗里多写一行「只列……」。 */
export function relationStatusesNarrowed(field: FormFieldDef): boolean {
return relationStatusesOf(field).length < RELATION_STATUSES.length
}
/** 这一格的候选按谁收;没配、配认不出的都退回默认那一档(只给自已发起的)。 */
export function relationScopeOf(field: FormFieldDef): RelationScope {
const raw = String(field.relationScope ?? '').trim()
return (RELATION_SCOPES as string[]).includes(raw) ? (raw as RelationScope) : RELATION_SCOPE_DEFAULT
}
/**
* 问候选列表时那句 `scope`。
*
* 与状态那一句分开传:状态问的是「这张单完没走完」,范围问的是「这张单算不算你的」,
* 后端两条条件各加各的,合成一句只会让下一任配的人以为它们是一件事。
*/
export function relationScopeQueryOf(field: FormFieldDef): string {
return relationScopeOf(field)
}
/** 这一格的范围收窄过了没有:回到「与我相关」就不必在弹窗里多写那一句。 */
export function relationScopeNarrowed(field: FormFieldDef): boolean {
return relationScopeOf(field) === RELATION_SCOPE_CREATED
}
/** 这一格要不要配候选来源。 */
export function carriesOptionSource(type: string): boolean {
return OPTION_SOURCE_TYPES.includes(type)
}
/**
* 没有候选来源、却共用「用什么姿势挑」这一问的类型:多选月份。
*
* 它的候选是那一年那 12 个月,谈不上手填 / 字典 / 单据 / 数据源,但挑选姿势是同一个问题,
* 于是设计器里那一栏照摆、字段上照用 ``pickerStyle``。判"这一格要不要摆挑选方式"问下面那句,
* 别再问 carriesOptionSource——那一句只该管来源。
*/
export const STYLE_ONLY_TYPES: string[] = ['months']
/** 这一格要不要摆「挑选方式」那一栏:有候选来源的那几类,加上多选月份。 */
export function carriesStyleChoice(type: string): boolean {
return carriesOptionSource(type) || STYLE_ONLY_TYPES.includes(type)
}
/**
* 这一类字段**技术上**装得下哪几种来源(判这一格走哪条路用它;设计器给挑的清单是
* offeredSourceKinds 那一份)。
*
* 关联审批单不给「手填选项」:选项手填等于一个多选框,那一格已经有了;
* 这一类的价值就在于挂的是**别处的一批数据**。
*/
export function sourceKindsOf(type: string): OptionSourceKind[] {
if (!carriesOptionSource(type)) return []
return type === 'relation' ? OPTION_SOURCE_KINDS.filter((kind) => kind !== 'manual') : [...OPTION_SOURCE_KINDS]
}
/**
* 设计器里这一类字段的定位:下拉框只挂表单自己的数据,下拉选择只挂别处的数据。
*
* 这是**给挑的清单**,不是技术边界——判这一格走哪条路、渲染哪只控件,一律看 sourceKindOf。
*/
export function offeredSourceKinds(type: string): OptionSourceKind[] {
return OFFERED_SOURCE_KINDS[type] ?? sourceKindsOf(type)
}
/**
* 设计器那一栏的下拉里列哪几条:定位那几条,加上这一格**此刻已经用上**的那一条。
*
* 老表单里「下拉框挂了数据源」「下拉选择挂了字典」是配得出也跑得通的(历史上就那么用),
* 只按定位列会让那一格显示成「未选择」——配的人以为没配,填的人照旧按老来源提交。
*/
export function sourceKindChoicesOf(field: FormFieldDef): OptionSourceKind[] {
const offered = offeredSourceKinds(field.type)
const current = sourceKindOf(field)
return offered.includes(current) ? offered : [...offered, current]
}
/**
* 这一格此刻走的是哪条来源。
*
* 写着 `optionSource` 就照它来(写得不属于这一类字段时退回推导,别拿一个配歪的值去渲染);
* 没写的按**字段上有没有配过候选的痕迹**推:绑了字典编码就是字典,手写过选项就是手填,
* 关联审批单天然是流程单据——于是历史表单一个字节都不改,读出来跟今天一模一样。
*
* 什么痕迹都没有(刚拖出来的一格)才轮到这一类字段的定位说话:下拉框落回手填选项,
* 下拉选择落回外部数据源。让它也推成「手填选项」的话,新加的那一格会自带一条
* 它本不该有的来源,设计器里也会多出那个挑不到的选项。
*/
export function sourceKindOf(field: FormFieldDef): OptionSourceKind {
const declared = field.optionSource
if (declared && sourceKindsOf(field.type).includes(declared)) return declared
if (field.type === 'relation') return 'process'
if ((field.dictCode ?? '').trim()) return 'dict'
if ((field.options ?? []).length) return 'manual'
// 这一类字段一个来源都挑不了(文本框那类):照老口径当手填选项,渲染上也确实是一列选项
return offeredSourceKinds(field.type)[0] ?? 'manual'
}
/**
* 这一格存的是一串值还是一个值。
*
* 多选、关联审批单天生是一串;下拉框与下拉选择那一格由「可以选好几个」这个开关说了算
* (下拉框勾上它就成了多选下拉:行首带勾选框,挑中的几项挂在框里)。
* 哪些姿势装得下一串值、默认挑哪一种、导出与回显按什么形状念,全问这一句
* (后端镜像在 `dicts.holds_list_value`,两份清单必须一起改)。
*/
export function holdsListValue(field: FormFieldDef): boolean {
if (LIST_VALUE_TYPES.includes(field.type)) return true
return MULTIPLE_PICKER_TYPES.includes(field.type) && field.multiple === true
}
/**
* 这一格能挑哪几种姿势(顺序即设计器里的顺序)。
*
* 一串值也装得进下拉:选项行首有勾选框,勾完不关弹层,挑中的几项挂在框里
* (`Select` 的 `multiple`,格子太窄时收进「+N」)。于是只剩一条硬边界——
* **搜出来的候选不给平铺**:手上永远只有搜到的那一页,摊成一排等于只让人在第一页里挑。
*
* `type` 与 `multiple` 只剩「这一格存的值是什么形状」这一层用处(默认姿势、导出、回显问它们),
* 不再决定哪几种姿势能挑,所以留着不用;调用方仍然按同一份签名问。
*/
export function styleChoicesOf(_type: string, kind: OptionSourceKind, _multiple = false): PickerStyle[] {
const open: PickerStyle[] = SEARCHED_KINDS.includes(kind)
? ['dropdown', 'dialog']
: ['dropdown', 'inline', 'dialog']
return ['auto', ...open]
}
/** 没写样式时的默认姿势:各来源里最常用、也最不容易配错的那一种。 */
export function autoStyleOf(type: string, kind: OptionSourceKind, multiple = false): Exclude<PickerStyle, 'auto'> {
if (INLINE_BY_DEFAULT.includes(type)) return 'inline'
// 单据是「一万张单里找那张」:一屏铺不开,也不该在窄窄的下拉里认单号
if (kind === 'process') return 'dialog'
// 关联审批单存的一直是一串:勾中几条挂在框里,这是它今天的样子,不动
if (LIST_VALUE_TYPES.includes(type)) return 'dialog'
// 勾了「可以选好几个」的两格下拉组件:候选就在手里的(手填、字典),下拉里连着勾最省事;
// 搜出来的那两条还是弹出框划算——一行写得下三样信息,还带分页
if (multiple && SEARCHED_KINDS.includes(kind)) return 'dialog'
return 'dropdown'
}
/** 最终姿势:写着 `auto` 或与来源不搭(比如给搜出来的候选配平铺)时回落到默认。 */
export function pickerStyleOf(
field: FormFieldDef,
kind: OptionSourceKind = sourceKindOf(field)
): Exclude<PickerStyle, 'auto'> {
const multiple = holdsListValue(field)
const declared = field.pickerStyle
if (declared && declared !== 'auto' && styleChoicesOf(field.type, kind, multiple).includes(declared)) {
return declared as Exclude<PickerStyle, 'auto'>
}
return autoStyleOf(field.type, kind, multiple)
}
/**
* 这一格的取值要不要按「必须在候选里」把关。
*
* 手填选项和字典的候选是**全量拿在手里的**,选中的值不在里面就是配歪了、越界了,
* 前端会把值清掉、后端会拦提交。流程单据与外部数据源不一样:手上永远只有搜出来的那一页,
* 拿这一页去判「这个值存不存在」,等于把用户选中但没在搜索结果第一页里的东西当非法——
* 那一格的取值合不合法只有对面的系统说得清,这一层闭嘴。
*
* 给了 ``data`` 就按**此刻命中的那一条候选来源**判:挂了条件路由的格子,这一分钟是字典
* (要把关)、下一分钟可能是外部数据源(不把关)。不给就当"这套配置里有没有要把关的来源",
* 只有拿不到单据值的那几处才这么问(后端 ``dicts.constrains_values`` 同一句)。
*/
export function constrainsValues(field: FormFieldDef, data?: Record<string, unknown>): boolean {
if (data === undefined) {
const routes = optionRoutesOf(field)
if (!routes.length) return ['manual', 'dict'].includes(sourceKindOf(field))
const kinds = new Set<OptionSourceKind>(routes.map((item) => item.source))
kinds.add(sourceKindOf(field))
let guarded = false
kinds.forEach((kind) => {
if (kind === 'manual' || kind === 'dict') guarded = true
})
return guarded
}
return ['manual', 'dict'].includes(sourceKindOf(optionFieldView(field, data)))
}
// ---------------------------------------------------------------------------
// 候选来源的条件路由:一格挂好几套候选,按这张单上的值挑一套
//
// 「这一格的候选从哪儿来」以前只有一答。现实里同一格常常要换家:报销类型是「差旅」时候选是
// 差标字典,是「招待」时要问 ERP 的费用科目,选「其他」又只想让人自己挑两个词。以前只有两条路
// ——摆三格再用显隐条件把另外两格藏起来(三格 = 三个字段名 = 三份导出列与三套环节权限),
// 要么去对面求一个聚合接口。这一层给第三答:一份**有序清单**,自上而下第一条成立的用它,
// 一条都不成立就回落到字段自己那一份配置(= 今天的行为,老表单一个字节都不用改)。
//
// 后端镜像在 ``service/dicts.py``(``routes_of`` / ``matched_route`` / ``option_view``),
// 两份算法必须算出同一个结果:界面按 A 家的候选渲染、提交按 B 家判越界,是最难查的那种错。
// ---------------------------------------------------------------------------
/** 条件路由清单存在字段上哪一个键(与后端 ``dicts.OPTION_ROUTES_KEY`` 同名)。 */
export const OPTION_ROUTES_KEY = 'optionRoutes' as const
/** 一格最多挂几条;再多就不是「换一家」而是该做个聚合接口了(后端 MAX_OPTION_ROUTES 同一句)。 */
export const MAX_OPTION_ROUTES = 8
/** 每一条自己带的那几格:这一条用哪种来源,就只有那一种的配置说得通。 */
export const ROUTE_OWNED_KEYS: Record<OptionSourceKind, string[]> = {
manual: ['options'],
dict: ['dictCode', 'cascadeFrom'],
process: ['relationProcess', 'relationStatuses', 'relationScope'],
dataSource: ['dataSourceCode', OPTION_ARGS_KEY]
}
/** 一条候选路由**自带的那份带出**挂在哪个键上(只给外部数据源那一条用)。 */
export const ROUTE_FILL_KEY = 'fill'
/** 一份带出里能存的三张表(与 ``binding.entries`` 归一出来的那三个键同一份)。 */
export const ROUTE_FILL_TABLES = ['args', 'picks', 'extras'] as const
/** 所有来源会留下的痕迹(换来源、收残骸时用这一份)。 */
// 浏览器口径:这一层不押 Set 迭代器与 flat,去重走 utils/legacyCompat 那一份(同全站规矩)
const ALL_ROUTE_KEYS = uniqTexts(
objValues(ROUTE_OWNED_KEYS).reduce<string[]>((all, keys) => all.concat(keys as string[]), [])
)
/**
* 这一格配的条件路由清单,洗成能用的那几条。
*
* 没配、配成非数组、来源不属于这一类字段的一律丢掉——脏条目当没配比报错好:宁可回落到
* 字段自己那份配置,也不要让填单的人对着一只永远为空的挑选器(后端 ``routes_of`` 同一句)。
*/
export function optionRoutesOf(field: FormFieldDef): OptionSourceRoute[] {
const raw = (field as unknown as Record<string, unknown>)[OPTION_ROUTES_KEY]
if (!Array.isArray(raw)) return []
const kinds = sourceKindsOf(field.type)
const out: OptionSourceRoute[] = []
raw.forEach((item) => {
if (!item || typeof item !== 'object') return
const route = item as OptionSourceRoute
if (!kinds.includes(route.source)) return
const clean: OptionSourceRoute = { source: route.source }
if (route.when && typeof route.when === 'object') clean.when = route.when
ROUTE_OWNED_KEYS[route.source].forEach((key) => {
const value = (route as unknown as Record<string, unknown>)[key]
if (value === undefined || value === null || value === '' || (Array.isArray(value) && !value.length)) return
if (typeof value === 'object' && !Array.isArray(value) && !Object.keys(value).length) return
;(clean as unknown as Record<string, unknown>)[key] = value
})
const note = String(route.note ?? '').trim()
if (note) clean.note = note
if (route.optionMap && typeof route.optionMap === 'object') clean.optionMap = route.optionMap
// 这一条自带的带出:它和「这一条问哪一家」是同一次决定,一起洗、一起丢
const fill = cleanRouteFill((route as unknown as Record<string, unknown>)[ROUTE_FILL_KEY])
if (fill) (clean as unknown as Record<string, unknown>)[ROUTE_FILL_KEY] = fill
out.push(clean)
})
return out.slice(0, MAX_OPTION_ROUTES)
}
/** 自上而下第一条成立的;一条都不成立回 ``null``(= 用字段自己那份配置)。 */
export function matchedOptionRoute(
field: FormFieldDef,
data: Record<string, unknown> | undefined
): OptionSourceRoute | null {
const routes = optionRoutesOf(field)
for (const route of routes) {
if (conditionOk(route.when, data ?? {})) return route
}
return null
}
/**
* 按**指定那一条**路由把字段摊成一张视图(设计器逐条检查用它,不必造假数据)。
*
* 视图只动来源那一维(外带这一条自己那份「显示 / 存值」);挑选方式、能不能选好几个、
* 关联带出这些与来源无关的格子原样留着。返回新对象,不改传进来的那一份。
*/
export function optionRouteView(field: FormFieldDef, route: OptionSourceRoute): FormFieldDef {
if (!sourceKindsOf(field.type).includes(route.source)) return field
const view: FormFieldDef = { ...field, optionSource: route.source }
ALL_ROUTE_KEYS.forEach((key) => {
delete (view as unknown as Record<string, unknown>)[key]
})
ROUTE_OWNED_KEYS[route.source].forEach((key) => {
const value = (route as unknown as Record<string, unknown>)[key]
if (value !== undefined) (view as unknown as Record<string, unknown>)[key] = value
})
if (route.optionMap && Object.keys(route.optionMap).length) view.optionMap = route.optionMap
return view
}
/**
* 这一格**此刻**按哪一套候选来源工作:命中路由给换过来源的视图,否则给字段本身。
*
* 渲染、取候选、判越界三处都要吃这一份,否则就会出现「界面是 A 家的候选、提交按 B 家把关」。
*/
export function optionFieldView(field: FormFieldDef, data?: Record<string, unknown>): FormFieldDef {
const route = data === undefined ? null : matchedOptionRoute(field, data)
return route ? optionRouteView(field, route) : field
}
/** 带回来的值不在这格的候选里也收不收(见字段上的 ``allowOutsideValue``)。 */
export function acceptsOutsideValue(field: FormFieldDef): boolean {
return field.allowOutsideValue === true
}
/**
* 换这一条的来源:新来源那几格留着,别的来源那几格清掉。
*
* 与字段级那份 :func:`optionSourcePatch` 同一分寸——「显示哪一列」写的是上一家的列名,
* 换一家之后那些名字对不上,留着只会让下一任配的人对着一行看不懂的映射发愣。
*/
export function optionRoutePatch(route: OptionSourceRoute, kind: OptionSourceKind): OptionSourceRoute {
const next: OptionSourceRoute = { ...route, source: kind }
ALL_ROUTE_KEYS.forEach((key) => {
if (!ROUTE_OWNED_KEYS[kind].includes(key)) delete (next as unknown as Record<string, unknown>)[key]
})
next.optionMap = undefined
// 带出问的是「这一家还能给出哪几列」,换一家之后那些列名对不上,留着只会让人对着一行猜
if (kind !== 'dataSource') (next as unknown as Record<string, unknown>)[ROUTE_FILL_KEY] = undefined
return next
}
/** 新加一条路由时的起点:默认接住字段现在用的那一种来源,配的人少挑一次。 */
export function blankOptionRoute(kind: OptionSourceKind): OptionSourceRoute {
return { source: kind }
}
/** 「名字 -> 值」那张表的洗法:非对象当没配,键或值为空的那一行丢掉。 */
function textMap(value: unknown): Record<string, string> {
if (!value || typeof value !== 'object' || Array.isArray(value)) return {}
const out: Record<string, string> = {}
Object.keys(value as Record<string, unknown>).forEach((name) => {
const item = String((value as Record<string, unknown>)[name] ?? '').trim()
const key = name.trim()
if (key && item) out[key] = item
})
return out
}
/**
* 一份带出洗成能存下来的样子:只留 `args` / `picks` / `extras` 那三张表,三张都空回 `undefined`。
*
* 留一个空对象只会让下一任配表的人以为这一条配过什么(后端 `dicts.clean_fill` 同一句)。
*/
export function cleanRouteFill(value: unknown): RouteFill | undefined {
if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined
const out: RouteFill = {}
const code = String((value as Record<string, unknown>).source ?? '').trim()
if (code) out.source = code
ROUTE_FILL_TABLES.forEach((key) => {
const rows = textMap((value as Record<string, unknown>)[key])
if (Object.keys(rows).length) (out as Record<string, unknown>)[key] = rows
})
return Object.keys(out).length ? out : undefined
}
/**
* 这一条候选路由自带的带出,摊成**一条取数条目**:源、条件、入参都跟着这一条走。
*
* 只有外部数据源那一条说得上「带出别的列」——字典那一家的带出走 `autoFill`(它读的就是
* 此刻命中的那本字典的附加值),流程单据那一家走 `linkFill`(读的是实际挂上那张单),
* 那两条本来就跟路由走,不需要再挂一层。入参没另写时沿用这一条筛候选用的那一份,
* 省得配的人把同一组参数写两遍。没自带、或那一条还没选源,回 `undefined`。
*/
export function routeFillEntry(route?: OptionSourceRoute): FetchSourceEntry | undefined {
if (!route || route.source !== 'dataSource') return undefined
const fill = cleanRouteFill((route as unknown as Record<string, unknown>)[ROUTE_FILL_KEY])
if (!fill) return undefined
// 带出默认问的就是这一条那一家;另填了 source 才另问一家
const code = String(fill.source ?? route.dataSourceCode ?? '').trim()
if (!code) return undefined
const args = textMap(fill.args)
const entry: FetchSourceEntry = {
source: code,
args: Object.keys(args).length ? args : textMap(route.dataSourceArgs),
picks: textMap(fill.picks),
extras: textMap(fill.extras)
}
if (route.when && typeof route.when === 'object') entry.when = route.when
return entry
}
/** 这一格**此刻**那一条的带出(没命中或那条没自带时回 `undefined`)。 */
export function routeFill(field: FormFieldDef, data?: Record<string, unknown>): FetchSourceEntry | undefined {
if (data === undefined) return undefined
return routeFillEntry(matchedOptionRoute(field, data) ?? undefined)
}
/** 字典带出(「选了字典项 → 把那一本附加值里的某一列写进别的格子」)挂在哪个键上。 */
export const AUTO_FILL_KEY = 'autoFill'
/**
* 候选路由里那几条**字典来源**各挂的是哪一本(自上而下、去重)。
*
* 两处要用:换来源时判这一格上的 ``autoFill`` 算不算残骸(字段自己不挂字典、但某一条候选
* 挂的是字典,那份带出就还有用),以及设计期那句「这一档不起作用」。
* 后端镜像在 ``service/dicts.py:dict_route_codes``。
*/
export function dictRouteCodesOf(field: FormFieldDef): string[] {
const out: string[] = []
optionRoutesOf(field).forEach((route) => {
if (route.source !== 'dict') return
const code = String((route as { dictCode?: unknown }).dictCode ?? '').trim()
if (code && !out.includes(code)) out.push(code)
})
return out
}
/**
* 这一格**有没有可能**自带带出(不看此刻命中哪一条)。
*
* 「这一格会不会往外写值」那一类清单判断要用这一句:值还没填进表单时一条都不命中,
* 可这一格确实会往别的格子里写值。后端镜像 `fetch.has_fetch`。
*/
export function hasRouteFill(field: FormFieldDef): boolean {
return optionRoutesOf(field).some((route) => routeFillEntry(route) !== undefined)
}
/** 这一格一共挂了几条候选来源(清单为空 = 只用字段自己那一份)。 */
export function optionRouteCount(field: FormFieldDef): number {
return optionRoutesOf(field).length
}
/**
* 这一格的值是不是**系统带进来的**,是哪一种带出(提示里要说清是哪一头)。
*
* 三种带出都排在提交校验之前跑:外部取数(``fetch``)、关联单据带出(``linkFill``)、
* 字典带出(``autoFill``)。都没配就是这一格由人填,回空串。
* 后端镜像在 ``formruntime.filled_by_label``,说法两边同一句。
*/
/** 这一格身上所有会跑的取数条目:字段那份 `fetch` +候选路由各条自带的 `fill`。 */
function allFetchEntries(field: FormFieldDef): FetchSourceEntry[] {
const routes = optionRoutesOf(field)
.map((route) => routeFillEntry(route))
.filter((entry): entry is FetchSourceEntry => Boolean(entry))
return [...fetchEntries(field.fetch), ...routes]
}
/** 这份取数写进哪些格子(`picks` 的那些去向;候选路由那条 fill 的去向也算在这儿)。 */
function fetchTargets(field: FormFieldDef): Set<string> {
const out = new Set<string>()
allFetchEntries(field).forEach((entry) => {
Object.values(entry?.picks ?? {}).forEach((to) => out.add(String(to)))
})
return out
}
/** 有没有一条取数落在**这一格**上:条目自带的 `pick` 写的是它自己那一格,`picks` 点名这一格也算。 */
function fetchWrites(field: FormFieldDef, key: string): boolean {
if (key && fetchTargets(field).has(key)) return true
// 候选路由那一条自带的 fill 是 fillOnly(绝不盖这一格刚挑中的值),它压根没有 pick 这一档
return allFetchEntries(field).some((entry) => Boolean(String(entry?.pick ?? '').trim()))
}
/** `autoFill` / `linkFill` 那两类带出的去向里有没有这一格(配置挂在发起那一格身上,写的是别的格子)。 */
function rulesHitSelf(rules: Array<{ to?: unknown }> | undefined, key: string): boolean {
return Boolean(key) && (rules ?? []).some((rule) => String(rule?.to ?? '').trim() === key)
}
export function filledByOther(field: FormFieldDef, peers: FormFieldDef[]): string {
// 隔壁那一格的带出指着这一格:认字典带出 / 关联单据带出 / 外部取数(含候选路由那一条自带的 fill)。
// 只认「去向正好等于这一格的字段名」——明细列那种 `表.列` 的写法不算,那一格在表里。
const key = String(field.key ?? '').trim()
if (!key) return ''
let fetched = false
for (const other of peers || []) {
if (!other || String(other.key ?? '').trim() === key) continue
if (rulesHitSelf(other.autoFill as Array<{ to?: unknown }> | undefined, key)) return '字典带出'
if (sourceKindOf(other) === 'process' && rulesHitSelf(other.linkFill?.rules, key)) return '关联单据带出'
// 隔壁那条取数只有**去向点名这一格**才算(它自带的 pick 写的是它自己那一格)
if (fetchTargets(other).has(key)) fetched = true
}
return fetched ? '外部取数' : ''
}
export function filledByLabel(field: FormFieldDef, peers?: FormFieldDef[]): string {
// 判的是「有没有一条带出的**落点**在这一格上」,不是「这一格有没有配带出」:字典带出与关联
// 单据带出都配在发起那一格身上、写进别的格子,光看有没有配会把人挑的那一格说成是系统写的
// (后端 filled_by_label 同)。给了 peers 时还认隔壁那一格的带出指着这一格。
const key = String(field.key ?? '').trim()
if (fetchWrites(field, key)) return '外部取数'
if (rulesHitSelf(field.linkFill?.rules, key)) return '关联单据带出'
if (rulesHitSelf(field.autoFill as Array<{ to?: unknown }> | undefined, key)) return '字典带出'
if (!peers) return ''
return filledByOther(field, peers)
}
/**
* 清单本身配得对不对(后端 ``dicts.route_problems`` 同一句,措辞两边一字不差)。
*
* 「触发条件引用了不存在的字段」不在这里说——路由的上游已并进 ``conditionDependencies``,
* 由 ``formLinkage.linkageProblems`` 一处说,免得同一条错在面板里冒两遍。
*/
export function optionRouteProblems(field: FormFieldDef): string[] {
const raw = (field as unknown as Record<string, unknown>)[OPTION_ROUTES_KEY]
if (raw === undefined) return []
const label = field.label || field.key
if (!Array.isArray(raw)) return [`「${label}」的候选来源清单要写成一份列表`]
const problems: string[] = []
if (raw.length > MAX_OPTION_ROUTES) {
problems.push(`「${label}」的候选来源最多 ${MAX_OPTION_ROUTES} 条,多出来的不会被用上`)
}
const kinds = sourceKindsOf(field.type)
raw.forEach((item, index) => {
const at = `「${label}」的第 ${index + 1} 条候选来源`
if (!item || typeof item !== 'object') {
problems.push(`${at}配置格式不对`)
return
}
const route = item as OptionSourceRoute
const kind = String(route.source ?? '')
if (!kinds.includes(kind as OptionSourceKind)) {
problems.push(!kind ? `${at}还没选来源` : `${at}的来源这类字段挑不了:${kind}`)
return
}
if (kind === 'dict' && !String(route.dictCode ?? '').trim()) problems.push(`${at}还没选要用的数据字典`)
if (kind === 'dataSource' && !String(route.dataSourceCode ?? '').trim())
problems.push(`${at}还没选要用哪一张外部数据源`)
if (kind === 'manual' && !(route.options ?? []).length)
problems.push(`${at}一条选项都没填,选到它就是一只空下拉`)
if (kind === 'process' && route.relationStatuses !== undefined) {
const tokens = Array.isArray(route.relationStatuses)
? route.relationStatuses.map((one) => String(one).trim())
: []
if (!Array.isArray(route.relationStatuses)) problems.push(`${at}:能挂哪几种状态的单据要写成一份清单`)
else if (tokens.some((one) => !RELATION_STATUSES.includes(one as RelationStatus)))
problems.push(`${at}:能挂哪几种状态的单据里有认不出的档位`)
else if (!tokens.length) problems.push(`${at}:至少勾一种状态:一种都不勾,这一格永远搜不到候选`)
}
if (kind === 'process' && route.relationScope !== undefined) {
const one = String(route.relationScope ?? '').trim()
if (!one) problems.push(`${at}:候选范围还没挑:只给自已发起的,还是与我相关的都算`)
else if (!(RELATION_SCOPES as string[]).includes(one)) problems.push(`${at}:候选范围里有认不出的档位:${one}`)
}
})
return problems
}
/**
* 换来源时要跟着动的这一把:新来源自己那格留着,别的来源那几格清掉。
*
* 留着不清不是不行,是**看不见的东西最容易骗人**:从字典换成外部数据源之后,
* 老的 `dictCode` 还躺在字段上,后端 `effective_options` 又优先认字典编码,
* 于是界面显示的是新源搜出来的候选、提交时按老字典判越界。
* 级联只认字典,离开字典就清掉;字典带出认的是**这一格任何一处**挂着的字典(字段上那一本,
* 或某一条候选来源那一本),所以只有两处都没字典时才跟着走。
*/
export function optionSourcePatch(
field: FormFieldDef,
kind: OptionSourceKind
): Partial<FormFieldDef> {
const values: Partial<FormFieldDef> = { optionSource: kind }
if (kind !== 'dict') {
values.dictCode = undefined
values.cascadeFrom = undefined
// 字段自己不挂字典了,可**某一条候选来源挂的就是字典**:那一条命中时带的就是它那本的附加值,
// 这份带出不是上一家的残骸,留着(后端 api/design.py:clean_option_source 同一分寸)
if (!dictRouteCodesOf(field).length) values.autoFill = undefined
}
if (kind !== 'process') {
values.relationProcess = undefined
values.relationStatuses = undefined
values.relationScope = undefined
// 关联带出读的是「这一格挂的是哪几张单」:换成字典或外部数据源就没有单据可读了
values.linkFill = undefined
}
if (kind !== 'dataSource') {
values.dataSourceCode = undefined
values[OPTION_ARGS_KEY] = undefined
}
if (kind !== 'manual') values.options = undefined
// 「显示哪一列、存哪一列」是按来源那一行的列名写的:换来源之后那些列名多半对不上,
// 留着一份对不上的映射只会让下一任配的人对着一个看不懂的下发愣
values.optionMap = undefined
// 样式里有没有「平铺」这一档,是跟着来源走的:换完来源,原来那档可能已经不成立
if (!styleChoicesOf(field.type, kind, holdsListValue(field)).includes(field.pickerStyle ?? 'auto')) {
values.pickerStyle = undefined
}
// 「看哪几列」写的也是上一家来源的列名,一并清;搜索与每页条数那几格与来源无关,留着
values.picker = keepSourceAgnosticPickerConfig(field.picker)
return values
}
/**
* 换来源之后还留得住的那几格展示配置。
*
* 下拉与弹出框「看哪几列」写的是列名(`extra.spec`、单据的 `serial`…),换一张源多半对不上;
* 搜索开不开、一次捞几条、弹窗标题这三格说的是这一格的用法,与候选从哪儿来无关。
*/
export function keepSourceAgnosticPickerConfig(picker?: PickerConfig): PickerConfig | undefined {
if (!picker) return undefined
const next: PickerConfig = {}
if (picker.search === false) next.search = false
if (picker.pageSize) next.pageSize = picker.pageSize
if ((picker.dialogTitle ?? '').trim()) next.dialogTitle = String(picker.dialogTitle).trim()
return Object.keys(next).length ? next : undefined
}
/**
* 设计期检查:来源选了却没配到底、指向的源已经不能用、样式与来源搭不上,
* 以及这一格同时挂着外部取数、两边口径互相打脸。
*
* 只在保存那一刻挡:填单的人不该是第一个发现「这一格是空的」那个人。
* `ctx.keys` 是同一张表单里已有的字段名(判候选入参的 `{form.x}` 引用),
* `ctx.source` 是这张字段引用的那张数据源(判它还在不在、停用没停用)——
* 拿不到库的那一处不传就行,两句后端都会再说一遍。
*/
export function optionSourceProblems(
field: FormFieldDef,
ctx: {
keys?: Set<string>
source?: Parameters<typeof sourceProblem>[1]
/** 全量数据源清单按编码索引:条件路由里那几条各引用一张,逐条判"这张源还在不在" */
rows?: Record<string, DataSource | null | undefined>
/** 同一张表单里的其它字段:隔壁那一格的带出指着这一格,也算「这一格的值由系统带来」 */
peers?: FormFieldDef[]
} = {}
): string[] {
if (!carriesOptionSource(field.type)) return []
const kind = sourceKindOf(field)
const problems: string[] = []
// 来源这一栏点不出歪值,歪值只会从接口直传与 AI 起草那两条路进来:
// 后端认不出来会拦提交,这里也照说一句,免得设计器一脸没事、校验那一步才报错
if (field.optionSource && kind !== field.optionSource) {
problems.push(`这类字段挑不了「${field.optionSource}」这种候选来源,请重新选一个`)
}
if (kind === 'dict' && !(field.dictCode ?? '').trim()) problems.push('还没选择要用的数据字典')
const sourceCode = (field.dataSourceCode ?? '').trim()
if (kind === 'dataSource' && !sourceCode) problems.push('还没选择要用哪一张外部数据源')
if (kind === 'dataSource' && sourceCode) {
if (ctx.source !== undefined) {
const reason = sourceProblem(sourceCode, ctx.source, { want: 'search', noun: '候选' })
if (reason) problems.push(reason)
}
argRefProblems(field[OPTION_ARGS_KEY] ?? {}, ctx.keys ?? new Set<string>(), OPTION_ARGS_AT, field.key)
.forEach((reason) => problems.push(reason))
}
// 取数写进来的值不是人选的,而候选是判越界的那两种来源:两边各自都配得对,
// 凑一起必定在提交那一刻拦给填单的人看(后端 option_source_problems 同一句)
const filledBy = filledByLabel(field, ctx.peers)
if (acceptsOutsideValue(field) && !filledBy) {
problems.push(
'这一格没配任何带出(外部取数 / 关联单据带出 / 字典带出),「带出的值不在候选里也收下」这一档暂时不起作用'
)
}
if (filledBy && constrainsValues(field) && !acceptsOutsideValue(field)) {
problems.push(
`这一格的值由${filledBy}写入,候选又来自${kind === 'manual' ? '手填选项' : '数据字典'}:` +
'取回来的编码必须在那份清单里,否则提交时会被判「取值已不在可选范围内」。' +
'请把带回来的值补进这份清单,把候选来源改成外部数据源 / 流程单据,' +
'或勾上「带出的值不在候选里也收下」'
)
}
// 字典带出读的是字典项的附加值:字段上这一本与候选路由里那几本都没有,这一档就是空转
if ((field.autoFill ?? []).length && !(field.dictCode ?? '').trim() && !dictRouteCodesOf(field).length) {
problems.push('配了字典带出,可这一格没挂数据字典(字段上与候选来源那几条里都没有),这一档不起作用')
}
// 条件路由那几条:清单本身 + 每一条挑的那一种来源,逐条问一遍
problems.push(...optionRouteProblems(field))
optionRoutesOf(field).forEach((route, index) => {
const at = `第 ${index + 1} 条候选来源`
optionMapProblems(optionRouteView(field, route), route.source)
.forEach((reason) => problems.push(`${at}:${reason}`))
const code = (route.dataSourceCode ?? '').trim()
if (route.source === 'dataSource' && code) {
const row = ctx.rows?.[code]
if (row !== undefined) {
const reason = sourceProblem(code, row, { want: 'search', noun: '候选' })
if (reason) problems.push(`${at}:${reason}`)
}
argRefProblems(route[OPTION_ARGS_KEY] ?? {}, ctx.keys ?? new Set<string>(), OPTION_ARGS_AT, field.key)
.forEach((reason) => problems.push(`${at}:${reason}`))
}
})
// 勾了「可以选好几个」之后这一格存的是一串值:额度与外部取数那两头都只认一笔 / 一个值
if (holdsListValue(field) && field.quota) {
problems.push('这一格控一笔额度,只能挑一笔:勾了「可以选好几个」之后额度那一头认不出选中的是哪一笔,请取消多选')
}
if (holdsListValue(field) && fetchEntries(field.fetch).length) {
problems.push('这一格的值由外部取数写入,取的是一笔;勾了「可以选好几个」之后两边存的形状对不上,请取消多选')
}
if (holdsListValue(field) && field.threshold) {
problems.push('这一格的阈值条件比的是一个值;勾了「可以选好几个」之后这条条件多半永远不命中,请取消多选或换个格子')
}
// 手填选项那条路:每个选项自己填「显示文字」和「存的值」,存的值空着等于这一格选了就存个空
if (kind === 'manual') {
const blank = (field.options ?? []).filter((option) => String(option.value ?? '').trim() === '')
if (blank.length) problems.push(`有 ${blank.length} 个选项没填要存的值,填了会存成空白`)
}
// 来源=流程单据:能挂哪几档要说清。勾到一种都不剩,等于留一只永远搜不到候选的挑选器
// (措辞与后端 formruntime.option_source_problems 一字不差,check_binding.py 逐句对)
if (kind === 'process' && field.relationStatuses !== undefined) {
const raw = field.relationStatuses
if (!Array.isArray(raw)) {
problems.push('能挂哪几种状态的单据要写成一份清单')
} else {
const tokens = raw.map((item) => String(item).trim())
const unknown = tokens.filter((item) => !RELATION_STATUSES.includes(item as RelationStatus))
if (unknown.length) problems.push(`能挂哪几种状态的单据里有认不出的档位:${unknown.join('、')}`)
else if (!tokens.length) problems.push('至少勾一种状态:一种都不勾,这一格永远搜不到候选')
}
}
// 候选范围那一档(只给我发起的 / 与我相关):界面上挑不出歪值,歪值只从接口直传与 AI 起草进来
// (措辞与后端 dicts.relation_scope_problems 一字不差)
if (kind === 'process' && field.relationScope !== undefined) {
const raw = String(field.relationScope ?? '').trim()
if (!raw) problems.push('候选范围还没挑:只给自已发起的,还是与我相关的都算')
else if (!(RELATION_SCOPES as string[]).includes(raw)) problems.push(`候选范围里有认不出的档位:${raw}`)
}
optionMapProblems(field, kind).forEach((reason) => problems.push(reason))
pickerDisplayProblems(kind, field.picker).forEach((reason) => problems.push(reason))
const style = field.pickerStyle
if (style && style !== 'auto' && !styleChoicesOf(field.type, kind, holdsListValue(field)).includes(style)) {
// 两句话各管一件事:认不出的样式、搜出来的候选铺不成一排
// (后端 option_source_problems 分的也是这两句,两边说法一模一样)
problems.push(
!PICKER_STYLES.includes(style)
? `挑选方式不认识:${style}`
: '这一格的候选是搜出来的,铺不成一排,请改成下拉选项或弹出框'
)
}
return problems
}
/**
* 已经用上、却不在清单里的那一条不能从下拉里凭空消失。
*
* 字典或数据源被人删了,字段上那个编码还在:下拉里找不到对应项就会显示成「未选择」,
* 于是配的人以为没配、填的人照旧按老编码提交。留着它并标一句,才看得见真正要修的是哪儿。
* 调用方自己拼好 label(这一层不碰 i18n)。
*/
export function withMissingOption<T extends { value: string }>(
options: T[],
value: string | undefined,
make: (value: string) => T
): T[] {
const code = (value ?? '').trim()
if (!code || options.some((item) => String(item.value) === code)) return options
return [...options, make(code)]
}
/** 这一格有没有把候选来源配到底(明细列那种「既没写选项也没选字典」的老检查走这个)。 */
export function hasSourcedOptions(field: FormFieldDef): boolean {
const kind = sourceKindOf(field)
if (kind === 'dict') return Boolean((field.dictCode ?? '').trim())
if (kind === 'dataSource') return Boolean((field.dataSourceCode ?? '').trim())
if (kind === 'process') return true
return Boolean((field.options ?? []).length)
}