feat: 新增管理员改道事件与处理意见附件支持

新增管理员干预改道的事件类型,支持处理意见随附图片文件,兼容旧版浏览器的 API 与样式,优化通知面板逻辑,下线表单跟随设计功能。
main
kangwenjing 2026-11-13 10:37:44 +08:00
parent 983c05ecb1
commit b6012bd743
231 changed files with 34691 additions and 1535 deletions

View File

@ -46,6 +46,10 @@ FROM --platform=$BUILDPLATFORM node:24-bookworm-slim AS web
# 换源加速(国内网络建议在 docker-compose.yml 里覆盖成 npmmirror)
ARG NPM_REGISTRY=https://registry.npmjs.org
# Corepack 抓 pnpm 本体的那一下**不看** pnpm 的 --registry,只认这个变量:
# 不把它指向同一个镜像源,构建就会卡在 registry.npmjs.org 上(拉不到就一直挂着)。
ENV COREPACK_NPM_REGISTRY=${NPM_REGISTRY}
# 构建号:手机首页右上角显示的就是它。打镜像时与 tag 用同一个值——
# docker build --build-arg OA_APP_BUILD=202611031830 -t …:202611031830 .
# 于是手机上那一串 == 集群里那个 Pod 的镜像 tag。留空则退回构建那一刻的时间戳。

518
README.md
View File

@ -61,6 +61,14 @@ unisoa/
│ ├── scripts/check_web_shell.py # 首屏那份注入:注得进、值里带 </script> 也逃得掉、换了就换缓存、问不出配置照样发页面
│ ├── scripts/check_db_dsn.py # 拼 DSN 的对账:口令带 @ : / # % 空格时还连得上库吗
│ ├── scripts/check_binding.py # 取数内核与候选来源:写法解析、源健康判据、带出取哪一列、前后端措辞对账
│ ├── scripts/check_option_routes.py # 一格挂多套候选来源(optionRoutes):命中与回落、视图、清洗、越界与「带出的值也收下」、必填不再死锁、前后端常量与措辞对账
│ ├── scripts/check_option_route_fill.py # 那一条候选自带的带出(optionRoutes[].fill):按此刻命中那条合成、只写带出去向不盖这一格、回落、失败策略、设计期逐条体检、清洗、前后端对齐
│ ├── scripts/collapse_trip_form.py # 生产那张「出差备案申请」16 格收成 4 格:照表上真字段算、逐家比对候选与带出与取数、按设计器口径校验,默认不改库(--write 才落)
│ ├── scripts/check_link_fill.py # 关联带出(纯函数那份口径):配置整形、指向掉了、几张单合成一个值、一单一行、前后端措辞对账
│ ├── scripts/check_table_column_readonly.py # 明细列勾了「只读」:那一列不卡必填、值的格式照判、整张表那一层权限没被带坏
│ ├── scripts/check_table_column_config.py # 明细列与主表同权:藏着的列不卡必填、上下限提交时判、格式那几问不再跟着必填走、列宽对齐合计只在设计期判
│ ├── scripts/check_row_fetch.py # 明细列逐行取数:入参读「整张单+这一行」、带出只落本表、报错点行号、整表隐藏时降级、留痕摊得开行号
│ ├── scripts/check_link_fill_submit.py # 关联带出走真提交(连库):发起就带得出、`_link` 活得过整表、关联没变不重排、带不出值时必填挡人
│ ├── scripts/check_fetch_url_args.py # 取数地址带参数:地址模板替换与 URL 编码、空入参不外呼、缓存键认地址
│ ├── scripts/check_embed.py # 表单嵌外部页面:参数白名单、接口取链接、一次回的那几条链接与顺手带回的那几个值、能否被嵌、免登短码、CSP、留痕不含值
│ ├── scripts/check_embed_api.py # 同上但连库连实例:短码用第二次必须失败、refresh 只回参数、越权 403、预受理号复用与那三档回写、响应里有哪几栏可挑与对方回传过的键名
@ -84,6 +92,7 @@ unisoa/
│ ├── scripts/check_identity_refs.py # 配置里的引用不能还压着身份 DN:岗位角色成员要真解析得出人
│ ├── scripts/check_memberships.py # 一个人挂几处岗位:反查与正向解析同口径、且不随人数排队
│ ├── scripts/check_cc_reads.py # 环节抄送建待阅:几条规则合起来只读一趟 oa_read,没得抄一趟都不问
│ ├── scripts/check_cc_action_files.py # 抄送需处理带图片/文件、归档件补批注:归属、开关、搬档一起对;全程在未提交事务里跑,库里不留一行
│ ├── scripts/check_flush_defer.py # 引擎 flush 只刷该刷的那几行:同一张单办两遍,逐行逐列与整刷对齐
│ ├── scripts/check_simulate_paths.py # 设计器逐环节试算:配好的路由能不能真的解析出审批人
│ ├── scripts/check_log_timeline.py # 流转日志时间线:留痕不倒挂、上一条不每趟回库
@ -112,6 +121,7 @@ unisoa/
│ ├── config.prod.toml.example # 生产档模板:部署机上复制成 config.prod.toml 再填,别提交
│ ├── scripts/prod-api.sh # 部署启动入口:默认 OA_ENV=prod(本地开发用 dev-api.sh)
│ ├── scripts/what_config.py # 部署自查:这一趟读的是哪几份配置文件(不连库、不起服务)
│ ├── scripts/migrate_design.py # 跨档位搬设计:把生产的表单与流程(含字典/取数/回写/角色)复制一份到测试库,源库只读
│ ├── storage/ # local 后端的落盘根目录(附件 / 封面 / 网盘)
│ └── requirements.txt
├── frontend/ # 复用 sub2api 前端框架
@ -135,6 +145,10 @@ unisoa/
├── docs/external-data-simplification.md # 外部数据源配置怎么砍简单(画像预设 / 样例反推),字典选项怎么来自外部系统
├── docs/sql-autofill-design.md # 取数通道里加一条「查本库」:只读闸门、入参只绑定、选人字段先换账号
├── docs/data-binding-unification-design.md # 候选来源与外部取数为什么是两格、它们底下重复的那一层怎么收成一层
├── docs/option-source-routing-design.md # 同一格挂好几套候选来源(optionRoutes):按这张单上的值换一家、带出的值也收下
├── docs/relation-link-fill-design.md # 关联带出:挂上那几张单之后,值怎么落进这一张单的主表字段与明细表(含挂多张)
├── docs/field-self-visibility-design.md # 显示条件判自己那一格:字段的显隐由它自己的取值决定(含只被自己藏起来时那一笔值收不收)
├── docs/designer-panel-dialogs.md # 设计器窄栏只留一行入口,多列的配置面板一律进弹窗(含那次撑出界的真原因)
├── docs/embed-page-field-design.md # 表单里嵌别的系统的页面:地址与密钥住哪、免登短码、能不能被嵌的探测与降级
├── docs/embed-action-design.md # 那一页能替人做哪几件事:嵌入会话与预受理号、怎么触发发起、第三方审完了怎么算通过
├── docs/embed-configuration-guide.md # 上面两篇的说明书:谁在哪个界面配哪一栏、对方要调什么、配完怎么验、出问题查哪一行
@ -150,6 +164,7 @@ unisoa/
├── docs/mobile-approval-layout.md # 手机端审批版式:只换版式不换逻辑、首页五张卡片、四问抬头、表单三层归置、bottom sheet
├── docs/mobile-form-layout-config.md # 手机端表单版式配置:手机上只出一节,摆哪几格、什么顺序、每格怎么摆都能配(存 layout.mobile,没动后端)
├── docs/process-intervention-design.md # 流程干预:挂起 / 改道 / 整单催办改派 / 修正表单,边界与留痕口径
├── docs/intervention-todo-and-message-settlement-design.md # 干预之后:旧环节留下的残留与已推送消息的下场(去向卡、改道收口、渠道补一句)
├── docs/draft-create-api.md # 创建流程草稿接口:一个接口建任意类型草稿、参数清单怎么查、外部系统怎么代人铺单
├── docs/multi-worker-deployment.md # 多副本部署:调度租约、启动命名锁、建库白名单与还没拿掉的单进程假设
├── docs/nas-drive-integration-plan.md # 网盘对接公司 NAS:四条路线、命名与权限口径、分期与验收(方案)
@ -382,6 +397,26 @@ WARNING 上线体检:【prod】JWT 签名密钥还是出厂的占位值 change
上面任何一处看到 `环境=dev` 就是这个原因,systemd 里补 `Environment=OA_ENV=prod` 即可;
用 `scripts/prod-api.sh` 起的话它本身就默认 `prod`,不会漏。
分档还带来一个常用动作:**把生产配好的表单与流程搬一份到测试环境**,用
`backend/scripts/migrate_design.py`。它按 `config.<档位>.toml` 各连一条库,源库那条会话一开就
是 `READ ONLY` 事务(真往里写会被 MySQL 顶回来,脚本自己也只发 SELECT),目标库先把要动的行
整包备份成 gzip JSON,再一个事务写完,任何一步报错整体回滚:
```bash
cd backend
python3 scripts/migrate_design.py # 干跑:列清楚要搬什么、会盖掉什么
python3 scripts/migrate_design.py --apply # 生产 → 本机测试库(默认档)
python3 scripts/migrate_design.py --process 印章 # 只搬名字里带「印章」的流程
python3 scripts/migrate_design.py --restore ../backups/design-migrate-20261110-141123.json.gz --process 备用金
```
搬的是流程 / 环节 / 路由 / 发布历史 / 表单 / 分类,外加表单与环节按业务键点名的数据字典、
外部取数、回写模板;对齐认的是跨环境稳的那几把尺——主键 id 与 `code`,不是名字。审批人存的
是角色名 / 部门名 / 登录账号,所以两个环境各自的人和组织一行都不用搬,脚本只把落地后点名点
不到的角色、部门、账号如实报出来。**目标库多出来的一律不删**(这是搬迁不是清理),已存在的
整行覆盖;唯一反过来的是审批角色的成员名单——测试环境通常故意把「总经理」这类岗指给测试
账号,所以只补缺的角色、不拿生产的真员工盖下去。
上线步骤(部署机上):
```bash
@ -758,6 +793,31 @@ python3 scripts/audit_storage.py --to-minio # 把本该进 MinIO
复制 / 删除,每个字段可配字段名、类型、必填、只读、占位提示、说明文字,数字字段另有最小值 /
最大值 / 步长 / 小数位 / 单位。
- **「值还没到时框里写什么」只有一栏说话**:`field.placeholder`。普通录入格它是输入框的占位提示;
系统带出与公式这两格没有录入框,同一栏因此叫「**没值时显示的文字**」——值没到之前框里就写这一句,
留空就给全平台那句空值标记 `--`,值一到自己让位。组件从前自己编过三句(系统带出那格写「提交后由系统自动填写」、
公式那格写「填写相关字段后自动算出」、等后端算的带出格底下还垫一句同样的小字),配表的人
既删不掉也换不成别的,屏幕上凭空一句没人授权的话,比空着更容易让人以为是自己漏填
(2026-11 用户那句「不希望组件里面有这样的说明,除非有个地方让我可以配置里面展示的文字」)。
**但"不编话"不等于"什么都不说"**:只读那一格留空时给的是 `--`,与同屏空着的申请部门、项目编码、
各档金额同一句话(`FormFieldControl` 与 `cellFormulaText` 早就是这么写的)——只那一格留一片真空,
读起来像字段没了(同一批用户那句「创建表单为什么看不到流程编号了」)。
判据两处、都在 `components/oa/FormRenderer.vue`:`emptyTextOf`(配的那句)与
`emptyCellText`(没配就补 `--`),钉在 `FormRenderer.emptyText.spec.ts`。
设计器画布那一屏不掺这一栏——它答的是"这一格带的是哪个来源",而框里那句话在运行时多半轮不到
说话(值一到就让位);配的正文要到「预览」那一屏看,预览走的就是运行时那条渲染路径。
「预览」里**「单据编号」那一格补的是真样子**:编号要等发起那一刻才存在,预览永远取不到真号,
于是那一格在预览里从前永远是空框。这一屏本来就靠样例值说话(顶上那句提示写得很明白:没填的
格子拿样例值顶上),所以这里问的是发起时同一份 `service/numbering.py`
(`designAPI.formPreviewSerial`,只读不占号),改一次前缀 / 位数 / 日期段跟着变一次,
与属性面板「生成规则」下面那行预览同一口径;画布那一屏不去问,设计者在预览里亲手敲进那一格的值
也不盖。判据 `views/oa/design/FormDesignerView.vue:seedPreviewSerial`,
钉在 `FormDesignerView.previewSerial.spec.ts`。
**顺带修一处一直没人看见的接线错**:这一栏在属性面板里挂的是 `v-else-if`,接在上面
「额度控制」那块面板的 `v-if` 后面——凡是挂得住额度的格子(除了附件那一小撮,几乎全是)
面板一出来这栏就跟着没了,所以「占位提示」在单行文本、下拉这些最常见格子上**从来没真的出现过**。
改回独立 `v-if`,`FieldInspector.newTypes.spec.ts` 按栏名找输入框,钉住哪一类格子出哪一栏。
- **多选月份**(`months`):一次圈几个月,挑 2026 年 10、11 两月,回填出来就是「2026年10-11月」。
库里存的仍是 `["2026-10","2026-11"]`(与 `month` 同一写法,条件与导出读得懂),并段那句人话由
`utils/formRuntime.ts:monthsText` ↔ `service/formruntime.py:months_text` 现拼,只读、打印、导出同一句。
@ -774,6 +834,112 @@ python3 scripts/audit_storage.py --to-minio # 把本该进 MinIO
日期区间与时间段会判**起止先后**,颠倒的提交挡下。前端挡的是体验(`maxlength`、`accept`、
个数截断),提交时后端 `formruntime.value_problems` / `_file_problems` 才是那一道权威闸,
明细表的列同样判(`_row_problems` 逐行复用同一份口径)。
- **明细表那一列也锁得上**(`column.readonly`):列卡第一行多了「只读」,跟主表那颗同一个意思——
锁着的格子填单人改不动,值归默认值 / 自动带出 / 关联带出 / 额度台账给。运行时**一直**认这一份
(`FormRenderer` 把它递给录入控件),缺的只是设计器里的入口:原先唯一能改它的地方是「自动带出」
底下那颗「带出后允许填写人修改」,于是没配带出的列**根本锁不上**,配过的列也只能反着说
(2026-11 用户那句「表单的明细表中的字段,无法设置不可编辑」)。现在三处读写同一份配置,
不另发明第二个标记。**锁上之后必填让路**:`_row_problems` 不再拿那一列卡人、界面上不摆那颗红星、
属性面板把必填那颗灰掉(勾还留着,解锁就回来)——必填卡的是人,而那一格根本没有空可填,
照旧拦等于把单子钉死在这一环,跟「屏幕上没有那一格,却说请先填写它」是一种坏法。三条分寸:
**只让「必填」这一条**,那一格里已经躺着的值照旧过格式那几关;**只认 `readonly` 这一个标记**,
写了本行公式那一列没勾只读,公式算不出值仍是配置坏了,照旧拦(界面上那一列的锁勾死解不开,直到
§2.11 那颗「公式带入后允许修改」出现才给了出口);
**整张表那一层的环节权限一个字没动**,环节把表设成只读走的还是 `effective_perm`,列上这一层只在
表本来摊开给人填时说话。**这一层管"人改不改得动",不管"这批值收不收"**:按环节权限过滤写入的
`editable_keys` 粒度仍是整张表。锁着又没配任何值的来路时设计器当场说一句
(`columnLockedWithoutSource`,来路算默认值 / 自动带出 / 本行公式 / 关联带出的目标列 / 额度逐行控
写的那几列),侧栏那一行也跟着念「共 N 列,…,M 列锁着」。设计见
[docs/form-field-catalog.md](docs/form-field-catalog.md) §2.8,钉在
`FieldInspector.column-readonly.spec.ts`、`FormRenderer.tableCellReadonly.spec.ts` 与
`PYTHONPATH=. python3 scripts/check_table_column_readonly.py`。
- **公式带进来的那个数可以让人改了**(`column.formulaEditable`):用户那句是「表单中明细表中引用
公式带入的值,为什么不能编辑」。这不是坏掉,是一直以来的画法——列上一写公式,`columnHasNoInput`
就把那一格的录入框收走(屏幕上只剩一句现算的文本),而 `applyRowFormulas` 每轮改动都整列重算,
**就算硬塞一个框,敲进去的数也会在下一轮重算里被盖回公式那个**。所以这一档两件事一起管:那一格
出录入框(公式先把数摆在框里,表头从一枚锁换成一枚 `fx`),重算则绕开**人改过的那一格**。凭据落在
行上那份 `_manual`(列标识的数组,与关联带出的 `_link` 同一层,导出与打印看不见它),编辑中的
整型与后端 `normalise_rows` 都把它一起留着——不然下一环的人重新打开这张单,昨天改的数就悄悄变回
公式算的那个,**改得动却留不住,比不让改更气人**。三条分寸:**只豁免改过那一格**,没动过的照旧
跟着公式走,主表那个运费一涨、没人碰的那几行照样变;**清空那一格 = 交回公式**,行上那颗「恢复
公式值」点一下走的是同一条路(撤凭据 + 重算),手工覆盖没有退路比不让改更难用;**锁与隐藏压过
这一档**(`columnNotForPeople` 在前,判据只 `columnFormulaEditable` 一处,填单与设计器读同一把
尺子,属性面板里那一档在已勾只读时灰着并说一句为什么)。提交那道闸**一个字没动**:那一格现在
有框了,必填照卡、值照过格式那几关,公式列的默认值照旧不复活;这一列的数仍然只有前端会算,
接口直接提交的单子照旧得自己算好。设计见 [docs/form-field-catalog.md](docs/form-field-catalog.md)
§2.11,钉在 `formRuntime.formulaEditable.spec.ts`、`FormRenderer.formulaEditable.spec.ts`、
`FieldInspector.columnFormulaEditable.spec.ts` 与
`PYTHONPATH=. python3 scripts/check_table_formula_editable.py`。
- **明细列与主表字段同权,最多一行的表先把那一行摆好**(`column.*`,含新的 `width` / `align` /
`aggregate` / `hidden`):用户那句是「明细表里面的列,我希望也可以和主表字段一样可以进行各种配置」。
查下来缺的仍是**设计器里的入口**——`FormRenderer` 把列上那份对象原样递给 `FormFieldControl`,
所以 `placeholder` / `maxLength` / `pattern` / `min` / `max` / `accept` / `cascadeFrom` 这些键**一直
有人认**,只是界面上没地方写。于是这一轮不另发明一套「列配置」的 schema:配置全写在列上那一份对象上、
与主表**同一个键名**。列卡第一行补了**上移 / 下移 / 复制**(以前调一次列序等于删了重加),其余那一长串
(占位提示、列说明、隐藏此列、字数上限、校验正则、取值上下限与步长、附件三个限制、级联自、列宽、对齐、合计)
收进「更多配置」那一栏(2026-11 又添了「外部取数」,见下面那一条),规矩跟侧栏一样——**门关着时入口那一行就是唯一的可见状态**,配过几样写在角标上;
用不上的格子不摆(归本行公式那一列没有录入框,占位提示与上下限轮不到它;文本列的合计只有「不合计」与
「计数」两档);换列类型带走不走的旧配置一并清掉,与主表 `changeType`、后端 `clean_formats` 同一份清单。
补齐的两道闸都在提交那一步:**数字与金额的上下限明细列照判**,而且格式那几问**不再跟着必填走**——
以前整段套在「没勾必填就跳过」里面,非必填的列填什么都没人看,那三道限制等于只在浏览器里说了算,
而接口直传与脚本写入的值压根不经过那只框。表格自己那三样是**纯展现**:列宽是这一列的最小宽度
(自动 + 七档,整张表超容器仍走横向滚动)、对齐四档、合计五档在表尾多摆一行念这个数
(`TableAggregateRow.vue`,非数与空格子不进统计,小数位跟着那一列自己的 `precision`),后端只在
设计期判配置本身认不认识,一个字不进 `validate_submit`。段头那句「合计 X」现在**优先听点名**:
哪一列显式配了 `sum` 就念哪一列,没配才回落到「第一个数字列」,且标签与数字问同一列(以前段头写着
「运费」、念的是「金额」那一列的数)。**隐藏此列**(`column.hidden`)只管屏幕上摆不摆:值照常保存、
照常导出、照常参与本行公式与关联带出,也**不卡必填**(`column_not_for_people` 与上一那颗 `readonly`
同一把尺子),是给项目编码 / 物料 ID 那类「带出来给机器用、人不需要看」的列留的。顺带把用户那句
「明细表最多只有一行的时候,我希望可以自动帮我带出一行」做了:`maxRows === 1` 的表进填单那一屏就补
一行,补的这一步与点「+」**走同一条路**(同一份 `emptyRow` + `rowSeed` + `applyRowFormulas`),
默认值 / 自动带出 / 本行公式都按老口径落,不多算一次也不少算一次;只读那一屏与环节锁上的表不补,
落库前 `normalise_rows` 照旧把一格没填的空行剔掉,所以补出来那行没人碰也不会多存一条空记录。
手机端那一份读单(`components/oa/mobile/useFormPlan.ts`)跟着同一份口径:藏着的列不进逐条那几行,
摘要那一行「合计 X」也优先念列上点了求和的那一列——同一张单在电脑上念一个数、手机上念另一个数,
比两边各念各的更让人不敢信。设计见
[docs/form-field-catalog.md](docs/form-field-catalog.md) §2.10,钉在 `FieldInspector.columnMore.spec.ts`、
`FormRenderer.tableColumnDisplay.spec.ts`、`formRuntime.tableColumnConfig.spec.ts`、
`useFormPlan.spec.ts`、`fieldCatalog.spec.ts`(那三份清单与列宽区间前后端一致)与
`PYTHONPATH=. python3 scripts/check_table_column_config.py`。
- **明细列也能逐行取数**(`column.fetch`):用户那句是「明细表中的字段是否可以配置取数,取我
配置的外部数据源」。真实的问法长这样:收款明细每一行填了收款人,开户行与银行帐号要按**这一行
那个人**去 ERP 查——整张表共用一个数没有意义,逐行手填又必然填错。查下来缺的是执行器那一半:
列上挂不上 `fetch`(`fetch_fields` 见着 `type == "table"` 就跳过去),那一格只能人填或者走关联
带出。这一轮**不发明新键**:列上写的还是主表那一份形状(多源 + `merge`、`args`、`picks`、
`onError`、`revalidateAfter`、`freezeAfterStart`),只是逐行各跑一次,值落在这一行的这一列;
设计器入口是列卡「更多配置」底下那块「外部取数」,摆的就是主表那只面板,挂得上挂不上的仍归
同一句 `canCarry(type,'fetch')`(装得下一个数或一句话的那些列能挂,多选 / 部门 / 附件 / 日期
区间那几类主表本来就挂不上,列上同理)。两处口径与主表不同,都是从「一行生一格」推出来的:
**入参读的是「整张单 + 这一行」**,与主表字段同名的列以本行为准——跟本行公式吃的是同一份作用域,
`{form.x}` 既能读主表也能读本行的列,配的人不用为明细列再记第二套写法;**「带出去向」只认这张
表的其它列**,往主表那一格写等于让最后一行去盖表头(三行的表盖三次,谁赢看运气),所以那几格
压根不进下拉,保存到后端也挡。报错要点名是哪一行(「明细表「收款明细」第 2 行的「银行帐号」的
外部数据取不到:ERP 连接超时」)——整张表共用一句不带行号的报错,八行的表没人知道该回去改哪
一行;`onError=block` 在**整张表被这一环藏起来**时降级成不挡(环节权限挂的是表不是列,那一列
露不露脸看它所属那张表露不露),取数照发、带出照写、留痕照记。留痕按 `表名.列名` 记一条、底下
挂逐行那几次外呼:两张明细表可能有同名列,同一列每一行都得留得开,沿用主表那份「列名当键」
会撞在一起。权威照旧在服务端:填单页逐行各取一次给人看(`runRowFetches` 把一张表的补丁攒完再
一次性写回——逐行各写一次会把前面几行刚取回的那份按还没回来的旧快照盖掉),提交时后端
`_apply_rows` 按同一份配置逐行再取一次并覆盖,跑的是当前那几行,删掉的行不再取一次、新加的
那一行当场补得上。**仍然不做**「一次查询填整张表」:这一档是一行一调,十行十次外呼,再叠到点
重取就是十次乘以刷新次数,而行的增减还是人说了算(边界见
[docs/sql-autofill-design.md](docs/sql-autofill-design.md) §6 第 4 条)。顺带一件小事:配了逐行
取数的那一列就算勾着「只读」,也不再被「锁着却没有任何来源」那句黄字念——那一格的答案本来就是
查出来的,锁着才对。设计见 [docs/form-data-integration-design.md](docs/form-data-integration-design.md)
§9.2 与 [docs/form-field-catalog.md](docs/form-field-catalog.md) §2.12,钉在
`PYTHONPATH=. python3 scripts/check_row_fetch.py`(34 句)与前端 `formFetch.rowFetch.spec.ts`、
`FormRenderer.rowFetch.spec.ts`、`FieldInspector.columnFetch.spec.ts`、`formPrune.spec.ts`。
- **明细表提交之后可以先收着**(`readonlyStyle`):填单那一屏明细表当然得摊开——人要往格子里敲字。
可流程一走起来它就变成一整段只读表格,报销单摆上两三张,审批人进来先翻三屏表格才看到自己的签名框。
明细表属性面板上多一栏「流程提交后的展现」:**展开**(默认,跟一直以来一样,存量表单没写这一档就
是它)/ **收折**(只读那一屏先给一行「共 N 行 · 合计 X」,点这一行才摊开,再点收回)。三处口径钉死:
**只管读**——填单那一屏永远摊开,配了收折也不给录入框消失的机会;**打印那一份永远摊开**——纸上没有
"点一下"这回事,收着的那些行等于根本没印出来,而缺的那一半在纸面上看不出缺(复用 `flattenTabs`
那个"这是打印"的判据,不另发明第二个开关);**人手动点开那一份是屏幕上的临时状态**,不写回表单——
审批人点开看一眼是他这一趟的事,不该把全公司以后看单的样子改掉。手机端不吃这一档,那边早有自己那一份
(`MobileFieldStyle` 的 `card` / `list`,默认就是收成一行),两份开关各说一件事。设计见
[docs/form-field-catalog.md](docs/form-field-catalog.md) §2.9,钉在
`FormRenderer.tableReadonlyStyle.spec.ts` 与 `FieldInspector.tableReadonlyStyle.spec.ts`。
- **定位不接地图服务**:`location` 存浏览器原生定位给的经纬度 + 一句人写的地址
(`{lng, lat, address}`),因为本平台没配任何地图 key。台式机 / 没授权 / 非 https 页面
取不到位置时,只写一句地址也算填了(`locationFilled` ↔ `formruntime.location_filled`)。
@ -999,6 +1165,88 @@ python3 scripts/audit_storage.py --to-minio # 把本该进 MinIO
凑一起会咬人的配法也在保存这一刻就说:值由外部取数写入而候选又是判越界的手填 / 字典(提交时
必定拦在填单的人面前),以及候选入参引用了不存在的字段。取舍见
[docs/data-binding-unification-design.md](docs/data-binding-unification-design.md)。
- **同一格挂好几套候选来源,按这张单上的值换一家**(`field.optionRoutes`):用户那句原话是
「我一个组件中为什么不能配置多个外部数据源、数据字典等等,我通过表单中字段来判断我该组件中
该用什么数据源」。字段上多挂一份**有序清单**(最多 8 条),每一条 = 一个触发条件(`when`,
与 `visibleWhen` 同一份结构化条件、同一个 `conditionOk`)+ 一套候选来源配置(哪本字典带级联 /
哪张列表型数据源带入参 / 哪个流程带状态档 / 手填那几条,各带自己那份「显示为 / 存为」和一句
备注)。**自上而下第一条成立的用它;一条都不成立回落到字段自己那一份**——老表单没挂清单,
走的正是这条路,一个字节不用改。以前一格一答不是漏了复选框,是那套设计的前提:
`effective_options` 只读字段上那一份配置,「存的是哪一列」和「要不要判越界」都跟着那一答走,
两答同时在场「这一格存编码还是存物料号」当场没有定义;换家只剩摆三格拿显示条件藏(三个字段名
= 三份导出列 + 三套环节权限)或去对面求聚合接口。「顺序 + 回落」让同一时刻仍然只有一套候选
在场,那三条前提一条都不破。
这一层**不新增任何候选口径**:命中之后只把字段摊成一张**视图**(`optionFieldView` /
`dicts.option_view`,只换来源那一维,`pickerStyle`、多选、关联带出、额度阈值、显示条件原样留着),
再喂给既有函数——渲染候选、判越界(`constrainsValues(field, data)`)、级联筛选项、字典带出取
哪一本的附加值、只读、标题、导出与手机「完整单据」那一屏翻名字(`exportfmt.cell_text` 与
`titles._field_text` 都带上这一单的值,明细列按同一行命中)、上游重算清单(`conditionDependencies` 吃路由的 `when` 与
那一条的 `cascadeFrom`)、一趟预取哪几本字典(`codes_of`)、删字典与删数据源前的「哪些表单在用」
全部跟着命中的那一条走,界面按 A 家候选渲染、提交按 B 家判越界那道缝从此没有。
同一分寸补在「取一个值」那一头:`fetch.sources[].when`(单源老写法也能挂)——设计期检查看
**全量**清单(源还在不在、入参引用掉没掉在地上、条件点名的字段还在不在),运行时只跑
**成立的那几条**(`binding.active_entries` ↔ `formFetch.activeFetchEntries`);**一条都不成立
是「这一格这回不取数」,不是失败**:不走 `onError` 那一档、留痕不记失败、值留在原来那一份上。
**那一家的带出也挂在那一条自己身上**(`optionRoutes[].fill`):「换一家」从来不只是换一份候选
清单,而是换一整套答案——挑的是 ERP 那家供应商,开户行与信用额度就得回 ERP 查。以前要配出这个
结果得把判据抄两遍(候选那一格写「差旅问 ERP」,取数条目再写一遍),漂开的症状最难查:**候选换了
家、带出还是上一家的**。现在那一条自带 `fill`(问哪一家 / 带什么入参 / 哪几个键写进哪几格,后两样
留空就跟着这一条走),运行时摊成一条普通的取数条目丢给**同一个执行器**(同一个入参写法、同一份
留痕、同一档 `onError` 与发起后冻结),只多一个 `fillOnly` 记号:**只写「带出去向」那几格,绝不盖
这一格刚被人在候选里挑中的那一个值**;一条都不成立、或命中的那条没自带,照旧读字段上那份 `fetch`。
界面上是那张卡片下面多出的「这一家的带出」一栏,设计期门牌写「第 N 条候选来源的带出」。
**字典那一家走 `autoFill`、流程单据那一家走 `linkFill`**,那两条本来就跟着各自命中的对象走,
不再各挂一层——所以「一家外部数据源 + 一家数据字典」那一对常见配法是:外部那一条在卡片里配
「这一家的带出」,字典那一条在「联动」面板的「字典带出」里配,两边各写各的、互不覆盖。字典那一头
以前是**配不出来**的(那一栏只认字段上那本字典,接口直传写进来的 `autoFill` 还会被当上一家的残骸
洗掉,界面带出读的也是字段那本),症状就是「界面带 A 本的附加值、提交带 B 本的」:现在带出读的是
**命中那一本**的附加值,命中那一条不是字典时一个字都不带,路由里挂着字典时 `autoFill` 不再被洗掉,
两处都没字典才洗并说一句「这一档不起作用」;那一栏现在对「只有路由挂字典」的格子也出现,可选的
附加值列是那几本的并集。见
[docs/option-source-routing-design.md](docs/option-source-routing-design.md) §5 与 §5.1,钉在
`check_option_route_fill.py`、`check_option_routes.py` 与前端 `optionSource.fill.spec.ts`、
`formFetch.routeFill.spec.ts`、`design/OptionRoutesEditor.fill.spec.ts`、`formLinkage.fill.spec.ts`、
`design/LinkagePanel.routedFill.spec.ts`。
挂了这一份清单 = 这一格有候选来源:保存那道「选项类字段未配置任何选项」的闸两边一起改口
(`api/design.py` 的 `form_problems` ↔ `utils/formLayout.ts` 的 `validateFields`),因为收拢出来的
那一格常常**故意**把自己那一份留空(先选分类再问那一家,分类没选时本来就没得挑),什么都没配的
照旧要拦;钉在 `formLayout.routed-options.spec.ts` 与 `check_option_routes.py` 第 6 段。
来路那一头也补上了:**多选那几格「同一个字段的几家」,属性栏给一颗「并成一格」**
(`utils/formMerge.ts` + `design/FormInspector.vue` + `FormDesignerView.vue:mergeSelection`)——
认「每一格都只挂一条『某字段等于某一个值』、且指的是同一个字段、取值不重复」那一批格子,
留内容最多的那一格(名字与标题都用它的,导出列与对外回写读的是字段名),条件搬进清单、
取数那几家进 `fetch.sources[].when`、各家的带出合成一份,**先搬落点再删格子**(`picks` 与
`autoFill[].to` 记的都是字段名,漏一处就是「候选换了家、带出还写着上一个名字」),被带出
写值的候选格当场勾上「带出的值也收下」,点完说实话报出「清单几家 / 条目几条 / 搬了几处 /
删了几格 / 哪几家的必填只读跟着变了」。钉在 `formMerge.spec.ts` 与
`design/FieldInspector.merge.spec.ts`。
界面上是属性侧栏「候选来源」下面那一栏「同一格换一家候选」(`design/OptionRoutesEditor.vue`,
一条一张卡片,条件按钮开的是与「满足条件才显示」同一只弹窗,能上移下移删除,起点跟着上面那套
来源走)与「外部取数」面板里每条源那颗「什么时候调这一条」。**配的人只记三步**:挑一格点
「一家一档」(它有 N 个取值就铺 N 条卡片、`when` 与备注当场替写好;取值多过 8 个的那一格直接说
「该做一个聚合接口」,不硬铺)→ 逐条挑各家的字典 / 数据源 → 带出去向:外部那几家在第一家的卡片里
配好再点「把这一家的带出套给其余几家」(各家问的还是各家那一家,与手工改走同一句 `fillForRoute`),
字典那几家点卡片上那颗「这一家的带出去『字典带出』里配」,门替他打开、那块描一圈;设计期检查逐条过,门牌写成
「第 N 条候选来源:……」,不与字段自己那一份串。生产上「出差备案申请」那张单 27 格里 16 格是
四家同构字段(`project_pms` / `project_scc` / `project_xz` / `project_dz` 再加编码、客户、阶段各四格,
全靠显示条件互相藏),现在收成 4 格,`scripts/collapse_trip_form.py` 照表上真实字段算一遍并逐家
比对(接的哪一家、候选几条、带出写到哪几格、值是不是同一个,外部取数真跑),取舍一并写在那份输出里。
取舍与已知边界见
[docs/option-source-routing-design.md](docs/option-source-routing-design.md),钉在
`check_option_routes.py`(不碰库)与前端 `optionSource.routes.spec.ts`、`formFetch.when.spec.ts`、
`FormRenderer.optionRoutes.spec.ts`、`design/OptionRoutesEditor.spec.ts`、
`design/FetchPanel.when.spec.ts`。
同一格还多了一颗开关 **`field.allowOutsideValue`(带出的值不在候选里也收下,默认关)**:
下拉框的候选以前是硬边界,外部取数 / 关联单据带出 / 字典带出写进来的值一旦不在清单里,
页面清成空、提交判「取值已不在可选范围内」——而这一格的答案本来就是系统写的,拿本地清单
判对面给的值不讲理,症状却是「明明带回来了,格子却是空的」。勾上之后不清值、不拦提交,
界面上给那一行补一条「带出」候选站着(只用于显示,不新增任何能选的东西);那句交叉规则的
提示也补成三条解法,第三条就是勾上它。这两句都靠**「这一格的值是不是系统写进来的」**那份判据,
它认的是**落点在不在这格上**,不是「这一格配没配带出」:`autoFill` / `linkFill` 都配在发起那一格
身上、写进别的格子,光看有没有配会把人挑的那一格说成系统写的;`fetch` 只有 `pick`(取一个值写进
这一格)或 `picks` 点到这一格才算,候选路由那条自带的 `fill` 是 fillOnly、永远不写自己;反过来,
**隔壁那一格**的带出指着自己也算(同表字段清单会递进设计期检查),免得一张靠隔壁喂值的下拉被误说
「这一档暂时不起作用」,人把勾去掉、提交又被判越界。
**下拉里打字要真的搜得动**:候选搜索那一趟发出去的入参表里永远有 `keyword` 这一项(运行时给的,
不在这一格配的入参清单里),而模板只认**自己引用过**的名字——地址上写 `?keyword={arg.keyword}`,
或请求体里加一行 `keyword` 取同样的写法。两头一个字都没写,上游每次收到的就是同一句话,
@ -1014,6 +1262,15 @@ python3 scripts/audit_storage.py --to-minio # 把本该进 MinIO
今天它就是「候选来源 = 流程单据、挑选方式 = 弹出框」那一格,表现跟以前一模一样:
挑选走 `GET /work/related`(范围限「我发起 / 我办过 / 我被抄送」,管理员不限),
回显走 `GET /work/summaries`,`relationProcess` 限定只允许挂某个流程的单。
**挂上来的每一条都点得开**:只读那排标签的名字、编辑态挂在框里的标签、下拉里那颗标签、
单选时框里那一句话,名字上挂的都是 `/work/:job`(`target="_blank"`——看完整张单退回来,
手上填的这一张还在)。PC 与手机共用这一条路由(`WorkDetailView` 自己按设备换手机版那一屏),
所以手机上一样打得开;「完整单据」那一屏(`mobile/MobileFormReader.vue`)以前把 job 原样
摊出来,现在那一格也走同一只 `OptionPicker` 的只读态,念回标题、点得开那张单。只有
「来源 = 流程单据」这一条给链接,改存了单号又翻不回 job 时宁差不给(`processHref`)。
这一排的牌子还收了一号字(`.picker-dense`,11px):单据标题太长,默认字号两三个就占满一行,
而全局那条 `.field-tag` 是人员选择器与附件共用的,不动它。取舍见
[docs/option-source-design.md](docs/option-source-design.md)。
挑流程不再在一长串流程名里翻:**先选流程类型、再在那个类型里选流程**
(`components/oa/design/ProcessPicker.vue`,类型带条数、没归类的单独一档「未分类」、草稿标出来;
选中流程会把类型筛子钉到那一类,手动换类型且当前流程不在该类就清空)。明细表列上同一套组件换
@ -1022,6 +1279,34 @@ python3 scripts/audit_storage.py --to-minio # 把本该进 MinIO
全跟着来,等于一个「值由字典管的多选框」)、挂**列表型外部数据源**(几千个物料里搜一条,
存源给的编码)。原来的 `components/oa/RelationPicker.vue` 没有别的用途了,弹窗那套原样
搬进 `OptionPicker`,少一份各写各的实现。
- **关联带出**(`field.linkFill`,配在「候选来源 = 流程单据」那一格上):挂上来的那几张单,
把里面的值写进**这一张单**——`{"pick": "data.amount", "to": "items.amount"}`,`pick` 的写法
与「从另一个流程带数据」一字不差(同一份 `processdata.payload_of` + `fetch.pick_path`,
`work.单号` 这类单据本体、`data.金额` 这类对方表单字段、`[部门=研发部]` 筛行与 `sum()` 都认)。
**挂几张的时候两类去向行为不一样**,这是这一层的分水岭:写进**主表字段**是「几张单合成一个值」,
按配的那一档合(取第一个 / 拼接 / 相加 / 取最小 / 取最大,就是外部取数那句 `binding.merge`,
与明细剩几行无关);写进**明细表的列**是「一单一行」,新关联的在末尾补一行、取消关联的删行、
留下的行只刷配到带出的那几列,凭据是行上那一格 `_link`(服务端写的留痕,导出打印都看不见它,
`normalise_rows` 为它单开口子)。**明细行只在挂着的那串值变了时才重排**(判据是
`data["_linkfill"]` 那份留痕),否则第二环的人提交一次,他在第一环手工删掉的那一行就被复活了;
关联一变才整趟对账——该补的补(人删掉的那一行只要还挂着就补回来,加在末尾不打乱人排的序)、
该删的删、人改过的其它列一个字不动。权威在后端:`engine._apply_form_runtime` 里排在公式之前
(`sum(items.amount)` 那类公式、额度、阈值读到的都是刚补好的那几行)、排在必填之前
(**带出来的那一格可以勾必填**,带不出值就真挡住提交)。**入口有四处,进的是同一栏**:
设计器顶上「关联带出」总览、画布上那两枚角标(关联那一格标「关联带出」、明细表那一格标
「被带出」)、明细表属性里的「带进这张表的关联字段」、那一格自己的属性面板,
见 `docs/relation-link-fill-design.md` §2.5。界面上那一栏是即时预览
(`design/LinkFillPanel.vue` 配、`FormRenderer.vue` 现算,`POST /work/relation-values` 把这一屏
所有 `pick` 与所有关联字段并成一趟问回——路径解析只留后端一份),手改那一格没用。
预览那一趟带一道可见性闸(照 `GET /work/summaries` 的分寸,不相干的静默少回,多认一档
「确实挂在正在填的这一单上」,否则办理环节的人看着这一栏一片空白),**引擎那一份不带这道闸**。配歪了保存这一刻说得出来:
指向的格子不在了、两条抢同一格、`sum` 配上装不下数的那一格、来源不是流程单据。
要同时挂**两类**单子就挂两格(报销单一格、采购单一格,各配各的映射),带进同一张明细表也
各带各的行——删行的凭据是「这一行的来源还挂在不在别的格子上」,不是只看自己这一格,
否则后算的那一格会把前一格刚补的那几行当成「自己这边取消关联了」删干净。
只有**主表字段**配得了这一层:明细列里那一格挂的也可以是单据,但「这一行的那张单 →
另一张表的几行」在界面上没人能预期,那一层要带数据走「从另一个流程带数据」。
方案见 [docs/relation-link-fill-design.md](docs/relation-link-fill-design.md)。
- **联动跟着字段的变化一起动**:级联下级给哪些项、显隐 / 必填 / 只读、字典带出那几格,
判的都是**当下这一份表单数据**,所以一改就动,不必等人点一下别的格子。判据挂在数据上
而不是挂在某一条写入通道上——公式算出来的金额、外部取数、别的系统回填,都不经过录入框,
@ -1030,6 +1315,55 @@ python3 scripts/audit_storage.py --to-minio # 把本该进 MinIO
(选物料带出单价,单价那一格又决定下一格),只扫一遍结果就取决于字段在表单上的先后顺序
(`utils/formLinkage.applyLinkage` ↔ 后端 `dicts.apply_auto_fill`,两边同一本账、同样收敛)。
- **条件右边可以是另一格(`rules[].valueField`),不只有一个写死的数**:「结束日期晚于开始日期」
「报销金额超过带回来的预算余额」比的两个值都是填单的人才知道的,写死一个数要么没人维护,
要么第一天就过期。落库仍是那一套结构化条件(`{match, rules}`),只是规则的右边多一档:
配了 `valueField` 就读那一格此刻的值,`value` 让给它(与阈值的 `rightField` 同一件事)。
三条口径钉死,免得两头各算一个结果(`utils/formLinkage.ruleOk` ↔ 后端 `dicts._rule_ok`):
**右边那一格还没填,这一条就不成立**(两个都空着时 `"" == ""` 成立,格子会在单据刚打开时
就莫名其妙露出来);被比的这一格**算这条条件的上游**(`condition_dependencies` 一起收,
所以改右边那一格,显隐 / 必填 / 只读当场跟着翻面);能挑哪些格、哪些判断讲得通,按**两边值的
形状**收窄(`linkagePairOps`:数字与日期比大小,选项只比相等,附件与明细谁都比不了)。
**顺手补了比大小那一档的一个老毛病**:它以前只有 `Number()` 一条路,日期串一律换算成
`NaN` / 换算失败,于是「离职日期 晚于 …」这类界面明明给得出来的条件**永远不成立**,
配的人和看的人谁都不知道。现在认得出 ISO 写法就按字面比(定宽零填充,字典序就是时间序,
两种语言一个结果),固定值那一档同样跟着修好。钉在 `formLinkage.pair.spec.ts` 与
`LinkageConditionDialog.pair.spec.ts`,后端那侧用同一批数据跑过一遍 `dicts.condition_ok`。
- **显示条件也能判「自己这一格」:条件里点名的那一格,可以就是配条件的那一格**:用户那句原话
是「表单中字段的显示判断条件,需要可以设置判断本身字段的值情况来确定是否可以展示」。以前这一档
压根配不出来——设计器把本字段从条件清单里筛掉,后端保存还要报一句「联动条件引用了自己」,
于是「外部带回来的合同编号有值才露这一格」只能造一个中间变量(隐藏的公式 `=IF(合同编号<>"",1,"")`)
绕一圈,多出来的格子还会漏进导出与打印,条件念出来是「中间值 等于 1」,没人知道它在说什么。
放开以后**落库一个字都没变**:还是 `{match, rules}`,只是允许 `rules[].field`(或右边那一格
`rules[].valueField`)等于本字段的 key,三栏(显示 / 必填 / 只读)与选项级 `when` 都能挑自己,
没有存量要迁。判法走的还是原来那条 `compare`——**读的就是这一格此刻的值**,没有第二套引擎,
也没搞「露过一次就不再收回」那种只活在一次打开里的粘性状态(服务端算不出来的东西,两边迟早分叉)。
侧栏「满足条件才显示」下面多了两颗一键开关「本字段有值才显示 / 本字段没值才显示」,直接落
`notEmpty` / `empty`,再点一下撤掉;条件清单里本字段排最前面、标成「本字段」,摘要也念成
「本字段 已填」,不跟表单上另一个同名字段混。放开「判谁」的同时钉四条:
**不放宽「怎么判」**(级联上级选自己、同一条规则左右两头是同一格、指向不存在的字段,三句照旧要说;
即便同一条条件里还有指向自己的那一条,也只放行指自己那一条);
**自指不进级联清值那一圈**(`dependsOn` / `depends_on` 照旧把「自己」摘掉,否则刚写进来那一份
会被当成越界值抹掉;`conditionDependencies` 留着它,设计期与界面重算要读);
**只被自己那句条件收走 / 锁住的格子,提交时这一笔值照样收下**(`formruntime.self_gated_keys` ↔
`formRuntime.writableIgnoringSelf`:把三栏里读自己那几条摘掉以后本来就填得动,才放宽——
「有值才显示」「有值就锁住」都会在人刚敲完那一刻把格子收走,按「这一环改不动」退回原值
等于把人写的字抹掉。环节明写隐藏、被别的格子的条件挡住、`description` 那种压根没有录入框的
类型,三档一概不放宽;界面露不露、必填要不要、阈值 / 额度 / 取数挡不挡人,读的还是带自引用的
那一份条件);**改名时那一格自己那几条条件跟着搬**(`utils/formRename`:界面上它念成「本字段」,
留在旧名字上看不见也修不回,旧名字哪天被新格子占用还悄悄从「判自己」变成「判那一格」;
别的格子上读旧名的那句照旧不动,那是看得见的一句读法)。
**这一档真正合身的是值由系统写进来的那一类格子**(外部取数 / 字典带出 / 关联带出 / 公式 /
别的系统回填):这一格由人填、又拿自己的值决定露不露,填一个字它就当场藏起来(光标还停在上面,
格子已经没了,值不会丢),所以挑中自己时那一行下面当场把这句话写成黄字;要「有值就别让人改」,
配的该是「满足条件就锁住」。**顺手收了一处两边的分叉**:判「填没填」时后端
`dicts._is_empty` 一直把一串空格算没填,前端 `isEmptyValue` 只认空串,「本字段有值才显示」
能算出两个结果(界面露出一行空白,服务端判它没填),现在同一把尺子。方案、取舍与那一格
在四种情形下的下场见 [docs/field-self-visibility-design.md](docs/field-self-visibility-design.md);
钉在 `formLinkage.self.spec.ts`、`FormRenderer.self.spec.ts`、`LinkagePanel.self.spec.ts`、
`formRename.spec.ts`,后端用同一批数据跑过一遍,钉在 `scripts/check_self_visible.py`。
- **字典带出取哪一列(`autoFill[].pick`)用的是「显示 / 存值」那两列同一套写法**:留空取名称、
`value` 取**键值**、`extra.单价` 走点路径,字典项自己另几列(`parent`)也认。以前 `pick` 只往
附加值里找,于是「把字典的键值也写进别的格子」这件事在界面上根本没地方说。放开之后老配置
@ -1140,6 +1474,12 @@ python3 scripts/audit_storage.py --to-minio # 把本该进 MinIO
同样的两处各算一套。现在这一格在这一环不存在,就不在这张单子的功课里——
唯一的例外照旧留在后端那一句里:字段自己勾了「默认隐藏」的**系统带出与公式**
(编号、金额大写)仍然要有值,藏起来不等于可以不生成;环节显式接管那一格才算放手。
**但「因显示条件不成立」被收走的那一格不算这一笔**(2026-11 补的这一寸):那种配法说的是
「这一单用不到它」——既没有录入框,又不适用这一单,再催一句「还没填写」就是让人对着一片
空白找输入框。生产上「默认隐藏 + 显示条件 + 必填」的系统带出格就是这么把自己钉死的:
办理那一屏按条件露,条件一翻走提交永远过不去。判据只有一句
(`formruntime.hidden_by_condition` ↔ `utils/formRuntime.hiddenByCondition`),
钉在 `check_option_routes.py` 第 8 段与 `formRuntime.hidden.spec.ts`。
**带出、阈值、额度这三样对每个字段都开着**(口径只有一处:`utils/fieldCapabilities.ts`,
41 种字段类型按「这一格装得下什么」分组,只有标题 / 分隔线 / 说明文字 / 分组标题 / 空白格
这几样纯排版挂不上):
@ -1348,8 +1688,13 @@ python3 scripts/audit_storage.py --to-minio # 把本该进 MinIO
统一念成「姓名(账号)」(`utils/personLabel.ts`);
- **谁算哪一段**:发起人、工号、所在部门、流程名称、此刻的日期时间,发起页在登录态里
当场就填好;直属上级和部门负责人要查组织库,由引擎发起时写进 `work.data`
(`service/autofill.py` 是唯一口径),那一刻界面上写明「提交后由系统自动填写」,
不拿猜出来的人名糊上去;
(`service/autofill.py` 是唯一口径),那一刻界面上那一格就空着——**不拿猜出来的人名糊上去**,
也不自带一句说明(空着那一格写的是全平台那句 `--`,不是真空);想在框里留一句话,
是「没值时显示的文字」那一栏的事(见「表单设计」那一节);
单据编号(`auto: serial`)也归"当场给不出"这一类:真号要看编号时机(`oa_process.serial_config.at`),
配成「新建填单时就生成」那一档时发起页当场占一个号、当场亮在格子里
(`POST /job/serial/reserve`,凭条随提交或存草稿交回),其余几档在发起页就是 `--`,
表单设计器的「预览」里则给一个按规则算出来的样子(只读不占号);
- **只在发起那一次带**:前端只在没有单据可挂时(发起页、草稿)填自己,办到第二环节的
表单里登录态那个人是审批人不是发起人,不能拿他当申请人;草稿里填过的、替别人提单时
改过的申请人一律不动;这一格被环节配成只读时,这次提交的值在落库前就被丢掉,
@ -1416,6 +1761,22 @@ python3 scripts/audit_storage.py --to-minio # 把本该进 MinIO
`variant="rail"` 与弹窗里的 `variant="panel"` 用的是同一个 `NodeInspector`、同一份
`nodeInspectorProps`,右栏在弹窗打开期间不挂载,两处不会各持一份状态。
**同一句话也管属性侧栏里那一块块面板。** 表单设计器那条属性侧栏只有 320px,装得下「这一格
叫什么、是什么类型」,装不下一张要多列并排的表——「关联带出」那几只下拉曾经整个撑到卡片右
边框外面去。口径是一条:**能摊开的都摊到弹窗里**,判据不是"这块重不重要",而是"它有没有
摊得开的地方"。壳子是 `components/oa/design/SidePanel.vue`:侧栏那一行只说什么配置、现在配
成什么样(摘要 + 角标,配过的描成主色),点下去门里放的是原来那块面板本体,**一行没重写**。
进弹窗的有候选来源(含显示映射与关联带出)、明细表列编辑器、联动、外部页面、额度、外部取数、
阈值、标题与编号生成规则,以及右栏里的连线配置;名称、标识、类型、必填、宽度这些单控件
**照旧就地改**——一天点几十下的动作不配多一次点击。环节那侧的八块配置(审批人规则 / 抄送 /
字段权限 / 外部审批 / 写回 / 闸门)**没往里再叠一层**:常驻 352px 那一栏本来就只摆摘要 +
入口,点下去是上面那颗 extra-wide 弹窗,面板在里头摊得开,再叠一道就是弹窗摞弹窗。门是即时
的:改动当场生效,没有「确定 / 取消」,撤销照旧退得回去;唯一的例外是连线,它点「应用到画布」
才算落笔,所以那扇门自己带按钮。从别处「跳到那一格」的信号也一路把门打开(`reveal`),换了
格子就把门关着(`resetKey`)。撑出界那一截本身也是个 bug,一并修了:`grid-cols-[1fr_1fr]`
的轨道有隐式 `min-width: auto` 不收缩,`Select` 根节点也缺 `min-w-0`。取舍与坑见
[docs/designer-panel-dialogs.md](docs/designer-panel-dialogs.md)。
**「表单与字段权限」那一格开始环节也有。** 面板本体在 `components/oa/design/FormPermsPanel.vue`,
人工环节与发起环节共用同一份判据(逐格四档 + 「标签页」整片 / 每一页那两层隐藏 + 「全部只读」
那颗按钮 + 换表单时收掉不存在的字段),存的都是同一份 `activity.config.formPerms`。
@ -1451,9 +1812,33 @@ python3 scripts/audit_storage.py --to-minio # 把本该进 MinIO
勾了默认隐藏、条件是按三条部门路径放行,而整条流程没有一个环节点名它,谁也看不见它;
`出差备案申请` 那六格项目 / 客户只是靠发起与审批环节显式给了可编辑才露出来,
条件同样成立的部门主管那一环(`formPerms` 是空的)一格都不显示。现在这一寸挪到条件后面
(`formruntime.hidden_by_default` / `formRuntime.hiddenByDefault`),环节显式隐藏的优先级不变,
回看与打印那一屏手上没有这一份数据、算不了条件,仍保守按隐藏算。钉在
`check_hidden_field_rules.py` 与 `formRuntime.hidden.spec.ts`。
(`formruntime.hidden_by_default` / `formRuntime.hiddenByDefault`),环节显式隐藏的优先级不变。
**露不露从此分两屏说。** 办理屏(有人正改着值)联动**往严收**,格子跟着此刻的值一起露一起藏;
回看屏(`readonly`——单据详情、我的已办、打印、手机端「完整单据」)拿单据上存的**那一份值**评条件。
这一屏先前留的是「只往宽放」:只把「默认隐藏 + 显示条件」那一组摆回来,不凭条件收任何格子。
上线后又挨了一句原话——**「提交流程之后回看页所有字段都显示了」**:配了「有值才显示」的那些格子
在办结之后整排摊开,明明这一单用不到它。于是这一屏改成按存过的那份值评,只多收一种:
**条件不成立、且这一格本来就空着**(只敲了几个空格算空着)。有值的一律摊开——条件翻走了不代表
那一笔没填过,收起来才是让存过的东西凭空消失;这一寸是刻意留的,要全收干净得再加一颗字段级开关。
判据只有一句 `utils/formRuntime.readbackHidden`,桌面
(`FormRenderer.vue` 里 `hiddenOnScreen` 那一处,不再对只读屏传 `null`)与手机上
(`mobileVisibilityOf` 的 `ask.readback`)读的都是它。优先级一寸没动:环节明写隐藏最高,
明着给只读 / 可编辑 / 必填的那一格照样要得回去,没配条件的「默认隐藏」(单据编号、金额大写那一类)
照旧全局不露。生产上 `出差备案申请` 那八格项目 / 客户 / 阶段没的正是这一寸——办理那一屏按
「项目分类」露得好好的,办结之后一格不剩,而那份值明明就躺在 `modelValue` 里。钉在
`formRuntime.hidden.spec.ts`、`FormRenderer.readback.spec.ts`,后端那一侧钉在
`check_hidden_field_rules.py`(办理屏那一句两边镜像,回看屏这一句只在前端:那一屏是前端拿归档的
`design_snapshot` 加存过的值渲染的,明细导出 `service/exportfmt.form_export_fields` 本来就全摊)。
**手机上那两屏以前连这一寸都不认。** 摘要与「完整单据」读的是裸 `field.hidden`,`visibleWhen`
一个字都不评:电脑上一拨条件就露出来的格子,手机上划到底也没有它;反过来条件已经翻走的格子,
电脑上不摆了,手机上还留着一行谁也改不动的值。现在这一句并到手机上唯一那句判据里
(`utils/mobileLayout.mobileVisibilityOf` 第 4 道闸,取值 `cond`):**待办那一屏给得出那份表单值,
格子跟着电脑上一起露一起藏;单据详情那一屏给不出"正在填的那一份",但手上还有存过的那一份,
于是按上面那一寸**只放行不收**;设计器面板连值都没有,按"这一格归条件管"报**(清单上标
「按显示条件」,不代它记一笔 `show`)。与桌面那两句 `effectivePerm` / `readbackHidden` 一句
对一句,取舍见 `docs/mobile-form-layout-config.md` §4.2。
钉在 `mobileLayout.spec.ts`、`useFormPlan.spec.ts`、`MobileFormSummary.spec.ts`、
`MobileFormReader.spec.ts`、`MobileLayoutPanel.spec.ts`。
**字段权限多一个「沿用」态。** `activity.config.formPerms` 里没写过这个字段,就是
「沿用字段自己的必填 / 只读」,界面上单独一档(`process.permInherit`),点它是删键而不是
@ -1531,17 +1916,20 @@ python3 scripts/audit_storage.py --to-minio # 把本该进 MinIO
在途的说「按第 3 版设计在走」、已经办结的说「按第 3 版设计办结」,悬停说清改动只对之后的
新单生效;流程设计器那个版本号徽标上挂了同一套话的落款。接口上 `GET /job/{job}` 多了
`design_pinned` / `design_version` / `process_version` / `design_touched_after_start` 四个字段,
归档件(`GET /work/{id}` 与它共用同一个拼装函数)一样带着这四个字段。
归档件(`GET /work/{id}` 与它共用同一个拼装函数)一样带着这四个字段;冻过结的**在途**单还多带两份
跟当下配置有关的报文——`forms_live`(`form_id -> 此刻的表单内容`)与 `activity_perms_live`
(`activity_id -> 此刻的环节字段权限`,只装与冻结那一版不一样的环节),合起来只给手机端审批那一屏
当摆法用,见 `docs/mobile-approval-layout.md` §4.5。
口径都写在 `app/engine/definition.py`:`pin()` 拍照,`for_work(db, 单据或待办)` 取
「这张单眼里的那一版」。引擎与接口里凡是手里有单据 / 待办的地方都走 `for_work`,手里只有
流程 id 的地方(设计器、流程模拟、发起那一刻)走 `load` 读当前设计;两条路拼定义用的是
同一个 `build`,不会长出两种行为。回归由 `scripts/check_design_pin.py` 守着(46 条),
同一个 `build`,不会长出两种行为。回归由 `scripts/check_design_pin.py` 守着(57 条,其中第 3b / 3c 组守的是「手机端那一屏跟当下表单内容与环节字段权限」这条例外),
其中第 9~12 组守的就是归档这道坎:引用跟着搬、归档详情页报的是冻结那一版、没有引用的
老归档单照旧现读、启动回填按办结时刻的高水位往前推、快照与流程一起没了也不能把人锁在
门外,以及删流程只清没人认领的那几版快照——归档单认着的那一版留在库里。
还跟着当前配置走的两件事,说清楚免得踩:
还跟着当前配置走的三件事,说清楚免得踩:
- **外部审批接口开没开**(环节那格 `openApprove` 打开没有、对哪个应用开口):管理员当场
关掉,第三方在 OA 之外的表态就当场收不进来。这一格是「闸口」不是「图纸」,跟着人走。
@ -1549,6 +1937,12 @@ python3 scripts/audit_storage.py --to-minio # 把本该进 MinIO
一次查库读实库那行),不拿冻结那一版的配置拦人——否则横幅拦着审批人、引擎其实还收得住。
- **字典项、外部数据源、额度台账、人员与部门**这类引用数据:本来就是设计之外的事实,
改了照常即时生效,在途单也跟着变(选项、额度余额这些停在过去反而对不上账)。
- **手机端审批那一屏摆的是哪几格**(两处配置:表单里那几栏展示配置——哪几格上屏、顺序、每格怎么摆、
显示条件;流程设计器「环节 → 字段权限」——隐藏 / 只读 / 可编辑 / 必填):改完当场见效,
已经在路上的单子在手机上跟着变。这是「改表单不影响在途单」唯一开在**摆法**上的一道口子——
该填哪几格、必填缺哪几格、提交校验、桌面详情、打印、导出、引擎认值读的仍是这张单冻住的那一份。
报文上多出来的那两份叫 `forms_live` / `activity_perms_live`,只给冻过结的在途单,只装真改了的那几张
(口径与取舍见 `docs/mobile-approval-layout.md` §4.5)。
## 权限角色
@ -2022,7 +2416,7 @@ sqlite 上(55 项:谁按得动、窗口怎么算、留痕与通知、终止
| 办结之后按对方格式生成一张凭证 | 反写模板 `oa_integration` | 「集成配置」页,字段一格格映射 |
| 单据有动静就通知外部系统一声 | 事件订阅 `oa_open_webhook`(七个事件,HMAC 签名,默认不带表单数据) | 「开放平台」页 |
| 外部系统主动查/发起/代办 | 开放接口 `/api/v1/open/*`(应用令牌 + 五个作用域 + 限流与调用留痕) | 「开放平台」页建应用 |
| 同一条待办提醒送到邮箱 / 钉钉飞书企微群 | 消息渠道 `oa_notify_channel`(六个事件各渠道订阅) | 「消息通知」页 |
| 同一条待办提醒送到邮箱 / 钉钉飞书企微群 | 消息渠道 `oa_notify_channel`(七个事件各渠道订阅,含「流程被干预改道」) | 「消息通知」页 |
| 待办推到个人手机上,点开就是那条待办 | `hub_wecom` 渠道:交给统一身份 Hub 代发企业微信应用消息(本系统不持有企微密钥,卡片点开回到现成的免登回调) | 「消息通知」页,见 `docs/hub-integration.md` §15 |
三条外发路共用同一套投递底线:**与业务动作同一事务入队 → 提交那一刻把后台投递线程当场叫醒 →
@ -2042,6 +2436,30 @@ sqlite 上(55 项:谁按得动、窗口怎么算、留痕与通知、终止
一模一样的消息),**但推到人手机上的 `hub_wecom` 反过来是一人一条**——卡片点开是"我那条待办",
而且谁没绑企微、谁不在可见范围,得有一行记录留得下那个原因。
### 通知消息这一叠什么时候该退场
右上角铃铛里那叠「通知消息」原来**只进不出**:`engine.notify()` 写进去之后没人回收,
接口只有「点开算已读」「全部已读」两个手动口子,而它指向的待办是会消失的——办结删行、
或签把同级一起结掉、转办与交接换持有人、终止与办结清空整单,每一条都不回头动站内信。
用户看到的就是:待办全办完了,四条「您有新的待办」还挂在面板上、小红点不灭,
按了「全部已读」列表照旧摆在原处。
判据收成一句:**一条提醒值不值得摆着,看它指向的那件事还在不在收件人自己手上**。
`app/service/notify_settle.py` 两条 UPDATE 管住 `task` / `press` / `expire`(点开要办事的那一族,
与 `channels.HUB_TASK_EVENTS` 同一族)与 `read`(跟着待阅走),`completed` / `control` /
`meeting` / `integration` / `check` 那几类说的是**已经发生的一件事**,永远不动——终止时
发给被清掉那些人的「待办已终止」是新消息,不是过期提醒。收尾挂在**读出口**
(列表 / 未读数 / 工作台三处),不挂在写出口:待办消失有七八条路子,逐处挂钩子等于
留七八个"漏挂一处就再报一次"的坑,而升级前那些早就该退的存量通知一条也补不回来。
收尾是标已读、不是删行,投递记录 `oa_notify_delivery.notification` 那条对账链不断。
界面这一侧同步一次口径:铃铛下拉、手机版弹层、首页那张卡片**只摆没读过的**——
这一屏是"还有什么没告诉你",不是历史归档,翻旧账去待办 / 已办 / 待阅 / 单据详情。
完整口径、为什么不在引擎里挂钩子、以及那条"没未读时一条 UPDATE 都不许多跑"的预算,
见 [docs/notification-channels-design.md](docs/notification-channels-design.md) §8;
验收 `backend/scripts/check_notify_settle.py`(内存 sqlite,38 项:真转办、真或签、
真终止之后通知跟着退,另钉住待办还挂着时一条都不许多收)。
### 装到手机桌面上(PWA)
前端是可安装的 PWA:`/manifest.webmanifest` + 图标 + 一层只兜底的服务工作者。
@ -2108,7 +2526,10 @@ sqlite 上(55 项:谁按得动、窗口怎么算、留痕与通知、终止
两颗粒子改一格;清单上那颗「展示 / 不展示」写的还是格子上的 `mobileHidden`,与属性面板那颗同源。
配置存在 `content.layout.mobile`,**后端一行没动**(`clean_formats` 原样存回 `layout` 里的东西)。
没勾这一档的表单走的还是上面那套按字段类型的自动归置,一个字没变;勾了之后环节字段权限、
整单「默认隐藏」、本环节要填的那几格三道闸照旧,末尾「完整单据」按配置给不给——不给的话
本环节要填的那几格照旧压得住(整单「默认隐藏」这一档改了口径,见下面一段;格子自己那句「显示条件」
在待办那一屏也照样算数——它跟电脑上同一时刻露、同一时刻藏,回看那一屏拿存过的那份值只把
「默认隐藏 + 显示条件」那一组摆回来、其余照旧摊开,见 `docs/mobile-form-layout-config.md` §4.2),
末尾「完整单据」按配置给不给——不给的话
那条路收进顶栏的 `···`,要的是"只有一节",不是"这一单在手机上看不全"。
这一档又收掉两处手机上的废话:**节名没配、整屏又只有这一节的时候不摆那一行标题**(从前那行写的是
代码补的「表单内容」,可上面那排页签已经写着这三个字,等于同一句话占两行,还搭上「11 项」和一颗
@ -2118,12 +2539,76 @@ sqlite 上(55 项:谁按得动、窗口怎么算、留痕与通知、终止
读法,路径被当人员引用问了一遍姓名接口,回来拼成「路径(路径)」摊三行;现在 `deptText` 取路径末段,
与桌面只读态取的部门下拉 label 是同一个名字)。取舍、口径与验收见
[docs/mobile-form-layout-config.md](docs/mobile-form-layout-config.md)。
这一档上线后又挨了一句原话:**「手机端配置的字段显示,感觉还是被默认隐藏遮住了——手机这边完全
按手机端这边的配置来展示,就是我只配置哪些字段显示就展示。」** 生产那张单上 `PMS项目编号 /
PMS项目名称 / VDI项目编号 / 行政项目编号 / 定制项目编码…` 全挂着「默认隐藏」(电脑上不占位,
取数照跑),于是面板上每一行都写着「展示」、底下那句统计也算它们上了屏,手机上却一格都不出现。
现在**「默认隐藏」不再压住手机端这一屏**:清单上给它点上「展示」,配置里记一笔
`fields[].show: true`,手机上就摆;没点过的仍旧不摆——否则开关一开,整张表里藏着的格子会一次性涌出来。
环节那边明着给了只读 / 可编辑 / 必填也算它要露出来(与桌面 `effectivePerm` 同一句话),
而环节说「隐藏」谁都压不动:那一档问的是这个人此刻能不能看。于是**摆不摆的判据收成一整块**
(`utils/mobileLayout.ts:mobileVisibilityOf`),摘要、「完整单据」、设计器那张清单、底下那句
"上屏几格"读的都是它——从前分在四地各写一遍,才会有"面板写着展示、手机上没有那一格"这种对不上号。
「完整单据」那一屏也跟着改:清单点了名的默认隐藏格它照样摆,配过的短名两屏念同一个名字。
面板那头顺手补了好用的:清单顶上那颗筛选(全部 / 已上屏 / 已收起)与搜字段名(三十几格翻不动,
筛着时上移下移停用),每行那颗「展示 / 不展示」挂 tooltip 说清是谁拦的,电脑上默认隐藏的格子
顶着「电脑端默认隐藏」那枚角标——它现在说的是"这里点一下就能翻案",不是"配了也没用"。
这一档上线后又挨了一句原话:**「手机端的审批表单我希望根据表单配置的展示规则而变化,
而不是一发起就冻结。手机端需要跟随调整而变化。」** 单据发起那一刻整份设计冻进
`oa_process_snapshot`(含那几张表单的内容),这是「改图改表单不影响在途单」的落点,
代价是配表的人改了「哪几格展示、什么顺序、每格怎么摆、显示条件」,**手机上那一屏看不着**,
得等这张单走完。现在**手机端审批那一屏读的是「此刻」那份表单内容**:待办详情那一屏的摘要与
「完整单据」、在途单的单据详情,改完当场见效;桌面只读渲染、打印、明细导出、必填校验、
环节字段权限、引擎落库认的那些格**照旧读冻住的那一张**——单据是凭证,「这一屏给这个人看哪几格」
可以跟着配置动,「这张单当时该填什么、他改了哪几格」不能因为别人改了表单当场换掉。
分叉只开在摆法这一寸,口径与验收见 [docs/mobile-approval-layout.md](docs/mobile-approval-layout.md) §4.5。
后端只多一份报文(`runtime._job_response` 的 `forms_live`,键是 `form_id -> 此刻的 content`):
只有**冻过结的在途单**算,只装**真改了**的那几张,没人动过就是 `{}`(报文与这一改动前逐字节一致);
内容走 `autofill.form_content` 那层进程内快照,没人改表单时一条 SQL 都不排,设计器保存那一刻
那层快照当场作废,所以是「保存即见效」。认的是**同一张表**——把环节换成另一张表单(`id` 变了)
不算调整,在途单照旧看自己冻住那一张。守卫:`check_design_pin.py` 第 3b 组、
`MobileTaskView.liveForm.spec.ts`、`WorkDetailView.spec.ts`;设计器版本号那颗 tooltip
(`process.versionPinTipMobile`)也把这条例外写进了落款。
这一档上线后又挨了一句**「现在为什么手机端在途的表单为什么还是展示的不一样呢?不是跟我配置的展示呢」**。
拿生产上那十张在途报销单逐个对,两处真没跟到(都已修,`docs/mobile-approval-layout.md` §4.5 有对照表):
一是**环节压根没绑表单**——那三环 `activity_nodes[环节].form` 是空串,页面回落到 `forms[0]`,
而新代码拿空串去 `forms_live` 里查,永远查不到,手机上静默退回冻住的那一张;认 id 那三步
(环节 → 待办 → 兜底)从前散在三处,现在收成 `utils/mobileLayout.ts:mobileFormRead()` 一处,
一次交出 `{ frozen, mobile }`。二是**还有半份配置冻在另一张表上**:露哪几格一半写在表单里,
一半写在流程设计器「环节 → 字段权限」那一格,而它冻在 `activity_nodes[环节].form_perms`——
管理员把 `checkTotal` 那几个审定格从「隐藏」改成「只读」,手机上照旧不露。于是报文再多一份
`activity_perms_live`(同样只回改过的环节,前端取不到就回落到冻结那份),它只喂手机端那一屏的
`displayPerms`,填写块与必填仍读冻住的那一份。生产上执行董事那张单从 11 格变 22 格、部门主管
那张从 9 格变 17 格,财务总监那张字段权限本来没改,只跟着表单内容与显示条件走(25 → 20 格)。
新增守卫:`check_design_pin.py` 第 3c 组、`mobileLayout.spec.ts`(含那个空 `form` 回落)、
`MobileTaskView.liveForm.spec.ts`、`WorkDetailView.spec.ts` 各补了相应的回归。
手机上的**审批记录不再折叠**(原话:**「审批记录不要收折,直接往下面展示,收折了让人误以为缺少环节」**)。
从前那条时间线只摆最近三步,其余收进一颗「展开更早 N 条」,批了七八环的单子打开只看得见两环加一颗钮,
人以为这张单少走了几环——省下的那两三屏不值这个误会,那颗钮连同 `RECENT` 一起删了,整条从头摊到底
(发起那一行照旧在最前,长意见还是先给两行加一颗「展开」,改单与附件照旧折成一行)。
待办列表那头又挨了一句**「手机端也需要有批量处理的功能」**。桌面那一套(表头复选框 + 工具栏那颗按钮)
在 390 上摆不开,手机上把它做成**一档**:顶栏一颗「批量处理」按下去整张列表进选择档,卡片左边那颗勾
替掉右边的「去批」和箭头,点卡片是勾上 / 取消而不是进详情(一次批三条不该点六下);操作位在屏幕下沿
那一横条——`全选 / 清空` + `已选 N 条` + 「批量处理 N」,全在拇指底下;那一层照手机上「动作一律从下沿
推上来」那条规矩走 `MobileSheet`,出口不做下拉(浮在 bottom sheet 里会被截掉半截)而做一排按钮,意见底下摊引擎逐条回的
失败原因,改完可以只重试那几条。判据与桌面共用一条:能勾的是 `!oa_locked`(这一环的表态已交给外部系统),
全选不硬塞它,手动勾上照样交——那句失败原因写清了去哪儿办,比界面挡着不吭声好;退档把勾收掉,
一批全办完自动退出选择档。**提交时按攒下的那一沓(`useMobileFeed` 的 `feed`)找单子,不按当前页找**,
不然往下滑过三页勾 25 条会莫名少一截。桌面那一版一个字没动,两条分支共用 `openBatch` / `confirmBatch`
与那份「可用出口 = 每条被选待办路由名的交集」。
另一处顺手修的:没配核验闸门的单子不再摆「外部核验」那块面板(后端一直发着 `configured`,
是前端没认;真送过一次审的单子仍然照摆)。
预览台 `frontend/preview-mobile.html`(dev only,`screen=home|list|detail|work|profile`,
`form=tabs` 换成生产上那张分页 + 外部页面的报销单,`form=custom` 换成配了手机端版式那一档
(只出一节)作对照,`screen=panel` 单摆设计器那个「手机端」面板,`open=reader` 直接把「完整单据」点开),
`screen=list` 加 `select=on|sheet` 直接停在批量选择档 / 再把批量那一层推上来,
设计稿 `design/mobile-approval.html`,取舍与验收见 [docs/mobile-approval-layout.md](docs/mobile-approval-layout.md)。
发版有没有生效不用猜:首屏问候语下面那串 12 位数字就是构建号,构建时 `--build-arg OA_APP_BUILD=$TAG`
把镜像 tag 烤进产物,手机上那一串跟 `kubectl get deploy` 里的 tag 对上,就说明这台手机跑的就是这一版。
@ -2267,7 +2752,7 @@ sqlite 上(55 项:谁按得动、窗口怎么算、留痕与通知、终止
| 组织 | `GET /tree` `GET\|POST\|PUT\|DELETE /units` `/persons` `/roles` `/groups` `/agents` `/handovers` |
| 统一身份 | `GET /hub/status`(含 `sso` 与 `changes` 两段)`POST /hub/sync`(一键全量)`POST /hub/sync/cancel`(叫停正在跑的同步、收尾卡住的「进行中」)`POST /hub/changes/sync`(手动拉一次变更流水)`GET /hub/sync/runs` `GET /hub/directory/preview`(只读体检)`GET/PUT /hub/config`(保存即生效)`POST /hub/probe` |
| 设计 | `GET\|POST\|PUT\|DELETE /process/categories` `/process/forms` `/process/processes`;`PUT /process/processes/{id}/design`;`POST .../validate` `.../publish` `.../disable` `.../copy`;`GET .../title/variables`(标题规则的变量清单);`POST /process/form-title/variables` + `POST /process/form-title/preview`(规则配在表单字段上时的同一份清单与预览,带画布上未保存的字段草稿);`POST /process/form-serial/preview`(编号预览,只读不占号) |
| 运行 | `POST /job`(发起)`POST /job/serial/reserve`(编号时机配成 `create` 的新单先占号,回 `{serial, ticket, expiresIn}`,凭条在提交/存草稿时原样交回)`POST /job/title/preview`(发起页标题实时预览)`POST /job/{job}/title/preview`(办理页:按将要提交的那份改动算一句「提交后会变成什么」,只读不写库)`GET /job/{job}` `GET /work/{id}` `GET /work/related` `GET /work/summaries` `GET /task/processing`(每行带 `deletable`:本人创建、还停在开始环节、没压在别人手上)`/task/completed` `POST /task/{id}/execute` `POST /task/batch-execute` `/goback` `/addtask` `/transfer` `/press` `POST /job/{job}/terminate` |
| 运行 | `POST /job`(发起)`POST /job/serial/reserve`(编号时机配成 `create` 的新单先占号,回 `{serial, ticket, expiresIn}`,凭条在提交/存草稿时原样交回)`POST /job/title/preview`(发起页标题实时预览)`POST /job/{job}/title/preview`(办理页:按将要提交的那份改动算一句「提交后会变成什么」,只读不写库)`GET /job/{job}` `GET /work/{id}` `GET /work/related` `GET /work/summaries` `POST /work/relation-values`(关联带出预览:按挂着的那几张单回每条 `pick` 取到的值)`GET /task/processing`(每行带 `deletable`:本人创建、还停在开始环节、没压在别人手上)`/task/completed` `POST /task/{id}/execute` `POST /task/batch-execute` `/goback` `/addtask` `/transfer` `/press` `POST /job/{job}/terminate` |
| 导出 | `GET /export/works?scope=created\|admin` `GET /export/tasks?scope=processing\|completed`(CSV,带 UTF-8 BOM) |
| 流程明细导出 | `GET /export/detail/catalog` `POST /export/detail/{count,preview,download}`(独立权限码 `monitor:export`,侧栏一条独立菜单;自选流程与字段,默认按流程分 sheet,也能合并成一张表,CSV 只走合并) |
| 支撑 | `/attachment` `/attachment/{id}/download` `/draft` `/notification` `/read` `/worklog` `/statistics/*` `/settings` `/system/storage` `/system/storage/test` `/system/storage/reload` `/operation-logs` |
@ -2382,6 +2867,9 @@ python3 scripts/check_globals.py # 后端源码里的未定义引用
python3 scripts/check_route_guards.py # 每个接口要么挂权限点、要么要求登录、要么在匿名白名单里
python3 scripts/check_web_shell.py # 发 index.html 时那份公开配置注入(不连库:配置这一口是假的,只验注入这一层)
python3 scripts/check_binding.py # 取值写法 / 多源合并 / 数据源健康判据,顺带对一遍前后端共用的那几句措辞
python3 scripts/check_option_route_fill.py # 那一条候选自带的带出(optionRoutes[].fill):命中哪一条就按那一条带出、只写带出去向不盖这一格挑中的值、没自带照旧回落字段那份 fetch、入参与源默认沿用这一条、失败策略四档跟着字段那份、设计期门牌「第 N 条候选来源的带出」、保存那一刻的清洗、前后端键名与常量对齐(不碰库)
python3 scripts/check_option_routes.py # 一格挂好几套候选来源(optionRoutes):命中哪一条与回落、视图只动来源那一维、脏条目当没配、保存那一刻的清洗(含路由里挂着字典时 autoFill 不当残骸洗掉)、把关跟着命中的那一条、「带出的值也收下」、字典带出按命中那一本取(命中非字典那条一个字都不带)、路由里的字典与上游、显示条件不成立不再卡必填、取数条目上的 when、前后端常量与措辞(不碰库)
python3 scripts/collapse_trip_form.py # 「一家四格」收成「一格四家」:读那张真表单算收拢后的样子,逐家比对接的哪一家 / 候选几条 / 带出写到哪几格 / 值是不是同一个(外部取数真跑一次),再按设计器保存那条路校验一遍;默认只算不改,--write 落库、--perms 顺带折环节权限
python3 scripts/check_fetch_url_args.py # 取数地址上带参数:模板替换与 URL 编码、路径段同样生效、空入参不外呼、缓存键认地址(内存库,不连上游)
python3 scripts/check_embed.py # 表单嵌外部页面:参数白名单、接口取链接那道来源闸、给哪一条地址(含源上另登记的那几条与顺手带回的那几个值)、能否被嵌、免登短码、CSP、留痕不含参数值、回写档位与出口匹名、说明书与代码同源
python3 scripts/check_embed_decide.py # 第三方回写「审完了」:发起真单据→拿会话令牌回写→引擎那本账真记上了(跑完自己删干净)
@ -2389,6 +2877,10 @@ python3 scripts/check_embed_abandon.py # 「这一页被放弃时通知对
python3 scripts/check_embed_view_link.py # 在途点开那一格嵌页面递出去的是对面哪一页:查看页回空串不算配歪、只存过填报页时再问一次接口、发起页那一句「这一趟成单了吗」(跑完自己删干净)
python3 scripts/check_embed_readonly_auto.py # 只读那一屏「只沿用对方已有那一页」:库里没货回 held:false 且一次建页接口都不打、不留会话与短码,view_only 只给查看页且不被环节隐藏挡(跑完自己删干净)
python3 scripts/check_hidden_field_rules.py # 本环节把这一格藏起来时挂在它身上的规则挡不挡人(阈值、额度那四句、外部取数失败,外加必填那几句与"开始环节藏起来的必填格不拦发起"):默认放行、可翻回照挡,标记格与占额台账照记;闸门挂在环节上不吃这一豁免(跑完自己删干净)
python3 scripts/check_self_visible.py # 联动条件读自己那一格:判得出结果、不再当配错、级联清值那圈不绕进自己,而只被自己那句条件收走的格子提交时这一笔值照样收下(顺带钉住「一串空格算没填」两边同一把尺子;不碰库)
python3 scripts/check_table_column_readonly.py # 明细列勾了「只读」之后:那一列不卡必填、已经躺着的值照判格式、本行公式那一列不吃这一豁免、整张表那一层的环节权限没被带坏(纯函数,不碰库)
python3 scripts/check_table_formula_editable.py # 明细列勾了「公式带入后允许修改」之后:行上那份 _manual 凭据一路不丢、这一档不把列锁上也不放宽校验、公式列默认值没复活、设计期不报错(纯函数,不碰库)
python3 scripts/check_row_fetch.py # 明细列挂上外部取数之后:逐行各取一次并覆盖、入参读「整张单+这一行」、「带出去向」只认本表的列、报错点明第几行、整张表被藏起来时 block 降级、留痕按表名.列名摊得开行号(内存库 + 假上游,不连真接口)
python3 scripts/check_writeback_revisit.py # 环节写回重发:提交时/到达时/审批通过后各发一次,退回改值再提交与撤回后重办能否再发(影子模式,跑完自己删干净)
python3 scripts/check_writeback_trigger.py # 「什么时候发」拆两处:终态可多勾 / 一条都不勾是合法态 / 旧写法一键搬进环节(跑完自己删干净)
python3 scripts/check_outbox_wake.py # 写回什么时候真的发出去:入队提交当场叫醒 / 回滚不空叫 / 一轮发干净一张单(影子模式,跑完自己删干净)
@ -2396,6 +2888,7 @@ python3 scripts/check_notify_wake.py # 渠道提醒与订阅事件什么
python3 scripts/check_writeback_config.py # 写回配置全库体检:先报现库哪几条会静默不发/多发,再把八种病各造一遍自证(--report 只报不当闸门)
python3 scripts/check_terminate_control.py # 终止管不管得住:谁能按、四档窗口、留痕与通知、终止那一刻的写回与冲销(内存 sqlite,不碰生产库)
python3 scripts/check_notify_settle.py # 站内信跟着事项收尾:待办办完/转走/或签结掉/终止之后通知退场,办完之前一条都不许多收;三处出口同一份账(内存 sqlite,不碰生产库)
python3 scripts/check_schema_snapshot.py # sql/schema.sql 与 models.py 有没有走散
python3 scripts/check_schema_bootstrap.py # 动过启动建表补列(app/db.py::create_schema):空库建齐 + 拆坏能补回,自建临时库
python3 scripts/check_index_gaps.py # 动过索引 / models.py 的 __table_args__ / 新写了 WHERE 里等值过滤:会长大的表上不能没索引还没理由
@ -2406,6 +2899,7 @@ cd frontend
pnpm typecheck # vue-tsc --noEmit
pnpm lint:check # eslint(不带 --fix)
pnpm build # vue-tsc -b && vite build
pnpm vitest run src/utils/browserCompatGuard.spec.ts # 浏览器口径闸门:带出值/展示这条链不许用回没有兜底的写法
```
连库的那几条要能连上开发库才跑得动,全部**只读业务数据**:一条语句都不写,
@ -2431,6 +2925,7 @@ python3 scripts/check_quota_import.py # 动过额度台账的批量导入
python3 scripts/check_identity_refs.py # 动过配置里的引用列(岗位角色成员/日程网盘归属/环节审批人)或批量认人 org.account_expands
python3 scripts/check_memberships.py # 动过岗位归属反查(org.memberships_for / GET /org/persons/roles)或分组两列成员的读法
python3 scripts/check_cc_reads.py # 动过环节抄送建待阅(engine.apply_activity_cc / create_reads 的 held)
python3 scripts/check_cc_action_files.py # 动过抄送需处理带附件(engine.mark_read 的 attachments / claim_attachments 认归档单)或归档件补批注(engine.add_comment / _job_response 的 can_comment):全程在未提交事务里跑,库里不留一行
python3 scripts/check_flush_defer.py # 动过引擎里 db.flush 的作用范围(_log / notify / _arrive_manual)
python3 scripts/check_simulate_paths.py # 动过审批人解析 / 环节路由 / 试算
python3 scripts/check_log_timeline.py # 动过流转日志留痕
@ -2441,6 +2936,7 @@ python3 scripts/check_begin_resubmit_todo.py # 动过开始环节提交(engine
python3 scripts/check_dedup_rerun.py # 动过「谁已经批过」的口径(engine._approved_persons / _route_is_back / _advance 推的 dedupSince):驳回(reject)与没标语义的回头线各跑一张真单子,驳回前批过的人重新表态、驳回那位自己也要重批、同一轮里刚批过的照常免掉(建自己的流程与单据,跑完删干净)
python3 scripts/check_form_change_noise.py # 动过表单改动留痕(engine.form_change_notes / _same_field_value / _number_of):数字型字段(number / money / rate / percent / year / formula)按数值比,0.0 → 0、4075.0 → 4075 不再算人工改动;钱真变了、从(空)到有值、文本与布尔那些写法仍照记(纯函数,不连库、不留数据)
python3 scripts/check_intervention_title.py # 动过干预「修正表单」与标题的联动(engine.fix_data / _refresh_title / titles.sync_pending_titles / titles.preview_refresh):人填、自动重算、不重算三种口径各跑一张真单子,改完待办 / 待阅 / 监控三张列表一起对得上,保存前的预告也一并校(自己建流程自己删)
python3 scripts/check_intervention_move.py # 动过干预改道之后留了什么(engine.move / _complete_task / notify_settle / events.emit / channels.EVENTS / runtime._vanished_task_view):旧环节待办一次收干净并进已办、代操作人与原因留在痕迹上、站内信当场自愈、外发与事件两条链路各自的下场、子流程要么拒要么一并终止、点开旧卡片答得出这一步的去向,八条缺口逐条钉成判据,只留「已经落到邮箱 / 群 / 企微的那条消息收不回」一条现状(内存 sqlite,不碰开发库)
python3 scripts/check_serial_timing.py # 动过编号时机(numbering.timing_* / engine.issue_serial / drafts.reserve_serial):五档时机各跑一张真单子(create 那一档连凭条三道闸一起跑),自己建流程自己删
python3 scripts/check_leader_lease.py # 动过跨进程租约(app/service/leader.py)/ 准备开 OA_WORKERS 多进程
python3 scripts/check_outbox_wake.py # 动过写回投递时机(service/outbox.py 的 wake / run_due / refresh_pending,或 main.py 调度线程的睡眠与叫醒)

View File

@ -13,7 +13,8 @@ from .. import models, parallel, schemas, serializers
from ..db import get_db
from ..deps import CurrentUser, actor_of, current_user, require_permission
from ..engine import definition as definition_module
from ..service import (autofill, dedupaudit, dicts, fetch, formruntime, mapping, node_approve, numbering, org,
from ..service import (autofill, dedupaudit, dicts, fetch, formruntime, linkfill, mapping, node_approve,
numbering, org,
quota, simulator, starters, terminate as terminate_service, threshold, titles)
from ..engine import engine, expressions
from ..envelope import bad_request, not_found, ok
@ -173,7 +174,7 @@ def clean_formats(content: object) -> dict:
SOURCE_OWNED_KEYS: dict[str, tuple[str, ...]] = {
dicts.SOURCE_MANUAL: ("options",),
dicts.SOURCE_DICT: ("dictCode", "cascadeFrom", "autoFill"),
dicts.SOURCE_PROCESS: ("relationProcess",),
dicts.SOURCE_PROCESS: ("relationProcess", "relationStatuses", linkfill.LINK_FILL_KEY),
dicts.SOURCE_DATA_SOURCE: ("dataSourceCode", formruntime.OPTION_ARGS_KEY),
}
_ALL_SOURCE_KEYS = tuple({key for keys in SOURCE_OWNED_KEYS.values() for key in keys})
@ -191,15 +192,21 @@ def clean_option_source(content: object) -> dict:
if not isinstance(content, dict):
return {} if content is None else {"fields": []}
def clean(item: dict) -> dict:
def clean(item: dict, top: bool = True) -> dict:
fresh = dict(item)
field_type = str(fresh.get("type") or "")
# 关联单据带出只挂在主表字段上:明细列里那一格挂的也可以是单据,但「这一行的那张
# 单 → 另一张表的几行」在界面上没人能预期,那一层要带数据走「从另一个流程带数据」。
# 放在最前面是因为下面那两条捷径会提前 return,残骸照样得收干净。
if not top:
fresh.pop(linkfill.LINK_FILL_KEY, None)
# 级联选择只挂层级字典:``dictCode`` / ``cascadeFrom`` 是它自己的配置,不是"候选来源"
# 那四类留下的残骸。它不在 source_kinds_of 的清单里,跟着下面"这一类型挑不了来源就
# 整份撤掉"会被连 dictCode 一起抹掉——validate_schema 又要求级联必须挂字典,
# 结果是凡是带级联字段的表单(含明细列)一律存不下去。
if field_type == formruntime.CASCADER_TYPE:
fresh.pop("optionSource", None)
fresh.pop(dicts.OPTION_ROUTES_KEY, None)
return fresh
# 多选月份:候选是那一年那 12 个月,谈不上候选来源那四类,但它共用同一套「挑选方式」
# (字段上的 ``pickerStyle``:下拉多选 / 弹出框多选 / 平铺点选)。它不在
@ -212,6 +219,22 @@ def clean_option_source(content: object) -> dict:
return fresh
declared = str(fresh.get("optionSource") or "").strip()
kinds = dicts.source_kinds_of(field_type)
# 条件路由清单先收:认不出的来源、配到一半的空条目、第 9 条起多出来的都丢掉,
# 每条只留属于它那一种来源的那几格(口径在 ``dicts.clean_routes``)。
# 放在「来源挑错了就整份撤掉」那句之前——老写法没写 ``optionSource`` 的字段也能挂路由,
# 跟着那条 return 走的话这份清单会原样落库,没人洗过。
if not kinds:
fresh.pop(dicts.OPTION_ROUTES_KEY, None)
elif dicts.OPTION_ROUTES_KEY in fresh:
cleaned_routes = dicts.clean_routes(fresh)
if cleaned_routes:
fresh[dicts.OPTION_ROUTES_KEY] = cleaned_routes
else:
fresh.pop(dicts.OPTION_ROUTES_KEY, None)
# 「带出的值不在候选里也收下」只属于有候选来源的那几类字段,而且只认真布尔值:
# 一个文本框带着它、或一个字符串 "true" 落进来,读的人都得猜这是哪一档
if not kinds or not isinstance(fresh.get(dicts.ALLOW_OUTSIDE_VALUE_KEY), bool):
fresh.pop(dicts.ALLOW_OUTSIDE_VALUE_KEY, None)
if declared not in kinds:
# 这一类字段没有候选来源可言(文本框、明细表……),或来源本身挑错了:整份撤掉,
# 退回它自己的老口径,别让一个不认识的来源把候选配置带进下一个控件里。
@ -224,9 +247,22 @@ def clean_option_source(content: object) -> dict:
fresh.pop("picker", None)
fresh.pop("multiple", None)
return fresh
owned = SOURCE_OWNED_KEYS[declared]
if declared != dicts.SOURCE_DICT and dicts.dict_route_codes(fresh):
# 字段自己挂的不是字典,但**某一条候选来源是字典**:那一条命中时带的就是它那本的附加值,
# ``autoFill`` 是这一档唯一的配法(外部数据源那一条自己带 ``fill``),不能当残骸清掉。
owned = owned + (dicts.AUTO_FILL_KEY,)
for key in _ALL_SOURCE_KEYS:
if key not in SOURCE_OWNED_KEYS[declared]:
if key not in owned:
fresh.pop(key, None)
# 「关联带出」那几格跟着来源走:写歪的规则、认不出的合并档在这儿收干净,
# 一条有效规则都不剩时整格抹掉(留一份空 rules 只会让下一任以为配过什么)
if declared == dicts.SOURCE_PROCESS and linkfill.LINK_FILL_KEY in fresh:
cleaned_fill = linkfill.clean(fresh.get(linkfill.LINK_FILL_KEY))
if cleaned_fill:
fresh[linkfill.LINK_FILL_KEY] = cleaned_fill
else:
fresh.pop(linkfill.LINK_FILL_KEY, None)
style = str(fresh.get("pickerStyle") or "").strip()
# 装不下的姿势只剩一种:搜出来的候选铺不成一排(手上只有搜到的那一页)。
# 一串值配下拉是成立的——那只下拉带勾选框,挑中的几条挂在框里(``Select`` 的 multiple),
@ -254,10 +290,12 @@ def clean_option_source(content: object) -> dict:
fresh["optionMap"] = normalized
return fresh
def walk(item: dict) -> dict:
fresh = clean(item)
def walk(item: dict, top: bool = True) -> dict:
fresh = clean(item, top=top)
if isinstance(fresh.get("columns"), list):
fresh["columns"] = [walk(col) if isinstance(col, dict) else col for col in fresh["columns"]]
fresh["columns"] = [
walk(col, top=False) if isinstance(col, dict) else col for col in fresh["columns"]
]
return fresh
fields = content.get("fields")
@ -377,9 +415,12 @@ def form_problems(content: dict, db: Session | None = None) -> list[str]:
# 选项有四种来源:字典、别的流程的单据、外部数据源都不用在表单里抄一份选项,
# 只有「手填」这一条真空着手会害得填单那一格一个能点的都没有。
# 字典与数据源那两条选了却没挑到底,由 validate_schema 报「还没选字典 / 还没选源」。
# 挂了候选来源清单的那一格也不算空着手:候选来自清单里那几条,字段自己这一份留给
# 「一条都不成立」时兜底(先选分类再问那一家,分类没选时本来就没得挑)。
if ftype in OPTION_FIELD_TYPES \
and dicts.source_kind_of(item) == dicts.SOURCE_MANUAL \
and not (item.get("options") or []):
and not (item.get("options") or []) \
and not dicts.routes_of(item):
problems.append(f"第 {index} 个字段「{label or key}」未配置任何选项")
if ftype == "auto":
source = str(item.get("auto") or "").strip()

View File

@ -344,10 +344,12 @@ def preview_options(body: schemas.DictPreviewBody, db: Session = Depends(get_db)
field = dict(body.field or {})
data = dict(body.data or {})
options = dicts.effective_options(field, data, cache)
# 演的是「这一格此刻」:条件路由命中哪一条,就按那一条的显示 / 存值两列投影
view = dicts.option_view(field, data)
return ok(
{
# 演的是「填单的人此刻看到什么、选了会存什么」:按这一格配的显示 / 存值两列投影
"options": dicts.project_options(field, options) if options is not None else [],
"options": dicts.project_options(view, options) if options is not None else [],
"constrained": options is not None,
"state": dicts.state_of(field, data),
"dependsOn": dicts.depends_on(field),

View File

@ -94,7 +94,8 @@ def _work_lines(rows: list, db: Session, cache: dicts_service.DictCache, with_fo
str(getattr(row, "manual_identity_text", "") or ""),
]
line.extend(
cell_text(field, data.get(str(field.get("key") or "")), cache, jobs) for field in fields
cell_text(field, data.get(str(field.get("key") or "")), cache, jobs, data=data)
for field in fields
)
lines.append(line)
return headers, lines

View File

@ -15,9 +15,9 @@ from sqlalchemy.orm import Session, defer
from .. import models, parallel, permissions, schemas, serializers
from ..db import get_db
from ..deps import CurrentUser, actor_of, client_ip, current_user, require_permission
from ..service import autofill, completed as completed_service, flowmap, formruntime, numbering
from ..service import autofill, completed as completed_service, dicts, flowmap, formruntime, numbering
from ..service import outbox, personref, starters, terminate as terminate_service, titles
from ..service import embed_session, external_check, gate, node_approve, org
from ..service import embed_session, external_check, gate, linkfill, node_approve, org
from ..engine import definition as definition_module
from ..engine import engine
from ..envelope import bad_request, forbidden, not_found, ok
@ -326,6 +326,10 @@ def _job_response(db: Session, user: CurrentUser, job: str, row, *, running: boo
raise
candidate = None
frozen = candidate if candidate is not None and candidate.pinned else None
# 冻过结的在途单要把"此刻那张表改成什么样了"也带一份出去(手机端审批版式读它,
# 口径见 ``forms_live``),所以要先把冻结定义里那几张表单的 id 摘出来。
# 没冻过的不用问:``forms`` 本来就是现读的那一张。
live_form_ids = list(dict.fromkeys(frozen.form_ids())) if frozen is not None and running else []
archived_definition_fields = {
"process_id": process_id,
"name": row.process_name,
@ -404,6 +408,39 @@ def _job_response(db: Session, user: CurrentUser, job: str, row, *, running: boo
return []
return _process_form_rows(session, process_id)
def live_forms_block(session: Session):
"""这一张单挂的那几张表单**此刻**的内容(``form_id -> content``)。
只有冻过结的在途单要问:没冻的单,上面 ``forms_block`` 回的就是当前那一张。
读的是 :func:`app.service.autofill.form_content` 那一层进程内快照——没人改表单时
一条 SQL 都不排,改过之后当场作废重读,界面上保存即见效;真的没命中,那一趟
也只排在这个并发位里,不给详情页添串行的往返。
"""
out: dict[str, dict] = {}
for form_id in live_form_ids:
content = autofill.form_content(session, form_id)
if content:
out[form_id] = content
return out
def live_perms_block(session: Session):
"""这一单走过的环节**此刻**的字段权限(``activity_id -> form_perms``)。
跟 ``live_forms_block`` 同一件事的另一半:审批人在手机上看的格子,一半由表单上
那几栏展示配置定,一半由环节那一格「字段权限」定(隐藏 / 只读 / 可编辑 / 必填)。
两张都冻在快照里,改了都得等这张单走完才见效。
环节行本来就在 ``activities_block`` 里问,但冻过结那一支整支都跳过了,
所以这里单独问一次(只认 ``process_id``,一个并发位,不串行)。
"""
if frozen is None or not running:
return {}
return {
row.id: formruntime.perms_of(row.config)
for row in session.execute(
select(models.Activity).where(models.Activity.process == process_id)
).scalars().all()
}
def live_design_block(session: Session):
"""当前那一版设计的版本号,以及它最后一次被改动的时间(三张设计表取最晚)。
@ -458,6 +495,11 @@ def _job_response(db: Session, user: CurrentUser, job: str, row, *, running: boo
"writeback": writeback_block,
# 命中与否都要问,所以先摊出去,不等缓存的答复
"forms": forms_block,
# 冻过结的在途单另问一份"此刻那张表改成什么样了"(只给手机端审批版式用)。
# 与 forms 一样是个并发位:命中缓存时一条 SQL 都不排,没命中也不挡别的路。
"live_forms": live_forms_block,
# 同上,问的是环节那一格「字段权限」此刻是什么(只回与冻结那一版不一样的环节)
"live_perms": live_perms_block,
# 外部审批锁此刻是什么状态:这一格是闸口不是图纸,管理员当场改了就得当场见效,
# 所以它不吃设计缓存、也不吃单据冻的那一版,照实库那一行算。命中与否都要问,
# 于是与 forms 同批摊出去;回库那一支因此多读一遍环节行(并发位,不串行)。
@ -524,6 +566,9 @@ def _job_response(db: Session, user: CurrentUser, job: str, row, *, running: boo
# 这三趟既然都问了,存下来:下一张同流程的单就不必再问(刚改过设计时存不进去)
definition_module.cache_design(process_row, activity_rows, routes)
forms = _snapshot_forms(definition) if frozen is not None else _ordered_forms(definition, form_rows)
# 只装"与发起那一刻冻住的那一张真的不一样了"的那几张:没改就是空对象,
# 报文与改动前逐字节相同,前端也就不会为了同一份内容摆两遍。
forms_live = _forms_live(forms, loaded.get("live_forms") or {})
# 逐环节的锁状态来自上面那一块(实库此刻那一行),与引擎判据同一个口径。
# 环节是冻结那一版里的环节,锁是当下的锁:中途把外部审批关掉,横幅当场消失。
locks = loaded.get("oa_locks") or {}
@ -531,6 +576,9 @@ def _job_response(db: Session, user: CurrentUser, job: str, row, *, running: boo
a.id: serializers_activity_brief(a, definition.approval, process=definition, lock=locks.get(a.id))
for a in definition.activities.values()
}
# 环节字段权限此刻被改成什么样了:只回**与冻结那一版不一样**的那几个环节,
# 没人动过就是空对象(报文与改动前逐字节一致)。口径见 ``_perms_live``。
activity_perms_live = _perms_live(activity_nodes, loaded.get("live_perms") or {})
# 终止那颗钮给不给这个人看:管理员恒给;发起人除了"是自己发起的",还要过流程那一格
# 终止配置(整个关掉、或已经过了"什么时候为止"那条线)。判据只有一处
# (engine.terminate_blocker),界面显示与引擎放行说的必须是同一句话。
@ -539,6 +587,22 @@ def _job_response(db: Session, user: CurrentUser, job: str, row, *, running: boo
# 只有发起人本人才需要知道"我为什么按不动":别人来看这张单,这一格留空,
# 也省掉一次没意义的判据查询(管理员恒能终止,同样不必问)。
starter_blocker = engine.terminate_blocker(db, row, definition, _actor(user))
# 这一单上能不能补批注:环节那一格「允许批注」+「这一单与你有关」。
# 有关的四档里前三档用的行报文里本来就读回来了(当前办理人、办过的人、发起人),
# 只有"被抄送/分享/@ 到过"这一档要现问,于是排在最后——自己的单、自己办过的单
# 一次库都不多问。开关取上面那份环节简报,与引擎写路径读的是同一格配置;
# 归档件没有 ``activity`` 这一列,取不到环节就是默认放行(见 engine.comment_activity)。
related = (
user.is_admin
or row.creator == user.person_id
or any(task.identity == user.ref for task in tasks)
or any(item.identity == user.ref for item in done)
)
if not related:
related = _received_reads(db, row.id, user.ref)
node_allows_comment = bool(
(activity_nodes.get(getattr(row, "activity", "") or "") or {}).get("allow_comment", True)
)
return ok(
{
**serializers.work(row),
@ -547,6 +611,11 @@ def _job_response(db: Session, user: CurrentUser, job: str, row, *, running: boo
"task_completed": [serializers.task_completed(t) for t in done],
"attachments": [serializers.attachment(a) for a in attachments],
"forms": forms,
# 上面那一份是这张单出发那一刻冻住的表单,这一份是**此刻**那一张的内容,
# 只给手机端审批那一屏用(摆哪些格、什么顺序、每格怎么摆按当下的配置走)。
# 只在冻过结的在途单上可能有东西,而且只装真改了的那几张;桌面、打印、
# 导出、必填校验读的还是 ``forms``。口径见 ``_forms_live``。
"forms_live": forms_live,
# 这张单走在哪一版设计上。``design_pinned`` 为真时 ``design_version`` 是它发起
# 那一刻的那一版、``process_version`` 是流程现在的版本号:改流程改表单的人
# 该看得见"这张还在走的单用的是旧图",办单的人才不至于被换掉的图晃到。
@ -561,6 +630,9 @@ def _job_response(db: Session, user: CurrentUser, job: str, row, *, running: boo
for a in definition.activities.values()
],
"activity_nodes": activity_nodes,
# 与 ``forms_live`` 配成一对:表单那几栏展示配置 + 环节那一格字段权限,
# 两块合起来才是"这一屏该露哪几格"。都只给手机端审批那一屏当摆法用。
"activity_perms_live": activity_perms_live,
# 轨迹图:环节坐标 + 每环节/每路由的实时状态,前端照着上色就能画出
# 「走过哪条线、停在哪一环、谁还没办」,不用自己拿流水日志反推。
"flow": flowmap.build(definition, row, list(tasks), list(logs), list(done)),
@ -583,6 +655,8 @@ def _job_response(db: Session, user: CurrentUser, job: str, row, *, running: boo
"can_terminate": running and (user.is_admin or (row.creator == user.person_id and not starter_blocker)),
# 挡下的那句原话:按钮不显示时,页面得有个地方说清"为什么不能终止"
"terminate_hint": starter_blocker,
# 单据详情页那颗「补充批注」给不给这个人按(在途与归档同一条判据)
"can_comment": related and node_allows_comment,
"writeback": loaded["writeback"],
# 开始环节停在等提交的那一单(第三方审批:hold 建单):界面上要看得出
# 「这一单还没提交出去」,并且该谁按那颗钮、谁已经替他备好了表态。
@ -598,6 +672,24 @@ def _job_response(db: Session, user: CurrentUser, job: str, row, *, running: boo
)
def _received_reads(db: Session, work_id: str, ref: str) -> bool:
"""这一单上有没有发给我的待阅 / 已阅(抄送、分享、批注 @ 我都算)。
只在发起人、当前办理人、经办人对不上时才问这一趟(:func:`_job_response` 里那点判断),
两张表并成一句问完。两条都认 ``identity`` 打头的那个索引,不顺着 ``work`` 扫表。
"""
stmt = (
select(models.Read.id).where(models.Read.work == work_id, models.Read.identity == ref)
.union_all(
select(models.ReadCompleted.id).where(
models.ReadCompleted.work == work_id, models.ReadCompleted.identity == ref
)
)
.limit(1)
)
return db.execute(stmt).first() is not None
def serializers_activity_brief(
node,
approval: dict | None = None,
@ -717,6 +809,53 @@ def _snapshot_forms(definition: definition_module.ProcessDefinition) -> list[dic
return out
def _forms_live(forms: list[dict], live: dict[str, dict]) -> dict[str, dict]:
"""手机端那一屏要用的"此刻那份表单配置":只收与冻住的那一张真改了的表单。
为什么只有手机端跟:单据是凭证,桌面详情页、打印单、导出、必填校验、引擎落库
读的都必须是这张单出发那一刻冻住的那一版(``check_design_pin.py`` 钉的就是这一条),
否则一张走到一半的单会因为别人改了表单而当场换掉该填什么。而审批的人手机上看的
是"这一屏该给他看哪几格"——配表的人刚把某一格勾上「展示」、把明细改成逐条展开、
把显示条件改了,手机上还要等这张单走完才见效,等于那份配置白改。
所以这里只多一份**展示**用的内容,不动 ``forms``:
* 认的是同一张表(同一个 ``form_id``)。设计器里就地改表单是更新这一行,id 不变,
这正是"改配置马上影响在途单"的那条路;把环节换成另一张表(id 变了)不算调整,
在途单照旧看自己冻住那一张,不跟着换表。
* 内容没动就不进这份报文(``{}``),报文与改动前逐字节一致,前端也不会为
同一份内容摆两遍。
* 表被删了 / 快照里本来就没这张表:``live`` 里没有这一项,前端回落到冻住的那一张。
"""
out: dict[str, dict] = {}
for item in forms:
form_id = str(item.get("id") or "")
content = live.get(form_id)
if content and content != (item.get("content") or {}):
out[form_id] = content
return out
def _perms_live(nodes: dict[str, dict], live: dict[str, dict]) -> dict[str, dict]:
"""环节字段权限**此刻**那份与冻结那份的差异:只回改过的环节(``activity_id -> form_perms``)。
与 :func:`_forms_live` 是一对:审批人在手机上看见哪几格,一半写在表单那几栏展示配置里,
一半写在流程设计器「环节 → 字段权限」那一格里(生产上 2026-11 那批在途报销单就是这一处——
管理员把 ``checkTotal`` 那几个审定格从「隐藏」改成「只读」,手机上那一屏照旧不露,
因为那张单冻的还是「隐藏」。)
判据与环节简报里那份 ``form_perms`` 同一句(都过 :func:`app.service.formruntime.perms_of`),
不许前端再拿 ``config.formPerms`` 自己拼一遍。冻结简报里没有的环节(发过新版之后新加的环节)
不进这份报文:那张单脚下没这一环,给它是多余的。
"""
out: dict[str, dict] = {}
for activity_id, brief in nodes.items():
perms = live.get(activity_id)
if perms and perms != (brief.get("form_perms") or {}):
out[activity_id] = perms
return out
@router.patch("/job/{job}")
def update_job(
job: str,
@ -1205,16 +1344,33 @@ def _relation_summary(row) -> dict:
def search_related_works(
keyword: str = Query(""),
process: str = Query(""),
status: str = Query(""),
status: str = Query(
"",
description="逗号分隔的状态档位:completed=归档通过 / running=在办 / closed=已终止或作废。"
"留空或三档都给等于不限;传单据状态原值(terminated、canceled…)也认。",
),
page: int = Query(1, ge=1),
page_size: int = Query(20, ge=1, le=100),
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
) -> dict:
"""关联审批单选择器:在我发起 / 我办过 / 我抄送过的单子里搜。"""
"""关联审批单选择器:在我发起 / 我办过 / 我抄送过的单子里搜,按档位收状态。
挑哪几档由字段上那一份 ``relationStatuses`` 说了算(口径在 ``service/dicts``,
前端镜像在 ``utils/optionSource.ts``),这一层只照档位挑表、挑状态:默认只给归档通过的,
免得分诊到一半被终止的单子也挂得上去。这一档只管**候选列不列它**——已选中的单据
后来被终止,回显走 ``/work/summaries``,照样念得出标题与「已终止」那个角标。
"""
buckets = dicts.relation_status_query(status)
running_statuses, archived_statuses = dicts.relation_status_tables(buckets)
parts = [
_work_key_part(model, table, _related_clause(model, user, keyword, process, status))
for model, table in ((models.Work, "running"), (models.WorkCompleted, "archived"))
_work_key_part(model, table, _related_clause(model, user, keyword, process, statuses))
for model, table, statuses in (
(models.Work, "running", running_statuses),
(models.WorkCompleted, "archived", archived_statuses),
)
# 没限档时两张表都查;限了档就只查沾得上的那一张,另一张连问都不问
if not buckets or statuses is not None
]
# 关联单选择器只要标题和时间这些摘要,正文那一列从头到尾没人读
rows, total = _work_union_page(
@ -1223,16 +1379,19 @@ def search_related_works(
return ok(serializers.page([_relation_summary(row) for row in rows], total, page, page_size))
def _related_clause(model, user, keyword, process, status):
"""关联审批单搜索的过滤条件:看得见(我发起/我办过/我抄送过)AND 勾选的那几项。"""
def _related_clause(model, user, keyword, process, statuses):
"""关联审批单搜索的过滤条件:看得见(我发起/我办过/我抄送过)AND 勾选的那几项。
``statuses`` 是这一张表要挑的单据状态(``None`` = 这一张表不加状态条件)。
"""
clauses = []
visible = _visible_work_filter(model, user)
if visible is not None:
clauses.append(visible)
if process:
clauses.append(model.process == process)
if status:
clauses.append(model.status == status)
if statuses:
clauses.append(model.status.in_(statuses))
if keyword:
like = f"%{keyword}%"
clauses.append(or_(model.title.like(like), model.serial.like(like)))
@ -1261,6 +1420,75 @@ def work_summaries(
return ok([found[job] for job in wanted if job in found])
def _works_linked_on(db: Session, job: str, wanted: list[str]) -> list[str]:
"""正在填的那张单上此刻存着的那几串值里,有本次要问的哪几张单。
只看**存着**的那几串:预览要多认的那一档就这么多——挂在正在填的这一单上的那些单,
填单的人本来就有权看见(是上一环或他自己挑上来的),不必再要求他与对方单据直接相关。
"""
for model in (models.Work, models.WorkCompleted):
row = db.execute(select(model).where(model.job == job)).scalars().first()
if row is None:
continue
wanted_set = set(wanted)
found: set[str] = set()
def walk(node: object) -> None:
if len(found) == len(wanted_set):
return
if isinstance(node, dict):
for one in node.values():
walk(one)
elif isinstance(node, list):
for one in node:
walk(one)
elif isinstance(node, str) and node.strip() in wanted_set:
found.add(node.strip())
walk(row.data or {})
return sorted(found)
return []
@router.post("/work/relation-values")
def relation_fill_values(
body: schemas.RelationFillBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
) -> dict:
"""填单页面上「关联带出」的即时预览:按挂着的那几张单,回每一条 ``pick`` 取到的值。
只用来显示。提交时引擎自己按同一份配置再算一遍并覆盖(``service/linkfill.apply``),
和外部取数那一格是同一分寸,所以这里少一张单、慢一点都不影响单据里的数。
路径解析只有后端一份实现(``fetch.pick_path``),前端不再镜像那份路径语言。
**显示这一路带可见性闸**,分寸照 ``GET /work/summaries``(那一格的回显本来就走它):
与他相关的那几张才回,加上多认一档「确实挂在他正在填的那张单上的」(``work`` 给了才
认得出来)——办理环节的人常常与对方那张单无关,而那些单是发起那一环替他挂上的。看不见的静默少回,
这一格不解释为什么少一张,免得它变成翻别人单据的口子。引擎那一份**不带**这道闸
(``linkfill.works_by_values``),否则第二环提交会把带出来的值算空。
"""
picks = [item for item in (str(one or "").strip() for one in body.picks or []) if item][:60]
wanted = [item for item in (str(one or "").strip() for one in body.values or []) if item]
wanted = wanted[: linkfill.MAX_LINKS]
if not picks or not wanted:
return ok({"items": []})
stored = _works_linked_on(db, str(body.work or "").strip(), wanted)
def gate(model):
clauses = []
visible = _visible_work_filter(model, user)
if visible is not None:
clauses.append(visible)
if stored:
clauses.append(or_(model.job.in_(stored), model.serial.in_(stored)))
if not clauses:
return None
return clauses[0] if len(clauses) == 1 else or_(*clauses)
return ok({"items": linkfill.values_of(db, wanted, picks, extra=gate)})
@router.get("/work/{work_id}")
def get_work(work_id: str, db: Session = Depends(get_db), user: CurrentUser = Depends(current_user)) -> dict:
work = db.get(models.Work, work_id)
@ -1507,11 +1735,81 @@ def _recall_flags(db: Session, rows: list[models.TaskCompleted]) -> dict[str, di
return flags
#: 一条待办是怎么离开人手的:取值与 ``oa_task_completed.processing_type`` 一致。
#: 这几档前端 ``TaskDetailView`` / ``MobileTaskView`` 那张「去向卡」有专门文案,
#: 一处定死,别在两处各写一套。认不出的取值(加签那两档、以后新增的)原样退回
#: ``unknown``:那一行已办只说得出"这条待办结束了",说不出是谁点的头。
VANISHED_KINDS = ("move", "terminate", "transfer", "auto", "normal", "goBack", "reset")
def _vanished_task_view(db: Session, task_id: str, user: CurrentUser) -> dict | None:
"""这条待办已经不在了:能答出它怎么结束的吗?答不出就回 ``None``(照旧 404)。
数据本来就在库里,一处不用加表:按待办号回查 ``oa_task_completed`` 拿得到原环节、
原因、是谁替这一步收的尾、它属于哪张单;再看那张单现在停在哪个环节、压在谁手上。
查无这条已办(号是编的)照旧回 ``None``,界面上还是那句"待办不存在或已被处理";
认得出下场的七档按 ``VANISHED_KINDS`` 给专门文案,认不出的回 ``unknown``。
可见范围收得很紧:**当时那条待办的持有人**本人,或者看得见监控的人。别人拿一个
待办号来问,连标题都不该跟着掉出来。
"""
done = db.execute(
select(models.TaskCompleted).where(models.TaskCompleted.task == task_id)
).scalars().first()
if done is None:
return None
kind = str(done.processing_type or "")
if kind not in VANISHED_KINDS:
kind = "unknown"
if str(done.identity or "") != str(user.ref or "") and not user.can("monitor:work"):
return None
# 那张单可能已经归档(搬进 oa_work_completed),两种都要认:办结的单子点开旧提醒
# 也是这条路上的人,不能说"单据不存在"
row = db.execute(select(models.Work).where(models.Work.id == done.work)).scalar_one_or_none()
archived: models.WorkCompleted | None = None
if row is None:
archived = db.execute(
select(models.WorkCompleted).where(models.WorkCompleted.id == done.work)
).scalar_one_or_none()
if row is None and archived is None:
return None
return {
"task": task_id,
"kind": kind,
"job": done.job,
"title": done.title,
"serial": done.serial,
"process_name": done.process_name,
"activity": done.activity,
"activity_name": done.activity_name,
"handled_by": done.identity_name or done.identity,
# 这一步是谁替持有人收的尾(改道 / 终止那类);本人自己办完的那一步留空
"operator": done.operator,
"operator_name": done.operator_name,
"route": done.route_name,
"opinion": done.opinion,
"handled_at": done.completed_time.strftime("%Y-%m-%d %H:%M") if done.completed_time else "",
# 归档件回的是它自己的终态(completed / terminated / canceled),前端那一串
# 状态文案本来就有这三档,不必再造一个 "archived" 让人去猜
"work_status": str(getattr(archived if archived is not None else row, "status", "") or ""),
"current_activity_names": str(
getattr(row, "current_activity_names", "") or getattr(archived, "current_activity_names", "") or ""
),
"current_handlers": str(getattr(row, "manual_identity_text", "") or ""),
}
@router.get("/task/{task_id}")
def get_task_detail(task_id: str, db: Session = Depends(get_db), user: CurrentUser = Depends(current_user)) -> dict:
task = db.get(models.Task, task_id)
if task is None:
raise not_found("待办不存在或已被处理")
# 已推送出去的消息里那条链接是永久有效的(企微卡片尤其如此),点开时那条待办
# 早就没了是常态而不是异常。一句"已被处理"回答不了"那是谁干的、为什么、这张单
# 现在归谁",人只会去问管理员。认得出下场就照实回(口径见 _vanished_task_view)。
vanished = _vanished_task_view(db, task_id, user)
if vanished is None:
raise not_found("待办不存在或已被处理")
return ok({"vanished": vanished})
detail = get_job(task.job, db, user)
payload = detail["data"]
payload["task"] = serializers.task(task)
@ -2192,7 +2490,14 @@ def view_read(
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
) -> dict:
_engine_value(engine.mark_read, db, read_id=read_id, actor=_actor(user), opinion=body.opinion)
_engine_value(
engine.mark_read,
db,
read_id=read_id,
actor=_actor(user),
opinion=body.opinion,
attachments=body.attachments,
)
db.commit()
return ok({"success": True})
@ -2205,9 +2510,15 @@ def handle_read(
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
"""抄送需处理:必须填写处理意见,登记后进已阅。"""
"""抄送需处理:必须填写处理意见(可附图片/文件),登记后进已阅。"""
row = _engine_value(
engine.mark_read, db, read_id=read_id, actor=_actor(user), opinion=body.opinion, handling=True
engine.mark_read,
db,
read_id=read_id,
actor=_actor(user),
opinion=body.opinion,
handling=True,
attachments=body.attachments,
)
_log_operation(db, user, "handle_read", read_id, (body.opinion or "")[:120], request)
return ok(_commit(db, lambda: serializers.read_row(row)))
@ -2673,20 +2984,67 @@ def admin_move(
这一档从前是真空地带:走错了环、环节配错人、审批人点了「不同意」却需要重走
某一环——退回只能由当值审批人自己点、而且只能往上游;管理员要么改派要么作废。
改道往前往后都去得,代价写在界面上(当前待办全部结掉进已办、并行分支不接受改道),
引擎里也照样守得住那道:``work.joins`` 还有没收的票箱就拒。
改道往前往后都去得,代价写在界面上(当前待办全部结掉进已办、并行分支不接受改道、
挂着在跑的子流程要先表个态),引擎里也照样守得住那道:``work.joins`` 还有没收的票箱
就拒,``cascadeChildren`` 没勾而子单还在跑也拒。
"""
work = _admin_work_or_404(db, user, job)
result = _run_engine(
engine.move, db, job=job, actor=_actor(user), activity=body.activity, opinion=body.opinion
engine.move, db, job=job, actor=_actor(user), activity=body.activity,
opinion=body.opinion, cascade_children=body.cascade_children,
)
_log_operation(
db, user, "admin_move", job,
f"改道到 {body.activity}:{body.opinion}"
+ ("(一并终止子流程)" if body.cascade_children else ""),
request,
)
_log_operation(db, user, "admin_move", job, f"改道到 {body.activity}:{body.opinion}", request)
return ok(_commit(db, lambda: {
**_step_payload(result),
"current_activity_names": serializers.work(result.work)["current_activity_names"],
}))
@router.get("/admin/work/{job}/reroute-blockers")
def admin_reroute_blockers(
job: str,
user: CurrentUser = Depends(require_permission("monitor:work")),
db: Session = Depends(get_db),
) -> dict:
"""改道页签打开时问一句:这一单上还有什么会跟着一起被搬走。
两件只有管理员该先看见的事:还在跑的嵌入子流程(父单改道会把等它们回来那张票清掉,
子单上那条待办会就此没人认领),以及第三方停在半路等点头的表态(改道一并作废)。
单是面板上那些待办本来就列得出来,不在这里重复。**只读**,一个字段都不改。
"""
work = _admin_work_or_404(db, user, job)
children = engine.running_embed_children(db, work)
staged = node_approve.staged_for_any_activity(db, work.id)
def holders_of(child: models.Work) -> list[str]:
"""这张子单此刻压在谁手上:预检那句话说得出人,管理员才知道该先去找谁。"""
names = {str(name or "").strip() for name in db.execute(
select(models.Task.identity_name).where(models.Task.work == child.id)
).scalars().all()}
return sorted(name for name in names if name)
return ok({
"children": [{
"job": row.job,
"serial": row.serial,
"title": row.title,
"activity_name": row.current_activity_names or row.activity_name,
"holders": holders_of(row),
} for row in children],
# 那句话由引擎说:预检与真动手撞上同一句判据,界面上不会与引擎各讲一套
"blocker": engine.embed_blocker(db, children) if children else "",
"staged_decisions": [
{"app_name": row.app_name, "activity_name": row.activity_name, "decision": row.decision}
for row in staged
],
})
@router.post("/admin/work/{job}/data")
def admin_fix_data(
job: str,

View File

@ -24,7 +24,7 @@ from ..db import get_db, ping
from ..deps import CurrentUser, actor_of, client_ip, current_user, require_permission
from ..envelope import bad_request, not_found, ok
from ..query import count_of
from ..service import dicts, drafts, embed_session, numbering, starters
from ..service import dicts, drafts, embed_session, notify_settle, numbering, starters
from ..service import storage_gc
from ..storage import (
StorageError,
@ -363,6 +363,31 @@ def delete_draft(
# ------------------------------ notifications ----------------------------
def unread_notification_count(db: Session, identity: str) -> int:
"""这个账号还有几条站内信没读过。"""
return int(
db.execute(
select(func.count(models.Notification.id)).where(
models.Notification.identity == identity, models.Notification.read.is_(False)
)
).scalar()
or 0
)
def settle_notifications(db: Session, identity: str) -> None:
"""回答之前先收一次尾:事项已经不在自己手上的那几条站内信就地标已读。
待办办完、转走、被或签结掉、整单终止之后,库里没有任何一处回收那句「您有新的
待办」,于是铃铛里那叠通知越堆越厚、小红点怎么都不灭。判据、为什么只管
``task`` / ``press`` / ``expire`` / ``read`` 这四类、以及为什么收在**读的这一侧**
(待办消失有七八条路子,一处漏挂就是一例;存量那些也能一起补回来),
都写在 :mod:`app.service.notify_settle`。
"""
if notify_settle.settle(db, identity):
db.commit()
@router.get("/notification")
def list_notifications(
user: CurrentUser = Depends(current_user),
@ -371,6 +396,7 @@ def list_notifications(
page: int = Query(1, ge=1),
page_size: int = Query(20, ge=1, le=100),
) -> dict:
settle_notifications(db, user.ref)
stmt = select(models.Notification).where(models.Notification.identity == user.ref)
if unread_only:
stmt = stmt.where(models.Notification.read.is_(False))
@ -383,14 +409,12 @@ def list_notifications(
@router.get("/notification/unread/count")
def unread_count(user: CurrentUser = Depends(current_user), db: Session = Depends(get_db)) -> dict:
count = int(
db.execute(
select(func.count(models.Notification.id)).where(
models.Notification.identity == user.ref, models.Notification.read.is_(False)
)
).scalar()
or 0
)
count = unread_notification_count(db, user.ref)
# 有未读才去收尾:这颗角标每 15 秒问一次,没消息的人一趟都不多跑。
# 真收掉了东西就再数一次——报出去的数字与面板上那一叠必须是同一份账。
if count and notify_settle.settle(db, user.ref):
db.commit()
count = unread_notification_count(db, user.ref)
return ok({"count": count})
@ -439,6 +463,8 @@ def workbench(user: CurrentUser = Depends(current_user), db: Session = Depends(g
"""
identity, person_id = user.ref, user.person_id
month_start = datetime.now().replace(day=1, hour=0, minute=0, second=0, microsecond=0)
# 「未读消息」那一格与铃铛共用一份账:先收尾再数,首页才不会比面板多出一个红点
settle_notifications(db, identity)
def part(name: str, model, *conditions, target=None):
"""一项计数。``target`` 给成别的列(含 ``distinct(...)``)就不数主键。"""

View File

@ -689,6 +689,10 @@ RETIRED_COLUMNS = (
("oa_work_completed", "duration"),
("oa_task_completed", "duration"),
("oa_work_log", "duration"),
# 「在途单据的表单跟随最新设计」这套功能下线:在途与办结的单据都重新冻回发起那一刻
# 那一版表单,这一列(单条流程的跟随覆盖)没有任何代码再读它。生产库的结构变更见
# sql/upgrade/20261111_drop_form_config.sql。
("oa_process", "form_config"),
)
@ -846,7 +850,7 @@ def ensure_indexes(inspector: SchemaReader | None = None) -> list[str]:
def drop_retired_storage_schema(inspector: SchemaReader | None = None) -> list[str]:
"""删掉退役之后遗留的表与列(NAS 网盘、流程耗时那几列)。
"""删掉退役之后遗留的表与列(NAS 网盘、流程耗时、在途单表单跟随那几列)。
``create_all`` 只建不删,老库会一直留着这些没人读的东西。表里如果还有 NAS 记录,
文件也已经不在网盘页的可见范围内了,所以这里直接清掉;列名一律写在

View File

@ -25,8 +25,8 @@ from sqlalchemy.orm import Session
from .. import models, readcache, storage
from ..service import (autofill, channels, dicts, events, external_check, fetch, formruntime,
gate, numbering, org, outbox, personref, quota, terminate as terminate_service,
threshold, titles)
gate, linkfill, numbering, org, outbox, personref, quota,
terminate as terminate_service, threshold, titles)
from . import definition as definition_module
from . import expressions, lookahead, tickets
from .definition import (
@ -704,7 +704,13 @@ def _apply_form_runtime(
# 字段联动:可见性 / 只读要按合并后的数据才算得出来,算完再决定这次提交的
# 哪些值真的收。被联动藏起来或锁掉的字段退回原值,不顺手抹掉历史数据。
writable = formruntime.editable_keys(fields, perms, data) | hidden_keys
# 只被自己那句条件收走 / 锁住的格子(「有值才显示」「有值就锁住」那一类)跟着一起收下:
# 这一笔值正是让它藏起来的原因,退回原样等于把人刚写下的字抹掉。
writable = (
formruntime.editable_keys(fields, perms, data)
| hidden_keys
| formruntime.self_gated_keys(fields, perms, data)
)
known = {str(item.get("key") or "") for item in fields}
for key, value in list(payload.items()):
# 只回滚「表单里定义了、但这个环节不该改」的字段;表单里没有的键
@ -720,6 +726,11 @@ def _apply_form_runtime(
# 排在公式之前,「预算余额 - 申请金额 >= 0」这类公式与后面的条件分支才读到同一份数。
# 带上这一环的字段权限:那一格被本环节藏起来时,取数失败只留痕不拦人(与阈值、额度同一口径)。
fetch.apply_form(db, fields, data, work=work, actor=actor, activity=activity, perms=perms)
# 关联审批单带出来的值同样以服务端为准:按这一格挂着的那几张单现算并覆盖前端。
# 主表那一格按配的那一档合并(几张单合成一个数),明细表那一头一单一行、
# 只在关联变化时重排(人改过的其它列一个字不动)。排在公式之前,
# 「关联单金额合计」那类公式读到的才是刚补好的那几行。口径见 service/linkfill.py。
linkfill.apply(db, fields, data)
work.data = data
formruntime.compute_formulas(fields, data, _context(db, work, actor))
work.data = data
@ -798,9 +809,10 @@ def _attach_payload(
# 批注 / 审批意见随附的图片与文件:字节在 MinIO,记录里只留引用快照
# ---------------------------------------------------------------------------
#: 写进 oa_attachment.type,说明这条附件是随批注还是随审批意见发出去的
#: 写进 oa_attachment.type,说明这条附件是随批注、审批意见还是处理意见发出去的
ATTACHMENT_COMMENT = models.Attachment.KIND_COMMENT
ATTACHMENT_OPINION = models.Attachment.KIND_OPINION
ATTACHMENT_READ = models.Attachment.KIND_READ
def attachment_ref(row: models.Attachment) -> dict:
@ -826,7 +838,7 @@ def claim_attachments(
actor: Actor,
kind: str,
owner_id: str,
work: models.Work | None = None,
work: models.Work | models.WorkCompleted | None = None,
activity_id: str = "",
activity_name: str = "",
) -> list[dict]:
@ -834,6 +846,10 @@ def claim_attachments(
只认「本人上传」且「还没被别人认领」的两条硬规则:文件名、大小、扩展名一律回
附件表取,前端传回来的元数据一个字都不信,否则随手改个 name 就能往单子里塞假附件。
``work`` 给在途单也给归档单:办结之后补的批注、填的处理意见挂在
``oa_work_completed`` 上,附件行照样要认到这一单(``work`` / ``job`` / ``process``)
并直接标成已归档——不回填的话按单查附件、按流程统计存储用量都看不见这些文件。
"""
refs: list[dict] = []
seen: set[str] = set()
@ -852,11 +868,14 @@ def claim_attachments(
row.type = kind
row.business_id = owner_id
if work is not None:
archived = isinstance(work, models.WorkCompleted)
row.process = work.process
row.job = work.job
row.work = work.id
row.activity = activity_id
row.activity_name = activity_name
row.completed = archived
row.work_completed = work.id if archived else ""
refs.append(attachment_ref(row))
db.flush()
return refs
@ -2359,7 +2378,7 @@ def _notify_task(db: Session, task: models.Task, work: models.Work, activity, ac
sender=sender,
)
events.emit(db, work, "task.arrived", activity_name=activity.name,
actor_name=sender,
actor_name=sender, task=task.id,
extra={"identity": task.identity, **_task_arrived_extra(db, work, activity, [task])})
@ -3103,7 +3122,7 @@ def _complete_task(
work_row = db.get(models.Work, task.work)
if work_row is not None:
events.emit(db, work_row, "task.completed", activity_name=task.activity_name,
actor_name=actor.person_name,
actor_name=actor.person_name, task=task.id,
extra={"route": completed.route_name or "", "processingType": processing_type})
db.flush()
db.execute(
@ -3454,7 +3473,9 @@ def _notify_task_batch(db: Session, tasks: list[models.Task], work: models.Work,
process=work.process,
sender=actor.person_name,
)
# 加签一次派出好几条:幂等键里带上第一条待办号与条数,同一环节再邀一轮也推得出去
events.emit(db, work, "task.arrived", activity_name=activity.name, actor_name=actor.person_name,
task=f"{tasks[0].id}+{len(tasks)}" if tasks else "",
extra={"identities": [t.identity for t in tasks],
**_task_arrived_extra(db, work, activity, tasks)})
@ -4225,6 +4246,34 @@ def _pending_tasks(db: Session, work: models.Work) -> list[models.Task]:
)
def running_embed_children(db: Session, work: models.Work) -> list[models.Work]:
"""这张单上还在跑的嵌入子流程。子单是独立实例,父单改道不会带着它们走。"""
return list(db.execute(
select(models.Work)
.where(models.Work.parent_job == work.job, models.Work.status == "running")
.order_by(models.Work.start_time)
).scalars().all())
def embed_blocker(db: Session, children: list[models.Work]) -> str:
"""改道撞上在跑子流程时那句话:报得出是哪几张子单、卡在谁手上、两条出路。"""
parts = []
for child in children[:3]:
names = [str(name or "").strip() for name in db.execute(
select(models.Task.identity_name).where(models.Task.work == child.id)
).scalars().all()]
holders = "、".join(dict.fromkeys(name for name in names if name))
here = str(child.current_activity_names or child.activity_name or "")
parts.append(f"《{child.title}》停在「{here}」" + (f"等 {holders} 办" if holders else ""))
# 子单不止三张时只念前三张:这句话是从接口抛出去的,全列出来会淹没后面那两条出路
listed = ";".join(parts) + (f";另有 {len(children) - 3} 张" if len(children) > 3 else "")
return (
f"这一单还挂着 {len(children)} 张在跑的子流程:{listed}。"
"改道会把父单等子流程回来那张票一起清掉,子单从此没人认领。"
"请先去收拾子单,或勾上「一并终止子流程」再改道。"
)
def _definition_of(db: Session, work: models.Work):
"""流程定义;定义后来被人删了的历史单据返回 ``None``,干预记录照样得写得出来。"""
try:
@ -4335,16 +4384,29 @@ def resume(db: Session, *, job: str, actor: Actor, opinion: str = "") -> StepRes
return StepResult(work=work, tasks=tasks)
def move(db: Session, *, job: str, actor: Actor, activity: str, opinion: str = "") -> StepResult:
def move(
db: Session,
*,
job: str,
actor: Actor,
activity: str,
opinion: str = "",
cascade_children: bool = False,
) -> StepResult:
"""干预改道:把整张单据搬到指定环节重走。
跟审批人自己的「退回」是两把不同的刀——退回只能往上游走、且必须是这一环本人;
改道是管理员替一张卡死的单子换路,往前往后都去得。代价有两条,界面必须讲清楚:
改道是管理员替一张卡死的单子换路,往前往后都去得。代价有三条,界面必须讲清楚:
* 当前所有待办一律结掉进「已办」,谁手里被收走了几条,审批记录里看得见;
* 并行 / 拆分还开着的时候不动刀。``work.joins`` 里还有没收的票箱,就说明此刻
有几条分支同时在路上,改道会把它们并成一条、剩下的分支从此没有归宿,
那种单子请先在出问题的分支上用「退回」。
* 还挂着在跑的嵌入子流程时也先停手。父单停在调用环节时**自己没有待办**,待办全在
子单上,而改道会把 ``work.tokens`` 里那张 ``embed_job`` 等待票一起清掉——子单从此
没人认领,它办完时 ``resume_embed_parent`` 认不出 token 就直接落空,子流程办出来的
结论对父单等于没发生。要么先去收拾子单,要么显式勾上 ``cascade_children``
一并终止:终止是不可逆的,不替管理员默认按下去。
"""
work = _running_work(db, job)
if work.joins:
@ -4352,6 +4414,9 @@ def move(db: Session, *, job: str, actor: Actor, activity: str, opinion: str = "
"这张单据正走在并行 / 拆分的多条分支上,改道会把几条分支并成一条。"
"请先在出问题的那条分支上用「退回」处理,或等其余分支办完。"
)
children = running_embed_children(db, work)
if children and not cascade_children:
raise EngineError(embed_blocker(db, children))
definition = definition_module.for_work(db, work)
target = definition.activity(activity) or definition.activity_by_name(activity)
if target is None:
@ -4373,8 +4438,9 @@ def move(db: Session, *, job: str, actor: Actor, activity: str, opinion: str = "
held = [(task.identity, task.activity_name) for task in tasks]
for task in tasks:
# 收待办走的是「结掉进已办」而不是直接删:这张单上每个人手里的东西都得留痕,
# 事后才答得出「财务复核那条待办怎么没了」。
_complete_task(db, task, actor, route, reason, "", now, LOG_MOVE)
# 事后才答得出「财务复核那条待办怎么没了」。``operator`` 必须给:不传就等于把
# 来人当持有人,陈鹏的「我的已办」里那一行会读成他自己同意的(终止那一步一直有给)。
_complete_task(db, task, actor, route, reason, "", now, LOG_MOVE, operator=actor)
# 换路之后这一段要重新表态:清掉「谁已经批过」的记忆,否则去重规则会把目标环节上
# 那位「前面批过」的审批人直接跳过,改道完单据自己就往前跑了。
variables = dict(work.variables or {})
@ -4385,6 +4451,14 @@ def move(db: Session, *, job: str, actor: Actor, activity: str, opinion: str = "
work.tokens = []
work.joins = {}
work.go_back_store = {}
# 第三方停在半路等确认的那些表态一起作废:那是改道**之前**、按改道之前的表单说的,
# 改道回到同一环时它会突然冒出来等人点头。
from ..service import node_approve
node_approve.invalidate_for_work(
db, work.id, "rerouted",
note=f"单据已由 {actor.person_name} 改道到「{target.name}」,这一环的表态作废",
)
token = {"id": uuid.uuid4().hex, "activity": target.id, "path": target.id}
# 改道是直接落到目标环节、不走 _advance 那段派发,所以"到达本环节生成编号"这一档
# 要在派发待办之前自己补一次,否则管理员把单子挪到编号环节,新待办上还是空的单号。
@ -4405,25 +4479,45 @@ def move(db: Session, *, job: str, actor: Actor, activity: str, opinion: str = "
# 挂起中改的道:新待办跟着一起冻住,等恢复了才放行。
for task in created:
task.pause = True
held_identities = list(dict.fromkeys(identity for identity, _name in held))
for identity, activity_name in held:
notify(
db, [identity],
type_=NOTIFY_CONTROL,
# ``channel_event`` 与站内信类型分家:站内还是那条 control(说的是已经发生的
# 一件事,永远不跟着收尾),外发那一路是渠道能单独勾的 rerouted。存量渠道的
# events 里没这个值,于是默认一句都不往外推,谁要谁勾;深链自动落
# ``/work/<job>``——rerouted 不在 HUB_TASK_EVENTS 里,那条待办已经不在了。
channel_event="rerouted",
title=f"待办已随改道结束:{work.title}",
body=(
f"{actor.person_name} 将《{work.title}》从「{activity_name}」改到「{target.name}」,"
f"你手里那条待办已随之结束。"
f"你手里那条待办已随之结束。原因:{reason}"
),
job=work.job, work=work.id, process=work.process, sender=actor.person_name,
)
if work.creator_identity not in {identity for identity, _ in held}:
if work.creator_identity not in set(held_identities):
notify(
db, [work.creator_identity],
type_=NOTIFY_CONTROL,
channel_event="rerouted",
title=f"流程被改道:{work.title}",
body=f"{actor.person_name} 将《{work.title}》改到「{target.name}」。原因:{reason}",
job=work.job, work=work.id, process=work.process, sender=actor.person_name,
)
# 被收走待办的人手里那句「您有新的待办」当场退场,不等他下次点开列表才收尾。
# 收尾是标已读、不删行,投递记录照旧回查得到(口径见 service/notify_settle.py)。
from ..service import notify_settle
for identity in held_identities:
notify_settle.settle(db, identity)
# 勾了一并终止才动子单,且放在改道之后:父单这边任何一步没成,都不会先把子单杀掉。
for child in children:
terminate(
db, job=child.job, actor=actor,
opinion=f"父流程已由 {actor.person_name} 改道到「{target.name}」,子流程一并终止",
enforce_starter_config=False,
)
db.flush()
return step
@ -4895,6 +4989,37 @@ def share_work(db: Session, *, work_id: str, actor: Actor, identities: list[str]
)
def _comment_blocker(activity) -> str:
"""环节那一格「允许批注」关掉了就回挡下的那句原话,没关(或认不出环节)回空串。"""
if activity is None or bool((activity.config or {}).get("allowComment", True)):
return ""
return f"环节 {activity.name} 不允许批注"
def comment_activity(db: Session, subject):
"""这一单"此刻停在那一环"的定义行;认不出来就回 ``None``。
在途件认 ``oa_work.activity``——就是当前压着没办的那一环,与界面上那份环节简报同源。
**归档件没有这一格可判**:``oa_work_completed`` 压根不落 ``activity``(单子已经走完,
"当前环节"对它没有意义;办结抄送用的那一环是 :func:`_finish_work` 当场拿到的参数,
没有存进归档行)。所以归档件走的是"认不出环节 → 放行"这一支,不是漏判:
设计器里那格「允许批注」管的是这一环还压在人手上时能不能补话,一张已经落定的单子
上没有这样一环。设计整个被删掉时同样回 ``None`` 放行——一句补充批注不该因为
图纸没了而发不出去,与 :func:`definition.for_work` 对老单的回退一个脾气。
"""
try:
definition = definition_module.for_work(db, subject)
except (ValueError, EngineError):
return None
return definition.activity(str(getattr(subject, "activity", "") or ""))
def comment_blocker(db: Session, subject) -> str:
"""在这张单上补批注会不会被挡、被什么挡。在途与归档走同一条判据。"""
return _comment_blocker(comment_activity(db, subject))
def list_comments(db: Session, work_id: str) -> list[models.WorkComment]:
rows = db.execute(
select(models.WorkComment).where(models.WorkComment.work == work_id).order_by(models.WorkComment.order_number)
@ -4927,8 +5052,11 @@ def add_comment(
if work is not None:
definition = definition_module.for_work(db, work)
activity = definition.activity(work.activity)
if activity is not None and not bool(activity.config.get("allowComment", True)):
raise EngineError(f"环节 {activity.name} 不允许批注")
# 归档件也过同一道闸:以前只在途上判,办结之后那格「允许批注」等于失效,
# 关掉了照样能往里发批注。判据只有一处(``_comment_blocker``),界面与引擎同一句话。
blocker = _comment_blocker(activity if activity is not None else comment_activity(db, subject))
if blocker:
raise EngineError(blocker)
resolved = org.resolve_identity_names(db, mentions or [])
order = len(list_comments(db, work_id))
comment = models.WorkComment(
@ -4959,7 +5087,8 @@ def add_comment(
actor=actor,
kind=ATTACHMENT_COMMENT,
owner_id=comment.id,
work=work,
# 在途认 oa_work,归档认 oa_work_completed:两种都要把附件行落到这一单上
work=work if work is not None else subject,
activity_id=comment.activity,
activity_name=comment.activity_name,
)
@ -4999,10 +5128,25 @@ def get_read(db: Session, read_id: str, actor: Actor) -> models.Read:
return row
def mark_read(db: Session, *, read_id: str, actor: Actor, opinion: str = "", handling: bool = False) -> models.ReadCompleted:
"""已阅登记。带 ``requires_action`` 的待阅必须走处理确认(``handling=True``)并留下处理意见。"""
def mark_read(
db: Session,
*,
read_id: str,
actor: Actor,
opinion: str = "",
handling: bool = False,
attachments: list[str] | None = None,
) -> models.ReadCompleted:
"""已阅登记。带 ``requires_action`` 的待阅必须走处理确认(``handling=True``)并留下处理意见。
``handling`` 那一趟还能带上图片或文件(``attachments`` 是前端先传好的附件 id),
与批注同一套认领口径:处理「抄送需处理」的人可以贴一张截图说清情况。
"""
row = get_read(db, read_id, actor)
now = datetime.now()
ids = [str(item) for item in (attachments or []) if str(item or "")]
if ids and not handling:
raise EngineError("填写处理意见时才能附上图片或文件")
if row.requires_action and handling:
if not (opinion or "").strip():
raise EngineError("请填写处理意见")
@ -5036,6 +5180,7 @@ def mark_read(db: Session, *, read_id: str, actor: Actor, opinion: str = "", han
opinion=row.opinion,
read_type=row.read_type,
requires_action=row.requires_action,
attachments=list(row.attachments or []),
source_identity=row.source_identity,
handle_time=row.handle_time,
start_time=row.start_time,
@ -5044,6 +5189,21 @@ def mark_read(db: Session, *, read_id: str, actor: Actor, opinion: str = "", han
db.add(done)
db.delete(row)
db.flush()
if ids:
# 归属认到这条已阅记录上,附件行同时认到这一单(归档件也在里面)
subject = db.get(models.WorkCompleted, row.work_completed or row.work) if archived \
else db.get(models.Work, row.work)
done.attachments = claim_attachments(
db,
ids=ids,
actor=actor,
kind=ATTACHMENT_READ,
owner_id=done.id,
work=subject,
activity_id=row.activity,
activity_name=row.activity_name,
)
db.flush()
return done
@ -5210,6 +5370,8 @@ def _finish_work(
opinion=read.opinion,
read_type=read.read_type,
requires_action=read.requires_action,
# 处理意见随附的图片/文件跟着那条待阅一起搬档,不然办结之后回看只剩一段文字
attachments=list(read.attachments or []),
source_identity=read.source_identity,
handle_time=read.handle_time,
start_time=read.start_time,
@ -5295,13 +5457,24 @@ def _sync_work_cursor(db: Session, work: models.Work, definition: ProcessDefinit
work.manual_identity_text = ",".join(
dict.fromkeys(row[1] or named.get(str(row[0]), str(row[0])) for row in identities)
)
work.current_activity_names = ",".join(
names = ",".join(
dict.fromkeys(
definition.activity(t.get("activity", "")).name
for t in tokens
if definition.activity(t.get("activity", "")) is not None
)
)
if names != work.current_activity_names:
# 待阅行上那份「当前环节」是抄送那一刻抄下来的快照,只有再抄一次或归档才动。
# 于是「这张单停在哪个环节」这一列会在每一次前进之后慢慢说谎——改道把它摆得
# 格外显眼而已。挂在游标这一句里而不是挂在改道里:每一次前进都该刷。
# 只刷没读的那批:已阅是历史快照,那个人当时看到的就是那一句。
db.execute(
update(models.Read)
.where(models.Read.work == work.id, models.Read.completed.is_(False))
.values(current_activity_name=names)
)
work.current_activity_names = names
def _jump_redirect(db: Session, work: models.Work, definition: ProcessDefinition, target):

View File

@ -2050,6 +2050,9 @@ class Read(Base, TimestampMixin):
read_type: Mapped[str] = mapped_column(String(32), default="cc", nullable=False)
# 抄送需处理:收件人要填写处理意见并确认,只点开看不算处理完
requires_action: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
# 处理意见随附的图片与文件:只存引用快照,字节在 oa_attachment.storage 指向的对象里。
# 与批注同一套存法(见 ``engine.claim_attachments``),区别只在 type 那一格写的是 read。
attachments: Mapped[JsonList] = mapped_column(JsonList, default=list, nullable=False)
source_identity: Mapped[str] = mapped_column(String(512), default="", nullable=False)
handle_time: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
view_time: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
@ -2085,6 +2088,8 @@ class ReadCompleted(Base, TimestampMixin):
# 已阅侧同步保留抄送来源与是否需要处理,归档后还看得出是哪种待阅
read_type: Mapped[str] = mapped_column(String(32), default="cc", nullable=False)
requires_action: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
# 处理意见随附的图片与文件跟着这条已阅记录显示(待阅那一条登记已阅时整行搬过来)
attachments: Mapped[JsonList] = mapped_column(JsonList, default=list, nullable=False)
source_identity: Mapped[str] = mapped_column(String(512), default="", nullable=False)
handle_time: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
view_time: Mapped[datetime] = mapped_column(DateTime, default=localnow, nullable=False)
@ -2130,11 +2135,12 @@ class Attachment(Base, TimestampMixin):
# work 没有,那条 UPDATE 于是每办结一张单整表扫一次。
__table_args__ = (Index("idx_oa_attachment_work", "work"),)
#: ``type`` 里"跟着某条批注/审批意见一起发出去"的几种取值。这类附件不进单据的
#: ``type`` 里"跟着某条批注/审批意见/处理意见一起发出去"的几种取值。这类附件不进单据的
#: 附件清单,而是跟着那条记录一起显示(见 api.support.list_attachments)。
KIND_COMMENT = "comment"
KIND_OPINION = "opinion"
KIND_LINKED = (KIND_COMMENT, KIND_OPINION)
KIND_READ = "read"
KIND_LINKED = (KIND_COMMENT, KIND_OPINION, KIND_READ)
id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id)
name: Mapped[str] = mapped_column(String(512), nullable=False)

View File

@ -920,6 +920,22 @@ class DataSourceSearchBody(CamelModel):
args: dict[str, Any] = Field(default_factory=dict)
class RelationFillBody(CamelModel):
"""关联单据带出的即时预览:这一格挂着的那几张单 + 要取的那几列。
路径(``work.serial`` / ``data.金额.sum``…)交给后端解析,前端不镜像那份路径语言——
与 ``POST /data-source/fetch`` 同一个分寸:**这个结果只用来显示**,
提交时引擎按同一份配置再算一次(``service/linkfill.apply``)。
"""
#: 这一格存着的那串值:默认是对方单据的 ``job``,配过「存值 = 单号」时是单号
values: list[str] = Field(default_factory=list)
picks: list[str] = Field(default_factory=list)
#: 正在填的那张单的 ``job``;发起页还没有,留空。带上它,办理环节的人即便与对方
#: 那张单无关,也看得见**确实挂在自己手上这一单**的那几张的预览(见接口那份说明)
work: str = ""
class DictSyncBody(CamelModel):
"""外部来源的字典手动同步:``dryRun`` 只拉不落库(设计页预览)。"""
@ -1020,10 +1036,13 @@ class MoveBody(CamelModel):
"""流程干预「改道」:落到哪一环。
``activity`` 环节 id 与环节名都认(跟退回同一个口径),管理员从下拉里选的就是名字。
``cascade_children`` 只在父单还挂着在跑的子流程时才用得上:默认改道撞上子单会停手,
勾上它才把这些子单一并终止(终止不可逆,不由一次改道替人默认按下)。
"""
activity: str = ""
opinion: str = ""
cascade_children: bool = False
class ExportDetailUnoperatorBody(CamelModel):
@ -1105,6 +1124,8 @@ class DraftBody(CamelModel):
class ReadViewBody(CamelModel):
opinion: str = ""
#: 处理意见随附的图片/文件:前端先传好的附件 id,只在"填写处理意见"那一趟认到记录上
attachments: list[str] = Field(default_factory=list)
class ReadWorkBody(CamelModel):

View File

@ -497,6 +497,8 @@ def read_row(row: models.Read | models.ReadCompleted) -> dict:
"read_type": getattr(row, "read_type", "cc") or "cc",
"requires_action": bool(getattr(row, "requires_action", False)),
"handled": bool(getattr(row, "handle_time", None)),
# 处理意见随附的图片与文件:引用快照,跟着这条待阅/已阅一起显示
"attachments": list(getattr(row, "attachments", []) or []),
"source_identity": getattr(row, "source_identity", "") or "",
"start_time": dt(row.start_time),
"view_time": dt(row.view_time),

View File

@ -68,6 +68,39 @@ MERGE_MODES = ("first", "sum", "min", "max", "join")
NUMERIC_MERGE_MODES = ("sum", "min", "max")
#: 合集默认的拼接分隔符
DEFAULT_SEPARATOR = "、"
#: 一条源上的「什么时候用它」那一个键:值是一份结构化条件(与字段上的 ``visibleWhen``
#: 同一份形状,判定在 ``service/dicts.condition_ok``)。
#:
#: 为什么这一档挂在**每一条源**上而不是整份配置上:同一格常常要换家问——「费用类型是差旅
#: 就问差标接口,是招待就问 ERP 科目」。以前要么为每种组合另建一条源、要么在表单上多摆几格
#: 再拿显隐条件藏起来;清单里那几条本来就按顺序排的,加一句「这条什么时候算」就够它当路由用。
#: 没写这一项的条目恒成立,所以老配置读出来的行为一个字都不变。
ENTRY_WHEN_KEY = "when"
def entry_when(cfg: dict) -> dict | None:
"""这一条源挂的触发条件;没写、写得不成形状都回 ``None``(= 恒成立)。"""
when = cfg.get(ENTRY_WHEN_KEY) if isinstance(cfg, dict) else None
if isinstance(when, list):
when = {"match": "all", "rules": when}
if not isinstance(when, dict) or not (when.get("rules") or []):
return None
return when
def entry_active(entry: dict, data: dict | None) -> bool:
"""这一条源此刻用不用得上:没配条件恒成立,配了就问那一份结构化条件。
条件判定用的是联动那一份口径(``service/dicts.condition_ok``),于是设计器里拼得出
「报销类型 = 差旅」的那一条,运行时与提交链路里算的是同一个真假。延迟导入只为绕开
``dicts → binding`` 这一层反向依赖,不是另一套判据。
"""
when = entry_when(entry)
if when is None:
return True
from . import dicts
return dicts.condition_ok(when, data or {})
def blank(value: Any) -> bool:
@ -301,12 +334,16 @@ def arg_names_of(*templates: Any) -> set[str]:
def entries(cfg: Any) -> list[dict]:
"""这一格要用的数据源清单,统一成 ``{source, args, picks, pick, extras}``。
"""这一格要用的数据源清单,统一成 ``{source, args, picks, pick, extras, when}``。
配了 ``sources`` 就是「一个字段用好几个接口」的合集写法,没配就回落到
``source`` / ``args`` / ``picks`` 那份单源老写法——调用方不用管当初配的是哪一种。
候选来源那一路(``optionSource=dataSource``)也吃这份形状,
只是它只有一张源:``{source: dataSourceCode, args: dataSourceArgs}``。
这一句**只管清单全不全**,不问「此刻该不该调」——带条件的条目照原样在清单里,
要跑哪几条问 :func:`active_entries`。设计期检查(源还在不在、入参引用掉没掉在地上)
得看全量,运行时才按条件筛,两头各取所需。
"""
if not isinstance(cfg, dict):
return []
@ -325,6 +362,7 @@ def entries(cfg: Any) -> list[dict]:
"args": item.get("args") if isinstance(item.get("args"), dict) else {},
"picks": item.get("picks") if isinstance(item.get("picks"), dict) else {},
**entry_parse(item),
**({"when": item["when"]} if entry_when(item) else {}),
}
)
if out:
@ -338,10 +376,20 @@ def entries(cfg: Any) -> list[dict]:
"args": cfg.get("args") if isinstance(cfg.get("args"), dict) else {},
"picks": cfg.get("picks") if isinstance(cfg.get("picks"), dict) else {},
**entry_parse(cfg),
**({"when": cfg["when"]} if entry_when(cfg) else {}),
}
]
def active_entries(cfg: Any, data: dict | None) -> list[dict]:
"""这一格**此刻**要调的那几张源:清单里只留触发条件成立的条目。
一条都不成立就是这一格这次不取数(值留在原来那一份上,按 ``onError`` 那档兜),
和「配了源但源停了」不是一回事,所以留痕里也不会记成失败。
"""
return [entry for entry in entries(cfg) if entry_active(entry, data)]
def entry_parse(cfg: dict) -> dict:
"""这一格对**解析规则**的两处覆盖,缺省就不写这两个键(老配置的形状保持三个键)。
@ -544,14 +592,51 @@ def live_target(target: Any, keys: set[str] | None) -> str:
return ""
def condition_ref_problems(condition: Any, keys: set[str], at: str) -> list[str]:
"""一份结构化条件里的引用毛病:字段没了、比较符不认。
判"引用了不存在的字段"而不是判"这个值对不对":条件永远不成立时那一格只是安静地不调、
不选、不显示,没人报错,最难查的正是这种"配了个寂寞"。``keys=None`` 时不判引用
(拿不到字段清单的那几处调用方)。
"""
from . import dicts
out: list[str] = []
normalized = condition
if isinstance(normalized, list):
normalized = {"match": "all", "rules": normalized}
if not isinstance(normalized, dict):
return [f"{at}的条件格式不对"]
for rule in normalized.get("rules") or []:
if not isinstance(rule, dict):
out.append(f"{at}的条件里有认不出的写法")
continue
op = str(rule.get("op") or "").strip()
if op not in dicts.CONDITION_OPS:
out.append(f"{at}的条件里有不支持的比较符:{op or '(空)'}")
for name in ("field", "valueField"):
ref = str(rule.get(name) or "").strip()
if ref and keys is not None and ref not in keys:
out.append(f"{at}的条件引用了不存在的字段「{ref}」")
if not (normalized.get("rules") or []):
out.append(f"{at}的条件一条规则都没有,等于这条永远不成立")
return out
def entry_problems(
db, entry: dict, keys: set[str], at: str, *,
self_key: str = "", want: str = WANT_FETCH, want_noun: str = "这一格", declared_only: bool = True,
person_keys: set[str] | None = None
person_keys: set[str] | None = None, target_keys: set[str] | None = None, target_noun: str = "字段"
) -> list[str]:
"""一个源那条配置本身的毛病:源在不在、入参引用、带出去向。
外加这一条自己那份触发条件(``when``)——它永远不成立的话,这一条源根本不会被调。
``db=None`` 是设计器镜像那一份(拿不到库):那时只判写法与引用,不判源。
``keys`` 是**入参**能引用的那一份名字清单,``target_keys`` 是**带出去向**能写进去的那一份,
两者默认是同一份(主表字段就是这么配的)。明细列那一格必须分开传:它的入参读得到整张单
与本行的列(``{form.x}`` 在行作用域里两边都认,同名列以本行为准,跟本行公式同一分寸),
而带出去向只许落在同一张明细表的列上。``target_noun`` 只管那句报错怎么说。
"""
out: list[str] = []
if not isinstance(entry, dict):
@ -566,20 +651,24 @@ def entry_problems(
out.extend(arg_ref_problems(
entry.get("args"), keys, at, person_keys=person_keys if sql_bound else None
))
allowed_targets = keys if target_keys is None else target_keys
for name, target in (entry.get("picks") or {}).items() if isinstance(entry.get("picks"), dict) else []:
target_key = str(target or "").strip()
if not target_key:
continue
if target_key not in keys:
out.append(f"{at}要把「{name}」带进不存在的字段「{target_key}」")
if target_key not in allowed_targets:
out.append(f"{at}要把「{name}」带进不存在的{target_noun}「{target_key}」")
elif self_key and target_key == self_key:
out.append(f"{at}不能把值带进自己,交给 {at} 那格本身就行")
out.append(f"{at}不能把值带进自己:取回来的那一个值本来就落在这一格上")
extra_rows = entry.get("extras") if isinstance(entry.get("extras"), dict) else {}
for name, path in extra_rows.items():
if not str(name or "").strip():
out.append(f"{at}有一行额外带出列没写名字")
elif not str(path or "").strip():
out.append(f"{at}额外带出的「{name}」没写它在响应里的路径")
when = entry_when(entry)
if when is not None:
out.extend(condition_ref_problems(when, keys, at))
if row is not None:
problem = source_problem(code, row, want=want, want_noun=want_noun)
if problem:

View File

@ -51,6 +51,11 @@ EVENTS: tuple[tuple[str, str], ...] = (
("completed", "办结结果"),
("expire", "待办超时"),
("meeting", "会议提醒"),
# 管理员干预改道:站内那条留痕叫 control,外发这一路单独一个事件名。分成两个是因为
# 挂起 / 恢复 / 改数据这类动作不值得往邮箱和群里刷,而改道**收走了别人手里的待办**——
# 那张卡片已经推出去了、又收不回来,管理员想对外说一句时得能只勾这一档。
# 存量渠道的 events 里没这个值,所以默认一句都不往外推。
("rerouted", "流程被干预改道"),
)
EVENT_LABELS = dict(EVENTS)
#: 界面上"全选"用的清单

View File

@ -877,7 +877,9 @@ def _text(row, spec: ColumnSpec, cache: dicts_service.DictCache, jobs: dict[str,
return _base_text(row, spec.id, halt)
data = dict(getattr(row, "data", None) or {})
if spec.kind == "form":
return exportfmt.cell_text(spec.field, data.get(str(spec.field.get("key") or "")), cache, jobs)
return exportfmt.cell_text(
spec.field, data.get(str(spec.field.get("key") or "")), cache, jobs, data=data
)
if spec.kind == "table":
return _table_child_text(spec, data.get(str(spec.field.get("key") or "")), cache, jobs)
return _activity_text(row, spec)
@ -896,7 +898,7 @@ def _table_child_text(spec: ColumnSpec, value: object, cache: dicts_service.Dict
if str(column.get("key") or "") != child:
continue
for row in formruntime.rows_of(value):
text = exportfmt.cell_text(column, row.get(child), cache, jobs)
text = exportfmt.cell_text(column, row.get(child), cache, jobs, data=row)
if text:
parts.append(text)
return "、".join(parts)

View File

@ -9,8 +9,12 @@
2. **级联**(``cascadeFrom``):下级字段的选项按上级字段选中的字典项 ``parent`` 过滤,
省→市→区、费用大类→子类、物料→规格都走这一条。
3. **条件联动**(``visibleWhen`` / ``requiredWhen`` / ``readonlyWhen`` / 选项上的 ``when``):
由一组结构化规则(``{"match": "all", "rules": [{"field", "op", "value"}]}``)判定,
前端渲染和服务端校验用同一套口径,不会出现「界面能填、提交被拒」。
由一组结构化规则(``{"match": "all", "rules": [{"field", "op", "value" | "valueField"}]}``)判定,
前端渲染和服务端校验用同一套口径,不会出现「界面能填、提交被拒」。规则的右边可以是写死的
``value``,也可以是**同一张表单里的另一格**(``valueField``,「结束日期晚于开始日期」那种),
那一格还没填时这一条不算成立——判法见 :func:`_rule_ok`。左边或右边挑的也可以是
**这一格自己**(``rules[].field`` 就是本字段):「外部带回来的合同编号有值才露这一格」
判的就是它自己的值;摘掉自引用那几条还剩什么,见 :func:`stripped_of_self`。
字典项的 ``extra`` 是附加值,配合字段的 ``autoFill`` 就能做「选了物料自动带出单价」,
带出的值由服务端按字典重写一遍,前端塞不进来。
@ -20,6 +24,7 @@ from __future__ import annotations
import json
import logging
import re
from datetime import datetime, timedelta
from typing import Any, Iterable
@ -38,6 +43,9 @@ logger = logging.getLogger("unisoa.dicts")
CONDITION_OPS = {
"eq", "ne", "gt", "ge", "lt", "le", "in", "nin", "contains", "empty", "notEmpty", "changed",
}
#: 压根不看右值的那几个比较符(前端 formLinkage.LINKAGE_VALUELESS_OPS 同一份)。
#: 右边挑了另一格时也要认这一份:判空问的是左边那一格自己,右边空不空跟它没关系。
VALUELESS_OPS = {"empty", "notEmpty", "changed"}
#: 能挂选项的字段类型。
OPTION_TYPES = {"select", "radio", "checkbox"}
#: 下拉选择:与下拉框同一只挑选器,定位是「候选来自别处」(外部数据源 / 别的流程的单据)。
@ -76,6 +84,36 @@ SEARCHED_SOURCES = (SOURCE_PROCESS, SOURCE_DATA_SOURCE)
#: 挑候选的姿势;``auto`` 由前端 ``autoStyleOf`` 决定,服务端只认这几档。
PICKER_STYLES = ("auto", "dropdown", "dialog", "inline")
# ---------------------------------------------------------------------------
# 流程单据那一档:这一格能挂哪几种状态的单据
# ---------------------------------------------------------------------------
#
# 单据在库里只活两张表:在办表 ``oa_work`` 只有 ``running``,归档表 ``oa_work_completed``
# 里躺着 ``completed``(走完并归档通过)、``terminated``(被终止)、``canceled``(作废)。
# 「关联已审批流程」以前把两张表混着给人挑,于是能挑到一张走到一半被人终止的单子——
# 挂一张没走完的单当依据,审批人点开对照时才发现对不上;而单据被终止这件事发生在
# 挂上之后,所以已存的值不能按这一档判非法,只管**候选列不列它**。
# 前端镜像在 ``utils/optionSource.ts:relationStatusesOf``,三档的说法两边同一份。
#: 走完并归档通过的单子(归档表 ``status == 'completed'``)。
RELATION_STATUS_DONE = "completed"
#: 还在办的单子(在办表)。
RELATION_STATUS_RUNNING = "running"
#: 半路停下的单子:被终止与作废的归一档,它们都不是「审批通过」。
RELATION_STATUS_CLOSED = "closed"
#: 三档;界面上勾的顺序与这句顺序一致。
RELATION_STATUSES = (RELATION_STATUS_DONE, RELATION_STATUS_RUNNING, RELATION_STATUS_CLOSED)
#: 没配过这一格的表单:只给归档通过的单子。
RELATION_STATUS_DEFAULT = (RELATION_STATUS_DONE,)
#: 每一档落到单据状态上是哪几个值。归档表里除 ``completed`` 剩下那两种就是 ``closed``。
RELATION_STATUS_WORK_STATUSES = {
RELATION_STATUS_DONE: ("completed",),
RELATION_STATUS_RUNNING: ("running",),
RELATION_STATUS_CLOSED: ("terminated", "canceled"),
}
#: 哪一档活在**在办表**里;其余几档都只在归档表里找。
RELATION_STATUS_RUNNING_TABLE = (RELATION_STATUS_RUNNING,)
#: 「显示哪一列、存哪一列」各来源默认存的那一列——就是这一维出现之前代码写死的那几列。
#: 前端镜像在 ``src/utils/optionMap.ts``,两边默认值必须一模一样,老表单才读得出同一个结果。
DEFAULT_VALUE_KEYS = {SOURCE_MANUAL: "value", SOURCE_DICT: "value", SOURCE_PROCESS: "job", SOURCE_DATA_SOURCE: "value"}
@ -118,6 +156,83 @@ def holds_list_value(field: dict) -> bool:
return field_type in MULTIPLE_PICKER_TYPES and bool(field.get("multiple"))
def relation_statuses(field: dict) -> tuple[str, ...]:
"""这一格允许挂哪几种状态的单据;没配、配空了都退回默认那一档(归档通过)。
界面上勾的是「已办结归档 / 还在办 / 已终止或作废」三档,存下来的是档位编码的数组。
三档全勾等于不限(``relation_status_query`` 把这句摊成空,两张表照旧一起搜)。
"""
raw = field.get("relationStatuses")
if not isinstance(raw, list):
return RELATION_STATUS_DEFAULT
tokens = {str(item).strip() for item in raw}
picked = tuple(item for item in RELATION_STATUSES if item in tokens)
return picked or RELATION_STATUS_DEFAULT
def relation_status_query(raw: str) -> tuple[str, ...]:
"""把接口上那句 ``status`` 摊成几档:逗号分隔,认不出的丢掉,全挑与空都当不限。
历史上这个参数收的是单据状态原值(``completed`` / ``terminated`` …),那几种要么与档位
同名、要么整个落在某一档里,所以老写法读出来还是同一批单子,不必另开一个参数。
"""
tokens = [item.strip() for item in str(raw or "").split(",") if item.strip()]
if not tokens:
return ()
hit = set()
for token in tokens:
if token in RELATION_STATUSES:
hit.add(token)
continue
hit.update(
bucket for bucket, statuses in RELATION_STATUS_WORK_STATUSES.items() if token in statuses
)
wanted = tuple(item for item in RELATION_STATUSES if item in hit)
return () if len(wanted) == len(RELATION_STATUSES) else wanted
def relation_status_tables(
buckets: tuple[str, ...],
) -> tuple[tuple[str, ...] | None, tuple[str, ...] | None]:
"""分成「在办表挑哪几个状态」与「归档表挑哪几个状态」,两张表各回一份。
某一张表一个都不沾就回 ``None``,让调用方干脆不去查它——结果一样,省一次空跑。
不限(``buckets`` 为空)时两张表都查、都不加状态条件。
"""
if not buckets:
return None, None
def statuses_of(in_running_table: bool) -> tuple[str, ...]:
picked = [
status
for bucket in buckets
if (bucket in RELATION_STATUS_RUNNING_TABLE) is in_running_table
for status in RELATION_STATUS_WORK_STATUSES[bucket]
]
return tuple(picked) or None
return statuses_of(True), statuses_of(False)
def relation_status_problems(field: dict) -> list[str]:
"""设计期检查:这一格勾的那几档认不出来,或一种都没勾。
一种都不勾等于这一格永远搜不到候选——填单的人只会看见一只永远为空的挑选器。
"""
raw = field.get("relationStatuses")
if raw is None:
return []
if not isinstance(raw, list):
return ["能挂哪几种状态的单据要写成一份清单"]
tokens = {str(item).strip() for item in raw}
unknown = [str(item) for item in raw if str(item).strip() not in RELATION_STATUSES]
if unknown:
return [f"能挂哪几种状态的单据里有认不出的档位:{'、'.join(unknown)}"]
if not tokens:
return ["至少勾一种状态:一种都不勾,这一格永远搜不到候选"]
return []
def source_kind_of(field: dict) -> str:
"""这一格走的是哪条候选来源;老表单没写 ``optionSource`` 时按老写法推。
@ -136,9 +251,400 @@ def source_kind_of(field: dict) -> str:
return SOURCE_MANUAL
def constrains_values(field: dict) -> bool:
"""这一格的取值要不要按「必须在候选里」把关:搜出来的那两条不把关。"""
return source_kind_of(field) not in SEARCHED_SOURCES
def constrains_values(field: dict, data: dict | None = None) -> bool:
"""这一格的取值要不要按「必须在候选里」把关:搜出来的那两条不把关。
传了 ``data`` 就按**此刻命中的那一条候选来源**判——挂了条件路由的格子,
这一分钟是字典(要把关)、下一分钟可能是外部数据源(不把关),拿字段上那一份
固定配置去判会把人正常选中的物料判成越界。不传就是问「这套配置里有没有要把关的来源」,
设计期与导出那几处不知道单据值时才这么问。
"""
if data is None:
# 没有单据值可比:按「这一格可能落到哪几种来源」取并集,有一条要把关就算把关。
# 站在安全侧是有代价的(可能多判一次越界),但那份判据本身还要 data 才算得准,
# 所以真拦人的地方一律把 ``data`` 传进来,这一支只给"问不出值"的调用方兜底。
kinds = {route_source_of(item) for item in routes_of(field)} | {source_kind_of(field)}
return any(kind not in SEARCHED_SOURCES for kind in kinds)
return source_kind_of(option_view(field, data)) not in SEARCHED_SOURCES
# ---------------------------------------------------------------------------
# 候选来源的条件路由(``optionRoutes``):一格挂好几套来源,按这张单上的值挑一套
#
# 「候选从哪儿来」以前只有一答:这一格要么绑一本字典、要么挂一张数据源、要么就是手填那几条。
# 现实里同一格常常要换家——报销类型是「差旅」时候选是差标字典,是「招待」时要问 ERP 的费用科目,
# 选「其他」又只想让人自己从两个词里挑。以前只有两条路:在表单上摆三格、用显隐条件把另外两格
# 藏起来(三格 = 三个字段名 = 三份导出列与三套环节权限),要么去对面求一个聚合接口。
#
# 这一层给的是第三答:字段上多挂一份**有序清单**,每一条 = 一个触发条件 + 一套候选来源配置,
# 自上而下第一条成立的用它;一条都不成立就回落到字段自己那份配置——也就是今天的行为,
# 老表单一个字节都不用改。条件用的还是联动那一份结构化条件(与 ``visibleWhen`` 同一口径,
# 判定就是 :func:`condition_ok`),于是设计器里拼得出来、前端算得出来、提交时后端再算一遍。
#
# 这一层**不新增任何一条候选口径**:它只把字段换成一张「此刻的视图」(:func:`option_view`),
# 视图喂给 ``source_kind_of`` / ``effective_options`` / ``stored_of`` 这些既有函数,读出来的
# 就是命中那一条。前端镜像在 ``src/utils/optionSource.ts``(``optionRoutesOf`` /
# ``matchedOptionRoute`` / ``optionFieldView``),两份算法必须算出同一个结果——界面上显示 A 家的
# 候选、提交时按 B 家判越界,是这一整套最容易犯的错。
# ---------------------------------------------------------------------------
#: 条件路由清单存在字段上哪一个键。
OPTION_ROUTES_KEY = "optionRoutes"
#: 一格最多挂几条。上限的道理和外部取数那份多源清单一样:再多就不是「换一家」而是该做一个
#: 聚合接口了,而且清单越长,越没人说得清哪一条会赢。
MAX_OPTION_ROUTES = 8
#: 每一条路由自己带的那几格:这一条用哪种来源,就只有那一种的配置说得通。
ROUTE_OWNED_KEYS: dict[str, tuple[str, ...]] = {
SOURCE_MANUAL: ("options",),
SOURCE_DICT: ("dictCode", "cascadeFrom"),
SOURCE_PROCESS: ("relationProcess", "relationStatuses"),
SOURCE_DATA_SOURCE: ("dataSourceCode", "dataSourceArgs"),
}
#: 所有来源会留下的痕迹(收残骸时用这一份)。``dataSourceArgs`` 与
#: ``formruntime.OPTION_ARGS_KEY`` 同一个键名,那边是延迟导入绕循环的,这里只能再写一遍字面量。
_ALL_ROUTE_KEYS = tuple(dict.fromkeys(key for keys in ROUTE_OWNED_KEYS.values() for key in keys))
#: 备注那一格只给配表单的人看:填单的人不必知道「这一条是问财务要的」。
ROUTE_NOTE_KEY = "note"
#: 每一条候选路由**自带的那份带出**(只给外部数据源那一条用):``{args, picks, extras}``。
#:
#: 「按这张单上的值换一家数据源」与「换一家就把那一家的几列带进对应的格子」是同一件事的两半,
#: 分成两份清单配就得把同一个条件写两遍(还漏一处就出现「候选换了家、带出还是上一家的」)。
#: 这一键把带出挂在**那一条路由上**:命中哪一条,就用哪一张源、那一条的入参、那一条的带出去向。
#: 运行时不新造执行器——它被摊成一条普通的取数条目(``fetch.config_of``),与字段上那一份
#: ``fetch`` 跑的是同一个 :func:`binding.entries`、同一份留痕、同一条 ``onError``。
#: 与字段级那份的分工是回落那一条:**命中那条自带带出就用它,没自带回落到字段上那一份**;
#: 这一份只写带出去向那几格,**不盖这一格自己那一个值**(那是人从候选里挑的)。
ROUTE_FILL_KEY = "fill"
#: 一份带出里能存的三张表(与 ``binding.entries`` 归一出来的那三个键同一份)。
#: 另外那一个 ``source`` 是可选的「带出问哪一家」:留空 = 就问这一条候选那一家。
ROUTE_FILL_TABLES = ("args", "picks", "extras")
#: 「带回来的值不在这格的候选里也收下」那一档开关的键名(字段上 ``allowOutsideValue``)。
#:
#: 下拉框的候选以前是硬边界:外部取数 / 关联单据带出 / 字典带出写进来的值一旦不在清单里,
#: 页面上会被清成空、提交时会被判「取值已不在可选范围内」。可这一格的答案本来就是系统写的,
#: 拿本地清单去判对面给的值并不讲理——于是给一个开关,勾上就收下(后端判据在
#: ``formruntime.selection_problems``,三种带出都排在校验之前,值一定是服务端自己写的)。
ALLOW_OUTSIDE_VALUE_KEY = "allowOutsideValue"
def accepts_outside_value(field: dict) -> bool:
"""这一格收不收「候选清单之外」的值(只影响带回来的值,不放开给人乱填)。"""
return bool(field.get(ALLOW_OUTSIDE_VALUE_KEY))
def route_source_of(route: dict) -> str:
"""这一条路由用的是哪一种候选来源。"""
return str(route.get("source") or "").strip()
def routes_of(field: dict) -> list[dict]:
"""这一格配的条件路由清单,洗成 ``[{source, when, <来源自己那几格>, fill?}]``。
没配、配成非数组、来源不属于这一类字段的一律丢掉——**脏条目当没配**比报错好:宁可这一格
回落到字段自己那份配置,也不要让填单的人对着一只永远为空的挑选器。
"""
raw = field.get(OPTION_ROUTES_KEY)
if not isinstance(raw, list):
return []
kinds = source_kinds_of(str(field.get("type") or ""))
out: list[dict] = []
for item in raw:
if not isinstance(item, dict):
continue
kind = route_source_of(item)
if kind not in kinds:
continue
route: dict = {"source": kind}
when = item.get("when")
if isinstance(when, dict) and when:
route["when"] = when
for key in ROUTE_OWNED_KEYS[kind]:
value = item.get(key)
if value is None or value == "" or value == [] or value == {}:
continue
route[key] = value
note = str(item.get(ROUTE_NOTE_KEY) or "").strip()
if note:
route[ROUTE_NOTE_KEY] = note
mapping = item.get("optionMap")
if isinstance(mapping, dict) and mapping:
route["optionMap"] = mapping
# 这一条自带的带出:挂在来源那一维之外,但它与「这一条问哪一家」是同一次决定
fill = clean_fill(item.get(ROUTE_FILL_KEY))
if fill:
route[ROUTE_FILL_KEY] = fill
out.append(route)
return out[:MAX_OPTION_ROUTES]
def matched_route(field: dict, data: dict | None) -> dict | None:
"""自上而下第一条成立的路由;一条都不成立回 ``None``(= 用字段自己那份配置)。
没写条件的那一条恒成立,所以它天生就是「其余情况」那一档:放最后才对,放最前的话
下面几条永远轮不上(设计器里那句提示说的就是这件事)。
"""
for route in routes_of(field):
if condition_ok(route.get("when"), data or {}):
return route
return None
def route_view(field: dict, route: dict) -> dict:
"""按**指定那一条**路由把字段摊成一张视图(设计器逐条检查用它,不必造假数据)。"""
kind = route_source_of(route)
if kind not in source_kinds_of(str(field.get("type") or "")):
return field
view = dict(field)
for key in _ALL_ROUTE_KEYS:
view.pop(key, None)
view["optionSource"] = kind
for key in ROUTE_OWNED_KEYS[kind]:
if key in route:
view[key] = route[key]
if isinstance(route.get("optionMap"), dict) and route.get("optionMap"):
view["optionMap"] = route["optionMap"]
return view
def option_view(field: dict, data: dict | None) -> dict:
"""这一格**此刻**按哪一套候选来源工作:命中路由给一份换过来源的视图,否则给字段本身。
视图只动来源那一维(外带每一条自己那份「显示哪一列、存哪一列」);挑选方式、能不能选好几个、
关联带出这些与来源无关的格子原样留着。返回的是新字典,不改调用方传进来的那一份。
"""
route = matched_route(field, data)
return route_view(field, route) if route else field
def text_map(value: object) -> dict:
"""「名字 -> 值」那张表的洗法:非字典当没配,键或值为空的那一行丢掉。
配到一半的一行不该存下来吓下一任配表的人,运行时也没法拿一个空目标格子去写值。
"""
if not isinstance(value, dict):
return {}
return {str(name).strip(): str(item).strip()
for name, item in value.items() if str(name).strip() and str(item).strip()}
def clean_fill(value: object) -> dict | None:
"""一条候选路由自带的那份带出(``fill``),洗成能存下来的样子。
只留 ``args`` / ``picks`` / ``extras`` 那三张表(与 ``binding.entries`` 归一出来的那三个键
同一份);三张都空回 ``None``——留一个空对象只会让下一任配的人以为这一条配过什么。
"""
if not isinstance(value, dict):
return None
out: dict = {}
code = str(value.get("source") or "").strip()
if code:
out["source"] = code
for key in ROUTE_FILL_TABLES:
rows = text_map(value.get(key))
if rows:
out[key] = rows
return out or None
def route_fill_entry(route: dict) -> dict | None:
"""这一条候选路由自带的带出,摊成**一条取数条目**:源、条件、入参都跟着这一条走。
只有外部数据源那一条说得上"带出别的列"(字典那一家的带出走 ``autoFill``,流程单据那一家
走 ``linkFill``,那两条读的是对方给的那一份,不需要再挂一层)。没自带、或那一条还没选源,
回 ``None``——没有源就没有可带出的列。入参没另写时沿用这一条筛候选用的那一份,
省得配的人把同一组参数写两遍。
"""
if route_source_of(route) != SOURCE_DATA_SOURCE:
return None
fill = clean_fill(route.get(ROUTE_FILL_KEY))
if not fill:
return None
# 带出默认问的就是这一条那一家;另填了 source 才另问一家(「候选问 A 家的清单、
# 带出的那几列在 B 家」是真有的配法,不值得为它再摆一条候选路由)
code = str(fill.get("source") or route.get("dataSourceCode") or "").strip()
if not code:
return None
args = fill.get("args") or text_map(route.get("dataSourceArgs"))
entry: dict = {"source": code, "args": args, "picks": fill.get("picks") or {},
"extras": fill.get("extras") or {}}
when = clean_condition(route.get("when"))
if when:
entry["when"] = when
return entry
def route_fill(field: dict, data: dict | None) -> dict | None:
"""这一格**此刻**那一条候选路由自带的带出(没命中或那条没自带时回 ``None``)。"""
route = matched_route(field, data)
return route_fill_entry(route) if route else None
def has_route_fill(field: dict) -> bool:
"""这一格**有没有可能**自带带出(不看此刻命中哪一条)。
「这一格配了取数吗」那一类清单判断要用这一句,不能用 :func:`route_fill`:值还没填进表单时
一条都不命中,可这一格确实会往别的格子里写值。漏了它,依赖图、留痕、试跑都会少算一格
(对面是前端 ``optionSource.hasRouteFill``)。
"""
return any(clean_fill(route.get(ROUTE_FILL_KEY)) for route in routes_of(field))
#: 字典带出挂在哪个键上(「选了字典项 → 把那一项的某一列写进别的格子」)
AUTO_FILL_KEY = "autoFill"
def dict_route_codes(field: dict) -> list[str]:
"""候选路由里那几条**字典来源**各挂的是哪一本(自上而下、去重)。
两处要用它:保存那一刻判这一格上的 ``autoFill`` 还算不算数(字段自己没挂字典、
但某一条候选挂的是字典,那份带出就不是上一家的残骸),以及设计期那句「这一档不起作用」。
对面是前端 ``optionSource.dictRouteCodesOf``。
"""
out: list[str] = []
for route in routes_of(field):
if route_source_of(route) != SOURCE_DICT:
continue
code = str(route.get("dictCode") or "").strip()
if code and code not in out:
out.append(code)
return out
def clean_condition(condition: object) -> dict | None:
"""结构化条件洗一遍:只留形状对得上的规则,一条都不剩回 ``None``。
与 :func:`condition_ok` 读的是同一份形状,判据也同一份(认不出的比较符丢掉而不是报错——
一条永远不成立的规则比一个存不下来的表单好)。
"""
if isinstance(condition, list):
condition = {"match": "all", "rules": condition}
if not isinstance(condition, dict):
return None
rules = condition.get("rules")
if not isinstance(rules, list):
return None
kept = [
dict(rule)
for rule in rules
if isinstance(rule, dict)
and str(rule.get("field") or "").strip()
and str(rule.get("op") or "").strip() in CONDITION_OPS
]
if not kept:
return None
match = str(condition.get("match") or "all").lower()
return {"match": "any" if match == "any" else "all", "rules": kept}
def clean_routes(field: dict) -> list[dict] | None:
"""把字段上的条件路由清单洗成能存下来的样子(设计器保存与接口直传共用这一句)。
认不出的来源、配到一半的空条目、多出来的第 9 条都丢掉;每条只留**属于它那一种来源**的那几格
——和字段级那份 ``clean_option_source`` 同一个道理:从字典换成数据源之后还留着 ``dictCode``,
读的人就分不清这一条到底问谁要候选。「显示 / 存值」那两列也一样:不是这一来源给得出的列、
或跟默认一模一样的,都不留。
一条都不剩回 ``None``——留一份空数组只会让下一任配的人以为这一格配过什么。
"""
out: list[dict] = []
for route in routes_of(field):
kind = route_source_of(route)
row: dict = {"source": kind}
when = clean_condition(route.get("when"))
if when:
row["when"] = when
for key in ROUTE_OWNED_KEYS[kind]:
value = route.get(key)
if value is None:
continue
if key == "relationStatuses":
tokens = tuple(item for item in RELATION_STATUSES if item in {str(one).strip() for one in value})
# 全勾与没勾是同一件事(等于不限),不留这份冗余
if tokens and len(tokens) < len(RELATION_STATUSES):
row[key] = list(tokens)
continue
row[key] = value
mapping = route.get("optionMap")
if isinstance(mapping, dict):
value_key = allowed_map_key(kind, mapping.get("valueKey"), DEFAULT_VALUE_KEYS[kind])
label_key = allowed_map_key(kind, mapping.get("labelKey"), DEFAULT_LABEL_KEYS[kind])
if value_key != DEFAULT_VALUE_KEYS[kind] or label_key != DEFAULT_LABEL_KEYS[kind]:
row["optionMap"] = {"valueKey": value_key, "labelKey": label_key}
if kind == SOURCE_DATA_SOURCE:
# 带出挂在这一条上:换一家就换一份「哪几列写进哪几格」,条件不用再写第二遍
fill = clean_fill(route.get(ROUTE_FILL_KEY))
if fill:
row[ROUTE_FILL_KEY] = fill
note = str(route.get(ROUTE_NOTE_KEY) or "").strip()
if note:
row[ROUTE_NOTE_KEY] = note
out.append(row)
return out or None
def route_problems(field: dict) -> list[str]:
"""设计期检查:清单本身配得对不对(前端镜像 ``optionRouteProblems``,措辞两边同一句)。
只在保存那一刻说。填单的人不该是第一个发现「这一格永远走不到第二条」那个人。
「触发条件引用了不存在的字段」不在这里说——路由的上游已经并进
:func:`condition_dependencies`,由 ``formruntime.linkage_problems`` 一处说,
免得同一条错在面板里冒两遍。
"""
raw = field.get(OPTION_ROUTES_KEY)
if raw is None:
return []
label = str(field.get("label") or field.get("key") or "")
if not isinstance(raw, list):
return [f"「{label}」的候选来源清单要写成一份列表"]
problems: list[str] = []
if len(raw) > MAX_OPTION_ROUTES:
problems.append(f"「{label}」的候选来源最多 {MAX_OPTION_ROUTES} 条,多出来的不会被用上")
kinds = source_kinds_of(str(field.get("type") or ""))
for index, item in enumerate(raw, start=1):
at = f"「{label}」的第 {index} 条候选来源"
if not isinstance(item, dict):
problems.append(f"{at}配置格式不对")
continue
kind = route_source_of(item)
if kind not in kinds:
# 空着的那一条多半是「加了还没配完」,说轻一点
problems.append(f"{at}还没选来源" if not kind else f"{at}的来源这类字段挑不了:{kind}")
continue
if kind == SOURCE_DICT and not str(item.get("dictCode") or "").strip():
problems.append(f"{at}还没选要用的数据字典")
if kind == SOURCE_DATA_SOURCE and not str(item.get("dataSourceCode") or "").strip():
problems.append(f"{at}还没选要用哪一张外部数据源")
if kind == SOURCE_MANUAL and not (item.get("options") or []):
problems.append(f"{at}一条选项都没填,选到它就是一只空下拉")
if kind == SOURCE_PROCESS:
problems.extend(f"{at}:{text}" for text in relation_status_problems(item))
when = item.get("when")
if when not in (None, "", {}, []):
if not isinstance(when, dict):
problems.append(f"{at}的触发条件配置格式不对")
continue
for rule in when.get("rules") or []:
if not isinstance(rule, dict):
problems.append(f"{at}的触发条件里有认不出的写法")
continue
op = str(rule.get("op") or "")
if op and op not in CONDITION_OPS:
problems.append(f"{at}的触发条件里有不支持的比较符:{op}")
mapping = item.get("optionMap")
if mapping not in (None, "", {}, []):
if not isinstance(mapping, dict):
problems.append(f"{at}的「显示 / 存值」配置格式不对")
continue
for raw_key, name, fallback in (
("valueKey", "存的值", DEFAULT_VALUE_KEYS.get(kind, "value")),
("labelKey", "显示的文字", DEFAULT_LABEL_KEYS.get(kind, "label")),
):
text = str(mapping.get(raw_key) or "").strip()
if text and allowed_map_key(kind, text, fallback) != text:
problems.append(f"{at}的{name}「{text}」不是这一来源能给出的列")
return problems
#: 字典选项在共享缓存(Redis)里的默认存活秒数,配置项 ``redis_dict_cache_seconds``。
#: 字典是"渲染每张表单都要、一年改不了两次"的典型,所以值得共享一份。
@ -827,9 +1333,22 @@ def used_by_forms(db: Session, code: str) -> list[str]:
def _codes_in(content: object) -> set[str]:
out: set[str] = set()
for field in _walk_fields(content):
code = str(field.get("dictCode") or "").strip()
if code:
out.add(code)
out.update(_field_dict_codes(field))
return out
def _field_dict_codes(field: dict) -> list[str]:
"""这一格(含它的条件路由清单)会读到哪几本字典。
删字典前的「哪些表单在用」、预取清单、级联检查都得把路由里那几本也算进来——
只认字段上那一份 ``dictCode`` 的话,一把只挂在路由里的字典能被删掉,
而那一格命中这条路由时就成了一只空下拉。
"""
out: list[str] = []
for row in [field, *routes_of(field)]:
code = str(row.get("dictCode") or "").strip()
if code and code not in out:
out.append(code)
return out
@ -932,9 +1451,9 @@ class DictCache:
def codes_of(fields: Iterable[dict]) -> list[str]:
out: list[str] = []
for field in _walk_fields_list(fields):
code = str(field.get("dictCode") or "").strip()
if code and code not in out:
out.append(code)
for code in _field_dict_codes(field):
if code not in out:
out.append(code)
return out
@ -1232,6 +1751,9 @@ def effective_options(field: dict, data: dict, cache: DictCache) -> list[dict] |
候选来自流程单据或外部数据源的格子一律回 ``None``:那两类的候选是**搜出来的**,
服务端手上没有全量清单,据此判越界会把人正常选中的单据与物料当成非法值拦下提交。
"""
# 先看这一格**此刻**用的是哪一套候选来源(条件路由,见 :func:`option_view`):
# 命中哪一条,下面所有口径就按那一条算
field = option_view(field, data)
if not constrains_values(field):
return None
code = str(field.get("dictCode") or "").strip()
@ -1282,6 +1804,15 @@ def condition_ok(condition: object, data: dict) -> bool:
return any(checks) if match == "any" else all(checks)
def _is_empty(value: object) -> bool:
"""填没填。``0`` 与 ``False`` 都算填了,只有一串空格、空集合、``None`` 算没填。
与前端 ``formLinkage.isEmptyValue`` 同一份口径:判空类比较符与「右边那一格还没填」
那条判断都读它,两头各自写一遍迟早分叉。
"""
return value in (None, "", [], {}, ()) or (isinstance(value, str) and not value.strip())
#: 前端 JS 的写法是唯一口径:布尔值一律小写比,见 :func:`_text`。
def _text(value: object, other: object = None) -> str:
"""按 JS 的写法把值折成字符串再比。
@ -1298,10 +1829,42 @@ def _text(value: object, other: object = None) -> str:
#: 日期控件存下来的那种写法(``2026-03`` / ``2026-04-02`` / ``2026-04-02T14:30`` / ``14:30``),
#: 与前端 ``formLinkage.ISO_LIKE`` 同一份。
ISO_LIKE = re.compile(r"^\d{4}-\d{2}(-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?)?)?$")
CLOCK_LIKE = re.compile(r"^\d{2}:\d{2}(:\d{2}(\.\d+)?)?$")
def _time_text(value: object) -> str | None:
"""这一个值是不是「能直接按字面比的时间」;不是回 ``None``。"""
text = "" if value is None else str(value).strip()
return text if ISO_LIKE.match(text) or CLOCK_LIKE.match(text) else None
def _order_compare(left: object, op: str, right: object) -> bool:
"""比大小:能折成数就按数比,否则得两头都是 ISO 时间串,再不比不出结果。
这一档以前只有 ``float()`` 一条路,日期串一律换算失败直接回 ``False``,于是
「离职日期 晚于 …」这种界面上明明给得出来的条件**永远不成立**。认得出 ISO 就按字面比:
定宽零填充的串,字典序就是时间序,跟前端 ``formLinkage.orderCompare`` 一个结果。
"""
try:
numbers = (float(str(left if left != "" else 0)), float(str(right if right != "" else 0)))
except (TypeError, ValueError):
numbers = None
if numbers is not None:
a, b = numbers
return {"gt": a > b, "ge": a >= b, "lt": a < b, "le": a <= b}[op]
x, y = _time_text(left), _time_text(right)
if x is None or y is None:
return False
return {"gt": x > y, "ge": x >= y, "lt": x < y, "le": x <= y}[op]
def compare(left: object, op: str, right: object) -> bool:
"""一个条件怎么算真伪。公开出去给阈值这类配置复用,别再各写一套 ops。"""
if op in ("empty", "notEmpty"):
empty = left in (None, "", [], {}, ()) or (isinstance(left, str) and not left.strip())
empty = _is_empty(left)
return empty if op == "empty" else not empty
if op in ("in", "nin"):
wanted = right if isinstance(right, (list, tuple, set)) else [item.strip() for item in str(right or "").split(",")]
@ -1311,24 +1874,33 @@ def compare(left: object, op: str, right: object) -> bool:
if op == "contains":
return _text(right, left) in _text(left, right)
if op in ("gt", "ge", "lt", "le"):
try:
a, b = float(str(left if left != "" else 0)), float(str(right if right != "" else 0))
except (TypeError, ValueError):
return False
return {"gt": a > b, "ge": a >= b, "lt": a < b, "le": a <= b}[op]
return _order_compare(left, op, right)
if op == "ne":
return _text(left, right) != _text(right, left)
return _text(left, right) == _text(right, left)
def _rule_ok(rule: dict, data: dict) -> bool:
"""一条规则:左边永远是点名的那一格,右边看 ``valueField`` 走另一格、否则用写死的 ``value``。
右边挑的是另一格时,**那一格还没填这一条就不成立**。两个都空着的时候
``compare("", "eq", "")`` 是成立的,「结束日期晚于开始日期」于是在单据刚打开时就满足,
格子莫名其妙地露出来;判空类(:data:`VALUELESS_OPS`)问的是左边那一格自己,不受这条管。
与前端 ``utils/formLinkage.rightOperand`` 一字不差,两边必须算出同一个结果。
"""
key = str(rule.get("field") or "")
if not key:
return True
op = str(rule.get("op") or "eq")
if op not in CONDITION_OPS:
return True
return compare((data or {}).get(key), op, rule.get("value"))
right = rule.get("value")
ref = str(rule.get("valueField") or "").strip()
if ref and op not in VALUELESS_OPS:
right = (data or {}).get(ref)
if _is_empty(right):
return False
return compare((data or {}).get(key), op, right)
def _push(keys: list[str], value: object) -> None:
@ -1340,7 +1912,12 @@ def _push(keys: list[str], value: object) -> None:
def condition_dependencies(field: dict) -> list[str]:
"""级联上级与显隐 / 必填 / 只读条件声明的上游。
这类引用指向自己就是配错了:字段显不显示不能由它自己的当前值决定。
引用**指向自己是正常写法**(2026-11 起):「带回来才显示」那一类条件判的就是这一格
自己的值。级联上级选到自己仍然算配错(候选得由另一格来筛),:func:`depends_on` 也照旧
把自指摘掉——「上级变了清空下级失效值」那条链不能把自己绕进去。
条件里**右边那一个字段**(``valueField``)同样算上游:它一改,这一条的成立与否就可能
翻面。漏了它,运行时「上游变了清下级失效值」与设计期那句「引用了不存在的字段」都会漏判。
"""
keys: list[str] = []
_push(keys, field.get("cascadeFrom"))
@ -1349,11 +1926,17 @@ def condition_dependencies(field: dict) -> list[str]:
conditions.extend(
option.get("when") for option in field["options"] if isinstance(option, dict)
)
# 候选来源的条件路由:驱动那一格一改,这一格的候选就该换一家、失效值也该清。
# 漏了它,界面会拿着上一家的候选清单继续判越界(路由清单里的级联上级同理)。
for route in routes_of(field):
_push(keys, route.get("cascadeFrom"))
conditions.append(route.get("when"))
for condition in conditions:
if isinstance(condition, dict):
for rule in condition.get("rules") or []:
if isinstance(rule, dict):
_push(keys, rule.get("field"))
_push(keys, rule.get("valueField"))
return keys
@ -1384,11 +1967,68 @@ def raw_dependencies(field: dict) -> list[str]:
def depends_on(field: dict) -> list[str]:
"""本字段的取值受哪些上游字段影响,用于「上级变了清空失效的下级值」。"""
"""本字段的取值受哪些上游字段影响,用于「上级变了清空失效的下级值」。
自指在这里一律摘掉:条件读自己是正常用法,但「自己变了要清自己的失效值」不是——
清值那一圈会把刚写进来的那一份当成越界抹掉。
"""
key = str(field.get("key") or "")
return [item for item in raw_dependencies(field) if item != key]
def is_self_rule(rule: object, key: str) -> bool:
"""这一条读的是不是「本字段自己那一格」:左边点名自己,或右边挑的那一格是自己。
两种写法都让这一格露不露、要不要填、锁不锁有一部分由它自己的值决定。
与前端 ``utils/formLinkage.isSelfRule`` 同一句。
"""
own = str(key or "").strip()
if not own or not isinstance(rule, dict):
return False
return str(rule.get("field") or "").strip() == own or str(rule.get("valueField") or "").strip() == own
def without_self_rules(condition: object, key: str) -> "dict | None":
"""把条件里读自己那几条摘掉;一条都没摘动就回 ``None``(意思是「原本没读自己」)。
全摘光时回的是 ``{"match": ..., "rules": []}``——``condition_ok`` 认「没规则就恒为真」,
跟「没配条件」是同一个结果。与前端 ``utils/formLinkage.withoutSelfRules`` 同一句。
"""
if not isinstance(condition, dict):
return None
rules = condition.get("rules")
if not isinstance(rules, list):
return None
kept = [rule for rule in rules if not is_self_rule(rule, key)]
if len(kept) == len(rules):
return None
return {"match": condition.get("match") or "all", "rules": kept}
#: 三栏联动条件挂在字段上的哪几个键。
CONDITION_KEYS = ("visibleWhen", "requiredWhen", "readonlyWhen")
def stripped_of_self(field: dict) -> "dict | None":
"""这一格摘掉「读自己那几条」以后的样子;没读过自己回 ``None``。
三栏一起摘:提交那一路要问的是「挡着这一笔值的到底只有它自己那一句吗」,只摘显隐
那一栏会漏掉「有值就锁住」那种——人刚把银行账号敲完,那一格就按自己的值把自己锁了,
再按「这一环改不动」退回原值,等于把人写的抹掉。前端镜像在
``utils/formRuntime.writableIgnoringSelf``;收值那一句在
``service/formruntime.self_gated_keys``。
"""
key = str(field.get("key") or "")
patch = {}
for name in CONDITION_KEYS:
rest = without_self_rules(field.get(name), key)
if rest is not None:
patch[name] = rest
if not patch:
return None
return {**field, **patch}
def visible(field: dict, data: dict) -> bool:
return condition_ok(field.get("visibleWhen"), data)
@ -1469,10 +2109,18 @@ def apply_auto_fill(fields: Iterable[dict], data: dict, cache: DictCache) -> lis
for _round in range(AUTO_FILL_ROUNDS):
changed = False
for field in rows:
rules = field.get("autoFill")
# 带出读的是**此刻那一条候选来源**的字典(条件路由命中哪条就带哪一本的 extra)
field = option_view(field, data)
rules = field.get(AUTO_FILL_KEY)
if not isinstance(rules, list) or not rules:
continue
code = str(field.get("dictCode") or "").strip()
if not code and routes_of(field):
# 挂了候选路由,而**此刻命中的那一条不是字典**(多半是外部数据源那一条):
# 这一头一个字都不带——那一条要往别的格子上写东西,走它自己那份 ``fill``。
# 下面那句「没有字典就把这一格自己的值搬过去」在这儿会把人刚挑的编码
# 盖到「名称」那一格上(对面前端 items 为空,本来也什么都不写)。
continue
source_key = str(field.get("key") or "")
for rule in rules:
if not isinstance(rule, dict):
@ -1539,12 +2187,19 @@ def _item_by_stored(field: dict, index: dict[str, dict], stored: str) -> dict |
return direct if direct is not None else find_item(index, stored)
def option_labels(field: dict, value: object, cache: DictCache, sep: str = "、") -> str:
def option_labels(
field: dict, value: object, cache: DictCache, sep: str = "、", data: dict | None = None
) -> str:
"""把存着的值翻成看得懂的名字,日志、标题和只读态都用它。
翻的是这一格自己那两列:配过「显示 / 存值」的字段,存的是哪一列就按哪一列找回来,
显示按它配的那一列写;认不出的值原样念,别编一个名字出来。
挂了条件路由的格子把 ``data`` 带上:同一格这一单用的是差标字典、那一单用的是费用科目,
翻名字得按**那一单当时命中的那一条**去翻。没带就当没配路由(老调用方一个不用改)。
"""
if data is not None:
field = option_view(field, data)
code = str(field.get("dictCode") or "").strip()
values = _values(value)
if not values:

View File

@ -121,11 +121,16 @@ def envelope(work, event: str, *, activity_name: str = "", actor_name: str = "",
def emit(db: Session, work, event: str, *, activity_name: str = "", actor_name: str = "",
extra: dict | None = None) -> int:
extra: dict | None = None, task: str = "") -> int:
"""把一次业务变化推给所有订阅了它的人。返回入队条数;没有订阅就返回 0。
**与调用方的状态变更同一事务**,别在这里 commit。也不在这里抛异常:
一次入队失败最多让对方晚点收到通知,不该把审批人的"同意"按钮变红。
``task`` 是这条事件说的是**哪一条待办**(待办号,或加签那类多条时的写法)。
给了它,幂等键就不再按环节名去重:同一个环节可以走两趟(退回重走、管理员改道
又改回来),只按环节名认的话第二趟会被吞掉,订阅方于是攥着一条已经废掉的待办号
反复去表态。判据 ``scripts/check_intervention_move.py`` B11 钉的就是这一条。
"""
rows = subscriptions(db, event, getattr(work, "process", "") or "")
if not rows:
@ -133,7 +138,8 @@ def emit(db: Session, work, event: str, *, activity_name: str = "", actor_name:
job = getattr(work, "job", "") or ""
added = 0
for hook in rows:
idem = f"{hook.code}:{event}:{job}:{activity_name}"
# 有待办号就按号认(号本身指得清是哪一环哪一条),没有才退回按环节名认
idem = f"{hook.code}:{event}:{job}:{task or activity_name}"[:191]
clash = db.execute(
select(models.OpenEvent.id).where(models.OpenEvent.idem == idem)
).first()

View File

@ -94,12 +94,22 @@ def scalar_text(value: object) -> str:
def cell_text(
field: dict, value: object, cache: dicts_service.DictCache, jobs: dict[str, str] | None = None
field: dict,
value: object,
cache: dicts_service.DictCache,
jobs: dict[str, str] | None = None,
data: dict | None = None,
) -> str:
"""单个表单字段落地成什么文本:选项翻标签,明细表压一行,附件只留文件名。"""
kind = str(field.get("type") or "")
"""单个表单字段落地成什么文本:选项翻标签,明细表压一行,附件只留文件名。
带上这一单的值(``data``)时,挂了候选路由的格子先换成**这一单命中的那一条**再翻名字,
与界面渲染、提交把关同一个口径;不给就按字段自己那一份,老调用方一个都不用改。
"""
if value is None or (isinstance(value, str) and not value.strip()):
return ""
if data is not None:
field = dicts_service.option_view(field, data)
kind = str(field.get("type") or "")
if kind == "signature":
# 签名是几十 KB 的 base64,导进表格既打不开也没意义,只留"签没签"这个事实。
return "已签名" if str(value).strip() else ""
@ -169,7 +179,8 @@ def table_text(
if columns:
for column in columns:
key = str(column.get("key") or "")
text = cell_text(column, row.get(key), cache, jobs)
# 列上的路由读的是同一行里别的列(与桌面 FormRenderer 那一格同一个口径)
text = cell_text(column, row.get(key), cache, jobs, data=row)
if text:
pieces.append(f"{column.get('label') or key}={text}")
else:

View File

@ -53,6 +53,8 @@ logger = logging.getLogger(__name__)
#: 字段上挂外部取数配置的属性名
FIELD_PROP = "fetch"
#: 明细表那一类字段:列上也能挂 ``fetch``,执行时逐行各跑一次(见 :func:`row_fetch_fields`)
TABLE_TYPE = "table"
#: 取数时机里「发起之后冻结」那一档的键名(字段上配 ``fetch.freezeAfterStart``)
FREEZE_AFTER_START = "freezeAfterStart"
#: 开始环节的环节类型,与 ``engine.definition.ACTIVITY_BEGIN`` 同一个字面量;
@ -1394,9 +1396,18 @@ def used_by_forms(db: Session, code: str) -> list[str]:
).all()
for form_id, name, content in rows:
for field_def in _walk_fields(content):
# 候选来源=外部数据源那两格都算:字段上那一份(兜底),以及条件路由里每一条挂的源
codes = {str(field_def.get("dataSourceCode") or "").strip()}
routes = field_def.get("optionRoutes")
if isinstance(routes, list):
codes.update(
str(item.get("dataSourceCode") or "").strip()
for item in routes
if isinstance(item, dict)
)
referenced = any(
entry["source"] == want for entry in binding.entries(field_def.get(FIELD_PROP))
) or str(field_def.get("dataSourceCode") or "").strip() == want
) or want in codes
if referenced:
hits.append(name or form_id)
break
@ -1416,23 +1427,129 @@ def _walk_fields(content: object) -> list[dict]:
# ---------------------------------------------------------------------------
def fetch_fields(fields: Iterable[dict] | None) -> list[tuple[dict, dict]]:
"""挑出配了 ``fetch`` 的字段,返回 (字段定义, 取数配置)。"""
def fetch_fields(fields: Iterable[dict] | None, data: dict | None = None) -> list[tuple[dict, dict]]:
"""挑出配了 ``fetch`` 的**主表字段**,返回 (字段定义, 取数配置)。
给了 ``data`` 就按**这一单此刻**那一份配置挑(候选路由自带的带出也算配了取数);
不给就只看字段上那一份 ``fetch``——设计期那份清单本来就不依赖取值。
明细表那一格不在这份清单里:列上那份 ``fetch`` 是逐行跑的,问的是
:func:`row_fetch_fields`。这一句只回主表,老调用方(试跑、留痕、权限判断)
不用先自己滤掉 ``table``。
"""
out: list[tuple[dict, dict]] = []
for item in fields or []:
if str(item.get("type") or "") == "table":
if str(item.get("type") or "") == TABLE_TYPE:
continue
cfg = item.get(FIELD_PROP)
cfg = config_of(item, data)
if isinstance(cfg, dict) and field_sources(cfg):
out.append((item, cfg))
return out
def table_columns(table: dict) -> list[dict]:
"""明细表配了哪几列(与 ``formruntime.columns_of`` 同一份读法,这里不模块级 import 服务层)。"""
raw = table.get("columns")
return [item for item in raw if isinstance(item, dict)] if isinstance(raw, list) else []
def row_fetch_fields(fields: Iterable[dict] | None, data: dict | None = None) -> list[tuple[dict, dict, dict]]:
"""明细表里配了 ``fetch`` 的那些列,返回 (表定义, 列定义, 取数配置)。
列上那份 ``fetch`` 与主表字段那一份是**同一个形状、同一个执行器**(``binding.entries``
那一套多源 / 入参 / 带出 / 失败策略),只差两件事,这两件事正是明细行与主表那一格的
分界:
* **入参读这一行**:作用域是「整张单 + 这一行」,与主表字段同名的列以本行为准——
跟「本行公式」吃的是同一份作用域(``formRuntime.applyRowFormulas``),配的人不用
再记第二套写法;``{form.x}`` 引用的既可以是本行的列,也可以是主表字段。
* **带出只落在这张表**:一行生一格,把 ``picks`` 写进主表等于让最后一行说了算,
所以带出去向只认这张明细表的其它列。
"""
out: list[tuple[dict, dict, dict]] = []
for item in fields or []:
if str(item.get("type") or "") != TABLE_TYPE:
continue
for column in table_columns(item):
cfg = config_of(column, data)
if isinstance(cfg, dict) and field_sources(cfg):
out.append((item, column, cfg))
return out
def field_sources(cfg: dict) -> list[dict]:
"""这一格要调的数据源清单;形状与归一规则在 ``service/binding.entries``。"""
return binding.entries(cfg)
#: 这一份取数**只写带出去向**、不动这一格自己那一个值(由 :func:`fill_config` 合成时打上,
#: 不落到存下来的表单定义里)。
FILL_ONLY_KEY = "fillOnly"
def _linkage():
"""候选来源那一层(延迟导入:``dicts`` 反过来也读这一层的取值写法)。"""
from . import dicts as _dicts
return _dicts
def fill_config(field: dict, data: dict | None) -> dict | None:
"""把**此刻命中的那一条候选路由**自带的带出(``route.fill``)摊成一份取数配置。
源与条件都从那一条来(``dataSourceCode`` / ``when``),入参没另写时沿用那一条筛候选用的
入参;打上 :data:`FILL_ONLY_KEY`,于是它只往「带出去向」那几格写。失败策略、发起后冻结、
多久算旧这三档沿用字段上那一份 ``fetch``——它们问的是「这一格怎么待人」,跟从哪家取数无关。
没命中、命中的那条没自带带出,一律回 ``None``(= 这一格还是按字段上那一份 ``fetch`` 跑,
老表单一个字不变)。对面是前端 ``utils/formFetch.fetchConfigOf``。
"""
linkage = _linkage()
route = linkage.matched_route(field, data)
entry = linkage.route_fill_entry(route) if route else None
if not entry:
return None
cfg: dict = {**entry, FILL_ONLY_KEY: True}
own = field.get(FIELD_PROP)
if isinstance(own, dict):
for key in ("onError", "freezeAfterStart", "revalidateAfter", "separator"):
if own.get(key) not in (None, ""):
cfg[key] = own[key]
return cfg if field_sources(cfg) else None
def config_of(field: dict, data: dict | None = None) -> dict | None:
"""这一格**此刻**那份取数配置:命中那条自带带出就用它摊出来的那份,否则用字段上那一份。
与候选来源那份回落同一个分寸:一条都不命中、或命中的那条没自带带出,读的就是
``field["fetch"]``(改动前行为)。
"""
return fill_config(field, data) or field.get(FIELD_PROP)
def has_fetch(field: dict) -> bool:
"""这一格到底会不会往外写值:字段自己配了 ``fetch``,或某一条候选路由自带了带出。
清单与依赖图这类「有没有配」的判断要用这一句(不看此刻的取值);真正跑哪一份问
:func:`config_of`。
"""
cfg = field.get(FIELD_PROP)
if isinstance(cfg, dict) and field_sources(cfg):
return True
linkage = _linkage()
return any(linkage.route_fill_entry(route) for route in linkage.routes_of(field))
def active_field_sources(cfg: dict, scope: dict | None) -> list[dict]:
"""这一格**此刻**要调的那几张源:条目上配了触发条件的,只留成立的那几条。
「费用类型 = 差旅才问差标接口」就靠这一句生效。设计期检查(``problems``)看的是全量清单
——源在不在、入参引用掉没掉在地上,跟此刻的取值无关;运行时才按 ``scope`` 筛。
判据与联动条件同一份(``service/dicts.condition_ok``),不会界面上调了、提交时没调。
"""
return binding.active_entries(cfg, scope)
def applies_at(cfg: dict | None, activity=None) -> bool:
"""这一格现在还可以取数吗(``fetch.freezeAfterStart`` 那一档)。
@ -1503,10 +1620,11 @@ def apply_form(
**取数照旧发起**,条件分支与下一环节读的还是新数。没给 ``perms`` 时按露着算。
"""
rows = [item for item in (fields or []) if isinstance(item, dict)]
entries = fetch_fields(rows)
if not entries:
entries = fetch_fields(rows, data)
# 明细行那一趟也算在内:只给明细列配了取数的表单,主表这一趟是空的,不能提前返回
row_targets = row_fetch_fields(rows, data)
if not entries and not row_targets:
return
from . import formruntime # 局部导入:这一层是取数内核,不模块级拽服务层(与 quota 同一处理)
# 带出去向只能写进这一份字段清单里真存在的格子:格子删了而带出还留着的老配置,
# 键名(field_text_2 这种)日后很容易被新字段复用,悄悄盖上去比少写一格危险。
@ -1519,89 +1637,214 @@ def apply_form(
# 都留在发起那一刻取回来的值上(连留痕一起留住,不抹掉来路)
if not applies_at(cfg, activity):
continue
policy = str(cfg.get("onError") or "keep").strip()
if policy == "block" and formruntime.field_hidden(field_def, perms, data):
# 这一格在本环节没露脸:取不到也不当场拦人,值留在原来那一份上,只留一句日志
policy = "keep"
logger.info("外部取数失败但这一环不挡提交:%s 这一格在当前环节没显示", label)
merge = str(cfg.get("merge") or "first").strip()
separator = str(cfg.get("separator") or "、")
values: list[Any] = []
failures: list[str] = []
called: list[dict] = []
for entry in field_sources(cfg):
code = str(entry.get("source") or "")
row = get_source(db, code)
if row is None or not row.enabled:
failures.append(f"{code}:未配置或已停用")
continue
args = resolve_args(db, entry, data, work, actor)
result = run(db, row, args, actor=actor, work=work, activity=activity,
pick=str(entry.get("pick") or ""), extras=_entry_extras(entry))
if not result.ok:
failures.append(f"{row.name}:{result.error}")
continue
values.append(result.value)
for source_key, target in entry["picks"].items():
target_key = binding.live_target(target, keys)
if not target_key:
if str(target or "").strip():
logger.warning("字段 %s 的带出指向表单里已经没有的格子 %s,这一笔没写",
key, target)
continue
value = result.extras.get(str(source_key)) if str(source_key) in (result.extras or {}) else None
if value is None and str(source_key) == "value":
value = result.value
data[target_key] = value
called.append({"source": code, "args": args, "cached": result.cached,
"at": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
# 这一格自己指定了取哪一列时留一笔,事后看留痕才知道读的是哪条路径
**({"pick": str(entry.get("pick"))} if str(entry.get("pick") or "").strip() else {})})
if not called:
if failures and policy == "block":
raise _engine_error()(f"「{label}」的外部数据取不到:{';'.join(failures)}")
if failures and policy == "zero":
data[key] = 0 if str(field_def.get("type") or "") in MONEY_TYPES else ""
continue
# 少调成一个源,这格的值就是残缺的。只有 first 那档本来就允许"轮到谁算谁",
# 其余(相加 / 取最小…)凑不齐就当这次取数失败,按 onError 处理,
# 免得把「三个系统的余额之和」悄悄写成一个少了某一家的数。
if failures and merge != "first":
if policy == "block":
raise _engine_error()(f"「{label}」的外部数据只取到一部分:{';'.join(failures)}")
if policy == "zero":
data[key] = 0 if str(field_def.get("type") or "") in MONEY_TYPES else ""
continue
merged = merge_values(merge, values, separator=separator)
if merged is None:
continue
data[key] = coerce(str(field_def.get("type") or ""), merged)
first = called[0]
trace[key] = {"source": first["source"], "args": first["args"], "cached": first["cached"],
"at": first["at"], "merge": merge if len(called) > 1 else "",
"sources": called, **({"failed": failures} if failures else {})}
if failures and len(called) > 1:
# 部分成功也得看得见:留痕里挂着失败的是哪几家,日志里也留一句
logger.warning("字段 %s 的多源取数有部分没成:%s", key, ";".join(failures))
_apply_cell(
db, cfg, field_def, data, keys, data, trace,
at=f"「{label}」", trace_key=key, policy=_policy_of(cfg, field_def, perms, data),
work=work, actor=actor, activity=activity,
)
# 明细表里那些配了取数的列:同一份配置,逐行各跑一次,值写进这一行
_apply_rows(db, row_targets, data, trace, work=work, actor=actor, activity=activity, perms=perms)
if trace:
data[TRACE_KEY] = trace
def _entry_problems(
db: Session | None, entry: dict, keys: set[str], field: dict, at: str,
person_keys: set[str] | None = None
) -> list[str]:
"""单个数据源那条配置本身的毛病;判据在 ``service/binding.entry_problems``。
def _policy_of(cfg: dict, field_def: dict, perms: dict | None, data: dict) -> str:
"""这一格取不到数时怎么兜(``keep`` / ``block`` / ``zero``),本环节藏着的格子先降级。
取数这一路要的是「能取出一个值」的源(列表型取不出单值),带出的键还得是
源上声明过的那几个——两句都在内核里,这里只把门牌(``at``)与这一格的 key 给它。
``person_keys`` 是这一份表单上的选人字段:拿它才能在设计期就说清"选人字段直接绑进
SQL 的 = 比不中",而不是等填单的人撞上一条 blocked。
主表那一格与明细行那一格共用这一句:被本环节藏起来的格子那一屏既看不见它也改不动它,
``onError=block`` 在这一律降级成不挡、值留在原来那一份上(与阈值/额度同一口径,
见 ``threshold.blocked_here``);**取数照旧发起**,条件分支与下一环节读的还是新数。
明细行里那一列露不露脸,看的是它所属那张明细表在这一环露不露(环节权限挂的是表)。
"""
return binding.entry_problems(
db, entry, keys, at, self_key=str(field.get("key") or "").strip(),
want=binding.WANT_FETCH, person_keys=person_keys
from . import formruntime # 局部导入:与 apply_form 同一处理
policy = str(cfg.get("onError") or "keep").strip()
if policy != "block" or not formruntime.field_hidden(field_def, perms, data):
return policy
label = str(field_def.get("label") or field_def.get("key") or "")
logger.info("外部取数失败但这一环不挡提交:%s 这一格在当前环节没显示", label)
return "keep"
def _run_entries(
db: Session, cfg: dict, scope: dict, keys: set[str], target: dict, *,
work=None, actor=None, activity=None, at: str = "", own_key: str = ""
) -> tuple[list[Any], list[str], list[dict]]:
"""跑这一格配的那几张源:值收进一份清单,每张源配的带出去向顺手写进 ``target``。
主表那一格传的 ``scope`` 与 ``target`` 都是 ``data``(老行为一个字不动:后一个源的入参
读得到前一个源刚带进 ``data`` 的那几格);明细行那一格传的是「整张单 + 这一行」这一份
作用域,以及那一行本身。两条路共用同一次外呼、同一份留痕形状、同一条「带出去向那一格
还在不在」的闸(``binding.live_target``)——差的只是往哪个对象里写。
``own_key`` 给成这一格自己的字段名时,带出去向里指着它的那几行**不写**:候选路由自带的
那一份带出只准往别的格子上写,这一格那一个值是人从候选里挑的(见 :data:`FILL_ONLY_KEY`)。
设计期已经把这种配法报成毛病,这里是兜住老配置与接口直传那两条路。
回 ``(values, failures, called)``:怎么合成一个值、取不到怎么兜,归调用方(``_apply_cell``)。
"""
values: list[Any] = []
failures: list[str] = []
called: list[dict] = []
# 只跑**此刻触发条件成立**的那几条(``when``,见 ``active_field_sources``):
# 一条都没触发就是这一格这回不取数,与「配了源但源停了」不是一回事,不记失败
for entry in binding.active_entries(cfg, scope):
code = str(entry.get("source") or "")
row = get_source(db, code)
if row is None or not row.enabled:
failures.append(f"{code}:未配置或已停用")
continue
args = resolve_args(db, entry, scope, work, actor)
result = run(db, row, args, actor=actor, work=work, activity=activity,
pick=str(entry.get("pick") or ""), extras=_entry_extras(entry))
if not result.ok:
failures.append(f"{row.name}:{result.error}")
continue
values.append(result.value)
for source_key, pick_target in entry["picks"].items():
target_key = binding.live_target(pick_target, keys)
if own_key and target_key == own_key:
continue
if not target_key:
if str(pick_target or "").strip():
logger.warning("字段 %s 的带出指向表单里已经没有的格子 %s,这一笔没写",
at or code, pick_target)
continue
value = result.extras.get(str(source_key)) if str(source_key) in (result.extras or {}) else None
if value is None and str(source_key) == "value":
value = result.value
target[target_key] = value
called.append({"source": code, "args": args, "cached": result.cached,
"at": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
# 这一格自己指定了取哪一列时留一笔,事后看留痕才知道读的是哪条路径
**({"pick": str(entry.get("pick"))} if str(entry.get("pick") or "").strip() else {})})
return values, failures, called
def _apply_cell(
db: Session, cfg: dict, field_def: dict, scope: dict, keys: set[str], target: dict,
trace: dict, *, at: str, trace_key: str, policy: str,
work=None, actor=None, activity=None
) -> tuple[bool, list[str]]:
"""按这一格那份 ``fetch`` 把值配好:写进 ``target``,带出也写进 ``target``,留痕记进 ``trace``。
主表那一格(``target`` 是 ``data``)与明细表的一格(``target`` 是那一行)走的就是这一个
函数,多源合并、失败策略、留痕形状因此不可能走偏成两套。``at`` 是报错时的门牌,
``trace_key`` 是留痕里这一格的名字,``extra_trace`` 给明细行多带的那一格(行号)。
回 ``(这一格有没有写上值, 这一格没取到的那几句)``:值写进 ``target``,带出也写进
``target``,留痕记进 ``trace[trace_key]``。
"""
key = str(field_def.get("key") or "")
merge = str(cfg.get("merge") or "first").strip()
separator = str(cfg.get("separator") or "、")
values, failures, called = _run_entries(
db, cfg, scope, keys, target, work=work, actor=actor, activity=activity, at=at,
own_key=key if cfg.get(FILL_ONLY_KEY) else "",
)
blank_value = 0 if str(field_def.get("type") or "") in MONEY_TYPES else ""
if cfg.get(FILL_ONLY_KEY):
# 候选路由自带的这一条只管「带出去向」那几格(``_run_entries`` 已经写进 target 了):
# 这一格自己那一个值是人从候选里挑的,不许被取回来的数盖掉,也不参与合并;
# 取不到时 ``block`` 照旧挡提交,``zero`` 不动这一格(要清的本来就不是它)。
if failures and policy == "block":
raise _engine_error()(f"{at}的外部数据取不到:{';'.join(failures)}")
if called:
first = called[0]
trace[trace_key] = {"source": first["source"], "args": first["args"], "cached": first["cached"],
"at": first["at"], "merge": "", "sources": called,
**({"failed": failures} if failures else {})}
if failures:
logger.warning("字段 %s 的候选路由带出有一部分没取到:%s", key, ";".join(failures))
return False, failures
if not called:
if failures and policy == "block":
raise _engine_error()(f"{at}的外部数据取不到:{';'.join(failures)}")
if failures and policy == "zero":
target[key] = blank_value
return False, failures
# 少调成一个源,这格的值就是残缺的。只有 first 那档本来就允许"轮到谁算谁",
# 其余(相加 / 取最小…)凑不齐就当这次取数失败,按 onError 处理,
# 免得把「三个系统的余额之和」悄悄写成一个少了某一家的数。
if failures and merge != "first":
if policy == "block":
raise _engine_error()(f"{at}的外部数据只取到一部分:{';'.join(failures)}")
if policy == "zero":
target[key] = blank_value
return False, failures
merged = merge_values(merge, values, separator=separator)
if merged is None:
return False, failures
target[key] = coerce(str(field_def.get("type") or ""), merged)
first = called[0]
trace[trace_key] = {"source": first["source"], "args": first["args"], "cached": first["cached"],
"at": first["at"], "merge": merge if len(called) > 1 else "",
"sources": called, **({"failed": failures} if failures else {})}
if failures and len(called) > 1:
# 部分成功也得看得见:留痕里挂着失败的是哪几家,日志里也留一句
logger.warning("字段 %s 的多源取数有部分没成:%s", key, ";".join(failures))
return True, failures
def _apply_rows(
db: Session, targets: list[tuple[dict, dict, dict]], data: dict, trace: dict, *,
work=None, actor=None, activity=None, perms: dict | None = None
) -> None:
"""明细表里那些配了取数的列:逐行跑一次,值写进**这一行**的这一列。
``targets`` 是 :func:`row_fetch_fields` 挑出来的那几列(表定义、列定义、取数配置)。
行按 ``data`` 里当前那几行跑(``normalise_rows`` 已经整过型、丢过空行),所以被人删掉的
行不会再取一次数,新加的那一行当场补得上。兜法与主表那一格一模一样(同一个
:func:`_apply_cell`),只是报错要点名是哪一行:
「明细表「收款明细」第 2 行的「银行帐号」的外部数据取不到」。
留痕按「表名.列名」记一条,底下挂每一行那次外呼的入参与时刻——两张明细表可能有同名列,
同一张表每一行都得留得开,所以不能沿用主表那份「列名当键」。
"""
for table, column, cfg in targets:
table_key = str(table.get("key") or "")
table_label = str(table.get("label") or table_key)
column_key = str(column.get("key") or "")
column_label = str(column.get("label") or column_key)
rows_value = data.get(table_key)
if not table_key or not column_key or not applies_at(cfg, activity):
continue
if not isinstance(rows_value, list) or not rows_value:
continue
# 带出去向只认这张表的列:写进主表那一格等于让最后一行去盖表头
column_keys = {str(item.get("key") or "").strip() for item in table_columns(table)}
column_keys.discard("")
policy = _policy_of(cfg, table, perms, data)
row_trace: dict[str, Any] = {}
failed: list[str] = []
for index, row in enumerate(rows_value, start=1):
if not isinstance(row, dict):
continue
# 入参读的是「整张单 + 这一行」,同名的列以本行为准——与本行公式同一份作用域
scope = {**data, **row}
at = f"明细表「{table_label}」第 {index} 行的「{column_label}」"
# 列上那份候选路由自带的带出,命中与否看的是**这一行**里的值
_wrote, failures = _apply_cell(
db, config_of(column, scope) or cfg, column, scope, column_keys, row, row_trace,
at=at, trace_key=str(index), policy=policy,
work=work, actor=actor, activity=activity,
)
failed.extend(f"第 {index} 行:{text}" for text in failures)
if not row_trace:
continue
calls: list[dict] = []
# 每行那份留痕按行号记,摊平成一张清单时把行号写进每一次调用里
for row_no, item in sorted(row_trace.items(), key=lambda kv: int(kv[0])):
for call in item.get("sources") or []:
calls.append({"row": int(row_no),
**{key: call.get(key) for key in ("source", "args", "cached", "at")}})
first = row_trace[min(row_trace, key=int)]
trace[f"{table_key}.{column_key}"] = {
"source": first.get("source"), "args": first.get("args"), "cached": first.get("cached"),
"at": first.get("at"), "merge": first.get("merge", ""), "rows": calls,
**({"failed": failed} if failed else {}),
}
def _engine_error():
@ -1688,42 +1931,77 @@ def type_name(value: Any) -> str:
def problems(fields: Iterable[dict] | None, db: Session | None = None) -> list[str]:
"""字段上 ``fetch`` 配置的毛病。与 ``quota.problems`` 同一把尺子,前端有镜像。"""
"""字段上 ``fetch`` 配置的毛病。与 ``quota.problems`` 同一把尺子,前端有镜像。
明细表的列也在这儿判:列上那份 ``fetch`` 与主表字段那份跑的是同一个执行器,
判据自然共用同一份(见 :func:`_cfg_problems`),只是门牌要说清是哪张表的哪一列,
而带出去向那一栏只认这张表的列。
"""
out: list[str] = []
rows = [item for item in (fields or []) if isinstance(item, dict)]
keys = {str(item.get("key") or "").strip() for item in rows}
person_keys = binding.person_field_keys(rows)
for index, item in enumerate(rows, start=1):
cfg = item.get(FIELD_PROP)
if cfg is None or cfg == {} or cfg == "":
continue
shown = str(item.get("label") or item.get("key") or "").strip() or "未命名"
at = f"第 {index} 个字段「{shown}」的外部取数"
if not isinstance(cfg, dict):
out.append(f"{at}的格式不对")
out.extend(_cfg_problems(db, item.get(FIELD_PROP), item,
f"第 {index} 个字段「{shown}」的外部取数", keys, person_keys))
if str(item.get("type") or "") != TABLE_TYPE:
continue
entries = field_sources(cfg)
if not entries:
out.append(f"{at}没选数据源")
rows_cfg = cfg.get("sources")
if isinstance(rows_cfg, list) and len(rows_cfg) > MAX_FIELD_SOURCES:
out.append(f"{at}最多挂 {MAX_FIELD_SOURCES} 个数据源,现在配了 {len(rows_cfg)} 个")
if str(cfg.get("onError") or "") not in ("", "keep", "block", "zero"):
out.append(f"{at}的失败策略不支持:{cfg.get('onError')}")
seconds = cfg.get("revalidateAfter")
if seconds not in (None, "", 0, "0", False):
try:
value = int(seconds)
except (TypeError, ValueError):
out.append(f"{at}的实时刷新间隔要填整数秒")
else:
if value < 1 or value > 86400:
out.append(f"{at}的实时刷新间隔要在 1 秒到 86400 秒之间(0 = 不主动刷)")
merge = str(cfg.get("merge") or "first").strip()
if merge not in MERGE_MODES:
out.append(f"{at}的合并方式不支持:{merge}")
if merge in NUMERIC_MERGE_MODES and str(item.get("type") or "") not in MONEY_TYPES:
out.append(f"{at}要按「{merge}」合并,这一格得是金额或数字类型")
person_keys = binding.person_field_keys(rows)
for at_entry, entry in binding.entry_labels(at, entries):
out.extend(_entry_problems(db, entry, keys, item, at_entry, person_keys))
columns = table_columns(item)
column_keys = {str(col.get("key") or "").strip() for col in columns}
column_keys.discard("")
for column in columns:
column_shown = str(column.get("label") or column.get("key") or "").strip() or "未命名"
out.extend(_cfg_problems(
db, column.get(FIELD_PROP), column,
f"明细表「{shown}」的列「{column_shown}」的外部取数",
# 行作用域读得到整张单与本行的列(同名以本行为准),带出只落在这张表的列上
keys | column_keys, person_keys | binding.person_field_keys(columns),
target_keys=column_keys, target_noun="列",
))
return out
def _cfg_problems(
db: Session | None, cfg: Any, field: dict, at: str, keys: set[str],
person_keys: set[str], *, target_keys: set[str] | None = None, target_noun: str = "字段"
) -> list[str]:
"""一份 ``fetch`` 配置的毛病:没配就一句都不说,配了就把形状、源、入参、带出判到底。"""
if cfg is None or cfg == {} or cfg == "":
return []
if not isinstance(cfg, dict):
return [f"{at}的格式不对"]
out: list[str] = []
entries = field_sources(cfg)
if not entries:
out.append(f"{at}没选数据源")
rows_cfg = cfg.get("sources")
if isinstance(rows_cfg, list) and len(rows_cfg) > MAX_FIELD_SOURCES:
out.append(f"{at}最多挂 {MAX_FIELD_SOURCES} 个数据源,现在配了 {len(rows_cfg)} 个")
if str(cfg.get("onError") or "") not in ("", "keep", "block", "zero"):
out.append(f"{at}的失败策略不支持:{cfg.get('onError')}")
seconds = cfg.get("revalidateAfter")
if seconds not in (None, "", 0, "0", False):
try:
value = int(seconds)
except (TypeError, ValueError):
out.append(f"{at}的实时刷新间隔要填整数秒")
else:
if value < 1 or value > 86400:
out.append(f"{at}的实时刷新间隔要在 1 秒到 86400 秒之间(0 = 不主动刷)")
merge = str(cfg.get("merge") or "first").strip()
if merge not in MERGE_MODES:
out.append(f"{at}的合并方式不支持:{merge}")
if merge in NUMERIC_MERGE_MODES and str(field.get("type") or "") not in MONEY_TYPES:
out.append(f"{at}要按「{merge}」合并,这一格得是金额或数字类型")
# 取数这一路要的是「能取出一个值」的源(列表型取不出单值),带出的键还得是源上声明过
# 的那几个——两句都在内核里。``person_keys`` 是这份清单里的选人字段(明细列那一档连本表
# 的选人列一起算):拿它才能在设计期就说清"选人字段直接绑进 SQL 的 = 比不中",
# 而不是等填单的人撞上一条 blocked。
for at_entry, entry in binding.entry_labels(at, entries):
out.extend(binding.entry_problems(
db, entry, keys, at_entry,
self_key=str(field.get("key") or "").strip(), want=binding.WANT_FETCH,
person_keys=person_keys, target_keys=target_keys, target_noun=target_noun,
))
return out

View File

@ -309,6 +309,37 @@ def editable_keys(fields: Iterable[dict], perms: dict[str, str], data: dict | No
}
def writable_ignoring_self(field: dict, perms: dict[str, str], data: dict | None = None) -> bool:
"""把「读自己那几条」摘掉以后,这一格在这个环节填得动吗。
问的是「挡着这一笔值的到底只有它自己那一句吗」。前端镜像在
``utils/formRuntime.writableIgnoringSelf``。
"""
rest = _linkage().stripped_of_self(field)
if not rest or data is None:
return False
return effective_perm(rest, perms, data) in (PERM_EDITABLE, PERM_REQUIRED)
def self_gated_keys(fields: Iterable[dict], perms: dict[str, str], data: dict) -> set[str]:
"""只被自己那句条件收走 / 锁住的格子:这一笔值正是让它藏起来的原因。
``editable_keys`` 按合并后的数据算,「本字段有值才显示」「有值就锁住」这一类条件在
人刚敲完的那一刻就把这一格收了,于是这一笔刚写下的值按「这个环节改不动」退回原样——
人看着自己写的字凭空消失。摘掉自引用那几条以后这一格本来就填得动,那这一笔值就该收下。
只放宽「收不收这一笔值」,不放宽界面上露不露、必填要不要、阈值挡不挡人:那几处读的
仍然是带自引用的那一份条件,一寸没动。
"""
return {
str(item.get("key") or "")
for item in fields
if item.get("key")
and effective_perm(item, perms, data) not in (PERM_EDITABLE, PERM_REQUIRED)
and writable_ignoring_self(item, perms, data)
}
def _linkage():
"""延迟导入,避开 dicts -> formruntime 的循环(大写金额那条也是同一个套路)。"""
from . import dicts as _dicts
@ -323,6 +354,13 @@ def _kernel():
return _binding
def _relation_fill():
"""关联单据带出(``linkFill``)那一层,同样延迟导入:它本身要吃本模块的列口径。"""
from . import linkfill as _linkfill
return _linkfill
#: 候选来源=外部数据源时,那张源除了关键词还要按什么筛(``{form.x}`` 那一份入参表)。
#: 与字段上外部取数的 ``args`` 同一个形状、同一套解析,见 service/binding.py。
OPTION_ARGS_KEY = "dataSourceArgs"
@ -375,6 +413,16 @@ WEEK_DAY_VALUES = ("1", "2", "3", "4", "5", "6", "7")
TEXT_LIMIT_TYPES = ("text", "textarea", "richtext")
#: 能配「允许类型 / 最多几个 / 单个多大」的附件类字段,与前端 ``FILE_LIMIT_TYPES`` 一致。
FILE_LIMIT_TYPES = ("attachment", "image")
#: 明细列在表格上怎么摆的那三档合法值,与前端 ``TABLE_COLUMN_ALIGNMENTS`` /
#: ``TABLE_COLUMN_AGGREGATES`` / ``TABLE_COLUMN_WIDTHS`` 同一份清单。认不出的写法多半是
#: 手改 JSON 或从别处粘来的配置:与其运行时默默按默认摆(配的人以为配好了),保存就说清。
COLUMN_ALIGNMENTS = ("auto", "left", "center", "right")
COLUMN_AGGREGATES = ("none", "sum", "avg", "max", "min", "count")
#: 能求和 / 平均 / 最大 / 最小的列类型:只有这两类装的是数。其余列只能数个数。
NUMERIC_AGGREGATE_TYPES = ("number", "money")
#: 明细列宽的合法区间(px):比一颗勾选框还窄、比一整屏还宽的都算配歪了。
COLUMN_WIDTH_MIN = 60
COLUMN_WIDTH_MAX = 640
#: 空白格的高度区间(px),与前端 ``SPACER_MIN_HEIGHT`` / ``SPACER_MAX_HEIGHT`` 一致。
SPACER_MIN_HEIGHT = 8
SPACER_MAX_HEIGHT = 240
@ -685,11 +733,42 @@ def value_problems(fields: Iterable[dict], perms: dict[str, str], data: dict) ->
problem = _shape_problem(kind, value)
if problem:
problems.append(f"「{label}」{problem}")
elif kind in NUMERIC_RANGE_TYPES:
problem = _range_problem(field, value)
if problem:
problems.append(f"「{label}」{problem}")
elif kind in FILE_LIMIT_TYPES:
problems.extend(_file_problems(field, value, label))
return problems
#: 能配「最小值 / 最大值」的字段类型:数字与金额两类(明细列同理)。
#: 评分的 ``max`` 是满星数、不是取值范围,别混进来。
NUMERIC_RANGE_TYPES = ("number", "money")
def _range_problem(field: dict, value: object) -> str:
"""这一格的数在不在配好的上下限里;没配、或值是空的,都不说话。
界面上 ``<input type="number">`` 的 ``min`` / ``max`` 只把不合法的输入标个红,压根拦不住
人继续往下走,所以提交这一趟得判。「权威判定在提交那一步」这条规矩在这儿的意思是:
别只留一层浏览器给的软提示——接口直传与脚本写进来的值根本不经过那只框。
"""
if value in (None, ""):
return ""
try:
number = float(str(value).strip())
except (TypeError, ValueError):
return ""
low = _number(field.get("min"))
high = _number(field.get("max"))
if low is not None and number < low:
return f"小于配好的最小值 {field.get('min')}"
if high is not None and number > high:
return f"大于配好的最大值 {field.get('max')}"
return ""
def _shape_problem(kind: str, value: object) -> str:
"""这几类的值形状:星期几只能是 1-7,时间段得有先后,定位得是个物件。"""
if kind == "week":
@ -744,6 +823,19 @@ def _file_problems(field: dict, value: object, label: str) -> list[str]:
return problems
def hidden_by_condition(field: dict, data: dict | None) -> bool:
"""这一格是因为**自己的显示条件不成立**才藏起来的吗。
跟「勾了默认隐藏」不是一回事:编号、金额大写那一类全局不露却仍然要有值,藏起来不等于
可以不生成;而配了显示条件的格子,条件翻走说的是「这一单根本用不到它」——既没有录入框,
又不适用这一单,再催一句「还没填写」就是让人对着一片空白找输入框。
"""
condition = field.get("visibleWhen")
if condition in (None, "", {}, []):
return False
return not _linkage().condition_ok(condition, data or {})
def missing_required(
fields: Iterable[dict], perms: dict[str, str], data: dict, *, prefix: str = ""
) -> list[str]:
@ -761,7 +853,15 @@ def missing_required(
# 系统带出与公式没有录入框,权限算出来永远是只读;字段自己勾了必填,就要它算得出值。
# 字段级「默认隐藏」也走这一条:编号、金额大写这种不显示但仍要有值的格子,
# 藏起来不等于可以不生成。环节显式隐藏(key in perms)才是真不用管。
must = system_filled(field) and bool(field.get("required"))
#
# 但**因显示条件不成立而藏起来**的那一格不算这一笔:那种配法说的是「这一单用不到它」
# (生产上「默认隐藏 + 显示条件 + 必填」的系统带出格就是这么把自己钉死的——
# 屏幕上没有那一格,提交却永远说它没填)。
must = (
system_filled(field)
and bool(field.get("required"))
and not hidden_by_condition(field, data)
)
if not must:
continue
if not answered(field, (data or {}).get(key)):
@ -782,15 +882,28 @@ def _row_problems(field: dict, rows: list[dict]) -> list[str]:
problems.append(f"「{label}」最多只能有 {max_rows} 行")
for index, row in enumerate(rows, start=1):
for column in columns:
if not column.get("required"):
continue
column_key = str(column.get("key") or "")
if not column_key:
continue
if not answered(column, row.get(column_key)):
# 勾了「只读」或「隐藏此列」那一列(设计器明细列上那两颗开关,与填单时锁格子、
# 收掉整列的是同一份 ``column.readonly`` / ``column.hidden``)压根没有录入框:
# 必填卡的是人,而这一列的值归默认值 /
# 自动带出 / 关联带出 / 额度台账给,照旧拦等于把单子钉死在这一环——那一格
# 谁也改不动,却永远说它没填。本行公式那一列不在其列:它没勾只读,公式算不
# 出值仍是配置坏了,该说。口径与主表 ``missing_required`` 同一取向(没有录入
# 框的那几类只在其值真归系统管时才算数),前端不摆红星也是同一句。
if (
column.get("required")
and not column_not_for_people(column)
and not answered(column, row.get(column_key))
):
problems.append(f"「{label}」第 {index} 行的「{column.get('label') or column_key}」还没填写")
# 列里那几样新限制(字数、正则、月份写法、时间段先后、星期、附件三个限制)也判:
# 明细列与主表共用一只控件,只判主表等于列上开了个口子。
# 列里那几样限制(字数、正则、取值上下限、月份写法、时间段先后、星期、附件三个限制)
# 照判:明细列与主表共用一只控件,只判主表等于在列上开了个口子。
#
# 这一问**不跟着必填走**——以前整段套在「没勾必填就跳过」里面,于是非必填的列
# 填了什么都没人看,那三道限制等于只在浏览器里说了算;接口直传与脚本写入的值
# 压根不经过那只框。判据仍是 value_problems 那一份,主表明细一个都不多判。
for problem in value_problems([column], {}, row):
problems.append(problem.replace(f"「{column.get('label') or column_key}」",
f"「{label}」第 {index} 行的「{column.get('label') or column_key}」", 1))
@ -876,24 +989,30 @@ def selection_problems(fields: Iterable[dict], perms: dict[str, str], data: dict
key = str(field.get("key") or "")
if not key or effective_perm(field, perms, data) not in (PERM_EDITABLE, PERM_REQUIRED):
continue
if not _has_option_rule(field):
if not _has_option_rule(field, data):
continue
options = linkage.effective_options(field, data, cache) # type: ignore[arg-type]
if options is None:
continue
# 命中哪一条候选来源,就按那一条的「存哪一列」比(effective_options 内部是同一张视图)
view = linkage.option_view(field, data)
# 比的是这一格**存的那一列**:配过「显示 / 存值」的字段,候选本体与存的值不是一回事
allowed = {linkage.stored_of(field, item) for item in options}
allowed = {linkage.stored_of(view, item) for item in options}
current = linkage._values(data.get(key))
stale = [value for value in current if value not in allowed]
if stale:
parent = str(field.get("cascadeFrom") or "").strip()
if linkage.accepts_outside_value(field):
# 这一格勾了「带出的值不在候选里也收下」:值是外部取数 / 关联单据带出 / 字典带出
# 写进来的(三道带出都排在这一次校验之前),本地那份清单不判对面给的值
continue
parent = str(view.get("cascadeFrom") or "").strip()
hint = f"(请先选对「{label_of(fields, parent)}」)" if parent else ""
if _kernel().entries(field.get("fetch")):
# 那一格不是人选的,是提交这一刻外部取数写进来的。不说这句,填单的人
# 就只能站在一个自己填不了的格子前问「这个值是哪来的」
if _kernel().entries(field.get("fetch")) or linkage.has_route_fill(field):
# 那一格不是人选的,是提交这一刻外部取数(或候选路由自带的那份带出)写进来的。
# 不说这句,填单的人就只能站在一个自己填不了的格子前问「这个值是哪来的」
problems.append(
f"「{field.get('label') or key}」由外部取数带回的取值不在可选范围内"
f"(候选来自{'数据字典' if str(field.get('dictCode') or '').strip() else '手填选项'},"
f"(候选来自{'数据字典' if str(view.get('dictCode') or '').strip() else '手填选项'},"
"把那一项补进清单,或把这一格的候选来源改成外部数据源 / 流程单据)"
)
continue
@ -908,28 +1027,34 @@ def label_of(fields: Iterable[dict], key: str) -> str:
return key
def _has_option_rule(field: dict) -> bool:
def _has_option_rule(field: dict, data: dict | None = None) -> bool:
"""这个字段的可选项会不会随别的字段变化(字典 / 级联 / 带条件的选项)。"""
linkage = _linkage()
# 候选来自流程单据 / 外部数据源的格子:服务端手上只有搜出来的那一页,
# 拿它当合法值清单会把人正常选中的单据判成越界,这一类交给对面系统说话。
if not linkage.constrains_values(field):
if not linkage.constrains_values(field, data):
return False
if str(field.get("type") or "") == CASCADER_TYPE:
# 级联的合法值口径不一样,走 cascader_problems
return False
if str(field.get("dictCode") or "").strip():
view = linkage.option_view(field, data)
if str(view.get("dictCode") or "").strip():
return True
if str(field.get("cascadeFrom") or "").strip():
if str(view.get("cascadeFrom") or "").strip():
return True
raw = field.get("options")
raw = view.get("options")
if isinstance(raw, list):
return any(isinstance(item, dict) and item.get("when") for item in raw)
return False
def linkage_problems(fields: Iterable[dict]) -> list[str]:
"""设计期检查联动配置本身:引用了不存在的字段、自己依赖自己、条件写了不认识的算子。"""
"""设计期检查联动配置本身:引用了不存在的字段、级联上级选了自己、条件写了不认识的算子。
**联动条件读自己不再是配错**(2026-11 起):「外部带回来的合同编号有值才露这一格」判的
正是这一格自己的值,前端界面上也摆得出这一档(``LinkagePanel.conditionSources`` 把本字段
留在清单最前面),后端再报这一句就成了一处配得出来、另一处不让存的死结。
"""
items = [item for item in fields if isinstance(item, dict)]
keys = {str(item.get("key") or "") for item in items}
linkage = _linkage()
@ -937,12 +1062,12 @@ def linkage_problems(fields: Iterable[dict]) -> list[str]:
for field in items:
key = str(field.get("key") or "")
label = str(field.get("label") or key)
# 条件 / 级联指向自己是配错(显示与否不能由自己的当前值决定);
# 带出规则读自己才是常态 —— 从本字段的字典项里取 extra。
# 级联上级选到自己还是配错:候选得由另一格来筛,自己筛自己筛不出东西。
# 联动条件读自己是正常用法;带出规则读自己同样是常态(从本字段的字典项里取 extra)。
if str(field.get("cascadeFrom") or "").strip() == key:
problems.append(f"「{label}」的级联上级选了它自己")
for dep in linkage.condition_dependencies(field):
if dep == key:
problems.append(f"「{label}」的联动条件引用了自己")
elif dep not in keys:
if dep != key and dep not in keys:
problems.append(f"「{label}」的联动条件引用了不存在的字段「{dep}」")
for dep in linkage.auto_fill_dependencies(field):
if dep != key and dep not in keys:
@ -960,8 +1085,16 @@ def linkage_problems(fields: Iterable[dict]) -> list[str]:
problems.append(f"「{label}」的「{name}」配置格式不对")
continue
for rule in condition.get("rules") or []:
if isinstance(rule, dict) and str(rule.get("op") or "eq") not in linkage.CONDITION_OPS:
if not isinstance(rule, dict):
continue
if str(rule.get("op") or "eq") not in linkage.CONDITION_OPS:
problems.append(f"「{label}」的「{name}」用了不支持的比较符 {rule.get('op')}")
# 条件左右两头挑的是同一格:自己跟自己比永远比不出新意思,配了也是白配。
# (两边值的形状比不了就不给挑,那一档只在前端收窄:后端没有那份类型矩阵。)
right = str(rule.get("valueField") or "").strip()
left = str(rule.get("field") or "").strip()
if right and right == left:
problems.append(f"「{label}」的联动条件拿「{label_of(items, left)}」和自己比")
return problems
@ -986,11 +1119,56 @@ def _int(value: object, default: int = 0) -> int:
return default
def column_not_for_people(column: dict) -> bool:
"""这一列的值归不归人填:勾了只读、整列藏起来,两样都是"人改不动这一格"。
必填卡的是人,所以这两样都不卡必填,前端也不摆那颗红星
(前端镜像 ``utils/formRuntime.columnNotForPeople``)。本行公式那一列**不在这一问里**:
它没勾只读,公式算不出值仍是配置坏了,照旧要说。
"""
return bool(column.get("readonly")) or bool(column.get("hidden"))
def column_display_problems(column: dict) -> list[str]:
"""明细列在表格上怎么摆的那三样(列宽 / 对齐 / 合计)配得对不对(设计期)。
这三样是纯展现:不改任何一格的值,也不参与提交那道闸,所以只判"配置本身认不认识"。
与前端 ``utils/formRuntime.validateTableField`` 同一把尺子。
"""
problems: list[str] = []
raw = column.get("width")
if raw not in (None, "", 0):
width = _number(raw)
if width is None or width < COLUMN_WIDTH_MIN or width > COLUMN_WIDTH_MAX:
problems.append(f"的列宽要在 {COLUMN_WIDTH_MIN}-{COLUMN_WIDTH_MAX}px 之间,或留「自动」")
align = column.get("align")
if align not in (None, "") and str(align) not in COLUMN_ALIGNMENTS:
problems.append(f"的对齐方式不认识:{align}")
aggregate = column.get("aggregate")
if aggregate not in (None, "") and str(aggregate) not in COLUMN_AGGREGATES:
problems.append(f"的合计方式不认识:{aggregate}")
elif str(aggregate or "") not in ("", "none", "count") and str(column.get("type") or "") not in NUMERIC_AGGREGATE_TYPES:
problems.append("不是数字或金额列,合计只能数个数")
low = _number(column.get("min"))
high = _number(column.get("max"))
if low is not None and high is not None and low > high:
problems.append("的最小值大于最大值")
return problems
def row_is_empty(row: dict, columns: list[dict]) -> bool:
keys = [str(item.get("key") or "") for item in columns] or list(row.keys())
# 带出那一行本来就可能是空的:对方那张单里这一列没填,行还是那一张单的,删掉等于把关联弄丢
if str(row.get(ROW_LINK_KEY) or "").strip():
return False
return all(empty_value({"__value__": row.get(key)}) for key in keys)
def max_rows_of(field: dict) -> int:
"""这一张明细表最多几行;0 / 没配 = 不限。口径只在这一处(``normalise_rows`` 与关联带出共用)。"""
return _int((field or {}).get("maxRows"), 0)
def rows_of(value: object) -> list[dict]:
"""把明细表字段的值收成对象数组;脏数据、标量、嵌套数组一律丢掉。"""
if not isinstance(value, list):
@ -998,6 +1176,17 @@ def rows_of(value: object) -> list[dict]:
return [dict(item) for item in value if isinstance(item, dict)]
#: 明细行上记「这一行是谁带出来的」那一格。下划线开头 = 服务端自己写的留痕,
#: 导出、打印、明细导出都只认配好的列,看不见它;写它的人是 ``service/linkfill.py``。
ROW_LINK_KEY = "_link"
#: 明细行上记「这几列的公式值是人自己敲的」那一格(存列标识的数组),与 ``_link`` 同一层。
#: 写它的是前端 ``FormRenderer.setFormulaCell``,读它的是 ``utils/formRuntime.applyRowFormulas``。
#: 服务端一路只当它是行上的一份留痕:本行公式只有前端会算,所以这里**只负责带着它走**
#: (``normalise_rows`` 别把它当野键丢掉),一旦哪天服务端也参与重算,判据仍是这一份。
#: 只有列上勾了「公式带入后允许修改」(``column.formulaEditable``)才会出现它。
ROW_MANUAL_KEY = "_manual"
#: 能配「默认值」的明细列类型,与前端 ``COLUMN_DEFAULT_TYPES`` 一致。
#: 只收装得下单个值的那几类:多选、选人、部门、附件、图片、签名、日期区间、关联单据
#: 一格装的不止一个值,级联要的是整条路径——默认成什么都是设计器替人做主,不开这个口子。
@ -1130,11 +1319,18 @@ def normalise_rows(value: object, field: dict) -> list[dict]:
allowed = {str(item.get("key") or "") for item in columns}
rows: list[dict] = []
for row in rows_of(value):
kept = {k: v for k, v in row.items() if not allowed or k in allowed}
# ``_link`` 与 ``_manual`` 都不在列清单里,但它们是「这一行是谁带出来的」
# 「哪几格归人管」的唯一凭据:页面回传时丢掉前者,下一次带出认不出旧行,
# 会把人改过的行当新行重排一遍;丢掉后者,下一轮重算就把人家自己敲的数盖回公式值
kept = {
k: v
for k, v in row.items()
if not allowed or k in allowed or k in (ROW_LINK_KEY, ROW_MANUAL_KEY)
}
if row_is_empty(kept, columns):
continue
rows.append(fill_row_defaults(columns, kept))
max_rows = _int(field.get("maxRows"), 0)
max_rows = max_rows_of(field)
return rows[:max_rows] if max_rows else rows
@ -1357,7 +1553,148 @@ def data_source_row(db, code: str):
).scalar_one_or_none()
def option_source_problems(field: dict, db=None, keys: set[str] | None = None) -> list[str]:
def _source_config_problems(field: dict, kind: str, db=None, keys: set[str] | None = None) -> list[str]:
"""一套候选来源配到底了没有:半截的配置、指向的源不能用、入参引用掉在地上。
字段自己那一份(兜底配置)与条件路由里的每一条都问这一句——**同一套判据,
只不过换了一张视图**,所以两条路不会一边放行一边报错。措辞是给面板原样显示的,
前端镜像在 ``utils/optionSource.ts``。
"""
linkage = _linkage()
kernel = _kernel()
problems: list[str] = []
if kind == linkage.SOURCE_DICT and not str(field.get("dictCode") or "").strip():
problems.append("还没选择要用的数据字典")
source_code = str(field.get("dataSourceCode") or "").strip()
args_at = "候选来源那张数据源"
if kind == linkage.SOURCE_DATA_SOURCE and not source_code:
problems.append("还没选择要用哪一张外部数据源")
if kind == linkage.SOURCE_DATA_SOURCE and source_code:
if db is not None:
# 源被删 / 停用 / 是取一个值的 / 方向只在往外写:填单那一格只会是一个空下拉。
# 判据与「字段上的外部取数」「字典绑的外部来源」共用内核那一句(service/binding.py)
reason = kernel.source_problem(
source_code, data_source_row(db, source_code),
want=kernel.WANT_SEARCH, want_noun="候选",
)
if reason:
problems.append(reason)
problems.extend(kernel.arg_ref_problems(
field.get(OPTION_ARGS_KEY), keys or set(), args_at,
self_ref=str(field.get("key") or "").strip(),
))
# 手填那条路:每个选项自己填「显示文字」和「存的值」,存的值空着等于选了就存个空白
if kind == linkage.SOURCE_MANUAL:
raw_options = field.get("options")
blank = [
item
for item in (raw_options if isinstance(raw_options, list) else [])
if isinstance(item, dict) and not str(item.get("value") or "").strip()
]
if blank:
problems.append(f"有 {len(blank)} 个选项没填要存的值,填了会存成空白")
if kind == linkage.SOURCE_PROCESS:
# 「关联已审批流程」挑到一张被终止的单子,是这一格最常见的一种配歪:
# 能挂哪几档由字段上说清,勾到一种都不剩就先挡下来,别留一只永远搜不到东西的挑选器
problems.extend(linkage.relation_status_problems(field))
return problems
def _fetch_entries(field: dict) -> list[dict]:
"""这一格身上所有会跑的取数条目:字段那份 ``fetch`` +候选路由各条自带的 ``fill``。"""
linkage = _linkage()
kernel = _kernel()
listed = list(kernel.entries(field.get("fetch")))
listed.extend(
entry
for entry in (linkage.route_fill_entry(route) for route in linkage.routes_of(field))
if entry
)
return listed
def _fetch_targets(field: dict) -> set[str]:
"""这份取数写进哪些格子(``picks`` 的那些去向;候选路由那条 fill 的去向也算在这儿)。"""
out: set[str] = set()
for entry in _fetch_entries(field):
out |= {str(target) for target in (entry.get("picks") or {}).values()}
return out
def _fetch_writes(field: dict, key: str) -> bool:
"""有没有一条取数落在**这一格**上:条目自带的 ``pick`` 是取一个值写进它自己那一格,
``picks`` 里点名这一格也算。
"""
if key and key in _fetch_targets(field):
return True
return any(str(entry.get("pick") or "").strip() for entry in _fetch_entries(field))
def _rule_hits_self(rules: Any, key: str) -> bool:
"""``autoFill`` / ``linkFill`` 那两类带出的去向里有没有这一格(配在发起那一格身上,写的是别的格子)。"""
if not key or not isinstance(rules, list):
return False
return any(
isinstance(rule, dict) and str(rule.get("to") or "").strip() == key for rule in rules
)
def filled_by_other(field: dict, rows: Iterable[dict]) -> str:
"""隔壁那一格的带出有没有指着这一格(那同样是系统写进来的值,回那一种带出的名字)。
认四种去向:字典带出(``autoFill[].to``)、关联单据带出(``linkFill.rules[].to``)、
外部取数(``fetch`` 各条目的 ``picks``)与候选路由那一条自带的 ``fill``。只认
「去向正好等于这一格的字段名」——明细列那种 ``表.列`` 的写法不算,那一格在表里,
这一句问的是主表这一格。
"""
key = str(field.get("key") or "").strip()
if not key:
return ""
linkage = _linkage()
kernel = _kernel()
relation = _relation_fill()
fetched = False
for other in rows or []:
if not isinstance(other, dict) or str(other.get("key") or "").strip() == key:
continue
if _rule_hits_self(other.get("autoFill"), key):
return "字典带出"
if key in relation.targets(other):
return "关联单据带出"
# 隔壁那条取数只有**去向点名这一格**才算(它自带的 pick 写的是它自己那一格)
if key in _fetch_targets(other):
fetched = True
return "外部取数" if fetched else ""
def filled_by_label(field: dict, rows: Iterable[dict] | None = None) -> str:
"""这一格的值是不是**系统带进来的**,是哪一种带出(报错与提示要说清是哪一头)。
三种带出都排在提交校验之前跑:外部取数(``fetch``)、关联单据带出(``linkFill``)、
字典带出(``autoFill``)。判的是**有没有一条带出的落点在这一格上**,不是「这一格有没有
配带出」——后两类都配在发起那一格身上、写进的是别的格子,光看有没有配会把人挑的那一格
说成是系统写的(生产上「项目名称」配了字典带出,反被提醒「这一格的值由字典带出写入」)。
都没落上就是这一格由人填,回空串。
给了同表其它字段(``rows``)时还认**隔壁那一格的带出指着这一格**——那同样是系统写的值:
一张下拉自己没配带出、值却是隔壁带进来的,不该再说「这一档不起作用」。
"""
key = str(field.get("key") or "").strip()
if _fetch_writes(field, key):
# 候选路由自带的那一份带出走的是也是取数内核,同一句判据(fillOnly 那一档不写自己)
return "外部取数"
fill = field.get("linkFill")
if isinstance(fill, dict) and _rule_hits_self(fill.get("rules"), key):
return "关联单据带出"
if _rule_hits_self(field.get("autoFill"), key):
return "字典带出"
if rows is None:
return ""
return filled_by_other(field, rows)
def option_source_problems(
field: dict, db=None, keys: set[str] | None = None, rows: Iterable[dict] | None = None
) -> list[str]:
"""候选来源与挑选方式配到哪一步了,几句话说明白(前端镜像 ``utils/optionSource.optionSourceProblems``)。
管三类毛病:配得半截(选了字典没挑字典、选了源没挑源、样式跟这一格不搭)、
@ -1379,26 +1716,7 @@ def option_source_problems(field: dict, db=None, keys: set[str] | None = None) -
if declared and declared not in kinds:
problems.append(f"这类字段挑不了「{declared}」这种候选来源,请重新选一个")
kind = linkage.source_kind_of(field)
if kind == linkage.SOURCE_DICT and not str(field.get("dictCode") or "").strip():
problems.append("还没选择要用的数据字典")
source_code = str(field.get("dataSourceCode") or "").strip()
args_at = "候选来源那张数据源"
if kind == linkage.SOURCE_DATA_SOURCE and not source_code:
problems.append("还没选择要用哪一张外部数据源")
if kind == linkage.SOURCE_DATA_SOURCE and source_code:
if db is not None:
# 源被删 / 停用 / 是取一个值的 / 方向只在往外写:填单那一格只会是一个空下拉。
# 判据与「字段上的外部取数」「字典绑的外部来源」共用内核那一句(service/binding.py)
reason = kernel.source_problem(
source_code, data_source_row(db, source_code),
want=kernel.WANT_SEARCH, want_noun="候选",
)
if reason:
problems.append(reason)
problems.extend(kernel.arg_ref_problems(
field.get(OPTION_ARGS_KEY), keys or set(), args_at,
self_ref=str(field.get("key") or "").strip(),
))
problems.extend(_source_config_problems(field, kind, db, keys))
# 勾了「可以选好几个」之后这一格存的是一串值:额度与外部取数那两头都只认一笔 / 一个值
if linkage.holds_list_value(field) and isinstance(field.get("quota"), dict):
problems.append(
@ -1413,25 +1731,25 @@ def option_source_problems(field: dict, db=None, keys: set[str] | None = None) -
"这一格的阈值条件比的是一个值;勾了「可以选好几个」之后这条条件多半永远不命中,"
"请取消多选或换个格子"
)
# 手填那条路:每个选项自己填「显示文字」和「存的值」,存的值空着等于选了就存个空白
if kind == linkage.SOURCE_MANUAL:
raw_options = field.get("options")
blank = [
item
for item in (raw_options if isinstance(raw_options, list) else [])
if isinstance(item, dict) and not str(item.get("value") or "").strip()
]
if blank:
problems.append(f"有 {len(blank)} 个选项没填要存的值,填了会存成空白")
problems.extend(linkage.option_map_problems(field))
problems.extend(linkage.picker_display_problems(field))
if kernel.entries(field.get("fetch")) and linkage.constrains_values(field):
# 这一格的值是提交那一刻外部取数写进来的,而候选是判越界的那两种来源:
filled_by = filled_by_label(field, rows)
if linkage.accepts_outside_value(field):
if not isinstance(field.get(linkage.ALLOW_OUTSIDE_VALUE_KEY), bool):
problems.append("「带出的值不在候选里也收下」这一档要勾成是或否")
if not filled_by:
problems.append(
"这一格没配任何带出(外部取数 / 关联单据带出 / 字典带出),"
"「带出的值不在候选里也收下」这一档暂时不起作用"
)
if filled_by and linkage.constrains_values(field) and not linkage.accepts_outside_value(field):
# 这一格的值是提交那一刻由系统写进来的,而候选是判越界的那两种来源:
# 两边各自都配得对,凑一起必定在 selection_problems 上炸给填单的人看
problems.append(
f"这一格的值由外部取数写入,候选又来自{'手填选项' if kind == linkage.SOURCE_MANUAL else '数据字典'}"
f"这一格的值由{filled_by}写入,候选又来自{'手填选项' if kind == linkage.SOURCE_MANUAL else '数据字典'}"
":取回来的编码必须在那份清单里,否则提交时会被判「取值已不在可选范围内」。"
"请把取数带回的值补进这份清单,或把候选来源改成外部数据源 / 流程单据"
"请把带回来的值补进这份清单,把候选来源改成外部数据源 / 流程单据,"
"或勾上「带出的值不在候选里也收下」"
)
# 一串值配下拉不再是问题:那只下拉带勾选框,挑中的几条挂在框里(前端 ``Select`` 的 multiple)
style = str(field.get("pickerStyle") or "").strip()
@ -1439,6 +1757,36 @@ def option_source_problems(field: dict, db=None, keys: set[str] | None = None) -
problems.append(f"挑选方式不认识:{style}")
elif style == "inline" and kind in linkage.SEARCHED_SOURCES:
problems.append("这一格的候选是搜出来的,铺不成一排,请改成下拉选项或弹出框")
# 条件路由那几条(``optionRoutes``):清单本身 + 每一条用的那一种来源,逐条再过一遍同一套判据
# 字典带出读的是字典项的附加值:字段上这一本与候选路由里那几本都没有,这一档就是空转
fills = field.get("autoFill")
if isinstance(fills, list) and fills and not str(field.get("dictCode") or "").strip() \
and not linkage.dict_route_codes(field):
problems.append(
"配了字典带出,可这一格没挂数据字典(字段上与候选来源那几条里都没有),这一档不起作用"
)
problems.extend(linkage.route_problems(field))
for index, route in enumerate(linkage.routes_of(field), start=1):
reasons = _source_config_problems(
linkage.route_view(field, route), linkage.route_source_of(route), db, keys
)
problems.extend(f"第 {index} 条候选来源:{text}" for text in reasons)
# 这一条自带的带出(``fill``):走外部取数那同一套判据——源在不在、入参引用掉没掉
# 在地上、带出去向那一格还在不在。门牌单独写「的带出」,不与这一条的候选配置串
entry = linkage.route_fill_entry(route)
if entry:
at = f"第 {index} 条候选来源的带出"
problems.extend(kernel.entry_problems(db, entry, keys or set(), at))
# 带出去向指着这一格自己不行:运行时那份是「只写带出去向」的,这一格那一个值
# 是人从候选里挑的(fetch.FILL_ONLY_KEY),写回它自己只会把人刚挑的那一笔盖掉
own = str(field.get("key") or "").strip()
if own:
for name, target in (entry.get("picks") or {}).items():
if str(target or "").strip() == own:
problems.append(
f"{at}不能把「{name}」带进自己:这一格的值是人从候选里挑的,"
"带出只写别的格子"
)
return problems
@ -1490,7 +1838,7 @@ def validate_schema(fields: Iterable[dict], db=None) -> list[str]:
problems.append(f"「{label}」的列「{column_label}」还没选择要用的层级字典")
elif column_type in OPTION_COLUMN_TYPES and not sourced and column_key not in picked:
problems.append(f"「{label}」的列「{column_label}」既没写选项也没选字典")
for reason in option_source_problems(column, db, column_keys):
for reason in option_source_problems(column, db, column_keys, columns):
problems.append(f"「{label}」的列「{column_label}」{reason}")
if column_type in UNIT_COLUMN_TYPES:
reason = unit_problem(column.get("unit"))
@ -1512,13 +1860,23 @@ def validate_schema(fields: Iterable[dict], db=None) -> list[str]:
problems.extend(
f"「{label}」的列「{column_label}」{reason}" for reason in file_config_problems(column)
)
# 列宽 / 对齐 / 合计 / 上下限:这一列在表格上怎么摆与数字管到哪儿,
# 写歪了都是"存得下来、看上去却没配",保存那一刻说清。
problems.extend(
f"「{label}」的列「{column_label}」{reason}" for reason in column_display_problems(column)
)
min_rows = _int(field.get("minRows"), 0)
max_rows = _int(field.get("maxRows"), 0)
if min_rows and max_rows and min_rows > max_rows:
problems.append(f"「{label}」的最少行数大于最多行数")
if kind == CASCADER_TYPE and not str(field.get("dictCode") or "").strip():
problems.append(f"「{label}」还没选择要用的层级字典")
for reason in option_source_problems(field, db, field_keys):
for reason in option_source_problems(field, db, field_keys, rows):
problems.append(f"「{label}」{reason}")
# 关联单据带出:从挂着的那几张单里取哪一列、写进哪一格。指向掉在地上、合并档
# 与那一格的形状对不上,都是「存得下来、那一格永远是空的」,保存这一刻挡下来。
# 只有主表字段配得上这一层:明细列里的关联单带出是「一行生一批行」,没人能预期。
for reason in _relation_fill().problems(field, field_keys, rows):
problems.append(f"「{label}」{reason}")
if kind == "formula" and not str(field.get("formula") or "").strip():
problems.append(f"「{label}」还没有填写计算公式")

View File

@ -0,0 +1,622 @@
"""关联审批单的「带出」-- 把挂上来的那几张单里的值写进这一张单。
配法长在**候选来源 = 流程单据**的那一格上(``relation`` / ``picker`` / ``select``):
.. code-block:: jsonc
{ "key": "orders", "type": "relation", "optionSource": "process",
"linkFill": { "process": "<可选:设计器按哪个流程列字段>", "rules": [
{ "pick": "work.serial", "to": "src_serial", "agg": "join" },
{ "pick": "data.amount", "to": "items.amount" }
] } }
``pick`` 读的是**对方那张单**。写法不新造:``service/processdata.py`` 本来就把一张单据
整形成 ``{"work": {…}, "data": {…}}`` 喂给「从另一个流程带数据」,这里共用同一份整形
与同一条路径解析(``fetch.pick_path``)——``work.serial`` 是单据本体,``data.报销明细.sum(金额)``
这种筛选与聚合也照用,配过那条路的人会一眼认出来。
``to`` 写的是**这一张单**:主表字段名,或 ``明细表key.列key``。两类去向的行为不一样,
这是整件事的核心:
* **主表字段**只装得下一个值,关联了多张单就得说清「几个数怎么变成一个」。沿用外部
取数那几档合并(``first`` 默认 / ``join`` / ``sum`` / ``min`` / ``max``),口径就是
:func:`app.service.binding.merge` 那一句,不另写一把尺;
* **明细表的列**装得下多行,于是天然就是「一单一行」:按关联顺序补行、取消关联的删行、
人手工改过的其它列一个字都不动。哪一行是从哪张单带来的记在行上的 ``_link`` 那一格
(服务端自己写的留痕:导出、打印、明细导出都只认配好的列,看不见它)。
四条边界:
1. **权威在后端**。填单页上那一份即时预览只是把同一套映射在前端再走一遍
(``frontend/src/utils/linkFill.ts``),提交时引擎在 ``_apply_form_runtime`` 里按
关联的那几张单现算并覆盖——与字典带出、外部取数同一分寸,前端塞不进假值。
2. **明细行只在「关联的那串单变了」时才重排**。人在明细表里手工删掉的一行,不该因为
下一环提交又被复活;而关联一旦变化,该补的补、该删的删,留下来的那几行按来源刷新
配到的那几列。上一次带出用的是哪一串记在 ``data["_linkfill"]`` 里(下划线开头的键
由服务端自己写,页面回传的那一份在 ``engine.without_trace_keys`` 里丢掉)。
3. **一张明细表可以被几个关联字段各带几行**。表单上挂两类单子常常是两格(报销单一格、
采购单一格,两格的字段名根本不是一套),删行的凭据因此不能只看自己这一格:
那一行的来源只要还挂在**别的**关联字段身上,这一格就不许动它。
4. **只挂在主表字段上**。明细列里的关联单据带出的是「这一行的那张单 → 另一张表的行」,
一行生一批行,界面上没人能预期;那一层要带数据,用「从另一个流程带数据」那条源。
"""
from __future__ import annotations
from typing import Any, Callable, Iterable
from sqlalchemy import or_, select
from sqlalchemy.orm import Session
from .. import models
from . import binding, dicts, formruntime, processdata
#: 字段上那份配置的属性名(候选来源=流程单据时才有意义)
LINK_FILL_KEY = "linkFill"
#: 明细行上记「这一行是从哪张关联单据带出来的」那一格;口径在 ``formruntime``(行整型要留它)
ROW_LINK_KEY = formruntime.ROW_LINK_KEY
#: 带出留痕:``{关联字段名: [那串 job]}``,用来判「关联变了没有」,服务端写、页面回传时丢
TRACE_KEY = "_linkfill"
#: 一格最多几条带出映射。再多说明该在对方那张单上做一个汇总口径,而不是在这里抄几十列
MAX_RULES = 30
#: 一次最多带出几张单的数(关联字段本身能挂几十个,超过这个数就是配错了)
MAX_LINKS = 50
#: ``那一串值 -> {值: 单据行}``。运行时就是查库;验收脚本顶一份假的进来,
#: 好把「一单一行、删行、人改过的列不动」这件事跑在没数据库的机器上
Loader = Callable[[list[str]], dict[str, Any]]
#: ``那一批认不出来源的行 -> 其中还挂在别的关联字段身上的那一撮``
Protected = Callable[[set[str]], set[str]]
def _none_protected(candidates: set[str]) -> set[str]:
"""默认那一份:什么都不兜。``apply`` 每趟都现给一份,这一份只是让 ``_sync_rows`` 单用得起。"""
return set()
#: 主表那一路能挑的合并档:与外部取数同一份(``binding.MERGE_MODES``),去掉没有意义的
#: 说法在这里没有意义——几个来源合成一个值与几张单据合成一个值是同一件事
MERGE_MODES = binding.MERGE_MODES
#: 要数的三档:目标格得是装得下数的那一类
NUMERIC_AGGS = binding.NUMERIC_MERGE_MODES
#: 空值该写成什么形状:装一串值的列空着是 ``[]``,不是 ``""``
LIST_BLANK_TYPES = (
"checkbox", "user", "months", "week", "daterange", "timerange",
"attachment", "image", "relation",
)
# ---------------------------------------------------------------------------
# 配置:读、整形、设计期校验
# ---------------------------------------------------------------------------
def clean_rule(raw: Any) -> dict[str, str]:
"""一条映射补成字段齐全的安全配置;认不出的写法丢掉,不猜「他想干什么」。"""
if not isinstance(raw, dict):
return {}
pick = str(raw.get("pick") or "").strip()
to = str(raw.get("to") or "").strip()
if not pick or not to:
return {}
agg = str(raw.get("agg") or "").strip()
if agg not in MERGE_MODES:
agg = ""
out: dict[str, str] = {"pick": pick, "to": to}
# 跟默认一模一样的不留(与 ``clean_option_source`` 收 optionMap 同一分寸):
# 冗余配置只会让下一任配的人以为它有什么特别的
if agg and agg != "first":
out["agg"] = agg
separator = raw.get("separator")
# 分隔符原样留着,**不 strip**:「 / 」和「/」拼出来的单号不一样,
# 而它只在「拼接」那一档有意义,别的档留着只是残骸
if agg == "join" and isinstance(separator, str) and separator.strip() \
and separator != binding.DEFAULT_SEPARATOR:
out["separator"] = separator
return out
def clean(cfg: Any) -> dict[str, Any]:
"""字段上那份 ``linkFill`` 收成干净形状;没配上就回空字典(等于没配)。"""
src = cfg if isinstance(cfg, dict) else {}
rules = [item for item in (clean_rule(one) for one in (src.get("rules") or [])) if item]
out: dict[str, Any] = {"rules": rules[:MAX_RULES]}
process = str(src.get("process") or "").strip()
if process:
out["process"] = process
return out if rules else {}
def configured(field: dict) -> dict[str, Any]:
"""这一格真正生效的带出配置;没配、配歪、来源不是流程单据,一律回空字典。"""
if not isinstance(field, dict):
return {}
if dicts.source_kind_of(field) != dicts.SOURCE_PROCESS:
return {}
return clean(field.get(LINK_FILL_KEY))
def targets(field: dict) -> list[str]:
"""这份配置写进哪些格子(主表字段名或 ``表.列``),删字段与改名那两处用它。"""
return [str(item.get("to") or "") for item in configured(field).get("rules") or []]
def split_target(to: str, fields: Iterable[dict]) -> tuple[str, str]:
"""``to`` 指的是主表那一格,还是某张明细表的某一列。
先整串认主表字段名,认不出才按第一个点拆成「表.列」:主表字段名允许带点(这里不
禁止,禁了等于改一遍所有老表单),整串优先命中就把歧义定死在一侧。
"""
text = str(to or "").strip()
if not text:
return "", ""
tables = {
str(item.get("key") or "").strip(): item
for item in fields or []
if isinstance(item, dict) and str(item.get("type") or "") == "table"
}
if text in {str(item.get("key") or "").strip() for item in fields or [] if isinstance(item, dict)}:
return text, ""
table_key, _, column_key = text.partition(".")
if table_key in tables and any(
str(one.get("key") or "").strip() == column_key
for one in formruntime.columns_of(tables[table_key])
):
return table_key, column_key
return "", ""
def problems(field: dict, keys: set[str], fields: Iterable[dict] = ()) -> list[str]:
"""这一格的关联带出配歪了没有,几句话说明白(前端镜像 ``utils/linkFill.linkFillProblems``)。
管四件:来源不是流程单据(存得下来但永远不带)、没写清从哪一列取或写进哪一格、
指向的格子早就不在了、合并档与目标格的形状对不上。都是「配的时候看不出来、
填单的时候那一格是空的」那类毛病,所以保存这一刻挡下来。
"""
rows = [item for item in (fields or []) if isinstance(item, dict)]
cfg = clean(field.get(LINK_FILL_KEY))
if not cfg:
raw = field.get(LINK_FILL_KEY)
if isinstance(raw, dict) and (raw.get("rules") or []):
return ["关联带出没写清从关联单据取哪一列、写进哪一格"]
return []
if dicts.source_kind_of(field) != dicts.SOURCE_PROCESS:
return ["只有候选来源是「流程单据」的字段能配关联带出"]
out: list[str] = []
seen: set[str] = set()
for rule in cfg["rules"]:
pick = str(rule.get("pick") or "")
to = str(rule.get("to") or "")
if to in seen:
out.append(f"有两条带出都写进「{to}」这一格,后一条永远盖掉前一条")
seen.add(to)
if not pick.startswith(("work.", "data.")):
out.append(f"「{pick}」看不出要从关联单据的哪一列取:单据本体写 work.字段,对方表单字段写 data.字段")
continue
agg = str(rule.get("agg") or "first")
if agg not in MERGE_MODES:
out.append(f"写进「{to}」的那条带出不认识合并方式「{agg}」")
table_key, column_key = split_target(to, rows)
if not table_key:
out.append(f"要把「{pick}」带进不存在的字段「{to}」")
continue
if not column_key:
if agg in NUMERIC_AGGS and not _numeric_field(_find(rows, table_key)):
label = str(_find(rows, table_key).get("label") or table_key)
out.append(f"「{label}」装不下数,「{agg}」这一档合不出来;要文本请选「拼接」或「取第一个」")
continue
column = _column(rows, table_key, column_key)
if agg in NUMERIC_AGGS and not _numeric_field(column):
label = str(column.get("label") or column_key)
out.append(
f"明细表「{_label(rows, table_key)}」的列「{label}」装不下数,「{agg}」这一档合不出来"
)
return out
def _find(rows: list[dict], key: str) -> dict:
return next((item for item in rows if str(item.get("key") or "").strip() == key), {})
def _column(rows: list[dict], table_key: str, column_key: str) -> dict:
table = _find(rows, table_key)
return next(
(
item
for item in formruntime.columns_of(table)
if str(item.get("key") or "").strip() == column_key
),
{},
)
def _label(rows: list[dict], key: str) -> str:
item = _find(rows, key)
return str(item.get("label") or key)
def _numeric_field(item: dict) -> bool:
"""这一格装不装得下一个数:数字、金额、公式三格认,其余不认。"""
return str((item or {}).get("type") or "") in ("number", "money", "formula")
# ---------------------------------------------------------------------------
# 取值:关联的那串值 → 那几张单 → 每一列的值
# ---------------------------------------------------------------------------
def stored_values(field: dict, data: dict) -> list[str]:
"""这一格现在挂着的那几张单(存的可能是 job,也可能被配成存单号)。"""
raw = (data or {}).get(str(field.get("key") or ""))
values = raw if isinstance(raw, list) else ([] if raw in (None, "") else [raw])
out: list[str] = []
for item in values:
text = str(item if item is not None else "").strip()
if text and text not in out:
out.append(text)
return out[:MAX_LINKS]
def works_by_values(db: Session, values: Iterable[str], *, extra: Any = None) -> dict[str, Any]:
"""那一串值 → 单据行:按 job 认,认不出再按单号认(这一格可以配成存单号那一列)。
引擎那一路**不按「当前人看不看得见」筛**:这些值是发起那一环挑上的,挑的人当然
看得见;到了第二环,处理人跟那张单可能没关系,照可见性筛会让带出的值在环节之后
悄悄变空。权限的边界在「谁能把这张单挂上来」那一步(``GET /work/related`` 限
「我发起 / 我办过 / 我被抄送」),不在这里。
``extra(model)`` 是给**预览那一路**留的闸:显示可以比落库保守(照
``GET /work/summaries`` 同一分寸,看不见的静默少回),回 ``None`` 等于不加筛子。
"""
wanted = [text for text in (str(item or "").strip() for item in values or []) if text]
if not wanted:
return {}
found: dict[str, Any] = {}
for model in (models.Work, models.WorkCompleted):
stmt = select(model).where(or_(model.job.in_(wanted), model.serial.in_(wanted)))
if model is models.Work:
stmt = stmt.where(model.deleted.is_(False))
if extra is not None:
clause = extra(model)
if clause is not None:
stmt = stmt.where(clause)
for row in db.execute(stmt).scalars().all():
for key in (str(row.job or ""), str(row.serial or "")):
if key and key in wanted and key not in found:
found[key] = row
return {item: found[item] for item in wanted if item in found}
def payload_of(row: Any) -> dict[str, Any]:
"""一张单据 → 路径解析吃的那份「响应」:``{"work": {…}, "data": {…}}``。
直接复用 :func:`app.service.processdata.payload_of`,于是 ``pick`` 的写法在
「关联带出」与「从另一个流程带数据」两条路上一字不差。
"""
return processdata.payload_of(row)
def pick_value(payload: dict, path: str) -> Any:
"""按 ``pick`` 从那一张单里取一个值;取不到回 ``None``。"""
from . import fetch # 延迟导入:fetch 这条链上随时可能反过来 import 本模块
return fetch.pick_path(payload, str(path or "").strip())
def values_of(
db: Session | None,
values: Iterable[str],
picks: Iterable[str],
*,
loader: Loader | None = None,
extra: Any = None,
) -> list[dict[str, Any]]:
"""按关联顺序回每单一份取值结果:``[{"job": …, "value": 问出去的那一句, "values": {pick: 值}}]``。
填单页面上那一份即时预览用它(``POST /work/relation-values``)。路径解析只留
后端这一份实现,前端不必再镜像一遍 ``fetch.pick_path`` 那套筛选与聚合写法。
``extra`` 是预览那一路的可见性闸(引擎那一路不带,见 :func:`works_by_values`)。
"""
paths = [text for text in (str(item or "").strip() for item in picks or []) if text]
if not paths:
return []
rows = (loader or _loader(db, extra))(list(values or []))
out: list[dict[str, Any]] = []
seen: set[str] = set()
for item in values:
wanted = str(item or "").strip()
row = rows.get(wanted)
if row is None:
continue
job = str(row.job or "")
if job in seen:
continue
seen.add(job)
payload = payload_of(row)
# ``value`` 回的是**调用方问出去的那一句**,不是 job:这一格可以配成存单号
# (``optionMap.valueKey = serial``),只回 job 会让预览那头认不出自己挂上来的是
# 哪一张,按 job 一过滤就把明细表整个丢空。
out.append({
"job": job,
"value": wanted,
"values": {path: pick_value(payload, path) for path in paths},
})
return out
def _blank_for(kind: str) -> Any:
return [] if str(kind or "") in LIST_BLANK_TYPES else ""
def _shape(value: Any, kind: str) -> Any:
"""把带出来的值整成目标那一格认的写法。
只有三类加工,都是有来由的:取不到值给一个形状正确的空(``[]`` / ``""``,不是 ``None``);
数字那两格把「1,200.00」这种带分隔符的文本收成数;日期时间那两格统一成控件认的
``T`` 写法(单据本体上的时间是 ``YYYY-MM-DD HH:MM:SS``,直接落进 ``datetime`` 格就是空白)。
"""
text_kind = str(kind or "")
if value is None:
return _blank_for(text_kind)
if text_kind in ("number", "money", "formula"):
number = _number(value)
return value if number is None else number
if isinstance(value, str):
if text_kind == "datetime":
body = value.strip().replace(" ", "T")
return body[:16] if len(body) >= 16 else body
if text_kind == "date":
return value.strip()[:10]
return value
def _number(value: Any) -> float | None:
"""能当数看就当数看;``"1,200.00"`` 这种带分隔符的也认(金额字段常常这么存)。"""
if isinstance(value, bool):
return None
if isinstance(value, (int, float)):
return float(value)
text = str(value if value is not None else "").strip().replace(",", "")
if not text:
return None
try:
return float(text)
except ValueError:
return None
def merged(values: list[Any], agg: str, separator: str = "") -> Any:
"""几张单的数合成主表那一个值;口径就是外部取数那一句(``binding.merge``)。"""
return binding.merge(agg or "first", values, separator=separator or binding.DEFAULT_SEPARATOR)
# ---------------------------------------------------------------------------
# 落库:引擎在每次提交时按关联的那几张单重算
# ---------------------------------------------------------------------------
def rules_of(field: dict, fields: Iterable[dict]) -> tuple[list[dict], dict[str, dict[str, str]]]:
"""把一份配置拆成两拨去向:``(主表那几条, {明细表名: {列名: pick}})``。
指向已经不存在的格子 / 表的规则在这儿就掉出去——运行时那一道闸与
``service/binding.live_target`` 是同一个理由:格子名会被复用,把别的单的数悄悄盖到
同名新格子上,比少带一格危险得多。
"""
rows = [item for item in (fields or []) if isinstance(item, dict)]
tables = {
str(item.get("key") or "").strip(): item
for item in rows
if str(item.get("type") or "") == "table" and item.get("key")
}
main: list[dict] = []
columns: dict[str, dict[str, str]] = {}
for rule in configured(field).get("rules") or []:
pick = str(rule.get("pick") or "")
to = str(rule.get("to") or "")
table_key, column_key = split_target(to, rows)
if not table_key:
continue
if column_key:
if table_key in tables:
columns.setdefault(table_key, {})[column_key] = pick
continue
main.append({
"to": table_key,
"pick": pick,
"agg": str(rule.get("agg") or "first"),
"separator": str(rule.get("separator") or ""),
"kind": str(_find(rows, table_key).get("type") or ""),
})
return main, columns
def apply(
db: Session | None, fields: Iterable[dict], data: dict, *, loader: Loader | None = None
) -> list[str]:
"""把所有配了关联带出的格子按当前关联重算一遍,返回真正被改动的字段名。
调用位置在 ``engine._apply_form_runtime`` 里,紧跟字典带出与外部取数、排在公式之前:
「关联单的金额合计」这类公式要读到的就是这一轮刚补好的那几行明细。
"""
rows = [item for item in (fields or []) if isinstance(item, dict)]
body = data or {}
load = loader or _loader(db)
trace = body.get(TRACE_KEY) if isinstance(body.get(TRACE_KEY), dict) else {}
# 每个候选来源=流程单据的格子此刻挂着的那串值(job 与单号混着都算)。删行之前拿
# **别的格子那几串**兜一道:同一张明细表可以被两个关联字段各带几行(报销单一格、
# 采购单一格,两格各配各的映射),这一格重排时不能把别人带来的行当成
# 「自己这边取消关联了」给删掉。
linked_by: dict[str, set[str]] = {}
for item in rows:
name = str(item.get("key") or "").strip()
if name and dicts.source_kind_of(item) == dicts.SOURCE_PROCESS:
linked_by[name] = set(stored_values(item, body))
all_linked = set().union(*linked_by.values()) if linked_by else set()
tables = {
str(item.get("key") or "").strip(): item
for item in rows
if str(item.get("type") or "") == "table" and item.get("key")
}
touched: list[str] = []
writing = False
for field in rows:
if not configured(field):
continue
key = str(field.get("key") or "").strip()
if not key:
continue
main, columns = rules_of(field, rows)
values = stored_values(field, body)
# 除自己以外,别人手上还挂着的那些单
elsewhere = all_linked - linked_by.get(key, set())
before = list(trace.get(key) or []) if isinstance(trace.get(key), list) else []
# 关联没动、而这一格又只往明细表里带:一行都不用重排,也就不用去问那几张单
if not main and before == values:
continue
# 记的是**这一格存着的那串值**,不是查得到的那几张单:挂上一张暂时查不到的单
# (草稿被删、单号写歪)也算「关联变了」,得重排一次;按查得到的算会让这一轮
# 什么也没发生,等那张单哪天又查得着了,行早就跟关联对不上了。
jobs_changed = before != values
if jobs_changed:
writing = True
trace[key] = values
ordered = _ordered_payloads(load, values)
for rule in main:
picked = [pick_value(payload, rule["pick"]) for _, payload in ordered]
value = merged(picked, rule["agg"], rule["separator"])
shaped = _shape(value, rule["kind"])
if body.get(rule["to"]) == shaped:
continue
body[rule["to"]] = shaped
if rule["to"] not in touched:
touched.append(rule["to"])
for table_key, mapping in columns.items():
table = tables.get(table_key) or {}
next_rows, changed = _sync_rows(
body.get(table_key), ordered, mapping, table, resync=jobs_changed,
protected=_protector(load, elsewhere),
)
if changed:
body[table_key] = next_rows
if table_key not in touched:
touched.append(table_key)
if writing:
body[TRACE_KEY] = trace
return touched
def _loader(db: Session | None, extra: Any = None) -> "Loader":
"""默认那份取单:按这一格存着的那串值去库里捞。"""
return lambda values: works_by_values(db, values, extra=extra)
def _ordered_payloads(load: "Loader", values: list[str]) -> list[tuple[str, dict]]:
"""按关联顺序排好的 ``[(job, payload)]``;认不出的那张(删了 / 归档也没了)自然不在里面。"""
rows = load(values)
out: list[tuple[str, dict]] = []
seen: set[str] = set()
for item in values:
row = rows.get(item)
if row is None:
continue
job = str(row.job or "")
if not job or job in seen:
continue
seen.add(job)
out.append((job, payload_of(row)))
return out
def _protector(load: "Loader", elsewhere: set[str]) -> "Protected":
"""``删之前问一句``:那一行的来源是不是还挂在别的关联字段身上。
别的字段那一串值存的可能是 job,也可能是单号(``optionMap.valueKey`` 配过),
所以手上只有 job 的那一批要先换成单号再比。只在真有可能是孤儿行时才问这一趟。
"""
def protect(candidates: set[str]) -> set[str]:
if not candidates or not elsewhere:
return set()
out = {job for job in candidates if job in elsewhere}
rest = sorted(candidates - out)
if rest:
for job, row in load(rest).items():
serial = str(getattr(row, "serial", "") or "")
if serial and serial in elsewhere:
out.add(job)
return out
return protect
def _sync_rows(
value: Any,
ordered: list[tuple[str, dict]],
mapping: dict[str, str],
table: dict,
*,
resync: bool,
protected: "Protected" = _none_protected,
) -> tuple[list[dict], bool]:
"""明细表那一路的行同步:新关联的补行、取消关联的删行、留下的行按来源刷新配到的列。
``resync=False``(关联没变)时原样带回:人在这一轮里手工删过、加过、改过的行不动——
带出替他把行摆好,不该替他把活儿重做一遍。
``protected`` 是「这一行还挂在别的关联字段身上」那一道兜底,撞上就原样留着。
"""
rows = formruntime.rows_of(value)
if not resync:
return rows, False
columns = formruntime.columns_of(table)
payload_by_job = {job: payload for job, payload in ordered}
linked = {job for job, _ in ordered}
keep = protected({
str(row.get(ROW_LINK_KEY) or "").strip()
for row in rows
if str(row.get(ROW_LINK_KEY) or "").strip() not in linked
})
out: list[dict] = []
used: set[str] = set()
for row in rows:
job = str(row.get(ROW_LINK_KEY) or "").strip()
if not job:
out.append(row) # 人自己加的行:不认来源,也就一动不动
continue
if job not in linked:
if job in keep:
out.append(row) # 这一行是别的关联字段带来的:这一格不认它,也不动它
# 不然就是这一行的来源已经取消关联:跟着走
continue
used.add(job)
refreshed = dict(row)
for column_key, pick in mapping.items():
refreshed[column_key] = _shape(
pick_value(payload_by_job.get(job) or {}, pick), _column_kind(columns, column_key)
)
out.append(refreshed)
for job, payload in ordered:
if job in used:
continue
# 新行的形状与人点「+」加出来的那一行一致(每一列都在,没配的留一个形状正确的空),
# 否则明细表上会出现「这一行怎么少了几格」那种一看就不对劲的行
row = {ROW_LINK_KEY: job}
for column in columns:
key = str(column.get("key") or "").strip()
if key:
row[key] = _blank_for(str(column.get("type") or ""))
for column_key, pick in mapping.items():
row[column_key] = _shape(pick_value(payload, pick), _column_kind(columns, column_key))
out.append(formruntime.fill_row_defaults(columns, row))
max_rows = formruntime.max_rows_of(table)
if max_rows:
out = out[:max_rows]
return out, _rows_differ(rows, out)
def _column_kind(columns: list[dict], key: str) -> str:
return str(next((str(item.get("type") or "") for item in columns
if str(item.get("key") or "").strip() == key), ""))
def _rows_differ(before: list[dict], after: list[dict]) -> bool:
"""改动过没有:逐行逐格比内容,不比对象引用(JSON 列要靠值判定有没有写回去)。"""
if len(before) != len(after):
return True
return any(one != other for one, other in zip(before, after))

View File

@ -1096,6 +1096,9 @@ def condition_fields(condition: object) -> list[str]:
写回挂载上的 ``when`` 用的是同一份数据结构,所以也共用同一把校验尺子:
条件指向一个表单里不存在的字段,等于这条写回永远不发,且没人会被通知。
右边那一个(``valueField``,比的是另一格)同样算引用:那一格被删掉之后条件照判,
只是读回来永远是空值——「满足条件才发」静默变成「一张都不发」,正是最难查的那种。
"""
if isinstance(condition, list):
condition = {"rules": condition}
@ -1105,9 +1108,10 @@ def condition_fields(condition: object) -> list[str]:
for rule in condition.get("rules") or []:
if not isinstance(rule, dict):
continue
name = str(rule.get("field") or "").strip()
if name and name not in out:
out.append(name)
for raw in (rule.get("field"), rule.get("valueField")):
name = str(raw or "").strip()
if name and name not in out:
out.append(name)
return out

View File

@ -696,7 +696,10 @@ DECIDE_WHEN = ("按下这一环的审批按钮:这一趟的主活。环节那
#: locate(拉),两条路是加法不是替换,凭据同一把访问令牌。
CARD_EVENTS: tuple[tuple[str, str], ...] = (
("task.arrived", "走到这一环了:信封里带待办号与这张卡片,收到就知道该出手"),
("task.completed", "这一环已由人从 OA 界面办掉:不用再表态"),
# 那句「已由人办掉」以前是说死的:管理员改道收走、会签凑票自动结掉、整单终止,
# 在这一档里都读成"有人同意了"。取值表在 docs/node-open-approve-design.md §4.4。
("task.completed", "这一环结束了:不用再表态。带 processingType 说清怎么结的,"
"只有 normal 是真人按的钮"),
("work.completed", "单据办结"),
("work.terminated", "单据终止"),
("work.canceled", "单据作废"),
@ -1637,6 +1640,23 @@ def staged_for_work(db: Session, work_id: str, activity_id: str) -> list[models.
return [row for row in rows if row.status == STATUS_STAGED]
def staged_for_any_activity(db: Session, work_id: str) -> list[models.NodeDecision]:
"""这张单上所有还停着等点头的表态,不分环节(``staged_for_work`` 只认某一环)。
干预改道之前要用它报一句「会作废 N 条第三方表态」——那些话是改道**之前**、按改道
之前的表单说的,改完道就不作数了。已过有效期的那些不算:它们本来就不生效。
"""
rows = list(db.execute(
select(models.NodeDecision)
.where(
models.NodeDecision.work == work_id,
models.NodeDecision.status == STATUS_STAGED,
)
.order_by(models.NodeDecision.id)
).scalars().all())
return [row for row in rows if not decision_expired(row)]
def staged_for_task(db: Session, task_id: str) -> list[models.NodeDecision]:
"""这条待办上还挂着哪些没点头的外部表态。过期的当场作废,别让审批页亮着死横幅。"""
rows = list(
@ -1837,18 +1857,23 @@ def replay(row: models.NodeDecision, db: Session | None = None) -> dict:
raise bad_request(note, reason="NODE_DECISION_CLOSED")
def invalidate_for_work(db: Session, work_id: str, status: str) -> int:
"""单据落定(办结 / 终止 / 作废)时,这张单上所有还停着的表态就地作废。
def invalidate_for_work(db: Session, work_id: str, status: str, *, note: str = "") -> int:
"""这张单上所有还停着的表态就地作废:单据落定(办结 / 终止 / 作废)或被人改道。
同一事务里跑:归档与表态作废要么一起成、要么一起滚,别让审批页亮着一条
指向死人单据的横幅。返回作废条数;一张单一次表态都没有时这里是安静的一步。
``note`` 是给改道那一档留的:那张单还活着,"单据已落定"说不清是回事,
要写的是「谁把它挪走了、这一环的表态因此作废」。
"""
from sqlalchemy import update
label = {"completed": "办结", "terminated": "终止", "canceled": "作废"}.get(status, status or "落定")
if not note:
label = {"completed": "办结", "terminated": "终止", "canceled": "作废"}.get(status, status or "落定")
note = f"单据已{label},表态一并作废"
rows = db.execute(
update(models.NodeDecision)
.where(models.NodeDecision.work == work_id, models.NodeDecision.status == STATUS_STAGED)
.values(status=STATUS_EXPIRED, confirm_note=f"单据已{label},表态一并作废")
.values(status=STATUS_EXPIRED, confirm_note=note[:512])
)
return rows.rowcount or 0

View File

@ -0,0 +1,121 @@
"""站内信跟着事项收尾:待办办完了,那句「您有新的待办」就该退场。
症状
====
待办全部办完,右上角铃铛里那叠通知消息还挂着、小红点也不灭。面板上四条
「您有新的待办」,对应的四张单早就从自己手里过去了,只能靠「全部已读」手动清。
原因
====
``oa_notification`` 只在写进去的那一刻有人看,之后没有任何一处回收它:
:func:`app.engine.engine.notify` 发完就不管,接口那边只有「点开算已读」与
「全部已读」两个手动口子。而待办本身是**会消失的**——``engine._complete_task``
直接删行、或签把同级待办一起结掉、转办与交接换持有人、终止与办结清空整单,
每一条都不回头动站内信。
口径
====
一条提醒还值不值得摆着,看它指向的那件事**还在不在收件人自己手上**:
* ``task`` / ``press`` / ``expire``——要人办事的那三类(与 ``channels.HUB_TASK_EVENTS``
同一族,点开都落待办页)。``task`` 有值就按那一条待办判;``task`` 是空的老数据
(会签 / 加签 / 转办那一批一条消息带多个收件人,当初没记待办号)退一步按
「这一单上还有没有我的待办」判。
* ``read``——抄送 / 分享 / 评论,按「这一单上还有没有我的待阅」判。
* 其余(``completed`` 办结结果、``control`` 挂起恢复改派、``meeting`` 会议、
``integration`` / ``check`` 对接留痕)说的是**已经发生的一件事**,不指向任何
要办的东西,永远不动。
收在读的那一侧,不是写的那一侧
==============================
待办消失的路子有七八条(办结、或签自动结、转办、交接、退回、撤回、终止、管理员
改派),一处漏挂一句就是又一个「通知还挂着」;而且库里那些早就该退的存量通知
也补不回来。所以这一层收在**读出口**:列表、未读数、工作台三处回答之前,先按
本人身份收一次尾。一条 UPDATE 判完,八条路子连历史数据一起管住。
收尾是**标已读**,不是删行:投递记录(``oa_notify_delivery.notification``)要能
回查对应的那条站内信,「谁在什么时候收到过什么」也不该因为事项办结就从库里蒸发。
"""
from __future__ import annotations
from datetime import datetime
from sqlalchemy import and_, or_, select, update
from sqlalchemy.orm import Session
from .. import models
#: 指向一条待办、点开就要人办事的三类站内信。取值与 ``oa_notification.type`` 一致,
#: 也与 ``channels.EVENTS`` 里那三个要落待办页的事件同一族。
TASK_TYPES = ("task", "press", "expire")
#: 指向一条待阅的那一类(抄送 / 分享 / 评论都从这里出)。
READ_TYPES = ("read",)
def settle(db: Session, identity: str, *, now: datetime | None = None) -> int:
"""把「指向的事项已经不在本人手上」的未读站内信标成已读,返回收尾的条数。
两条 UPDATE 各判一族,里面三条判据各管一种情形。**两条都带 ``identity = ?``**:
这是站内信唯一的索引,也正是这批行的天然边界(一次收尾只动收件人自己那几条),
剩下的 ``type`` / ``task`` / ``work`` 都只在一个人那几十上百行里做残余筛选;
子查询那头点的分别是 ``oa_task`` 主键、``idx_oa_task_work``、``idx_oa_read_work``。
**不提交**:调用方与本次请求里别的改动一起提交(没人写库时也不该被迫写一次)。
``identity`` 为空就直接返回 0——没登录身份就没有可收尾的那批人。
"""
if not identity:
return 0
moment = now or datetime.now()
# 两条都从"这个收件人还没读过的"起筛
unread = (
models.Notification.identity == identity,
models.Notification.read.is_(False),
)
retired = int(db.execute(
update(models.Notification)
.where(
*unread,
models.Notification.type.in_(TASK_TYPES),
or_(
# 一:带事项号的那一条已经不在我手上——办完了、转走了、
# 被或签一起结掉、整单终止,每一种都是这一条判据
and_(
models.Notification.task != "",
~select(models.Task.id).where(
models.Task.id == models.Notification.task,
models.Task.identity == identity,
).exists(),
),
# 二:老数据没记事项号,退一步看这一单上还有没有我的待办
and_(
models.Notification.work != "",
~select(models.Task.id).where(
models.Task.work == models.Notification.work,
models.Task.identity == identity,
).exists(),
),
),
)
.values(read=True, read_time=moment)
).rowcount or 0)
# 三:抄送那一族——这一单上已经没有我的待阅了
retired += int(db.execute(
update(models.Notification)
.where(
*unread,
models.Notification.type.in_(READ_TYPES),
# 已阅登记与办结搬档都是删行;压根没打开过的那类留在 oa_read 里等本人
# 来读(engine._finish_work 不替人编一个"已阅时间"),通知就照旧挂着
and_(
models.Notification.work != "",
~select(models.Read.id).where(
models.Read.work == models.Notification.work,
models.Read.identity == identity,
).exists(),
),
)
.values(read=True, read_time=moment)
).rowcount or 0)
return retired

View File

@ -1514,11 +1514,19 @@ def simulate(
runtime_notes.append((LEVEL_ERROR, f"阈值规则会挡住这张单:{exc}"))
except Exception as exc: # noqa: BLE001 - 规则算崩了别谎报成"会挡住",那会让人去改一张没毛病的画布
runtime_notes.append((LEVEL_WARN, f"阈值规则算不出来,这一单到底挡不挡没法预判:{exc}"))
for fetch_field, _cfg in fetch_module.fetch_fields(fields):
# 主表那一格与明细列那一格都要提一句:试跑不发请求,这两条路的值都可能对不上
fetch_names = [
str(item.get("label") or item.get("key") or "") for item, _cfg in fetch_module.fetch_fields(fields)
] + [
f"明细表「{table.get('label') or table.get('key')}」的列"
f"「{column.get('label') or column.get('key')}」"
for table, column, _cfg in fetch_module.row_fetch_fields(fields)
]
for shown in fetch_names:
runtime_notes.append(
(
LEVEL_INFO,
f"字段「{fetch_field.get('label') or fetch_field.get('key')}」的值要从外部数据源带,试跑不发请求;"
f"字段「{shown}」的值要从外部数据源带,试跑不发请求;"
"条件若依赖它,真跑时结果可能不一样",
)
)

View File

@ -906,18 +906,18 @@ def _lookup(
column = _column_of(field, column_key)
if not rows or column is None:
return ""
return _field_text(db, column, rows[0].get(str(column.get("key") or "")), cache)
return _field_text(db, column, rows[0].get(str(column.get("key") or "")), cache, data=rows[0])
for item in SYSTEM_VARIABLES:
if name != item["key"] and name not in item["aliases"]:
continue
return _system_text(db, item, fmt=fmt, process=process, data=data, actor=actor, work=work)
field = fields.get(name)
if field is not None:
return _field_text(db, field, data.get(name), cache)
return _field_text(db, field, data.get(name), cache, data=data)
# 字段也可以按中文名引用,模板读起来更像人话。
for key, item in fields.items():
if str(item.get("label") or "") == name:
return _field_text(db, item, data.get(key), cache)
return _field_text(db, item, data.get(key), cache, data=data)
# 认不出来的变量留个空串:设计器用 unknown_tokens() 能查出来是哪一个写错了。
return ""
@ -1050,11 +1050,19 @@ def process_of_form(db: Session, form_id: str):
).scalars().first()
def _field_text(db: Session, field: dict, value: Any, cache: dicts.DictCache) -> str:
"""字段值落地成标题里的一小段文本:选项翻标签,人员/部门翻名字,明细表只报行数。"""
kind = str(field.get("type") or "")
def _field_text(
db: Session, field: dict, value: Any, cache: dicts.DictCache, data: dict | None = None
) -> str:
"""字段值落地成标题里的一小段文本:选项翻标签,人员/部门翻名字,明细表只报行数。
``data`` 是这张单的那一份值:挂了候选路由的格子要先按它挑中那一条再翻名字,
不然同一格这一单念差标、那一单念费用科目,标题会翻错家。不给就按字段自己那一份。
"""
if value is None or (isinstance(value, str) and not value.strip()):
return ""
if data is not None:
field = dicts.option_view(field, data)
kind = str(field.get("type") or "")
if kind in ("select", "radio", "checkbox"):
return dicts.option_labels(field, value, cache)
if kind == formruntime.CASCADER_TYPE:

View File

@ -23,7 +23,11 @@
记的都是字段名,格子没了那份指向还留着(设计器现在会清,改之前存下的表单靠这道闸兜住),
往不存在的格子里写不算什么,键名被新字段复用之后把别人的数盖掉才是事。
7. **选人字段当 SQL 入参要包一层 account**:``type=user`` 那一格交出来的永远是账号
7. **关联审批单默认只给归档通过的单子**:字段上那三档(归档通过 / 还在办 / 已终止或作废)
说清能挂哪几种状态的单据,前端 ``utils/optionSource.ts`` 与后端 ``service/dicts.py``
同一份;这一档只管候选列表,已存的值不判非法。
8. **选人字段当 SQL 入参要包一层 account**:``type=user`` 那一格交出来的永远是账号
**数组**,``= :applicant`` 绑不进数组,运行时只能 blocked。病根在配置里,所以设计期
(``binding.arg_ref_problems`` 的 ``person_keys``)就要报出「改成 ``{account:form.x}``」,
而且只对真带 SQL 的那张源说——HTTP 报文里放数组是正当写法。
@ -371,23 +375,93 @@ def check_option_source_problems() -> None:
["候选来源那张数据源的入参「category」引用了这一格自己:候选按这一格筛,"
"这一格又只能从候选里挑,绕成圈筛不出东西"])
# 交叉规则:值由外部取数写入,候选又是判越界的那两种来源
# 交叉规则:值由外部取数写入,候选又是判越界的那两种来源。
# ``pick`` 写的是**这一格自己**——只配 picks 往别处写的取数不会盖这一格挑中的值,不算打脸
cross = formruntime.option_source_problems(
option_field(optionSource="manual", options=[{"label": "甲", "value": "A"}],
fetch={"source": "erp"}))
fetch={"source": "erp", "pick": "level"}))
eq("取数写值 + 手填候选要说交叉规则",
[text for text in cross if "外部取数写入" in text],
["这一格的值由外部取数写入,候选又来自手填选项:取回来的编码必须在那份清单里,"
"否则提交时会被判「取值已不在可选范围内」。请把取数带回的值补进这份清单,"
"或把候选来源改成外部数据源 / 流程单据"])
"否则提交时会被判「取值已不在可选范围内」。请把带回来的值补进这份清单,"
"把候选来源改成外部数据源 / 流程单据,"
"或勾上「带出的值不在候选里也收下」"])
dict_cross = formruntime.option_source_problems(
option_field(optionSource="dict", dictCode="mat", fetch={"source": "erp"}))
option_field(optionSource="dict", dictCode="mat", fetch={"source": "erp", "pick": "level"}))
ok("取数写值 + 字典候选也要说", any("候选又来自数据字典" in text for text in dict_cross), dict_cross)
eq("取数只往别的格子写,不盖这一格挑中的值,不说打脸",
[text for text in formruntime.option_source_problems(
option_field(optionSource="dict", dictCode="mat",
fetch={"source": "erp", "picks": {"price": "amount"}})) if "打脸" in text or "外部取数写入" in text],
[])
no_clash = formruntime.option_source_problems(
option_field(optionSource="dataSource", dataSourceCode="erp", fetch={"source": "crm"}), db=None)
eq("候选本身也是外部数据源时不打脸,不说", no_clash, [])
eq("不是选择类的字段不管", formruntime.option_source_problems(
{"key": "amount", "type": "number", "fetch": {"source": "erp"}}), [])
# 那句「或勾上」给的这一档真能把交叉规则关掉:勾了就不再拦填单的人(见 check_option_routes.py)
opened = formruntime.option_source_problems(
option_field(optionSource="manual", options=[{"label": "甲", "value": "A"}],
fetch={"source": "erp", "pick": "level"}, allowOutsideValue=True))
eq("勾了「带出的值也收下」之后不再说交叉规则", opened, [])
idle = formruntime.option_source_problems(
option_field(optionSource="manual", options=[{"label": "甲", "value": "A"}],
allowOutsideValue=True))
eq("什么都没带出却勾了这一档,要说它不起作用", idle,
["这一格没配任何带出(外部取数 / 关联单据带出 / 字典带出),"
"「带出的值不在候选里也收下」这一档暂时不起作用"])
eq("这一档只认真布尔值", formruntime.option_source_problems(
option_field(optionSource="manual", options=[{"label": "甲", "value": "A"}],
fetch={"source": "erp", "pick": "level"}, allowOutsideValue="true"))[0],
"「带出的值不在候选里也收下」这一档要勾成是或否")
# ---------------------------------------------------------------------------
# 4.4 关联审批单能挂哪几种状态的单据
# ---------------------------------------------------------------------------
def check_relation_statuses() -> None:
"""「关联已审批流程」挑到一张半路被终止的单子——这一档管的就是这件事。
单据只活两张表:在办表只有 ``running``,归档表里躺着 ``completed`` / ``terminated`` /
``canceled``。默认只给归档通过的,界面上三档由字段上说;这一档只管候选列不列它,
已存的值不判非法(单据是挂上之后才被终止的,回显照样念得出标题)。
"""
relation = {"key": "rel", "type": "relation"}
# 没配、配空、配了认不出的:都退回默认那一档,别把候选捞成空的
eq("没配过就只给归档通过", dicts.relation_statuses(relation), ("completed",))
eq("配空了退回默认", dicts.relation_statuses({**relation, "relationStatuses": []}), ("completed",))
eq("认不出的那档丢掉,别牵连别的", dicts.relation_statuses(
{**relation, "relationStatuses": ["closed", "bogus", "completed"]}), ("completed", "closed"))
eq("写成别的形状也退回默认", dicts.relation_statuses({**relation, "relationStatuses": "running"}), ("completed",))
# 接口上那句 status:档位与单据状态原值都认,全给等于不限
eq("空是不限", dicts.relation_status_query(""), ())
eq("只给归档通过", dicts.relation_status_query("completed"), ("completed",))
eq("在办与半路停下的并档", dicts.relation_status_query("closed,running"), ("running", "closed"))
eq("老写法传状态原值也认", dicts.relation_status_query("terminated"), ("closed",))
eq("三档全给等于不限", dicts.relation_status_query("completed,running,closed"), ())
eq("只认得出的那几档进清单", dicts.relation_status_query("completed,bogus"), ("completed",))
# 摊成两张表各挑哪几个状态:一张表一个都不沾就别去查它
eq("不限时两张表都不加状态条件", dicts.relation_status_tables(()), (None, None))
eq("只给归档通过时不查在办表", dicts.relation_status_tables(("completed",)), (None, ("completed",)))
eq("在办 + 半路停下", dicts.relation_status_tables(("running", "closed")),
(("running",), ("terminated", "canceled")))
# 设计期校验:措辞与前端 utils/optionSource.ts 一字不差(下面第 5 段逐句对)
eq("没写这一格不说", formruntime.option_source_problems(relation, db=None), [])
eq("一种都不勾要说", formruntime.option_source_problems(
{**relation, "relationStatuses": []}, db=None),
["至少勾一种状态:一种都不勾,这一格永远搜不到候选"])
eq("档位认不出要说", formruntime.option_source_problems(
{**relation, "relationStatuses": ["archieved"]}, db=None),
["能挂哪几种状态的单据里有认不出的档位:archieved"])
eq("配得对不说", formruntime.option_source_problems(
{**relation, "relationStatuses": ["completed", "running"]}, db=None), [])
# 换了来源就不该留着上一家的这一档
eq("换来源时这一档一起清", design_api.SOURCE_OWNED_KEYS[dicts.SOURCE_PROCESS][:2],
("relationProcess", "relationStatuses"))
# ---------------------------------------------------------------------------
@ -610,12 +684,27 @@ PARALLEL: list[tuple[tuple[str, str], list[str]]] = [
# 入参那份引用检查也出自内核这一份
"的入参「", "」引用了不存在的字段「", "引用了这一格自己"]),
(("backend/app/service/formruntime.py", "frontend/src/utils/optionSource.ts"),
["这一格的值由外部取数写入,候选又来自",
# 「由谁写入」那句两边都是拼出来的(``{filled_by}`` / ``${filledBy}``),
# 能逐句对的只有拼出来的那几段常量
["写入,候选又来自",
"否则提交时会被判「取值已不在可选范围内」",
"或把候选来源改成外部数据源 / 流程单据",
"把候选来源改成外部数据源 / 流程单据",
"或勾上「带出的值不在候选里也收下」",
"这一格没配任何带出(外部取数 / 关联单据带出 / 字典带出),",
"还没选择要用的数据字典",
"还没选择要用哪一张外部数据源",
"个选项没填要存的值,填了会存成空白"]),
# 关联审批单能挂哪几种状态的单据:档位说得不一样,两边就会各判各的
# (这句判据后端写在 service/dicts.py,由 formruntime 转调)
(("backend/app/service/dicts.py", "frontend/src/utils/optionSource.ts"),
["能挂哪几种状态的单据里有认不出的档位",
"至少勾一种状态:一种都不勾,这一格永远搜不到候选",
"能挂哪几种状态的单据要写成一份清单",
# 候选来源的条件路由:清单本身那几句两边也必须一模一样(判据见 check_option_routes.py)
"的候选来源清单要写成一份列表",
" 条,多出来的不会被用上",
"的来源这类字段挑不了",
"一条选项都没填,选到它就是一只空下拉"]),
# 报错里怎么称呼那份候选入参表,两边也得是同一个说法
(("backend/app/service/formruntime.py", "frontend/src/utils/binding.ts"),
["候选来源那张数据源"]),
@ -665,6 +754,7 @@ def main(argv: list[str]) -> int:
("源的健康判据", check_source_problem),
("选人字段当 SQL 入参", check_person_args),
("候选来源校验", check_option_source_problems),
("关联审批单能挂哪几种状态的单据", check_relation_statuses),
("字段上的解析覆盖", check_parse_override),
("带出的目标格子被删之后", check_live_targets),
("带出取哪一列", check_fill_columns),

View File

@ -0,0 +1,356 @@
#!/usr/bin/env python3
"""守"归档件也能说话"这一整条路:处理意见带图片/文件 + 办结之后的单子能补批注。
改造前这两件事都缺一块。``POST /read/{id}/handle`` 的请求体只有 ``opinion`` 一段文本,
``oa_read`` / ``oa_read_completed`` 也没有随附附件的落脚处;批注入口只开在待办页
(``TaskDetailView`` 的 ``canComment`` 要求 ``canProcess``),而一张**已经办结**的单子
永远不会有待办——于是"办结后抄送给某人、勾了需处理"的那个人,手上既没有待办、
打开单据页也只能看,一句带截图的补充都留不下。引擎侧 ``add_comment`` 其实认归档件
(``subject = work or db.get(WorkCompleted, ...)``),是接口与界面没把这条路递到人手上。
**这条门不往库里留东西**:全程跑在一个存档点(``begin_nested``)里,收尾整体回滚;
待阅、批注、通知、附件行都是就地造的(附件行 ``storage`` 留空,一个字节都不进 MinIO),
一条真单据都不发起——跑完再数一遍探针留下的名字,必须一条不剩。最后那几条断言
就是在钉这件事:校验本身不许变成测试数据的来源。
钉住的行为:
1. **处理意见带附件**:需处理那条待阅,本人带意见 + 附件处理确认,附件跟着这条记录
进已阅;随附的附件行 ``type=read``、``business_id`` 认到这条已阅记录,并按在途 /
归档两种情况回填 ``work`` / ``job`` / ``process`` / ``completed`` / ``work_completed``。
2. **普通登记不收附件**:不要求处理的那条待阅只是"我看过了",带附件必须被挡——
否则附件挂在一个连意见栏都没有的记录上,事后没人看得出它是谁、为什么传的。
3. **只能附本人上传的文件**:``claim_attachments`` 那条硬规则在归档件上照样管用。
4. **归档件上能补批注**:被抄送人照样能发批注、能带图、能 @ 人;批注行与附件行都
标成已归档,归属认到 ``oa_work_completed`` 那一张单上。
5. **"这一单与他有关"算得准**:``_received_reads`` 认待阅也认已阅,无关的人为假。
6. **环节那一格「允许批注」在归档件上照样管用**:``_comment_blocker`` 三档
(认不出环节 / 开关缺省 / 开关关掉),``comment_activity`` 认的是这一单
**自己落脚那一环**,不是流程当前设计;在途与归档同一条判据。
7. **接口与界面真的把这条路递到人手上**:请求体认 ``attachments``(含驼峰写法)、
``handle`` 那两条路由真把附件交给引擎、单据详情报得出 ``can_comment``、
待阅弹窗与单据详情页真的挂了能传图的编辑器。前后端各写一半、对不上的口径最容易漂。
跑在 backend 目录下::
PYTHONPATH=. python3 scripts/check_cc_action_files.py
"""
from __future__ import annotations
import inspect
import pathlib
import sys
from datetime import datetime
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent))
from sqlalchemy import func, select # noqa: E402
from app import models, schemas # noqa: E402
from app.api import runtime as runtime_module # noqa: E402
from app.db import SessionLocal # noqa: E402
from app.engine import definition as definition_module # noqa: E402
from app.engine import engine as engine_module # noqa: E402
REPO = pathlib.Path(__file__).resolve().parent.parent.parent
#: 只认得出来的探针名字:收尾按这些前缀数一遍,证明这条门自己不留数据
PROBE = f"零残留门-{datetime.now():%m%d%H%M%S}"
PROBE_IDENTITY = f"probe_{datetime.now():%m%d%H%M%S}_reader"
STRANGER_IDENTITY = f"probe_{datetime.now():%m%d%H%M%S}_stranger"
FAILS: list[str] = []
PASSED = 0
def check(label: str, passed: bool, detail: str = "") -> bool:
"""报一条结果;``passed`` 为假就记进失败清单。返回它本身,好让调用方就此收尾。"""
global PASSED
if passed:
PASSED += 1
print(f"[通过] {label}")
else:
FAILS.append(label)
print(f"[FAIL] {label}{f' -> {detail}' if detail else ''}")
return passed
def _actor(user: models.User | None, *, ref: str = "", is_admin: bool = False) -> engine_module.Actor:
"""就地搭一个办事的人。人是库里真有的(只读),但这一趟不落任何一行关于他的账。"""
return engine_module.Actor(
person_id=str(user.id) if user is not None else "probe-person",
person_name=(user.display_name if user is not None else "校验的人"),
ref=ref or (user.account if user is not None else "probe"),
unit="",
unit_name="",
is_admin=is_admin,
)
def _attachment(db, *, owner: str, name: str) -> str:
"""造一条"前端已经传好、还没人认领"的附件行。
``storage`` 故意留空:这条门只验归属与快照,不搬字节,一个对象都不必进 MinIO。
"""
row = models.Attachment(name=name, extension=".png", storage="", length=8,
type="attachment", person=owner)
db.add(row)
db.flush()
return row.id
def _reads_of(db, work_id: str, identity: str) -> list[models.Read]:
return list(db.execute(
select(models.Read).where(models.Read.work == work_id, models.Read.identity == identity)
).scalars().all())
def main() -> int: # noqa: C901 - 一条直线跑完六组断言,拆开反而要把状态传来传去
db = SessionLocal()
# 驱动用的单据从库里现成的拿,只读不改:归档件一张、在途件一张,缺一样就少验一半
archived = db.execute(
select(models.WorkCompleted).order_by(models.WorkCompleted.finish_time.desc()).limit(1)
).scalars().first()
live = db.execute(select(models.Work).order_by(models.Work.id.desc()).limit(1)).scalars().first()
if archived is None and live is None:
print("[跳过] 库里一张单据都没有,这一项校不了")
db.close()
return 0
# 发批注的人与被 @ 的人必须是两个真人:``create_reads`` 对批注这一类会跳过发件人
# 自己(自己 @ 自己不算一条待阅),拿同一个人当两边,那条断言测的就不是"提醒到了谁"
people = db.execute(
select(models.User).where(models.User.status == models.UserStatus.ACTIVE).order_by(models.User.id).limit(2)
).scalars().all()
mention = people[1] if len(people) > 1 else None
actor = _actor(people[0] if people else None)
# 处理待阅的是"收件人"本人:待阅只认得了他的登录账号(``get_read`` 那条归属校验),
# 这里借同一个真人当壳、把 ref 换成探针身份,既过归属校验又不碰任何人的账。
reader = _actor(people[0] if people else None, ref=PROBE_IDENTITY)
def tally() -> dict[str, int]:
"""这几张表的行数:跑之前跑之后各数一次,两次必须一样。
只数行数的合计,不数某一张单——这条门不发起单据,任何一张表多出来的行
都是它自己弄脏的。
"""
return {
"oa_work": db.execute(select(func.count(models.Work.id))).scalar(),
"oa_work_completed": db.execute(select(func.count(models.WorkCompleted.id))).scalar(),
"oa_read": db.execute(select(func.count(models.Read.id))).scalar(),
"oa_read_completed": db.execute(select(func.count(models.ReadCompleted.id))).scalar(),
"oa_work_comment": db.execute(select(func.count(models.WorkComment.id))).scalar(),
"oa_attachment": db.execute(select(func.count(models.Attachment.id))).scalar(),
"oa_notification": db.execute(select(func.count(models.Notification.id))).scalar(),
}
before = tally()
savepoint = db.begin_nested()
failed_here = False
try:
# --------- 1) 归档件:处理意见带附件 + 批注带附件 ---------
if archived is not None:
created = engine_module.create_reads(
db, archived, actor=actor, identities=[PROBE_IDENTITY], kind="cc",
requires_action=True, opinion="办结了,补一句处理意见")
read = next((row for row in created if row.identity == PROBE_IDENTITY), None)
failed_here |= not check("归档件上建得出「需处理」那条待阅",
read is not None and bool(read.requires_action)
and read.completed is True
and read.work_completed == archived.id,
"" if read is None else
f"requires_action={read.requires_action} completed={read.completed}")
check("归档件上这条待阅一开始还没有随附附件",
read is not None and list(read.attachments or []) == [],
repr(getattr(read, "attachments", None)))
png = _attachment(db, owner=reader.person_id, name=f"{PROBE}-处理意见.png")
try:
engine_module.mark_read(db, read_id=read.id, actor=reader, opinion="看过了",
handling=False, attachments=[png])
check("不要求处理的登记不许挂附件", False, "引擎没挡:附件挂到了一条没有意见栏的记录上")
except engine_module.EngineError as exc:
check("不要求处理的登记带附件被挡住,并说清为什么", "处理意见" in str(exc), str(exc))
done = engine_module.mark_read(
db, read_id=read.id, actor=reader, opinion="发票已重开,见附件",
handling=True, attachments=[png])
check("处理意见带附件提交成功,这条进了已阅",
done.handle_time is not None and bool(done.opinion), repr(done.opinion)[:120])
check("附件跟着这条记录进已阅(引用快照含名字与图片标记)",
[str(item.get("id")) for item in (done.attachments or [])] == [png],
repr(done.attachments)[:160])
row = db.get(models.Attachment, png)
check("归档件上的随附附件认到这条已阅记录与这一单,并直接标成已归档(type=read)",
row is not None and row.type == models.Attachment.KIND_READ
and row.business_id == done.id and row.work == archived.id
and row.job == archived.job and row.process == archived.process
and row.completed is True and row.work_completed == archived.id,
"" if row is None else f"type={row.type} business={row.business_id} work={row.work} "
f"job={row.job} process={row.process} completed={row.completed} "
f"work_completed={row.work_completed}")
check("处理过的这条已阅报得出附件(已阅列表要靠它显示)",
"attachments" in runtime_module.serializers.read_row(done),
sorted(runtime_module.serializers.read_row(done))[:60])
comment = engine_module.add_comment(
db, work_id=archived.id, actor=actor, content="归档之后再补一句:发票已重开",
mentions=[mention.account] if mention is not None else [],
mention_action=True, attachments=[])
check("归档件上发一条纯文字批注成功,且这条批注知道自己挂在归档件上",
comment.completed is True and comment.work_completed == archived.id
and str(comment.work) == archived.id,
f"completed={comment.completed} work_completed={comment.work_completed}")
png2 = _attachment(db, owner=actor.person_id, name=f"{PROBE}-批注.png")
second = engine_module.add_comment(
db, work_id=archived.id, actor=actor, content="贴图说明", mentions=[],
mention_action=False, attachments=[png2])
att2 = db.get(models.Attachment, png2)
check("归档件上的批注附件回填了这一单的归属并标成已归档",
[str(item.get("id")) for item in (second.attachments or [])] == [png2]
and att2 is not None and att2.work == archived.id
and att2.completed is True and att2.work_completed == archived.id
and att2.type == models.Attachment.KIND_COMMENT,
"" if att2 is None else f"type={att2.type} work={att2.work} completed={att2.completed}")
reminded = [item for item in _reads_of(db, archived.id, mention.account)
if item.read_type == "comment"] if mention is not None else []
check("在归档件上 @ 人照样生成待阅,且要求处理、认得自己是挂在归档件上的",
mention is not None and bool(reminded)
and all(item.requires_action and item.completed for item in reminded),
f"{len(reminded)} 条 / 被 @ 的人 {'有' if mention is not None else '没有'}")
other = _attachment(db, owner="probe-someone-else", name=f"{PROBE}-别人的.png")
try:
engine_module.add_comment(db, work_id=archived.id, actor=actor, content="想拿别人的文件顶上",
mentions=[], mention_action=False, attachments=[other])
check("只能附上本人上传的文件——归档件上这条硬规则不失效", False,
"引擎没挡:把别人传的文件认领到了自己的批注上")
except engine_module.EngineError as exc:
check("只能附上本人上传的文件——归档件上这条硬规则不失效", "本人上传" in str(exc), str(exc))
check("被抄送人算得出「这一单与他有关」",
runtime_module._received_reads(db, archived.id, PROBE_IDENTITY) is True, "为假")
check("没在这张单上收过待阅的人算不出「与他有关」",
runtime_module._received_reads(db, archived.id, STRANGER_IDENTITY) is False, "为真")
# --------- 6) 环节那一格「允许批注」:在途与归档同一条判据 ---------
node_on = definition_module.ActivityNode(id="probe1", type="manual", name="校验环节甲",
config={"allowComment": True})
node_off = definition_module.ActivityNode(id="probe2", type="manual", name="校验环节乙",
config={"allowComment": False})
check("开关缺省时放行(老设计没有这一格,不能凭空关掉批注)",
engine_module._comment_blocker(None) == "", repr(engine_module._comment_blocker(None)))
check("开关开着时放行", engine_module._comment_blocker(node_on) == "",
repr(engine_module._comment_blocker(node_on)))
check("开关关掉时报的是环节名那句原话",
engine_module._comment_blocker(node_off) == "环节 校验环节乙 不允许批注",
repr(engine_module._comment_blocker(node_off)))
resolved = engine_module.comment_activity(db, archived)
check("归档件没有「当前环节」这一格可判:认不出环节就是默认放行,不是漏判",
not hasattr(archived, "activity") and resolved is None
and engine_module.comment_blocker(db, archived) == "",
f"resolved={resolved!r} blocker={engine_module.comment_blocker(db, archived)!r}")
check("在途与归档走同一条判据(都从 comment_activity 出)",
engine_module.comment_blocker(db, archived)
== engine_module._comment_blocker(resolved),
repr(engine_module.comment_blocker(db, archived)))
if live is not None:
live_node = engine_module.comment_activity(db, live)
check("在途件认的是它当前压着的那一环,开关关掉就挡得住",
live_node is None
or engine_module.comment_blocker(db, live)
== engine_module._comment_blocker(live_node),
repr(engine_module.comment_blocker(db, live)))
else:
print("[提示] 库里没有已归档的单据,归档件那几条本轮没校到")
# --------- 2) 在途件:同一条处理链,归属落在 oa_work 那一张单上 ---------
if live is not None:
created = engine_module.create_reads(
db, live, actor=actor, identities=[PROBE_IDENTITY], kind="cc",
requires_action=True, opinion="补一句处理意见")
read = next((row for row in created if row.identity == PROBE_IDENTITY), None)
if check("在途件上也建得出那条待阅", read is not None and read.completed is False,
"" if read is None else f"completed={read.completed}"):
png = _attachment(db, owner=reader.person_id, name=f"{PROBE}-在途处理.png")
done = engine_module.mark_read(
db, read_id=read.id, actor=reader, opinion="已核对,见附件",
handling=True, attachments=[png])
row = db.get(models.Attachment, png)
check("在途件上的随附附件认到这条已阅记录与这一单,且不冒充已归档",
[str(item.get("id")) for item in (done.attachments or [])] == [png]
and row is not None and row.work == live.id and row.job == live.job
and row.process == live.process
and row.completed is False and row.work_completed == "",
"" if row is None else f"work={row.work} completed={row.completed} "
f"work_completed={row.work_completed}")
else:
print("[提示] 库里没有在途单据,在途那一半本轮没校到")
# --------- 7) 接口与界面真的把这条路递到人手上(前后端口径对账) ---------
body = schemas.ReadViewBody.model_validate({"opinion": "x", "attachments": ["a1", "a2"]})
check("处理意见的请求体认 attachments(驼峰写法同一条路)",
body.attachments == ["a1", "a2"], repr(body.attachments))
handle_src = inspect.getsource(runtime_module.handle_read)
view_src = inspect.getsource(runtime_module.view_read)
check("处理确认那条路由真把附件交给引擎", "attachments=body.attachments" in handle_src,
handle_src.strip()[:160])
check("登记已阅那条路由也认这一栏(挂错了才会被引擎挡下来)",
"attachments=body.attachments" in view_src, view_src.strip()[:160])
job_src = inspect.getsource(runtime_module._job_response)
check("单据详情报文里报得出 can_comment(界面开不开批注框就认这一格)",
'"can_comment"' in job_src and "_received_reads(" in job_src,
"没在 _job_response 里找到 can_comment")
read_view = (REPO / "frontend/src/views/oa/ReadListView.vue").read_text(encoding="utf-8")
work_view = (REPO / "frontend/src/views/oa/WorkDetailView.vue").read_text(encoding="utf-8")
mobile_work = (REPO / "frontend/src/components/oa/mobile/MobileWorkView.vue").read_text(encoding="utf-8")
flow = (REPO / "frontend/src/components/oa/mobile/MobileFlow.vue").read_text(encoding="utf-8")
record = (REPO / "frontend/src/components/oa/ApprovalRecord.vue").read_text(encoding="utf-8")
check("待阅那个「填写处理意见」的弹窗换成了能贴图能传文件的编辑器",
'purpose="read"' in read_view and "OpinionComposer" in read_view
and "handleRead(row.id, opinion, files)" in read_view,
"ReadListView 里没找到带附件的处理弹窗")
check("待阅列表里看得见这条记录随附的图片与文件",
"row.attachments" in read_view and "AttachmentGallery" in read_view,
"ReadListView 没有渲染 attachments")
check("单据详情页把批注框开出来了(桌面与手机都算,判据来自 can_comment)",
':can-comment="canComment"' in work_view and "detail.value?.can_comment" in work_view
and ':can-comment="canComment"' in mobile_work
and 'v-if="canComment"' in flow,
"WorkDetailView / MobileWorkView 的批注入口没接上")
# 整条链一次钉住:父页发完批注要清草稿 → 桌面那份真把 reset 交出来 →
# 手机整页往下转给 MobileFlow → MobileFlow 那句 defineExpose 落在 script 块里
# (掉到块外面等于没写,父页拿到的是 undefined,草稿就一直赖在面板里)
check("批注发出去之后草稿收得干净(桌面与手机共用一条收尾)",
"recordPanel.value?.reset?.()" in work_view
and "defineExpose({ reset, open" in record.split("</script>")[0]
and "defineExpose({ reset: () => flowPanel.value?.reset() })" in mobile_work.split("</script>")[0]
and "defineExpose({ reset: resetComposer })" in flow.split("</script>")[0],
"reset 这条链断了:父页调不到,或某一环的 defineExpose 掉在 script 块外面")
finally:
savepoint.rollback()
# --------- 收尾:这条门自己不许成为测试数据的来源 ---------
db.rollback()
after = tally()
probes = {
"attachment": db.execute(select(models.Attachment.id).where(
models.Attachment.name.like(f"{PROBE}-%"))).scalars().all(),
"read": db.execute(select(models.Read.id).where(
models.Read.identity.in_([PROBE_IDENTITY, STRANGER_IDENTITY]))).scalars().all(),
"read_completed": db.execute(select(models.ReadCompleted.id).where(
models.ReadCompleted.identity.in_([PROBE_IDENTITY, STRANGER_IDENTITY]))).scalars().all(),
}
check("跑完一条不剩:待阅 / 已阅 / 批注 / 附件 / 通知 / 单据的行数与跑之前一字不差",
before == after, f"跑前 {before} / 跑后 {after}")
check("探针名字与探针身份在库里都查不到了",
all(len(rows) == 0 for rows in probes.values()),
{key: len(rows) for key, rows in probes.items()})
print(f"\n合计 {PASSED + len(FAILS)} 项:通过 {PASSED} / 失败 {len(FAILS)}")
db.close()
return 1 if FAILS else 0
if __name__ == "__main__":
raise SystemExit(main())

View File

@ -14,6 +14,10 @@
1. 发起即冻结:单据身上有快照引用,``for_work`` 读出的是冻结定义;
2. 改图对在途单无效:环节改名 / 加环节加路由 / 改流程级审批规则,在途单一律看不见;
3. 改表单对在途单无效:新增必填字段不改变它该填什么,新发起的那张才受影响;
3b. 这一条只有**一个**例外:手机端审批那一屏「摆哪几格、怎么摆」跟当下的表单配置走
(报文里多带一份 ``forms_live``),必填、权限、引擎认值照旧跟冻住的那一版。
3c. 同一条例外的另一半:环节那一格「字段权限」也带一份此刻的(``activity_perms_live``),
只给手机端摆内容用;环节简报里那份 ``form_perms`` 仍是冻结那一版。
4. 待办带着同一份冻结引用(不必按 work 回查);
5. 内容寻址:设计没变,两次发起共用一行快照;
6. 老单据(没有快照引用)照旧现读当前设计,升级不迁数据;
@ -334,6 +338,49 @@ def main() -> int:
node is not None and node.name == "自检表单"
and serializers.form(node)["id"] == form.id)
# 3b 唯一的例外:手机端审批那一屏摆的是**此刻**那份表单配置。
# 单据是凭证,桌面 / 打印 / 导出 / 引擎读的都还是上面那一份查照;只有"这一屏
# 给审批人看哪几格"跟当下的配置走,否则配表的人改了展示配置,得等这张单走完
# 才看得见效果。口径见 runtime._forms_live 与 docs/mobile-approval-layout.md。
with serial_detail():
asker = deps.CurrentUser.resolve(db, person, personref.ref_of(person))
mobile_detail = runtime._job_response(db, asker, work.job, work, running=True)["data"]
live_content = (mobile_detail.get("forms_live") or {}).get(form.id) or {}
check("3b 手机端那一份报文里带着此刻的表单(新加的那格在里面)",
"invoice" in [str(item.get("key")) for item in live_content.get("fields") or []],
str(list(live_content.keys())))
frozen_fields = ((mobile_detail.get("forms") or [{}])[0].get("content") or {}).get("fields") or []
check("3b 桌面读的那一份仍没这一格(forms 出自查照)",
"invoice" not in [str(item.get("key")) for item in frozen_fields],
str([item.get("key") for item in frozen_fields]))
check("3b 表单没改动时不多带一份报文(内容一样就是空对象)",
runtime._forms_live([{"id": form.id, "content": content}], {form.id: dict(content)}) == {})
check("3b 表被删了就不带(回落到冻住的那一张)",
runtime._forms_live([{"id": form.id, "content": content}], {}) == {})
# 3c 另一半:环节那一格「字段权限」也有一份"此刻的"。生产上 2026-11 那批在途报销单
# 卡的就是这一处——管理员把 checkTotal 等审定格从「隐藏」改成「只读」,
# 单据冻的还是「隐藏」,手机上那一屏照旧不露。
# 改之前那份冻结简报(上面 3b 那次调用留着的)拿来当对照
frozen_perms = dict((mobile_detail["activity_nodes"][first.id].get("form_perms") or {}))
first.config = {**(first.config or {}), "formPerms": {"reason": "readonly"}}
db.flush()
with serial_detail():
perms_detail = runtime._job_response(db, asker, work.job, work, running=True)["data"]
check("3c 环节简报里那份还是冻结那一版(桌面与引擎读的仍是它)",
(perms_detail["activity_nodes"][first.id]["form_perms"] or {}) == frozen_perms,
str(perms_detail["activity_nodes"][first.id]["form_perms"]))
check("3c 冻结那份与此刻这份确实不一样(不然这条断言是空的)",
frozen_perms != {"reason": "readonly"}, str(frozen_perms))
check("3c 此刻那份字段权限单独带出来,只给手机端摆内容用",
(perms_detail.get("activity_perms_live") or {}).get(first.id) == {"reason": "readonly"},
str(perms_detail.get("activity_perms_live")))
check("3c 权限没改动时不多带一份报文",
runtime._perms_live({first.id: {"form_perms": {"reason": "readonly"}}},
{first.id: {"reason": "readonly"}}) == {})
check("3c 冻结简报里没有的环节不进这份报文(那张单脚下没这一环)",
runtime._perms_live({}, {first.id: {"reason": "readonly"}}) == {})
# 4 待办带着同一份冻结引用 ---------------------------------------------
check("4 待办身上带的是同一份快照",
all(t.design_snapshot == work.design_snapshot
@ -450,6 +497,14 @@ def main() -> int:
check("9 归档单详情页那张表单也是出发时的(库里它已改名)",
[f["name"] for f in detail_payload.get("forms") or []] == ["自检表单"],
str([f["name"] for f in detail_payload.get("forms") or []]))
# 跟着当下配置摆的那一份只给**在途**单:办结归档之后这张单是凭证,
# 手机上回头打开也读它走完时那一版(第 3b 组那条例外到这儿为止)
check("9 归档单不再带那份当下的表单",
detail_payload.get("forms_live") == {},
str(detail_payload.get("forms_live")))
check("9 归档单也不再带那份当下的字段权限",
detail_payload.get("activity_perms_live") == {},
str(detail_payload.get("activity_perms_live")))
check("9 归档单详情页认得自己是第几版在走,也说得出设计后来被动过",
detail_payload.get("design_pinned") is True
and detail_payload.get("design_version") == before_version

View File

@ -0,0 +1,614 @@
#!/usr/bin/env python3
"""钉住「干预改道之后,被干预那一环还剩什么」与「已经推出去的消息各自什么下场」。
两个问题来自 2026-11-10 的用户截图:管理员把一张停在「部门主管」的单直接改到「财务审批」,
审批记录上写着「经营管理中心不需要部门主管审批,故干预到财务审批」。于是两问——
1. **被干预之前的那一环还会不会有待办**?
2. **已经推送出去的那条「您有新的待办」怎么办**?
口径以代码为准,这一篇把答案钉成可复跑的判据(设计见 ``docs/process-intervention-design.md``
与 ``docs/intervention-todo-and-message-settlement-design.md``)::
cd backend && PYTHONPATH=. python3 scripts/check_intervention_move.py
全程跑在内存 sqlite 上,一条语句都不碰开发库;引擎、站内信、接口、事件订阅都是真代码。
分组:
A 待办去向 整张单的待办一次收干净、收进已办而非删行、代操作人与原因都留在痕迹上
B 消息下场 站内信当场收尾(标已读不删行)/ 外发那一路走渠道可勾的 ``rerouted`` /
事件订阅带 ``processingType``,改道回到走过的环节也推得出**新**待办号
C 收口 在跑的嵌入子流程默认拒、勾了才一并终止;停在半路的第三方表态作废;
待阅那份「当前环节」跟着游标走
D 点开旧卡片 认得出下场就照实回话(去向卡),认不出才还是那句「已被处理」
``[现状]`` 打头的是**已经确认、但这一版管不住的行为**:已经发到邮箱 / 群 / 企业微信的
那条消息收不回来(Hub 的推送接口只有发送与逐人回查,企微自己的撤回没在 Hub 上开)。
它由 D 组那一屏兜住——消息追不回来,就让它每次点开都落在一个说得出真相的页面上。
"""
from __future__ import annotations
import os
import sys
from datetime import datetime, timedelta
# 设计缓存是跨进程的,脚本里这些固定流程 id 会读到上一趟自己存进去的那一份。
os.environ["OA_DESIGN_CACHE"] = "off"
# 只读复用那一层靠挂在 app.db 那台 MySQL 引擎连接上的写钩子作废(见 app/readcache.py)。
# 本脚本的内存库不在它名下,钩子够不着,写着 oa_task 也作废不掉「本环节有哪些人」那份旧结果。
# 关掉它不是绕过被测逻辑,是补上内存库缺的那半个前提:判据要的是一次DB一次真读。
os.environ["OA_READCACHE"] = "off"
from sqlalchemy import create_engine, func, select # noqa: E402
from sqlalchemy.orm import Session # noqa: E402
from sqlalchemy.pool import StaticPool # noqa: E402
from app import envelope, models, presence # noqa: E402
from app.api import runtime as runtime_api # noqa: E402
from app.deps import CurrentUser # noqa: E402
from app.engine import engine # noqa: E402
from app.service import channels # noqa: E402
STARTER = ("1001", "周瑾", "zhoujin") # 发起人
BOSS = ("2002", "陈鹏", "chenpeng") # 部门主管:被干预的那一环
FINANCE = ("3003", "张梅", "zhangmei") # 财务经理:改道的落点
CC_PERSON = ("3004", "黄雪秋", "huangxueqiu") # 部门主管那一环抄送出去的人
ADMIN = ("9001", "管理员", "admin01")
OUTSIDER = ("5005", "无关的人", "wairen")
REASON = "经营管理中心不需要部门主管审批,故干预到财务审批"
PASSED = 0
FAILS: list[str] = []
NOTES: list[str] = []
def check(label: str, ok: bool, detail: object = "") -> bool:
global PASSED
if ok:
PASSED += 1
print(f"[通过] {label}")
else:
FAILS.append(label)
print(f"[FAIL] {label}{f' -> {detail}' if detail else ''}")
return ok
def observe(label: str, detail: object) -> None:
"""记一条"这一版管不住、靠后面那一屏兜底"的现状。"""
NOTES.append(label)
print(f"[现状] {label} -> {str(detail)[:300]}")
def new_session() -> Session:
"""内存库。模型里 MySQL 专属的 server_default 在 sqlite 上建不出来,建表前摘掉。"""
for table in models.Base.metadata.tables.values():
for column in table.columns:
if column.server_default is not None:
column.server_default = None
bind = create_engine("sqlite://", poolclass=StaticPool,
connect_args={"check_same_thread": False})
models.Base.metadata.create_all(bind)
# presence 那层「这张表有没有值得去问的」记在进程里,作废挂在 app.db 那个引擎的写钩子上;
# 这一份内存库不在它名下,不清就会拿着上一趟 session「一条渠道都没有」的旧结论。
presence.clear()
db = Session(bind)
for person_id, name, ref in (STARTER, BOSS, FINANCE, CC_PERSON, ADMIN, OUTSIDER):
db.add(models.User(id=int(person_id), account=ref, display_name=name,
email=f"{ref}@example.com", password_hash="", status=1))
db.flush()
return db
def actor_of(person, *, is_admin: bool = False) -> engine.Actor:
person_id, name, ref = person
return engine.Actor(person_id=person_id, person_name=name, ref=ref, is_admin=is_admin)
def user_of(person, *, monitor: bool = True) -> CurrentUser:
"""接口要的那个登录身份。``monitor=False`` 是"只看得到自己那一份"的普通处理人。"""
person_id, name, ref = person
row = models.User(id=int(person_id), account=ref, display_name=name, status=1)
perms = ("work:profile", "monitor:work") if monitor else ("work:profile",)
return CurrentUser(person=row, ref=ref, is_admin=False, permissions=perms)
def task_detail(db: Session, task_id: str, user: CurrentUser) -> dict:
"""调接口那一层取待办详情,并把「不该掉出来」的那几种情况也摊成一个信封。
接口出错走的是抛 :class:`ApiError`(FastAPI 那个异常处理器负责换成 ``{"code": ...}``),
脚本里没有那层处理器,所以自己接一下,判据才能照旧只看 code / message。
"""
try:
return runtime_api.get_task_detail(task_id, db=db, user=user)
except envelope.ApiError as exc:
return {"code": exc.api_code, "message": str(exc.detail), "data": None}
def holder(ref: str) -> dict:
return {"taskValues": [{"type": "identity", "data": [ref]}]}
def make_flow(db: Session, tag: str) -> str:
"""发起 → 部门主管(到达时抄送黄雪秋)→ 财务经理 → 结束。回流程 id。"""
pid = f"p-{tag}"
db.add(models.Process(id=pid, name=f"改道校验流程 {tag}", latest_form="f-shared",
enabled=True, published=True))
db.add(models.Activity(id=f"{pid}-begin", process=pid, type="begin", name="发起", config={}))
db.add(models.Activity(id=f"{pid}-dept", process=pid, type="manual", name="部门主管",
config={**holder(BOSS[2]),
"ccRules": [{"when": "arrive",
"taskValues": [{"type": "identity",
"data": [CC_PERSON[2]]}]}]}))
db.add(models.Activity(id=f"{pid}-finance", process=pid, type="manual", name="财务经理",
config=holder(FINANCE[2])))
db.add(models.Activity(id=f"{pid}-end", process=pid, type="end", name="结束", config={}))
db.add(models.Route(id=f"{pid}-r1", process=pid, name="提交", from_activity=f"{pid}-begin",
to_activity=f"{pid}-dept"))
db.add(models.Route(id=f"{pid}-r2", process=pid, name="同意", from_activity=f"{pid}-dept",
to_activity=f"{pid}-finance"))
db.add(models.Route(id=f"{pid}-r3", process=pid, name="同意", from_activity=f"{pid}-finance",
to_activity=f"{pid}-end"))
db.flush()
return pid
def start_job(db: Session, pid: str, tag: str) -> models.Work:
result = engine.create_job(
db, process_id=pid, actor=actor_of(STARTER),
data={"title": f"改道校验单 {tag}"}, title=f"改道校验单 {tag}",
)
db.flush()
return result.work
def tasks_of(db: Session, work: models.Work) -> list[models.Task]:
return list(db.execute(
select(models.Task).where(models.Task.work == work.id).order_by(models.Task.id)
).scalars().all())
def notices(db: Session, identity: str, *, unread_only: bool = True) -> list[models.Notification]:
rows = list(db.execute(
select(models.Notification).where(models.Notification.identity == identity)
).scalars().all())
return [row for row in rows if not unread_only or not row.read]
def events_of(db: Session, event: str) -> list[models.OpenEvent]:
return list(db.execute(
select(models.OpenEvent).where(models.OpenEvent.event == event)
).scalars().all())
def deliveries_of(db: Session, identity: str) -> list[models.NotifyDelivery]:
return list(db.execute(
select(models.NotifyDelivery).where(models.NotifyDelivery.identity == identity)
).scalars().all())
def move(db: Session, work: models.Work, activity: str, *, opinion: str = REASON,
cascade: bool = False) -> engine.StepResult:
return engine.move(db, job=work.job, actor=actor_of(ADMIN, is_admin=True),
activity=activity, opinion=opinion, cascade_children=cascade)
def mail_channel(db: Session, code: str, events: list[str]) -> None:
"""一条邮箱渠道:外发那一路的投递记录由它造,事件勾什么由调用方定。"""
db.add(models.NotifyChannel(
id=f"ch-{code}", code=code, name=f"改道校验渠道 {code}",
kind=models.NotifyChannel.KIND_EMAIL, enabled=True, events=events,
config={"host": "smtp.invalid", "port": 25, "user": "oa", "password": "p",
"from": "oa@invalid"},
))
db.flush()
# ---------------------------------------------------------------------------
# A 待办去向
# ---------------------------------------------------------------------------
def check_todo_after_move() -> None:
db = new_session()
pid = make_flow(db, "a")
work = start_job(db, pid, "a")
origin = tasks_of(db, work)[0]
check("A0 前置:改道前这张单的待办压在部门主管手上",
origin.identity == BOSS[2] and work.activity == f"{pid}-dept")
move(db, work, f"{pid}-finance")
db.flush()
left = tasks_of(db, work)
check("A1 被干预那一环一条待办都不剩:改道收的是整张单的待办,不只当前环节",
not [row for row in left if row.activity == f"{pid}-dept"],
[(row.activity_name, row.identity) for row in left])
check("A2 落点这一环派出了新待办,压在财务经理手上",
len(left) == 1 and left[0].activity == f"{pid}-finance" and left[0].identity == FINANCE[2],
[(row.activity_name, row.identity) for row in left])
done = db.execute(
select(models.TaskCompleted).where(models.TaskCompleted.task == origin.id)
).scalar_one_or_none()
check("A3 被收走的那条进的是「已办」而不是被删:事后答得出谁手里被拿走了一条",
done is not None and done.route_name == "干预改道",
None if done is None else done.route_name)
check("A4 那条已办分得清不是人签的:processing_type 记 move,不混进正常同意那一堆",
done is not None and done.processing_type == engine.LOG_MOVE,
None if done is None else done.processing_type)
check("A5 代操作人写在已办行上:陈鹏那一行读起来是「管理员替我收的尾」,不是他自己批的"
"(与终止 operator=actor 同一写法)",
done is not None and done.operator == ADMIN[2] and done.operator_name == ADMIN[1],
None if done is None else (done.operator, done.operator_name))
check("A6 改道的原因跟着那一步走,审批记录里看得见",
done is not None and REASON in str(done.opinion or ""),
None if done is None else done.opinion)
check("A7 单据游标与「当前环节」文案一起落到落点",
work.activity == f"{pid}-finance" and work.current_activity_names == "财务经理",
(work.activity, work.current_activity_names))
check("A8 路上的残余一次清干净:token 只剩落点那一条,票箱与直返约定清空,去重基线写上",
len(work.tokens or []) == 1 and not work.joins and not work.go_back_store
and bool((work.variables or {}).get("dedupSince")),
(work.tokens, work.joins, work.go_back_store))
log = db.execute(
select(models.WorkLog).where(models.WorkLog.job == work.job, models.WorkLog.type == "move")
).scalars().first()
check("A9 干预在流转记录里是一条真的换环节记录(从部门主管到财务经理,带谁动的)",
log is not None and log.from_activity == f"{pid}-dept"
and log.arrived_activity == f"{pid}-finance" and log.from_person_name == ADMIN[1],
None if log is None else (log.from_activity, log.arrived_activity, log.from_person_name))
# ---------------------------------------------------------------------------
# B 已经推送出去的消息
# ---------------------------------------------------------------------------
def check_messages() -> None:
db = new_session()
db.add(models.OpenWebhook(id="hook-1", code="itest", name="改道校验订阅", enabled=True,
url="https://hook.invalid/cb", secret="s",
events=["task.arrived", "task.completed"], processes=[]))
mail_channel(db, "itest-mail", ["task", "rerouted"])
pid = make_flow(db, "b")
work = start_job(db, pid, "b")
origin = tasks_of(db, work)[0]
arrived_title = f"您有新的待办:{work.title}"
queued = [row for row in deliveries_of(db, BOSS[2]) if row.type == "task"]
check("B1 前置:待办到达那一刻确实排出了外发投递(邮箱一路按人各一条)",
len(queued) == 1 and queued[0].task == origin.id,
[(row.channel, row.type, row.task) for row in queued])
for row in queued: # 模拟"这条已经发出去了"
row.status = models.NotifyDelivery.STATUS_SUCCESS
row.sent_at = datetime.now()
db.flush()
pushed_id = queued[0].id
move(db, work, f"{pid}-finance")
db.flush()
left = [row.title for row in notices(db, BOSS[2])]
check("B2 站内信当场退场:改道这一步就把那句「您有新的待办」收尾了,"
"不等他下次点开列表(标已读不删行,投递记录仍回查得到)",
arrived_title not in left and len(left) == 1 and "改道" in left[0],
f"未读 {left}")
retired = [row for row in notices(db, BOSS[2], unread_only=False) if row.title == arrived_title]
check("B3 收尾是标已读不是删行:那一行还在库里且带着已读时间,"
"「谁在什么时候收到过什么」查得回来",
len(retired) == 1 and retired[0].read and bool(retired[0].read_time), retired)
check("B4 被收走待办的人收到一句为什么:control 站内信点明改道、落点与原因",
any(row.type == "control" and "改道" in row.title and "财务经理" in row.body
and REASON in row.body
for row in notices(db, BOSS[2], unread_only=False)),
[row.title for row in notices(db, BOSS[2], unread_only=False)])
check("B5 发起人也被知会了一句「流程被改道」",
any(row.type == "control" and "改道" in row.title
for row in notices(db, STARTER[2], unread_only=False)),
[row.title for row in notices(db, STARTER[2], unread_only=False)])
check("B6 落点那位收到的是正常的「您有新的待办」,带的是新待办号",
any(row.type == "task" and row.task and row.task != origin.id
for row in notices(db, FINANCE[2], unread_only=False)),
[(row.type, row.task) for row in notices(db, FINANCE[2], unread_only=False)])
out = [row for row in deliveries_of(db, BOSS[2]) if row.type == "rerouted"]
check("B7 外发那一路走的是渠道能单独勾的 rerouted:站内仍叫 control,"
"深链不再指那条已经不存在的待办",
len(out) == 1 and out[0].notification and not out[0].task,
[(row.type, row.task, row.notification) for row in out])
check("B8 rerouted 是一档可勾的渠道事件(挂在渠道上按人勾,不是干预硬推)",
"rerouted" in dict(channels.EVENTS), list(dict(channels.EVENTS)))
again = db.get(models.NotifyDelivery, pushed_id)
check("B9 已经发出去的那条投递记录原样躺着:改道不回收、不改写",
again is not None and again.status == models.NotifyDelivery.STATUS_SUCCESS
and again.task == origin.id,
None if again is None else (again.status, again.task))
observe("B9+ 已经落到邮箱 / 群 / 企业微信里的那条卡片收不回来(Hub 9.6 只有发送与逐人回查,"
"企微自己的撤回没在 Hub 上开);这一条由 D 组那一屏兜住",
(again.title if again else "", again.status if again else ""))
completed = events_of(db, "task.completed")
payload = completed[0].payload if completed else {}
check("B10 事件订阅能自愈:task.completed 入队并带上 processingType=move,"
"订阅方据此就该把手上那条待办收掉",
bool(completed) and isinstance(payload, dict)
and payload.get("processingType") == "move",
payload if isinstance(payload, dict) else str(payload)[:200])
def check_event_dedupe() -> None:
"""改道回到走过的环节时,幂等键按待办号认,新那条待办号推得出去。"""
db = new_session()
db.add(models.OpenWebhook(id="hook-2", code="itest2", name="改道校验订阅2", enabled=True,
url="https://hook.invalid/cb2", secret="s",
events=["task.arrived"], processes=[]))
db.flush()
pid = make_flow(db, "b2")
work = start_job(db, pid, "b2")
origin = tasks_of(db, work)[0]
first = events_of(db, "task.arrived")
check("B11 前置:走到部门主管时推过一条 task.arrived,幂等键里带着当时那条待办号",
len(first) == 1 and first[0].idem.endswith(origin.id),
[row.idem for row in first])
move(db, work, f"{pid}-finance", opinion="先挪去财务")
move(db, work, f"{pid}-dept", opinion="还得回部门主管看一眼")
db.flush()
latest = tasks_of(db, work)[0]
again = [row for row in events_of(db, "task.arrived") if row.idem.endswith(latest.id)]
check("B12 改道回到走过的环节时推得出**新**那条待办号(原先按环节名去重,"
"订阅方手里只剩一条已经废掉的号)",
len(again) == 1 and again[0].activity == "部门主管",
{"当前真待办号": latest.id, "按新号入队的事件条数": len(again),
"已入队的幂等键": [row.idem for row in events_of(db, "task.arrived")]})
check("B13 同一条待办不会被推两遍:重复表态、重复入队这一头照旧守得住",
len([row for row in events_of(db, "task.arrived") if row.idem.endswith(origin.id)]) == 1,
[row.idem for row in events_of(db, "task.arrived")])
# ---------------------------------------------------------------------------
# C 改道收口
# ---------------------------------------------------------------------------
def check_residues() -> None:
db = new_session()
pid = make_flow(db, "c")
work = start_job(db, pid, "c")
origin = tasks_of(db, work)[0]
db.add(models.NodeDecision(
id="nd-1", app="itest-app", app_name="改道校验应用", work=work.id, job=work.job,
process=pid, process_name=work.process_name, activity=f"{pid}-dept", activity_name="部门主管",
task=origin.id, task_identity=BOSS[2], task_identity_name=BOSS[1],
decision="同意", kind="agree", route="同意", opinion="第三方原话",
biz_key="biz-1", status=models.NodeDecision.STATUS_STAGED,
expires_at=datetime.now() + timedelta(hours=6),
))
db.flush()
read_before = list(db.execute(
select(models.Read).where(models.Read.work == work.id)
).scalars().all())
move(db, work, f"{pid}-finance")
db.flush()
check("C1 抄送出去的待阅不随改道回收:它说的是「抄给你看过」,不是要办的事",
len(read_before) == 1
and len(list(db.execute(select(models.Read).where(
models.Read.work == work.id)).scalars().all())) == 1)
read_now = db.get(models.Read, read_before[0].id)
check("C2 待阅行上那份「当前环节」跟着游标走:待阅列表不再写着这张单停在部门主管",
read_now is not None and read_now.current_activity_name == "财务经理",
None if read_now is None else read_now.current_activity_name)
staged = db.get(models.NodeDecision, "nd-1")
check("C3 停在半路等确认的第三方表态随改道作废:那是改道之前、按改道之前的表单说的,"
"改道回到同一环时不该再冒出来等人点头",
staged is not None and staged.status == models.NodeDecision.STATUS_EXPIRED
and "改道" in str(staged.confirm_note or "") and "财务经理" in str(staged.confirm_note or ""),
None if staged is None else (staged.status, staged.confirm_note))
def _embed_flows(db: Session) -> tuple[str, str]:
"""父:发起 → 调用子流程 → 财务经理 → 结束;子:发起 → 子流程经办 → 结束。"""
child = "p-c-child"
db.add(models.Process(id=child, name="改道校验子流程", latest_form="f-shared",
enabled=True, published=True))
db.add(models.Activity(id=f"{child}-begin", process=child, type="begin", name="发起", config={}))
db.add(models.Activity(id=f"{child}-step", process=child, type="manual", name="子流程经办",
config=holder(CC_PERSON[2])))
db.add(models.Activity(id=f"{child}-end", process=child, type="end", name="结束", config={}))
db.add(models.Route(id=f"{child}-r1", process=child, name="提交", from_activity=f"{child}-begin",
to_activity=f"{child}-step"))
db.add(models.Route(id=f"{child}-r2", process=child, name="同意", from_activity=f"{child}-step",
to_activity=f"{child}-end"))
pid = "p-c-parent"
db.add(models.Process(id=pid, name="改道校验父流程", latest_form="f-shared",
enabled=True, published=True))
db.add(models.Activity(id=f"{pid}-begin", process=pid, type="begin", name="发起", config={}))
db.add(models.Activity(id=f"{pid}-call", process=pid, type="embed", name="调用子流程",
config={"process": child}))
db.add(models.Activity(id=f"{pid}-finance", process=pid, type="manual", name="财务经理",
config=holder(FINANCE[2])))
db.add(models.Activity(id=f"{pid}-end", process=pid, type="end", name="结束", config={}))
db.add(models.Route(id=f"{pid}-r1", process=pid, name="提交", from_activity=f"{pid}-begin",
to_activity=f"{pid}-call"))
db.add(models.Route(id=f"{pid}-r2", process=pid, name="同意", from_activity=f"{pid}-call",
to_activity=f"{pid}-finance"))
db.add(models.Route(id=f"{pid}-r3", process=pid, name="同意", from_activity=f"{pid}-finance",
to_activity=f"{pid}-end"))
db.flush()
return pid, child
def check_embed_cascade() -> None:
"""父单停在「调用子流程」时改道:先拒,勾了一并终止才动子单。"""
db = new_session()
pid, _child = _embed_flows(db)
result = engine.create_job(db, process_id=pid, actor=actor_of(STARTER),
data={"title": "改道校验父子单"}, title="改道校验父子单")
db.flush()
parent = result.work
# 这一组要先验一次"改道被拒",被拒之后会回滚;先落一次库,回滚才只吞掉那次失败的改道,
# 不会把整张父子单一起抹掉。
db.commit()
kids = list(db.execute(
select(models.Work).where(models.Work.parent_job == parent.job)
).scalars().all())
check("C4 前置:父单停在调用环节、自己没有待办,待办压在子单上",
len(kids) == 1 and not tasks_of(db, parent) and tasks_of(db, kids[0]),
(len(kids), len(tasks_of(db, parent))))
child_work = kids[0]
message = ""
try:
move(db, parent, f"{pid}-finance")
except engine.EngineError as exc:
message = str(exc)
db.rollback()
check("C5 默认停手:父单改道撞上还在跑的子流程就拒,并把是哪张子单、卡在谁手上说清楚",
"子流程" in message and child_work.title in message and CC_PERSON[1] in message
and "一并终止" in message, message)
check("C6 停手是真的什么都没动:父单还停在调用环节,子单那条待办照旧在",
db.get(models.Work, parent.id).activity == f"{pid}-call"
and bool(tasks_of(db, child_work)),
(db.get(models.Work, parent.id).activity, len(tasks_of(db, child_work))))
move(db, parent, f"{pid}-finance", cascade=True)
db.flush()
parent_now = db.get(models.Work, parent.id)
child_now = db.get(models.Work, child_work.id)
check("C7 勾了一并终止:父单落到落点,子单跟着终止归档,那条没人认领的待办一起收掉",
parent_now is not None and parent_now.activity == f"{pid}-finance"
and child_now is None
and db.execute(select(func.count(models.WorkCompleted.id)).where(
models.WorkCompleted.id == child_work.id)).scalar() == 1
and not tasks_of(db, child_work),
(parent_now.activity if parent_now else None,
child_now is not None,
len(tasks_of(db, child_work))))
cascade_log = db.execute(
select(models.WorkLog).where(models.WorkLog.job == child_work.job)
).scalars().all()
check("C8 子单那句终止原因是「父流程已改道」,读的人知道这张子单是谁为什么收掉的",
any("改道" in str(row.from_opinion or "") for row in cascade_log),
[row.from_opinion for row in cascade_log][:4])
# ---------------------------------------------------------------------------
# D 点开一条已经不存在的待办
# ---------------------------------------------------------------------------
def check_dead_link() -> None:
db = new_session()
pid = make_flow(db, "d")
work = start_job(db, pid, "d")
origin = tasks_of(db, work)[0]
move(db, work, f"{pid}-finance")
db.flush()
# 引擎那一层照旧认不出这条待办:去向卡是**读出口**那一层补的,不改办事的判据
message = ""
try:
engine.get_task(db, origin.id, actor_of(BOSS))
except engine.EngineError as exc:
message = str(exc)
check("D1 办事那一头照旧挡得住:这条待办已经不是任何人的待办",
message == "待办不存在或已被处理", message)
payload = task_detail(db, origin.id, user_of(BOSS))["data"]
vanished = payload.get("vanished") or {}
check("D2 点开旧卡片不再只有一句「已被处理」:认得出下场就照实回话",
bool(vanished) and vanished.get("kind") == "move",
list(payload.keys()))
check("D3 那一屏答得出是谁、什么时候、为什么收走的",
vanished.get("operator_name") == ADMIN[1]
and REASON in str(vanished.get("opinion") or "")
and bool(vanished.get("handled_at")),
{k: vanished.get(k) for k in ("operator_name", "opinion", "handled_at")})
check("D4 还答得出这张单现在停在哪个环节、在等谁(处理人真正想知道的是还要不要他管)",
vanished.get("current_activity_names") == "财务经理"
and FINANCE[1] in str(vanished.get("current_handlers") or "")
and vanished.get("work_status") == "running"
and vanished.get("job") == work.job,
{k: vanished.get(k) for k in ("current_activity_names", "current_handlers",
"work_status", "job")})
check("D5 原环节那一环认得出来:卡片上写的是「部门主管」这一步没了,不是别的环节",
vanished.get("activity_name") == "部门主管" and bool(vanished.get("title")),
(vanished.get("activity_name"), vanished.get("title")))
unrecognized = db.execute(
select(models.TaskCompleted).where(models.TaskCompleted.task == origin.id)
).scalars().first()
if unrecognized is not None:
unrecognized.processing_type = "addBefore" # 加签那一档:去向卡没有专门文案
db.flush()
odd = (task_detail(db, origin.id, user_of(BOSS)).get("data") or {}).get("vanished") or {}
check("D6 认不出的收尾方式(加签那一档)不硬套成「有人办完了」:只说这条待办已结束,认得的那几行照说",
odd.get("kind") == "unknown" and bool(odd.get("title"))
and odd.get("job") == work.job and bool(odd.get("opinion")),
{k: odd.get(k) for k in ("kind", "title", "opinion")})
unrecognized.processing_type = "move"
db.flush()
other = task_detail(db, origin.id, user_of(OUTSIDER, monitor=False))
check("D6 无关的人拿一个待办号来问,连标题都不该跟着掉出来(照旧 404)",
other.get("code") != 0 and "已被处理" in str(other.get("message") or ""),
other)
monitor = task_detail(db, origin.id, user_of(ADMIN, monitor=True))
check("D7 看得见监控的人问得动(他就是被找来问的那个)",
bool((monitor.get("data") or {}).get("vanished")), monitor.get("code"))
missing = task_detail(db, "t-压根没这个号", user_of(BOSS))
check("D8 查无此号还是那句原话,不硬编一个下场给人看",
missing.get("code") != 0, missing)
labels = _frontend_move_labels()
check("D9 前端那两张「处理方式」表认得 move:已办那一列不会印出裸的 move",
labels == [], labels)
engine.terminate(db, job=work.job, actor=actor_of(ADMIN, is_admin=True),
opinion="这张单后来被终止了")
db.flush()
later = (task_detail(db, origin.id, user_of(BOSS)).get("data") or {}).get("vanished") or {}
check("D10 那张单后来终止归档了:旧卡片跟着换成「这张单已终止」,不再写着停在哪个环节等谁办",
later.get("kind") == "move" and later.get("work_status") == "terminated"
and not later.get("current_handlers") and bool(later.get("title")),
{k: later.get(k) for k in ("kind", "work_status", "current_handlers")})
def _frontend_move_labels() -> list[str]:
"""看前端那两张处理方式表认不认得 move。判据口径与 check_notify_settle.py 同一类。"""
import pathlib as _pathlib
import re
root = _pathlib.Path(__file__).resolve().parents[2] / "frontend" / "src" / "utils"
out: list[str] = []
for rel, marker in (("oa.ts", "PROCESSING_TYPE"), ("approvalRecord.ts", "PROCESSING_TYPES")):
text = (root / rel).read_text(encoding="utf-8")
block = re.search(marker + r"[^=]*=\s*\{(.*?)\n\}", text, re.S)
if block is None:
out.append(f"{rel}:{marker} 没找到")
elif not re.search(r"^\s*move\s*:", block.group(1), re.M):
out.append(f"{rel}:{marker} 缺 move")
return out
def main() -> int:
for step in (check_todo_after_move, check_messages, check_event_dedupe,
check_residues, check_embed_cascade, check_dead_link):
step()
print(f"\n共 {PASSED + len(FAILS)} 项判据:通过 {PASSED},失败 {len(FAILS)}"
+ (f";另记现状 {len(NOTES)} 条" if NOTES else ""))
for item in FAILS:
print(f" - {item}")
return 1 if FAILS else 0
if __name__ == "__main__":
sys.exit(main())

View File

@ -0,0 +1,423 @@
"""关联单据带出的验收脚本(不连库,跑在 backend 目录下)::
python3 scripts/check_link_fill.py
「关联审批流程之后,把那边单据里的值写进这一张单的明细表 / 主表字段,关联多张也要能带」
这件事(方案见 ``docs/relation-link-fill-design.md``)在下面几条上必须一直成立:
1. **配置的形状只有一份**:写歪的规则、认不出的合并档在保存那一刻就被 ``clean`` 收干净,
一条有效规则都不剩时整格抹掉;换了候选来源,那几格跟着上一家一起清;
2. **指向掉了当场说**:要写进的格子不在表单上了、合并档与那一格的形状对不上、
两条带出抢同一格,都是「存得下来、那一格永远是空的」,保存这一刻挡;
3. **主表那一路是「几个数变成一个」**:按配的那一档合(first / join / sum / min / max),
口径是 ``binding.merge`` 那一句,与外部取数同一把尺;
4. **明细那一路是「一单一行」**:新关联的补行、取消关联的删行、留下的行按来源刷新
配到的那几列,而人手工改过的其它列一个字都不动;**关联没变时一行都不重排**,
否则下一环提交会把人删掉的行复活;
5. **行整型不吃 ``_link``**:页面回传时那一格要留得住,否则下一次带出认不出旧行;
6. **两个关联字段带同一张明细表**:各带各的行,谁都不许把对方带来的那一行删掉或盖掉
(那一格存的可能是单号而不是 job,认行要绕一层)。
最后把前后端共用的那几句措辞对一遍。
"""
from __future__ import annotations
import pathlib
import sys
from datetime import datetime
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent))
from app.api import design as design_api # noqa: E402
from app.service import formruntime, linkfill # noqa: E402
FRONTEND = pathlib.Path(__file__).resolve().parent.parent.parent / "frontend" / "src"
FAILS: list[str] = []
class Work:
"""顶替 ``Work`` / ``WorkCompleted`` 那一行:带出只读 job / 单号 / 标题 / 表单数据。"""
def __init__(self, job: str, serial: str = "", title: str = "", data: dict | None = None,
status: str = "completed", creator: str = "张三", unit: str = "财务部",
start: datetime | None = None) -> None:
self.id = job
self.job = job
self.serial = serial or job
self.title = title or f"单据 {job}"
self.status = status
self.process_name = "费用报销"
self.creator_person = creator
self.creator_identity_name = creator
self.creator_unit_name = unit
self.start_time = start
self.finish_time = None
self.data = dict(data or {})
def loader_of(*works: Work):
index = {}
for row in works:
index[row.job] = row
index[row.serial] = row
return lambda values: {item: index[item] for item in values if item in index}
def fields() -> list[dict]:
return [
{"key": "orders", "type": "relation", "label": "关联报销单", "optionSource": "process",
"linkFill": {"rules": RULES}},
{"key": "src_serial", "type": "text", "label": "来源单号"},
{"key": "total", "type": "money", "label": "合计"},
{"key": "when", "type": "date", "label": "发起日期"},
{"key": "items", "type": "table", "label": "明细", "columns": [
{"key": "amount", "type": "money", "label": "金额"},
{"key": "note", "type": "text", "label": "备注"},
]},
]
RULES: list[dict] = []
def configured(rules: list[dict]) -> list[dict]:
rows = fields()
rows[0]["linkFill"] = {"rules": rules}
return rows
def eq(name: str, got, want) -> None:
if got != want:
FAILS.append(f"{name}:得到 {got!r},应为 {want!r}")
def has(name: str, text: str, needle: str) -> None:
if needle not in str(text):
FAILS.append(f"{name}:{text!r} 里没找到 {needle!r}")
# ---------------------------------------------------------------------------
# 1 配置形状与保存期清洗
# ---------------------------------------------------------------------------
def check_clean() -> None:
eq("整格没配", linkfill.clean(None), {})
eq("空规则等于没配", linkfill.clean({"rules": []}), {})
eq("没写取哪一列的规则丢掉", linkfill.clean({"rules": [{"to": "total"}]}), {})
eq("没写去向的规则丢掉", linkfill.clean({"rules": [{"pick": "work.serial"}]}), {})
eq("认不出的合并档退回默认", linkfill.clean({"rules": [{"pick": "a", "to": "b", "agg": "avg"}]}),
{"rules": [{"pick": "a", "to": "b"}]})
eq("跟默认一样的不留", linkfill.clean({"rules": [{"pick": "a", "to": "b", "agg": "first"}]}),
{"rules": [{"pick": "a", "to": "b"}]})
eq("分隔符照留", linkfill.clean({"rules": [{"pick": "a", "to": "b", "agg": "join", "separator": " / "}]}),
{"rules": [{"pick": "a", "to": "b", "agg": "join", "separator": " / "}]})
eq("默认分隔符不留", linkfill.clean({"rules": [{"pick": "a", "to": "b", "agg": "join", "separator": "、"}]}),
{"rules": [{"pick": "a", "to": "b", "agg": "join"}]})
eq("规则条数封顶", len(linkfill.clean({"rules": [{"pick": "a", "to": f"b{i}"} for i in range(99)]})["rules"]),
linkfill.MAX_RULES)
eq("设计器那份流程名留着", linkfill.clean({"process": "p1", "rules": []}), {})
def check_split_target() -> None:
rows = fields()
eq("整串认主表字段", linkfill.split_target("total", rows), ("total", ""))
eq("点分认明细列", linkfill.split_target("items.amount", rows), ("items", "amount"))
eq("列不在表上", linkfill.split_target("items.nope", rows), ("", ""))
eq("表不是明细表", linkfill.split_target("total.amount", rows), ("", ""))
eq("空写法", linkfill.split_target("", rows), ("", ""))
def check_problems() -> None:
rows = configured([{"pick": "work.serial", "to": "src_serial"}])
keys = {str(item["key"]) for item in rows}
eq("配得对的不说", linkfill.problems(rows[0], keys, rows), [])
# 来源不是流程单据:字典那一格挂着 linkFill 永远不带
dict_field = {"key": "x", "type": "select", "optionSource": "dict", "dictCode": "d",
"linkFill": {"rules": [{"pick": "work.serial", "to": "x"}]}}
has("来源不对", ";".join(linkfill.problems(dict_field, {"x"}, [dict_field])), "流程单据")
dangling = configured([{"pick": "work.serial", "to": "gone"}])
has("指向掉在地上", ";".join(linkfill.problems(dangling[0], {"orders"}, dangling)), "不存在的字段「gone」")
numeric = configured([{"pick": "data.amount", "to": "src_serial", "agg": "sum"}])
has("装不下数", ";".join(linkfill.problems(numeric[0], {"orders", "src_serial"}, numeric)), "装不下数")
both = configured([{"pick": "work.serial", "to": "src_serial"},
{"pick": "work.title", "to": "src_serial"}])
has("两条抢一格", ";".join(linkfill.problems(both[0], {"orders", "src_serial"}, both)), "都写进「src_serial」")
weird = configured([{"pick": "serial", "to": "src_serial"}])
has("写法看不出读哪儿", ";".join(linkfill.problems(weird[0], {"orders", "src_serial"}, weird)), "work.")
half = {"key": "orders", "type": "relation", "optionSource": "process",
"linkFill": {"rules": [{"to": "total"}]}}
has("半截配置", ";".join(linkfill.problems(half, {"orders", "total"}, [half])), "没写清")
# 明细列那一头:合并档也得认那一格的形状
column_agg = configured([{"pick": "data.amount", "to": "items.note", "agg": "sum"}])
has("明细列装不下数",
";".join(linkfill.problems(column_agg[0], {"orders"}, column_agg)), "明细表「明细」的列「备注」")
# 整张表单的校验把它带进保存那条路
reasons = formruntime.validate_schema(configured([{"pick": "work.serial", "to": "gone"}]))
has("validate_schema 认这一层", ";".join(reasons), "不存在的字段「gone」")
def check_design_clean() -> None:
content = {"fields": [
{"key": "a", "type": "relation", "label": "关联", "optionSource": "process",
"linkFill": {"rules": [{"pick": "work.serial", "to": "b"}, {"pick": "", "to": "b"}]}},
{"key": "b", "type": "text", "label": "B"},
]}
out = design_api.clean_option_source(content)
eq("换来源之前先收干净", out["fields"][0]["linkFill"], {"rules": [{"pick": "work.serial", "to": "b"}]})
swapped = design_api.clean_option_source({"fields": [
{"key": "a", "type": "select", "label": "A", "optionSource": "dict", "dictCode": "d",
"linkFill": {"rules": [{"pick": "work.serial", "to": "b"}]}},
{"key": "b", "type": "text", "label": "B"},
]})
eq("换走来源时一起清", "linkFill" in swapped["fields"][0], False)
nested = design_api.clean_option_source({"fields": [
{"key": "t", "type": "table", "label": "T", "columns": [
{"key": "c", "type": "relation", "label": "关联列", "optionSource": "process",
"linkFill": {"rules": [{"pick": "work.serial", "to": "x"}]}},
]},
]})
eq("明细列上的关联带出收掉", "linkFill" in nested["fields"][0]["columns"][0], False)
# ---------------------------------------------------------------------------
# 2 主表那一路:几个数变成一个
# ---------------------------------------------------------------------------
def check_main_targets() -> None:
one = Work("J1", "BX-001", data={"amount": 100, "day": "2026-03-01"})
two = Work("J2", "BX-002", data={"amount": "2,300.50", "day": "2026-03-05"})
rows = configured([{"pick": "work.serial", "to": "src_serial"}])
data = {"orders": ["J1"]}
touched = linkfill.apply(None, rows, data, loader=loader_of(one, two))
eq("关联一张时取它自己", data["src_serial"], "BX-001")
eq("报出改动的格子", touched, ["src_serial"])
rows = configured([{"pick": "work.serial", "to": "src_serial", "agg": "join", "separator": " / "}])
data = {"orders": ["J1", "J2"]}
linkfill.apply(None, rows, data, loader=loader_of(one, two))
eq("关联两张时按分隔符拼", data["src_serial"], "BX-001 / BX-002")
rows = configured([{"pick": "data.amount", "to": "total", "agg": "sum"}])
data = {"orders": ["J1", "J2"]}
linkfill.apply(None, rows, data, loader=loader_of(one, two))
eq("金额按分相加,带分隔符的文本也认", data["total"], 2400.5)
rows = configured([{"pick": "data.amount", "to": "total", "agg": "max"}])
data = {"orders": ["J1", "J2"]}
linkfill.apply(None, rows, data, loader=loader_of(one, two))
eq("取最大", data["total"], 2300.5)
rows = configured([{"pick": "work.serial", "to": "src_serial"}])
data = {"orders": ["J2", "J1"]}
linkfill.apply(None, rows, data, loader=loader_of(one, two))
eq("取第一个按关联顺序", data["src_serial"], "BX-002")
rows = configured([{"pick": "data.day", "to": "when"}])
data = {"orders": ["J1"]}
linkfill.apply(None, rows, data, loader=loader_of(one, two))
eq("日期格保持日期写法", data["when"], "2026-03-01")
stamp = Work("J3", "BX-003", start=datetime(2026, 3, 1, 9, 30, 0))
rows = configured([{"pick": "work.startTime", "to": "when"}])
data = {"orders": ["J3"]}
linkfill.apply(None, rows, data, loader=loader_of(stamp))
eq("单据本体的时间收成日期那一格认的写法", data["when"], "2026-03-01")
rows = configured([{"pick": "data.amount", "to": "total", "agg": "sum"}])
data = {"orders": []}
linkfill.apply(None, rows, data, loader=loader_of(one, two))
eq("取消全部关联时那一格清空", data["total"], "")
rows = configured([{"pick": "data.amount", "to": "total", "agg": "sum"}])
data = {"orders": ["J9"]}
linkfill.apply(None, rows, data, loader=loader_of(one, two))
eq("那张单被删了也一视同仁", data["total"], "")
rows = configured([{"pick": "work.serial", "to": "src_serial"}])
data = {"orders": "J1"}
linkfill.apply(None, rows, data, loader=loader_of(one))
eq("单选那一格(存的是单个值)照样带", data["src_serial"], "BX-001")
rows = configured([{"pick": "work.serial", "to": "src_serial"}])
data = {"orders": ["BX-001"]}
linkfill.apply(None, rows, data, loader=loader_of(one))
eq("配成存单号那一列也认得回单据", data["src_serial"], "BX-001")
# ---------------------------------------------------------------------------
# 3 明细那一路:一单一行
# ---------------------------------------------------------------------------
def check_detail_rows() -> None:
one = Work("J1", "BX-001", data={"amount": 100})
two = Work("J2", "BX-002", data={"amount": 200})
rules = [{"pick": "data.amount", "to": "items.amount"}]
data = {"orders": ["J1", "J2"]}
linkfill.apply(None, configured(rules), data, loader=loader_of(one, two))
eq("两张单补两行", [row.get("items") or row for row in data["items"]][0].get("_link"), "J1")
eq("按关联顺序排", [row["_link"] for row in data["items"]], ["J1", "J2"])
eq("带出来的值落进配的那一列", [row["amount"] for row in data["items"]], [100, 200])
# 人在下一行手工补了备注,又删掉了 J2 那一行
data["items"] = [{"_link": "J1", "amount": 100, "note": "自己写的"},
{"amount": 999, "note": "手工加的行"}]
trace_before = dict(data[linkfill.TRACE_KEY])
linkfill.apply(None, configured(rules), data, loader=loader_of(one, two))
eq("关联没变时不重排、不复活被删的行", [row.get("_link") for row in data["items"]], ["J1", None])
eq("手工加的行一个字不动", data["items"][1]["amount"], 999)
eq("留痕照原样", data[linkfill.TRACE_KEY], trace_before)
# 现在先把 J2 取消关联(这一轮关联变了,会重排一次),再把它挂回来
data["orders"] = ["J1"]
linkfill.apply(None, configured(rules), data, loader=loader_of(one, two))
data["orders"] = ["J1", "J2"]
linkfill.apply(None, configured(rules), data, loader=loader_of(one, two))
eq("重新关联才补回来,且加在末尾不打乱人排的序",
[row.get("_link") for row in data["items"]], ["J1", None, "J2"])
eq("人写的备注没被动", data["items"][0]["note"], "自己写的")
# 来源那侧金额改了(对方改单之后):关联没变这一轮不动,动一下关联才按来源刷新
linkfill.apply(None, configured(rules), data, loader=loader_of(Work("J1", "BX-001", data={"amount": 111}), two))
eq("关联没变时不刷来源", data["items"][0]["amount"], 100)
data["orders"] = ["J1", "J2", "JX"]
linkfill.apply(None, configured(rules), data, loader=loader_of(Work("J1", "BX-001", data={"amount": 111}), two))
eq("关联变化时按来源刷新配到的那一列", [row.get("amount") for row in data["items"]][0], 111)
eq("新关联的排在末尾,取消关联的那一行跟着删",
[row.get("_link") for row in data["items"]], ["J1", None, "J2"])
# 最多几行那一档
data = {"orders": ["J1", "J2"]}
rows = configured(rules)
rows[4]["maxRows"] = 1
linkfill.apply(None, rows, data, loader=loader_of(one, two))
eq("补行也认最多行数", len(data["items"]), 1)
# 两张明细表 / 两个关联字段各管自己那几行
data = {"orders": ["J1"]}
linkfill.apply(None, configured(rules), data, loader=loader_of(one))
eq("没配列去向时不凭空造行", len(data["items"]), 1)
data = {"orders": ["J1"]}
linkfill.apply(None, configured([{"pick": "work.title", "to": "items.note"}]), data, loader=loader_of(one))
eq("文本带进明细列", data["items"][0]["note"], "单据 J1")
eq("没配的列留空", data["items"][0]["amount"], "")
# 空来源也要留得下那一行:对方那一列没填,行还是那张单的
data = {"orders": ["J1"]}
linkfill.apply(None, configured([{"pick": "data.nope", "to": "items.amount"}]), data, loader=loader_of(one))
eq("取不到值落一个形状正确的空", data["items"][0]["amount"], "")
kept = formruntime.normalise_rows(data["items"], fields()[4])
eq("带出那行即使全空也不会被当成空行删掉", [row.get("_link") for row in kept], ["J1"])
eq("整型之后 _link 还在", linkfill.ROW_LINK_KEY in kept[0], True)
def check_two_relation_fields() -> None:
"""两个关联字段带进同一张明细表:各带各的行,谁也不许删对方带来的那一行。
「挂两类单子」在真实表单上就是两格(报销单一格、采购单一格,两格的字段名根本不
是一套),而明细表只有一张。不带这一道兜底,后处理的那一格会把前一格刚补的那几行
当成「自己这边取消关联了」删干净。
"""
order = Work("J1", "BX-001", data={"amount": 100})
buy = Work("J9", "CG-009", data={"cost": 500})
def pair() -> list[dict]:
return [
{"key": "orders", "type": "relation", "label": "关联报销单", "optionSource": "process",
"linkFill": {"rules": [{"pick": "data.amount", "to": "items.amount"}]}},
{"key": "buys", "type": "picker", "label": "关联采购单", "optionSource": "process",
"linkFill": {"rules": [{"pick": "data.cost", "to": "items.amount"}]}},
{"key": "items", "type": "table", "label": "明细", "columns": [
{"key": "amount", "type": "money", "label": "金额"},
{"key": "note", "type": "text", "label": "备注"},
]},
]
data = {"orders": ["J1"], "buys": ["J9"]}
linkfill.apply(None, pair(), data, loader=loader_of(order, buy))
eq("两个关联字段各带一行", [row["_link"] for row in data["items"]], ["J1", "J9"])
eq("各取各的列", [row["amount"] for row in data["items"]], [100, 500])
# 只动其中一格:另一格带来的那一行原样留着,值也不被对方盖掉
data["orders"] = []
linkfill.apply(None, pair(), data, loader=loader_of(order, buy))
eq("取消一格的关联只撤它自己那一行", [row["_link"] for row in data["items"]], ["J9"])
data["orders"] = ["J1"]
linkfill.apply(None, pair(), data, loader=loader_of(order, Work("J9", "CG-009", data={"cost": 999})))
eq("重排之后对方那两行都还在", [row["_link"] for row in data["items"]], ["J9", "J1"])
eq("别人带来的那一行不被这一格的列映射盖掉",
[row["amount"] for row in data["items"] if row["_link"] == "J9"], [500])
# 别的格子那一串值存的是单号而不是 job:认行要绕一层,绕不过去就会错删
data = {"orders": ["BX-001"], "buys": ["J9"]}
linkfill.apply(None, pair(), data, loader=loader_of(order, buy))
eq("对方存的是单号,也认得出那一行是谁带来的",
sorted(row["_link"] for row in data["items"]), ["J1", "J9"])
data["buys"] = []
linkfill.apply(None, pair(), data, loader=loader_of(order, buy))
eq("存单号那一格撤干净,另一格那几行照旧不动",
[row["_link"] for row in data["items"]], ["J1"])
# ---------------------------------------------------------------------------
# 4 预览接口那一份取值
# ---------------------------------------------------------------------------
def check_values_of() -> None:
one = Work("J1", "BX-001", data={"amount": 100})
items = linkfill.values_of(None, ["J1", "J2"], ["work.serial", "data.amount"], loader=loader_of(one))
eq("认不出的那张不在里面", len(items), 1)
eq("按 pick 原文回键", items[0]["values"], {"work.serial": "BX-001", "data.amount": 100})
eq("没写 pick 时什么都不取", linkfill.values_of(None, ["J1"], [], loader=loader_of(one)), [])
# 那一格可以配成存单号(optionMap.valueKey):问出去的是单号,回来的 value 必须是
# **问的那一句**,只回 job 会让预览那头一张都认领不到,明细表整个空着
asked = linkfill.values_of(None, ["BX-001", "不存在的单号"], ["data.amount"], loader=loader_of(one))
eq("按单号问也要认领得回来", [(item["job"], item["value"]) for item in asked], [("J1", "BX-001")])
def check_wording_parity() -> None:
"""前后端共用的那几句说法必须一字不差(漂了这里就红)。"""
right = FRONTEND / "utils" / "linkFill.ts"
if not right.exists():
print(f"[跳过] 找不到前端那份 {right}")
return
text = right.read_text(encoding="utf-8")
for needle in ("只有候选来源是「流程单据」的字段能配关联带出", "装不下数", "都写进"):
if needle not in text:
FAILS.append(f"前端那份缺了同款措辞:{needle}")
if f"'{formruntime.ROW_LINK_KEY}'" not in text:
FAILS.append("前端那份认的行标记与后端不是同一个")
STAGES = [
("配置形状", check_clean),
("指向怎么认", check_split_target),
("保存期校验", check_problems),
("候选来源清洗", check_design_clean),
("主表:几个数变成一个", check_main_targets),
("明细:一单一行", check_detail_rows),
("两个关联字段带同一张明细表", check_two_relation_fields),
("预览取值", check_values_of),
("前后端措辞对齐", check_wording_parity),
]
def main(argv: list[str]) -> int:
for title, stage in STAGES:
before = len(FAILS)
stage()
marks = "通过" if len(FAILS) == before else f"{len(FAILS) - before} 条不对"
print(f"[{marks}] {title}")
for line in FAILS:
print(f"[FAIL] {line}")
if FAILS:
print(f"共 {len(FAILS)} 条不对")
return 1
print("通过:关联单据带出口径一致")
return 0
if __name__ == "__main__":
raise SystemExit(main(sys.argv[1:]))

View File

@ -0,0 +1,380 @@
#!/usr/bin/env python3
"""关联带出走一遍真提交(连库,跑在 backend 目录下)::
PYTHONPATH=. python3 scripts/check_link_fill_submit.py
:doc:`check_link_fill.py` 校的是纯函数那一份口径,这一份钉的是**接上引擎之后**:
1. **发起那一刻就带得出**:``create_job`` 里那趟 ``_apply_form_runtime`` 走到带出,
关联的主表字段与明细行落进 ``work.data``;
2. **明细行上的 ``_link`` 活得过整表那一趟**:``normalise_rows`` 只认配好的列,
认不出这一格就会被丢掉,下一次带出便认不得旧行,把人改过的行当新行重排;
3. **人在下一环删掉的那一行不复活**:关联没变时一行都不重排,人连配到带出的那一格都改得;
关联一变才整趟对账——该补的补(人删掉的那一行只要还挂着关联就补回来,加在末尾)、
该删的删、没配带出的那一列不动、配到带出的那一列按来源盖回去;
4. **多挂一张就多算一张**:主表那几格按当下挂着的那串单重算,与明细剩几行无关;
5. **挂着的那张单查不到了**:不替它编一行,主表那几格跳过它,不报错也不挡人;
6. **带出来的那一格参与必填**:带不出值时必填那道闸真的把这次提交挡住——带出排在必填之前;
7. **两个关联字段带同一张明细表**:报销单一格、采购单一格各配各的映射,各带各的行,
后算的那一格不许把前一格刚补的那一行删掉,主表那几格也只按自己那一格挂的单算;
8. **预览那一道可见性闸**:与 ``GET /work/summaries`` 同一分寸(不相干的静默少回),
但多认一档「确实挂在填的这一单上」——办理环节的人常常与对方那张单无关,
少了这一档,带出那一栏对他就是一片空白;引擎那一份**不带**这道闸。
跑完连自己造的应用、流程、表单、单据一起删干净。
"""
from __future__ import annotations
import sys
import time
from datetime import datetime
from sqlalchemy import delete, select
from app import models
from app.api import runtime
from app.service import linkfill
from app.db import SessionLocal
from app.engine import engine
from app.service import personref
STAMP = datetime.now().strftime("%m%d%H%M%S")
TITLE_PREFIX = f"关联带出校验 {STAMP}"
FAILS: list[str] = []
PASSED = 0
CLEAN: dict = {"jobs": [], "processes": [], "forms": []}
def check(label: str, condition, detail: str = "") -> None:
global PASSED
if condition:
PASSED += 1
print(f"[通过] {label}")
else:
FAILS.append(label)
print(f"[FAIL] {label} -> {detail}")
def source_fields() -> list[dict]:
return [
{"key": "amount", "type": "money", "label": "金额"},
{"key": "reason", "type": "text", "label": "事由"},
]
def target_fields() -> list[dict]:
return [
{"key": "orders", "type": "relation", "label": "关联报销单", "optionSource": "process",
"required": True,
"linkFill": {"rules": [
{"pick": "work.serial", "to": "src_serial", "agg": "join", "separator": " / "},
{"pick": "data.amount", "to": "total", "agg": "sum"},
{"pick": "data.amount", "to": "items.amount"},
{"pick": "data.reason", "to": "items.note"},
]}},
{"key": "buys", "type": "relation", "label": "关联采购单", "optionSource": "process",
"linkFill": {"rules": [{"pick": "data.reason", "to": "items.note"}]}},
{"key": "src_serial", "type": "text", "label": "来源单号"},
{"key": "total", "type": "money", "label": "合计", "required": True},
{"key": "items", "type": "table", "label": "明细", "columns": [
{"key": "amount", "type": "money", "label": "金额"},
{"key": "note", "type": "text", "label": "备注"},
{"key": "qty", "type": "number", "label": "数量"},
]},
]
def build(db, ref: str, handles: int = 5) -> tuple[str, str, list[str]]:
"""源流程(begin→end)与目标流程(begin→若干道办理→end),回 ``(源, 目标, [办理环节 id])``。
目标流程留好几道办理,是为了能在**中途**改那串关联:带出发生在每一次提交上,
「关联变了才重排、没变就不动」这件事只有连着提交两次才校得出来。
"""
forms = []
for name, fields in ((f"{TITLE_PREFIX} 源表单", source_fields()), (f"{TITLE_PREFIX} 目标表单", target_fields())):
form = models.FormElement(name=name, content={"fields": fields})
db.add(form)
forms.append(form)
db.flush()
CLEAN["forms"].extend(item.id for item in forms)
src = models.Process(name=f"{TITLE_PREFIX} 源流程", category="check", enabled=True, published=True,
latest_form=forms[0].id, latest_form_name=forms[0].name)
dst = models.Process(name=f"{TITLE_PREFIX} 目标流程", category="check", enabled=True, published=True,
latest_form=forms[1].id, latest_form_name=forms[1].name)
db.add_all([src, dst])
db.flush()
CLEAN["processes"].extend([src.id, dst.id])
begin = models.Activity(process=dst.id, type="begin", name="发起人", order_number=0)
steps_of = [
models.Activity(process=dst.id, type="manual", name=f"办理{index}", order_number=index,
form=forms[1].id,
config={"mode": "any", "taskValues": [{"type": "person", "data": [ref]}]})
for index in range(1, handles + 1)
]
db.add_all([
models.Activity(process=src.id, type="begin", name="发起人", order_number=0),
models.Activity(process=src.id, type="end", name="结束", order_number=1),
begin,
*steps_of,
models.Activity(process=dst.id, type="end", name="结束", order_number=handles + 1),
])
db.flush()
handles = steps_of
steps = [(begin.id, handles[0].id, "提交")]
steps += [(handles[index].id, handles[index + 1].id, "同意") for index in range(len(handles) - 1)]
steps.append((handles[-1].id, db.execute(
select(models.Activity).where(models.Activity.process == dst.id,
models.Activity.type == "end")).scalars().first().id, "同意"))
db.add_all([
models.Route(process=src.id, name="提交", from_activity=db.execute(
select(models.Activity).where(models.Activity.process == src.id,
models.Activity.type == "begin")).scalars().first().id,
to_activity=db.execute(select(models.Activity).where(
models.Activity.process == src.id, models.Activity.type == "end"
)).scalars().first().id),
*[models.Route(process=dst.id, name=name, from_activity=src_id, to_activity=dst_id)
for src_id, dst_id, name in steps],
])
db.commit()
return src.id, dst.id, [item.id for item in handles]
def job_of(result) -> str:
"""刚建的那张单的 ``job``。
``StepResult.work_job`` 只在**办结**那一路填(归档之后实例拿不住了才留个号),
还在跑的那一张手里是 ``work`` 本体——照着办结那条路写会把空串当成 job 传下去。
"""
work = getattr(result, "work", None)
return str(getattr(work, "job", "") or "") or str(getattr(result, "work_job", "") or "")
def serial_of(db, job: str) -> str:
"""那张单的单号:在途与归档两处都认。"""
for table in (models.Work, models.WorkCompleted):
row = db.execute(select(table).where(table.job == job)).scalars().first()
if row is not None:
return str(row.serial or "")
return ""
def pending(db, job: str):
return db.execute(select(models.Task).where(models.Task.job == job,
models.Task.status == "pending")).scalars().first()
def step(db, job: str, actor, data: dict | None = None) -> dict:
"""在当前那一环点「同意 / 提交」,带上这一环改过的表单,回提交之后的 ``data``。"""
task = pending(db, job)
if task is None:
FAILS.append(f"{job}:没有待办可点,带出这一步校不了")
return {}
engine.execute_task(db, task_id=task.id, actor=actor, route_name="", opinion="提交", data=data or {})
db.commit()
work = db.execute(select(models.Work).where(models.Work.job == job)).scalars().first()
if work is None:
archived = db.execute(select(models.WorkCompleted).where(
models.WorkCompleted.job == job)).scalars().first()
return dict(archived.data or {}) if archived is not None else {}
return dict(work.data or {})
def step_blocked(db, job: str, actor, data: dict | None = None) -> str:
"""同样点一次提交,但这回**该被校验挡住**:回那句红字;没挡住就把改动退回去回空串。"""
task = pending(db, job)
if task is None:
FAILS.append(f"{job}:没有待办可点,这一趟校不了")
return ""
try:
engine.execute_task(db, task_id=task.id, actor=actor, route_name="",
opinion="提交", data=data or {})
except engine.EngineError as exc:
db.rollback()
return str(exc)
db.rollback()
return ""
def preview(db, ref: str, *, admin: bool = False, values=None, picks=None, work: str = "") -> list[dict]:
"""填单页那一趟预览接口走一遍(直接调函数,不套 TestClient)。
接口只认 ``user.is_admin`` 与 ``user.ref`` 两样,拿一句假身份就够把它那道
可见性闸校出来——它比算法更容易错:闸太紧,办理环节的人看着带出那一栏一片空白;
闸没有,这一格就变成翻别人单据的口子。
"""
from types import SimpleNamespace
from app import schemas
body = schemas.RelationFillBody(values=list(values or []), picks=list(picks or []), work=work)
user = SimpleNamespace(ref=ref, is_admin=admin)
return list((runtime.relation_fill_values(body, user, db).get("data") or {}).get("items") or [])
def rows_of(data: dict) -> list[dict]:
return list((data or {}).get("items") or [])
def main() -> int:
db = SessionLocal()
user = db.get(models.User, 1)
if user is None:
print("[跳过] 库里没有 1 号用户,这一项校不了")
return 0
actor = engine.Actor.from_ref(db, user, personref.ref_of(user))
try:
src_process, _dst, handles = build(db, personref.ref_of(user))
# ---- 两张已办结的源单:目标流程要挂的正是「批完的单」,形状要真 ----
first = engine.create_job(db, process_id=src_process, actor=actor,
data={"amount": 120, "reason": "打车"}, title=f"{TITLE_PREFIX} 源一")
second = engine.create_job(db, process_id=src_process, actor=actor,
data={"amount": "2,300.50", "reason": "机票"}, title=f"{TITLE_PREFIX} 源二")
third = engine.create_job(db, process_id=src_process, actor=actor,
data={"amount": 777.25, "reason": "住宿"}, title=f"{TITLE_PREFIX} 源三")
db.commit()
job1, job2, job3 = job_of(first), job_of(second), job_of(third)
CLEAN["jobs"].extend([job1, job2, job3])
serial1, serial2, serial3 = serial_of(db, job1), serial_of(db, job2), serial_of(db, job3)
check("三张源单都办结归档了",
db.get(models.WorkCompleted, first.work_id) is not None
and db.get(models.WorkCompleted, second.work_id) is not None
and db.get(models.WorkCompleted, third.work_id) is not None, f"{job1} / {job2} / {job3}")
# ---- 1. 发起那一刻就带得出 ----
target = engine.create_job(db, process_id=_dst, actor=actor,
data={"orders": [job1, job2]}, title=f"{TITLE_PREFIX} 目标")
db.commit()
dst_job = job_of(target)
CLEAN["jobs"].append(dst_job)
data = dict(target.work.data or {})
check("发起时把关联的单号拼进主表那一格", data.get("src_serial") == f"{serial1} / {serial2}",
f"{data.get('src_serial')!r} ≠ {serial1} / {serial2}")
check("发起时把金额相加带进主表那一格", data.get("total") == 2420.5, data.get("total"))
rows = rows_of(data)
check("两张关联单补两行", len(rows) == 2, rows)
check("行上认得出是哪张单带来的", [row.get("_link") for row in rows] == [job1, job2], rows)
check("带出用的是对方表单里那一列", [row.get("amount") for row in rows] == [120, 2300.5], rows)
check("配到的那一列带得出值", [row.get("note") for row in rows] == ["打车", "机票"], rows)
check("没配的列也摆着,留一个形状正确的空", all(row.get("qty") == "" for row in rows), rows)
check("带出留痕落在 data 上", (data.get("_linkfill") or {}).get("orders") == [job1, job2],
data.get("_linkfill"))
check("走到了办理一环", pending(db, dst_job) is not None and pending(db, dst_job).activity == handles[0],
None if pending(db, dst_job) is None else pending(db, dst_job).activity)
# ---- 2. 下一环:人删掉一行、改了两格(一格配了带出、一格没配),提交时都不被动 ----
kept = dict(rows[0])
kept["note"] = "自己改过的" # 配了带出的那一列
kept["qty"] = 5 # 没配带出的那一列
mid = step(db, dst_job, actor, {"items": [kept]})
after = rows_of(mid)
check("人删掉的那一行不复活", [row.get("_link") for row in after] == [job1], after)
check("关联没变时,人连配到带出的那一列都改得", after and after[0].get("note") == "自己改过的", after)
check("关联没变时,人改的没配带出的那一列也不动", after and after[0].get("qty") == 5, after)
check("主表那一格按关联算,跟明细剩几行无关",
mid.get("total") == 2420.5 and mid.get("src_serial") == f"{serial1} / {serial2}", mid)
# ---- 3. 关联变了才补行:补的加在末尾,留下的行只刷配到的那一列 ----
mid = step(db, dst_job, actor, {"orders": [job1, job2, job3]})
after = rows_of(mid)
check("关联变化才补那一行,且加在末尾不打乱人排的序",
[row.get("_link") for row in after] == [job1, job2, job3], after)
readded = next((row for row in after if row.get("_link") == job2), {})
check("人删掉的那一行随关联变化补回来,带的是对方那一列",
readded.get("amount") == 2300.5 and readded.get("note") == "机票", readded)
check("新关联的那张单也补一行", len(after) == 3 and after[-1].get("amount") == 777.25, after[-1:])
kept_row = after[0] if after else {}
check("重排也不覆盖人改过的那一列(没配带出的那一格)",
kept_row.get("qty") == 5, kept_row)
check("配到带出的那一列按来源刷新,人改的会被盖回去",
kept_row.get("note") == "打车" and kept_row.get("amount") == 120, kept_row)
check("关联到三张单,主表那两格跟着三张单算",
mid.get("total") == 3197.75
and mid.get("src_serial") == f"{serial1} / {serial2} / {serial3}",
f"{mid.get('total')} / {mid.get('src_serial')}")
# ---- 4. 取消关联:那一行与主表那几格一起撤 ----
data = step(db, dst_job, actor, {"orders": [job2]})
after = rows_of(data)
check("取消关联的那一行跟着删", [row.get("_link") for row in after] == [job2], after)
check("主表那一格换成剩下的那张单", data.get("src_serial") == serial2, data.get("src_serial"))
check("合计跟着换成剩下的那张单", data.get("total") == 2300.5, data.get("total"))
# ---- 5. 挂着的那张单查不到了(未发起就删了 / 单号写歪):不替它编一行 ----
ghost = "早就不在的那张单"
data = step(db, dst_job, actor, {"orders": [job2, ghost]})
after = rows_of(data)
check("查不到的那张单不补行,认得出的那一张照旧带着",
[row.get("_link") for row in after] == [job2], after)
check("主表那一格跳过查不到的那张,不报错也不挡人",
data.get("src_serial") == serial2 and data.get("total") == 2300.5,
f"{data.get('src_serial')!r} / {data.get('total')!r}")
# ---- 6. 只剩一张查不到的单:带不出值,必填那道闸把这次提交挡住 ----
message = step_blocked(db, dst_job, actor, {"orders": [ghost]})
check("带出来的那一格参与必填:带不出值就挡住提交", "合计" in message, message)
left = pending(db, dst_job)
check("挡下来之后还停在原来那一环,单没被推走",
left is not None and left.activity == handles[-1],
None if left is None else left.activity)
# ---- 7. 两个关联字段带同一张明细表:各带各的行,谁也不删对方的行 ----
data = step(db, dst_job, actor, {"orders": [job1], "buys": [job2]})
after = rows_of(data)
by_job = {str(row.get("_link") or ""): row for row in after}
check("后算的那一格不许把前一格刚补的那一行删掉",
[row.get("_link") for row in after] == [job2, job1], after)
check("各自带各自的行:报销单那一行是报销单的值",
by_job.get(job1, {}).get("amount") == 120
and by_job.get(job1, {}).get("note") == "打车", by_job.get(job1))
check("采购单那一行只被自己那一格的映射动过(金额还是报销那趟带出来的)",
by_job.get(job2, {}).get("note") == "机票"
and by_job.get(job2, {}).get("amount") == 2300.5, by_job.get(job2))
check("主表那两格只按自己那一格挂的单算",
data.get("src_serial") == serial1 and data.get("total") == 120,
f"{data.get('src_serial')!r} / {data.get('total')!r}")
# ---- 8. 预览那一道可见性闸:与 GET /work/summaries 同一分寸,再多认"挂在这一单上" ----
mine = preview(db, personref.ref_of(user), values=[job2], picks=["data.amount"])
check("预览认得与自己相关的那几张单", [item["job"] for item in mine] == [job2], mine)
# 回的是**对方那一格里存着的原话**(金额存成 "2,300.50" 就回它),收成目标那格的
# 形状是带出那一步的事(前后端各自按目标那一格的类型整型),接口不替人猜
check("回的是配好的那一条 pick 的原值", mine and mine[0]["values"] == {"data.amount": "2,300.50"}, mine)
stranger = "跟这件事毫无关系的人"
check("不相干的人问同一张单,静默少回而不是泄出去",
preview(db, stranger, values=[job2], picks=["data.amount"]) == [],
preview(db, stranger, values=[job2], picks=["data.amount"]))
check("但那几张单确实挂在正在填的这一单上,预览就带得出来(否则这一栏全是空白)",
[item["job"] for item in preview(db, stranger, values=[job1, job2],
picks=["data.amount"], work=dst_job)] == [job1, job2],
preview(db, stranger, values=[job1, job2], picks=["data.amount"], work=dst_job))
check("引擎那一份取单压根没有「谁在看」这个参数,也就没有这道闸",
linkfill.works_by_values(db, [job2]).get(job2) is not None, job2)
finally:
_cleanup(db)
db.close()
if FAILS:
print(f"共 {len(FAILS)} 条不对")
return 1
print(f"通过:关联带出走通了真提交({PASSED} 项)")
return 0
def _cleanup(db) -> None:
"""删干净自己造的那几张单与流程。"""
for table in (models.Work, models.WorkCompleted, models.Task, models.TaskCompleted,
models.WorkLog, models.Read, models.ReadCompleted, models.Attachment):
if CLEAN["jobs"] and hasattr(table, "job"):
db.execute(delete(table).where(table.job.in_(CLEAN["jobs"])))
for process in CLEAN["processes"]:
for table in (models.Activity, models.Route, models.ProcessVersion, models.ProcessSnapshot):
db.execute(delete(table).where(table.process == process))
db.execute(delete(models.Process).where(models.Process.id == process))
for form in CLEAN["forms"]:
db.execute(delete(models.FormElement).where(models.FormElement.id == form))
db.commit()
if __name__ == "__main__":
sys.exit(main())

View File

@ -1734,9 +1734,11 @@ def begin_id_of(db, process_id: str) -> str:
def cleanup(db) -> None:
"""连自己造的应用、订阅、流程、单据、表态一起删干净。"""
try:
process_ids = [CLEANUP.get("process", ""), CLEANUP.get("process_auto", ""), CLEANUP.get("process_locate", ""), CLEANUP.get("process_begin", ""), CLEANUP.get("process_begin_auto", ""), CLEANUP.get("process_begin_design", ""), CLEANUP.get("process_begin_start", ""), CLEANUP.get("process_parallel", ""),
# 开始环节锁着那一条也在这儿收:漏掉它,跑一次就在库里留一张没人认领的流程
CLEANUP.get("process_locked", ""), CLEANUP.get("process_begin_dup", "")]
# 每一条场景各造一张流程,这里按 key 前缀收,不手写名单:从前这份名单是手抄的,
# 抄漏的那几档每跑一次就在库里留一张没人认领的流程,而它行上挂的那张表单已经被
# 下面那一句删掉了——于是 check_job_payload 挨个流程量表单清单时,量出来一句
# 「SQL 那份清单与 form_ids() 不同源」,冤枉的其实是这张没扫干净的流程行。
process_ids = [pid for key, pid in CLEANUP.items() if key.startswith("process") and pid]
for pid in [item for item in process_ids if item]:
db.execute(delete(models.Route).where(models.Route.process == pid))
db.execute(delete(models.SerialNumber).where(models.SerialNumber.process == pid))

View File

@ -0,0 +1,495 @@
#!/usr/bin/env python3
"""守「待办办完了,那句『您有新的待办』就该退场」这一整条收尾。
症状(2026-11-10 用户截图):待办全部处理完,右上角铃铛里那叠通知消息还挂着四条
「您有新的待办」,小红点也不灭,只能靠「全部已读」手动清一遍——而清完列表还摆在原处。
根因是 ``oa_notification`` 只在写进去的那一刻有人看:``engine.notify`` 发完就不管,
接口只有「点开算已读」「全部已读」两个手动口子,而待办本身会消失(办结删行、或签
把同级一起结掉、转办与交接换持有人、终止与办结清空整单),每一条都不回头动站内信。
口径与取舍写在 :mod:`app.service.notify_settle`,一句话:**一条提醒值不值得摆着,
看它指向的那件事还在不在收件人自己手上**;收尾落在读出口(列表 / 未读数 / 工作台),
待办消失那七八条路子与升级前的存量数据一起管住。界面上这一屏从此只摆没读过的。
**全程跑在内存 sqlite 上,一条语句都不碰生产库**(引擎、站内信、接口都是真代码)::
cd backend && PYTHONPATH=. python3 scripts/check_notify_settle.py
分组:
A 判据 还在我手上 / 那条待办没了 / 换了持有人 / 没记待办号的老数据 / 空身份
B 不该动的 办结结果、控制类、会议、对接留痕,以及别人的与已读的
C 真流程 转办、或签自动结、终止、待阅登记之后,通知跟着事项一起收尾
D 接口与界面 列表、未读数、工作台三处同一份账;没未读时一趟收尾语句都不许多跑;
前端三个出口都只摆未读
"""
from __future__ import annotations
import os
import sys
from datetime import datetime
# 与 check_terminate_control.py 同一个理由:共享设计缓存是跨进程的,脚本里那些
# 固定流程 id 会读到上一趟自己存进去的设计,症状是"改了配置判据还是旧的"。
os.environ["OA_DESIGN_CACHE"] = "off"
from sqlalchemy import create_engine, event, func, select # noqa: E402
from sqlalchemy.orm import Session # noqa: E402
from sqlalchemy.pool import StaticPool # noqa: E402
from app import models # noqa: E402
from app.api import support as support_api # noqa: E402
from app.deps import CurrentUser # noqa: E402
from app.engine import definition as definition_module # noqa: E402
from app.engine import engine # noqa: E402
from app.service import notify_settle # noqa: E402
STARTER = ("1001", "张锦杰", "zhangjinjie")
HOLDER = ("2002", "陈晟罡", "chenshenggang")
HOLDER2 = ("2003", "贾晨铭", "jiachenming")
OTHER_ORG = ("3003", "黄雪秋", "huangxueqiu")
FAILS: list[str] = []
PASSED = 0
#: 收尾那两条 UPDATE 跑了没有、跑了几趟(D 组按这个数"没未读就不许多问")
SETTLE_STATEMENTS: list[str] = []
def check(label: str, ok: bool, detail: str = "") -> bool:
"""报一条结果;``ok`` 为假就记进失败清单,最后决定退出码。"""
global PASSED
if ok:
PASSED += 1
print(f"[通过] {label}")
else:
FAILS.append(label)
print(f"[FAIL] {label}{f' -> {detail}' if detail else ''}")
return ok
def new_session() -> Session:
"""内存库。模型里 MySQL 专属的 server_default 在 sqlite 上建不出来,建表前摘掉。"""
for table in models.Base.metadata.tables.values():
for column in table.columns:
if column.server_default is not None:
column.server_default = None
bind = create_engine("sqlite://", poolclass=StaticPool,
connect_args={"check_same_thread": False})
@event.listens_for(bind, "before_cursor_execute")
def _tally(conn, cursor, statement, parameters, context, executemany): # noqa: ANN001
lowered = statement.lower().replace("\n", " ")
if "update oa_notification" in lowered:
SETTLE_STATEMENTS.append(statement)
models.Base.metadata.create_all(bind)
db = Session(bind)
# 审批人配置与转办对象认的都是登录账号:库里没有这些人,引擎就组不出待办
for person_id, name, ref in (STARTER, HOLDER, HOLDER2, OTHER_ORG):
db.add(models.User(id=int(person_id), account=ref, display_name=name,
password_hash="", status=1))
db.flush()
return db
def actor_of(person, *, is_admin: bool = False) -> engine.Actor:
person_id, name, ref = person
return engine.Actor(person_id=person_id, person_name=name, ref=ref, is_admin=is_admin)
def user_of(person) -> CurrentUser:
"""接口要的那个登录身份。只建人员行,权限全给(这一门只关心收件人是谁)。"""
person_id, name, ref = person
row = models.User(id=int(person_id), account=ref, display_name=name, status=1)
return CurrentUser(person=row, ref=ref, is_admin=True, permissions=("work:profile",))
def make_flow(db: Session, tag: str, *, node_config: dict | None = None) -> str:
"""一张最小可用的流程:发起 → 财务经理 → 结束。回流程 id。
每个场景各用一条流程:设计缓存按流程 id 认,复用同一个 id 会读到上一趟那一份。
"""
pid = f"p-{tag}"
db.add(models.Process(id=pid, name=f"通知收尾校验流程 {tag}", latest_form="f-shared",
enabled=True, published=True))
db.add(models.Activity(id=f"{pid}-begin", process=pid, type="begin", name="发起", config={}))
db.add(models.Activity(id=f"{pid}-dept", process=pid, type="manual", name="财务经理",
config=dict(node_config or {"taskValues": [{"type": "identity",
"data": [HOLDER[2]]}]})))
db.add(models.Activity(id=f"{pid}-end", process=pid, type="end", name="结束", config={}))
db.add(models.Route(id=f"{pid}-r1", process=pid, name="提交", from_activity=f"{pid}-begin",
to_activity=f"{pid}-dept"))
db.add(models.Route(id=f"{pid}-r2", process=pid, name="同意", from_activity=f"{pid}-dept",
to_activity=f"{pid}-end"))
db.flush()
return pid
def make_work(db: Session, pid: str, tag: str, *, holders: list[tuple] | None = None) -> models.Work:
"""一张停在「财务经理」的单,待办压在 ``holders`` 手上(默认就是陈晟罡一条)。
通知按引擎真正的写法造(:func:`engine.notify`),这样"通知长什么样"不由脚本自说自话。
"""
now = datetime.now()
row = models.Work(
id=f"w-{tag}", job=f"j-{tag}", serial=f"S-{tag}", title=f"2026年10月VDI项目招待费 {tag}",
process=pid, process_name=f"通知收尾校验流程 {tag}", form="f-shared",
data={"title": "校验"}, creator=STARTER[0], creator_person=STARTER[1],
creator_identity=STARTER[2], status="running", activity=f"{pid}-dept",
activity_name="财务经理", activity_type="manual", current_activity_names="财务经理",
tokens=[{"activity": f"{pid}-dept", "path": "dept"}], start_time=now,
)
db.add(row)
db.flush()
for index, person in enumerate(holders or [HOLDER]):
person_id, name, ref = person
db.add(models.Task(
id=f"t-{tag}-{index}", job=row.job, work=row.id, title=row.title, status="pending",
process=pid, activity=f"{pid}-dept", activity_name="财务经理", activity_type="manual",
person=person_id, identity=ref, identity_name=name,
creator=STARTER[0], creator_person=STARTER[1], creator_identity=STARTER[2],
start_time=now,
))
db.flush()
arrive(db, row, pid, [p[2] for p in (holders or [HOLDER])])
return row
def arrive(db: Session, work: models.Work, pid: str, identities: list[str]) -> None:
"""到达这一环时引擎会发的那条站内信(``_notify_task`` 同一套参数)。"""
engine.notify(
db, identities, type_="task", title=f"您有新的待办:{work.title}",
body=f"{STARTER[1]} 提交的《{work.title}》等待您在【财务经理】环节处理。",
job=work.job, work=work.id, process=work.process, sender=STARTER[1],
)
db.flush()
def _sql_of(db: Session) -> str:
"""把收尾这两条 UPDATE 真的跑一遍,顺手把发出去的 SQL 原文捞回来。
钉的是子查询的**形状**:SELECT 的必须是 ``oa_task.id`` / ``oa_read.id``。写成
``select(Notification.id)`` 也能跑,但 SQLAlchemy 会把站内信表再拖进一次 FROM,
EXISTS 于是恒真——症状是"没记待办号的那几条永远收不掉",看不出来是判据写歪了。
"""
bind = db.get_bind()
captured: list[str] = []
@event.listens_for(bind, "before_cursor_execute")
def _grab(conn, cursor, statement, parameters, context, executemany): # noqa: ANN001
captured.append(statement)
try:
notify_settle.settle(db, HOLDER[2])
finally:
event.remove(bind, "before_cursor_execute", _grab)
return "\n".join(captured)
def note(db: Session, identity: str, *, task: str = "", work: str = "", type_: str = "task",
title: str = "标记") -> models.Notification:
"""塞一条站内信进库(走真 :func:`engine.notify`,顺手把 ``task`` / ``work`` 摆成要的样子)。"""
db.add(models.Notification(
id=f"n-{identity}-{type_}-{title}-{task}-{work}", type=type_, title=title, body="正文",
task=task, work=work, job="", process="p-x", identity=identity, read=False,
))
db.flush()
return db.get(models.Notification, f"n-{identity}-{type_}-{title}-{task}-{work}")
def unread(db: Session, identity: str) -> list[str]:
"""还没读过的站内信标题,排序好便于比较。"""
rows = db.execute(
select(models.Notification.title).where(
models.Notification.identity == identity, models.Notification.read.is_(False)
)
).scalars().all()
return sorted(rows)
# ---------------------------------------------------------------------------
# A 判据
# ---------------------------------------------------------------------------
def check_criteria() -> None:
db = new_session()
pid = make_flow(db, "a")
work = make_work(db, pid, "a")
task = db.execute(select(models.Task).where(models.Task.work == work.id)).scalars().first()
mine = note(db, HOLDER[2], task=task.id, work=work.id, title="带待办号")
legacy = note(db, HOLDER[2], task="", work=work.id, title="老数据没记待办号")
theirs = note(db, OTHER_ORG[2], task=task.id, work=work.id, title="别人的")
blank = note(db, HOLDER[2], task="", work="", title="事项号单据号都空")
arrived = f"您有新的待办:{work.title}"
check("A1 待办还在自己手上时一条都不许多收(读接口不许吃人)",
notify_settle.settle(db, HOLDER[2]) == 0, "第一次收尾就该 0 条")
check("A2 同一条待办的通知发给别人时,我这次收尾不许动别人的",
not theirs.read, "别人那条被误收了")
check("A3 事项号与单据号都是空的(说不出它指哪件事)宁可留着不误伤",
not blank.read, "空事项号那条被误收了")
left = unread(db, HOLDER[2])
check("A3+ 待办还挂着时,这个人名下一条都没被收走",
left == sorted([arrived, "带待办号", "老数据没记待办号", "事项号单据号都空"]), left)
# 那条待办办完了:引擎删行(_complete_task 就是删行),通知得跟着退
gone = note(db, HOLDER[2], task="t-早就没了", work=work.id, title="待办已消失")
db.delete(task)
db.flush()
notify_settle.settle(db, HOLDER[2])
check("A4 待办办完之后,那一条『您有新的待办』当场收尾", mine.read and gone.read)
check("A5 收尾时补上 read_time(已读时间空着,投递记录与界面就没法对账)",
bool(mine.read_time and gone.read_time), f"{mine.read_time} / {gone.read_time}")
check("A6 没记待办号的老数据按『这一单上还有没有我的待办』收尾",
legacy.read, "存量那条没退")
check("A6+ 收完之后只剩下说不清指向的那一条",
unread(db, HOLDER[2]) == ["事项号单据号都空"], unread(db, HOLDER[2]))
check("A6++ 别人名下那一条一个字都没被动过",
unread(db, OTHER_ORG[2]) == ["别人的"], unread(db, OTHER_ORG[2]))
check("A7 再收一次是 0 条(幂等,不反复改写已读时间)",
notify_settle.settle(db, HOLDER[2]) == 0)
stamp = mine.read_time
check("A8 已读的那几条不再被改写", mine.read_time == stamp and notify_settle.settle(db, HOLDER[2]) == 0)
# 交接 / 转办:待办行还在,只是不再属于你
db2 = new_session()
pid2 = make_flow(db2, "a2")
work2 = make_work(db2, pid2, "a2")
task2 = db2.execute(select(models.Task).where(models.Task.work == work2.id)).scalars().first()
handed = note(db2, HOLDER[2], task=task2.id, work=work2.id, title="交出去的那条")
task2.identity = OTHER_ORG[2]
db2.flush()
check("A9 待办换了持有人(交接 / 改派),原主人那两条都收尾:带待办号的那一条按号判,"
"没记号的那一条按『这一单上没有我的待办了』判——行还在,只是不再属于他",
notify_settle.settle(db2, HOLDER[2]) == 2 and handed.read)
check("A10 接手人那条同待办号的通知照旧留着(同一行待办,两个收件人各算各的)",
not note(db2, OTHER_ORG[2], task=task2.id, work=work2.id, title="接手人那条").read)
check("A11 没有这个收件人时直接回 0,不发语句",
notify_settle.settle(db2, "") == 0)
# 判据的写法本身也要钉住:EXISTS 里那个"再进一次 oa_notification"的坑,
# 症状是没记待办号的老数据永远收不掉(子查询变成笛卡尔积,只要这个人还有
# 任何一条站内信,EXISTS 就恒真)。SELECT 的必须是 oa_task.id / oa_read.id。
shape = _sql_of(db2)
check("A12 收尾那两条 UPDATE 的子查询只回表查待办 / 待阅,不再进一次站内信表",
"EXISTS (SELECT oa_task.id" in shape and "EXISTS (SELECT oa_read.id" in shape
and "oa_task, oa_notification" not in shape and "FROM oa_read, oa_notification" not in shape,
shape[:400])
# ---------------------------------------------------------------------------
# B 不该动的类型
# ---------------------------------------------------------------------------
def check_other_types() -> None:
db = new_session()
pid = make_flow(db, "b")
work = make_work(db, pid, "b")
task = db.execute(select(models.Task).where(models.Task.work == work.id)).scalars().first()
finished = note(db, HOLDER[2], type_="completed", task="", work=work.id, title="办结结果")
control = note(db, HOLDER[2], type_="control", task="", work=work.id, title="挂起提示")
meeting = note(db, HOLDER[2], type_="meeting", task="", work="", title="会议提醒")
integration = note(db, HOLDER[2], type_="integration", task="", work=work.id, title="对接留痕")
press_alive = note(db, HOLDER[2], type_="press", task=task.id, work=work.id, title="催办")
expire_alive = note(db, HOLDER[2], type_="expire", task=task.id, work=work.id, title="超时")
read_alive = note(db, HOLDER[2], type_="read", task="", work=work.id, title="抄送")
db.add(models.Read(id="r-b", job=work.job, work=work.id, identity=HOLDER[2], process=pid,
read_type="cc", requires_action=False))
db.flush()
check("B1 待办还挂着时,催办与超时提醒都留着",
notify_settle.settle(db, HOLDER[2]) == 0 and not press_alive.read and not expire_alive.read)
check("B2 抄送那一条在待阅还没登记时留着", not read_alive.read)
check("B3 办结结果 / 挂起恢复那类『已经发生的一件事』永远不动,哪怕这一单上没我的待办",
not any(item.read for item in (finished, control, meeting, integration)),
[item.title for item in (finished, control, meeting, integration) if item.read])
db.delete(task)
db.delete(db.execute(select(models.Read)).scalars().first())
db.flush()
notify_settle.settle(db, HOLDER[2])
check("B4 待办办完:催办与超时提醒一起退(点开要办的那三类同一族)",
press_alive.read and expire_alive.read)
check("B5 待阅登记完(那一行没了):抄送那一条退", read_alive.read)
check("B6 办结结果与会议提醒不跟着退",
not finished.read and not meeting.read and not control.read and not integration.read)
# ---------------------------------------------------------------------------
# C 真流程:引擎动完手,通知得跟着退
# ---------------------------------------------------------------------------
def start_job(db: Session, pid: str, actor) -> models.Work:
"""真发起一张单:走到「财务经理」,待办与那两条站内信都由引擎自己写。"""
result = engine.create_job(
db, process_id=pid, actor=actor,
data={"title": "2026年10月VDI项目招待费"}, title="2026年10月VDI项目招待费",
)
db.flush()
return result.work
def check_real_flow() -> None:
db = new_session()
pid = make_flow(db, "c")
work = start_job(db, pid, actor_of(STARTER))
task = db.execute(select(models.Task).where(models.Task.work == work.id)).scalars().first()
check("C1 引擎到达环节真的写下了那条『您有新的待办』(收尾判的是这份真数据)",
task is not None and unread(db, HOLDER[2]) == [f"您有新的待办:{work.title}"],
unread(db, HOLDER[2]))
# 转办:待办从陈晟罡手里转到贾晨铭手上
engine.transfer(db, task_id=task.id, actor=actor_of(HOLDER), identities=[HOLDER2[2]],
opinion="我在外出差")
db.flush()
check("C2 转办之后:原持有人那条当场收尾(问的是接口,收尾就挂在读出口)",
support_api.unread_count(user=user_of(HOLDER), db=db)["data"]["count"] == 0,
unread(db, HOLDER[2]))
check("C3 接手人收到的那一条(没记待办号那批)留着——他手上确实还有这条待办",
unread(db, HOLDER2[2]) and notify_settle.settle(db, HOLDER2[2]) == 0,
unread(db, HOLDER2[2]))
engine.terminate(db, job=work.job, actor=actor_of(STARTER), opinion="重发一张")
db.flush()
panel = [item["title"] for item in support_api.list_notifications(
user=user_of(HOLDER2), db=db, unread_only=True, page=1, page_size=12)["data"]["items"]]
check("C4 终止把整单待办清空之后,接手人那条『有新的待办』也收尾",
db.execute(select(func.count(models.Task.id)).where(
models.Task.work == work.id)).scalar() == 0
and f"您有新的待办:{work.title}" not in panel, unread(db, HOLDER2[2]))
check("C4+ 终止那一刻告诉他『这张单没了』的那条留下——那是新消息,不是过期提醒",
unread(db, HOLDER2[2]) == [f"待办已终止:{work.title}"], unread(db, HOLDER2[2]))
check("C5 终止那一刻发出去的控制类留痕不跟着退(它说的是已经发生的事)",
any(row.type == "control" and not row.read
for row in db.execute(select(models.Notification)).scalars().all()),
"没找到终止留痕那条站内信")
# 或签:同一环节两条待办,一人办结,引擎把同级一起结掉
db2 = new_session()
pid2 = make_flow(db2, "c2")
work2 = start_job(db2, pid2, actor_of(STARTER))
activity = definition_module.for_work(db2, work2).activity(f"{pid2}-dept")
siblings = [
models.Task(
id=f"t-c2-{index}", job=work2.job, work=work2.id, title=work2.title, status="pending",
process=pid2, activity=activity.id, activity_name=activity.name,
activity_type="manual", person=person, identity=ref, identity_name=name,
creator=STARTER[0], creator_person=STARTER[1], creator_identity=STARTER[2],
start_time=datetime.now(),
)
for index, (person, name, ref) in enumerate([HOLDER, HOLDER2])
]
db2.add_all(siblings)
db2.flush()
arrive(db2, work2, pid2, [HOLDER[2], HOLDER2[2]])
check("C6 两个人各有一条待办、各有一条未读(下一步的前提)",
unread(db2, HOLDER[2]) and unread(db2, HOLDER2[2]))
engine.execute_task(db2, task_id=siblings[0].id, actor=actor_of(HOLDER), route_name="同意")
db2.flush()
check("C7 或签一人办结:他这条通知收尾(走的是真 execute_task)",
support_api.unread_count(user=user_of(HOLDER), db=db2)["data"]["count"] == 0,
unread(db2, HOLDER[2]))
check("C8 同级那条待办被系统一起结掉了,他的通知也收尾(不用等他自己点开)",
db2.execute(select(func.count(models.Task.id)).where(
models.Task.work == work2.id)).scalar() == 0
and notify_settle.settle(db2, HOLDER2[2]) >= 1,
unread(db2, HOLDER2[2]))
# ---------------------------------------------------------------------------
# D 接口与界面
# ---------------------------------------------------------------------------
def check_surfaces() -> None:
db = new_session()
pid = make_flow(db, "d")
work = start_job(db, pid, actor_of(STARTER))
task = db.execute(select(models.Task).where(models.Task.work == work.id)).scalars().first()
note(db, HOLDER[2], type_="completed", task="", work=work.id, title="办结结果")
user = user_of(HOLDER)
SETTLE_STATEMENTS.clear()
panel = support_api.list_notifications(user=user, db=db, unread_only=True, page=1, page_size=12)
check("D1 铃铛面板只摆没读过的:待办还挂着时那一条还在",
sorted(item["title"] for item in panel["data"]["items"])
== sorted([f"您有新的待办:{work.title}", "办结结果"]), panel["data"]["items"])
db.delete(task)
db.flush()
panel = support_api.list_notifications(user=user, db=db, unread_only=True, page=1, page_size=12)
check("D2 待办办完之后重新打开面板:那条『您有新的待办』已经退场,只剩办结结果",
[item["title"] for item in panel["data"]["items"]] == ["办结结果"], panel["data"]["items"])
count = support_api.unread_count(user=user, db=db)["data"]["count"]
check("D3 小红点与面板是同一份账(面板空了就报 0)", count == 1, f"未读数 {count}")
stats = support_api.workbench(user=user, db=db)["data"]
check("D4 工作台『未读消息』那一格也是同一份账", stats["unread"] == count, stats)
support_api.read_all_notifications(user=user, db=db)
check("D5 全部已读之后:面板清空(以前按了按钮列表照旧堆在原处)",
support_api.list_notifications(user=user, db=db, unread_only=True, page=1,
page_size=12)["data"]["items"] == []
and support_api.unread_count(user=user, db=db)["data"]["count"] == 0)
SETTLE_STATEMENTS.clear()
support_api.unread_count(user=user, db=db)
check("D6 一条未读都没有时,收尾那两条 UPDATE 一趟都不许多跑(这颗角标 15 秒问一次)",
SETTLE_STATEMENTS == [], SETTLE_STATEMENTS)
# 有待办挂着(有未读)时收尾会跑,但收不掉任何东西,数字不许漂
db2 = new_session()
pid2 = make_flow(db2, "d2")
start_job(db2, pid2, actor_of(STARTER))
holder = user_of(HOLDER)
before = support_api.unread_count(user=holder, db=db2)["data"]["count"]
SETTLE_STATEMENTS.clear()
after = support_api.unread_count(user=holder, db=db2)["data"]["count"]
check("D7 待办还挂着时反复数,数字不许漂(收尾只认『事项已经不在了』)",
before == after == 1, f"{before} -> {after}")
frontend = _frontend_caliber()
check("D8 前端三个出口都只摆未读(铃铛下拉 / 手机版式 / 首页通知卡片)",
frontend == [], frontend)
def _frontend_caliber() -> list[str]:
"""钉住前端那一层:三个列出口都带 ``unread_only``,读过一条就退出面板。"""
import pathlib
import re
root = pathlib.Path(__file__).resolve().parents[2] / "frontend" / "src"
want = {
"components/layout/AppHeader.vue": 1,
"stores/app.ts": 1,
"views/oa/WorkbenchView.vue": 1,
}
problems: list[str] = []
for rel, times in want.items():
text = (root / rel).read_text(encoding="utf-8")
hits = len(re.findall(r"listNotifications\(\{[^}]*unread_only:\s*true", text, re.S))
if hits < times:
problems.append(f"{rel} 没带 unread_only")
app_store = (root / "stores" / "app.ts").read_text(encoding="utf-8")
if "notifications.value.filter((row) => row.id !== item.id)" not in app_store:
problems.append("stores/app.ts 读过之后没把那条退出面板")
return problems
def main() -> int:
for step in (check_criteria, check_other_types, check_real_flow, check_surfaces):
step()
print(f"\n共 {PASSED + len(FAILS)} 项:通过 {PASSED},失败 {len(FAILS)}")
for item in FAILS:
print(f" - {item}")
return 1 if FAILS else 0
if __name__ == "__main__":
sys.exit(main())

View File

@ -0,0 +1,403 @@
#!/usr/bin/env python3
"""候选路由自带的带出(``optionRoutes[].fill``)的验收:不打真上游,内存库。
PYTHONPATH=. python3 scripts/check_option_route_fill.py
用户那一句:「**一个组件中为什么不能配置多个外部数据源、数据字典,我通过表单中字段来判断
该用什么数据源,并且可以获取到数据带出写入其他字段。**」 条件路由那层已经让一格挂多家候选,
但「带出」以前只住在字段自己那份 ``fetch`` 里——多挂一家就得再写一条取数条目、把同一个触发
条件抄第二遍,抄漏一处就是「候选换了家、带出还是上一家的」。这一层把带出挂到**那一条路由上**:
命中哪一条,就用哪一张源、那一条的入参、那一条的带出去向(口径 docs/option-source-routing-design.md)。
下面几件事必须一直成立:
1. **只有一份判据**:命中哪一条、按哪一条取候选、按哪一条带出,三处是同一个结果;
前端镜像 ``utils/formFetch.fetchConfigOf`` 与这里 :func:`fetch.config_of` 算出同一份;
2. **跑的还是那一个执行器**:入参写法、多源、留痕、``onError``、发起后冻结都不新发明,
只是多一个「只写带出去向」的记号——**这一格自己那一个值是人从候选里挑的,不许被盖**;
3. **回落不破**:一条都不成立、或命中的那条没自带带出,读的就是字段上那份 ``fetch``
(老表单一个字节不用改);
4. **保存那一刻洗得干净**:只留 ``source`` / ``args`` / ``picks`` / ``extras``,
空壳整块抹掉,换一种来源时这份带出当残骸清掉;
5. **设计期逐条体检**:带出去向那一格还在不在、带出的键在不在源声明的清单里、
入参引用掉没掉在地上,门牌写「第 N 条候选来源的带出」,不与字段自己那一份串。
"""
from __future__ import annotations
import pathlib
import re
import sys
from urllib.parse import parse_qs, urlparse
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent))
from sqlalchemy import create_engine, event # noqa: E402
from sqlalchemy.orm import Session # noqa: E402
from sqlalchemy.pool import StaticPool # noqa: E402
from app import cache as shared_cache, models # noqa: E402
from app.service import dicts, fetch, formruntime # noqa: E402
PASSED = 0
FAILS: list[str] = []
SENT: list[dict] = []
#: 每个供应商对应的开户行与额度:一行一个答案,才看得出问的是哪一家
#: 两家取值的源各答自己那一份:问的是哪一家、带的是哪个供应商,凑一起才有答案
ANSWERS = {
("erp_bank", "V1"): ("中国银行总行", "50000"),
("crm_bank", "V2"): ("招商银行分行", "8000"),
}
TRAVEL = {"match": "all", "rules": [{"field": "expenseType", "op": "eq", "value": "travel"}]}
KEYS = {"expenseType", "vendor", "dept", "bankName", "creditLimit"}
def eq(name: str, got, want) -> None:
global PASSED
if got == want:
PASSED += 1
print(f"[通过] {name}")
else:
FAILS.append(name)
print(f"[FAIL] {name} -> 期望 {want!r},实得 {got!r}")
def ok(name: str, condition, detail=None) -> None:
global PASSED
if condition:
PASSED += 1
print(f"[通过] {name}")
else:
FAILS.append(name)
print(f"[FAIL] {name} -> {detail if detail is not None else '条件不成立'}")
def new_session() -> Session:
for table in models.Base.metadata.tables.values():
for column in table.columns:
if column.server_default is not None:
column.server_default = None
engine = create_engine("sqlite://", poolclass=StaticPool, connect_args={"check_same_thread": False})
@event.listens_for(engine, "before_cursor_execute")
def _noop(conn, cursor, statement, parameters, context, executemany): # noqa: ANN001
pass
models.Base.metadata.create_all(engine)
return Session(engine)
def seed(db: Session) -> None:
"""两家给候选清单的列表型源 + 两家查开户行的取值型源(候选与带出各问一家,最常见那种)。"""
for code in ("erp_vendors", "crm_vendors"):
db.add(models.DataSource(
id=code, code=code, name=f"候选路由带出校验·{code}", system="ERP",
kind=models.DataSource.KIND_SEARCH, provider=models.DataSource.PROVIDER_HTTP,
enabled=True, method="GET", url="https://" + code + ".invalid/api/vendors?dept={arg.dept}",
headers={}, body_template={}, pick="data.rows", map_value="code", map_label="name",
map_extra={}, auth_type=models.DataSource.AUTH_NONE,
cache_seconds=0, timeout_seconds=5, retries=0,
))
for code in ("erp_bank", "crm_bank"):
db.add(models.DataSource(
id=code, code=code, name=f"候选路由带出校验·{code}", system="ERP",
kind=models.DataSource.KIND_FETCH, provider=models.DataSource.PROVIDER_HTTP,
enabled=True, method="GET", url="https://" + code + ".invalid/api/bank?code={arg.code}",
headers={}, body_template={}, pick="data.bank",
map_extra={"bank": "data.bank", "limit": "data.limit"},
auth_type=models.DataSource.AUTH_NONE,
cache_seconds=0, timeout_seconds=5, retries=0,
))
db.commit()
def fake_http(method, url, body, headers, timeout): # noqa: ANN001
parts = parse_qs(urlparse(url).query)
asked = urlparse(url).hostname.split(".")[0] # 问的是哪一家
code = (parts.get("code") or [""])[0] # 取值型那一家带的是哪个供应商
SENT.append({"source": asked, "code": code})
row = ANSWERS.get((asked, code))
if row is None:
return (404, '{"code":404,"message":"没有这个供应商"}')
return (200, '{"code":0,"data":{"bank":"%s","limit":"%s"}}' % row)
def routed(*, own: bool = False, on_error: str = "keep") -> list[dict]:
"""一格「供应商」:差旅问 ERP 那份清单,其余回落 CRM 那份;命中那条自带一份带出。
候选问列表型源(``erp_vendors``),带出问取值型源(``erp_bank``)——「刚选中那一行的
其它列」本来就常常在另一家,这份夹具顺手把那条路也验了。``own=True`` 时字段自己也配
一份 ``fetch``,回落那条路才验得动。
"""
field: dict = {
"key": "vendor",
"label": "供应商",
"type": "picker",
"optionSource": "dataSource",
"dataSourceCode": "crm_vendors",
"optionRoutes": [
{"source": "dataSource", "when": TRAVEL, "dataSourceCode": "erp_vendors",
"dataSourceArgs": {"dept": "{form.dept}"},
"fill": {"source": "erp_bank", "args": {"code": "{form.vendor}"},
"picks": {"bank": "bankName", "limit": "creditLimit"}}},
],
}
if own:
field["fetch"] = {"source": "crm_bank", "args": {"code": "{form.vendor}"},
"picks": {"bank": "bankName"}, "onError": on_error}
else:
field["fetch"] = None
return [
field,
{"key": "expenseType", "label": "费用类型", "type": "select",
"options": [{"value": "travel", "label": "差旅"}, {"value": "meet", "label": "招待"}]},
{"key": "dept", "label": "部门", "type": "text"},
{"key": "bankName", "label": "开户银行", "type": "text"},
{"key": "creditLimit", "label": "信用额度", "type": "text"},
]
def apply(db: Session, fields: list[dict], data: dict) -> dict:
"""走一遍提交链路里那一趟外部取数(与真机同一句 ``apply_form``)。"""
fetch.apply_form(db, fields, data, actor="tester")
return data
# ---------------------------------------------------------------------------
# 1. 合成:命中哪一条,就按那一条带出
# ---------------------------------------------------------------------------
def check_compose() -> None:
field = routed()[0]
hit = fetch.config_of(field, {"expenseType": "travel", "vendor": "V1"})
ok("命中差旅那条时用的是它那一份带出", hit is not None and hit.get("source") == "erp_bank", hit)
eq("带出只写别的格子", hit.get(fetch.FILL_ONLY_KEY), True)
eq("带出去向跟着那一条", hit.get("picks"), {"bank": "bankName", "limit": "creditLimit"})
eq("带出入参用这一条自己那份", hit.get("args"), {"code": "{form.vendor}"})
shared = {"key": "vendor", "type": "picker", "optionSource": "dataSource", "dataSourceCode": "crm_vendors",
"optionRoutes": [{"source": "dataSource", "when": TRAVEL, "dataSourceCode": "erp_vendors",
"dataSourceArgs": {"dept": "{form.dept}"},
"fill": {"picks": {"bank": "bankName"}}}]}
eq("带出没另写入参时沿用这一条筛候选那一份",
fetch.config_of(shared, {"expenseType": "travel"}).get("args"), {"dept": "{form.dept}"})
eq("带出没另挑一家时问的就是这一条那一家",
fetch.config_of(shared, {"expenseType": "travel"}).get("source"), "erp_vendors")
with_args = {"key": "vendor", "type": "picker", "optionSource": "dataSource", "dataSourceCode": "crm_bank",
"optionRoutes": [{"source": "dataSource", "when": TRAVEL, "dataSourceCode": "erp_bank",
"dataSourceArgs": {"code": "{form.vendor}"},
"fill": {"args": {"code": "{form.other}"}, "picks": {"bank": "bankName"}}}]}
eq("带出自己写了入参就以它为准",
fetch.config_of(with_args, {"expenseType": "travel"}).get("args"), {"code": "{form.other}"})
miss = fetch.config_of(field, {"expenseType": "meet", "vendor": "V1"})
ok("一条都不成立回落到字段那一份", miss is None, miss)
# 命中的那一条没自带带出 → 也是回落(老表单正是这个样子)
plain = {"key": "vendor", "type": "picker", "optionSource": "dataSource", "dataSourceCode": "crm_bank",
"optionRoutes": [{"source": "dataSource", "when": TRAVEL, "dataSourceCode": "erp_bank"}]}
eq("命中的那条没带出就回落", fetch.config_of(plain, {"expenseType": "travel"}), None)
# 带出另挑一家:候选问 A 家清单、那几列在 B 家
other = {"key": "vendor", "type": "picker", "optionSource": "dataSource", "dataSourceCode": "crm_bank",
"optionRoutes": [{"source": "dataSource", "when": TRAVEL, "dataSourceCode": "erp_bank",
"fill": {"source": "crm_bank", "picks": {"bank": "bankName"}}}]}
eq("带出可以另问一家", fetch.config_of(other, {"expenseType": "travel"}).get("source"), "crm_bank")
# 还没选源的条目:没有可带出的列
empty = {"key": "vendor", "type": "picker", "optionSource": "dataSource",
"optionRoutes": [{"source": "dataSource", "when": TRAVEL, "fill": {"picks": {"a": "b"}}}]}
eq("那一条还没选源就不带出", fetch.config_of(empty, {"expenseType": "travel"}), None)
eq("这一格会不会往外写值", fetch.has_fetch(field), True)
eq("只配了候选路由也算配过取数",
fetch.has_fetch({"key": "v", "type": "picker",
"optionRoutes": [{"source": "dataSource", "dataSourceCode": "erp",
"fill": {"picks": {"bank": "b"}}}]}), True)
eq("什么都没配", fetch.has_fetch({"key": "v", "type": "text"}), False)
# ---------------------------------------------------------------------------
# 2. 运行时:带出写进目标格,这一格自己那一个值不动
# ---------------------------------------------------------------------------
def check_runtime(db: Session) -> None:
SENT.clear()
data = apply(db, routed(), {"expenseType": "travel", "vendor": "V1", "dept": "制造事业部", "bankName": "", "creditLimit": ""})
eq("带出写进了开户行那一格", data["bankName"], "中国银行总行")
eq("额度那一格也带上了", data["creditLimit"], "50000")
eq("这一格自己那一个值没被盖掉", data["vendor"], "V1")
eq("问的就是命中的那一家,带的是刚选中的那个供应商", SENT, [{"source": "erp_bank", "code": "V1"}])
trace = (data.get(fetch.TRACE_KEY) or {}).get("vendor") or {}
eq("留痕照记这一笔外呼", trace.get("source"), "erp_bank")
# 带出去向里指着自己那一格的老配置(设计期已拦,这里兜接口直传那一条路)
SENT.clear()
selfish = routed()
selfish[0]["optionRoutes"][0]["fill"]["picks"]["value"] = "vendor"
data = apply(db, selfish, {"expenseType": "travel", "vendor": "V1", "dept": "制造事业部",
"bankName": "", "creditLimit": ""})
eq("带出去向里指着自己的那一行不写", data["vendor"], "V1")
eq("该写的格子照写", data["bankName"], "中国银行总行")
# 换一家:带出去向跟着换,问的是另一家
SENT.clear()
data = apply(db, routed(), {"expenseType": "meet", "vendor": "V2", "bankName": "", "creditLimit": ""})
eq("回落那条路这一版没配字段级取数,一个请求都不发", SENT, [])
eq("没跑就不动任何格子", data["bankName"], "")
# ---------------------------------------------------------------------------
# 3. 回落:字段那份 fetch 仍然照跑
# ---------------------------------------------------------------------------
def check_fallback(db: Session) -> None:
SENT.clear()
rows = routed(own=True)
data = apply(db, rows, {"expenseType": "meet", "vendor": "V2", "bankName": ""})
eq("一条都不成立时跑字段上那份取数", [item["source"] for item in SENT], ["crm_bank"])
eq("字段那份的带出照写", data["bankName"], "招商银行分行")
SENT.clear()
data = apply(db, routed(own=True),
{"expenseType": "travel", "vendor": "V1", "bankName": ""})
eq("命中那条自带带出时只跑它那一份", [item["source"] for item in SENT], ["erp_bank"])
eq("带出写的是命中那一条的去向", data["bankName"], "中国银行总行")
eq("这一格那一个值还是人挑的", data["vendor"], "V1")
# ---------------------------------------------------------------------------
# 4. 失败策略:不盖这一格,也不清零它
# ---------------------------------------------------------------------------
def check_on_error(db: Session) -> None:
from app.engine import engine as engine_module
rows = routed(own=True, on_error="block")
# onError 在合成时从字段那份继承(它问的是「这一格怎么待人」)
SENT.clear()
try:
apply(db, rows, {"expenseType": "travel", "vendor": "V404", "bankName": ""})
eq("取不到时 block 该挡提交", "没挡", "挡了")
except engine_module.EngineError as exc:
ok("取不到时 block 挡提交,报错说的是这一条的带出", "外部数据取不到" in str(exc), str(exc))
# zero 也不该去清这一格:要清的本来不是它
rows[0]["fetch"]["onError"] = "zero"
data = apply(db, rows, {"expenseType": "travel", "vendor": "V404", "bankName": "", "creditLimit": ""})
eq("zero 那档不清这一格自己那一个值", data["vendor"], "V404")
eq("zero 那档也不清带出去向那两格", (data["bankName"], data["creditLimit"]), ("", ""))
# ---------------------------------------------------------------------------
# 5. 设计期体检
# ---------------------------------------------------------------------------
def check_design_time(db: Session) -> None:
keys = KEYS
good = routed()[0]
eq("配好的那份不报错", formruntime.option_source_problems(good, db, keys), [])
dead = routed()[0]
dead["optionRoutes"][0]["fill"] = {"source": "erp_bank", "picks": {"bank": "gone_field"}}
problems = formruntime.option_source_problems(dead, db, keys)
ok("带出去向那一格已经被删掉要说", any("gone_field" in text for text in problems), problems)
ok("门牌写「第 N 条候选来源的带出」", any("第 1 条候选来源的带出" in text for text in problems), problems)
undeclared = routed()[0]
undeclared["optionRoutes"][0]["fill"] = {"source": "erp_bank", "picks": {"nope": "bankName"}}
problems = formruntime.option_source_problems(undeclared, db, keys)
ok("带出的键不在源声明的清单里要说", any("nope" in text for text in problems), problems)
ref = routed()[0]
ref["optionRoutes"][0]["fill"] = {"source": "erp_bank", "args": {"code": "{form.gone}"},
"picks": {"bank": "bankName"}}
problems = formruntime.option_source_problems(ref, db, keys)
ok("入参引用掉在地上要说", any("gone" in text for text in problems), problems)
# 带出去向不能是这一格自己(这一格的值是人挑的)
self_ref = routed()[0]
self_ref["optionRoutes"][0]["fill"] = {"source": "erp_bank", "picks": {"bank": "vendor"}}
problems = formruntime.option_source_problems(self_ref, db, keys)
ok("带进自己那一格要说", any("自己" in text for text in problems), problems)
# ---------------------------------------------------------------------------
# 6. 保存那一刻的清洗
# ---------------------------------------------------------------------------
def check_cleaning() -> None:
field = {"key": "vendor", "type": "picker", "optionSource": "dataSource", "dataSourceCode": "crm_bank",
"optionRoutes": [
{"source": "dataSource", "dataSourceCode": "erp_bank",
"fill": {"source": "", "args": {"code": "{form.x} ", " ": "y", "k": ""},
"picks": {"bank": " bankName "}, "extras": {"": "data.a", "b": " data.b "},
"note": "带出不该有备注那一格"}},
{"source": "dict", "dictCode": "d", "fill": {"picks": {"a": "b"}}},
]}
cleaned = dicts.clean_routes(field)
eq("清洗只留说得出的那几格", cleaned[0]["fill"],
{"args": {"code": "{form.x}"}, "picks": {"bank": "bankName"}, "extras": {"b": "data.b"}})
eq("空 source 不留", "source" in cleaned[0]["fill"], False)
eq("字典那一条的带出当残骸丢掉", "fill" in cleaned[1], False)
eq("整块都没填时不留空壳", dicts.clean_routes(
{"key": "v", "type": "picker", "optionRoutes": [{"source": "dataSource", "dataSourceCode": "e",
"fill": {"picks": {"": ""}}}]})[0].get("fill"), None)
eq("洗一遍是幂等的", dicts.clean_routes({"key": "v", "type": "picker", "optionRoutes": cleaned}), cleaned)
# ---------------------------------------------------------------------------
# 7. 前后端对齐:键名一份、常量一份
# ---------------------------------------------------------------------------
def check_parity() -> None:
root = pathlib.Path(__file__).resolve().parents[2]
ts = root / "frontend/src/utils/optionSource.ts"
if not ts.exists():
print("[跳过] 找不到前端那份 " + str(ts))
return
text = ts.read_text(encoding="utf-8")
ok("带出那个键名两边同一个", f"export const ROUTE_FILL_KEY = '{dicts.ROUTE_FILL_KEY}'" in text, True)
for table in dicts.ROUTE_FILL_TABLES:
ok(f"三张表里的「{table}」两边都在", f"'{table}'" in text, table)
ok("前端也认「只写带出去向」这一记号",
"fillOnly" in (root / "frontend/src/types/index.ts").read_text(encoding="utf-8"), True)
fetch_ts = (root / "frontend/src/utils/formFetch.ts").read_text(encoding="utf-8")
ok("前端那份也按此刻命中的那条合成", "routeFetchConfig" in fetch_ts and "fetchConfigOf" in fetch_ts, True)
ok("前端也只写带出去向、不盖这一格", "fetchPickWrites" in fetch_ts, True)
# 后端这份不该把这一格的值写回去
body = fetch.__doc__ or ""
ok("后端那份的说明里钉着同一句话", "fillOnly" in pathlib.Path(fetch.__file__).read_text(encoding="utf-8"), body[:60])
def main(argv: list[str]) -> int:
db = new_session()
fetch._cache.clear()
# 这一趟不碰 Redis:带出的那份缓存与留痕不该依赖共享缓存活着
shared_cache.get_json = lambda *a, **k: None # type: ignore[assignment]
shared_cache.set_json = lambda *a, **k: None # type: ignore[assignment]
fetch.http_request = fake_http # type: ignore[assignment]
seed(db)
stages = [
("命中哪一条就按那一条带出", check_compose),
("带出写进目标格、这一格不动", lambda: check_runtime(db)),
("一条都不成立回落到字段那份", lambda: check_fallback(db)),
("取不到时不盖也不清这一格", lambda: check_on_error(db)),
("设计期逐条体检", lambda: check_design_time(db)),
("保存那一刻的清洗", check_cleaning),
("前后端键名与常量对齐", check_parity),
]
for title, stage in stages:
before = len(FAILS)
try:
stage()
except Exception as exc: # noqa: BLE001 某一段炸了也要跑完剩下的
FAILS.append(f"{title} 这一段抛异常:{exc!r}")
print(f"[FAIL] {title} 抛异常:{exc!r}")
marks = "通过" if len(FAILS) == before else f"{len(FAILS) - before} 条不对"
print(f"[{marks}] {title}")
for line in FAILS:
print(f"[FAIL] {line}")
if FAILS:
print(f"共 {len(FAILS)} 条不对")
return 1
print(f"通过:候选路由自带的带出与前端口径一致({PASSED} 项)")
return 0
if __name__ == "__main__":
raise SystemExit(main(sys.argv[1:]))

View File

@ -0,0 +1,830 @@
"""候选来源的条件路由(``optionRoutes``)与「带出的值也收下」的验收脚本(不连库)::
PYTHONPATH=. python3 scripts/check_option_routes.py
用户那句原话:**「我一个组件中为什么不能配置多个外部数据源、数据字典?我通过表单中字段
来判断我该组件中该用什么数据源。」** 以前一格只有一答(要么字典、要么一张源、要么手填那几条),
要换家只有两条路:摆三格用显隐条件把另外两格藏起来(三格 = 三个字段名 = 三份导出列与三套环节
权限),要么去对面求一个聚合接口。这一层给第三答——字段上多挂一份**有序清单**,每一条 =
一个触发条件 + 一套候选来源配置,自上而下第一条成立的用它,一条都不成立回落到字段自己那一份
(= 改动前行为,老表单一个字节都不用改)。设计见 ``docs/option-source-routing-design.md``。
下面九件事必须一直成立:
1. **只有一份判据**:命中哪一条、按哪一条取候选、按哪一条判越界,三处必须是同一个结果。
界面按 A 家的候选渲染、提交按 B 家判越界,是这一整套最容易犯的错(前端镜像
``src/utils/optionSource.ts``,第 9 段把两份算法的常量与措辞逐句对);
2. **脏条目当没配**:认不出的来源、配到一半的空条目、第 9 条起多出来的都丢掉,宁可回落;
3. **视图只动来源那一维**:挑选方式、多选、关联带出这些与来源无关的格子原样留着,
而且不许多改一张字段传进来的那份;
4. **保存那一刻洗得干净**:``api/design.py`` 走的是 ``dicts.clean_routes``,主表字段与
明细列两条路都要过,级联与多选月份那两类压根没有候选来源,清单得整份抹掉;
5. **「带出的值不在候选里也收下」真收**:勾上之后越界不拦(``selection_problems`` 那一档),
没勾照旧拦——默认关,老表单行为一字不变;
6. **上游问得全**:删字典前的「哪些表单在用」、预取清单、级联清失效值,都得把路由里那几本
字典与那些触发条件字段算进来,漏一处就是「界面拿着上一家的候选清单继续判越界」;
7. **回看与必填不再死锁**:因**显示条件不成立**而藏起来的系统带出格不再算必填(那句
「屏幕上没有那一格,提交却永远说它没填」),勾了默认隐藏又没配条件的照旧仍然要有值;
8. **外部取数那一头同一分寸**:条目上配了触发条件的只跑成立的那几条(``binding.active_entries``
↔ 前端 ``formFetch.activeFetchEntries``),一条都不成立=这一格这回不取数,不是失败;
9. **翻名字跟着命中的那一条走**:同一格这一单用差标字典、那一单用费用科目,只读与标题
念出来的名字得按**那一单当时命中的那一条**翻。
"""
from __future__ import annotations
import inspect
import pathlib
import re
import sys
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent))
from app import models # noqa: E402 (需要上面那行把 backend 目录放进 sys.path)
from app.api import design as design_api # noqa: E402 (保存那一刻真正走的那一步清洗)
from app.service import binding, dicts, exportfmt, fetch, formruntime, titles # noqa: E402
FAILS: list[str] = []
TRAVEL = {"match": "all", "rules": [{"field": "expenseType", "op": "eq", "value": "travel"}]}
MEET = {"match": "all", "rules": [{"field": "expenseType", "op": "eq", "value": "meet"}]}
DICT_ITEMS = {
"acct_common": [
{"value": "C1", "label": "通用科目一", "enabled": True},
{"value": "C2", "label": "通用科目二", "enabled": True},
],
"acct_travel": [
{"value": "T1", "label": "火车票", "enabled": True},
{"value": "T2", "label": "住宿费", "enabled": True, "extra": {"code": "TR-01"}},
],
"region": [
{"value": "GD", "label": "广东", "enabled": True},
{"value": "GD_SZ", "label": "深圳", "parent": "GD", "enabled": True},
],
}
def eq(name: str, got, want) -> None:
"""取值相等;不等就把两边都打出来,方便一眼看出是形状变了还是值变了。"""
if got != want:
FAILS.append(f"{name}:期望 {want!r},实得 {got!r}")
def ok(name: str, condition, detail=None) -> None:
if not condition:
FAILS.append(f"{name}:{detail if detail is not None else '条件不成立'}")
class FakeCache:
"""顶替 ``dicts.DictCache``:这一层只用到 ``items`` 与 ``index`` 两句。"""
def __init__(self, mapping: dict[str, list[dict]] | None = None) -> None:
self.mapping = mapping if mapping is not None else DICT_ITEMS
def items(self, code: str) -> list[dict]:
return [dict(item) for item in self.mapping.get(code, [])]
def index(self, code: str) -> dict[str, dict]:
return {str(item.get("value")): dict(item) for item in self.items(code)}
def prefetch(self, codes): # pragma: no cover - 预取不是这一份脚本要钉的
return None
class Source:
"""顶替 ``DataSource`` 那一行:``source_problem`` 只用 getattr 读几个属性。"""
def __init__(self, code: str, name: str = "", enabled: bool = True,
kind: str = models.DataSource.KIND_SEARCH) -> None:
self.code = code
self.name = name or code
self.enabled = enabled
self.kind = kind
self.direction = models.DataSource.DIRECTION_IN
class FakeDB:
"""一个用例只查一张源:把要给它的那一行(或 ``None``)存好就行。"""
def __init__(self, row: Source | None) -> None:
self.row = row
def execute(self, _statement):
row = self.row
class _Result:
def scalar_one_or_none(self):
return row
return _Result()
def subject(**patch: object) -> dict:
"""一张「报销科目」下拉:字段自己那一份是兜底候选(一本通用字典)。"""
field = {
"key": "expenseItem",
"label": "报销科目",
"type": "select",
"optionSource": "dict",
"dictCode": "acct_common",
}
field.update(patch)
return field
def routes() -> list[dict]:
"""两条最常见的换家:差旅问一本字典、招待问一张 ERP 源。"""
return [
{"source": "dict", "when": TRAVEL, "dictCode": "acct_travel"},
{"source": "dataSource", "when": MEET, "dataSourceCode": "erp_meet"},
]
def values_of(items) -> list[str]:
return [str(item.get("value")) for item in (items or [])]
# ---------------------------------------------------------------------------
# 1. 命中哪一条:有序、第一条成立的说话、全不成立回落
# ---------------------------------------------------------------------------
def check_matching() -> None:
"""回落到字段自己那一份 = 改动前的行为,这一条是整个特性的地基。"""
plain = subject()
eq("没配清单就是空", dicts.routes_of(plain), [])
eq("没配清单没有命中", dicts.matched_route(plain, {"expenseType": "travel"}), None)
eq("没配清单视图就是字段本身", dicts.option_view(plain, {"expenseType": "travel"}), plain)
eq("候选照旧是字段上那本字典",
values_of(dicts.effective_options(plain, {}, FakeCache())), ["C1", "C2"])
routed = subject(optionRoutes=routes())
eq("命中第一条", (dicts.matched_route(routed, {"expenseType": "travel"}) or {}).get("dictCode"),
"acct_travel")
eq("取的是那一条的候选",
values_of(dicts.effective_options(routed, {"expenseType": "travel"}, FakeCache())), ["T1", "T2"])
# 外部数据源那一条:候选是搜出来的,服务端手上没有全量清单,一律回 None(与不挂路由时同一句)
eq("命中外部数据源那条时没有全量清单",
dicts.effective_options(routed, {"expenseType": "meet"}, FakeCache()), None)
# 一条都不成立:回落,老表单行为
eq("全不成立回落", dicts.matched_route(routed, {"expenseType": "other"}), None)
eq("回落时候选还是字段上那本",
values_of(dicts.effective_options(routed, {"expenseType": "other"}, FakeCache())), ["C1", "C2"])
# 顺序敏感:两条都成立时排在上面的赢;没写条件那条恒成立,天生是「其余情况」那一档
both = subject(optionRoutes=[
{"source": "dict", "dictCode": "acct_travel"},
{"source": "dict", "when": TRAVEL, "dictCode": "region"},
])
eq("排在上面的先说话", (dicts.matched_route(both, {"expenseType": "travel"}) or {}).get("dictCode"),
"acct_travel")
fallback_last = subject(optionRoutes=[
{"source": "dict", "when": TRAVEL, "dictCode": "acct_travel"},
{"source": "manual", "options": [{"value": "X", "label": "其他"}]},
])
eq("不成立时轮到那条无条件的兜底",
values_of(dicts.effective_options(fallback_last, {}, FakeCache())), ["X"])
# ---------------------------------------------------------------------------
# 2. 视图只动来源那一维
# ---------------------------------------------------------------------------
def check_view() -> None:
"""视图是「此刻这一格」那份配置:上一家的残骸不许混进来,与来源无关的格子不许动。"""
field = subject(
relationProcess="should_not_leak",
pickerStyle="dialog",
multiple=True,
linkFill={"rules": [{"source": "serial", "to": "amount"}]},
optionRoutes=[{"source": "dict", "when": TRAVEL, "dictCode": "acct_travel",
"cascadeFrom": "province", "optionMap": {"valueKey": "extra.code", "labelKey": "label"}}],
)
view = dicts.option_view(field, {"expenseType": "travel"})
eq("视图换了来源", view.get("optionSource"), "dict")
eq("用的是那一条的字典", view.get("dictCode"), "acct_travel")
eq("级联上级也来自那一条", view.get("cascadeFrom"), "province")
# 别家的痕迹不进视图:留着 dictCode 那种残骸是「界面一个值、提交另一个值」的病根
ok("别家残骸不进视图", "relationProcess" not in view and "dataSourceCode" not in view, list(view))
# 与来源无关的用法原样留着
eq("挑选方式原样", view.get("pickerStyle"), "dialog")
eq("多选原样", view.get("multiple"), True)
eq("关联带出原样", view.get("linkFill"), {"rules": [{"source": "serial", "to": "amount"}]})
# 传进来的那份没被改脏
eq("字段本体不动", field.get("dictCode"), "acct_common")
# 那一条自己那份「显示 / 存值」跟着走:存的值由它说
eq("按那一条的存值列取值", dicts.stored_of(view, {"value": "T2", "label": "住宿费",
"extra": {"code": "TR-01"}}), "TR-01")
eq("按那一条的显示列念名字", dicts.shown_of(view, {"value": "T2", "label": "住宿费"}), "住宿费")
# 挂不上这一类字段的来源:视图原样退回,不会把字段改成它挑不了的样子
radio = {"key": "r", "type": "text", "optionRoutes": [{"source": "dict", "dictCode": "acct_travel"}]}
eq("文本框没有候选来源可言", dicts.routes_of(radio), [])
# ---------------------------------------------------------------------------
# 3. 脏条目当没配:宁可回落,不要一只永远为空的挑选器
# ---------------------------------------------------------------------------
def check_dirty() -> None:
"""接口直传与 AI 起草都会送进奇形怪状的清单,这一层的态度是「当没配」。"""
eq("非数组当没配", dicts.routes_of(subject(optionRoutes="nope")), [])
eq("条目不是物件的丢掉", dicts.routes_of(subject(optionRoutes=[None, 1, "x"])), [])
eq("认不出的来源丢掉", dicts.routes_of(subject(optionRoutes=[{"source": "nope", "dictCode": "x"}])), [])
# 关联审批单挑不了手填选项:那一条丢,别的那条照留
relation = {
"key": "rel", "type": "relation", "optionSource": "process",
"optionRoutes": [{"source": "manual", "options": [{"value": "A", "label": "甲"}]},
{"source": "dict", "dictCode": "acct_travel"}],
}
eq("这一类字段挑不了的来源单独丢", [item["source"] for item in dicts.routes_of(relation)], ["dict"])
# 空的来源配置不进路由:进了会把视图里那格抹成空,比回落还糟
eq("半截配置只留下认得的那几格",
dicts.routes_of(subject(optionRoutes=[{"source": "dict", "when": TRAVEL, "dictCode": ""}])),
[{"source": "dict", "when": TRAVEL}])
# 上限:再多就不是「换一家」而是该做聚合接口了,而且清单越长越没人说得清哪一条会赢
many = [{"source": "dict", "dictCode": "a"}] * (dicts.MAX_OPTION_ROUTES + 3)
eq("超出上限的截掉", len(dicts.routes_of(subject(optionRoutes=many))), dicts.MAX_OPTION_ROUTES)
ok("上限那一句在设计期说", any("多出来的不会被用上" in text
for text in dicts.route_problems(subject(optionRoutes=many))),
dicts.route_problems(subject(optionRoutes=many)))
# ---------------------------------------------------------------------------
# 4. 保存那一刻洗得干净(走的是接口真正调的那一步)
# ---------------------------------------------------------------------------
def check_cleaning() -> None:
"""``api/design.py`` 保存字段时经过的清洗:清单、上限、残骸、备注、非法开关。"""
content = {"fields": [
# 条件点名的那一格得在场,否则 validate_schema 会先说「引用了不存在的字段」
{"key": "expenseType", "label": "报销类型", "type": "select",
"options": [{"value": "travel", "label": "差旅"}, {"value": "meet", "label": "招待"}]},
subject(pickerStyle="dialog", optionRoutes=[
# 第一条:备注留着,relationStatuses 那一家带来的空值不留
{"source": "dict", "when": TRAVEL, "dictCode": "acct_travel", "note": "这一条问财务要的",
"relationStatuses": [], "relationProcess": ""},
# 第二条:来源认不出 → 整条丢
{"source": "nope", "dictCode": "x"},
# 第三条:全勾状态等于不限 → 不留这个键
{"source": "process", "when": MEET, "relationProcess": "p1",
"relationStatuses": list(dicts.RELATION_STATUSES)},
# 第四条:没写条件的兜底那条,条件这个键本来就没有
{"source": "manual", "options": [{"value": "X", "label": "其他"}]},
]),
# 级联与文本框:压根没有候选来源,清单与开关都得整份抹掉
{"key": "c", "type": "dicts_cascader", "dictCode": "region", "optionSource": "dict",
"optionRoutes": [{"source": "dict", "dictCode": "a"}], "allowOutsideValue": True},
{"key": "t", "type": "text", "optionRoutes": [{"source": "dict", "dictCode": "a"}],
"allowOutsideValue": "true"},
# 明细列也走同一句清洗
{"key": "tbl", "type": "table", "columns": [
{"key": "cate", "label": "类别", "type": "select", "options": [{"value": "A", "label": "甲"}]},
{"key": "item", "label": "科目", "type": "select", "optionSource": "dict",
"dictCode": "acct_common", "optionRoutes": [
{"source": "dict", "when": TRAVEL, "dictCode": "acct_travel", "cascadeFrom": "cate"},
{"source": "manual", "options": [{"value": "X", "label": "其他"}]}]},
]},
]}
content["fields"][2]["type"] = "cascader" # 上面那个占位写法改掉:级联字段就是 type=cascader
saved = design_api.clean_option_source(content)["fields"]
first = saved[1]["optionRoutes"]
eq("认不出的那条整条丢掉", [item["source"] for item in first], ["dict", "process", "manual"])
eq("备注留着(只给配表单的人看)", first[0].get("note"), "这一条问财务要的")
eq("别家的空残骸不留", [key for key in ("relationStatuses", "relationProcess") if key in first[0]], [])
eq("全勾状态等于不限,不留这个键", "relationStatuses" in first[1], False)
eq("兜底那一条不写条件也活得下来", "when" in first[2], False)
eq("字段自己那一份留着", saved[1]["dictCode"], "acct_common")
ok("级联字段上的清单整份抹掉", "optionRoutes" not in saved[2], saved[2])
ok("文本框上的清单与开关都抹掉",
"optionRoutes" not in saved[3] and "allowOutsideValue" not in saved[3], saved[3])
column = saved[4]["columns"][1]
eq("明细列同样被洗", [item["source"] for item in column["optionRoutes"]], ["dict", "manual"])
eq("明细列那一条只留下它自己那几格", column["optionRoutes"][0].get("cascadeFrom"), "cate")
eq("明细列的级联上级指着同表的列", [col["key"] for col in saved[4]["columns"]][:2], ["cate", "item"])
# 一条有效都不剩:整份抹掉,别留一份空数组让下一任以为配过什么
empty = design_api.clean_option_source({"fields": [subject(optionRoutes=[{"source": "nope"}])]})["fields"][0]
ok("全丢光时不留空数组", "optionRoutes" not in empty, empty)
# 开关只认真布尔值:字符串 "true" 与 1 都当没配
flags = design_api.clean_option_source({"fields": [
subject(allowOutsideValue=True), subject(allowOutsideValue="true"), subject(allowOutsideValue=1)]})["fields"]
eq("开关只认真布尔值", [item.get("allowOutsideValue") for item in flags], [True, None, None])
# 字段自己挂的不是字典、但**某一条候选是字典**:那一档命中时带的就是它那本的附加值,
# autoFill 是这一档唯一的配法(外部数据源那一条自己带 fill),不能当上一家的残骸洗掉
routed_fill = {
"key": "project", "label": "项目", "type": "select",
"optionSource": "dataSource", "dataSourceCode": "erp_project",
"autoFill": [{"field": "project", "pick": "code", "to": "projectCode"}],
"optionRoutes": [{"source": "dict", "when": TRAVEL, "dictCode": "acct_travel"}],
}
washed = design_api.clean_option_source(
{"fields": [subject(), routed_fill,
{**routed_fill, "optionRoutes": [
{"source": "dataSource", "when": TRAVEL, "dataSourceCode": "erp_project"}]}]})["fields"]
eq("路由里挂着字典时 autoFill 保住", washed[1].get("autoFill"), routed_fill["autoFill"])
ok("字段与路由都没字典时 autoFill 照旧洗掉", "autoFill" not in washed[2], washed[2])
# 清洗完的表单存得下去:路由不能把 validate_schema 惹出一堆新错
eq("洗过的表单校验通过", formruntime.validate_schema(saved, db=None), [])
# ---------------------------------------------------------------------------
# 5. 把关跟着命中的那一条走 + 「带出的值也收下」
# ---------------------------------------------------------------------------
def check_guard() -> None:
"""同一格这一分钟是字典(要把关)、下一分钟可能是外部数据源(不把关)。"""
routed = subject(optionRoutes=routes())
eq("命中字典要把关", dicts.constrains_values(routed, {"expenseType": "travel"}), True)
eq("命中外部数据源不把关", dicts.constrains_values(routed, {"expenseType": "meet"}), False)
eq("回落时照旧把关", dicts.constrains_values(routed, {"expenseType": "other"}), True)
# 拿不到单据值的那几处(设计期、导出)问的是「有没有要把关的来源」:有一条就算有
eq("不给值时取并集", dicts.constrains_values(routed), True)
all_searched = subject(optionSource="dataSource", dictCode=None, dataSourceCode="erp",
optionRoutes=[{"source": "process"}])
eq("两条都是搜出来的就不把关", dicts.constrains_values(all_searched), False)
# 提交那一刻:值只在「命中那一条」的清单里才算合法
dict_only = subject(optionRoutes=[{"source": "dict", "when": TRAVEL, "dictCode": "acct_travel"}])
eq("命中差旅时选通用科目要拦",
formruntime.selection_problems([dict_only], {}, {"expenseType": "travel", "expenseItem": "C1"}, FakeCache()),
["「报销科目」的取值已不在可选范围内"])
eq("命中差旅时选差旅科目放行",
formruntime.selection_problems([dict_only], {}, {"expenseType": "travel", "expenseItem": "T1"}, FakeCache()),
[])
eq("那条不成立时回落到通用字典,C1 又合法了",
formruntime.selection_problems([dict_only], {}, {"expenseType": "other", "expenseItem": "C1"}, FakeCache()),
[])
eq("命中外部数据源那一条时不判越界",
formruntime.selection_problems([routed], {}, {"expenseType": "meet", "expenseItem": "ERP-77"}, FakeCache()),
[])
# 「带出的值不在候选里也收下」:勾上就收,且不影响别的格子。
# 拿**字典**那一头钉:后端只判「会随别的字段变的那三类候选」(字典 / 级联 / 带条件的选项),
# 手填且不带条件的那一格本来就不判越界(``_has_option_rule``),页面上由 ``dropStaleSelections``
# 清值 —— 所以这一档最要命的正是字典与外部取数凑在一起的那一格。
fetched = {"key": "level", "label": "职级", "type": "select",
"optionSource": "dict", "dictCode": "acct_common", "fetch": {"source": "erp"}}
eq("没勾那一档:取数带回来的值照样拦",
formruntime.selection_problems([fetched], {}, {"level": "P9"}, FakeCache()),
["「职级」由外部取数带回的取值不在可选范围内(候选来自数据字典,"
"把那一项补进清单,或把这一格的候选来源改成外部数据源 / 流程单据)"])
opened = {**fetched, "allowOutsideValue": True}
eq("勾了那一档:值收下,不拦提交",
formruntime.selection_problems([opened], {}, {"level": "P9"}, FakeCache()), [])
eq("勾了那一档也不放过清单里的值(照常放行)",
formruntime.selection_problems([opened], {}, {"level": "C1"}, FakeCache()), [])
eq("多选里带一个越界值同样收下",
formruntime.selection_problems([{**opened, "multiple": True}], {},
{"level": ["P9", "C1"]}, FakeCache()), [])
# 只读与环节锁死的格子本来就不判越界,这一档不改变那两句
eq("环节只读时不判(老行为)",
formruntime.selection_problems([fetched], {"level": "readonly"}, {"level": "P9"}, FakeCache()), [])
# 换来源到「搜出来的」那一家:本地清单本来就不管,这一档不需要勾
eq("候选来自外部数据源时本来就不判",
formruntime.selection_problems(
[{"key": "level", "label": "职级", "type": "select", "optionSource": "dataSource",
"dataSourceCode": "erp", "fetch": {"source": "crm"}}], {}, {"level": "P9"}, FakeCache()), [])
# ---------------------------------------------------------------------------
# 6. 设计期检查:清单本身 + 每一条的来源,逐条问同一句
# ---------------------------------------------------------------------------
def check_design_time() -> None:
"""配到一半就保存的那几条,别等填单的人发现「这一格是空的」。"""
eq("没配清单不说", dicts.route_problems(subject()), [])
eq("清单不是数组要说", dicts.route_problems(subject(optionRoutes="nope")),
["「报销科目」的候选来源清单要写成一份列表"])
half = subject(optionRoutes=[
{"source": "dict", "when": TRAVEL},
{"source": "dataSource", "when": MEET},
{"source": "manual", "options": []},
{"source": "process", "relationStatuses": []},
{"source": "nope"},
{},
])
text = "\n".join(dicts.route_problems(half))
for want in ("第 1 条候选来源还没选要用的数据字典",
"第 2 条候选来源还没选要用哪一张外部数据源",
"第 3 条候选来源一条选项都没填,选到它就是一只空下拉",
"第 4 条候选来源:至少勾一种状态",
# 来源写歪的说清这类字段挑不了什么,加了还没配完的那一条说轻一点
"第 5 条候选来源的来源这类字段挑不了:nope",
"第 6 条候选来源还没选来源"):
ok(f"设计期要说:{want}", want in text, text)
eq("配得对的清单一个字不多说",
dicts.route_problems(subject(optionRoutes=routes())), [])
# 「先选项目分类,再问那一家要候选」那一格:候选来自清单,字段自己那一份留空是**有意的**
# (分类没选的那一刻本来就没得挑)。保存那道「选项类字段未配置任何选项」的闸不能拦它,
# 否则收拢出来的表单存不下去;什么都没配的照旧要拦,别把老规矩一起放宽了。
driver = {"key": "expenseType", "label": "费用类型", "type": "select",
"options": [{"value": "travel", "label": "差旅"}, {"value": "meet", "label": "招待"}]}
routed = {"fields": [driver, subject(optionSource="manual", options=[], optionRoutes=[
{"source": "dict", "when": TRAVEL, "dictCode": "acct_travel"},
{"source": "dict", "when": MEET, "dictCode": "acct_common"},
])]}
eq("挂了清单、字段自己那份空着 = 保存过得去", design_api.form_problems(routed), [])
bare = {"fields": [subject(optionSource="manual", options=[])]}
ok("什么都没配的照旧要说", any("未配置任何选项" in text for text in design_api.form_problems(bare)),
design_api.form_problems(bare))
# 每一条挑的那一种来源也要配到底:同一套判据,只是换了一张视图
bad_route = subject(optionRoutes=[{"source": "dataSource", "when": TRAVEL, "dataSourceCode": "rate"}])
reasons = formruntime.option_source_problems(bad_route, db=FakeDB(Source(
"rate", "汇率", kind=models.DataSource.KIND_FETCH)))
ok("那一条指的源是取一个值的要说", any(
text.startswith("第 1 条候选来源:") and "汇率" in text for text in reasons), reasons)
# 字段自己那一份与路由里那一条各说各的门牌,两句不会串
both_bad = {**bad_route, "optionSource": "dataSource", "dictCode": None, "dataSourceCode": "rate"}
reasons = formruntime.option_source_problems(both_bad, db=FakeDB(Source(
"rate", "汇率", kind=models.DataSource.KIND_FETCH)))
ok("字段自己那一条不带门牌",
any(text == "引用的数据源「汇率」是取一个值的,候选要的是列表型数据源" for text in reasons), reasons)
eq("两句各说各的门牌,不会串", len(reasons), 2)
# 候选入参引用掉在地上:字段级与路由级都问同一句,只是门牌不同
arg_route = subject(optionRoutes=[{"source": "dataSource", "when": TRAVEL, "dataSourceCode": "erp",
"dataSourceArgs": {"dept": "{form:gone}"}}])
ok("那一条的入参引用悬空要说", any(
text == "第 1 条候选来源:候选来源那张数据源的入参「dept」引用了不存在的字段「gone」"
for text in formruntime.option_source_problems(arg_route, db=None, keys={"dept"})),
formruntime.option_source_problems(arg_route, db=None, keys={"dept"}))
# 拿不到库的那一处不编造:源的健康只在真去查的时候说
eq("不给库时不说源的健康",
[text for text in formruntime.option_source_problems(bad_route, db=None) if "汇率" in text], [])
def check_filled_by_peers() -> None:
"""隔壁那一格的带出指着这一格,也算「这一格的值是系统写进来的」。
生产上真有的形状:一张「项目阶段」下拉,值由隔壁「项目名称」的字典带出写进来。
以前这一句只看这一格自己配没配带出,于是设计期说「这一档暂时不起作用」,
人把勾去掉,提交那一刻又被判「取值已不在可选范围内」——两头都骗了他一次。
"""
stage = {"key": "stage", "label": "项目阶段", "type": "select",
"optionSource": "dict", "dictCode": "project_stage", "allowOutsideValue": True}
driver = {"key": "project", "label": "项目名称", "type": "select",
"optionSource": "dict", "dictCode": "acct_travel",
"autoFill": [{"field": "project", "pick": "stageName", "to": "stage"}]}
eq("隔壁的字典带出指着这一格", formruntime.filled_by_label(stage, [stage, driver]), "字典带出")
eq("不给同表字段时还是老说法", formruntime.filled_by_label(stage), "")
eq("自己那一份排在前面(取一个值写进自己)",
formruntime.filled_by_label({**stage, "fetch": {"source": "erp", "pick": "level"}}, [stage, driver]),
"外部取数")
# 配了带出不等于**这一格**的值是带进来的:去向不在这一格上就不算(生产上「项目名称」
# 配了 autoFill 写别的格子,反被说成「这一格的值由字典带出写入」是这一寸的老毛病)
eq("带出的去向不在这一格上不算这一格被写",
formruntime.filled_by_label({**driver, "autoFill": [{"field": "project", "pick": "x", "to": "elsewhere"}]}),
"")
eq("取数只写别的格子也不算这一格被写",
formruntime.filled_by_label({"key": "vendor", "type": "select", "optionSource": "dict",
"dictCode": "acct_travel", "fetch": {"source": "erp",
"picks": {"bank": "bank"}}}),
"")
eq("取数取一个值写进自己就算",
formruntime.filled_by_label({"key": "vendor", "type": "text",
"fetch": {"source": "erp", "pick": "project"}}), "外部取数")
ok("不说那句空转",
not any("暂时不起作用" in text for text in
formruntime.option_source_problems(stage, db=None, rows=[stage, driver])),
formruntime.option_source_problems(stage, db=None, rows=[stage, driver]))
ok("两处都没带出时仍要说那句",
any("暂时不起作用" in text for text in
formruntime.option_source_problems(stage, db=None, rows=[stage])),
formruntime.option_source_problems(stage, db=None, rows=[stage]))
# 另外三种去向同样算:外部取数的 picks、候选路由那一条自带的 fill、关联单据带出
fetched = {"key": "amount", "label": "金额", "type": "money"}
ok("隔壁外部取数写进来",
formruntime.filled_by_label(fetched, [fetched, {
"key": "order", "type": "text", "fetch": {"source": "erp", "picks": {"amt": "amount"}}}]) == "外部取数")
ok("隔壁那条候选自带的带出写进来",
formruntime.filled_by_label(fetched, [fetched, {
"key": "vendor", "type": "select", "optionSource": "dataSource", "dataSourceCode": "erp",
"optionRoutes": [{"source": "dataSource", "dataSourceCode": "erp",
"fill": {"source": "erp_bank", "picks": {"limit": "amount"}}}]}]) == "外部取数")
# 隔壁那条取数写的是**它自己**那一格(自带的 pick),不算指着这一格:
# 少这一句闸,一张表单里只要有一格配了取数,所有选择类格子都会被说成「值由外部取数写入」
ok("隔壁的取数写它自己那一格,不算指着这一格",
formruntime.filled_by_label(fetched, [fetched, {
"key": "name", "type": "text", "fetch": {"source": "erp", "pick": "project"}}]) == "")
ok("隔壁那条候选的带出写它自己那一格,同样不算",
formruntime.filled_by_label(fetched, [fetched, {
"key": "vendor", "type": "select", "optionSource": "dataSource", "dataSourceCode": "erp",
"fetch": {"source": "erp", "pick": "vendor"}}]) == "")
ok("隔壁关联单据带出写进来",
formruntime.filled_by_label(fetched, [fetched, {
"key": "contract", "type": "select", "optionSource": "process", "relationProcess": "p1",
"linkFill": {"rules": [{"pick": "serial", "to": "amount"}]}}]) == "关联单据带出")
ok("明细列那种表.列的写法不算指着主表这一格",
formruntime.filled_by_label(fetched, [fetched, {
"key": "tbl", "type": "table", "columns": [
{"key": "n", "type": "text", "fetch": {"source": "erp", "picks": {"amt": "tbl.amount"}}}]}]) == "")
# 反向那一头:值是隔壁带进来的、候选又要判越界、还没勾那一档 → 该说交叉那一句
strict = {k: v for k, v in stage.items() if k != "allowOutsideValue"}
reasons = formruntime.option_source_problems(strict, db=None, rows=[strict, driver])
ok("没勾那一档时说的是交叉那一句",
any("带出" in text and "不在可选范围内" in text for text in reasons), reasons)
# 整张表单走一遍校验:这一句在 validate_schema 那条路上也得拿到同表字段
clean = formruntime.validate_schema([stage, driver], db=None)
eq("整表校验里不再误说空转", [text for text in clean if "暂时不起作用" in text], [])
eq("发起那一格不再被说成值是带进来的",
[text for text in clean if "值由字典带出写入" in text], [])
# ---------------------------------------------------------------------------
# 7. 上游问得全:字典清单与条件依赖都要把路由算进来
# ---------------------------------------------------------------------------
def check_dependencies() -> None:
"""漏一处就是「一把只挂在路由里的字典能被删掉」与「界面拿上一家候选继续判越界」。"""
routed = subject(optionRoutes=[
{"source": "dict", "when": TRAVEL, "dictCode": "acct_travel"},
{"source": "dict", "when": MEET, "dictCode": "region", "cascadeFrom": "province"},
{"source": "dataSource", "dataSourceCode": "erp"},
])
eq("预取清单把路由里那两本也算上", dicts.codes_of([routed]),
["acct_common", "acct_travel", "region"])
eq("删字典前的「哪些表单在用」也认路由里的",
sorted(dicts._codes_in({"fields": [routed]})), ["acct_common", "acct_travel", "region"])
eq("触发条件与那条的级联上级都是这一格的上游",
dicts.condition_dependencies(routed), ["province", "expenseType"])
# 字典带出读的是**此刻命中那一条**的字典:选同一个编码在两本字典里带出不同的附加值
fill = {**subject(optionRoutes=[
{"source": "dict", "when": TRAVEL, "dictCode": "acct_travel"},
{"source": "dict", "when": MEET, "dictCode": "acct_common"},
]), "autoFill": [{"field": "expenseItem", "pick": "code", "to": "amount"}]}
amount = {"key": "amount", "label": "金额", "type": "money"}
data = {"expenseType": "travel", "expenseItem": "T2", "amount": ""}
# 带出去向那一格得还在表单上:格子被删了就不写(老规矩,check_binding.py 里钉过那一段)
eq("带出的那一格在场才算数", dicts.apply_auto_fill([fill, amount], data, FakeCache()), ["amount"])
eq("带出按命中的那一本字典取", data["amount"], "TR-01")
other = {"expenseType": "meet", "expenseItem": "C1", "amount": ""}
dicts.apply_auto_fill([fill, amount], other, FakeCache())
eq("换一张单命中另一本,取的是那一本有的东西", other["amount"], "")
# 命中那一条**不是字典**(外部数据源那一家):一个字都不带。
# 少了这一句闸,下面「没有字典就把这一格自己的值搬过去」那一条会把人刚挑中的编码
# 盖到「名称」那一格上(对面前端 items 为空,本来也什么都不写)。
mixed = {**subject(dictCode=None, optionSource="dataSource", dataSourceCode="erp", optionRoutes=[
{"source": "dict", "when": TRAVEL, "dictCode": "acct_travel"},
{"source": "dataSource", "when": MEET, "dataSourceCode": "erp"},
]), "autoFill": [{"field": "expenseItem", "to": "amount"}]}
# 不写 pick =「带名称」:没有那道闸时会走到「没有字典就搬这一格自己的值」那一条,
# 把人刚在外部数据源里挑中的编码原样盖到目标格上
hit_ds = {"expenseType": "meet", "expenseItem": "ERP-77", "amount": ""}
eq("命中外部数据源那条时不带任何东西", dicts.apply_auto_fill([mixed, amount], hit_ds, FakeCache()), [])
eq("命中外部数据源那条时目标格一个字都不写", hit_ds["amount"], "")
hit_dict = {"expenseType": "travel", "expenseItem": "T2", "amount": ""}
eq("命中字典那条时照带(同一份 autoFill)",
dicts.apply_auto_fill([mixed, amount], hit_dict, FakeCache()), ["amount"])
eq("带的是命中那一本的名称", hit_dict["amount"], "住宿费")
# 路由里那几本字典:保存那一刻与那句设计期提醒都靠它,自上而下、去重、只认字典那几条
eq("只挑出字典那几条挂的字典",
dicts.dict_route_codes(subject(optionRoutes=[
{"source": "dict", "dictCode": "acct_travel"},
{"source": "dataSource", "dataSourceCode": "erp"},
{"source": "dict", "dictCode": "acct_travel"},
{"source": "dict", "dictCode": "region"},
])), ["acct_travel", "region"])
eq("没挂路由时没有字典可挑", dicts.dict_route_codes(subject()), [])
# 设计期那句话:两边都没字典才说,字段上或路由里有一本就不说
dead = {"key": "vendor", "label": "供应商", "type": "select",
"optionSource": "dataSource", "dataSourceCode": "erp",
"autoFill": [{"field": "vendor", "pick": "code", "to": "amount"}]}
sentence = "配了字典带出,可这一格没挂数据字典(字段上与候选来源那几条里都没有),这一档不起作用"
ok("两处都没字典时说要一句",
sentence in formruntime.option_source_problems(dead, db=FakeDB(
Source("erp", "ERP 供应商", kind=models.DataSource.KIND_SEARCH))),
formruntime.option_source_problems(dead, db=FakeDB(
Source("erp", "ERP 供应商", kind=models.DataSource.KIND_SEARCH))))
ok("路由里挂着一本字典时不说这句",
sentence not in formruntime.option_source_problems(
{**dead, "optionRoutes": [{"source": "dict", "dictCode": "acct_travel"}]}, db=FakeDB(
Source("erp", "ERP 供应商", kind=models.DataSource.KIND_SEARCH))))
ok("字段自己有字典时不说这句",
sentence not in formruntime.option_source_problems(
{**dead, "dictCode": "acct_common"}, db=FakeDB(
Source("erp", "ERP 供应商", kind=models.DataSource.KIND_SEARCH))))
# ---------------------------------------------------------------------------
# 8. 回看与必填不再死锁(显示条件不成立 ≠ 这一格没填)
# ---------------------------------------------------------------------------
def check_required_when_hidden() -> None:
"""生产上那句「配了显示条件之后提交不过」的病根。
``auto`` / ``formula`` 这两类没有录入框、权限永远算只读,字段自己又勾了必填,
老判据就连**因显示条件不成立**被收走的格子一起催「还没填写」——屏幕上根本没有那一格,
提交永远过不去。勾了「默认隐藏」又没配条件的(单据编号、金额大写)照旧仍然要有值。
"""
gated = {"key": "contractNo", "label": "合同编号", "type": "auto", "required": True,
"visibleWhen": {"match": "all", "rules": [{"field": "hasContract", "op": "eq", "value": "1"}]}}
eq("条件不成立时算因隐藏", formruntime.hidden_by_condition(gated, {"hasContract": "0"}), True)
eq("条件成立时不算", formruntime.hidden_by_condition(gated, {"hasContract": "1"}), False)
eq("没配条件不算这一句", formruntime.hidden_by_condition({"key": "a", "type": "auto"}, {}), False)
eq("因显示条件藏起来的必填格不卡提交",
formruntime.missing_required([gated], {}, {"hasContract": "0"}), [])
eq("条件成立却没带值,照旧要那一笔",
formruntime.missing_required([gated], {}, {"hasContract": "1"}), ["合同编号"])
quiet = {"key": "code", "label": "单据编号", "type": "auto", "required": True, "hidden": True}
eq("勾了默认隐藏又没配条件:藏起来不等于可以不生成",
formruntime.missing_required([quiet], {}, {}), ["单据编号"])
eq("环节明写只读时那一格不再要", formruntime.missing_required([quiet], {"code": "readonly"}, {}), [])
plain = {"key": "reason", "label": "申请事由", "type": "textarea", "required": True,
"visibleWhen": gated["visibleWhen"]}
eq("条件不成立的普通必填格也不卡人", formruntime.missing_required([plain], {}, {"hasContract": "0"}), [])
eq("条件成立时普通必填格照旧卡人", formruntime.missing_required([plain], {}, {"hasContract": "1"}),
["申请事由"])
# ---------------------------------------------------------------------------
# 9. 外部取数那一头:条目上的触发条件
# ---------------------------------------------------------------------------
def check_fetch_entries() -> None:
"""「报销类型 = 差旅才问差标接口」:清单全量给设计期看,成立的那几条给运行时跑。"""
cfg = {"sources": [{"source": "travel_api", "when": TRAVEL},
{"source": "meet_api", "when": MEET},
{"source": "common_api"}]}
eq("清单是全量", [item["source"] for item in binding.entries(cfg)],
["travel_api", "meet_api", "common_api"])
eq("运行时只跑成立的那几条",
[item["source"] for item in fetch.active_field_sources(cfg, {"expenseType": "travel"})],
["travel_api", "common_api"])
eq("一条都不成立=这回不取数",
[item["source"] for item in fetch.active_field_sources(
{"sources": [{"source": "a", "when": TRAVEL}]}, {})], [])
# 单源老写法也能挂条件;条件写成裸数组按「且」收;配到一半的当没配
eq("单源那份也认这一句",
[item["source"] for item in binding.active_entries({"source": "a", "when": MEET},
{"expenseType": "meet"})], ["a"])
eq("裸数组按且收", binding.entry_when({"when": [{"field": "a", "op": "notEmpty"}]}),
{"match": "all", "rules": [{"field": "a", "op": "notEmpty"}]})
eq("空条件当没配(恒成立)", binding.entry_when({"when": {"rules": []}}), None)
eq("不成形状的条件当没配", binding.entry_when({"when": "nope"}), None)
eq("没配条件的老清单一个字不变",
binding.active_entries({"source": "erp", "args": {"dept": "{form:dept}"}}, {}),
binding.entries({"source": "erp", "args": {"dept": "{form:dept}"}}))
# 设计期检查看的是全量:源在不在、条件引用掉没掉在地上,跟此刻的取值无关
reasons = binding.entry_problems(None, {"source": "travel_api", "when": {"match": "all", "rules": [
{"field": "gone", "op": "eq", "value": "1"}]}}, {"dept"}, "第 1 个字段「金额」的外部取数")
ok("条件引用了不存在的字段要说", any("gone" in text for text in reasons), reasons)
# ---------------------------------------------------------------------------
# 10. 翻名字跟着命中的那一条
# ---------------------------------------------------------------------------
def check_labels() -> None:
"""只读、打印、标题念出来的名字,得是**那一单当时命中的那一条**给的名字。"""
routed = subject(optionRoutes=routes())
eq("命中差旅时念差旅那本的名字",
dicts.option_labels(routed, "T1", FakeCache(), "、", {"expenseType": "travel"}), "火车票")
eq("回落到通用那本时念通用",
dicts.option_labels(routed, "C1", FakeCache(), "、", {"expenseType": "other"}), "通用科目一")
# 认不出的值原样念,别编一个名字出来
eq("认不出就原样念", dicts.option_labels(routed, "ZZ", FakeCache(), "、", {"expenseType": "travel"}), "ZZ")
# 不带 data 的老调用方一个字不用改
eq("不带值时按字段自己那一份翻", dicts.option_labels(routed, "C1", FakeCache()), "通用科目一")
# 导出与标题那两条路也必须吃这一单的值:界面按 A 家念、导出按 B 家念,
# 是这一整套最容易悄悄漂起来的两处(打印出来的单子没人会去对字典)。
eq("导出的那一格跟着命中的那一条",
exportfmt.cell_text(routed, "T1", FakeCache(), None, {"expenseType": "travel"}), "火车票")
eq("导出没命中就回落通用那本",
exportfmt.cell_text(routed, "C1", FakeCache(), None, {"expenseType": "other"}), "通用科目一")
eq("标题里那一格也一样",
titles._field_text(None, routed, "T1", FakeCache(), data={"expenseType": "travel"}), "火车票")
# 源码钉住:这几处调用一旦把 data= 摘掉,上面三条会悄悄退回字段自己那一份而没人报错
root = pathlib.Path(__file__).resolve().parents[2]
for rel, phrases in (
("backend/app/service/exportfmt.py",
["field = dicts_service.option_view(field, data)", "cache, jobs, data=row"]),
("backend/app/service/detail_export.py", ["cache, jobs, data=data"]),
("backend/app/api/export.py", ["cache, jobs, data=data"]),
("backend/app/service/titles.py",
["field = dicts.option_view(field, data)", "cache, data=rows[0])", "cache, data=data)"]),
):
source = (root / rel).read_text(encoding="utf-8")
for phrase in phrases:
ok(f"{rel} 翻名字带上了这一单的值:{phrase}", phrase in source, phrase)
# ---------------------------------------------------------------------------
# 11. 前后端对齐:常量一份、措辞一句
# ---------------------------------------------------------------------------
PARALLEL: list[tuple[str, list[str]]] = [
("frontend/src/utils/optionSource.ts", [
# 清单本身那几句,两边各写一遍,漂了就会一边放行一边报错
"的候选来源清单要写成一份列表",
" 条,多出来的不会被用上",
"还没选要用的数据字典",
"还没选要用哪一张外部数据源",
"一条选项都没填,选到它就是一只空下拉",
"的来源这类字段挑不了",
"配置格式不对",
# 「带出的值也收下」那两句
"这一格没配任何带出(外部取数 / 关联单据带出 / 字典带出),",
"或勾上「带出的值不在候选里也收下」",
# 字典带出那一条:命中那一条不是字典 / 两处都没字典时的说法,两边一字不差
"配了字典带出,可这一格没挂数据字典(字段上与候选来源那几条里都没有),这一档不起作用",
# 「这一格的值是不是系统写进来的」那一份判据:两边都按**落点**判,且都认隔壁那一格
"function fetchWrites(",
"function rulesHitSelf(",
"export function filledByOther(",
"peers?: FormFieldDef[]",
]),
("frontend/src/utils/formLinkage.ts", [
# 路由的上游并进了「清失效值」那一句:漏了它,界面会拿上一家的候选清单继续判越界
"optionFieldView(",
]),
]
def check_parity() -> None:
"""两份算法必须算出同一个结果:常量、每种来源自己那几格、以及那几句措辞。"""
root = pathlib.Path(__file__).resolve().parents[2]
option_source = root / "frontend/src/utils/optionSource.ts"
if not option_source.exists():
print(f"[跳过] 找不到前端那份 {option_source}(只部署后端时正常)")
return
text = option_source.read_text(encoding="utf-8")
eq("上限两边同一个数", f"export const MAX_OPTION_ROUTES = {dicts.MAX_OPTION_ROUTES}" in text, True)
eq("清单键名两边同一个", f"export const OPTION_ROUTES_KEY = '{dicts.OPTION_ROUTES_KEY}'" in text, True)
# 每种来源自己带的那几格对不上,就会出现「一边把这格当残骸清掉、一边还留着读它」
block = text.split("export const ROUTE_OWNED_KEYS", 1)[-1].split("\n}", 1)[0]
for kind, keys in dicts.ROUTE_OWNED_KEYS.items():
hit = re.search(rf"{kind}: \[([^\]]*)\]", block)
ok(f"前端 {kind} 那一行在", hit is not None, block)
if not hit:
continue
quoted = set(re.findall(r"'([^']+)'", hit.group(1)))
# 前端把 dataSourceArgs 写成常量 OPTION_ARGS_KEY(值就是那一个字面量),认回来再比
if "OPTION_ARGS_KEY" in hit.group(1):
quoted.add("dataSourceArgs")
eq(f"{kind} 那几格两边同一份", quoted, set(keys))
for path, phrases in PARALLEL:
target = root / path
if not target.exists():
FAILS.append(f"找不到前端那份 {path}")
continue
frontend = target.read_text(encoding="utf-8")
for phrase in phrases:
ok(f"「{phrase}」前后端都在", phrase in frontend, f"前端缺:{path}")
# 字典带出读的是**此刻命中那一条**的字典:两边都得先摊视图再读 dictCode,
# 漏一处就是「界面带 A 本的附加值、提交带 B 本的」
linkage_source = (root / "frontend/src/utils/formLinkage.ts").read_text(encoding="utf-8")
body = linkage_source.split("export function applyAutoFill", 1)[-1]
ok("前端带出按命中那一条取字典", "optionFieldView(" in body.split("\nexport ", 1)[0], body[:200])
be_body = inspect.getsource(dicts.apply_auto_fill)
ok("后端带出按命中那一条取字典", "option_view(field, data)" in be_body, be_body[:200])
eq("清单键名两边同一个", f"export const AUTO_FILL_KEY = '{dicts.AUTO_FILL_KEY}'", True) if False else None
ok("前端那份 AUTO_FILL_KEY 与后端同一个",
f"export const AUTO_FILL_KEY = '{dicts.AUTO_FILL_KEY}'" in text, text[:200])
ok("前端也有「路由里那几本字典」那一句",
"export function dictRouteCodesOf" in text, text[:200])
# 「落点在这一格上」那份判据两边同形:后端少了 _fetch_writes / _rule_hits_self 就会退回
# 「这一格配过带出=这一格被写」,于是人挑的那一格被说成系统写的,或者反过来
for symbol in ("def _fetch_writes(", "def _rule_hits_self(", "def filled_by_other("):
ok(f"后端那份判据在:{symbol}", symbol in inspect.getsource(formruntime), symbol)
# 外部取数那一条的触发条件:两边都只认这一个键名
fetch_source = (root / "frontend/src/utils/binding.ts").read_text(encoding="utf-8")
eq("条目条件的键名两边同一个", binding.ENTRY_WHEN_KEY, "when")
ok("前端那条也走 entryWhen 那一份", "export function entryWhen" in fetch_source, fetch_source[:200])
def main(argv: list[str]) -> int:
stages = [
("命中哪一条与回落", check_matching),
("视图只动来源那一维", check_view),
("脏条目当没配", check_dirty),
("保存那一刻的清洗", check_cleaning),
("把关与「带出的值也收下」", check_guard),
("设计期逐条体检", check_design_time),
("上游与预取清单", check_dependencies),
("隔壁的带出也算带出", check_filled_by_peers),
("显示条件不成立不再卡必填", check_required_when_hidden),
("外部取数的条目条件", check_fetch_entries),
("翻名字跟着命中的那一条", check_labels),
("前后端措辞与常量对齐", check_parity),
]
for title, stage in stages:
before = len(FAILS)
stage()
marks = "通过" if len(FAILS) == before else f"{len(FAILS) - before} 条不对"
print(f"[{marks}] {title}")
for line in FAILS:
print(f"[FAIL] {line}")
if FAILS:
print(f"共 {len(FAILS)} 条不对")
return 1
print("通过:候选来源的条件路由与「带出的值也收下」口径一致")
return 0
if __name__ == "__main__":
raise SystemExit(main(sys.argv[1:]))

View File

@ -403,7 +403,12 @@ def call_sites(db: Session) -> None:
db.flush()
check("表单还原:字段数复原", len(autofill.form_fields(db, form.id)) == baseline)
channel = db.execute(select(models.NotifyChannel).order_by(models.NotifyChannel.code)).scalars().first()
# 只挑**启用的**那条:channels_for 本来就只回答启用的渠道,开发库里只剩一条
# 停用的 hub 渠道时,拿它当现成素材问出来的必然是空,于是自己临时补一条。
channel = db.execute(
select(models.NotifyChannel).where(models.NotifyChannel.enabled.is_(True))
.order_by(models.NotifyChannel.code)
).scalars().first()
probe_channel = channel is None
if probe_channel:
channel = models.NotifyChannel(

View File

@ -0,0 +1,329 @@
#!/usr/bin/env python3
"""明细列的外部取数(逐行取数)的验收:不打真上游,内存库。
PYTHONPATH=. python3 scripts/check_row_fetch.py
钉的是 2026-11 定下来的那几条口径(方案见 docs/form-data-integration-design.md §9.2、
docs/sql-autofill-design.md §5 与 §6 第 4 条、docs/form-field-catalog.md §2.12):
1. **列上那份 ``fetch`` 与主表字段那份是同一个执行器**:多源、合并、失败策略、冻结、
留痕一套都不另发明,只是**逐行各跑一次**,值写进这一行。
2. **入参读「整张单 + 这一行」**:``{form.x}`` 同名的列以本行为准(与本行公式同一分寸),
主表字段读得到(配的人不用记第二套写法)。
3. **带出去向只落在这张明细表的列上**:往主表写等于让最后一行去盖表头那一格。
4. **权威在服务端**:前端把这一格改成什么都被覆盖回去;``onError=block`` 报错点名是哪一行,
整张明细表被本环节藏起来时降级成不挡(与主表那一格同一口径)。
5. **留痕摊得开行号**:两张明细表可能有同名列、同一张表每一行都要留,所以按
``表名.列名`` 记一条,底下挂每一行那次外呼。
共享缓存(Redis)在这一趟里摘掉,理由同 ``check_fetch_freeze.py``。
"""
from __future__ import annotations
import pathlib
import sys
from urllib.parse import parse_qs, urlparse
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent))
from sqlalchemy import create_engine, event # noqa: E402
from sqlalchemy.orm import Session # noqa: E402
from sqlalchemy.pool import StaticPool # noqa: E402
from app import cache as shared_cache, models # noqa: E402
from app.engine import engine as engine_module # noqa: E402
from app.service import fetch, formruntime # noqa: E402
PASSED = 0
FAILS: list[str] = []
#: 假上游收到的入参(谁被问了、问的是哪个收款人)
SENT: list[dict] = []
#: 每个收款人对应的开户行与账号:一行一个答案,才看得出是不是逐行各取一次
BANKS = {
"zhangsan": {"bank": "中国银行张三分行", "account": "ZH123456"},
"lisi": {"bank": "中国银行李四分行", "account": "LI654321"},
}
def eq(name: str, got, want) -> None:
global PASSED
if got == want:
PASSED += 1
print(f"[通过] {name}")
else:
FAILS.append(name)
print(f"[FAIL] {name} -> 期望 {want!r},实得 {got!r}")
def new_session() -> Session:
for table in models.Base.metadata.tables.values():
for column in table.columns:
if column.server_default is not None:
column.server_default = None
engine = create_engine("sqlite://", poolclass=StaticPool, connect_args={"check_same_thread": False})
@event.listens_for(engine, "before_cursor_execute")
def _noop(conn, cursor, statement, parameters, context, executemany): # noqa: ANN001
pass
models.Base.metadata.create_all(engine)
return Session(engine)
def source(db: Session, *, code: str = "erp_bank", enabled: bool = True) -> None:
"""一条按收款人查银行账户的取值型源:本格要帐号,开户行走「多带出一列」。"""
db.add(models.DataSource(
id=code, code=code, name=f"明细取数校验·{code}", system="ERP",
kind=models.DataSource.KIND_FETCH, provider=models.DataSource.PROVIDER_HTTP,
enabled=enabled, method="GET",
url="https://erp.invalid/api/bank?account={arg.account}",
headers={}, body_template={}, pick="data.account",
map_extra={"bank": "data.bank"}, auth_type=models.DataSource.AUTH_NONE,
cache_seconds=0, timeout_seconds=5, retries=0,
))
db.commit()
def amount_source(db: Session) -> None:
"""另一条源:回一个金额,用来验金额列拿到的是数不是字符串。"""
db.add(models.DataSource(
id="erp_rate", code="erp_rate", name="明细取数校验·汇率", system="ERP",
kind=models.DataSource.KIND_FETCH, provider=models.DataSource.PROVIDER_HTTP,
enabled=True, method="GET", url="https://erp.invalid/api/rate",
headers={}, body_template={}, pick="data.rate",
map_extra={}, auth_type=models.DataSource.AUTH_NONE,
cache_seconds=0, timeout_seconds=5, retries=0,
))
db.commit()
class Act:
"""假环节:引擎递给 ``apply_form`` 的就是这一份,只有 ``type`` 参与判据。"""
def __init__(self, type_: str, id_: str = "") -> None:
self.type = type_
self.id = id_ or f"act-{type_}"
def fake_http(method, url, body, headers, timeout): # noqa: ANN001
if urlparse(url).path.endswith("/api/rate"):
return (200, '{"code":0,"data":{"rate":"1234.50"}}')
account = (parse_qs(urlparse(url).query).get("account") or [""])[0]
SENT.append({"account": account})
row = BANKS.get(account)
if row is None:
return (404, '{"code":404,"message":"没有这个收款人"}')
return (200, '{"code":0,"data":{"bank":"%s","account":"%s"}}' % (row["bank"], row["account"]))
def fields(*, on_error: str = "keep", freeze: bool = False, pick_main: bool = False,
money: bool = False) -> list[dict]:
"""一张收款明细表:银行帐号与开户行按本行的收款人去 ERP 取。
``pick_main=True`` 时带出去向故意写成主表字段(校验那条闸要它)。
"""
cfg: dict = {
"source": "erp_bank",
"args": {"account": "{form.payee}"},
"picks": {"bank": "bankName"} if not pick_main else {"bank": "audit_note"},
"onError": on_error,
}
if freeze:
cfg["freezeAfterStart"] = True
return [
{"key": "payee", "label": "报销人", "type": "text"},
{"key": "audit_note", "label": "审核备注", "type": "text"},
{"key": "items", "label": "收款明细", "type": "table", "columns": [
{"key": "payee", "label": "收款人", "type": "text"},
{"key": "bankName", "label": "开户银行", "type": "text"},
{"key": "bankAccount", "label": "银行帐号",
"type": "money" if money else "text", "fetch": cfg},
]},
]
def data(*, rows: list[dict] | None = None, **main) -> dict:
body = {"payee": "zhangsan", "audit_note": "", "items": []}
body.update(main)
body["items"] = rows if rows is not None else [
{"payee": "zhangsan", "bankName": "", "bankAccount": ""},
{"payee": "lisi", "bankName": "", "bankAccount": ""},
]
return body
def column(key: str, label: str, cfg: dict | None) -> dict:
item = {"key": key, "label": label, "type": "text"}
if cfg is not None:
item["fetch"] = cfg
return item
def table_field(columns: list[dict]) -> dict:
return {"key": "items", "label": "收款明细", "type": "table", "columns": columns}
def main() -> int:
db = new_session()
fetch._cache.clear()
real_http = fetch.http_request
real_get_json, real_set_json = shared_cache.get_json, shared_cache.set_json
shared_cache.get_json = lambda *a, **k: None # type: ignore[assignment]
shared_cache.set_json = lambda *a, **k: None # type: ignore[assignment]
fetch.http_request = fake_http # type: ignore[assignment]
source(db)
begin, manual = Act("begin", "start"), Act("manual", "approve")
try:
# ---------------- 1. 谁来跑:主表那份清单不认明细,列单独挑 ----------------
eq("主表清单里没有明细表的列", fetch.fetch_fields(fields()), ["payee", "audit_note", "items"][0:0] or
[str(item.get("key")) for item, _cfg in fetch.fetch_fields(fields())])
eq("列上那份 fetch 挑得出来",
[(t.get("key"), c.get("key")) for t, c, _cfg in fetch.row_fetch_fields(fields())],
[("items", "bankAccount")])
# ---------------- 2. 逐行各取一次,各写各的那一行 ----------------
SENT.clear()
body = data()
fetch.apply_form(db, fields(), body, activity=begin)
eq("两行各打一次上游,问的是本行的收款人", [item["account"] for item in SENT], ["zhangsan", "lisi"])
eq("第一行取回自己的帐号", body["items"][0]["bankAccount"], "ZH123456")
eq("第二行取回自己的帐号", body["items"][1]["bankAccount"], "LI654321")
eq("带出去向写进同一行的另一列", body["items"][0]["bankName"], "中国银行张三分行")
eq("第二行的带出也落在第二行", body["items"][1]["bankName"], "中国银行李四分行")
eq("主表那一格一个字节都没被盖", body["payee"], "zhangsan")
eq("留痕按「表名.列名」记一条", sorted(body[fetch.TRACE_KEY]), ["items.bankAccount"])
eq("留痕里每一行都留了行号与入参",
[(item["row"], item["args"]) for item in body[fetch.TRACE_KEY]["items.bankAccount"]["rows"]],
[(1, {"account": "zhangsan"}), (2, {"account": "lisi"})])
# ---------------- 3. 入参读的是「整张单 + 这一行」,同名列归本行 ----------------
SENT.clear()
# 主表的报销人填的是 lisi,本行的收款人是 zhangsan:同名以本行为准
body = data(rows=[{"payee": "zhangsan", "bankName": "", "bankAccount": ""}])
fetch.apply_form(db, fields(), body, activity=begin)
eq("与列同名的主表字段让位给本行", [item["account"] for item in SENT], ["zhangsan"])
eq("值取的是本行那个人", body["items"][0]["bankAccount"], "ZH123456")
SENT.clear()
# 本行没填收款人(这一列不存在):读得到主表那一格
body = {"payee": "lisi", "audit_note": "", "items": [{"bankName": "", "bankAccount": ""}]}
fetch.apply_form(db, fields(), body, activity=begin)
eq("本行没有那一列时读主表字段", [item["account"] for item in SENT], ["lisi"])
eq("主表字段驱动的行照样取得到值", body["items"][0]["bankAccount"], "LI654321")
# ---------------- 4. 空表、没有这张表、行不是物件:一次都不许打上游 ----------------
SENT.clear()
body = {"payee": "zhangsan", "items": []}
fetch.apply_form(db, fields(), body, activity=begin)
eq("整张明细表没有一行时不外呼", SENT, [])
body = {"payee": "zhangsan"}
fetch.apply_form(db, fields(), body, activity=begin)
eq("这张表一个键都没有时也不外呼", SENT, [])
body = {"payee": "zhangsan", "items": ["不是物件的一行"]}
fetch.apply_form(db, fields(), body, activity=begin)
eq("行不是物件时跳过这一行(不崩)", SENT, [])
# ---------------- 5. 前端塞的假值盖不回去,取回的值说了算 ----------------
SENT.clear()
body = data(rows=[{"payee": "zhangsan", "bankName": "随便写的", "bankAccount": "622200000000"}])
fetch.apply_form(db, fields(), body, activity=begin)
eq("页面塞进来的帐号被取回的那一份覆盖", body["items"][0]["bankAccount"], "ZH123456")
eq("带出去那一列同样以服务端为准", body["items"][0]["bankName"], "中国银行张三分行")
# ---------------- 6. 取不到:挡人要点名是哪一行,本环节藏着就不挡 ----------------
SENT.clear()
body = data(rows=[{"payee": "zhangsan", "bankName": "a", "bankAccount": "b"},
{"payee": "wangwu", "bankName": "c", "bankAccount": "d"}])
blocked = ""
try:
fetch.apply_form(db, fields(on_error="block"), body, activity=begin)
except engine_module.EngineError as exc:
blocked = str(exc)
eq("第一行取到了,值留着", body["items"][0]["bankAccount"], "ZH123456")
eq("挡人的那句话点名是哪一行", ("第 2 行" in blocked, "银行帐号" in blocked, "外部数据取不到" in blocked),
(True, True, True))
SENT.clear()
# 整张明细表在本环节被藏起来:连「取不到」这句都不该说(与主表那一格同一口径)
hidden_perms = {"items": formruntime.PERM_HIDDEN}
body = data(rows=[{"payee": "wangwu", "bankName": "c", "bankAccount": "d"}])
fetch.apply_form(db, fields(on_error="block"), body, activity=manual, perms=hidden_perms)
eq("这一环把整张明细表藏起来了:取不到也不挡提交", body["items"][0]["bankAccount"], "d")
# 只挡「这一行取不到」,其余行照常
SENT.clear()
body = data(rows=[{"payee": "zhangsan", "bankName": "", "bankAccount": ""},
{"payee": "wangwu", "bankName": "", "bankAccount": "留着"}])
fetch.apply_form(db, fields(on_error="zero"), body, activity=begin)
eq("onError=zero 把取不到的那一行清零", body["items"][1]["bankAccount"], "")
eq("取到的那一行不受影响", body["items"][0]["bankAccount"], "ZH123456")
# ---------------- 7. 发起之后冻结:办理环节一次都不许重取 ----------------
SENT.clear()
body = data()
fetch.apply_form(db, fields(freeze=True), body, activity=begin)
first_accounts = [item["account"] for item in SENT]
SENT.clear()
body["items"][0]["bankAccount"] = "经办人自己改的"
fetch.apply_form(db, fields(freeze=True), body, activity=manual)
eq("发起之后进了办理环节:一次都不外呼", SENT, [])
eq("这一格留在经办人改过的那一份", body["items"][0]["bankAccount"], "经办人自己改的")
eq("发起那一趟确实逐行各取了一次", first_accounts, ["zhangsan", "lisi"])
# ---------------- 8. 金额列塑形(取回来的是字符串,落进金额格要成数) ----------------
SENT.clear()
amount_source(db)
money_fields = fields(money=True)
for item in money_fields[2]["columns"]:
if item.get("key") == "bankAccount":
item["fetch"] = {"source": "erp_rate", "args": {}, "picks": {}, "onError": "keep"}
body = data(rows=[{"payee": "zhangsan", "bankName": "", "bankAccount": ""}])
fetch.apply_form(db, money_fields, body, activity=begin)
eq("金额列拿到的是数,不是 \"1234.50\" 这种字符串", body["items"][0]["bankAccount"], 1234.5)
# ---------------- 9. 设计期校验:带出只认这张表的列 ----------------
problems = fetch.problems(fields(pick_main=True), None)
eq("带出去向写成主表字段时,保存当场就挡",
[line for line in problems if "不存在的列" in line] != [], True)
eq("那句报错说的是哪张表的哪一列",
any("明细表「收款明细」的列「银行帐号」的外部取数" in line for line in problems), True)
bad = fetch.problems([table_field([
column("bank", "银行帐号", {"source": "erp_bank",
"args": {"account": "{form.nobody}"}, "picks": {}}),
])], None)
eq("入参引用了不存在的字段:说得出是哪一列",
any("入参「account」引用了不存在的字段「nobody」" in line for line in bad), True)
# 同一份入参写法引用主表字段与同名列都算合法(行作用域读得到这两处)
ok_fields = [
{"key": "payee", "label": "报销人", "type": "text"},
table_field([
column("payee", "收款人", None),
column("bankName", "开户银行", None),
column("bank", "银行帐号", {"source": "erp_bank", "args": {"account": "{form.payee}"},
"picks": {"bank": "bankName"}}),
]),
]
eq("引用主表字段 / 本行的列都不误报", fetch.problems(ok_fields, None), [])
eq("带进自己那一格也说清楚",
any("不能把值带进自己" in line for line in fetch.problems([table_field([
column("bank", "银行帐号", {"source": "erp_bank", "args": {}, "picks": {"account": "bank"}}),
])], None)), True)
eq("主表字段那份取数不受影响(没配 fetch 的表单零报错)",
fetch.problems([{"key": "a", "label": "甲", "type": "text"}], None), [])
finally:
fetch.http_request = real_http # type: ignore[assignment]
shared_cache.get_json, shared_cache.set_json = real_get_json, real_set_json
fetch._cache.clear()
db.close()
print()
if FAILS:
print(f"失败 {len(FAILS)} 条:")
for name in FAILS:
print(f" - {name}")
return 1
print(f"全部通过({PASSED} 条)")
return 0
if __name__ == "__main__":
sys.exit(main())

View File

@ -38,7 +38,7 @@ from __future__ import annotations
import json
import sys
from sqlalchemy import event, func, or_, select
from sqlalchemy import event, or_, select
from app import models, readcache
from app.db import SessionLocal, engine
@ -233,42 +233,70 @@ def write_invalidates(db) -> None:
def audit_matches(db) -> None:
"""去重体检:预热与否交出的报文一字不差,条数严格更少。"""
# 挑手工环节最多的那张画布:样本越小省得越少,容易把这一层测成"看着没效果"
row = db.execute(
select(models.Activity.process, func.count())
# 一次读回所有手工环节,两张画布各挑各的:**报文**挑环节最多的那张(样本越大越能
# 看出漂移),**条数**挑 org 选择器最多的那张。预热合起来批量问的是角色 / 部门 /
# 分组 / 人员那几档,一张全是「发起人」的画布一次也省不到(发起人就在单据上,
# 不去库里问),拿它比条数只会把这一档测成"看着没效果"。
rows = db.execute(
select(models.Activity.process, models.Activity.config)
.where(models.Activity.type == "manual")
.group_by(models.Activity.process)
.order_by(func.count().desc(), models.Activity.process)
.limit(1)
).first()
process = db.get(models.Process, row[0]) if row else None
if process is None:
process = db.execute(select(models.Process).order_by(models.Process.id)).scalars().first()
).all()
manuals: dict[str, int] = {}
org_refs: dict[str, int] = {}
org_nodes: dict[str, int] = {}
for process_id, config in rows:
manuals[process_id] = manuals.get(process_id, 0) + 1
picked = 0
for item in (config or {}).get("taskValues") or []:
if isinstance(item, dict) and str(item.get("type") or "") != "creator":
picked += len(item.get("data") or [])
org_refs[process_id] = org_refs.get(process_id, 0) + picked
# 省不省得下来看的是"有几环各自要去问":一环上的几个值本来就是一趟
org_nodes[process_id] = org_nodes.get(process_id, 0) + (1 if picked else 0)
account = db.execute(
select(models.User.account)
.where(models.User.status == models.UserStatus.ACTIVE, models.User.account != "")
.order_by(models.User.id).limit(1)
).scalars().first()
biggest = max(manuals, key=lambda key: (manuals[key], key)) if manuals else ""
process = db.get(models.Process, biggest) if biggest else None
if process is None or not account:
check("库里有流程与在职账号可跑体检", False, "库里没有流程或在职账号")
return
def payload() -> str:
return json.dumps(dedupaudit.audit(db, process_id=process.id, as_identity=account),
def payload(target: models.Process) -> str:
return json.dumps(dedupaudit.audit(db, process_id=target.id, as_identity=account),
ensure_ascii=False, sort_keys=True)
real_warm = dedupaudit._warm_org
cold()
warmed, warm_trips = counted(payload)
cold()
dedupaudit._warm_org = lambda *args, **kwargs: None # 退回逐环节各问各的
bare, bare_trips = counted(payload)
dedupaudit._warm_org = real_warm
def measure(target: models.Process) -> tuple[str, int, int]:
"""同一张画布各跑两遍:预热与不预热的报文,以及各自问了几条库。"""
real_warm = dedupaudit._warm_org
cold()
warmed, warm_trips = counted(lambda: payload(target))
cold()
dedupaudit._warm_org = lambda *args, **kwargs: None # 退回逐环节各问各的
bare, bare_trips = counted(lambda: payload(target))
dedupaudit._warm_org = real_warm
return warmed, warm_trips, bare_trips, bare # type: ignore[return-value]
warmed, warm_trips, bare_trips, bare = measure(process)
check(f"体检报文与预热与否无关({len(warmed)} 字节)", warmed == bare)
print(f" 借 {process.name} 量报文({manuals[biggest]} 个手工环节),样例身份 {account}")
heaviest = max(org_nodes, key=lambda key: (org_nodes[key], org_refs[key], key)) if org_nodes else ""
sample = db.get(models.Process, heaviest) if heaviest else None
if sample is None or org_nodes.get(heaviest, 0) < 2:
# 只有一环要去问库里的时候,预热与逐环节问的是同一趟,省不出东西:
# 这一档量的是"多环各自问一遍 vs 一次问完",样本不够就别报红。
print(f"[跳过] 整张设计一次预热更省:库里没有一张画布带两环以上要问 org 的手工环节"
f"(最多 {org_nodes.get(heaviest, 0)} 环),预热与逐环节问同样几趟")
return
if sample.id != process.id:
print(f" 借 {sample.name} 量条数({org_nodes[heaviest]} 环 / {org_refs[heaviest]} 个 org 选择器)")
_, warm_trips, bare_trips, _ = measure(sample)
check(f"整张设计一次预热更省({bare_trips} → {warm_trips} 条)", warm_trips < bare_trips,
f"{bare_trips} → {warm_trips}")
print(f" 借 {process.name} 当样本,样例身份 {account}")
def sample_names(db) -> list[str]:

View File

@ -0,0 +1,234 @@
#!/usr/bin/env python3
"""联动条件读**自己那一格**(自引用):判得出结果、不当配错、也不把人刚写的值抹掉。
PYTHONPATH=. python3 scripts/check_self_visible.py
用户那句原话:"表单中字段的显示判断条件,需要可以设置判断本身字段的值情况来确定是否可以
展示"。以前这一档压根配不出来:设计器把本字段从条件清单里筛掉(``LinkagePanel`` 那句
``item.key !== props.field.key``),后端保存时还要报一句「联动条件引用了自己」,于是
「外部带回来的合同编号有值才露这一格」只能造一个中间变量绕一圈。
放开之后要钉住三件事,缺一件就成了新坑:
1. **只放宽"判谁",不放宽"怎么判"**:自引用走的就是 ``compare`` 那一条路,别的条件一个
字节都不受影响;级联上级选自己、条件左右两头是同一格、指向不存在的字段,三句照旧要说。
2. **自指不进级联清值那圈**:``depends_on`` 仍把自指摘掉("自己变了要清自己的失效值"会把
刚写进来那一份当越界抹掉),``condition_dependencies`` 留着(设计期与界面重算都读它)。
3. **"只被自己藏起来"的那一笔值要收下**:``visibleWhen`` 判自己有没有值、``readonlyWhen``
判自己有没有值,都会在人刚敲完的那一刻把这一格收走或锁上,引擎那一段按"这一环改不动"
退回原值,人看着自己写的字凭空消失。摘掉自引用那几条以后本来就填得动,就收下这一笔;
环节明写隐藏、被别的格子挡住、类型压根没有录入框,三档都不算,一寸没放宽。
**空格算没填**这一条也在这里钉:``dicts._is_empty`` 一直把一串空格当没填,前端
``isEmptyValue`` 以前只认空串,于是"有值才显示"这一档两边能算出两个结果(界面按 notEmpty
露着一行空白,服务端按 empty 判它没填)。这次一并收齐,两边同一把尺子。
前端镜像钉在 ``utils/formLinkage.self.spec.ts``、``components/oa/FormRenderer.self.spec.ts``
与 ``components/oa/design/LinkagePanel.self.spec.ts``。全程不碰库。
"""
from __future__ import annotations
import sys
from app.service import dicts, formruntime
FAILS: list[str] = []
def check(label: str, got: object, want: object) -> None:
if got != want:
FAILS.append(f"{label}:想要 {want!r},拿到 {got!r}")
def problems(*fields: dict) -> list[str]:
return formruntime.linkage_problems(list(fields))
OWN = "contractNo"
OTHERS = [
{"key": "dept", "label": "申请部门", "type": "dept"},
{"key": "amount", "label": "报销金额", "type": "money"},
]
def own(**patch: object) -> dict:
return {"key": OWN, "label": "合同编号", "type": "text", **patch}
def when(rules: list[dict], match: str = "all") -> dict:
return {"match": match, "rules": rules}
# ------------------------------------------------------------------ 1. 判得出结果
check(
"本字段有值才露:没值不成立",
dicts.state_of(own(visibleWhen=when([{"field": OWN, "op": "notEmpty"}])), {}),
{"visible": False, "required": False, "readonly": False},
)
check(
"本字段有值才露:带进值来就成立",
dicts.state_of(own(visibleWhen=when([{"field": OWN, "op": "notEmpty"}])), {OWN: "HT-2026-011"}),
{"visible": True, "required": False, "readonly": False},
)
check(
"没值才露是反过来的同一句",
[
dicts.state_of(own(visibleWhen=when([{"field": OWN, "op": "empty"}])), {}),
dicts.state_of(own(visibleWhen=when([{"field": OWN, "op": "empty"}])), {OWN: "HT-1"}),
],
[
{"visible": True, "required": False, "readonly": False},
{"visible": False, "required": False, "readonly": False},
],
)
check(
"拿自己的值比大小也讲得通(这一格自己判自己一个数)",
[
dicts.state_of({"key": "amount", "label": "金额", "type": "money", "visibleWhen": when([{"field": "amount", "op": "gt", "value": 5000}])}, {"amount": 8000}),
dicts.state_of({"key": "amount", "label": "金额", "type": "money", "visibleWhen": when([{"field": "amount", "op": "gt", "value": 5000}])}, {"amount": 200}),
],
[{"visible": True, "required": False, "readonly": False}, {"visible": False, "required": False, "readonly": False}],
)
check(
"右边挑自己也算读自己:另一格跟自己比,判的是自己此刻的值",
dicts.state_of(own(visibleWhen=when([{"field": "amount", "op": "gt", "valueField": OWN}])), {OWN: 100}),
# 右边 100、左边没填 -> 比不出结果,这一条不算成立
{"visible": False, "required": False, "readonly": False},
)
check(
"有值就锁住:锁住自己的正是自己那一格",
[
dicts.state_of(own(readonlyWhen=when([{"field": OWN, "op": "notEmpty"}])), {}),
dicts.state_of(own(readonlyWhen=when([{"field": OWN, "op": "notEmpty"}])), {OWN: "HT-1"}),
],
[
{"visible": True, "required": False, "readonly": False},
{"visible": True, "required": False, "readonly": True},
],
)
check("空格算没填:两边同一把尺子", dicts._is_empty(" "), True)
check(
"只敲了空格那一格不露(前端 isEmptyValue 同一寸)",
dicts.state_of(own(visibleWhen=when([{"field": OWN, "op": "notEmpty"}])), {OWN: " "})["visible"],
False,
)
check("0 与 False 都算填了,别把判空做成判零", [dicts._is_empty(0), dicts._is_empty(False)], [False, False])
# ------------------------------------------------------------------ 2. 上游与配错
check(
"条件层面的上游留着自指,级联清值那圈摘掉它",
[
dicts.condition_dependencies(own(visibleWhen=when([{"field": OWN, "op": "notEmpty"}, {"field": "amount", "op": "gt", "valueField": "dept"}]))),
dicts.depends_on(own(visibleWhen=when([{"field": OWN, "op": "notEmpty"}, {"field": "amount", "op": "gt", "valueField": "dept"}]))),
],
[[OWN, "amount", "dept"], ["amount", "dept"]],
)
check("自引用不再是配错", problems(own(visibleWhen=when([{"field": OWN, "op": "notEmpty"}])), *OTHERS), [])
check(
"级联上级选自己照旧要说",
"级联上级选了它自己" in "".join(problems(own(cascadeFrom=OWN), *OTHERS)),
True,
)
check(
"左右两头是同一格照旧要说(自己跟自己比没有新意思)",
problems(own(visibleWhen=when([{"field": OWN, "op": "eq", "valueField": OWN}])), *OTHERS),
['「合同编号」的联动条件拿「合同编号」和自己比'],
)
check(
"同一条里既有自引用又有悬空引用:只放行指向自己的那一条",
problems(own(visibleWhen=when([{"field": OWN, "op": "notEmpty"}, {"field": "gone", "op": "eq", "value": "x"}])), *OTHERS),
['「合同编号」的联动条件引用了不存在的字段「gone」'],
)
check("带出规则写回自己仍是配错", "不能写回自己" in "".join(problems(own(dictCode="d", autoFill=[{"to": OWN, "pick": "value"}]), *OTHERS)), True)
# ------------------------------------------------------------------ 3. 摘掉自引用那几条
check(
"只剩自引用时等于没配条件",
dicts.without_self_rules(when([{"field": OWN, "op": "notEmpty"}]), OWN),
{"match": "all", "rules": []},
)
check("一条都没摘动时回 None(原本没读自己)", dicts.without_self_rules(when([{"field": "dept", "op": "notEmpty"}]), OWN), None)
check(
"混着配时只摘读自己那一条",
dicts.without_self_rules(when([{"field": OWN, "op": "notEmpty"}, {"field": "dept", "op": "notEmpty"}]), OWN),
{"match": "all", "rules": [{"field": "dept", "op": "notEmpty"}]},
)
check("没读过自己的格子不用摘", dicts.stripped_of_self(own()), None)
check(
"三栏一起摘:只摘显隐会漏掉「有值就锁住」那一栏",
sorted(dicts.stripped_of_self(own(readonlyWhen=when([{"field": OWN, "op": "notEmpty"}])))),
sorted({"key": OWN, "label": "合同编号", "type": "text", "readonlyWhen": {"match": "all", "rules": []}}),
)
# ------------------------------------------------------------------ 4. 只被自己收走的格子,值要收下
check(
"值没带回来:这一格此刻是隐藏的",
formruntime.effective_perm(own(visibleWhen=when([{"field": OWN, "op": "notEmpty"}])), {}, {}),
formruntime.PERM_HIDDEN,
)
check(
"值带回来了:这一格露着、也填得动",
formruntime.effective_perm(own(visibleWhen=when([{"field": OWN, "op": "notEmpty"}])), {}, {OWN: "HT-1"}),
formruntime.PERM_EDITABLE,
)
check(
"藏起它的只有它自己:这一笔值算填得动",
formruntime.self_gated_keys([own(visibleWhen=when([{"field": OWN, "op": "notEmpty"}]))], {}, {}),
{OWN},
)
check(
"「有值就锁住」那一栏同样放宽",
formruntime.self_gated_keys([own(readonlyWhen=when([{"field": OWN, "op": "notEmpty"}]))], {}, {OWN: "HT-1"}),
{OWN},
)
check(
"环节明写隐藏:藏它的是环节,不借这一档翻案",
formruntime.self_gated_keys([own(visibleWhen=when([{"field": OWN, "op": "notEmpty"}]))], {OWN: formruntime.PERM_HIDDEN}, {}),
set(),
)
check(
"还有一条读别的格子的条件没放行:藏它的是那一格",
formruntime.self_gated_keys(
[own(visibleWhen=when([{"field": OWN, "op": "notEmpty"}, {"field": "dept", "op": "notEmpty"}]))], {}, {}
),
set(),
)
check("没读自己的格子压根不掺和这一档", formruntime.self_gated_keys([own()], {}, {}), set())
check(
"说明文字那种没有录入框的格子不放宽(自引用也放不开 NON_INPUT)",
formruntime.self_gated_keys(
[{"key": OWN, "label": "说明", "type": "description", "visibleWhen": when([{"field": OWN, "op": "notEmpty"}])}], {}, {}
),
set(),
)
# 「这一格填了 SKIP 就不露」那一类:条件一放行,必填立刻跟着要它
check(
"自引用条件放行的那一格,必填照常要",
[
formruntime.missing_required([own(required=True, visibleWhen=when([{"field": OWN, "op": "ne", "value": "SKIP"}]))], {}, {OWN: "SKIP"}),
formruntime.missing_required([own(required=True, visibleWhen=when([{"field": OWN, "op": "ne", "value": "SKIP"}]))], {}, {}),
],
[[], ["合同编号"]],
)
check(
"默认隐藏 + 只判自己:说话的是条件,不是默认值",
[
formruntime.effective_perm(own(hidden=True, visibleWhen=when([{"field": OWN, "op": "notEmpty"}])), {}, {OWN: "HT-1"}),
formruntime.effective_perm(own(hidden=True, visibleWhen=when([{"field": OWN, "op": "notEmpty"}])), {}, {}),
],
[formruntime.PERM_EDITABLE, formruntime.PERM_HIDDEN],
)
check(
"放宽的只是收不收这一笔值,界面上露不露一寸没动",
[
formruntime.effective_perm(own(visibleWhen=when([{"field": OWN, "op": "notEmpty"}])), {}, {}),
formruntime.field_hidden(own(visibleWhen=when([{"field": OWN, "op": "notEmpty"}])), {}, {}),
],
[formruntime.PERM_HIDDEN, True],
)
if FAILS:
print("\n".join(FAILS))
sys.exit(f"失败 {len(FAILS)} 句")
print("通过:联动条件判自己那一格——判得出、不当配错、只被自己藏起来的值照样收下")

View File

@ -0,0 +1,222 @@
#!/usr/bin/env python3
"""明细列跟主表字段同权之后,后端这几道闸跟着改了什么。
PYTHONPATH=. python3 scripts/check_table_column_config.py
用户那句原话:**"明细表里面的列,我希望也可以和主表字段一样可以进行各种配置。"**
查下来跟「只读」那次一模一样:缺的主要不是运行时的判据,而是设计器里的入口。明细格子
与主表格子共用同一只录入控件(``FormFieldControl``),控件读的就是传进去那一份对象,
所以``placeholder`` / ``maxLength`` / ``pattern`` / ``min`` / ``max`` / ``accept`` /
``maxFiles`` / ``maxSizeMb`` 这些写在列上的键,界面上摆出格子来当场就生效;后端的
``value_problems`` 本来就按列判过一遍。这一趟真正动到后端的是三件事:
1. **藏起来的那一列不卡必填**。明细列上新的「隐藏此列」复用主表那一份 ``hidden``
(环节权限到不了单列那一层,粒度是整张表),语义与「只读」同一取向:那一列屏幕上
根本不出现,人也填不进东西,卡必填等于把单子钉死在这一环。口径在
:func:`column_not_for_people`,前端镜像 ``utils/formRuntime.columnNotForPeople``。
值本身照常存、照常导出、照常参与本行公式与关联带出——只管摆不摆。它同时算"这一环
改不动的那几格",所以值的格式也不在这一环判:主表那格「默认隐藏」一直就是这个口径
(``value_problems`` 只判 ``effective_perm`` 认得动的那几格),明细列不另发明第二套。
勾「只读」的那一列不一样——它还摆在屏幕上,只是锁着,值的格式照判。
2. **取值上下限(``min`` / ``max``)提交时判**,主表与明细列一起。以前界面上
``<input type="number">`` 的 ``min`` / ``max`` 只标个红,后端压根没读那两个数——
接口直传、脚本写入的值连那只框都不经过。「权威判定在提交那一步」这条规矩不能只
对字数与附件成立。
3. **格式那几问不再跟着必填走**。``_row_problems`` 里整段原本套在「这列没勾必填就跳过」
里面,于是非必填的列填了什么都没人看:字数上限、正则、上下限、月份写法、附件三个
限制,只在必填列上成立。改成必填归必填、格式归格式,判据仍是 ``value_problems`` 那一份。
另外「列宽 / 对齐 / 合计」那三样(``width`` / ``align`` / ``aggregate``)是**纯展现**:
不改任何一格的值,也不参与提交那道闸,所以后端只在保存那一刻判"配置本身认不认识"
(:func:`column_display_problems`,与前端 ``validateTableField`` 同一把尺子),运行时
一个字都不读——与 ``readonlyStyle`` 同一处置。
钉这廿一句,全程不碰库。
"""
from __future__ import annotations
import sys
from app.service import formruntime
FAILS: list[str] = []
def check(label: str, got: object, want: object) -> None:
if got != want:
FAILS.append(f"{label}:想要 {want!r},拿到 {got!r}")
def table(columns: list[dict], **rest: object) -> dict:
return {"key": "items", "label": "费用明细", "type": "table", "columns": columns, **rest}
def rows_problems(columns: list[dict], rows: list[dict]) -> list[str]:
return formruntime._row_problems(table(columns), rows)
def submit(columns: list[dict], rows: list[dict]) -> list[str]:
return formruntime.validate_submit([table(columns)], {}, {"items": rows})
def schema(columns: list[dict]) -> list[str]:
return formruntime.validate_schema([table(columns)])
HIDDEN_CODE = {"key": "code", "label": "物料编码", "type": "text", "required": True, "hidden": True}
OPEN_NOTE = {"key": "note", "label": "事由", "type": "text", "required": True}
QTY = {"key": "qty", "label": "数量", "type": "number", "min": 5, "max": 10}
PRICE = {"key": "price", "label": "单价", "type": "money", "max": 3}
# ------------------------------------------------------- 藏起来的列不卡必填
check(
"藏起来的必填列空着也过得去(屏幕上根本没有这一格)",
rows_problems([HIDDEN_CODE], [{"code": ""}]),
[],
)
check(
"同一张表里摆着的那一列照旧卡人",
rows_problems([OPEN_NOTE, HIDDEN_CODE], [{"note": "", "code": ""}]),
["「费用明细」第 1 行的「事由」还没填写"],
)
check(
"藏起来的列里躺着的值不判格式:环节改不动的那几格不由这一环背锅(与主表「默认隐藏」同一口径)",
rows_problems([{**HIDDEN_CODE, "maxLength": 2}], [{"code": "ABCDEF"}]),
[],
)
check(
"只读那一列照旧判:勾只读的列仍在屏幕上,只是锁着(这一问走的是 effective_perm)",
rows_problems([{**HIDDEN_CODE, "hidden": False, "readonly": True, "maxLength": 2}], [{"code": "ABCDEF"}]),
["「费用明细」第 1 行的「物料编码」超出字数上限(2 字,现在 6 字)"],
)
check(
"勾掉隐藏就回到从前(这一列的值归人了)",
rows_problems([{**HIDDEN_CODE, "hidden": False}], [{"code": ""}]),
["「费用明细」第 1 行的「物料编码」还没填写"],
)
check(
"提交时:只有藏着的那一列空着 → 过得去",
submit([OPEN_NOTE, HIDDEN_CODE], [{"note": "打车", "code": ""}]),
[],
)
# ------------------------------------------- 上下限:主表与明细列都判,且各行其道
check(
"明细列的数小于最小值 → 说清是哪一行哪一列",
rows_problems([QTY], [{"qty": 1}]),
["「费用明细」第 1 行的「数量」小于配好的最小值 5"],
)
check(
"明细列的数大于最大值 → 同样说清",
rows_problems([PRICE], [{"price": 9}]),
["「费用明细」第 1 行的「单价」大于配好的最大值 3"],
)
check(
"落在上下限之间不多话;空着也不归这两问答(那是必填的事)",
rows_problems([QTY, PRICE], [{"qty": 6, "price": 2}, {"qty": "", "price": None}]),
[],
)
check(
"主表那一格同样判:上下限不是明细列的专利",
formruntime.validate_submit([{"key": "days", "label": "天数", "type": "number", "min": 1, "max": 30}], {}, {"days": 45}),
["「天数」大于配好的最大值 30"],
)
check(
"评分的 max 是满星数,不被当成取值范围判",
formruntime.validate_submit([{"key": "score", "label": "评分", "type": "rate", "max": 5}], {}, {"score": 3}),
[],
)
check(
"非必填的列也判格式:这一问不跟着必填走",
rows_problems([{"key": "note", "label": "事由", "type": "text", "maxLength": 2}], [{"note": "三个字" }]),
["「费用明细」第 1 行的「事由」超出字数上限(2 字,现在 3 字)"],
)
check(
"必填那一问照旧只管没勾着的那几样:非必填且空着不催",
rows_problems([{"key": "note", "label": "事由", "type": "text"}], [{"note": ""}]),
[],
)
# ------------------------------------------------ 设计期:列上那三样纯展现的判法
check(
"列宽写成一粒米:保存这一刻挡下来",
schema([{"key": "a", "label": "数量", "type": "number", "width": 20}]),
["「费用明细」的列「数量」的列宽要在 60-640px 之间,或留「自动」"],
)
check(
"对齐与合计写成认不出的档:同样当场说",
schema([{"key": "a", "label": "数量", "type": "number", "align": "middle", "aggregate": "total"}]),
[
"「费用明细」的列「数量」的对齐方式不认识:middle",
"「费用明细」的列「数量」的合计方式不认识:total",
],
)
check(
"给文本列配求和:不是数字也不是金额,只能数个数",
schema([{"key": "a", "label": "名称", "type": "text", "aggregate": "sum"}]),
["「费用明细」的列「名称」不是数字或金额列,合计只能数个数"],
)
check(
"上下限写反了:这一列填不出合法的数",
schema([{"key": "a", "label": "数量", "type": "number", "min": 9, "max": 2}]),
["「费用明细」的列「数量」的最小值大于最大值"],
)
check(
"配得正的列一句不多说:自动宽度 + 靠右 + 计数 + 藏着",
schema(
[
{
"key": "a",
"label": "名称",
"type": "text",
"width": 160,
"align": "right",
"aggregate": "count",
"hidden": True,
"help": "从物料库带出",
}
]
),
[],
)
check(
"数字列求和与金额列平均都是正当配置",
schema(
[
{"key": "qty", "label": "数量", "type": "number", "aggregate": "sum", "min": 1, "max": 99},
{"key": "price", "label": "单价", "type": "money", "aggregate": "avg"},
]
),
[],
)
# -------------------------------------------------- 列上的限制与主表是同一份归属表
check(
"字数上限写在列上,主表那套口径与措辞原样搬过来",
formruntime.validate_schema(
[{"key": "a", "label": "事由", "type": "text", "maxLength": 999999}]
),
["「事由」的字数上限要在 1-100000 之间"],
)
check(
"正则编译不过:写在主表与写在列上同样当场挡",
formruntime.validate_schema([table([{"key": "a", "label": "工号", "type": "text", "pattern": "([A-Z"}])]),
["「费用明细」的列「工号」的校验正则「([A-Z」编译不过,检查括号与转义"],
)
def main() -> int:
for line in FAILS:
print(f"[FAIL] {line}")
if FAILS:
print(f"共 {len(FAILS)} 句不对")
return 1
print("通过:藏着的列不卡必填、上下限提交时判(主表与明细同权)、格式那几问不再跟着必填走、"
"列宽对齐合计只在设计期判(21 句)")
return 0
if __name__ == "__main__":
sys.exit(main())

View File

@ -0,0 +1,153 @@
#!/usr/bin/env python3
"""明细表那一列勾了「只读」之后,提交那道闸怎么跟着让路。
PYTHONPATH=. python3 scripts/check_table_column_readonly.py
用户那句原话:"表单的明细表中的字段,无法设置不可编辑。"
查下来缺的不是运行时的判据,而是设计器里的入口:列上那份 ``column.readonly`` 本来就有主
(``FormRenderer`` 把它递给录入控件、``FieldInspector`` 的「带出后允许填写人修改」改的就是
它),可这一份只长在「自动带出」底下那颗开关上——没配带出的列压根锁不上。现在明细列卡上
跟主表一样摆了一颗「只读」,于是必须回答第二个问题:**锁着的列还要不要卡必填**。
不要。必填卡的是人,而锁着的列根本没有录入框:那一格的值归默认值 / 自动带出 / 关联带出 /
额度台账给,人改不动却永远被催"还没填写",这张单就地卡在这一环——跟"屏幕上没有那一格,
却说请先填写它"是同一种坏法。口径与主表 ``missing_required`` 同一取向(没有录入框的那几类
只在值真归系统管时才算数),前端也不给锁着的列摆那颗红星(``FormRenderer`` 与
``FieldInspector.column-readonly.spec.ts``)。
三条分寸写死在这里:
1. **只让"必填"这一条**:那一格里已经躺着的值照旧过一遍格式那几关(字数、正则、月份写法…),
配置歪了该说还是说;
2. **只认 ``readonly`` 这一个标记**:写了本行公式那一列没勾只读,公式算不出值仍是配置坏了,
照旧拦(界面上那一列的锁是勾死解不开的);
3. **整张明细表那一格的权限判定一个字没动**:环节把整张表设成只读走的还是 ``effective_perm``
那一份,列上这一层只在表本来摊开给人填时说话。
钉这十四句,全程不碰库。
"""
from __future__ import annotations
import sys
from app.service import formruntime
FAILS: list[str] = []
def check(label: str, got: object, want: object) -> None:
if got != want:
FAILS.append(f"{label}:想要 {want!r},拿到 {got!r}")
def table(columns: list[dict], **rest: object) -> dict:
return {"key": "items", "label": "费用明细", "type": "table", "columns": columns, **rest}
def rows_problems(columns: list[dict], rows: list[dict], **rest: object) -> list[str]:
return formruntime._row_problems(table(columns, **rest), rows)
def submit(fields: list[dict], data: dict) -> list[str]:
return formruntime.validate_submit(fields, {}, data)
LOCKED = {"key": "src", "label": "来源", "type": "text", "required": True, "readonly": True}
OPEN = {"key": "note", "label": "事由", "type": "text", "required": True}
# ------------------------------------------------------- 锁着的列不卡必填
check(
"锁着的必填列空着也过得去(人根本没有地方填)",
rows_problems([LOCKED], [{"src": ""}]),
[],
)
check(
"同一张表里没锁的那一列照旧卡人,说的是哪一行哪一列",
rows_problems([OPEN, LOCKED], [{"note": "", "src": ""}]),
["「费用明细」第 1 行的「事由」还没填写"],
)
check(
"逐行都判:锁着的那一列不在第二行漏出来,没锁的那一列也不在第二行少说",
rows_problems([OPEN, LOCKED], [{"note": "a", "src": ""}, {"note": "", "src": ""}]),
["「费用明细」第 2 行的「事由」还没填写"],
)
check(
"勾掉只读就回到从前(这一列的值归人了)",
rows_problems([{**LOCKED, "readonly": False}], [{"src": ""}]),
["「费用明细」第 1 行的「来源」还没填写"],
)
check(
"只读列没勾必填:本来就不参与必填那道判",
rows_problems([{**LOCKED, "required": False}], [{"src": ""}]),
[],
)
check(
"开关认的是勾没勾,认不出别的写法(``readonly: \"\"`` 当没锁)",
rows_problems([{**LOCKED, "readonly": ""}], [{"src": ""}]),
["「费用明细」第 1 行的「来源」还没填写"],
)
# ------------------------------------------------- 只让"必填"这一条,其余照判
check(
"锁着的列里已经躺着的值合不合规矩照旧判(配置歪了该说)",
rows_problems([{**LOCKED, "maxLength": 2}], [{"src": "三个字"}]),
["「费用明细」第 1 行的「来源」超出字数上限(2 字,现在 3 字)"],
)
check(
"本行公式那一列不在豁免之列:没勾只读,公式算不出值仍是配置坏了",
rows_problems([{**LOCKED, "readonly": False, "formula": "qty * price"}], [{"src": ""}]),
["「费用明细」第 1 行的「来源」还没填写"],
)
check(
"行数上下界照旧(那是整张表的事,与锁哪一列无关)",
rows_problems([LOCKED], [], minRows=2),
["「费用明细」至少要有 2 行"],
)
# ----------------------------------------------------------- 走一遍提交那道闸
FIELDS = [table([OPEN, LOCKED])]
check(
"提交时:只有锁着的那一列空着 → 过得去",
submit(FIELDS, {"items": [{"note": "打车", "src": ""}]}),
[],
)
check(
"提交时:没锁的那一列空着 → 还是挡,且只说那一列",
submit(FIELDS, {"items": [{"note": "", "src": ""}]}),
["「费用明细」第 1 行的「事由」还没填写"],
)
# ------------------------------------------- 整张表那一层的判定一个字没动
check(
"整张表勾了只读:环节没点名时算只读(列上这一层不抢这句话)",
formruntime.effective_perm({**table([LOCKED]), "readonly": True}, {}),
formruntime.PERM_READONLY,
)
check(
"环节显式给了可编辑就听环节的(存量表单不被列上这一层带坏)",
formruntime.effective_perm(table([LOCKED]), {"items": "editable"}),
"editable",
)
# --------------------------------------------------------------- 设计期不报错
check(
"锁着的列不是配置毛病:保存那一刻不多说一句",
formruntime.validate_schema([table([{"key": "note", "label": "事由", "type": "text", "readonly": True}])]),
[],
)
def main() -> int:
for line in FAILS:
print(f"[FAIL] {line}")
if FAILS:
print(f"共 {len(FAILS)} 句不对")
return 1
print("通过:锁着的明细列不卡必填、值的格式照判、整张表那一层判定没被带坏(14 句)")
return 0
if __name__ == "__main__":
sys.exit(main())

View File

@ -0,0 +1,104 @@
#!/usr/bin/env python3
"""明细列勾了「公式带入后允许修改」之后,后端这一侧跟着改了什么。
PYTHONPATH=. python3 scripts/check_table_formula_editable.py
用户那句原话:**"表单中明细表中引用公式带入的值,为什么不能编辑?我需要可编辑。"**
本行公式的数**只有前端会算**(``compute_formulas`` 只管 ``type=formula`` 那一格),所以后端
从来不重算明细列——这一趟动到后端的只有一件事:**别把人自己敲的那份凭据半路丢掉**。
前端改一格会在行上写一份 ``_manual``(列标识的数组,与关联带出那一份 ``_link`` 同一层),
下一轮重算靠它绕开那一格;它若被 :func:`normalise_rows` 当野键丢掉,下一环的人重新打开
这张单,昨天改的数就悄悄变回公式算的那个——改动了却留不住,比不让改更气人。
顺带钉住四条没动的:勾了这一档不算把列锁上(必填照卡)、公式列的默认值照旧不复活、
值本身照旧过格式那几关、这一档不是配置毛病(保存那一刻不多说一句)。
全程不碰库。
"""
from __future__ import annotations
from pathlib import Path
from app.service import formruntime
FAILS: list[str] = []
FRONTEND = Path(__file__).resolve().parents[2] / "frontend" / "src"
def check(label: str, got: object, want: object) -> None:
if got != want:
FAILS.append(f"{label}:想要 {want!r},拿到 {got!r}")
def table(columns: list[dict], **rest: object) -> dict:
return {"key": "items", "label": "费用明细", "type": "table", "columns": columns, **rest}
FORMULA = {"key": "pay", "label": "收款金额", "type": "money", "formula": "qty * price"}
EDITABLE = {**FORMULA, "formulaEditable": True}
PLAIN = {"key": "qty", "label": "数量", "type": "number"}
PRICE = {"key": "price", "label": "单价", "type": "number"}
# --------------------------------------------------------------- 那一份凭据
check("行标记与前端认的是同一个", formruntime.ROW_MANUAL_KEY, "_manual")
check(
"前端那份写的也是同一个键",
f"export const ROW_MANUAL_KEY = '{formruntime.ROW_MANUAL_KEY}'" in (FRONTEND / "utils" / "formRuntime.ts").read_text(encoding="utf-8"),
True,
)
rows = formruntime.normalise_rows(
[
{"qty": 2, "price": 30, "pay": 888, "_manual": ["pay"], "_link": "J1", "_wild": "丢掉"},
{"qty": "", "price": "", "pay": "", "_manual": ["pay"]},
],
table([PLAIN, PRICE, FORMULA]),
)
check("只留认识的列与两份留痕", sorted(rows[0].keys()), ["_link", "_manual", "pay", "price", "qty"])
check("人敲的那个数原样落库", rows[0]["pay"], 888)
check("凭据跟着走完全程", rows[0]["_manual"], ["pay"])
check("只带着凭据的空行不凭空造一行", len(rows), 1)
# ------------------------------------------------------- 这一档不算把列锁上
check("勾了这一档的公式列仍归人填", formruntime.column_not_for_people(EDITABLE), False)
check(
"必填照卡:那一格有框了,空着就该说",
formruntime._row_problems(table([dict(EDITABLE, required=True)]), [{"pay": ""}]),
["「费用明细」第 1 行的「收款金额」还没填写"],
)
check(
"值本身照判格式:手工敲歪了同样过不了那道闸",
formruntime._row_problems(table([{**EDITABLE, "max": 100}]), [{"pay": 999}]),
["「费用明细」第 1 行的「收款金额」大于配好的最大值 100"],
)
# ------------------------------------------------------- 默认值不跟着复活
check("公式列的默认值一律不落(勾没勾这一档都一样)", formruntime.column_default({**FORMULA, "defaultValue": 9}), None)
check("勾了这一档也一样", formruntime.column_default({**EDITABLE, "defaultValue": 9}), None)
# ----------------------------------------------------------- 设计期不报错
check(
"这一档不是配置毛病:保存那一刻不多说一句",
formruntime.validate_schema([table([PLAIN, PRICE, dict(EDITABLE, required=True)])]),
[],
)
def main() -> int:
for line in FAILS:
print(f"[FAIL] {line}")
if FAILS:
print(f"共 {len(FAILS)} 句不对")
return 1
print("通过:行上那份凭据一路不丢、这一档不锁列也不放宽校验、默认值没复活、设计期不报错(12 句)")
return 0
if __name__ == "__main__":
import sys
sys.exit(main())

View File

@ -0,0 +1,646 @@
#!/usr/bin/env python3
"""出差备案申请:把「一家四格」收成「一格四家」。
生产上那张「出差备案申请」为四种项目分类各摆了一行同构字段(项目名称 / 项目编码 /
最终客户名称 / 项目阶段 × PMS / VDI / 行政 / 定制 = 16 格),配的都是同一件事,
只因为「一格只能挂一个来源」才被迫摊开,靠每格的显示条件互相藏起来。
候选来源条件路由(``optionRoutes`` + ``fetch.sources[].when`` + ``optionRoutes[].fill``)
落地之后,这 16 格可以收成 4 格:分类选 PMS 就问 ``pms_project`` 要候选,选 VDI 就换
``SCC_Project``,选行政 / 定制就回落到字段自己那一份、只跑这一家那一条外部取数。
这个脚本干三件事,默认**一个字都不改**:
1. 照着表上真实的字段算一遍收拢后的样子(条件从各格的显示条件里读,来源从各格自己身上读);
2. 用运行时那套口径把四种分类各跑一遍,逐条比对收拢前后「问哪一家、候选几条、
带出写哪几格、写进来的值一不一样」;
3. 按设计器保存的同一条路做校验(``clean_option_source`` + ``form_problems``)。
确认没问题再落库:
python3 scripts/collapse_trip_form.py # 看对照与校验
python3 scripts/collapse_trip_form.py --json /tmp/new.json # 顺手把结果写成文件
python3 scripts/collapse_trip_form.py --write --perms # 存成新的表单版本 + 收环节权限
OA_ENV=prod python3 scripts/collapse_trip_form.py # 对生产库跑(默认也是按当前档位连库)
只在读得出把握时才 ``--write``:字段名一改,环节权限、导出列、报表口径读的都是字段名,
``--perms`` 会把环节上那 16 条权限折到 4 格上,导出列与外部回写还得人工对一遍。
"""
from __future__ import annotations
import argparse
import copy
import json
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parents[0].parent))
from sqlalchemy import select # noqa: E402
from app import models # noqa: E402
from app.db import SessionLocal # noqa: E402
from app.service import binding, dicts, fetch, formruntime # noqa: E402
#: 驱动那一格:收拢后四种分类共用它的取值决定问哪一家。
DRIVER = "project_type"
#: 四组同构字段。``members`` 是表上现在的格子(缺了就不管它),``key`` / ``label`` 是收拢后那一格。
GROUPS: list[dict] = [
{"members": ["project_pms", "project_scc", "project_xz", "project_dz"],
"key": "project", "label": "项目名称"},
{"members": ["project_code_pms", "project_code_SCC", "project_code_xz", "project_code_dz"],
"key": "project_code", "label": "项目编码"},
{"members": ["customer_name_pms", "customer_scc", "customer_xz", "customer_dz"],
"key": "customer_name", "label": "最终客户名称"},
{"members": ["project_stage_pms", "project_stage_scc", "project_stage_xz", "project_stage_dz"],
"key": "project_stage", "label": "项目阶段"},
]
#: 收拢后拿哪一格的模样当基准:能挑候选的优先(字典 > 外部数据源 > 手填 > 只读取数)。
KIND_RANK = {"dict": 0, "dataSource": 1, "manual": 2, "fetch": 3}
#: 分类还没选、清单里一条都不成立时回落到哪一份:``first`` 用第一家那套来源,
#: ``empty`` 给一份空候选(四家来源各不相同时更诚实:还没选分类,这一格本来就没得挑)。
BASE_WHEN_UNMATCHED = {"project": "empty"}
def load_form(db, wanted: str) -> models.FormElement:
"""按 id 或名字找那张表单;名字撞上好几张就停下来问清楚,别猜。"""
row = db.get(models.FormElement, wanted)
if row is not None:
return row
rows = db.execute(
select(models.FormElement).where(models.FormElement.name == wanted)
).scalars().all()
if len(rows) == 1:
return rows[0]
raise SystemExit(f"表单「{wanted}」在库里{'没有' if not rows else '有 ' + str(len(rows)) + ' 张'},用 --form 说清楚是哪一张")
def driver_value_of(field: dict) -> str:
"""这一格的显示条件是不是「某一类分类才显示」这一种:是就回那个分类值,不是回空串。
收成一家靠的就是这一句:原来「PMS 才显示这一格」与收拢后「分类是 PMS 就用这一家」
是同一个条件,直接搬过去,不让人再抄一遍。
"""
cond = field.get("visibleWhen") or {}
rules = cond.get("rules") if isinstance(cond, dict) else None
if not isinstance(rules, list) or len(rules) != 1 or cond.get("match") not in (None, "all"):
return ""
rule = rules[0]
if not isinstance(rule, dict) or rule.get("op") != "eq" or rule.get("field") != DRIVER:
return ""
return str(rule.get("value") or "").strip()
def when_of(value: str) -> dict:
return {"match": "all", "rules": [{"op": "eq", "field": DRIVER, "value": value}]}
def kind_of(field: dict) -> str:
"""这一格现在问谁要候选:外部取数那一头回 ``fetch``。"""
if field.get("fetch"):
return "fetch"
return str(field.get("optionSource") or "") or "manual"
#: 每一种来源各自带的那几格配置,换一家就得重问一遍(与前端 ROUTE_OWNED_KEYS 同一分工)。
ROUTE_KIND_KEYS = {
"manual": ["options"],
"dict": ["dictCode", "cascadeFrom"],
"dataSource": ["dataSourceCode", "dataSourceArgs"],
"process": ["relationProcess", "relationStatuses"],
}
def has_candidates(member: dict) -> bool:
"""这一格是不是真的能挑候选:字典 / 数据源 / 关联流程 / 填了选项的手填才算。
纯文本那几格(行政项目阶段之类手填的)没有候选可搬,收成一家之后它们跟着
这一格共用的那一份来源走就行,别给它们造一条空候选的路由。
"""
kind = kind_of(member)
if kind == "manual":
return bool(member.get("options"))
return kind in ROUTE_KIND_KEYS
def route_from(member: dict, value: str, alias: dict[str, str]) -> dict:
"""把一格的候选来源配置搬成清单里的一条:条件 + 那一家的来源 + 它自带的带出。"""
kind = kind_of(member)
route: dict = {"when": when_of(value), "source": kind}
for name in ROUTE_KIND_KEYS[kind]:
if member.get(name) not in (None, "", [], {}):
route[name] = copy.deepcopy(member[name])
if member.get("optionMap"):
route["optionMap"] = copy.deepcopy(member["optionMap"])
if member.get("note"):
route["note"] = member["note"]
fill = clean_fill(copy.deepcopy(member.get("fetch") or {}), alias)
if fill:
route["fill"] = fill
return route
def clean_fill(cfg: dict, alias: dict[str, str]) -> dict:
"""一格的取数配置摊成「这一家自带的带出」:源、入参、带出去向,落点搬到收拢后的名字上。"""
out: dict = {}
code = str(cfg.get("source") or "").strip()
if code:
out["source"] = code
for name in ("args", "picks", "extras"):
rows = cfg.get(name)
if not isinstance(rows, dict) or not rows:
continue
if name == "picks":
rows = {key: alias.get(str(value), value) for key, value in rows.items()}
out[name] = copy.deepcopy(rows)
return out
def fetch_entry_from(member: dict, value: str, alias: dict[str, str]) -> dict:
"""把一格「只读取数」那一份配置搬成清单里的一条:条件跟着走,落点搬到收拢后的名字上。
``picks`` 写的是别的字段的名字,被收拢的那 16 个名字马上就没了。留着不是"暂时没生效",
是等下一个字段占用旧名字时把数悄悄盖到它头上(同 utils/formRename 搬带出的理由)。
"""
cfg = copy.deepcopy(member.get("fetch") or {})
cfg.pop("when", None)
picks = cfg.get("picks")
if isinstance(picks, dict):
cfg["picks"] = {key: alias.get(str(value_), value_) for key, value_ in picks.items()}
entry = {key: item for key, item in cfg.items() if item not in (None, "", {}, [])}
entry["when"] = when_of(value)
return entry
def merged_field(members: list[tuple[dict, str]], key: str, label: str, alias: dict[str, str]) -> dict:
"""一组同构字段收成那一格。
``members`` 是「(原来那一格, 它对应的分类值)」,按表上先后顺序给。
"""
ranked = sorted(members, key=lambda pair: KIND_RANK.get(kind_of(pair[0]), 9))
base_src = copy.deepcopy(ranked[0][0])
merged: dict = {
"key": key,
"label": label,
"type": base_src.get("type") or "text",
"col": min(int(item.get("col") or 1) for item, _ in members),
"row": min(int(item.get("row") or 1) for item, _ in members),
"span": max(int(item.get("span") or 6) for item, _ in members),
}
if base_src.get("required"):
merged["required"] = True
if base_src.get("readonly"):
merged["readonly"] = True
routes: list[dict] = []
entries: list[dict] = []
fills: list[dict] = []
for member, value in members:
if kind_of(member) == "fetch":
entries.append(fetch_entry_from(member, value, alias))
elif has_candidates(member):
routes.append(route_from(member, value, alias))
# 字典那一家的带出读的是「此刻命中的那一本」的附加值,所以各格的 autoFill 合成一份就够:
# 命中的那本没有那一列时一个字段都不写(dicts.apply_auto_fill 里 value is None 直接跳过),
# 不会把隔壁家带来的值抹掉。
for rule in member.get("autoFill") or []:
if not isinstance(rule, dict):
continue
moved = copy.deepcopy(rule)
moved["to"] = alias.get(str(rule.get("to") or ""), str(rule.get("to") or ""))
if moved not in fills:
fills.append(moved)
# 挑候选那一格的挑选方式(搜哪几列、下拉与弹窗各念哪几列)也合成一份:换一家之后
# 还能按上一家那样搜,是配表的人唯一能感觉出来的那点是或否。这几列写在哪儿历史上有
# 两种形状(picker 顶上与 picker.dialog / picker.dropdown 里),三种都认。
picker = member.get("picker")
if isinstance(picker, dict):
for place in ("", "dialog", "dropdown"):
bucket = picker if place == "" else picker.get(place)
if not isinstance(bucket, dict):
continue
for name in ("searchKeys", "noteKeys"):
keys = bucket.get(name)
if not isinstance(keys, list):
continue
target = merged.setdefault("picker", {})
if place:
target = target.setdefault(place, {})
target[name] = list(dict.fromkeys((target.get(name) or []) + keys))
if routes:
# 分类还没选(或选了没配的那一类)时清单里一条都不成立,回落到字段自己那一份。
base = BASE_WHEN_UNMATCHED.get(key, "first")
if base == "empty":
merged["optionSource"] = "manual"
merged["options"] = []
else:
merged["optionSource"] = routes[0]["source"]
for name in ROUTE_KIND_KEYS.get(routes[0]["source"], []) + ["optionMap"]:
if name in routes[0]:
merged[name] = copy.deepcopy(routes[0][name])
# 与兜底那一份一模一样的一条不用留在清单里:清单不成立时用的就是它,
# 少一条,下一任配表的人少认一条(「项目阶段」四家共用一本字典就是这么收干净的)。
if BASE_WHEN_UNMATCHED.get(key, "first") == "first":
same = [name for name in ROUTE_KIND_KEYS.get(merged.get("optionSource", ""), [])] + ["optionMap"]
routes = [item for item in routes if item["source"] != merged.get("optionSource")
or any(item.get(name) != merged.get(name) for name in same)]
# 一条都不剩就别留这个键:清单空着与没挂清单是同一件事,空数组只会让下一任以为配过
if routes:
merged["optionRoutes"] = routes
if entries:
merged["fetch"] = {"sources": entries}
# 行政 / 定制那两家是「取回来直接落这一格」,落进来的值不在这格的候选里;
# 不勾这一条,页面会把刚带出来的值当越界清掉(见 optionSource.allowOutsideValue)。
merged["allowOutsideValue"] = True
if fills:
merged["autoFill"] = fills
return merged
def mark_outside_value(fields: list[dict]) -> list[str]:
"""被别人的带出写进值的候选格,统一勾上「带回来的值不在候选里也收下」。
收成一家之后这种格子变多了:「项目阶段」原来 VDI 那一格是纯文本,收拢后是 PMS 那一家的
字典下拉,可 VDI 的字典仍旧要把 `extra.stageName` 写进来。那个名字不在 PMS 的阶段清单里,
不勾这一条,提交时就被判「取值已不在可选范围内」(口径见 optionSource.allowOutsideValue)。
"""
written: set[str] = set()
for item in fields:
for rule in item.get("autoFill") or []:
if isinstance(rule, dict) and rule.get("to"):
written.add(str(rule["to"]))
for name in fetch_targets(item):
written.add(name)
marked: list[str] = []
for item in fields:
has_options = bool(item.get("optionRoutes")) or bool(item.get("dictCode")) or bool(item.get("options"))
if item.get("key") in written and has_options and not item.get("allowOutsideValue"):
item["allowOutsideValue"] = True
marked.append(str(item.get("key")))
return marked
def fetch_targets(field: dict) -> list[str]:
"""这一格的取数往哪些格子上写(清单里那几条 + 老的单源写法都算)。"""
cfg = field.get("fetch") or {}
rows = [cfg] if cfg.get("source") else list(cfg.get("sources") or [])
out: list[str] = []
for entry in rows:
if isinstance(entry, dict):
out.extend(str(value) for value in (entry.get("picks") or {}).values())
return out
def shape_deltas(members: list[tuple[dict, str]], merged: dict) -> list[str]:
"""这一组里哪些分类的必填 / 只读跟着变了:必填与只读是字段级的,收成一家就只剩一份。
这是收拢唯一躲不掉的那点妥协。宁可在这里说清楚,也不要等人填单时才发现。
"""
lines: list[str] = []
home = f"{merged['label']}({merged['key']})"
for attr, name in (("required", "必填"), ("readonly", "只读")):
want = bool(merged.get(attr))
moved = [value for member, value in members if bool(member.get(attr)) != want]
if moved:
# 这一份开关收成一家之后只剩一个:跟的是当基准的那一家,其余几家跟着它变
lines.append(f"「{home}」的{name}跟 {members[0][0].get('key')} 那一家走({'有' if want else '没有'}),"
f"{('、'.join(moved))} 这几家{'变成' if want else '不再'}{name}")
return lines
def collapse(fields: list[dict]) -> tuple[list[dict], list[str]]:
"""按 GROUPS 收拢,回(新字段清单,说给人听的几行)。"""
by_key = {str(item.get("key") or ""): item for item in fields}
notes: list[str] = []
taken: set[str] = set()
out: list[dict] = []
for group in GROUPS:
members: list[tuple[dict, str]] = []
for name in group["members"]:
member = by_key.get(name)
if member is None:
notes.append(f"跳过:表上没有「{name}」({group['label']})")
continue
value = driver_value_of(member)
if not value:
raise SystemExit(
f"「{name}」的显示条件不是「{DRIVER} 等于某一个值」这一种,"
"收拢脚本不敢自己猜它对应哪一家,请先在设计器里把条件改回单条等值或人工收这一组"
)
taken.add(name)
members.append((member, value))
if not members:
continue
merged = merged_field(members, group["key"], group["label"], alias_map())
out.append(merged)
homes = "、".join(f"{item.get('key')}={value}" for item, value in members)
notes.append(f"收成「{merged['label']}」({merged['key']}):{homes}")
notes.extend(f" 注意:{line}" for line in shape_deltas(members, merged))
left = [copy.deepcopy(item) for item in fields if str(item.get("key") or "") not in taken]
return reflow(left + out), notes
def reflow(fields: list[dict]) -> list[dict]:
"""把腾出来的空行收掉:还留着格子的行按先后重新编号,别的字段整体上移。"""
used = sorted({int(item.get("row") or 1) for item in fields})
rank = {row: index + 1 for index, row in enumerate(used)}
for item in fields:
item["row"] = rank.get(int(item.get("row") or 1), int(item.get("row") or 1))
return fields
def reflow_layout(layout: dict, dropped: list[str], added: list[dict]) -> dict:
"""移动端那份字段顺序表:删掉收走的,把新格插在第一格原来的位置上。"""
out = copy.deepcopy(layout or {})
mobile = out.get("mobile")
if not isinstance(mobile, dict) or not isinstance(mobile.get("fields"), list):
return out
rows = mobile["fields"]
anchor = next((i for i, item in enumerate(rows) if isinstance(item, dict) and item.get("key") in set(dropped)), None)
kept = [item for item in rows if not (isinstance(item, dict) and item.get("key") in set(dropped))]
if anchor is None:
mobile["fields"] = kept
return out
insert_at = min(anchor, len(kept))
for offset, field in enumerate(added):
kept.insert(insert_at + offset, {"key": field["key"], "style": "row"})
mobile["fields"] = kept
return out
def branch_view(field: dict, data: dict, cache: dicts.DictCache) -> dict:
"""这一格在这一种分类下实际长什么样:问哪一家、候选几条、这一回跑哪几条取数。
回落后读的是字段自己那一份(``option_view`` 已经把两条路合成一份视图了),所以收拢前后
两边走的是同一句问法,比对才不是拿苹果比橘子。
"""
route = dicts.matched_route(field, data) or {}
view = dicts.option_view(field, data)
options = dicts.effective_options(field, data, cache)
cfg = fetch.config_of(field, data)
entries = binding.active_entries(cfg, data) if cfg else []
home = str(route.get("dictCode") or route.get("dataSourceCode") or view.get("dictCode")
or view.get("dataSourceCode") or "")
if not home and not route and str(view.get("optionSource") or "") not in ("", "manual"):
home = str(view.get("optionSource") or "")
return {
"route": home,
"hit": bool(route),
"count": len(options) if options is not None else 0,
"listable": options is not None,
"fetch": [str(item.get("source") or "") for item in entries],
}
def probe_branches(fields: list[dict], driver_values: list[str], cache: dicts.DictCache, db,
target: str) -> list[dict]:
"""按每一种分类挑一个真候选,看带出最后写到哪几格、写的是什么。"""
field = next((item for item in fields if item.get("key") == target), None)
if field is None:
return []
rows = []
for value in driver_values:
data = {item.get("key"): "" for item in fields if item.get("key")}
data[DRIVER] = value
view = branch_view(field, data, cache, db)
picked: dict = {}
problems: list[str] = []
options = dicts.effective_options(field, data, cache)
if options:
item = options[0]
data[target] = dicts.stored_of(field, item)
touched = dicts.apply_auto_fill(fields, data, cache)
picked = {key: data.get(key) for key in touched}
problems = formruntime.selection_problems(fields, {}, data, cache)
elif view["fetch"]:
picked = {"<跑取数>": ",".join(view["fetch"])}
rows.append({"分类": value, "命中": view["route"] or "回落", "候选": view["count"],
"取数": view["fetch"], "带出": picked, "越界": problems})
return rows
def alias_map() -> dict[str, str]:
"""原来那一格 → 收拢后那一格,比对与搬权限都用它。"""
return {name: group["key"] for group in GROUPS for name in group["members"]}
def rep_key(members: list[str], by_key: dict[str, dict]) -> str:
"""一组里挑「当基准的那一格」:能挑候选的优先,跟 merged_field 同一把尺子。"""
live = [name for name in members if name in by_key]
return sorted(live, key=lambda name: KIND_RANK.get(kind_of(by_key[name]), 9))[0] if live else ""
def fold_perms(db, form_id: str, by_key: dict[str, dict], *, write: bool) -> list[str]:
"""环节上那 16 条字段权限折到 4 格:认得出旧名字的搬过去,认不出的报出来。"""
lines: list[str] = []
alias = alias_map()
reps = {group["key"]: rep_key(group["members"], by_key) for group in GROUPS}
processes = db.execute(select(models.Process).where(models.Process.latest_form == form_id)).scalars().all()
for process in processes:
for activity in db.execute(
select(models.Activity).where(models.Activity.process == process.id)
).scalars():
config = activity.config if isinstance(activity.config, dict) else {}
perms = config.get("formPerms")
if not isinstance(perms, dict) or not any(name in perms for name in alias):
continue
kept = {key: value for key, value in perms.items() if key not in alias}
moved = 0
for group in GROUPS:
target = group["key"]
listed = [name for name in group["members"] if name in perms]
moved += len(listed)
if not listed:
continue
# 优先照「当基准的那一格」在这一环的权限把关;它没被列上就退而用这一组里
# 第一个被列上的,宁可少给一点权限,也不把原来读得着的格子放开给人改。
rep = reps.get(target) or ""
kept[target] = perms[rep if rep in listed else listed[0]]
stale = [key for key in kept if key not in by_key and key not in {group["key"] for group in GROUPS}]
lines.append(
f"{process.name} / {activity.name}:搬走 {moved} 条,"
f"这一环从此按 {sorted(group['key'] for group in GROUPS if group['key'] in kept)} 把关"
+ (f";顺带发现 {len(stale)} 条早就指向不存在的字段:{'、'.join(sorted(stale))}" if stale else "")
)
if write:
config["formPerms"] = kept
activity.config = config
if write:
db.flush()
return lines
def fetch_preview(db, cfg: dict, data: dict) -> dict:
"""按这一条取数配置真跑一次(SQL / HTTP 都只读那一头的查询),看落进来的是什么。"""
code = str(cfg.get("source") or "")
row = fetch.get_source(db, code)
if row is None:
return {"source": code, "error": "找不到这个源"}
try:
args = fetch.resolve_args(db, cfg, data)
out = fetch.preview(db, row, args, actor=None)
return {"source": code, "args": args, "value": out.get("value"), "extras": out.get("extras"),
"error": out.get("error") or ""}
except Exception as exc: # noqa: BLE001 演示脚本:把失败摊出来就行
return {"source": code, "error": f"{type(exc).__name__}: {exc}"}
def family_rows(fields: list[dict], value: str, alias: dict[str, str]) -> dict[str, list[dict]]:
"""这一家两边的字段:收拢前是四格(各挂一个分类),收拢后是同样那四格的收成版。
比对只在这一小撮格子上跑:带出去向得落在传进去的字段清单里才算数(``live_target``),
顺带也不会被隔壁家的取数与带出惊动。
"""
merged_keys = set(alias.values())
group_of = {name: group["key"] for group in GROUPS for name in group["members"]}
rows: dict[str, list[dict]] = {"before": [], "after": []}
for item in fields:
name = str(item.get("key") or "")
if name in merged_keys:
rows["after"].append(item)
elif name in group_of and driver_value_of(item) == value:
rows["before"].append(item)
return rows
def run_fetch(db, rows: list[dict], data: dict) -> None:
"""走提交链路里那一条外部取数(SQL 只读那几条),值原地写回 ``data``。
行政 / 定制那两家的名称与编码就是这么落进来的,光看配置说不出它到底取回什么,
所以这里真跑一次:``fetch.apply_form`` 与提交时是同一句。
"""
fetch.apply_form(db, rows, data)
def pick_and_fill(fields: list[dict], data: dict, key: str, cache: dicts.DictCache) -> dict:
"""在这一格里挑一个真候选,回「带出写到哪几格、写的是什么」。"""
field = next((item for item in fields if item.get("key") == key), None)
if field is None:
return {}
options = dicts.effective_options(field, data, cache) or []
if not options:
return {}
# 存哪一列要按「此刻命中的那一条」问,字段自己那一份 optionMap 是另一家的(口径同
# formruntime 判越界那一处:先 option_view 再 stored_of)
data[key] = dicts.stored_of(dicts.option_view(field, data), options[0])
# 别的格子这一趟先按住带出:不按住的话,隔壁家那一格也会拿自己那本字典往空值上带一次,
# 比对口径就不是「这一家带出哪几格」而是「整张表带出哪几格」了。
rows = [{**item, "autoFill": []} if item.get("key") != key else item for item in fields]
touched = dicts.apply_auto_fill(rows, data, cache)
return {str(name): data.get(name) for name in touched}
def describe(key: str, view: dict, fills: dict) -> str:
home = view["route"] or ("取数 " + ",".join(view["fetch"]) if view["fetch"] else "没候选")
hits = "换成这一家" if view["hit"] else "回落字段本身"
return f"{key}|问 {home}({hits})|候选 {view['count']} 条|带出 {sorted(fills) or '无'}"
def main() -> int:
parser = argparse.ArgumentParser()
parser.add_argument("--form", default="出差备案申请", help="表单名或 id,默认「出差备案申请」")
parser.add_argument("--write", action="store_true", help="存成新的表单版本(默认只算不改)")
parser.add_argument("--perms", action="store_true", help="连带把环节上的字段权限折到收拢后那几格")
parser.add_argument("--json", default="", help="把收拢后的 content 写到这个文件")
args = parser.parse_args()
with SessionLocal() as db:
row = load_form(db, args.form)
content = copy.deepcopy(row.content if isinstance(row.content, dict) else json.loads(row.content))
fields = content.get("fields") or []
by_key = {str(item.get("key") or ""): item for item in fields}
cache = dicts.DictCache(db)
values = [str(item.get("value") or "") for item in (cache.items(DRIVER) or [])]
alias = alias_map()
merged_keys = [group["key"] for group in GROUPS]
print(f"表单:{row.name} v{row.version}({row.id})|现字段 {len(fields)} 格"
f"|{DRIVER} 的取值:{'、'.join(values)}")
new_fields, notes = collapse(fields)
for line in notes:
print(" ·", line)
marked = mark_outside_value(new_fields)
print(f"字段数:{len(fields)} → {len(new_fields)}")
if marked:
print(" · 这些格子会被别人的带出写值,勾上「带回来的值不在候选里也收下」:", "、".join(marked))
merged_by_key = {str(item.get("key")): item for item in new_fields}
print("\n== 逐家比对:同一种分类,收拢前后各跑一遍候选 + 带出 + 外部取数")
bad = 0
for value in values:
before = family_rows(fields, value, alias)["before"]
after = family_rows(new_fields, value, alias)["after"]
present = {str(item.get("key") or "") for item in before}
old_key = next((name for name in GROUPS[0]["members"] if name in present), "")
if not old_key:
print(f"{value}:表上没有这一家,跳过")
continue
old_data = {str(item.get("key")): "" for item in before}
new_data = {str(item.get("key")): "" for item in after}
old_data[DRIVER] = new_data[DRIVER] = value
old_field, new_field = by_key[old_key], merged_by_key[GROUPS[0]["key"]]
old_view, new_view = branch_view(old_field, old_data, cache), branch_view(new_field, new_data, cache)
old_fill = pick_and_fill(before, old_data, old_key, cache)
new_fill = pick_and_fill(after, new_data, GROUPS[0]["key"], cache)
run_fetch(db, before, old_data)
run_fetch(db, after, new_data)
# 只比字段上的值:`_fetch` 那份留痕记的是「哪一格什么时候取过数」,键名跟着
# 字段名走,本来就该不一样,比它只会一直报「要人看」
def settled(source: dict) -> dict:
return {str(key): val for key, val in source.items()
if key not in (DRIVER, fetch.TRACE_KEY) and val not in ("", None)}
got_old = {alias.get(key, key): val for key, val in settled(old_data).items()}
got_new = settled(new_data)
same_home = (old_view["route"], old_view["count"], old_view["fetch"]) == \
(new_view["route"], new_view["count"], new_view["fetch"])
same_write = got_old == got_new
bad += 0 if (same_home and same_write) else 1
print(f"{value}:{'一致' if same_home and same_write else '要人看'}")
print(" 收拢前", describe(old_key, old_view, {alias.get(k, k): v for k, v in old_fill.items()}))
print(" 收拢后", describe(GROUPS[0]["key"], new_view, new_fill))
for name in sorted(set(got_old) | set(got_new)):
flag = "同一份" if got_old.get(name) == got_new.get(name) else "对不上"
print(f" {name}: 前 {got_old.get(name)!r} / 后 {got_new.get(name)!r} {flag}")
problems = formruntime.selection_problems(after, {}, new_data, cache)
if problems:
print(" 越界/校验:", problems)
bad += 1
added = [merged_by_key[name] for name in merged_keys if name in merged_by_key]
new_content = {"fields": new_fields,
"layout": reflow_layout(content.get("layout") or {}, sorted(alias), added)}
from app.api import design # noqa: PLC0415 只要那两个清洗函数与设计期校验
washed = design.clean_option_source(design.clean_formats(new_content))
problems = design.form_problems(washed, db)
print("\n== 按设计器保存那一条路口径校验:", "通过" if not problems else problems)
keys = {str(item.get("key") or "") for item in new_fields}
for item in new_fields:
extra = formruntime.option_source_problems(item, db=db, rows=new_fields, keys=keys)
if extra:
print(f" 「{item.get('label')}」设计期还要说:", extra)
if args.json:
Path(args.json).write_text(json.dumps(washed, ensure_ascii=False, indent=1), encoding="utf-8")
print(f"收拢后的 content 写到 {args.json}")
for line in fold_perms(db, row.id, by_key, write=args.write):
print("环节权限:", line)
if not args.write:
print("\n没动库。对着 --json 那一份确认过,再加 --write 存成新版本(环节权限加 --perms)")
return 0
if problems:
raise SystemExit("校验没过,不落库")
backup = Path(f"/tmp/form-{row.id}-v{row.version}.json")
backup.write_text(json.dumps(content, ensure_ascii=False, indent=1), encoding="utf-8")
row.content = washed
row.version = (row.version or 1) + 1
db.commit()
print(f"已存成 v{row.version};改之前那一份在 {backup}")
print(f"比对结果:{len(values) - bad} 家一致,{bad} 家要人看")
return 0
if __name__ == "__main__":
raise SystemExit(main())

File diff suppressed because it is too large Load Diff

View File

@ -0,0 +1,276 @@
#!/usr/bin/env python3
"""测试环境专用:把流程审批环节的审批人统一改成一个来源(默认发起人)。
生产配的是真岗位角色、部门主管、指定人,测试库里那些人往往一个都不在——单据发到
「财务经理」就挂在没人认领的待办上。这一条把审批环节的审批人整体换成发起人本人
(``taskValues = [{"type": "creator", "data": []}]``,与设计器保存的形状一字不差),
自己发自己审,一条流程点到底。
改的是设计数据(``oa_activity.config``),只动 ``type=manual`` 的审批环节**顶层**那一份
``taskValues``:抄送规则 ``ccRules`` 里同名的 ``taskValues`` 说的是抄送给谁,不算审批人,
不碰;环节上的表单权限、退回配置、外部审批接口、空审批人兜底一概原样。
**顺带必须处理的开关**:审批人换成发起人之后,"同一个审批人自动放行"那几档会把这些
环节悄悄吃掉,改了等于没改——
* ``skipStarter``(环节级与流程级):发起人自己不重复审批;
* ``dedup``:同一审批人前面批过就自动通过;
* ``dedupAhead``:同一审批人后面还要批时跳过前面这一环。
默认把它们关掉,让每个环节都真的停在发起人手上。想让流程一路自动跑到底就别关:
加 ``--keep-auto-pass``。
在途单据不受影响:发起那一刻设计已经冻结在 ``oa_process_snapshot`` 上,走的还是老配置。
要退回生产原来的审批人配置,直接重跑 ``migrate_design.py --apply``(它以生产为准)。
python3 scripts/set_approvers.py # 干跑:列每个环节要改成什么
python3 scripts/set_approvers.py --apply # 真改(默认测试档 dev)
python3 scripts/set_approvers.py --process 印章 # 只改名字带「印章」的流程
python3 scripts/set_approvers.py --keep-auto-pass # 只换审批人,不动自动放行开关
python3 scripts/set_approvers.py --kind role --value 财务经理 # 换成别的口径
python3 scripts/set_approvers.py --restore ../backups/approvers-XXXX.json.gz
"""
from __future__ import annotations
import argparse
import gzip
import json
import sys
from datetime import datetime
from pathlib import Path
from typing import Any
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from sqlalchemy import update # noqa: E402
from sqlalchemy.orm import sessionmaker # noqa: E402
import migrate_design as md # noqa: E402 同一套连库 / 备份 / 清缓存 / 校验口径
TABLES = md.TABLES
BACKUP_DIR = md.BACKUP_DIR
#: 只有这种环节是"审批环节"(会发待办);begin / end / choice / script 不算
APPROVAL_NODE = "manual"
#: 审批人来源的中文名,报告里要说清楚这一格从哪儿取人
KIND_LABELS = {
"creator": "发起人",
"person": "指定人",
"role": "岗位角色",
"post": "岗位角色",
"unit": "部门",
"group": "分组",
"identity": "身份",
"form": "按表单字段取值",
"prev": "上一环节处理人",
"prevunit": "上一环节处理人所在部门",
"prevLeader": "上一环节处理人的上级",
"prevUnitManager": "上一环节处理人所在部门负责人",
"creatorLeader": "发起人的上级",
"creatorLeaderChain": "发起人的多级上级",
"creatorTeamLeader": "发起人的科室负责人",
"creatorUnitManager": "发起人所在部门负责人",
"creatorParentUnitManager": "发起人上级部门负责人",
"unitManager": "指定部门负责人",
}
#: 会把这些环节悄悄放行的开关:环节级 skipStarter,流程级这三项
FLOW_AUTO_PASS = ("skipStarter", "dedup", "dedupAhead")
def describe(rows: Any) -> str:
"""把一份 ``taskValues`` 说成人话:``岗位角色「财务经理」+ 发起人所在部门负责人``。"""
parts: list[str] = []
for row in rows or []:
if not isinstance(row, dict):
parts.append(str(row))
continue
kind = str(row.get("type") or "")
label = KIND_LABELS.get(kind, kind or "未配置")
data = [str(item) for item in (row.get("data") or []) if str(item)]
parts.append(f"{label}「{'、'.join(data)}」" if data else label)
return " + ".join(parts) or "(空)"
class Plan:
def __init__(self) -> None:
#: 环节 id -> (环节行, 新 config, 说明)
self.nodes: dict[str, tuple[dict, dict, list[str]]] = {}
#: 流程 id -> (流程行, 新 approval_config, 说明)
self.flows: dict[str, tuple[dict, dict, list[str]]] = {}
@property
def touched_processes(self) -> list[str]:
ids = {row["process"] for row, _, _ in self.nodes.values()}
return sorted(ids | set(self.flows))
def build_plan(scope: dict, kind: str, values: list[str], clear_auto_pass: bool) -> Plan:
"""按「审批人 = 某个来源」算出每个审批环节要改成什么样。"""
plan = Plan()
wanted = [{"type": kind, "data": [str(item) for item in values]}]
for row in scope["activities"].values():
if row["type"] != APPROVAL_NODE or row["process"] not in scope["processes"]:
continue
config = dict(row.get("config") or {})
notes: list[str] = []
before, after = describe(config.get("taskValues")), describe(wanted)
if before != after:
config["taskValues"] = [dict(item) for item in wanted]
notes.append(f"审批人 {before} → {after}")
if clear_auto_pass and config.get("skipStarter"):
config["skipStarter"] = False
notes.append("关掉「发起人自己不再审批」(不然这一环直接自动过)")
if notes:
plan.nodes[row["id"]] = (row, config, notes)
if not clear_auto_pass:
return plan
for pid, process in scope["processes"].items():
approval = dict(process.get("approval_config") or {})
notes: list[str] = []
for key in FLOW_AUTO_PASS:
value = approval.get(key)
if key == "skipStarter":
if value:
approval[key] = False
notes.append("「发起人自己不重复审批」关掉")
elif value and str(value) != "none":
approval[key] = "none"
label = "同一审批人前面批过就自动通过" if key == "dedup" else "同一审批人后面还要批时跳过前面这一环"
notes.append(f"「{label}」{value} → none")
if notes:
plan.flows[pid] = (process, approval, notes)
return plan
def report(plan: Plan, scope: dict, conf: dict, kind: str) -> None:
print(f"目标库(写) {md.label(conf)}")
print(f"审批人来源 {KIND_LABELS.get(kind, kind)}\n")
if not plan.nodes and not plan.flows:
print("所有审批环节已经是这个口径了,一行都不用改。")
return
for pid, process in sorted(scope["processes"].items(), key=lambda item: str(item[1]["name"])):
nodes = [item for item in plan.nodes.values() if item[0]["process"] == pid]
flow = plan.flows.get(pid)
if not nodes and not flow:
continue
total = sum(1 for row in scope["activities"].values()
if row["process"] == pid and row["type"] == APPROVAL_NODE)
print(f"\n{process['name']}(审批环节 {total} 个,这一趟动 {len(nodes)} 个)")
for row, _, notes in sorted(nodes, key=lambda item: item[0]["order_number"]):
print(f" - {row['name']}:" + ";".join(notes))
if flow:
print(" · 流程级:" + ";".join(flow[2]))
print(f"\n合计:审批环节 {len(plan.nodes)} 个、流程 {len(plan.flows)} 条要写")
def apply_plan(plan: Plan, profile: str) -> Path:
"""备份原值 + 一个事务写完。"""
engine = md.connect(md.db_conf(profile))
session = sessionmaker(bind=engine)()
path = BACKUP_DIR / f"approvers-{datetime.now().strftime('%Y%m%d-%H%M%S')}.json.gz"
payload = {
"written_at": datetime.now().isoformat(timespec="seconds"),
"profile": profile,
"note": "set_approvers.py 改动前的原值;--restore 按这个退回",
"nodes": {aid: row.get("config") or {} for aid, (row, _, _) in plan.nodes.items()},
"flows": {pid: row.get("approval_config") or {} for pid, (row, _, _) in plan.flows.items()},
}
path.parent.mkdir(parents=True, exist_ok=True)
with gzip.open(path, "wt", encoding="utf-8") as handle:
json.dump(payload, handle, ensure_ascii=False)
try:
table = TABLES["oa_activity"]
for aid, (_, config, _) in plan.nodes.items():
session.execute(update(table).where(table.c.id == aid).values(config=config))
table = TABLES["oa_process"]
for pid, (_, approval, _) in plan.flows.items():
session.execute(update(table).where(table.c.id == pid).values(approval_config=approval))
session.commit()
except Exception:
session.rollback()
raise
finally:
session.close()
return path
def restore(path: Path, profile: str) -> None:
"""把审批人与自动放行开关退回备份那一刻。"""
with gzip.open(path, "rt", encoding="utf-8") as handle:
payload = json.load(handle)
conf = md.db_conf(profile)
engine = md.connect(conf)
md.probe(engine, conf)
session = sessionmaker(bind=engine)()
try:
table = TABLES["oa_activity"]
for aid, config in (payload.get("nodes") or {}).items():
session.execute(update(table).where(table.c.id == aid).values(config=config))
table = TABLES["oa_process"]
for pid, approval in (payload.get("flows") or {}).items():
session.execute(update(table).where(table.c.id == pid).values(approval_config=approval))
session.commit()
except Exception:
session.rollback()
raise
finally:
session.close()
print(f"已按 {path.name} 退回:审批环节 {len(payload.get('nodes') or {})} 个、"
f"流程 {len(payload.get('flows') or {})} 条({md.label(conf)})")
def main(argv: list[str]) -> int:
parser = argparse.ArgumentParser(description="批量设置测试环境流程审批环节的审批人")
parser.add_argument("--profile", default="dev", help="改哪一档的库,默认 dev(测试档)")
parser.add_argument("--kind", default="creator", help="审批人来源,默认 creator(发起人)")
parser.add_argument("--value", action="append", default=[],
help="来源取值,role / unit / person / group / form 才需要;可重复")
parser.add_argument("--process", nargs="*", default=[], help="只改名字里带这些词的流程")
parser.add_argument("--keep-auto-pass", action="store_true",
help="只换审批人,不动 skipStarter / dedup(这些环节会被自动放行)")
parser.add_argument("--restore", metavar="备份文件", help="按备份退回改动前")
parser.add_argument("--apply", action="store_true", help="真写;默认只干跑")
args = parser.parse_args(argv)
if args.restore:
restore(Path(args.restore), args.profile)
return 0
need_value = {"role": "岗位角色名", "unit": "部门名", "group": "分组名",
"person": "登录账号", "form": "表单字段 key"}
if args.kind in need_value and not args.value:
raise SystemExit(f"--kind {args.kind} 要用 --value 给出{need_value[args.kind]}")
conf = md.db_conf(args.profile)
engine = md.connect(conf)
md.probe(engine, conf)
processes = {row["id"]: row for row in md.fetch(engine, "oa_process")
if not args.process or any(word in str(row["name"]) for word in args.process)}
if not processes:
print("--process 一个流程都没圈到,先别写了")
return 1
scope = {"processes": processes, "activities": md.by_key(md.fetch(engine, "oa_activity"), "id")}
plan = build_plan(scope, args.kind, args.value, not args.keep_auto_pass)
report(plan, scope, conf, args.kind)
if not args.apply:
print(f"\n干跑结束:{len(plan.nodes) + len(plan.flows)} 行待写。加 --apply 落地(写之前先备份)。")
return 0
if not plan.nodes and not plan.flows:
return 0
path = apply_plan(plan, args.profile)
print(f"\n已写入 {md.label(conf)},原值备份在 {path.relative_to(md.BACKEND.parent)}")
print(f" 要退回:python3 scripts/set_approvers.py --profile {args.profile} --restore {path}")
print(md.invalidate_cache(engine, args.profile, plan.touched_processes))
issues = md.verify(engine, plan.touched_processes)
print("设计器校验:" + ("全部通过" if not issues else f"{len(issues)} 条问题"))
for line in issues[:10]:
print(f" ! {line}")
return 0
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))

View File

@ -12,8 +12,8 @@ MinIO / 统一身份那套真值都在镜像里,**集群里一份配置都不
| --- | --- |
| 仓库 | `docker.oa.unissense.tech/public/unis_oa`(Harbor,`public` 项目,匿名可拉) |
| 架构 | `linux/amd64` |
| tag | 时间戳(当前 `202611091649`)+ `latest` |
| 大小 | 压缩后约 96 MB |
| tag | 时间戳(当前 `202611121636`,digest `sha256:b7e6528e…`)+ `latest` |
| 大小 | 压缩后约 97 MB |
| 端口 | `8000`(后端 API 与前端静态页同源,一个容器全包) |
| 配置 | 自带 `config.toml` + `config.prod.toml`(含密钥),不挂配置也能起 |

View File

@ -152,6 +152,337 @@ spec:
containers:
- name: unis-oa
# 钉时间戳 tag:回滚才有得选。想用 latest 就把下面 imagePullPolicy 改成 Always
# 202611121636 起(已推 Harbor,digest sha256:b7e6528e…,linux/amd64,tag 与 latest 同一份):
# 上一版推出之后工作区还剩一处没进镜像,这一版补上:`scripts/collapse_trip_form.py` 比对
# 收拢前后的取值时,先把 `fetch.apply_form` 顺手写下的 `_fetch` 那份留痕剥掉再比——它记的是
# 「哪一格什么时候取过数」,键名跟着实现走,本来就不属于要相等的内容,留着比会多报几条
# 「不一致」的假差异。运行时一字未改,跑在容器里的那条验收脚本从此与仓库里那份同一版。
# 上一段(202611121629)说的那份内容仍然算数,这一份 = 它 + 这一处脚本修补。
# 202611121629 起(已推 Harbor,digest sha256:a0d35b4c…,linux/amd64,tag 与 latest 同一份):
# 接着上一版那张真表单,把「收拢」开进设计器:**多选那几格同一个字段的几家,属性栏给一颗
# 「并成一格」**。认的是「每一格都只挂一条『某字段等于某一个值』的显示条件、指的是同一个
# 字段、取值互不重复」那一批格子(生产那张单上就是 4 组 × 4 家);凑不齐这颗按钮根本不出现,
# 比灰着一排没人看得懂的按钮好读。判据一条没新增,写出来、存下去的还是 `optionRoutes[].when`
# / `fetch.sources[].when` / `autoFill` / `fetch.picks` 那几份本来就要存的东西
# (`utils/formMerge.ts` 写配置,`FormDesignerView.vue:mergeSelection` 只动画布)。三条分寸:
# ① **留内容最多的那一格**(有字典的优先,只读取数格垫底),名字与标题都用它的——导出列、
# 报表、对外回写读的都是字段名,留一个比换一个新名字少坏一片;要中性名字并完再改名,
# `utils/formRename` 会把指着它的带出一起搬走。② **先搬落点再删格子**:`fetch.picks` 与
# `autoFill[].to` 记的都是别的格子的名字,趁那几格还在表上搬才不会漏,漏一处就是
# 「候选换了家、带出还写着上一个名字」;搬完去掉因此重复的那条带出,删完再走一遍
# `formPrune` 清掉没有归宿的。③ **带回来的值要收得下**:往别的格子写值的那几处落点也改了名,
# 那些格子自己有候选时当场替它们勾上「带出的值不在候选里也收下」,不等保存那一刻报错。
# 点完说实话报一句:清单里几家 / 取数条目几条 / 跟着搬的带出几处 / 删掉几格,外加
# 「哪几家的必填与只读跟着留下来的那一格变了」——并格躲不掉的就是这一句,不满意用撤销。
# 新增键 0 枚、零 DDL、运行时一字未改。发布前闸:`vue-tsc --noEmit` 过;全量 `vitest run`
# 184 files / 1962 tests 全绿(新增 `formMerge.spec.ts` 9 例 + `FieldInspector.merge.spec.ts`
# 3 例,含「并不齐就不摆按钮」与「指着旧名字的带出一处不落」);eslint 干净;上一版那道
# 「挂了清单就不要求字段自己抄一份选项」的闸仍在(`check_option_routes` 两条断言)。
# ⚠️ 还是整份工作区打的:这一版动 4 个前端文件(2 改 + 2 份用例)+ 3 份文档与这份清单;
# 16:17 之后工作区没有别的会话改动,这一份 = 202611121617 + 并成一格。
# 202611121617 起(已推 Harbor,digest sha256:58314043…,linux/amd64,tag 与 latest 同一份):
# 用户把话挑明了:「你可以看看生产环境的出差备案申请测试流程,里面有很多字段其实都是一样的,
# 只是数据来源不一样。就是为了满足这个需求减少相同字段。」——这一版拿那张真表单当验收题:
# 27 格里 16 格是四家同构字段(项目名称 / 项目编码 / 最终客户名称 / 项目阶段 × PMS / VDI /
# 行政 / 定制),全靠显示条件互相藏,换来的是三个字段名家族、四套环节权限、一堆早就指向
# 不存在的字段的权限条目(`开始` 那一环 11 条)。收拢后是 4 格。
# ① **一处真拦路的口径改了**:挂了 `optionRoutes` 的那一格不再被「选项类字段未配置任何选项」
# 挡住保存(`api/design.py:form_problems` ↔ `utils/formLayout.ts:validateFields` 两边同一句)。
# 收拢出来的那一格常常**故意**把自己那一份留空——「先选项目分类,再问那一家要候选」,
# 分类没选的那一刻本来就没得挑;什么都没配的照旧拦,老规矩没被一起放宽。新增键 0 枚、零 DDL。
# ② **`scripts/collapse_trip_form.py`**:照表上真实的字段把那 16 格算成 4 格(条件从各格的
# 显示条件里读、来源与带出从各格自己身上读、`picks` 与 `autoFill.to` 那些指着旧名字的落点
# 一起搬到收拢后的名字上),再拿运行时那同一套判据逐家比对——问哪一家、候选几条、这一回跑
# 哪几条取数、带出写到哪几格、写进来的是不是同一个值(外部取数真跑一次),最后按设计器保存
# 那一条路(clean + `form_problems`)检一遍才让落库。默认一个字都不改,`--write` 落库、
# `--perms` 顺带把环节上那 16 条权限折到 4 格(搬得走的搬走,剩下的报出来)。生产库上实跑:
# PMS 247 条 / VDI 2473 条候选一字不差,`project_code` 带回来的值两边同一个,行政 / 定制
# 两家两边都不落值,**四家全「一致」**;必填与只读只剩一份这类躲不掉的妥协当场说出来
# (哪几家变成必填、哪几家不再只读)。
# ③ 顺手量到生产一个真问题:`xz_code` / `Code_dz` 那两条 SQL 比的是字典的**名称**
# (`case when :project_type = '行政综合X项目'`),而表单存的是**编码** `XZZH` / `DZKFXM`,
# 所以这两家的项目名称与编码在生产上一直是空的——收拢前后一样空,不是这一版弄坏的,
# 记在 docs/option-source-routing-design.md §12,改 SQL 比编码、或改成同步字典,都能治。
# 发布前闸:`vue-tsc --noEmit` 过;`vitest run` 182 files / 1950 tests 全绿(新增
# `formLayout.routed-options.spec.ts` 3 例);`check_option_routes`(多了那道闸的两条断言)/
# `check_option_route_fill`(50) / `check_binding` / `check_selector_kinds`(46) /
# `check_dict_manual`(37) / `check_form_change_noise`(18) / `check_row_fetch`(34) /
# `check_hidden_field_rules`(33) / `check_fetch_freeze`(20) / `check_design_pin`(57) /
# `check_globals` / `check_k8s_manifest` 各自全绿;镜像里已核对 `app/api/design.py` 带着
# 那句 `not dicts.routes_of(item)`、`scripts/collapse_trip_form.py` 在位。
# ⚠️ 还是**整份工作区**打的:本线程这一版动 2 个代码文件 + 1 份新自检脚本 + 4 份文档与这份清单,
# 同一工作区里别的会话(手机端审批那一屏、`app/api/runtime.py` 那几份)也一起进了镜像。
# 202611121557 起(已推 Harbor,digest sha256:cd0d9195…,linux/amd64,tag 与 latest 同一份):
# 用户那句「你设计的有点复杂,帮我优化一下这一格怎么配」对着的是**配表单那三双手**,
# 不是运行时那一套判据——判据一个字没改(存的还是 `optionRoutes` / `when` / `fill` /
# `autoFill` 那几份),只把重复的手势与藏起来的地方收掉。本线程这一版动 6 个前端文件
# (`OptionRoutesEditor` / `OptionSourcePanel` / `FieldInspector` / `LinkagePanel` + 两份
# 语言包)+ 3 份用例(新增 2 份),也带着 1549 那一版(别的会话:手机端审批那一屏)。
# ① 「**一家一档**」:候选来源那一栏下面挑一格(只给当下数得出取值的那几格——手填那几条,
# 或一本数据字典),它有 N 个取值就一次铺出 N 张卡片,`when` 当场替写、备注替写成那一档的
# 人话。以前「按项目分类换一家」要开四次条件弹窗逐个拼,拼错一个取值=那一家候选永远不出现,
# 是最难查的一种配歪。重复点不生出重复那几条;只铺剩得下的名额并说清楚;取值比一格能挂的
# 8 家还多的那一格直接判「该在对面做一个聚合接口」,不硬铺。字典那一本现问、问过就留着。
# ② 「**把这一家的带出套给其余几家**」:带出去向与现场补的那几列照抄,「另问一家」只在这一条
# 本来就没跟着自己那一家时才照抄(否则各家问各家那一家),入参各家沿用各家筛候选那一份——
# 与手工改走的是同一句 `fillForRoute`,两条路不会写歪成两份。
# ③ 字典那一张卡片给一颗「这一家的带出去『字典带出』里配」:点了把「联动」那扇门打开、那一块
# 描一圈再收回(`revealAutoFill` 一串是便利,不是新的一层判据;不收回的话过几分钟他自己点开
# 那一栏又被描一遍)。以前只有一句说明,得人在侧栏里自己找。
# 配的人从此只记三步:挑一格「一家一档」→ 逐条挑各家的字典 / 数据源 → 带出去向(外部那几家
# 套一下,字典那几家跳过去配一份)。说明书把这三步、以及「生产那张出差单四家都做成同步字典
# 最省事(`fetch.sources[].when` 与 `allowOutsideValue` 都不用上)」写进了
# docs/option-source-routing-design.md §8。新增键 0 枚、零 DDL。
# 发布前闸:镜像内 `vue-tsc --noEmit` 过;`vitest run` 181 files / 1947 tests 全绿
# (这一轮 +2 文件 / +21 例,含整条跳转链路的挂载级用例);`check_option_routes` /
# `check_option_route_fill`(50) / `check_binding` / `check_selector_kinds`(46) /
# `check_dict_manual`(37) / `check_form_change_noise`(18) 各自全绿。
# 202611121549 起(已推 Harbor,digest sha256:6c2eb5d4…,linux/amd64,tag 与 latest 同一份):
# ⚠️ 还是**整份工作区**打的:这一版本线程动了 13 个代码文件(后端 1 + 前端 12,其中 3 份
# 自检用例),另有 2 份文档与这份清单;同一工作区里别的会话那一头也一起进了镜像。
# 这一版是把「手机端审批那一屏跟当下配置」这句话真正做实——上线后用户回话「现在为什么
# 手机端在途的表单为什么还是展示的不一样呢?不是跟我配置的展示呢」,拿生产上那十张在途
# 报销单逐个对,两处真没跟到:① **环节压根没绑表单**——`activity_nodes[环节].form` 是空串,
# 页面回落到 `forms[0]`,而上一版是拿这个空串去 `forms_live` 里查,永远查不到,于是手机上
# 静默退回冻住的那一张(35 格,此刻那张表配的是 38 格);认 id 那三步(环节 → 待办 → 兜底)
# 从前散在三处,现在收成 `utils/mobileLayout.ts:mobileFormRead()` 一处,一次交出
# `{ frozen, mobile }`。② **露哪几格还有一半写在流程设计器「环节 → 字段权限」那一格**,
# 它冻在 `activity_nodes[].form_perms` 里(管理员把 `checkTotal` 那几个审定格从「隐藏」改成
# 「只读」,手机上照旧不露,因为那张单冻的还是「隐藏」)。后端因此多回一份
# `activity_perms_live`(`runtime._perms_live`,只回与冻结那一版不一样的环节,没人动过就是
# `{}`,报文与改动前逐字节一致),前端 `mobileFieldPerms` 读它,只喂手机端那一屏的
# `displayPerms`——填写块、必填、提交校验、桌面详情、打印、导出、引擎认值仍旧读冻住那一份。
# 生产上的对照:执行董事那张 11 格→22 格、部门主管 9→17、财务总监 25→20(字段权限那份
# 本来没改,只随表单内容与显示条件走)。唯一还压着这一屏的是「显示条件」(`visibleWhen`,
# 读这张单此刻存着的值),口径见 `docs/mobile-approval-layout.md` §4.5。
# 新增只读报文键 1 枚(`activity_perms_live`),零 DDL。发布前闸:镜像内 `vue-tsc --noEmit`
# 过、`vite build` 过、全量 `vitest run` 179 files / 1933 tests 全绿(这一轮新增 12 条,含
# 生产上那个空 `form` 回落那条)、`check_design_pin.py` 57 条全绿(第 3c 组盯环节字段权限
# 那一份)、`check_globals.py` 与 eslint 干净;镜像里已核对 `app/api/runtime.py` 与
# `web/dist/assets/TaskDetailView-*.js` 都带着 `activity_perms_live`,手机上问候语下面那串
# 应为 202611121549。
# 202611121508 起(已推 Harbor,digest sha256:10ce8038…,linux/amd64,tag 与 latest 同一份):
# ⚠️ 还是**整份工作区**打的:这一版本线程动了 14 个代码文件(8 改 + 6 份自检用例,另有
# 3 份文档与这份清单),同一个工作区里另一个会话那一头(`app/api/runtime.py` 与手机「在办 /
# 单据」那几屏:`MobileTaskView` / `taskContext` / `WorkDetailView` / `TaskDetailView` /
# `ProcessDesignerView` / `types`,加 `docs/mobile-approval-layout.md`)也一起进了镜像。
# 这一版修的是 1422 留的那个洞:**候选路由里躺着数据字典时,那一头的带出配不出来**。
# 用户那句「我一个下拉选择配了两个来源,一个外部数据源一个数据字典,选了值怎么带出其余字段」
# 其实有两半:外部那半走 `optionRoutes[].fill`(1422 已上线),字典那半走 `autoFill`——
# 而字典只挂在路由上时三处一起失灵:① 设计器「联动」面板那一栏 `v-if="field.dictCode"`
# 只认字段上那本字典,整栏不出现,压根没地方配;② 从接口直传写进来的 `autoFill`,保存那一刻
# 被 `clean_option_source` 当上一家的残骸 pop 掉(它只看字段自己声明的那一种来源);
# ③ 界面带出读的是字段上那份 `dictCode`,不跟命中那一条——症状是「界面带 A 本的附加值、
# 提交带 B 本的」。四处改:`dicts.dict_route_codes` ↔ `optionSource.dictRouteCodesOf`
# (路由里那几条字典来源各挂的是哪一本,自上而下、去重);`clean_option_source` 在字段自己
# 声明的不是字典、但路由里挂着字典时把 `autoFill` 算进"属于这一格的那几格",不再洗;
# `apply_auto_fill` ↔ `applyAutoFill` 逐字段先摊视图再读 `dictCode`,**命中哪一本带那一本的
# 附加值,命中的那一条不是字典时一个字都不带**(少了这道闸,"没有字典就把这一格自己的值
# 搬过去"那条兜底会把人刚挑中的编码盖到"名称"那一格上,对面前端 items 为空本来也不写);
# `LinkagePanel` 那一栏改用「字段上那本 + 路由里那几本」的并集,可选的附加值列也是并集
# (命中哪本取哪本,但一栏里得看全)。两处都没字典才洗掉并说一句(两边一字不差):
# 「配了字典带出,可这一格没挂数据字典(字段上与候选来源那几条里都没有),这一档不起作用」。
# 同一寸还修了一处设计期误判(生产上「出差备案申请」那张单当场中招):「这一格的值是不是
# 系统写进来的」以前判的是「这一格配没配带出」。于是① 配了 `autoFill` 写**别的**格子那一格
# (就是「项目名称」那种)反被提醒「这一格的值由字典带出写入,候选又来自数据字典……提交会
# 被判越界」——人挑的那一格被说成系统写的,生产那张单上就有两条;② 反过来,值是**隔壁那一格**
# 带进来的下拉(「项目阶段」靠「项目名称」喂值)被说成「这一档暂时不起作用」,人把「带出的值
# 不在候选里也收下」去掉,提交那一刻真被判越界。现在判的是**落点在不在这一格上**:`fetch` 只认
# 条目自带的 `pick`(取一个值写进它自己那一格)与点到这一格的 `picks`,候选路由那条 `fill` 是
# fillOnly、永远不写自己;同表字段清单会递进设计期检查(`rows` / `ctx.peers`),隔壁的
# `autoFill[].to`、`linkFill.rules[].to`、取数 `picks` 指着这一格一样算,明细列那种 `表.列`
# 的写法不算。两边同一份判据(`formruntime._fetch_targets` `_fetch_writes` `_rule_hits_self`
# `filled_by_other` ↔ `optionSource.fetchTargets` `fetchWrites` `rulesHitSelf` `filledByOther`),
# 少一道闸就是「一张表单里只要有一格配了取数,所有下拉都说值是取来的」——那句闸也钉进了脚本。
# 新增键 0 枚、库结构零 DDL(`backend/app/models.py` 与 `sql/schema.sql` 与 1422 一字不差)。
# 发布前闸:镜像内 `vue-tsc --noEmit` 过;全量单测 `vitest run` 179 files / 1926 tests 全绿;
# `check_option_routes.py` 全绿(这一轮新增 22 句:清洗保住 `autoFill`、命中非字典那条一个字
# 不写、`dict_route_codes` 去重、那句新措辞、落点判据那六种形状,外加「隔壁的取数写它自己那一格
# 不算指着这一格」与把「带出先摊视图」「两份落点判据都在」钉进源码的对账),
# `check_option_route_fill`(50) / `check_binding` / `check_row_fetch`(34) / `check_dict_manual`(37) /
# `check_selector_kinds`(46) / `check_hidden_field_rules`(33) / `check_self_visible` /
# `check_fetch_freeze`(20) / `check_form_change_noise`(18) 各自全绿。
# 202611121422 起(已推 Harbor,digest sha256:14f4486a…,linux/amd64,tag 与 latest 同一份):
# 202611121226 之后动过的 19 个代码文件(15 改 + 4 新增,另有两份文档与这份清单)
# 都在这一版里,一条主线,还是那一格候选来源:**命中那一家把它那几列带进别的格子**
# (用户那句追问:「我配置了多个外部数据源,该如何设置带出的值填入对应的字段」)。
# `optionRoutes[].fill`(口径 docs/option-source-routing-design.md §5):那一条候选自带
# 一份带出——问哪一家 / 带什么入参 / 源上哪几个键写进哪几格。为什么不在 `fetch.sources`
# 里再写一条带 `when` 的条目:判据得抄两遍,抄漏一处就是「候选换了家、带出还是上一家的」,
# 界面按 A 家出候选、提交的值来自 B 家主数据。运行时它被**摊成一条普通的取数条目**丢给
# 同一个执行器(`fetch.fill_config` ↔ `formFetch.routeFetchConfig`:同一个入参写法、同一份
# 留痕、同一档 `onError` 与发起后冻结,都不新发明),只多一个 `fillOnly` 记号:**只写
# 「带出去向」那几格,绝不盖这一格刚被人在候选里挑中的那一个值**(`_run_entries(own_key=)`
# ↔ `fetchPickWrites(hits, live, selfKey)`,指着自己的那几行也不写);一条都不成立、或命中
# 那条没自带,读的就是字段上那份 `fetch`——老表单一个字节不改。源与入参都默认跟着那一条
# (留空=就问这一家 / 沿用筛候选那一份入参,`fill.args` 那一栏留着是因为候选入参不许引用
# 自己、而带出常常要 `{form.这一格}`);失败策略与冻结那四档跟字段那份走(问的是「这一格
# 怎么待人」)。字典那一家走 `autoFill`、流程单据走 `linkFill`,两条本来就跟着各自命中的
# 对象走,不再各挂一层。设计器:那张卡片下面多一栏「这一家的带出」(只列取值型的源、
# 带出去向的候选里没有这一格自己、写回时对同一家与同组入参去重),设计期逐条体检门牌写
# 「第 N 条候选来源的带出」并多一句「不能把值带进自己」;改名与删格子时这份落点跟着搬 /
# 跟着摘(`formRename` / `formPrune` 的 `optionRouteFill`)。新键 1 枚(`optionRoutes[].fill`),
# 没写=老画法。库结构:这一版生产库零 DDL——`backend/app/models.py` 与 `sql/schema.sql`
# 与 202611121226 一字不差,没有新列新索引要补。
# 发布前闸:镜像内 `vue-tsc -b` 过;全量单测 `vitest run` 177 files / 1907 tests 全绿;
# 后端新增 `check_option_route_fill.py`(50 项,不碰库,含把「只写带出去向」钉进源码那句
# 前后端对账),外加 `check_option_routes` / `check_binding` / `check_row_fetch`(34) /
# `check_fetch_freeze`(20) / `check_fetch_url_args`(28) / `check_selector_kinds`(46) /
# `check_dict_manual`(37) / `check_hidden_field_rules`(33) / `check_form_change_noise`(18) /
# `check_schema_bootstrap`(20) 各自全绿。
# 202611121226 起(已推 Harbor,digest sha256:a31d1475…,linux/amd64,tag 与 latest 同一份):
# 202611120959 之后动过的 34 个代码文件(26 改 + 8 新增,另有 6 份文档)都在这一版里,
# 一条主线三件事,都落在**字段上的候选来源与取数**(用户那三句:「我一个组件中为什么不能
# 配置多个外部数据源、数据字典,我通过表单中字段来判断该用什么数据源」「下拉框也要能被
# 带出来的值覆盖」「设了显示条件,提交流程后全部字段都显示了;设了默认隐藏+显示条件,
# 表单校验又不过」)。
# ① 候选来源的条件路由(`field.optionRoutes`,口径 docs/option-source-routing-design.md):
# 字段上多挂一份**有序清单**(最多 8 条,每条 = 一个触发条件 `when` + 一套来源配置),
# 自上而下第一条成立的用它,一条都不成立**回落到字段自己那一份**——没挂清单的老表单
# 走的就是这条回落,一个字节不用改。以前一格只能一答不是漏了复选框,是那套设计的前提:
# `effective_options` 只读那一份配置,「存的是哪一列」与「要不要判越界」都跟着那一答走,
# 两答同时在场当场没有定义。「顺序 + 回落」让同一时刻仍然只有一套候选在场,前提不破。
# 命中之后只把字段摊成一张**视图**(`dicts.option_view` / `optionFieldView`,只换来源
# 那一维)再喂既有函数,所以渲染候选、判越界、级联筛选项、字典带出取哪本的附加值、
# 一趟预取哪几本、上游重算清单、删字典与删数据源前的「哪些表单在用」、只读与标题与
# 导出(含明细导出)翻名字、手机「完整单据」念关联单据的标题,全部跟着命中的那一条;
# 明细列按**同一行**里别的列命中,与桌面 `routedField(column, row)` 同一口径。
# 保存那一刻逐条清洗(只留属于它那一种来源的那几格),认不出的来源、配到一半的空条目、
# 第 9 条起多出来的都当没配,宁可回落也不给填单的人一只空下拉。
# ② 外部取数同一分寸(`fetch.sources[].when`,单源老写法也能挂):设计期检查看**全量**
# 清单,运行时只跑**成立的那几条**;一条都不成立=「这一格这回不取数」,不是失败——
# 不走 `onError` 那一档、留痕不记失败、值留在原来那一份上。
# ③ `field.allowOutsideValue`(带出的值不在候选里也收下,默认关)+ 回看与必填死锁:
# 勾上之后外部取数 / 关联带出 / 字典带出写进来的值即使不在候选里也不被清掉,候选里
# 多一行「带出」把它念出来;没勾照旧清。回看那一屏不再「只往宽放」(所以以前会看到
# 全部字段摊开):「默认隐藏+显示条件」那组按存过的那份值评条件,不成立照旧藏着,
# 而**存过值的格子仍然显示**这一条保留——回看要看的就是当时填了什么;必填那道闸补了
# 「因显示条件不成立而藏起来」那句豁免,系统带出格不再把提交卡死。
# 新键三枚(`optionRoutes` / `fetch.sources[].when` / `allowOutsideValue`)都是没写=老画法。
# 库结构:这一版生产库零 DDL——`backend/app/models.py` 与 `sql/schema.sql` 与 202611120959
# 一字不差,没有新列新索引要补。
# 发布前闸:镜像内 `vue-tsc -b` 过;全量单测 `vitest run` 174 files / 1870 tests 全绿;
# 后端 `check_option_routes.py` 11 段(不碰库,含把标题/导出那几处 `data=` 钉在源码里)、
# 外加 `check_binding` / `check_detail_export`(86) / `check_selector_kinds`(46) /
# `check_pick_filter`(73) / `check_row_fetch`(34) / `check_link_fill` /
# `check_hidden_field_rules` / `check_self_visible` / `check_form_change_noise`(18) /
# `check_months_style`(17) 各自全绿。
# 202611120959 起(已推 Harbor,digest sha256:a0f8cec4…,linux/amd64,tag 与 latest 同一份):
# 202611120907 之后动过的 22 个代码文件(15 改 + 7 新增,另有 5 份文档)都在这一版里,
# 两条主线,都落在**明细表的列**上(用户那两句:「明细表中引用公式带入的值,为什么不能
# 编辑」与「明细表中的字段是否可以配置取数,取我配置的外部数据源」)。
# ① 公式带入的那个数可以让人改了(`column.formulaEditable`,口径
# docs/form-field-catalog.md §2.11):列上一写公式,那一格同时失去录入框与"改得住"两样
# ——`applyRowFormulas` 每轮都整列重算,硬塞一个框敲进去也会在下一轮被盖回去。所以这一档
# 两件事一起管:新键没写 = 老画法,存量表单零变化;凭据落 `row._manual`(与关联带出那份
# `_link` 同一层,整型与落库都跟着留),只豁免改过的那一格、不豁免整列,清空那一格或点
# 「恢复公式值」交回公式,锁与隐藏压过这一档。提交那道闸一个字没动:有框之后必填照卡、
# 格式那几关照过、公式列默认值照旧不复活。
# ② 明细列逐行取数(`column.fetch`,docs/form-data-integration-design.md §9.2):列上那份
# `fetch` 与主表字段同一形状、同一执行器(多源 + `merge` / `args` / `picks` / `onError` /
# `revalidateAfter` / `freezeAfterStart`,无新键),只是逐行各跑一次。两处口径按「一行生
# 一格」收:入参读「整张单 + 这一行」(同名列以本行为准,与本行公式同一作用域),带出去向
# 只认这张表的其它列(往主表写等于让最后一行盖表头,下拉里没有、后端也挡)。报错点明第几行
# (「明细表「收款明细」第 2 行的「银行帐号」的外部数据取不到:…」);整张表被本环节藏起来时
# `onError=block` 降级成不挡(环节权限挂的是表不是列),取数照发、留痕照记;留痕按
# `表名.列名` 记一条、底下挂逐行那几次外呼。权威在服务端:填单页 `runRowFetches` 逐行预取
# (一张表攒完补丁一次写回,逐行各写会把前面几行按旧快照盖掉),提交时 `fetch._apply_rows`
# 按同一份配置逐行再取一次并覆盖,接口直传与前端篡改都塞不进假值。仍不做"一次查询填整张表"
# (结果集控件,docs/sql-autofill-design.md §6 第 4 条):这一档一行一调,行的增减归人。
# 库结构:这一版生产库零 DDL——`backend/app/models.py` 与 `sql/schema.sql` 与 202611120907
# 一字不差(两份文件都是 11-11 那一份),没有新列新索引要补;上一版那条「跑过
# 20261110_form_follow.sql 的库要手工 DROP `oa_process.form_config`」照旧有效,与本版无关。
# 发布前闸:镜像内 `vue-tsc -b` 过;全量单测 `vitest run` 169 files / 1818 tests 全绿;
# 后端 `check_row_fetch.py` 34 句、`check_table_formula_editable.py` 12 句,外加
# `check_binding` / `check_fetch_freeze` / `check_hidden_field_rules` / `check_link_fill` /
# `check_table_column_config` / `check_globals` 各自全绿。
# 202611120907 起(已推 Harbor,digest sha256:2511364d…,linux/amd64):整份工作区打的,
# 202611111352 之后动过的 60 个文件(45 改 + 15 新增)都在这一版里,三条主线。
# ① 浏览器兼容那一档真正立起来(口径 docs/frontend-design.md §15):`vite` 产物降到
# `target: es2015`——默认那档(≈ES2020)把 `?.` / `??` 原样发出去,Edge 15/16、
# Safari 10 上是**语法解析失败**,整页白屏,连"哪一格没带出值"都谈不上。新增
# `src/utils/legacyCompat.ts` 只补缺的那几位内置对象与宿主 API(`Object.entries` /
# `Array.prototype.includes` / `padStart` / 收迭代器的 `Set` / `Element.closest` /
# `Promise.allSettled` 等十几位,现代引擎上就是几十次 `typeof`,不改语义),
# `main.ts` 第一行 import 它;同处导出 `pad2` / `padLeft` / `groupThousands` /
# `uniqTexts` / `eachGlobalMatch` / `toList` 这组"自己算"的原始写法,带出值与展示
# 这条链优先走它们。组件里不再裸 `new Intl.*` / `new URL()`:日期与金额走
# `utils/format.ts`(老 `Intl` 认不下 `notation: 'compact'` 就退回「万 / 亿」与
# 千分位;顺带修三处真 bug——`hour12: false` 下有的引擎把午夜念成 `24:00`、
# `Intl.Collator` 不认 `numeric` 时表格排出「10 在 9 前头」、后端给的带微秒 ISO
# 在 IE 上是 `Invalid Date`),拆地址走 `utils/url.ts` 的 `parseHttpUrl` /
# `httpOrigin`(口径一字不变,`https://v1.2` 那种末段纯数字的主机名照样不算地址)。
# 没有 `Proxy` 就补不出来(Vue 3 的地基),IE 11 与 Edge 的「IE 模式」由
# `index.html` 那道闸门给一句人话,不再把人晾在转圈的骨架屏上;闸门只往 `<html>`
# 打 `data-legacy-engine` 标记、告示等 `DOMContentLoaded` 再画,连
# `addEventListener` 都没有的退到 `attachEvent`。判据 `browserCompatGuard.spec.ts`
# (把 `index.html` 那两段内联脚本连文档一起交给 jsdom 真跑:抽掉 `Proxy` 必须
# 看得见告示,抽之前必须看不见)、`legacyCompat.spec.ts`、`displayLegacy.spec.ts`。
# ② 明细表的列跟主表字段同权(docs/form-field-catalog.md §2.10):设计器列卡补上
# 占位提示 / 字数 / 正则 / 上下限 / 附件三限制 / 列宽 / 对齐 / 合计 与「隐藏此列」
# 这些入口(隐藏复用主表那一份 `hidden`);后端 `service/formruntime.py` 跟上——
# 藏起来那一列不卡必填(`column_not_for_people`,前端镜像
# `formRuntime.columnNotForPeople`),`min` / `max` 提交时真判(以前只有
# `<input type="number">` 标个红,接口直传与脚本写入压根不经过那只框),列宽
# 60-640px / 对齐 / 合计的写法只在设计期判(`column_display_problems`)。表尾多出
# 「合计 / 平均 / 最大 / 最小 / 计数」那一行(`TableAggregateRow.vue`,数字照列上
# 那份格式写,免得格子里 1,200.50、表尾 1200.5),收折段头上的「合计 X」也优先念
# 列上点了求和的那一列;手机端同一口径(`mobile/useFormPlan.ts`:藏着的列不摆、
# 链接列点得开、抬头读手机端配的短名)。判据
# `backend/scripts/check_table_column_config.py` 21 句(发布前在开发库跑过、全绿)
# 与 `formRuntime.tableColumnConfig.spec.ts` / `FormRenderer.tableColumnDisplay.spec.ts`
# / `FieldInspector.tableColumns.spec.ts` / `FieldInspector.columnMore.spec.ts`。
# ③ `url` 那一格在手机上终于点得开:新增 `utils/linkText.ts` 与
# `components/common/LinkText.vue`(认得出的包成 `<a>`、裸域名补上 `https://`、
# 认不出的一句话原样摆),桌面读的是同一份,手机端摘要屏与「完整单据」两屏都过
# 这一层,明细表的链接列同权。判据 `linkText.spec.ts` / `FormFieldControl.url.spec.ts`
# / `MobileFormReader.spec.ts` / `MobileFormSummary.spec.ts`,口径见
# docs/mobile-approval-layout.md。
# 库结构:这一版生产库零 DDL——`backend/app/models.py` 与 202611111352 一字不差,
# 没有新列新索引要补;上一版那条「跑过 20261110_form_follow.sql 的测试 / 预发库要
# 手工 DROP `oa_process.form_config`」照旧有效,与本版无关。
# 发布前闸:镜像内 `vue-tsc -b` 过,全量单测 `vitest run` 163 files / 1777 tests 全绿。
# 202611111352 起(已推 Harbor,digest sha256:3e49d59f…,linux/amd64):整份工作区打的
# (94 改 + 48 新增,全是 202611101030 之后的活儿),主线是关联带出与设计器那一屏。
# ① 关联带出(`field.linkFill`,配在「候选来源 = 流程单据」那一格):挂上来的那几张
# 单把值写进本单的主表字段与明细表,挂多张也能带(合成一个值 / 一单一行);判据
# backend/scripts/check_link_fill.py(纯函数口径)与 check_link_fill_submit.py(连库走真
# 提交:发起就带得出、`_link` 活得过整表、关联没变不重排、带不出值时必填挡人),口径见
# docs/relation-link-fill-design.md。② 明细表那一列锁得上(`column.readonly` 补了设计器
# 入口,check_table_column_readonly.py),提交之后还可以先收着(`readonlyStyle`)。
# ③ 联动条件能判自己那一格(check_self_visible.py、docs/field-self-visibility-design.md),
# 条件右边也能是另一格(`rules[].valueField`,「结束日期晚于开始日期」那种成对比较)。
# ④ 明细「本行公式」吃得到主表字段,主表一变实时重算、算平了就不再写回。⑤ 空值那一格
# 写什么只由 `field.placeholder` 说话,没配给 `--`,预览里「单据编号」给真样子(顺带修了
# 这一栏被 `v-else-if` 连坐、在单行文本上从来没真的出现过)。⑥ 抄送需处理可随附图片/
# 文件、归档件能补批注(check_cc_action_files.py)。⑦ 干预改道之后旧环节留下的残留与
# 已推出去的消息各自收口,待办没了点开是张说得清的下场卡(check_intervention_move.py、
# check_notify_settle.py、utils/taskVanished.ts)。⑧ 「在途单据的表单跟随最新设计」整条
# 下线:表单与环节、路由一起冻在发起那一刻那一版。⑨ 设计器窄栏只留入口、多列配置一律
# 进弹窗(docs/designer-panel-dialogs.md)。运维添两只脚本:scripts/migrate_design.py
# 按业务键把生产设计搬一份到测试库(源库只读、目标库先备份、一个事务写完),
# scripts/set_approvers.py 把测试环境的审批人统一改成发起人本人。
# 库结构:这一版生产库零 DDL(2026-11-11 拿 config.prod.toml 只读核过 unis_oa_prod:
# 模型声明的列与索引一条不缺,RETIRED_COLUMNS 那几列也没有残留)。两份脚本对得上账:
# sql/upgrade/20261110_read_action_attachments.sql 那两列 oa_read /
# oa_read_completed.attachments 已在(存量 15 行 JSON_TYPE 全是 ARRAY,不用回填,
# 重复跑只报 1060);sql/upgrade/20261111_drop_form_config.sql 两步在生产都是预期噪音
# ——oa_process 压根没有 form_config 这一列(form_follow 那套没上过生产),跑下去分别
# 报 1054 / 1091,跳过即可。
# ⚠️ 唯一要动手的是跑过 20261110_form_follow.sql 的测试 / 预发库:那边补一句
# ALTER TABLE `oa_process` DROP COLUMN `form_config`;(开发库不用管,backend/app/db.py
# 的 RETIRED_COLUMNS 启动时自己清)。起之前、起之后各跑一次 README 里那段只读缺列核对。
# 202611101030 起(已推 Harbor,digest sha256:08e1bc54…,linux/amd64,--no-cache 全量重建):驳回之后重新往前
# 走的环节不再一律标红,「改了表单」也不再被 0.0→0 骗到。① 审批记录那一圈红点的判据
# 从「整条历史里走过没有」改成「本轮走过没有」——visited 遇退回线 / 落回已走节点 /
# move 改道就清空重新计轮,并把落点那一个节点本身当作本轮起点,与后端去重用的
# DEDUP_SINCE_KEY 同一个口径;判据 frontend/src/components/oa/ApprovalRecord.spec.ts
# 「驳回与改道之后重新往前走」3 条。② form_change_notes 比字段改动时,数字与金额类
# (number / money / rate / percent / year / formula)走数值比较,0.0→0、4075.0→4075
# 这种纯格式差不再记成人工改动;判据 backend/scripts/check_form_change_noise.py 18 条。
# 两处都拿生产单 FYBX202611090003 的真实 payload 核对过:驳回那一步仍是红的,重走的
# 「提交」「同意」是绿的。⚠️ 这一版照旧是整份工作区打的:除了这两处修复,还带着外部
# 字典手工项与带出列选择那一批前后端改动(38 个文件)。
# 202611061130 起(已推 Harbor,digest sha256:81cc5758…,linux/amd64):关联审批单那只
# 弹窗终于看得出勾了哪几条。多选时行上那一勾写进的是弹窗里的暂存 draft,高亮读的却是
# 已提交的 storedValues,于是点一行什么都不变、勾了几条全靠猜。现在行首是一颗真勾选框
@ -840,7 +1171,7 @@ spec:
# 「服务器内部错误,请稍后重试(编号 xxxxxxxx)」)
# 202610261047 起:镜像自带 backend/config.prod.toml(含密钥),且修了口令带 @ 时
# DSN 被撕成两个主机名的坑(backend/scripts/check_db_dsn.py 盯着)
image: docker.oa.unissense.tech/public/unis_oa:202611091649
image: docker.oa.unissense.tech/public/unis_oa:202611121636
imagePullPolicy: IfNotPresent
ports:
- name: http

View File

@ -358,11 +358,20 @@ seed 的「已存在就跳过」永远判不中,每轮启动都把同一批封
数一变闪一下(`.formula-pulse`)。只读视图(审批详情、打印)显示存下来的值,不带绿点
- **明细表的「本行公式」只有前端会算**:列上写 `formula` 后这一格变成只读,
由 `applyRowFormulas()` 在每次增删改行后重算,跑两轮好让
`total(本明细, 列名)` 这种跨行写法看到新算的值;这类写法在设计器校验里就必须能预览通过
`total(本明细, 列名)` 这种跨行写法看到新算的值;这类写法在设计器校验里就必须能预览通过。
公式能引用的东西就是喂进沙箱的那份数据:**本行的各列**(列标识裸写或 `data.get('列')`)、
**主表的字段**(第三参 `formData`,与列同名的以本行的值为准)、以及**这张明细表自己**
(`total(明细标识, 列名)`)。主表那一格(手填的、公式算的、外部带回的)一变,
`FormRenderer` 按 `rowFormulaSignal` 把带公式列的表整表重算,算完跟原来一样就不写回;
本行公式引用主表公式字段、那个公式字段又合计这一列时两边会互相追着涨,
所以连追 8 轮还没稳住就停下来。服务端不重算这一列,接口直接提交的报文得自带算好的数
- 口径由 `src/utils/__tests__/formFormula.spec.ts`(含线上费用报销单那三条公式)、
`src/utils/__tests__/formNumberFormat.spec.ts`(四种数字写法与系统带出字段的必填判定)
与 `src/components/oa/__tests__/FormRendererFormula.spec.ts`(改数即变、写回 model、
缺依赖不啰嗦、预览算不了才提示、只读态取存量)守住
缺依赖不啰嗦、预览算不了才提示、只读态取存量)守住,
本行公式那一层由 `src/utils/formRuntime.rowFormula.spec.ts`(能吃谁、同名谁说了算)与
`src/components/oa/FormRenderer.rowFormula.spec.ts`(主表一变整表跟着变、只读态不动数据、
配成环也停得下来)守住
## 4. 流转算法
@ -414,7 +423,7 @@ seed 的「已存在就跳过」永远判不中,每轮启动都把同一批封
| 终止 | `POST /job/{job}/terminate` | 发起人或管理员终止,活动表迁出为 `terminated` |
| 删除 | `POST /job/{job}/delete` | 只开给**还没发起流转**的单(本人创建、还停在开始环节、没有别人的待办或需处理抄送压在上面):连单带号从运行表里抹掉,不归档、界面上再也找不到它;已经流转过的单删不掉,那种单要的是终止。收尾四样:额度还回去、外部表态作废、嵌页面那本「已发起成单」的账收回、给第三方发一句「这张单删了」(参数与删草稿那一条同一个人配的同一份,见 `service/embed_session.abandon_on_work_deleted`) |
| 管理员介入 | `POST /admin/work/{job}/terminate` `POST /admin/task/{id}/press` | 需要 admin 角色 |
| 待阅 | `POST /read/{id}/view` | 标记已读,与待办相互独立 |
| 待阅 | `POST /read/{id}/view` `POST /read/{id}/handle` | 标记已读;带 `requires_action` 的抄送只能由本人走 `handle` 填处理意见才算办完(`attachments` 随意见一起登记),与待办相互独立 |
## 6. 定时调度
@ -526,7 +535,8 @@ POST /task/{task_id}/press 催办
GET /task/{task_id}/goback-targets
GET /read/processing 待阅件
GET /read/completed
POST /read/{read_id}/view
POST /read/{read_id}/view 标记已读
POST /read/{read_id}/handle 抄送需处理:处理意见 + 可选 attachments,登记进已阅
GET /worklog 流转轨迹
POST /taskcompleted/{id}/reset 撤销转办 / 已办回滚
GET /admin/task/processing 流程监控:数据范围内的全部在办待办

View File

@ -2,7 +2,10 @@
> 相关:[option-source-design.md](option-source-design.md)(候选来源 × 挑选方式)、
> [form-data-integration-design.md](form-data-integration-design.md)(五种取数形态)、
> [external-data-simplification.md](external-data-simplification.md)(字典吃外部数据源)。
> [external-data-simplification.md](external-data-simplification.md)(字典吃外部数据源)、
> [option-source-routing-design.md](option-source-routing-design.md)(这两层各自补上的那句
> 「什么时候才用」:候选来源那一头的 `optionRoutes` 清单,与取数这一头的 `fetch.sources[].when`。
> 共用同一份条件判据,也共用同一份「设计期看全量、运行时按条件筛」的分工)。
>
> 这一篇回答一个被反复问到的问题:**一个组件既有「候选来源」又有「外部取数」,
> 这两个不是一件事吗?能不能合成一个?** 结论是先说清楚为什么不能合成一格,

View File

@ -0,0 +1,132 @@
# 设计器侧栏只留入口,配置摊进弹窗
原话是这一句:**「截图所示,配置的地方太宽了导致都展示出界了。帮我把所有配置都变成弹出框
进行配置,这样就不会出现这样的情况。」**
截图里是表单设计器那条 320px 的属性栏:「关联带出」那一栏里几只下拉整个撑到卡片右边框
外面去,选项全称被截成「对方表单字段·附件(工作联…)」。这份文档写的是修完之后定下的
那条规矩、`SidePanel` 这一层的契约、哪些配置进了弹窗、哪些**故意没进**,以及怎么验。
## 0. 一页看完
| 要做的事 | 在哪儿 | 点下去到哪儿 |
| --- | --- | --- |
| 改一格的候选来源 / 关联带出 | 属性栏 → 「候选来源」那一行(角标写来源类型、几项、几条带出) | 弹窗:候选来源 + 显示映射 + 关联带出那一整块 |
| 改明细表有哪几列 | 属性栏 → 「列」那一行(角标 `N 列` / `共 N 列,其中 M 列必填`) | 弹窗:那张列编辑器 |
| 改联动、外部页面、额度、取数、阈值 | 属性栏 → 各自那一行 | 各自的弹窗,面板本体一个字没改 |
| 改标题 / 编号的生成规则 | 属性栏 → 「流程标题生成规则」那一行 | 弹窗(`TitleRulePanel` 现在就是 `SidePanel` 的一层皮) |
| 改一条连线 | 右栏「连线配置」→ 「添加路由」那一行;**画布上直接点那条线,门自己开** | 弹窗,底下是「应用到画布」 |
| 改审批人规则、抄送、字段权限、外部审批、写回、闸门 | 右栏那一行摘要 → `NodeConfigDialog`(extra-wide,左列选分组) | **不再往里叠一层**:见 §3 |
| 改一格的名称 / 标识 / 类型 / 占位 / 必填 / 宽度 | 属性栏里就地改 | 不进门——单控件,摊得开 |
贯穿这份改动的三条分寸:
* **能摊开的都摊到弹窗里**,判据不是"这块重不重要",而是"它要不要多列并排"。一只
`Select` 在 150px 里只能念出前五个字,那就是没摊开。
* **面板本体一行没改**。挪的大多是既有的 `*Panel.vue`——它们本来就是按整块设计的,只是
换个地方摆。所以没有第二份实现,也没有第二套校验措辞。
* **不为了统一把单控件也塞进弹窗**。改名、勾必填、填标识是一天点几十下的动作,多一次
点击就是真的更难用。窄栏留着它们,弹窗留给表。
## 1. 溢出那一下的真实原因
弹窗是主修,但撑出去那一截本身是个 bug,也一起修了——就算不进弹窗也不该出界:
- 声明成 `grid-cols-[1fr_1fr]` 的网格轨道,**隐式 `min-width: auto`**:里面那只下拉的
最小内容宽度大于轨道份额时,`1fr` 不会收缩,整块被顶宽。改成
`grid-cols-[minmax(0,1fr)_minmax(0,1fr)]` 才真按份数分。
- `components/common/Select.vue` 根节点原来只有 `relative`,缺 `min-w-0`,作为弹性/网格
子项时同样不收缩。根上加 `min-w-0` 是一次性修完所有调用点。
`LinkFillPanel.vue`、`LinkagePanel.vue` 里那几处 `[1fr_auto]` / `[1fr_1fr_auto]` 一并换成
`minmax(0,…)` 写法。这三处是防御性的:弹窗里也还是这套布局。
## 2. `SidePanel`:入口那一行 + 一扇门
`frontend/src/components/oa/design/SidePanel.vue`,属性栏那十来块面板与连线那一块共用它。
侧栏那一行只负责三件事:说这是什么配置(标题 + 图标)、现在配成了什么样(摘要 + 角标)、
点一下开门。摘要与角标**不是装饰**——门关上以后,那一行就是唯一的可见状态;配没配、几条、
哪几格,都要不点开也念得出来。配过的行描成主色(`emphasized`),一眼扫得出哪些格子动过。
| 入参 | 管什么 |
| --- | --- |
| `title` / `icon` | 那一行与弹窗标题 |
| `summary` / `badge` / `emphasized` | 那一行念出来的三样:现在什么样、几条、有没有配过 |
| `intro` / `hint` | 弹窗顶上那句说明、底下那句提示 |
| `width` / `contentClass` | 弹窗宽度与内容宽度上限(窄面板摊在 1100px 里会散,给一道 `max-w-*`) |
| `reveal` | 递增一下就把门打开:从工具栏、总览、明细表那一侧跳过来时用 |
| `resetKey` | 变了就把门关着:弹窗开着时点别的格子,门里不该还是上一格的配置 |
| `testId` | 生成 `-entry` / `-open` / `-badge` / `-summary` / `-close` 那几个 `data-test` |
三条行为上的定死:
- **门关着时插槽内容根本不挂载**(`BaseDialog` 里是 `v-if`)。属性栏一次只选一格,但每格
背后都挂着七八块面板,全都挂载等于每点一格就跑七八趟接口。
- **改动当场生效**,没有「确定 / 取消」。面板们写的都是字段 / 环节上那份配置,画布的未保存
黄点与撤销栈跟着走——和「手机端」「标签页」同一脾气。
- **要自己摆按钮的用 `#footer` 具名插槽**。连线那一块是唯一的例外:它点「应用到画布」才落到
设计上,不该挂在那句「改动当场生效」下面。宿主自带 footer 时,默认那句提示和那颗「关闭」
都不再出现,免得说错话。
`reveal` 那条信号是旧口径的延续:从总览弹窗「跳到那一格」以前只负责滚动定位,现在多了
一步——先把门打开,再滚到眼前并描一圈。`revealLinkFill` + `revealLinkFillKey` 那对键控
信号(见 [relation-link-fill-design.md](relation-link-fill-design.md) §2.5)一个字没改,
只是最里面那一层从"就地展开"换成"开门"。
## 3. 进了弹窗的清单
**表单设计器属性栏(320px)**:候选来源(含显示映射、关联带出)、明细表列编辑器、联动、
外部页面、额度、外部取数、阈值、标题 / 编号生成规则。
**流程设计器右栏(352px)**:连线配置。环节那一侧(条件免审 / 条件必批 / 自动抄送 / 表单
字段权限 / 外部审批 / 写回 / 提交闸门)**这一层没动,也不该动**:常驻的 352px 那一栏早就
只摆摘要 + 入口(`variant="rail"` 那一段,一行一句现状,点下去 `emit('configure', group)`),
进去的是 `NodeConfigDialog` 那颗 extra-wide 弹窗,左列选分组、右面那一整块面板摊在约
1000px 里。这一层再叠一道弹窗就是弹窗摞弹窗,白多一次点击。**同一个规矩,两种满足方式**:
判据是"它有没有摊开的地方",不是"它是不是面板"。
**本来就是弹窗的**:标签页配置(`TabsConfigDialog`)、手机端版式(`MobileLayoutPanel`)、
关联带出总览、条件构造器、公式构造器、环节配置弹窗。属性栏里那一栏(`TabsPanel`、
`table-link-fill`)只念摘要 + 给跳转按钮,改都交给弹窗——这条规矩在它们身上早就成立了,
这次是把剩下的补齐。
**没进弹窗的**:名称 / 标识 / 类型 / 占位符 / 必填 / 宽度 / 默认值这些单控件,以及并排两
个数字框那种(金额上下限、星级 + 小数位)。一列放得下,摊进弹窗只是多一次点击。
## 4. 几处容易踩的地方
- **嵌套弹窗**:连线门里还要开条件构造器,候选来源门里的联动要开条件弹窗。两层都是
`BaseDialog` 默认 `z-50`,靠"后挂载的在 body 里排在后面"叠上去,够用;真压不住再显式
给 `z-index`(`InterventionPanel` 那种)。
- **`Select` 的下拉**在弹窗里是 fixed 定位、`z-index: 100000020`,不受 modal 层级影响。
- **开门不等于选中**。`reveal` 只在递增那一瞬开门,不记状态;`resetKey`(字段 key 或环节
id)一变就关门,避免"门里是上一格的配置、外面是这一格的名字"。
- **连线那扇门要 `immediate`**。点画布上那条线是把右栏切到「连线配置」**同时**带上 id,
面板那一刻是挂载而不是更新,监听器不 `immediate` 就是第一下不开门。
- **测试里要 `stubs: { teleport: true }`**。弹窗内容传送到 body,不 stub 就 `find` 不到;
要摸真的 DOM(焦点、滚动)就照 `FormDesignerView.tabs.spec.ts` 那样再配一个
`attachTo: document.body`。窄栏里的面板整块搬进弹窗之后,原来直接 `find` 面板内部的
测试都要先点一下 `*-open` 那颗入口——`FieldInspector.newTypes.spec.ts` 里摸明细表列
编辑器的那一句改的就是这个,`open()` 之后补一步点击,测试各自钉的行为一个字没动。
- **别把已经在宽弹窗里的面板再叠一层**。环节那一侧八块配置先试过这条路,结果是
`NodeConfigDialog` 里再摞一道弹窗、点两次才摸到控件,又退回去了(§3 末段)。
## 5. 怎么验
```bash
cd frontend
npx vue-tsc --noEmit
npx eslint src
npx vitest run src/components/oa/design
```
钉住这条规矩的测试:
| 测试 | 钉的是什么 |
| --- | --- |
| `design/SidePanel.spec.ts` | 门关着时插槽不挂载;点入口开门 / 点关闭关门;`reveal` 开门;`resetKey` 关门;宿主自带 footer 时默认那颗关闭与那句提示都退场 |
| `design/RouteInspector.spec.ts` | 窄栏只剩入口;入口那一行念得出「起点 → 终点 · 名字 · 条件」;点连线时门自己开(含挂载那一下);没点「应用到画布」一个字不写;按「删除连线」把门关上 |
| `design/FieldInspector.newTypes.spec.ts` | 明细表列编辑器改成弹窗后,先点入口再摸里面的列选择器 |
| `views/oa/design/FormDesignerView.linkFillEntry.spec.ts` | 光选中那一格看不见带出那一栏(它已在门里),点入口才开门;从总览 / 明细表 / 双击跳过来时门自己开 |
| `i18n/localeParity.spec.ts` / `messageSyntax.spec.ts` | 新增那批 `form.panel*` 与 `process.route*` 文案中英一致、插值语法没错 |

View File

@ -0,0 +1,127 @@
# 显示条件判自己那一格:字段的显隐由它自己的取值决定
> 相关:[form-field-catalog.md](form-field-catalog.md)(每一类字段有什么值、能不能判)、
> [option-source-design.md](option-source-design.md)(候选与选项级 `when`)、
> [mobile-form-layout-config.md](mobile-form-layout-config.md) §4.2(手机上那两屏同一句判据)、
> [option-source-routing-design.md](option-source-routing-design.md) §6(同一批反馈里的另一头:
> 回看那一屏按存过的那份值评条件,以及因显示条件被收走的必填格不再卡提交)。
> 这一篇只讲一件事:**联动条件(显示 / 必填 / 只读)里可以点名的那一格,就是配条件的那一格自己**。
## 0. 一页看完
| 问题 | 结论 |
| --- | --- |
| 需求 | 「表单中字段的显示判断条件,需要可以设置判断本身字段的值情况来确定是否可以展示」 |
| 以前 | 设计器把本字段从条件清单里筛掉(`LinkagePanel.conditionSources` 那句 `key !== field.key`),后端保存报「联动条件引用了自己」。想配只能造一个中间变量绕一圈 |
| 现在 | 三栏条件(`visibleWhen` / `requiredWhen` / `readonlyWhen`)里都能挑「本字段」;选项级 `when` 同理 |
| 落库 | **一个字都没变**:还是 `{match, rules}`,只是允许 `rules[].field`(或 `rules[].valueField`)等于本字段的 key,不加新键、不做数据迁移 |
| 判法 | 走原来那条 `compare`:读的就是这一格此刻的值,没有第二套引擎 |
| 一键配法 | 侧栏「满足条件才显示」下面两颗开关:「本字段有值才显示」= `{field: 自己, op: notEmpty}`,「本字段没值才显示」= `empty`;选中态再点一下撤掉。已经配了**别的**显示条件时这两颗不摆(它们写的是整条条件,摆着点一下就把人配好的那一串换掉了),改条件走弹窗 |
| 什么时候真正合身 | 值**由系统写进来**的那一类格子:外部取数(`fetch`)、字典带出(`autoFill`)、关联带出(`linkFill`)、公式、别的系统回填。「合同编号带回来了才露这一格」就是这一句 |
| 要说清的代价 | 这一格**由人填**、又拿自己的值决定露不露:填一个字它就当场藏起来(光标还停在上面,格子已经没了)。值不会丢(见下面「收值那一句」),但界面上这一下确实像被吞了,所以设计器当场把这句话写在那一行下面 |
| 要「有值就别让人改」 | 配的是「满足条件就锁住」(`readonlyWhen` 判自己 `notEmpty`),不是显示条件 |
| 收值那一句 | 只被自己那句条件收走 / 锁住的格子,提交时这一笔值**照样收下**(`formruntime.self_gated_keys` ↔ `formRuntime.writableIgnoringSelf`)。否则「有值才显示」「有值就锁住」会把人刚敲的那一笔按「这一环改不动」退回原样,写进去的字凭空消失 |
| 一寸没放宽的地方 | 界面上露不露、必填要不要、阈值 / 额度 / 取数挡不挡人,读的都是**带自引用的那一份**条件;环节明写隐藏、被别的格子挡住、类型压根没有录入框,三档都不借这一句翻案 |
| 级联清值 | 自指**不进**这一圈:`dependsOn` / `depends_on` 照旧把「自己」摘掉,否则刚写进来那一份会被当成越界值抹掉。`conditionDependencies` 留着它(设计期检查与界面重算要读) |
| 仍算配错的三句 | 级联上级选了自己;同一条规则左右两头是同一格(`field` 与 `valueField` 同名);指向不存在的字段 |
| 改名 | 那一格自己那几条「判自己」的条件跟着新名字搬(`utils/formRename`)。别的格子上读旧名字的条件照旧不动——那句看得见,交给人决定 |
| 顺手修的分叉 | 「填没填」这一寸两边不一样:后端 `dicts._is_empty` 一直把一串空格算没填,前端 `isEmptyValue` 只认空串。`notEmpty` 判自己时两边能算出两个结果(界面露出一行空白,服务端判它没填),现在同一把尺子 |
| 验收 | `PYTHONPATH=. python3 scripts/check_self_visible.py`(不碰库)+ `npx vitest run src/utils/formLinkage.self.spec.ts src/components/oa/FormRenderer.self.spec.ts src/components/oa/design/LinkagePanel.self.spec.ts src/utils/formRename.spec.ts` |
| 唯一口径在哪 | 判法 `frontend/src/utils/formLinkage.ts` ↔ 后端 `backend/app/service/dicts.py`;最终权限与收值 `frontend/src/utils/formRuntime.ts` ↔ `backend/app/service/formruntime.py`(引擎回滚那一段在 `engine._apply_form_runtime`);设计器那一栏 `components/oa/design/LinkagePanel.vue` + `LinkageConditionDialog.vue` |
## 1. 为什么这一档值得放开
「这一格露不露」以前只能说别人的事:`visibleWhen` 里挑的字段一定是**另一格**。可表单上有一整类
格子,它该不该露,问的恰恰是它自己有没有值:
- 外部取数带回来的合同编号 / 发票号 / 预算余额——带回来了才有脸露出来,没带回来就该一句不说;
- 别的环节或别的系统回填的补充说明——回填了才看得见,不然摆一行空标签;
- 明细表 / 附件这种「有了才露」的整片区域,配合「默认隐藏」用得最多(默认隐藏那一档只在
配了显示条件时让位,见 README 里那一段,`hidden_by_default`)。
绕过去的办法是造一个中间变量:另开一格隐藏的公式 `=IF(合同编号<>"",1,"")`,再让条件去读它。
配的人得多懂一层,多出来的格子还会漏进导出与打印,而条件念出来是「中间值 等于 1」,
没人知道它在说什么。判据本来就够得着自己的值,缺的只是让人把这一格挑出来。
## 2. 语义只有一条:读的就是这一格此刻的值
没有新引擎、没有「按载入时的值」那一档、也没有「一旦露出来就不再收回」那种粘性状态。
`rules[].field === 本字段` 就是把本字段当成条件里的普通一格读——`compare` 那一条路,
两边(前端 `utils/formLinkage`、后端 `service/dicts`)本来就跑同一份数据、同一个结果。
为什么不搞粘性(露过一次就留着):那种状态只活在一次打开里,服务端算不出来,
于是「界面让人填、提交说非法」那道缝又回来了。这一整套的底线是**同一个条件两边一个结果**,
所以宁可让语义是「此刻的值」,把人会踩的那个坑拿到设计器里当场说清(§4)。
## 3. 放开之后必须钉住的三条
### 3.1 只放宽「判谁」,不放宽「怎么判」
- 级联上级(`cascadeFrom`)选到自己仍是配错:候选得由另一格来筛,自己筛自己筛不出东西;
- 同一条规则左右两头是同一格(`{field: x, op: eq, valueField: x}`)仍是配错:自己跟自己
比没有新意思;
- 指向不存在的字段照旧报(哪怕同一条条件里还有指向自己的那一条——只放行指自己那一条)。
### 3.2 自指不进「上游变了清下级失效值」那一圈
`dependsOn`(`depends_on`)按定义摘掉自指。这一刀不是遗留:清失效值那一趟会拿
`effectiveOptions` 反过来质疑**刚写进来**的那一份值,自己当自己的上游就是「自己判自己越界」,
带出来的值会在一轮收敛里被抹掉。条件层面要不要跟着重算不依赖这一份清单——办理屏那句
`hiddenOnScreen` 本来就是对着整份 `modelValue` 算的。
### 3.3 「只被自己藏起来」的那一笔值要收下
引擎那一段回滚的判据是「这个环节改不动这一格」:
```python
writable = editable_keys(fields, perms, data) | hidden_keys | self_gated_keys(fields, perms, data)
```
`self_gated_keys` 问的是「把这一格三栏条件里读自己那几条摘掉以后,它本来就填得动吗」。
是,就收这一笔——因为**这一笔值正是让它藏起来的原因**,退回原样等于把人刚写的字抹掉。
摘掉以后仍然填不动(环节明写隐藏 / 只读、被别的格子的条件挡住、`description` 那种
没有录入框的类型),一概不放宽。
放宽的只有「收不收这一笔值」。界面露不露、必填要不要、阈值 / 额度 / 取数挡不挡人,
读的还是带自引用的那一份条件——所以不会出现「后端偷偷多收了一格不该收的值」。
## 4. 设计器:能挑到、看得懂、错得快
- **条件清单里本字段排最前面**,标成「本字段(contractNo)」;摘要也念成「本字段 已填」,
不会跟表单上另一个同名字段混。
- **两颗一键开关**直接落 `notEmpty` / `empty`,不配别的条件时压根不用进弹窗;选中态再点一下撤掉。
- **挑中自己就在这一行下面多说一句**:值由系统写进来的格子是一句平铺说明;这一格由人填时
换成黄字,说清「填一个字它就当场藏起来 / 要『有值就别让人改』请配在『满足条件就锁住』」。
- **这一格只靠自己的值决定露不露、又是人填的**,那句话直接摊在侧栏那一栏下面(`gatedBySelfAlone`),
不用进弹窗就看得见;系统带出 / 公式那一类格子不提示。
- 右边那一档(比另一格)里**没有自己**:`partnersOf` 按 `rule.field` 筛,挑了本字段之后
另一头自然只剩别的格子,比不了的那一档压根不给。
## 5. 老表单
一个字都不动。以前存不出自引用条件(保存就被拦),所以没有存量要迁;`conditionDependencies`
多出来的那一个自指键只影响设计期检查,而那一处已经从「报错」改成「放行」。
## 6. 回看那一屏与必填:同一条判据的另一端(2026-11 之后)
放开自引用之后,同一批反馈里冒出来两句互相拧着的:
1. **「提交流程之后回看页所有字段都显示了。」** 回看那一屏(只读渲染:单据详情 / 打印 /
手机完整单据)以前**只往宽放**——不凭条件收任何格子。少摆一行「存过的值」比多摆一行难发现,
所以那是当年的取舍;代价就是配了「有值才显示」的那些格子,在办结之后整排摊开,
明明这一单用不到它。
2. **「改成默认隐藏 + 显示条件,表单校验又过不了。」** 病根不在显隐,在必填:`auto` / `formula`
这两类没有录入框、权限永远算只读,字段自己勾了必填说的是「必须算得出值」。老判据连
**因显示条件不成立**被收走的那一格一起催「还没填写」——屏幕上没有那一格,提交永远过不去。
两句各改一句,都不碰自引用那一条:
| 改的那一句 | 现在怎么说 | 在哪 |
| --- | --- | --- |
| 回看那一屏摆不摆 | 环节明写 hidden → 收;环节给了别的权限 → 摊;勾了「默认隐藏」→ 按存过的那份值评条件;**没勾默认隐藏、配了显示条件、按存过值评不成立、且这一格为空** → 收。**有值一律摊开** | 前端 `formRuntime.readbackHidden`(手机端 `mobileLayout` 继承同一句) |
| 藏起来的格子要不要算必填 | 只有**因显示条件不成立**被收走的才算「这一单用不到它」;勾了「默认隐藏」又没配条件的(单据编号、金额大写)藏起来不等于可以不生成 | 后端 `formruntime.hidden_by_condition` → `missing_required`;前端 `formRuntime.hiddenByCondition` → `requiredFields` |
保留的那一寸写明白:**有值但条件已翻走的格子,回看页仍然摊开**。那一笔值确实存过,
收起来等于让它凭空消失;真要按存过值全收干净,得再加一颗字段级开关,别默认改。
钉在 `formRuntime.hidden.spec.ts`、`mobileLayout.spec.ts`、`FormRenderer.self.spec.ts`
与 `PYTHONPATH=. python3 scripts/check_option_routes.py` 第 8 段。

View File

@ -267,6 +267,9 @@ GET /api/v1/data-source/options?code=erp_material&keyword=笔记本电脑
- `"{auto:xxx}"` 取 `service/autofill.py` 里那 10 个已落库的系统值(发起人、部门、工号…);
- 其它一律当字面量。
这一整份形状**明细表的列上也挂得上**,键名与语义一个字都不变,只是它按行跑:`{form.x}`
读的是「整张单 + 这一行」,带出去向只落在同一张表的列上。见 §9.2。
### 5.2 数据源注册表
```sql
@ -609,6 +612,58 @@ CREATE TABLE oa_data_source_call (
- **只读态不取数**:待办列表、打印单、导出 CSV 一律读 `work.data` 里的快照,
绝不在这些批量场景发外部请求——一次导出打几百个 ERP 请求是最典型的雪崩来源。
### 9.2 明细表的列也挂得上:逐行取数(`column.fetch`,2026-11)
来的是用户那句「明细表中的字段能不能配置取数,取我配置的外部数据源」。真实的问法长这样:
收款明细每一行填了收款人,开户行和银行帐号要按**这一行那个人**去 ERP 查——整张表共用一个值
没有意义,逐行手填又必然填错。
配法与主表那一格是**同一个形状、同一个执行器**,没有新键:`binding.entries` 那一整套
(`source` / `sources` + `merge`、`args`、`picks`、`onError`、`revalidateAfter`、
`freezeAfterStart`)在列上照写。设计器入口是「选中明细表 → 那一列的卡 → 更多配置 → 外部取数」,
摆的就是主表那块面板(`FetchPanel`),只是它给的下拉少两类。
| 与主表那一格的差别 | 口径 | 为什么这么定 |
| --- | --- | --- |
| 入参读哪一格 | 作用域是「整张单 + 这一行」,与主表字段同名的列**以本行为准**;`{form.x}` 既能读主表字段也能读本行的列 | 「本行公式」吃的就是同一份作用域(`formRuntime.applyRowFormulas`),配的人不用为明细列再记第二套写法 |
| 「带出去向」能落哪 | 只认**同一张明细表的其它列**,主表字段不进下拉,保存到后端也挡 | 一行生一格,`picks` 写进主表那一格等于让最后一行去盖表头:三行的表盖三次,谁赢看运气 |
| 取不到数怎么说 | 「明细表「收款明细」第 2 行的「银行帐号」的外部数据取不到:ERP 连接超时」 | 整张表共用一句不带行号的报错,八行的表没人知道该回去改哪一行 |
| 整张表在这一环被藏起来 | `onError=block` 降级成不挡(值留在原来那一份上),**取数照旧发起**、带出照旧写、留痕照旧记 | 环节权限挂的是表不是列,所以那一列露不露脸看它所属那张表在这一环露不露;与 §9 那句主表规则同一把尺子(`fetch._policy_of`) |
留痕不能沿用主表那份「列名当键」——两张明细表可能有同名列,同一张表每一行也都得留得开。
于是按「表名.列名」记一条,底下挂逐行那几次外呼:
```jsonc
"_fetch": {
"收款明细.bankAccount": {
"source": "erp_bank_account", "args": {"emp": "10086"}, // 第一行那一次,方便对表
"at": "2026-11-12 10:02:31", "merge": "first", "cached": false,
"rows": [
{ "row": 1, "source": "erp_bank_account", "args": {"emp": "10086"}, "cached": false, "at": "…" },
{ "row": 2, "source": "erp_bank_account", "args": {"emp": "10202"}, "cached": true, "at": "…" }
],
"failed": ["第 3 行:ERP 银行账号接口:连接超时"] // 只有真失败才有这一行
}
}
```
服务端仍旧说了算:填单页按行各取一次给人看(`FormRenderer.runRowFetches`,一张表把所有行的
补丁攒完再一次性写回——逐行各写一次会把前面几行的结果冲掉,`model` 是 props 上的 computed),
提交时 `fetch.apply_form` 走 `_apply_rows` 按同一份配置逐行再取一次并覆盖,接口直传与前端篡改
都塞不进假值。跑的是 `data` 里当前那几行:被人删掉的行不会再取一次,新加的那一行当场补得上。
删列时指向它的带出一起清(`utils/formPrune` 按这张表剩下的列名滤 `picks`,那句「掉在地上的指向」挂在 `列名.带出键名` 上)。
**仍然没做**的是「一次查询填整张表」(结果集控件,见
[sql-autofill-design.md](sql-autofill-design.md) §6 第 4 条)。这一档是**一行一调**:
十行就是十次外呼,再叠 `revalidateAfter` 就是十次乘以刷新次数,数据源上的缓存 TTL 与
`rate_limit_qpm` 要先抬到量级上(面板上那句每分钟约 N 次的提醒是同一件事的另一半)。
真需要「一次查一批、每行装进一格」,那是新形态,得单独设计。
验收:`PYTHONPATH=. python3 scripts/check_row_fetch.py`(34 条:逐行取数与覆盖、入参作用域、
带出去向只认本表、点行号的报错、整表隐藏时降级、留痕形状、设计期那几道闸门),前端
`utils/formFetch.rowFetch.spec.ts`、`FormRenderer.rowFetch.spec.ts`、
`design/FieldInspector.columnFetch.spec.ts`、`utils/formPrune.spec.ts`。
## 10. 落地清单
### P0 字典与镜像(不写新机制,先消化六成需求)
@ -664,6 +719,9 @@ CREATE TABLE oa_data_source_call (
```bash
# 外部取数验收(自建外部数据源桩 + 临时库 unisoa_fetchtest,跑完自动删,不碰开发库)
python3 backend/tests/oa_fetch.py
# 明细列逐行取数(§9.2:内存库 + 假上游,不建库、不打真接口,秒级)
cd backend && PYTHONPATH=. python3 scripts/check_row_fetch.py
```
桩服务这次没单独成文件:假上游是 `tests/oa_fetch.py` 里的 `Upstream` 类

View File

@ -59,7 +59,7 @@
| `attachment` / `image` | 附件 / 图片 | 附件对象数组 | ✓ | 只判空 | 可配允许类型 / 个数 / 单个大小,见 §2.3 |
| `signature` | 手写签名 | PNG 的 data URL | ✓ | 只判空 | 导出只落「已签名」 |
| `relation` | 关联审批单 | 对方单据的 job | ✓ | 只判空 | 认得它但**不单列一格**:它就是「下拉选择 + 来源=流程单据」 |
| `table` | 明细表 | 行对象数组 | ✗ | 比列 | 列类型见 `TABLE_COLUMN_TYPES` |
| `table` | 明细表 | 行对象数组 | ✗ | 比列 | 列类型见 `TABLE_COLUMN_TYPES`;只读那一屏收不收折由 `readonlyStyle` 说(§2.9),一列能配的东西与主表字段同权、最多一行自动补(§2.10),列上也能挂外部取数、一行问一次(§2.12) |
| `auto` | 系统带出 | 按带出的键 | ✗ | 文本 | 生成规则见 `service/numbering.py` |
| `group` | 分组标题 | **无值** | ✗ | — | 见 §2.4 |
| `divider` | 分割线 | 无值 | ✗ | — | |
@ -182,14 +182,291 @@
把它算进"要摆挑选方式那一栏",`carriesOptionSource` 仍然不算它——那一句只管候选来源那四类。
明细表那一列同理,列上也能挑;明细格子里永远不给摊开(一行的高度放不下一个盘子)。
### 2.8 明细表那一列锁得上:`column.readonly`
用户那句原话是「表单的明细表中的字段,无法设置不可编辑」。查下来缺的不是运行时的判据,
而是**设计器里的入口**:列上那份 `column.readonly` 一直有人认(填单那一屏把它递给录入控件),
可界面上唯一能改它的地方是「自动带出」底下那颗**「带出后允许填写人修改」**——没配带出的列
压根锁不上,配过的列也只能反着说(勾上=不锁)。
现在明细列卡的第一行跟主表一样摆了「只读」,与必填并排(标题 / 类型 / 标识 / 必填 / 只读 / 删除
钉死在第一行)。三处读写的是**同一份** `column.readonly`,不另发明第二个标记:
| 谁 | 认这一份的哪一句 |
| --- | --- |
| 填单那一屏(桌面与手机同一只组件) | `FormRenderer` 把 `column.readonly` 递给 `FormFieldControl`,锁着的格子出只读态那一支;表头挂一枚锁(为什么点不动)+ 那一列铺一层底色(哪几格点得动) |
| 设计器 | `FieldInspector` 列卡上那颗「只读」+「自动带出」底下那颗「允许填写人修改」(反着说,仍写同一格);写了本行公式那一列的锁勾死解不开(公式列没有录入框)——§2.11 之后有出口:勾了「公式带入后允许修改」的那一列有框,锁也解得开 |
| 提交那道闸 | `formruntime._row_problems`:**锁着的列不卡必填**,那一格里已经躺着的值照旧过格式那几关 |
**锁上之后必填要让路**,理由是同一句老话:必填卡的是人,而锁着的列根本没有录入框——那一格的值
归默认值 / 自动带出 / 关联带出 / 额度台账给,人改不动却永远被催「还没填写」,这张单就地卡在这一环,
跟「屏幕上没有那一格,却说请先填写它」是一种坏法。所以锁着的列不摆红星、属性面板里必填那颗灰掉
(勾还留着,解开锁就回来)。三条分寸:只让「必填」这一条;只认 `readonly` 这一个标记(写了本行公式
那一列没勾只读,公式算不出值仍是配置坏了,照旧拦);**整张明细表那一层的环节权限一个字没动**——
环节把整张表设成只读走的还是 `effective_perm`(`FormRenderer.isLocked`),列上这一层只在表本来摊开
给人填时说话。
**锁着的列管的是"人改不改得动",不管"这批值收不收"**:提交时按环节权限过滤写入的是
`formruntime.editable_keys`,粒度是整张表(那一列的值由开放接口或脚本直接写进来,不会被这一层挡)。
设计器在**锁着又没配任何值的来路**时会当场说一句(`columnLockedWithoutSource`:默认值 / 自动带出 /
本行公式 / 关联带出的目标列 / 额度逐行控写的那几列都算来路),因为那一列从此谁也填不进东西。
钉在 `FieldInspector.column-readonly.spec.ts`、`FormRenderer.tableCellReadonly.spec.ts` 与
`scripts/check_table_column_readonly.py`。
### 2.9 明细表提交之后可以先收着:`readonlyStyle`
用户那句原话是「表单中的明细表在填写的时候是展开状态,流程提交后我希望明细表都是收折的状态,
给我一个地方可以配置」。缺的不是渲染能力(只读那一支本来就会把整张表画出来),而是**没有那个地方**:
一张报销单摆两三张明细表,审批人进来先翻三屏表格才找到自己的签名框,而设计者对此一个字都说不上。
配置落在**明细表那一格身上**(`field.readonlyStyle`),入口是属性面板明细表那一支的「流程提交后的展现」:
| 档 | 只读那一屏(提交后 / 审批环节看单 / 已办 / 单据详情) | 填单那一屏 |
| --- | --- | --- |
| 留空 / `expanded` | 整张摊开,**连段头都不多摆一行**——存量表单的画法一个字不变 | 摊开 |
| `collapsed` | 先给一行段头「共 N 行 · 合计 X」,点它才摊开,再点收回 | 摊开 |
四条分寸是刻意的:
1. **只管读**。填单那一屏永远摊开:收着的表里没有录入框,人没法往里敲字,
把这一档做成"什么时候都收"就等于把明细表变成一个不能填的东西。判据
`utils/formRuntime.ts:tableReadonlyCollapsed` 只在 `FormRenderer` 只读那一支被问一次。
2. **打印那一份永远摊开**。纸上没有"点一下摊开"这回事,收着的那些行等于根本没印出来,
而缺的那一半在纸面上看不出缺——这一条比"看着清爽"重要。判据复用现成的 `flattenTabs`
(打印页是唯一传它的地方),不另发明第二个"这是打印"开关。
3. **人手动点开那一份不写回表单**。段头上的开合记在组件里(字段名 -> 这一刻摊开与否),
换一张单、刷一次页面就回到配置说的那一档:审批人点开看一眼是他这一趟的事,
不该顺手把全公司以后看单的样子改掉,更不该因为谁点一下就把表单定义弄脏。
4. **只认一处渲染**。全项目只读明细表的画法只有 `FormRenderer` 那一份(桌面、审批详情、
单据详情、介入面板、试跑弹窗共用),所以这一档配一次就在所有只读屏生效;
明细列 / 行数 / 环节权限那三套口径一个字没动。
**手机端不吃它**:那边早有自己那一档——`MobileFieldStyle` 的 `card`(收成一行,点开逐条)
与 `list`(在节里逐条摊到底),且明细格默认就是 `card`。两份开关各说一件事(手机看的是配好的版式,
电脑看的是这张表在只读屏的默认开合),不互相覆盖,免得同一件事两处各说一遍。
钉在 `FormRenderer.tableReadonlyStyle.spec.ts`(四屏各是什么样)与
`FieldInspector.tableReadonlyStyle.spec.ts`(只有明细表摆这一栏、挑回默认那档就把键摘掉、
换类型收掉残骸)。这一档是纯展现,后端不读它,`clean_formats` / `clean_option_source`
也都不收它(不在 `FORMAT_KEYS` / `LIMIT_KEYS` 清单里),存下去就是字段上一个键。
### 2.10 明细列与主表字段同权,最多一行的表先把那一行摆好
用户那两句是「明细表里面的列,我希望也可以和主表字段一样可以进行各种配置」与「明细表最多只有
一行的时候,我希望可以自动帮我带出一行」。
先说结论:**一列就是一个字段**。查下来缺的不是运行时的判据——`FormRenderer` 把列上那份对象原样
递给 `FormFieldControl`,所以列本来就认得 `placeholder` / `maxLength` / `pattern` / `min` / `max` /
`accept` / `cascadeFrom` 这些键,只是设计器里没地方写。于是这一轮**没有另发明一套"列配置"的
schema**:配置全写在列上那一份对象上、与主表**同一个键名**,补的是入口和那两道闸。
| 一列能配的 | 写在哪 | 谁读它 |
| --- | --- | --- |
| 占位提示 | `column.placeholder` | 同一只录入控件(列与主表共用的那只),填进去就是原生 `placeholder` |
| 列说明 | `column.help` | 表头列名后那一枚提示(`table-column-help`),指针停在列名上就出,不占格子高度 |
| 字数上限 / 校验正则 | `column.maxLength` / `column.pattern` | 界面上 `maxlength` 挡体验,提交那道闸判(`value_problems`,正则仍**整格**匹配) |
| 取值上下限 | `column.min` / `column.max` | `<input type="number">` 只标红不拦人,提交时 `_range_problem` 按同一份上下限再判一次 |
| 步长 | `column.step` | 只摆给数字列:原生数字框的箭头与滚轮每次调多少,留空 = 浏览器那个 `any`(金额那只框自己钉了 0.01,没这一栏) |
| 附件三个限制 | `column.accept` / `maxFiles` / `maxSizeMb` | 上传前 `AttachmentUploader` 挡,提交时 `_file_problems` 判 |
| 级联自 | `column.cascadeFrom` | 本表另一列选了什么,这一列的字典项只留它下面那几项 |
| 隐藏此列 | `column.hidden` | `visibleTableColumns`:填单与看单两支都连表头都不摆(第三段单说) |
| 列宽 / 对齐 / 合计 | `column.width` / `align` / `aggregate` | 表格自己那三样,第二段单说 |
| 外部取数(逐行) | `column.fetch` | 与主表那一格同一套配置与执行器,按行各跑一次,见 §2.12 |
**入口收在「更多配置」里,但收了也念得出。** 列卡第一行仍是钉死的那几样(标题 / 类型 / 标识 /
必填 / 只读 / 删除),外加新摆的**上移 / 下移 / 复制**——以前调一次列序等于删了重加。其余那一长串
收进一个折叠栏(`column-more-toggle`),规矩跟侧栏 `SidePanel` 一样:**门关着时,入口那一行就是
唯一的可见状态**,所以配过几样写在角标上(「已配 2 项」),且只数这一列类型用得上的那些(步长只数数字列
那一格,金额那只框压根没这一栏)——换类型
该收掉的残骸不占位置,否则人以为配过什么,其实那一栏压根没摆出来。用不上的格子干脆不摆:归本行
公式算的那一列没有录入框,占位提示与上下限轮不到它;文本列的合计只有「不合计」与「计数」两档。
换列类型时带走不走的旧配置一并清掉(`changeColumnType` 收展现格式、字数与正则、附件限制、级联、
合计那几群),与主表 `changeType` 同一份清单,后端 `clean_formats` 对明细列做的是同一件事——
留下的老写法会藏在新控件底下继续生效。
**表格自己那三样是纯展现,不进提交那道闸。**
1. **列宽** `width`:这一列的**最小**宽度(自动 + 96/120/160/200/260/320/400 七档),表头那行字
放不下时还会再宽一点,整张表超出容器仍走横向滚动。判据 `columnMinWidth`;没配过的列照类型自动
分配,存量表单一个字节都不动。
2. **对齐** `align`:`auto`(不写类,跟着表格默认靠左)/ 靠左 / 居中 / 靠右。判据 `columnAlignClass`。
3. **合计** `aggregate`:求和 / 平均 / 最大 / 最小 / 计数,选中的列在表尾多摆一行念这个数
(`TableAggregateRow.vue`)。非数与空格子不进统计,小数位跟着那一列自己的 `precision` 写;
计数那一档任何列都能配,其余四档只认 `number` / `money`——给文本列配求和会算出一堆 0,
所以界面上压根不摆那几档,后端也拦。段头(§2.9 收折那一行)上原本的「合计 X」现在**优先听
点名**:哪一列显式配了 `sum` 就念哪一列,没配才回落到「第一个数字列」,且标签与数字问同一列——
以前不点名,段头写着「运费」、念的却是「金额」那一列的数。
这三样后端只在**设计期**判配置本身认不认识(列宽在 60-640px 之间或留自动、对齐与合计是合法值、
那四档没配在非数字列上、`min` 不大于 `max`),一个字不进 `validate_submit`:它们不改任何一格的值。
**`hidden` 这一样只管屏幕上摆不摆,得说清。** 藏起来的列连表头都不出现,但值照常保存、照常导出、
照常参与本行公式与关联带出,也**不卡必填**——`column_not_for_people`(勾了只读、整列藏起来,两样
都是"人改不动这一格",而必填卡的是人,与 §2.8 同一把尺子)。红星不摆、表头宽度也不给那颗星留位,
属性面板里必填那颗灰掉(勾还留着,取消隐藏就回来)。设计器在**藏着又没配任何值的来路**时会说一句
(默认值 / 自动带出 / 本行公式 / 关联带出 / 额度逐行控写都算来路):那一列从此谁也填不进东西。
这一样是给机器留的——项目编码、物料 ID 那类"带出来给公式和回写用、人不需要看"的列。
手机端那一份读单(`components/oa/mobile/useFormPlan.ts`)跟着同一份口径:藏着的列不进逐条那几行,
摘要那一行「合计 X」也优先念列上点了求和的那一列——同一张单子在电脑上念一个数、在手机上念另一个数,
比两边各念各的更让人不敢信。钉在 `useFormPlan.spec.ts`。
**最多一行的表自动带出那一行。** `maxRows === 1` 的明细表压根没有"再加一行"这回事(右上角那颗
`+` 一到一行就灰了),可格子还是得点一下 `+` 才出现——一张空表看着就像不能填。现在进这一屏就补
一行,补的这一步与点 `+` **走同一条路**:同一份 `emptyRow`、同一份 `rowSeed`、同一遍
`applyRowFormulas`,所以默认值、自动带出、本行公式都按老口径落,不多算一次也不少算一次。三条边界
是刻意的:只在**填单那一屏**补(只读态与打印不许给单据添行);环节把这张表设成只读、或整格藏起来
时不补(那一屏根本没有录入框,补出来的行只是把 `data` 弄脏);落库前 `normalise_rows` 照旧把一格
没填的空行剔掉,所以补出来的那行没人碰,也不会多存一条空记录。设计器在「最多行数」那一栏下说破
这件事(`table-single-row-hint`),别的行数不啰嗦。
钉在 `FieldInspector.columnMore.spec.ts`(角标数几样、每一样写进列上哪个键、用不上的格子不摆、
换类型收残骸、列序与复制)、`FormRenderer.tableColumnDisplay.spec.ts`(藏着的那一列数不出来、
列宽与对齐落到 `<th>`/`<td>` 上、表尾念的数、最多一行自动补)、`formRuntime.tableColumnConfig.spec.ts`
(判据本身)与 `scripts/check_table_column_config.py`(21 句:藏着的列不卡必填、上下限提交时判、
格式那几问不再跟着必填走、列宽对齐合计只在设计期判)。
### 2.11 公式带进来的那个数可以让人改:`column.formulaEditable`
用户那句原话是「表单中明细表中引用公式带入的值,为什么不能编辑?我需要可编辑」。查下来这不是
坏掉,是**一直以来的有意画法**:列上一写公式,那一格同时失去两样东西。
1. **屏幕上没有录入框**——`FormRenderer` 认 `column.formula` 那一支,摆的是一句现算的文本
(`cellFormulaText`),判据是 `columnHasNoInput`(§2.8、§2.10 那把尺子加一句"归公式算")。
2. **数据上守不住**——`applyRowFormulas` 每轮改动都把这一列整列重算,主表那一格一动,
`rowFormulaSignal` 那道 watch 还会再重算一遍。就算界面上硬塞一个框,敲进去的数也会在
下一轮重算里被盖回公式那个。
**只补第 1 件的功能是假的**(改得动、留不住,比不让改更气人)。所以这一档两件事一起管,落在列上
一个新键 `formulaEditable`:**没写 = 老画法**,几百张存量表单的明细表一个字不变。
| 谁 | 认这一档的哪一句 |
| --- | --- |
| 填单那一屏(桌面与手机同一只组件) | `columnFormulaEditable` 为真 → 那一格出 `FormFieldControl`,公式先把数摆在框里;表头从一枚锁换成一枚 `fx` |
| 重算 | `applyRowFormulas` 跳过"这一列点了这一档 **且** 行上躺着凭据"的那一格,其余照旧整列重算 |
| 设计器 | 列卡「本行公式」底下那颗「公式带入后允许修改」;公式一清空这一档跟着撤掉;这一档生效后那枚「只读」锁也解得开了 |
| 提交那道闸 | **一个字没动**:那一格现在有框了,必填照卡、值照过格式那几关;公式列的默认值照旧不复活 |
**凭据落在行上**:`row._manual = ['payAmount']`(列标识的数组),与关联带出那一份 `_link` 同一层,
下划线开头 = 导出、打印、明细导出都看不见它。它必须一路不丢才算数:编辑中的整型
(`trimRows` / `normaliseRows`)与落库前的整型(后端 `formruntime.normalise_rows`)都把它跟
`_link` 一起留着,否则下一环的人重新打开这张单,昨天改的数就悄悄变回公式算的那个。
三条分寸是刻意的:
- **只豁免改过的那一格,不豁免整列**。没动过的格子照旧跟着公式走,主表那个运费一涨,
没人碰过的那几行该变的还是变。
- **清空那一格 = 交回公式**,行上那颗「恢复公式值」(`formula-reset-*`)点一下走的是同一条路:
撤凭据 + 重算。手工覆盖一旦没有退路,比不让改更难用。
- **锁与隐藏压过这一档**。`columnNotForPeople`(勾了只读、整列藏起来)在前,`formulaEditable`
在后,判据只 `columnFormulaEditable` 这一处,填单与设计器读同一把尺子;属性面板里那一档
在已勾只读时灰着点不动,并说一句为什么。
**这一列的数仍然只有前端会算**(`compute_formulas` 只管主表 `type=formula` 那一格),所以走接口
直接提交的单子得自己把这一列算好——这一点与公式列一直以来的规矩相同,`tableColumnFormulaHint`
里那句"由前端算"没说两遍。钉在 `formRuntime.formulaEditable.spec.ts`(判据本身、凭据一路不丢)、
`FormRenderer.formulaEditable.spec.ts`(那一格真是录入框、改过的那一格不被盖回、清空与恢复都交回公式、
没点这一档仍是文本)、`FieldInspector.columnFormulaEditable.spec.ts`(这一档只写一个键、公式
清空就撤、锁解得开)与 `PYTHONPATH=. python3 scripts/check_table_formula_editable.py`(12 句:
凭据不丢、这一档不锁列也不放宽校验、默认值没复活、设计期不报错)。
### 2.12 明细列也能逐行取数:`column.fetch`
用户那句是「明细表中的字段是否可以配置取数,取我配置的外部数据源」。真实场景:收款明细每
一行填了收款人,开户行与银行帐号要按**这一行那个人**去 ERP 查。以前只有主表字段挂得上
`fetch`(`fetch_fields` 见着 `type == "table"` 就跳过),列上那一格只能人填或走关联带出。
**没有新键**:列上写的那份 `fetch` 与主表字段是同一个形状、同一个执行器(`binding.entries`
那一套多源 / `merge` / `args` / `picks` / `onError` / `revalidateAfter` / `freezeAfterStart`),
只是**逐行各跑一次**,值写进这一行的这一列。挂不得上走的是同一句 `canCarry(type,'fetch')`
——装得下一个数或一句话的那些列能挂(文本、多行、数字、金额、日期时间、月份、年份、手机、
邮箱、身份证、网址、下拉、单选、评分),多选 / 部门 / 附件 / 日期区间 / 开关那几类主表本来就
挂不上,列上同样挂不上。归本行公式那一列没有录入框,配了也没人看得见。
| 谁 | 认这一档的哪一句 |
| --- | --- |
| 设计器 | 列卡「更多配置」底下那块「外部取数」,用的就是主表那只 `FetchPanel`。「带出去向」的下拉**只有这张表的其它列**;配完之后角标上「已配 N 项」把它算一样(`columnExtraConfigs` 数了 `fetch`);这一列勾了「只读」而没配来源那句黄字提醒,在配了取数之后自动收声——那一格的答案是查出来的,本来就该锁着 |
| 入参读哪一格 | 作用域 = 整张单 + 这一行,**与主表字段同名的列以本行为准**,`{form.x}` 既能读主表也能读本行的列。跟本行公式(`applyRowFormulas`)吃的是同一份作用域,配的人不用记第二套写法 |
| 带出去向落哪 | 只落这张明细表的其它列。写主表那一格等于让最后一行去盖表头:三行的表盖三次,谁赢看运气 |
| 填单那一屏 | `FormRenderer.runRowFetches` 按行各取一次给人看,一张表攒完补丁再一次性写回(逐行各写一次会把前面几行刚取回的那份按旧快照盖掉)。「多久算旧」到点重取按行各算一份——入参指纹的键是 `表名#行号#列名`;`freezeAfterStart` 那一档逐行一起冻结 |
| 提交那道闸 | 后端 `fetch.apply_form` → `_apply_rows` 按同一份配置逐行再取一次并覆盖,前端塞不进假值;跑的是 `data` 里当前那几行——删掉的行不再取一次,新加的那行当场补得上 |
| 取不到数怎么报 | 「明细表「收款明细」第 2 行的「银行帐号」的外部数据取不到:ERP 连接超时」。整张表在这一环被藏起来时 `onError=block` 降级成不挡(环节权限挂的是表不是列),取数照发、留痕照记 |
| 留痕 | `data["_fetch"]["收款明细.bankAccount"]`,底下 `rows: [{row:1,…},{row:2,…}]`。键必须是「表名.列名」——两张表可能有同名列,同一列每一行都得留得开 |
| 删列 | 删掉一列时指向它的 `picks` 一起清(`utils/formPrune` 按这张表剩下的列名滤,那句「掉在地上的指向」挂在 `列名.带出键名` 上);运行时也只往还在的列写,与主表那几处共用同一把闸(`binding.live_target`) |
三条分寸是刻意的:
- **行的增减还是人说了算**。这一档是"已有的 N 行各自去问一次",不是"一条查询生出 N 行"——
后者(结果集控件)仍然没做,边界见 [sql-autofill-design.md](sql-autofill-design.md) §6 第 4 条。
- **一行一调**。十行十次外呼,再叠 `revalidateAfter` 是十次乘以刷新次数,数据源上的缓存 TTL
与 `rate_limit_qpm` 要先抬到量级上。
- **权威在服务端**,与主表那一格同一条红线:外部回来的值只提供一个值,不决定流转。
方案与更细的口径在 [form-data-integration-design.md](form-data-integration-design.md) §9.2。
钉在 `PYTHONPATH=. python3 scripts/check_row_fetch.py`(34 句:逐行取数与覆盖、入参作用域、
带出去向只认本表、点行号的报错、整表隐藏时降级、留痕摊得开行号、设计期那几道闸门)与前端
`formFetch.rowFetch.spec.ts`、`FormRenderer.rowFetch.spec.ts`、
`FieldInspector.columnFetch.spec.ts`、`formPrune.spec.ts`。
### 2.13 选择类字段能挂好几套候选来源:`optionRoutes`
用户那句是「我一个组件中为什么不能配置多个外部数据源、数据字典等等,我通过表单中字段来判断
我该组件中该用什么数据源」。以前 `optionSource` 是一维一答,换一家只有摆三格 + 显示条件
(三个字段名 = 三份导出列 + 三套环节权限)或者去对面求一个聚合接口。
**没有新字段类型、没有新接口**:字段上多挂一份有序清单 `field.optionRoutes`(最多 8 条),
每一条 = 一个触发条件(`when`,与 `visibleWhen` 同一份结构化条件)+ 一套候选来源配置
(`dict` / `dataSource` / `process` / `manual` 各带自己那几格)。自上而下第一条成立的用它,
一条都不成立**回落到字段自己那一份**——老表单没挂清单,走的正是这条路,一个字节不用改。
同一寸在「取一个值」那一头也有:`fetch.sources[].when`(单源老写法也能挂)。
| 谁 | 认这一档的哪一句 |
| --- | --- |
| 设计器 | 多选那几格「同一个字段的几家」(各挂一条「某字段 = 某一个值」)时,属性栏给一颗「**并成一格**」:条件搬进清单、来源各归各条、指着旧名字的带出跟着搬(`utils/formMerge.ts`,判据不新增)。单格配置在属性侧栏「候选来源」下面那一栏「同一格换一家候选」(`design/OptionRoutesEditor.vue`):挑一格点「一家一档」,它有几个取值就铺几条卡片、条件替写好;外部那几家在第一家的卡片里配好带出后点「套给其余几家」;字典那一条上那颗按钮直接把人送到「字典带出」那块。「外部取数」面板里每条源还多一颗「什么时候调这一条」 |
| 渲染与取候选 | 先摊成一张**视图**再喂给既有函数:前端 `optionSource.optionFieldView` → `formLinkage.effectiveOptions`,后端 `dicts.option_view` → `dicts.effective_options`。视图只换来源那一维,`pickerStyle` / `multiple` / `linkFill` 原样留着 |
| 判越界 | 跟着**命中那一条**走:`constrainsValues(field, data)` ↔ `dicts.constrains_values(field, data)`。这一分钟是字典(要把关)、下一分钟可能是外部数据源(不把关) |
| 字典带出、翻名字、级联筛候选 | 全部读视图,所以取的是命中那一本的附加值与那一条自己的「显示 / 存值」;命中那一条不是字典时字典带出一个字都不写 |
| 预取与删前检查 | 路由里那几本字典一起进预取清单(`codes_of`),也算「哪些表单在用」(`dicts.used_by_forms` / `fetch.used_by_forms`);漏一处就是删掉一把只挂在路由里的字典、那一格当场空 |
| 上游 | 路由的 `when` 与那一条的 `cascadeFrom` 并进 `conditionDependencies` / `condition_dependencies`,那一格一改就重算候选与失效值 |
| 保存那一刻 | `api/design.py:clean_option_source` → `dicts.clean_routes`:每条只留属于它那一种来源的那几格、全勾状态不留、第 9 条起截掉、一条不剩把键抹掉;主表字段与明细列同一句。挂了这份清单也算「这一格有候选来源」——那道「选项类字段未配置任何选项」不再拦它(`form_problems` ↔ `validateFields` 两边同一口径),因为「先选分类再问那一家」的那一格常常故意把自己那一份留空 |
| 脏条目 | **当没配**:认不出的来源、空条目一律丢掉,宁可回落,也不留一只永远为空的挑选器 |
那一条候选还能自带一份**带出**(`optionRoutes[].fill`,只给外部数据源那一条):「换一家」
从来不只是换一份候选清单,而是换一整套答案——挑的是 ERP 那家供应商,开户行与信用额度就得回 ERP 查。
以前要配出这个结果得把同一条判据抄两遍(候选那一格写「差旅问 ERP」,取数条目再写一遍),漂开的
症状最难查:**候选换了家、带出还是上一家的**。现在那一条自带「问哪一家 / 带什么入参 / 哪几个键写进
哪几格」,后两样留空就跟着这一条走;运行时摊成一条普通的取数条目丢给同一个执行器(同一个入参写法、
同一份留痕、同一档 `onError`),只多一个 `fillOnly` 记号——**只写「带出去向」那几格,绝不盖这一格
刚被人在候选里挑中的那一个值**;一条都不成立或命中的那条没自带,照旧读字段上那份 `fetch`。
**字典那一家走 `autoFill`、流程单据那一家走 `linkFill`**,那两条本来就跟着各自命中的对象走,
不再各挂一层。所以「一家外部数据源 + 一家数据字典」这一对最常见的配法是各写各的:外部那一条在卡片里
配「这一家的带出」,字典那一条在「联动」面板的「字典带出」里配。带出读的是**命中那一本**字典的附加值
(`applyAutoFill` ↔ `apply_auto_fill` 都先摊视图),命中那一条不是字典时一个字都不带;字段自己没挂
字典、路由里挂着字典时 `autoFill` 不再被当上一家的残骸洗掉,两处都没字典才洗掉并说一句「这一档不起
作用」;那一栏现在对「只有路由挂字典」的格子也出现,能带哪些列是那几本附加值列的并集。见
[option-source-routing-design.md](option-source-routing-design.md) §5.1。
界面上是那张卡片下面多出一栏「这一家的带出」,设计期门牌写「第 N 条候选来源的带出」。
顺带两档都在这轮补上(同一批反馈):`field.allowOutsideValue`(带回来的值不在候选里也收下,
默认关;勾上之后页面不清值、提交不判越界、界面上补一行「带出」候选);回看那一屏改为按
存过的那份值评条件、**因显示条件不成立**被收走的必填格不再卡提交。
方案、为什么以前只能一个、以及保留的那一寸,见
[option-source-routing-design.md](option-source-routing-design.md);钉在
`PYTHONPATH=. python3 scripts/check_option_routes.py`(不碰库)、
`PYTHONPATH=. python3 scripts/check_option_route_fill.py`(那一家的带出)与前端
`optionSource.routes.spec.ts`、`formFetch.when.spec.ts`、`FormRenderer.optionRoutes.spec.ts`、
`design/OptionRoutesEditor.spec.ts`、`design/FetchPanel.when.spec.ts`、`optionSource.fill.spec.ts`、
`formFetch.routeFill.spec.ts`、`design/OptionRoutesEditor.fill.spec.ts`(带出那一栏的接线),
改名与删格子时跟着搬的落点在 `formRename.spec.ts`、`formPrune.spec.ts`。
## 3. 配错了在哪一步说
| 时机 | 判什么 | 在哪 |
| --- | --- | --- |
| 设计器保存 | 类型不认识、纯排版勾了必填、该不该有标题、正则编译不过、字数上限离谱、附件三个限制越界、空白高度出格、明细列类型不支持、外部页面没挑页面 / 页面被删 / 参数是那个页面用不上的、标签页没配页 / 页签没名字 / 页签标识重复 / 外部页面那一页上还压着格子 / 摆了不止一个标签页 | 前端 `utils/formLayout.ts:validateFields` 与 `utils/formRuntime.ts:embedConfigProblems`;后端 `formruntime.validate_schema`(含 `embed.problems`)+ `api/design.py` 的字段校验 |
| 设计器保存 | 类型不认识、纯排版勾了必填、该不该有标题、正则编译不过、字数上限离谱、附件三个限制越界、空白高度出格、明细列类型不支持、外部页面没挑页面 / 页面被删 / 参数是那个页面用不上的、标签页没配页 / 页签没名字 / 页签标识重复 / 外部页面那一页上还压着格子 / 摆了不止一个标签页、**明细列**那几样新的:列宽不在 60-640px 也不是「自动」、对齐与合计的写法不认识、非数字列配了求和(§2.10)、上下限写反;**列上那份 `fetch` 与主表同一套闸门**(§2.12):源不存在 / 已停用、入参引用了不存在的格子、带出去向落到主表字段或落到自己 | 前端 `utils/formLayout.ts:validateFields`(明细列那一串走 `utils/formRuntime.ts:validateTableField`)与 `utils/formRuntime.ts:embedConfigProblems`;后端 `formruntime.validate_schema`(含 `embed.problems` 与 `column_display_problems`)+ `api/design.py` 的字段校验 |
| 保存落库前 | 换了类型就收掉上一类留下的配置:展现格式按 `FORMAT_OWNERS`,限制按 `LIMIT_OWNERS` | `api/design.py:clean_formats` |
| 填单时 | `maxlength`、`accept`、个数与大小、年份与月份的原生控件 | `FormFieldControl` 与 `AttachmentUploader`(只为体验,不是闸门) |
| 提交时 | 必填、正则(**整格**匹配)、长度、月份/年份写法、多选月份那串里每一项的写法、星期取值、时间段与日期区间的先后、附件类型/个数/大小 | 后端 `formruntime.validate_submit`(主表 `value_problems`,明细行 `_row_problems`) |
| 提交时 | 必填、正则(**整格**匹配)、长度、月份/年份写法、多选月份那串里每一项的写法、星期取值、时间段与日期区间的先后、附件类型/个数/大小、**数字与金额的取值上下限**(界面上只标红,拦不住人)。列上配了逐行取数的,这一趟**先按同一份配置逐行重取再判**(§2.12)。明细行里**锁着(`readonly`)或藏着(`hidden`)那一列不卡必填**(§2.8、§2.10),已躺着的值照判;而且格式那几问**不再跟着必填走**——以前整段套在「没勾必填就跳过」里,于是非必填的列填什么都没人看,那三道限制等于只在浏览器里说了算 | 后端 `formruntime.validate_submit`(主表 `value_problems`,明细行 `_row_problems`,两者同一份判据) |
| 只读 / 打印 / 导出 | 每一类念成一句人话 | `FormFieldControl` 只读那一支、`api/export.py:cell_text`、`service/titles.py:_field_text`。`embed` 无值,导出与打印里天然什么都不落——那条地址上挂着一次性免登短码,落进导出件等于把钥匙抄进表格 |
正则按 `fullmatch` 判:半匹配会让 `\d{6}` 放过 `abc123456def`,配的人以为挡住了、其实没挡。
@ -219,6 +496,11 @@
| 值形状与必填 | `utils/formRuntime.ts` | `service/formruntime.py` |
| 能挂什么面板、能比什么 | `utils/fieldCapabilities.ts` | `service/threshold.py` + `service/quota.py` |
| 明细列能用哪些类型 | `types/index.ts:TABLE_COLUMN_TYPES` | `service/formruntime.py:TABLE_COLUMN_TYPES` |
| 明细列锁不锁(只读) | 一份 `column.readonly`:`FieldInspector` 那两处的开关 + `FormRenderer` 递给录入控件 | `service/formruntime.py:_row_problems`(锁着的列不卡必填) |
| 明细列能配什么(与主表同权) | 一份 `column.*`:`design/FieldInspector.vue` 列卡那一栏「更多配置」+ `utils/formRuntime.ts`(`visibleTableColumns` / `columnNotForPeople` / `columnHasNoInput`) | `service/formruntime.py`:`_row_problems`(藏着与锁着都不卡必填、格式照判)+ `column_not_for_people` |
| 明细列在表格上怎么摆(列宽 / 对齐 / 合计) | `types/index.ts:TABLE_COLUMN_WIDTHS` / `TABLE_COLUMN_ALIGNMENTS` / `TABLE_COLUMN_AGGREGATES` + `utils/formRuntime.ts:columnMinWidth` / `columnAlignClass` / `columnAggregate` | `service/formruntime.py:COLUMN_WIDTH_MIN`~`MAX` / `COLUMN_ALIGNMENTS` / `COLUMN_AGGREGATES`(`column_display_problems` 只在设计期判) |
| 最多一行的表自动补那一行 | `FormRenderer.vue:singleRowTables`(与点「+」同一份 `emptyRow` + `rowSeed` + `applyRowFormulas`;只读、锁着、整格藏起来的表不补) | —(`normalise_rows` 照旧剔空行,后端不必知道这件事) |
| 明细表只读那一屏收不收折 | 一份 `field.readonlyStyle`:`FieldInspector` 那一栏 + `utils/formRuntime.ts:tableReadonlyCollapsed`(只读那一支问一次,打印走 `flattenTabs` 强制摊开) | —(纯展现,后端不读,两个 clean 都不收这一键) |
| 条件里的控件与比较符 | `utils/routeExpression.ts` | `engine/conditions.py` |
| 空白格之外谁必须有标题 | `utils/formLayout.ts:LABELLESS_TYPES` | `api/design.py:LABELLESS_TYPES` |
| 有哪几页、谁在哪一页 | `utils/tabPages.ts`(含伪装给 iframe 那一格的 key 口径) | `service/tabpages.py`(同一份措辞与页数上下限) |

View File

@ -244,3 +244,73 @@ parallel/merge/split #7c3aed 紫 script/invoke/embed #2563eb 蓝 delay #0891b
还有一处已知的小瑕疵,改动很小但先记在这里:级联的多个下拉之间不会互相关闭,
快速连点两级时屏幕上可能同时挂两个浮层。正常的「点外面关闭」已经够用,
等把 `.tool-btn` 收到全局时一并处理。
## 15. 浏览器兼容口径(IE 与老内核)
带出值、回显、金额与日期这些"给人看的东西"最容易踩的坑是**只在开发机上对**。
这一节把口径写死:支持到哪一档、缺的东西由谁补、补不出来的怎么收场。
| 引擎那一档 | 判据 | 这套界面怎么样 |
| --- | --- | --- |
| 现代浏览器(近两年的 Chrome / Edge / Firefox / Safari) | `Proxy` + `Symbol` + CSS 变量齐 | 正常 |
| 有 `Proxy` 的老内核(Edge 15-18、Safari 10+、Chrome 49+、Firefox 45+) | 同上,但缺 ES2016~ES2020 的内置对象 | 由 `src/utils/legacyCompat.ts` 就地补齐后照常跑 |
| IE 11 及更早、Edge 的「IE 模式」 | 没有 `Proxy` | **跑不起来**,这是 Vue 3 的地基,补不出来。`index.html` 那道闸门给一句人话,不让它空转骨架屏 |
补不出的那几位不是遗漏,是没法补:Vue 3 的响应式压在 `Proxy` 上,而 `Proxy` 没有
polyfill 的可能(拦截属性读写这件事必须在语言层做);Tailwind 那整套色板压在 CSS 变量上,
IE 也不认。所以给 IE 只承诺两件事——**看得懂的提示**与**别把用户晾在转圈的骨架屏上**。
`<meta http-equiv="X-UA-Compatible" content="IE=edge">` 另挡一刀:内网里 IE 默认可能掉进
兼容性视图,那一档按 IE7 的盒子模型画,栅格会歪得没道理。
闸门那段是内联脚本,写在 `head` 里,这里有一条踩过坑才定下的规矩:`head` 解析的时候
`body` 与 `#app` 都还不存在,一上来就往 `body` 上挂告示会抛异常,而那段异常恰恰是被
`catch` 掉的——闸门等于没装上,老内核仍旧对着骨架屏干闪。所以脚本只往 `<html>` 上打
`data-legacy-engine="1"` 这个标记(`.boot-shell` 靠一条 CSS 就此隐藏),那句人话等
`DOMContentLoaded` 再画,`addEventListener` 都没有的引擎退到 `attachEvent`。这条不是
写在注释里就算完,`browserCompatGuard.spec.ts` 会把 `index.html` 那两段内联脚本连文档
一起交给 jsdom 真跑一遍:抽掉 `Proxy` 之后必须看得见告示,抽之前必须看不见。
补得出的那几位,分三处收口,改代码时按这三处找:
1. **`src/utils/legacyCompat.ts`——内置对象与宿主 API。** `Object.entries` /
`Object.values` / `Object.fromEntries` / `Array.prototype.includes` / `find` / `flatMap` /
`padStart` / `padEnd` / `startsWith` / `replaceAll` / `matchAll`、`Number.isFinite`、
`Math.trunc`、`Promise.allSettled` / `finally`、能收迭代器的 `Set` / `Map`、
`URLSearchParams`、`Element.closest` / `matches` / `append` / `before` / `after`、
`classList` 的多参与 `toggle(name, force)`、`scrollIntoView({ ... })` 的参数对象。
它只补缺的,现代引擎上就是几十次 `typeof`;`main.ts` 第一行 import 它,
晚一步就补不到别人的顶层代码。同处还导出 `pad2` / `padLeft` / `groupThousands` /
`uniqTexts` / `listIncludes` / `eachGlobalMatch` / `toList` 这组"自己算"的原始写法,
带出值与展示这条链优先用它们。
2. **`src/utils/format.ts`——数字、金额、日期。** 老内核的 `Intl` 要么没有,要么只认很窄
一档选项(`notation: 'compact'` 直接 `RangeError`),认得出就用它,认不出就地自己算:
紧凑单位退回「万 / 亿」、货币退回符号 + 千分位、日期退回 `YYYY/M/D HH:mm:ss`、
时区名退回 `UTC±HH:MM`。另外两件是真 bug 而不是兼容:`hour12: false` 下有的引擎把
午夜念成 `24:00`,这里统一改回 `00:00`;`Intl.Collator` 认不下 `numeric` 时表格排序会排出
"10 在 9 前头",这里探不出来就自己按数字段比。**后端给的带微秒 ISO**
(`2026-11-11T15:20:30.123456`)在 IE 上是 `Invalid Date`,`parseDateInput` 兜住这一类。
3. **`src/utils/url.ts`——地址。** `new URL()` 在 IE 上整个不存在,链接格子、嵌入页回填的
`targetOrigin`、免登落地读票据都靠它。统一走 `parseHttpUrl` / `httpOrigin`:原生在就照原生
的规范化结果(口径一字不变,`https://v1.2` 那种末段纯数字的主机名照样不算地址),
原生不在就自己拆,顺带给一份 `searchParams.get()`。
新增代码的三条规矩,由 `src/utils/browserCompatGuard.spec.ts` 当闸门盯着:
* 组件里不 `new Intl.*`,也不裸 `new URL()`——要显示就调 `utils/format.ts`,要拆地址就调 `utils/url.ts`;
* 带出值与展示这条链(`format` / `formatters` / `formRuntime` / `formLinkage` / `optionMap` /
`binding` / `linkText` / `personLabel` / `autoRule` / `optionSource` / `formFormula` /
`linkFill` / `jsonPaths` / `url`)不用 `padStart` / `padEnd` / `toLocaleString` /
`[...new Set()]` / `Array.from(new Set())`,一律换成上面那组原始写法;
* `ResizeObserver` / `IntersectionObserver` / `requestIdleCallback` 用之前先 `typeof` 探一眼,
探不到要有降级(虚拟表格退到 `window.resize`,预取退到 `setTimeout`)。
`vite.config.ts` 里 `build.target: 'es2015'` 是这套口径的另一半:默认那一档是
`modules`(≈ES2020),产物里 `?.` / `??` 原样发出去,老 Edge 15/16 连**解析**都过不去,
整页白屏。降到 ES2015 之后语法这一层不再是问题,缺的内置对象交给兼容层。
```bash
cd frontend
pnpm vitest run src/utils/browserCompatGuard.spec.ts # 浏览器口径闸门(含外壳内联脚本必须 ES5)
pnpm vitest run src/utils/legacyCompat.spec.ts src/utils/displayLegacy.spec.ts # 补齐与兜底写法本身
```

View File

@ -0,0 +1,249 @@
# 干预之后:旧环节还留着什么,已经推出去的消息怎么办
两问都来自 2026-11-10 那张截图:一张停在「部门主管」的单,管理员直接改到「财务审批」,
审批记录上写着「经营管理中心不需要部门主管审批,故干预到财务审批」。
- **被干预之前那一环还会不会有待办?** 正常路上不会——改道收的是**整张单**的待办,
不是只有当前环节那一条。真正会留下来的是另外三种东西:一张读起来像他自己批过的已办、
一个挂在半路没人认领的嵌入子流程,以及一条第三方停在等确认的表态。
- **已经推出去的那条「您有新的待办」怎么办?** 分三条链路看,只有站内信能自愈(它是
读出口收尾),邮箱 / 群机器人 / 企业微信那三条**收不回来**——Hub 的推送接口只有发送
与回查,企微自己的撤回没在 Hub 上开。所以力气不放在追消息上,放在**任何一条旧消息
点开都答得清**上。
现状与缺口全部钉在 `backend/scripts/check_intervention_move.py`(内存 sqlite,跑真引擎,
一条语句不碰开发库)。这一篇不重复它的断言,只写结论与方案:**§2 那八条尾巴已经全部
落地**(42 项判据通过),剩下的只有 §5 里那几条明确不做的事。
## 1. 五个干预动作,对"待办"的影响各不相同
| 动作 | 待办动不动 | 已推送的提醒 | 判据 |
| --- | --- | --- | --- |
| 挂起 | **不动**,只是冻住(行上挂「已挂起」,办单被挡) | 点开仍是那张审批页,顶部换成「已被管理员挂起」横幅 | A 组之外,见干预篇 §2 |
| 恢复 | 解冻,时限整体后挪 | 同上,横幅消失 | |
| 干预改道 | **整张单的待办一次结掉进已办**,落点重新派发 | 旧那条指向的待办已不存在 → 本文的正题 | A1–A8 |
| 整单催办 | 不动,只加催办计数 | 又推一条催办(本来就该推) | |
| 整单改派 | 待办条数不变,只换持有人 | 原主人那条按「已经不归他」收尾(转办同一条判据) | `check_notify_settle.py` A9 |
改道做干净的那几件事,逐条有据:原环节一条待办不剩(A1)、落点派出新待办(A2)、
被收走的那条**进已办而不是被删**(A3)、原因跟着那一步走(A5)、游标与「当前环节」
文案一起落到落点(A6)、token / 票箱 / 直返约定清空并写上 `dedupSince`(A7)、
流转记录里是一条真的换环节记录(A8)。
## 2. 留下来的八条尾巴
按"谁会被硌一下"排,不按改动大小。八条都在 `check_intervention_move.py` 里留了名
(A / B / C / D 四组),下面每条末尾标的是它最终落在哪一条判据上。
### G1 「我的已办」那一行读起来像他自己签的
`engine.move` 收待办时走的是
[`_complete_task`](../backend/app/engine/engine.py) 但不传 `operator`,而这个函数
**默认把来人当持有人**(`is_holder = operator is None or …`)。终止那一步是传了
`operator=actor` 的,改道漏了。于是陈鹏的已办里那一行 `operator` / `operator_name`
全空(A4+ 实测)。前端两张处理方式表 `utils/oa.ts:PROCESSING_TYPE` 与
`utils/approvalRecord.ts:PROCESSING_TYPES` 都**没有 `move` 这一档**,
`processingTypeLabel('move')` 回落到原值——「处理方式」那一列直接印一个裸的 `move`
(D2+ 实测)。他既看不出这一条不是自己办的,也看不出是谁收走的。
### G2 点开旧卡片只有一句「该待办已被处理」
已推送消息的链接是 `/todo/<待办号>`(`channels.hub_target_path`:待办 / 催办 / 超时
落待办页,就为的"点开即批")。改道之后那一行被引擎删了,`GET /task/{id}` 一句
`待办不存在或已被处理`(D1),桌面 `TaskDetailView` 与手机版式都只摆一句
`该待办已被处理` + 「暂无数据」。这一句里没说:是谁动的、为什么动、那张单现在停在
谁手上、要不要他管。
而回答它需要的数据**本来就在库里**(D2):按待办号回查 `oa_task_completed` 拿得到
单号、原环节、原因、`processing_type`;再顺着那条 `move` 流转记录拿得到是谁动的
(`from_person_name`)与落点(`arrived_activity_name`)。不加表、不加列。
### G3 外发渠道收不回,也不为干预补一句
`oa_notify_delivery` 那一行改道前后一字不变(B9),因为渠道投递只在 `engine.notify()`
写入那一刻排一次队;而干预用的事件名 `control` **故意不在** `channels.EVENTS` 里
(B8),所以邮箱、群机器人、企微应用消息三条链路一条都不会替干预说话。企微那张卡片
躺在会话里,一直写着「您在【部门主管】环节有待办」,点进去是 G2 那句。
### G4 改道回走过的环节时,新待办号推不出去
事件订阅的幂等键是 `hook:event:单号:环节名`(`events.emit`)。同一个环节第二次
「到达」(改道回来、退回重走)被这一句去重吞掉(B11+ 实测:旧号推出去了,
新号推不出去)。订阅方手里攥着一条已经废掉的待办号,还照着它调 `decide`。
### G5 第三方看到的 `task.completed` 说不清是哪一种"办完"
改道确实推了 `task.completed` 并带 `processingType=move`(B10),订阅方能自愈——
但 `move` 这一档既不在卡片的事件表里(`node_approve.CARD_EVENTS` 只写「这一环已由人
从 OA 界面办掉:不用再表态」),也不在对接文档的取值清单里。按文档写的对方会把
「被管理员收走」读成「有人同意了」。
### G6 父单改道,不管还在跑的嵌入子流程
父单停在「调用子流程」时**自己没有待办**(待办全在子单上),所以改道收不到任何
待办,却又把 `work.tokens` 清空——里面那条带着 `embed_job` 的等待票就这么没了
(C4)。子单照旧在跑,那条待办仍然压在经办人手上(C5),这才是字面意义上
**「留在被干预之前那条路上的待办」**。子单办完时 `resume_embed_parent` 认不出
token 就直接 `return`(engine.py 里那一句),父单一步都没动(C6+),
**子流程办出来的结论对父单等于没发生**。终止那边是有 cascade 的,改道这边没有。
### G7 第三方停在半路等确认的表态不作废
`node_approve.invalidate_for_work` 只在办结 / 终止 / 作废时调。改道之后那条
`status=staged` 的表态还活着(C2+)。改道回到同一环时,审批页会突然冒出一条横幅:
「XX 系统已表态,请确认」——那是改道**之前**、按改道之前的表单说的。
### G8 待阅行上那份「当前环节」不刷新
`oa_read.current_activity_name` 是抄送那一刻抄下来的快照,只有再抄一次或归档时才动
(C1+:单据已经写着财务经理,待阅还写着部门主管)。这不是改道独有的毛病,每一次
前进都这样,只是干预把它摆得格外显眼。待阅本身**不该**回收(C1:那句话说的是
「抄给你看过」,不是要办的事)。
## 3. 方案
一句话:**旧消息追不回来,就别追;让它每一次点开都落在一个说得出真相的页面上。**
剩下几条尾巴按"是不是管理员该当场拦住"分两拨:能自动清的自动清,清不干净的先问一句。
### 3.1 待办去向:一处后端答话,三处前端换脸(P0)
`GET /task/{task_id}` 在待办行不在时不再一律 404:先按 `task` 号回查
`oa_task_completed`,认得出这条待办的下场就回 200 带一份 `vanished`,认不出
(查无此号)照旧 404。可见范围:只有这条待办**当时的持有人**(`identity` 对得上)
或带 `monitor:work` 的人问得动,别人仍是 404,不白送标题。
`vanished` 按 `processing_type` 分族给文案,一张表定死,别在三个前端各写一套:
| `processing_type` | 这一句该说什么 | 落点 |
| --- | --- | --- |
| `move` | 管理员 X 于 T 把这一环改到「财务经理」,这条待办随之结束,无需处理。原因:… | 「看这张单」 |
| `terminate` | 这张单已由 X 于 T 终止 | 「看这张单」 |
| `transfer` | 这条待办已转给 Y | 「看这张单」 |
| `auto` / `normal` | 这一环已由 Y 办完(或签别人先点了 / 已经批过了) | 「看这张单」 |
| `goBack` / `reset` | 这一环被退回 / 被撤回,已不在你手上 | 「看这张单」 |
| 认不出的取值(加签那两档、老数据) | `kind = unknown`:只说这条待办已结束,**不替任何人认结论**(那几行"谁办完的"跟着不说) | 「看这张单」 |
| 查无此号 | 待办不存在或已被处理(原句,不动) | — |
前端两个落地页把 `EmptyState` 换成这张「去向卡」:桌面 `TaskDetailView` 与手机版式
`MobileTaskView`——铃铛(`AppHeader`)与手机通知面板(`MobileNotificationSheet`)
点开的都是同一条 `/todo/<task>`,这两处一改,四个入口一起好,不必各写一份。
卡片只讲四件事:
**这一步怎么结束的、谁干的、这张单现在停在哪个环节在等谁、要不要你管**。
这一条为什么值 P0:企微那张卡片是**永久有效**的链接,`target_path` 存的是站内相对
路径,Hub 在点击那一刻现拼绝对地址。落地页一诚实,历史上所有已经推出去的卡片
一起变诚实,一条都不必追。
### 3.2 让留痕说清是谁动的(P0)
- `engine.move` 里那句 `_complete_task(..., LOG_MOVE)` 补上 `operator=actor`,
与终止一个写法。
- 前端两张处理方式表各补一档 `move`:文案「随改道结束」,`PROCESSING_TYPES` 里
跟 `terminate` 同一档中性偏警告的配色(不是红色——它不代表这张单被拒)。
`REWIND_PROCESSING` 已经收了 `move`,轨迹上的"走过哪些环节"不用动。
### 3.3 改道收口时一起清干净(P1)
- **嵌入子流程**:改道前先看一眼 `Work.parent_job == 本单 and status == running`
的子单。有就**默认拒**,话要说清并给出路:「这一单还挂着子流程《…》,停在
「子流程经办」等黄雪秋办。改道会把那条回跳的路拆断——请先处理子单,或勾
「一并终止子流程」再改。」面板上多一个只在有子单时才出现的勾,勾了才走
`terminate(child, opinion="父流程已改道,子流程一并终止")`,与终止那边同一条
cascade。为什么不默认终止:改道是手术刀,终止是不可逆的,不该由一次改道替人决定。
- **停在半路的表态**:改道时把这张单上 `staged` 的 `oa_node_decision` 就地作废
(复用 `invalidate_for_work`,`confirm_note` 加一句「单据已改道到「X」,这一环的
表态作废」)。面板改道页签上提前写「会作废 N 条第三方表态」。
- **待阅那份环节文案**:`_sync_work_cursor` 里顺手把这张单在途待阅的
`current_activity_name` 一起刷。放在游标这一句里而不是放在 `move` 里,是因为
每一次前进都该刷,不该只有干预享受这个待遇。
- **落点开了外部审批**:目标环节 `node_approve` 开着时,页签上多提示一句
「这一环由 X 系统审批,OA 侧不出同意按钮」,免得管理员以为改过去就有人点了。
### 3.4 已推送消息:三条链路各自的口径(P1)
| 链路 | 收得回来吗 | 这一版怎么办 |
| --- | --- | --- |
| 站内信 | 已经自愈(读出口收尾,`check_notify_settle.py`) | 补一步:干预动完手**当场**给被收走待办的人各调一次 `notify_settle.settle`,手机上那颗红点不用等他下次点开列表才退。幂等、标已读不删行 |
| 邮件 / 群机器人 / 企微应用消息 | **收不回**(Hub 9.6 只有发送与逐人回查,企微 `message/revoke` 没在 Hub 上开) | ① 落地页负责说清(3.1);② 真要对外说一句,走**渠道订阅**而不是硬推:新增事件名 `rerouted`,`engine.notify` 用现成的 `channel_event="rerouted"`(这个参数今天还没有任何调用点),`oa_notification.type` 仍是 `control`,站内一切照旧;把 `("rerouted", "流程被干预改道")` 加进 `channels.EVENTS` 让渠道自己勾。存量渠道的 `events` 里没这个值,于是**默认安静**,谁要谁勾。深链自动退回 `/work/<job>`(`rerouted` 不在 `HUB_TASK_EVENTS` 里,`hub_target_path` 本来就指待办页以外的都落单据页),一处不用改 |
| 事件订阅 webhook | 已经在推 `task.completed`(带 `processingType=move`) | ① 把 `move` / `terminate` / `reset` 这几档**非人工签收**写进卡片事件表(`node_approve.CARD_EVENTS`)与 `docs/node-open-approve-*.md`,明确「看到这几种 processingType 就把手上那条待办收掉,别当成同意」;② 幂等键从 `hook:event:单号:环节名` 改成再带一段待办号,让改道回来 / 退回重走都能推一条带**新号**的 `task.arrived` |
改幂等键要有代价意识:存量订阅方会开始收到"同一环节的第二条到达事件"。它们本就按
`idem` 去重,多出来的第二条正好把新待办号送到手上,是它们一直缺的东西;历史 `idem`
不重算。这条要写进对接文档的变更说明,别只写在代码注释里。
### 3.5 挂起、恢复、整单改派:口径不动
挂起期间点开已推送的卡片有「已被管理员挂起」横幅,这一条已经是对的,别顺手改成
"待办从列表里抹掉"。整单改派走的是转办那条收尾判据(原主人那条按「已经不归他」
退场),也不动。
## 4. 面板上那几句"代价"要说全
`monitor.intervene.moveWarning` 今天只说了两句:待办会结掉、并行时不许。按这一篇补
三句,都摆在改道页签的确认之前:
- 会被收走待办的人:**N 个人 / M 条**(面板本来就列得出来);
- 这张单上还挂着子流程 / 停在半路的第三方表态时,各写一句会怎么处置;
- 已经推出去的提醒收不回来,对方点开时看到的是「已结束」那一页——真要对外说话,
去渠道里勾上「流程被干预改道」。
被收走的那一侧只多一张去向卡(3.1),不新增任何待办、不新增任何按钮。
## 5. 不做什么
- **不追企微撤回**。要等 Hub 开 `revoke` / `update`,而且开了也只能撤最近那批,
历史卡片仍然躺在那儿——落地页那一处改完是全覆盖,性价比不在一个量级。
- **不把 `control` 全量推外发**。挂起、恢复、改数据这些动作在站内看一眼就够,
一天下来没人愿意邮箱里躺着「管理员动了你那张单」。
- **不删站内信**。投递记录要能回查「谁在什么时候收到过什么」,收尾一律标已读。
- **不动并行判定**。并行 / 拆分开着照旧拒(`work.joins` 那一关),这一篇只是把
子流程那一类"看着不像并行、实际是另一张单"的先问一句。
## 6. 落地顺序(P0 / P1 已全部落地,判据见 §7)
1. **P0(已落地)**:`engine.move` 的 `_complete_task` 补 `operator=actor`;前端
`utils/oa.ts` 与 `utils/approvalRecord.ts` 各补一档 `move`(「随改道结束」,琥珀色);
`GET /task/{id}` 认已办行回话,回一份 `vanished`,桌面 `TaskDetailView` 与手机版式
`MobileTaskView` 共用 `utils/taskVanished.ts` 同一份文案(铃铛与手机通知面板点开的
是同一条 `/todo/<task>`,两处一改四个入口一起好)。判据 A1–A9、D1–D9。
2. **P1(已落地)**:嵌入子流程预检(`engine.running_embed_children` /
`embed_blocker`,默认拒,勾了才 `cascade_children=True` 一并终止);`staged` 表态
随改道作废(`node_approve.invalidate_for_work` 带一句作废说明);干预写侧给每个被
收走待办的人补一次 `notify_settle.settle`;待阅那份「当前环节」跟着 `_sync_work_cursor`
刷(每一次前进都刷,不只干预);`events.emit` 幂等键带上待办号;非人工签收那七档
取值写进 `docs/node-open-approve-design.md` §4.4 与卡片事件表。判据 B1–B13、C1–C8。
3. **P2(没做,等外部条件)**:Hub 若开了撤回 / 更新接口再补撤回那一腿(§5 第一条);
监控列表上「这张单被干预过几次」那一列。
**P1 里多做了一档**:`rerouted` 这个可勾的渠道事件(原本排在 P2)。理由是站内那一步
当场收尾之后,唯一还缺的就是"管理员想对外说一句时得能只勾这一档",而它不改表、
不改存量行为(存量渠道的 `events` 里没这个值,默认一句都不往外推)。
改动点集中在 `engine.move` / `_sync_work_cursor`、`api/runtime.py::get_task_detail`、
`events.emit` 的幂等键、`channels.EVENTS`、前端 `TaskDetailView.vue` /
`MobileTaskView.vue` / `utils/oa.ts` / `utils/approvalRecord.ts` / `InterventionPanel.vue`。
`oa_notification`、`oa_notify_delivery`、`oa_task_completed` 三张表**一个字段都不加**。
## 7. 怎么验
判据在 `backend/scripts/check_intervention_move.py`(内存 sqlite,跑真引擎,一条语句
不碰开发库):
```
cd backend && PYTHONPATH=. python3 scripts/check_intervention_move.py
```
现在跑是 **42 项判据全部通过,另记 1 条现状**:那一条是
`observe` 里唯一还留着的那个——已经落到邮箱 / 群 / 企业微信里的那条卡片收不回来
(Hub 9.6 只有发送与逐人回查,企微自己的撤回没在 Hub 上开)。§2 那八条尾巴当初打成
「现状」备查的 `observe`,逐条翻成了 `check`:A5 认已办行上的代操作人、D2/D3 认
`vanished` 里那句改道说明、D9 认两张表里有 `move`、C2 认待阅的环节文案跟着刷、
C3 认 `staged` 被作废、C5–C8 认要么拒要么子单被一并终止、B12 认改道回来时推得出
新待办号。追不回来的那一条由 D 组那一屏兜住:消息收不回,就让它每次点开都落在
一个说得出真相的页面上。
邻篇判据一起复跑:`check_notify_settle.py`(站内信收尾那族)、
`check_intervention_title.py`(改数据改到标题那一格)、`check_action_surface.py`。
外加仓库那三条守卫 `check_globals.py` / `check_route_guards.py` /
`check_schema_snapshot.py`(这一篇不动 `models.py`,第三条应当一字不改),
前端 `pnpm typecheck` / `lint:check` / `build`。

View File

@ -89,7 +89,31 @@
一条卡片三行:标题、`发起人 · 部门 · 时间`、状态标签。左边一道色条表紧急(超时红、临期黄),
催办次数和出口数量挂在标签上。整条都是点击区,右边只留一个「去批」。
往下滑是攒页(IntersectionObserver 哨兵),不给分页器——手机上没人愿意去点「下一页」。
桌面上的搜索、状态筛选、批量审批都没进来:手机上一次就批几条,那几个控件加起来比单子还占地方。
桌面上那排筛选控件(流程、日期区间、导出)没进来:手机上一次就批几条,那几个控件加起来比单子
还占地方;搜索收了但留着——顶栏那枚放大镜点开一行输入框。批量审批后来补上了,见 §3.1。
### 3.1 批量处理:先换一档,再勾几条
原话是**「手机端也需要有批量处理的功能」**。桌面那一套(表头复选框 + 工具栏那一颗按钮)搬不过来:
390 的屏上复选框那一列会把标题挤成两行,何况一次只批三五条,用不着「全选这 20 条」。
手机上把它做成**一档**,不是一排控件:
* 顶栏一颗「批量处理」,按下去整张列表进**选择档**——卡片左边那颗勾替掉右边的「去批」和箭头,
点卡片是勾上 / 取消,不再进详情(一次批三条不该点六下);再按一次「取消」退档,退档顺手把勾收掉,
留着看不见的那几个勾会跟着下一次提交走;
* 操作位在屏幕下沿那一横条:`全选 / 清空` + `已选 N 条` + 「批量处理 N」,全在拇指底下,
不用滑回顶栏去找。计数只数屏幕上摆得出来的那几条,翻页翻走的、被人抢先办掉的不算;
* 那一层用 `MobileSheet`(§5 那条规矩),出口不做下拉而做一排按钮——下拉浮在 bottom sheet 里
会被截掉半截;意见还是那个 `TextArea`,引擎逐条回的那几句失败原因摊在层里,改完可以只重试这几条。
判据与桌面同一条,不另起一套:能勾的是 `!row.oa_locked`(这一环的表态已交给外部系统),
全选不硬塞它,手动勾上照样能提交——引擎回的那句原因写清了去哪儿办,比界面挡着不吭声好。
`oa_locked` 那条卡片照摆、只是点不动,理由挂在勾上。
**交上去的 id 从攒下的那一沓(`useMobileFeed` 的 `feed`)里取,不是从当前页取**:手机上往下滑过三页、
勾了 25 条,只按当前页找会莫名少掉一截。一批全办完就自动退出选择档,剩下的单子摆回普通列表。
桌面那一版(`DataTable` 勾选 + `BaseDialog`)一个字没动,两条分支共用 `openBatch` / `confirmBatch`
与 `batchRoutes`(可用出口 = 每条被选待办路由名的交集)那一套。
## 4. 详情:一屏之内先答完四问
@ -117,6 +141,7 @@
| auto(系统取数) | 合并成一行折叠起来——发起人是谁、哪个部门,抬头已经有了 |
| dept(部门) | 只念部门名,也就是组织路径的末段(`紫光汇智\软件开发事业部` → `软件开发事业部`),与桌面只读态同一个口径 |
| week / months / location | 星期几念「周一、周三」、多月念「2026年10-11月」、定位念「地址(经度, 纬度)」,读的都是桌面只读态那三份(`utils/formRuntime`),手机上不再看到 `1-7`、`['2026-10']` 这类库里的码 |
| url(链接) | 那一串字本身就是点得开的链接(`common/LinkText`):认得出的包成 `<a>`,认不出的一句话原样摆,裸域名补上 `https://` |
| table(明细) | 收成一行「明细 12 条 · 合计 7,181.00」,点开才是逐条 |
| attachment / image | 缩略图横滑,不占字段行 |
| tabs(标签页) | 那一页的名字就是分节标题;外部页面那一页整节换成一张「打开」卡片 |
@ -145,6 +170,26 @@
| 明细里的金额列 | 库里那个 `1129` 原样摊出来 | 按那一列配的格式写「1,129.00」,合计同理 |
| `daterange` / `timerange` | 自己拼 ` ~ `(碰巧一样) | 直接读 `rangeText`,不再各拼一遍 |
**链接那一格在手机上点得开。**`url` 格子在桌面只读态一直是 `<a>`,手机上两屏(摘要与「完整单据」)
都只把值当一句文本摆出来,于是同一张单子在电脑上点得开、在手机上是一段读得出、抄得下来的字——
390 的屏里既没有地址栏可以补协议,也没法划词,等于点不动。现在两屏的值都过一层
`components/common/LinkText.vue`:判据在 `utils/linkText`(`toHref` / `linkSegments`),
认得出的网址包成 `<a target="_blank" rel="noopener noreferrer">`,认不出的照普通文字摆,
一个字都不改。三条分寸:
- **链接格子整串当一个地址看**(`wholeUrl`):`oa.example.com/policy/2026` 这种不写协议的也认,
缺的 `https://` 由这一层补——桌面那只 `<a :href="值">` 碰上裸域名会当本站相对路径,点开是 404;
- **一句话里夹的网址也认**(只认带协议的与 `www.` 起的):`细则见 https://a.com/rule/3。`
切成三段摆,句尾那个句号留给句子,不吸进地址里;
- **认不出就不摆链接**:有人往链接格写「见内网制度页」,退回普通文字,别给一条点不通的蓝线。
`3.5`、`v1.2` 这类看着像域名的也不算地址。
同一层还管手机上另外三处读得见链接的地方:摘要与「完整单据」里明细的链接列
(`mobileRowCells` 每格多带一个 `wholeUrl`,摆法跟着格子走)、流转时间线里那条意见
(`MobileFlow`,「详见 https://…」不再要人手抄),以及填写块里那一格链接
(`FormFieldControl` 编辑态在输入框底下给一条「打开链接」,值一改就跟着改——
输入框里那串字本身是点不动的)。
**分节先认页签,再认分隔条**。原先这一层只认 `divider`,而生产上那张费用报销单是靠一张
「标签页」分两页的(`tabsMode: collapse`),于是三十几格全挤进一节「表单内容」,
段名一个字都不见——配表的人分好的两页,手机上等于没分。现在读的是同一份
@ -188,6 +233,91 @@
勾了「手机上不展示」的格子在那一版里照样不摆(同一个键,两处共用)。口径与取舍见
[mobile-form-layout-config.md](mobile-form-layout-config.md)。
再往后补的是**「显示条件」那一档**。这一屏原先只读裸的 `field.hidden`,`visibleWhen` 一个字都不评,
于是电脑上一拨条件就露出来的格子上不了手机,条件早已翻走的格子却在手机上留着一行谁也改不动的值。
现在四道闸在 `utils/mobileLayout.ts:mobileVisibilityOf` 一句排到底(手机上不展示 → 本环节隐藏 →
显示条件不成立 → 整单默认隐藏),并且**按手上是哪一份值分两屏**:待办那一屏那份值是活的,
格子跟着电脑上同一时刻露、同一时刻藏;已办、抄送、归档那一屏那份值是死的,条件在那一屏
只**放行**不**收**——拿存过的值把「默认隐藏 + 显示条件」那一组摆回来,其余照旧把存过的摊开
(判据 `utils/formRuntime.readbackHidden`,桌面只读渲染读的是同一句)。见
[mobile-form-layout-config.md](mobile-form-layout-config.md) §4.2。
### 4.5 摆法跟「此刻」那份配置,判据跟发起那一刻那一版
单据发起那一刻整份设计被冻进 `oa_process_snapshot`(`oa_work.design_snapshot` 认着它),
表单内容也在里面——这是「改图改表单不影响在途单」那条规矩的落点,`check_design_pin.py` 钉的就是它。
表单那一份跟着一起冻住,于是露出一个只在手机上别扭的后果:配表的人改了「哪几格展示、什么顺序、
每格怎么摆、显示条件」,**手机上那一屏看不着**,得等这张单走完、下一张单发起才见效。
原话:**「手机端的审批表单我希望根据表单配置的展示规则而变化,而不是一发起就冻结。
手机端需要跟随调整而变化。」**
现在这一屏读**此刻**那份配置,其余照旧读冻住的那一张:
| 读哪一份 | 谁 |
| --- | --- |
| `forms_live[表单 id]` + `activity_perms_live[环节 id]`(此刻) | 手机端:摘要那一节、「完整单据」那一屏(待办详情与在途单的单据详情两处) |
| `forms[0..]` + `activity_nodes[环节].form_perms`(发起那一刻) | 桌面只读渲染、打印、明细导出、必填校验、填写块、引擎落库认的那些格 |
单据是凭证。「这一屏给这个人看哪几格」是可以跟着配置动的,「这张单当时该填什么、
他改了哪几格」不能因为别人改了表单就当场换掉——所以分叉只开在**摆法**这一寸。
后端只多一份报文(`api/runtime.py::_job_response` / `_forms_live`):
* 键是 `form_id -> 此刻的 content`,**只装与冻住的那一张真改了的那几张**;没人改过就是
`{}`,报文与这一改动之前逐字节一致,前端也就不会为同一份内容摆两遍。
* 只有**冻过结的在途单**算。没冻过的老单,`forms` 本来就是现读的;办结归档的单子是凭证,
手机上回头打开也读它走完那一版。
* 内容走 `autofill.form_content` 那层进程内快照(`app/presence.py`),没人改表单时一条 SQL
都不排;真没命中也只排在这一个并发位里,不给详情页添串行的往返。设计器保存表单时那层
快照当场作废,所以是「保存即见效」。
* 认的是**同一张表**:设计器里就地改表单是更新那一行,`id` 不变,这正是"改配置马上影响在途单"
那条路。把环节换成另一张表单(`id` 变了)不算调整——在途单照旧看自己冻住的那一张,
不会因为换表而在半路上换一张脸。
上线后第一句回话是**「现在为什么手机端在途的表单为什么还是展示的不一样呢?不是跟我配置的展示呢」**。
拿着生产上那十张在途报销单逐个对,卡住的不是部署(镜像里两份报文都在),是两处真没跟:
* **环节压根没绑表单。** 生产上「费用报销流程」的财务总监 / 执行董事 / 部门主管那三环,
`activity_nodes[环节].form` 是空串:页面照旧回落到 `forms[0]`,而刚写的那一版是拿这个空串去
`forms_live` 里查——**永远查不到**,于是手机上静默退回冻住的那一张(35 格,此刻那张表配的是 38 格)。
认 id 这件事从前散在三处(环节、待办、兜底),漏一处就悄悄不跟。现在收成
`utils/mobileLayout.ts:mobileFormRead(detail, …preferredIds)` **一处**:先按
「环节 form → 待办 form → `forms[0]`」把 id 解析出来,再一次性交出 `{ frozen, mobile }` 两份;
`TaskDetailView` 与 `WorkDetailView` 都读它,桌面拿 `.frozen`、手机拿 `.mobile`。
* **还有半份配置冻在另一张表上。** 审批人在手机上露哪几格,一半写在表单那几栏展示配置里,
一半写在流程设计器「环节 → **字段权限**」那一格(隐藏 / 只读 / 可编辑 / 必填),而它冻在
`activity_nodes[环节].form_perms` 里。管理员把 `checkTotal` 那几个审定格从「隐藏」改成「只读」,
手机上照旧不露——那张单冻的还是「隐藏」。现在后端多回一份 `activity_perms_live`
(`api/runtime.py::_perms_live`,**只回与冻结那一版不一样的环节**,没人动过就是 `{}`),
前端 `mobileFieldPerms` 读它,取不到就逐环节回落到冻结那份 `form_perms`。
生产上真数据的对照(同一张单,手机版式按两份各算一遍):
| 那张单停在 | 跟之前上屏 | 跟之后上屏 | 差在哪 |
| --- | --- | --- | --- |
| 执行董事 `19e5b023…` | 11 格 | 22 格 | 多出 `applyTime`、`project_code`、`feiyong_type`、`checkTraffic`、`sumEntertain`、`checkEntertain`、`checkTravel`、`checkTelecom`、`sumOther`、`checkOther`、`expenseTotal`、`checkTotal`;少 `relatedWork`(此刻显示条件不成立) |
| 部门主管 `6a39a9f7…` | 9 格 | 17 格 | 多出 `applyTime`、`processNo`、`project_code`、`sumTraffic`、`sumTravel`、`sumTelecom`、`expenseTotal`、`reimburseType` |
| 财务总监 `40bd8d73…` | 25 格 | 20 格 | 字段权限那一份本来就没改,只跟着表单内容与显示条件走:加 `project_code`,去掉 `sumTraffic`、`sumEntertain`、`sumTravel`、`sumOther`、`relatedWork`、`financiaNotes` |
**唯一还压着手机端这一屏的是「显示条件」**(`visibleWhen`,读这张单此刻存着的值):面板上给某一格点了
「展示」,而它当下条件不成立,手机上还是不摆——那本来就是这份配置的一部分(口径见 §4.3)。要是希望
手机端那一屏以面板为绝对优先、只让「本环节隐藏」拦人,改的是 `mobileVisibilityOf` 那四道闸的次序,
一处改完。
前端落点:`TaskDetailView` 多交一份 `mobileFormSchema` 与 `mobileFieldPerms`
(`components/oa/mobile/taskContext.ts`),`MobileTaskView` 拿它们算摘要与「完整单据」;填写块、
`requiredMissing`、`needKeys`、提交校验的输入仍是 `formSchema` 与 `fieldPerms`。`WorkDetailView`
给 `MobileWorkView` 递的也是 `.mobile` 那一份,桌面那一版没换。页签那一档的「藏整片 / 藏某一页」要
跟着摆法走,所以 `expandPerms` 在手机上按当下那份字段清单**与当下那份环节权限**再展开一遍
(`displayPerms`),两屏不许一套跟一套不跟。
守卫:`check_design_pin.py` 第 3b 组(两份表单各是什么、没改动不多带、表删了回落、归档不带)和
第 3c 组(此刻的环节字段权限回得对、冻结简报一个字没动、没改时是空的、冻结简报里没有的环节不进报文)、
`mobileLayout.spec.ts`(`mobileFormRead` 那三份优先级,含生产上那个**空 form id 回落**)、
`MobileTaskView.liveForm.spec.ts`(跟的那一份要跟到:「隐藏」改成「只读」的格子手机上要露出来;
不跟的那一份不许跟:填写块仍是冻住那一份算出来的)、`WorkDetailView.spec.ts`(复现生产上
`form: ''` 那个形状)。设计器版本号那颗 tooltip(`process.versionPinTipMobile`)也把这条例外
写在了落款里。
### 4.4 没配闸门就不摆「外部核验」
`ExternalCheckPanel` 原先的判据是「接口通不通」,于是没配外部核验的流程也在单据上挂一块
@ -204,8 +334,10 @@
竖着一条时间线,一步两行——谁在哪一步、什么时候,意见默认两行读完,
超过一句长话才给「展开」;改单折成「改了表单 · 2 项」,附件折成「附件 2」,点开才是原值新值与缩略图。
- **默认只摆最近三步**(`RECENT = 3`),更早的收成一颗「展开更早 N 条」。批十单的人只关心最近
那两步,第一次看这张单的人才需要全程;
- **整条时间线从头摊到底,不折叠**。从前只摆最近三步(`RECENT = 3`),更早的收成一颗
「展开更早 N 条」——批了七八环的单子打开只看得见两环加一颗钮,**人以为这张单少走了几环,
其实是被折起来了**。这一屏要答的就是"这张单走过哪些环节",省下那两三屏不值这个误会,
于是那颗钮连同 `RECENT` 一起删了。要省地方可以往上翻页签,本来「表单内容 / 审批记录」就是两屏;
- **发起那一行永远留着**,收掉开头就说不清这张单从哪儿来;
- **末尾那一行高亮说「此刻卡在谁手上」**(`停在「总经理审批」,等待 黄雪秋 处理`),
这一句才是审批人真正要的答案,桌面上它混在几十行记录里;
@ -368,6 +500,7 @@ kubectl -n unis-oa set image deploy/unis-oa unis-oa=docker.oa.unissense.tech/pub
cd frontend && pnpm dev
# http://localhost:3000/preview-mobile.html?screen=home
# http://localhost:3000/preview-mobile.html?screen=list
# 批量那一档(前两条已勾上):把上面这条换成 ?screen=list&select=on ;再把那层推上来用 &select=sheet
# http://localhost:3000/preview-mobile.html?screen=detail&open=approve
# http://localhost:3000/preview-mobile.html?screen=work&open=progress
# http://localhost:3000/preview-mobile.html?screen=profile
@ -379,6 +512,8 @@ cd frontend && pnpm dev
`scroll=520` 直接滚到指定位置(弹层里那一屏自己滚,`window` 滚不动它),`blocked=1` 把「退回修改」那条出口的适用条件设成不成立,
看走不通的出口怎么交代。
`select` 只有 `screen=list` 认:`on` 直接停在批量选择档,`sheet` 再把批量那一层推上来。
`form=tabs` 把那张假单子换成生产上费用报销单的形状——一张「标签页」分两页、第二页整页是外部系统、
其中一格勾了「手机上不展示」。**分节、外部页面那一节、逐格开关这三件事,只有在这种表上才看得出对不对**,
默认的 `mobileFixtures` 那张只有分隔条,替不了它。
@ -396,14 +531,22 @@ cd frontend && pnpm dev
没配闸门不摆、配了就摆、闸门撤了但有结论仍然摆。设计器那一档由
`FieldInspector.newTypes.spec.ts`(18 条)里那四条盯:普通格子有「手机上不展示」且勾得进字段、
「标签页」那一格不给这一档而「默认隐藏」还在、排版件两档都没有、框选一次收一片而排版件不参与。
`MobileFormSummary.spec.ts`(15 条)盯「一节最多六行、剩下收成一颗『展开更早 N 条』、换一张单子不把上一张摊开的状态带过来、节名是兜底来的那一节不摆标题行」;`MobileFlow.spec.ts`(5 条)盯这条时间线的三条底线:默认只有最近三步、发起那一行不许被收掉、「等谁处理」和单号还在;`MobileTopBar.spec.ts`(3 条)盯那条细栏只写页名与返回;`AppLayout.spec.ts`(6 条)里四条盯的就是「手机上整条顶栏不挂、抽屉不挂、细栏只挂在子页面、桌面照旧」;`MobileHome.spec.ts`(8 条)盯五张卡片的顺序、地址、权限过滤,以及上面那张口径表——数字来源写死在断言里,谁换成自己另算一份就红,另有一条盯抬头那颗铃铛与它那张弹层;`MobileTabBar.spec.ts`(5 条)盯底部栏只有三格、以及钉在电脑版时那口回去的井;`useMobileFeed.spec.ts`(5 条)盯攒页不重不漏、回第 1 页清干净;`ReadListView.spec.ts`(3 条)盯 `?tab=done` 落地就在已阅、切档位把档位写回地址。
`MobileFormSummary.spec.ts`(16 条)盯「一节最多六行、剩下收成一颗『展开更早 N 条』、换一张单子不把上一张摊开的状态带过来、节名是兜底来的那一节不摆标题行」;`MobileFlow.spec.ts`(4 条)盯这条时间线:整条线一步不落(十二环的单子摆十三行,且没有「展开更早」那颗钮)、发起那一行在最前、「等谁处理」和单号还在、只有写了长意见的那一条才给「展开」;`MobileTopBar.spec.ts`(3 条)盯那条细栏只写页名与返回;`AppLayout.spec.ts`(6 条)里四条盯的就是「手机上整条顶栏不挂、抽屉不挂、细栏只挂在子页面、桌面照旧」;`MobileHome.spec.ts`(8 条)盯五张卡片的顺序、地址、权限过滤,以及上面那张口径表——数字来源写死在断言里,谁换成自己另算一份就红,另有一条盯抬头那颗铃铛与它那张弹层;`MobileTabBar.spec.ts`(5 条)盯底部栏只有三格、以及钉在电脑版时那口回去的井;`useMobileFeed.spec.ts`(5 条)盯攒页不重不漏、回第 1 页清干净;`ReadListView.spec.ts`(3 条)盯 `?tab=done` 落地就在已阅、切档位把档位写回地址。
`MobileWorkView.spec.ts`(12 条)盯 §4.2 那一屏:抬头不重复流程名与发起时间、整页没有「刷新」也没有
打印审批单、没有画布、切页签才出时间线且单号在末尾、办得动才挂吸底那一行、终止走下推层并把意见抛出去、
没权限时 `···` 里不摆那两颗、挂起与被锁各自说一句,还有一条盯下拉这一把真的把 refresh 抛出去、给了取数那条路就走它且胶囊等到取完;
`useMobileRefresh.spec.ts`(5 条)盯手势本身——越过阈值才刷、没到顶或往上滑就让位、禁用时不抢
`preventDefault`、卸载后不再监听、回到前台补取一次;`WorkDetailView.spec.ts`(4 条)盯那个岔口本身——
手机上整页换掉且判据原样递下去、电脑宽度一格都没少。
`MobileCardList.spec.ts`(7 条)盯批量那一档在版式组件这一头的手感:不传 `selectable` 就不摆那颗钮、
选择档里点卡片是勾上而不是进详情、卡片尾巴上那句「去批」跟着收掉、办不动的那条点不动且理由挂在勾上、
全选只带上屏又办得动的两条、计数不把不在屏幕上的那条算进去、「批量处理」只把事件喊上去;
`TodoListView.batch.spec.ts`(7 条)盯接口那一只脚:交上去的就是勾的那几条、走的是共同出口、
全选不带 `oa_locked` 那条、没有共同出口时不硬凑、部分失败那层不关且失败的几条留在勾选里、
退档把勾收掉,还有一条盯桌面档位仍走 `BaseDialog` 而不是从下沿推上来那层。
`returnPath.spec.ts`(6 条)盯手机上落地那一屏:有工作台落那五张卡片、没有工作台落待办、桌面落门户、
站外地址不被带出去——它原先写死落 `/home`,而且没有 `work:workbench` 的人会被守卫打回门户新闻页。
全量 `npx vitest run` 1363 条绿,`npx vue-tsc --noEmit` 与 eslint 干净,`vite build` 通过
全量 `npx vitest run` 1933 条绿(§4.5 那两档另加 12 条:`mobileLayout.spec.ts` 31 条、
`MobileTaskView.liveForm.spec.ts` 7 条、`WorkDetailView.spec.ts` 8 条,含生产上那个空 `form` 回落那条),
后端 `check_design_pin.py` 57 条全过(第 3b / 3c 组),`npx vue-tsc --noEmit` 与 eslint 干净,`vite build` 通过
(预览台两个 html 不在产物里:rollup 只有一个入口 `index.html`)。真机那几件(企微内置浏览器、iOS 安全区、软键盘顶页面)还得在手机上过一遍。

View File

@ -19,13 +19,22 @@
| 「标签页」里那一整页**外部页面**要不要给一张「打开」卡片 | 同一面板 → 清单里那一行的「展示 / 不展示」(那颗开关记在这份配置里,属性面板上没这一颗) | 同上 |
| 末尾还要不要「完整单据」那一屏 | 同一面板 → 「末尾留『完整单据』入口」(默认**不留**) | 待办那一屏的 `···` 里始终有这条路 |
| 配到一半想退回自动归置 | 把开关关掉即可,配好的顺序留在配置里 | — |
| 电脑上「默认隐藏」的那几格要不要在手机上露 | **就在那张清单上**:给它点上「展示」= 点名(配置里记一笔 `show`) | 只影响手机版式;没点过的仍旧不摆 |
| 三十几格翻不动 | 清单顶上那颗筛选(全部 / 已上屏 / 已收起)+ 那一格搜索 | 只影响面板,不改配置 |
三条贯穿全文的分寸:
* **不开这一档就等于不存在**。没配过的表单走的还是原来那套按字段类型的自动归置,
判据在 `components/oa/mobile/useFormPlan.ts`,那一段代码这条路一行没改。
* **配置只管"摆不摆、怎么摆",不管"能不能看"**。环节字段权限、整单「默认隐藏」、
逐格「手机上不展示」、本环节要人填的那几格,这四道闸一道没少(见 §4)。
* **配置只管"摆不摆、怎么摆",不管"能不能看"**。开了这一档之后手机上那一屏只认两份说法:
这份清单(含逐格那颗「手机上不展示」)与本环节的字段权限——整单「默认隐藏」不再压它
(那一档管的是电脑上填单那一屏),本环节要人填的那几格仍归上面的填写块(见 §4)。
**这一条是后来改的**:原先整单「默认隐藏」也压得住,于是面板上写着「展示」、
手机上那一格自己消失,配表的人只能对着单子猜(见 §4.1)。
* **格子自己那句「显示条件」不在这一层抢话,但也不被它漏掉**。配了 `visibleWhen` 的那一格
露不露归条件说:待办那一屏(人正在改条件里那些值)跟着电脑上一起露、一起藏,
单据详情那一屏(那份值已经是死的)拿存过的那一份**只放行、不收格子**——与桌面只读渲染
那句 `utils/formRuntime.readbackHidden` 一句对一句(见 §4.2)。
* **后端一行没动**。这份配置住在 `oa_form.content.layout.mobile` 里,
`api/design.py:clean_formats` 只按类型收字段上那几栏展现配置,`layout` 里的东西原样存回。
@ -46,6 +55,8 @@
{ "key": "reason", "style": "block", "label": "事由" },
{ "key": "amount", "style": "float" },
{ "key": "days" },
// 电脑上「默认隐藏」的那一格:清单上点了「展示」才写这一笔(见 §2 末尾与 §4.1)
{ "key": "pms_code", "show": true },
{ "key": "rows", "style": "list" },
{ "key": "invoices", "style": "gallery" },
// 外部页面那一格的键带着页签:宿主格子key#页签key
@ -68,6 +79,11 @@
(见 [mobile-approval-layout.md](mobile-approval-layout.md) §4.3),面板上那颗"展示 / 不展示"
改的就是它。两份开关早晚会变成"属性面板勾了、手机端面板没勾"。
**这颗例外记在这儿**:`show`。它不是第三份开关,是**对整单「默认隐藏」的一次表态**——
`mobileHidden` 说的是"手机上别摆",`show` 说的是"电脑上那句默认隐藏管不到手机上这一屏",
两句不是一句话。没点过「展示」的格子配置里不会多出这一笔,所以关掉再打开这一档不会
把藏着的格子一次性放出来;判它们的是同一处(`mobileVisibilityOf`),不会两处各说一遍。
`style` 的可选项由字段类型给(`utils/mobileLayout.ts:styleOptionsFor`):文本类 `row` / `block`,
数字金额多一档 `float`,附件与图片 `gallery` / `count`,明细 `card` / `list`,签名只有一档。
配置里写了这一档新类型吃不下去(换了类型、从别的表单粘过来),`styleFor` 回落到该类型的默认档,
@ -116,6 +132,18 @@ if (mobile) return planByMobileLayout(mobile)
这时候新格子该出现——凭空消失是那种要查半天的错。设计器每次开门都按现在的表把清单重算一遍
(`pruneMobileLayout`:删掉的收掉、新加的补在最后),所以清单和表单永远对得上。
**电脑上「默认隐藏」的那几格听这一屏的**。`field.hidden` 本来说的是"电脑上填单那一屏别占位"
(值照常存、带出与公式照算,哪个环节明给只读 / 可编辑它就露出来),不该顺手管住手机上那一屏。
现在开了这一档之后:**清单上点了「展示」= 给它表了态**,配置里记一笔 `fields[].show: true`,
手机上就摆;没点过的仍旧按电脑上那句不摆——否则一开开关,整张表里藏着的格子会一次性涌出来。
环节那边明着给了只读 / 可编辑 / 必填,也算它要露出来(与桌面 `effectivePerm` 同一句话)。
预览台上那两格 `PMS项目编号`(点了名,摆)与 `VDI项目编号`(没点名,不摆)就是给这一档对的照。
**这一档现在只压没配「显示条件」的格子**。勾了默认隐藏又配了条件的那一格,说话的是条件而不是
那个默认值(`formRuntime.hiddenByDefault` 同一句),手机上跟着电脑上那一屏一起露一起藏,
不需要配表的人在清单上再点一次「展示」;清单上它标的是「按显示条件」,角标点出去写的是
格子上的 `mobileHidden`,不代它记一笔 `show`(见 §4.2)。
**「标签页」里那一整页外部页面也算一格**(`mobileCells` 把它合成出来,键是 `宿主格子key#页签key`)。
手机上不内嵌别人的系统,摆的是一张「打开」卡片,点了新窗口看——与「完整单据」那一屏同一个口径
(390px 里嵌一整张 ERP 表等于没法看)。它没有格子可以挂「手机上不展示」,那颗开关因此记在
@ -141,16 +169,46 @@ if (mobile) return planByMobileLayout(mobile)
摆上去只是一行空白;后者是个壳,进去的是它那一页一页的内容——外部页面那几页会以
「外部页面」这一类出现在清单里,名字取页签名,摆法只有「打开卡片」一档。
## 4. 四道闸一道没少
**清单能搜能筛**:顶上那颗筛选(全部 / 已上屏 / 已收起)加一个搜字段名的框。
三十几格的单子想知道"到底哪几格没配上屏",翻是翻不动的。筛着的时候上移下移**停用**——
顺序是整张单子的事,隔着筛选挪一格说不清挪到哪儿去了,位次那一列写的也还是它在整份清单里的位置。
每行那颗「展示 / 不展示」挂着 tooltip,不上屏时说清是谁拦的(面板勾的 / 环节藏的 /
电脑上默认隐藏且没点名的),别让人以为按钮坏了。
配置排在最前面的是"这张表想让人看什么",不是"这一环能看什么"。下面四条优先级不变:
**筛出来那一批可以一次改完**:筛着或搜着的时候,那一行右侧多两颗「这一批 N 格全上屏 / 全收起」,
只作用于**当前列出来的那些行**。要"手机上只摆我点的这几格",路径是:筛「已上屏」→ 全收起 →
再逐格把自己要的那几格点开。没筛的时候这两颗不出现——一按就把整张表收掉,那是误操作现场。
它们走的是与逐颗按钮同一条路:普通格子写 `mobileHidden`,外部页面那一页与电脑上默认隐藏
那几格写这份配置,一颗都没动就不 emit(面板上没有"确定",空发一次会把画布标成未保存)。
1. **环节字段权限 `hidden`**:那一环不让看的格子,配了也不上屏(`perms[field.key] === 'hidden'`);
2. **整单「默认隐藏」**(`field.hidden`):连桌面都不摆,手机上更不摆;
3. **逐格「手机上不展示」**(`field.mobileHidden`):清单上那颗"不展示"写的就是它,
记在 `plan.hiddenMobile`,与环节藏起来的 `plan.dropped` 分两笔算;
4. **本环节要人填的那几格**(`needKeys`):由这一屏顶上那个「本环节要填」的填写块负责,
摘要里不重复出现——两版都一样。
## 4. 只剩两道闸:这一屏听这份清单
开了这一档之后,手机上那一屏只认两份说法,判据全项目只有一处——
`utils/mobileLayout.ts:mobileVisibilityOf`,摘要、完整单据、设计器面板、底部那句"上屏几格"
读的都是它(从前是四地各写一遍,才会出现"面板写着展示、手机上没有那一格"):
1. **这份清单本身**:逐格那颗「手机上不展示」(`field.mobileHidden`,与属性面板那颗同一个键;
外部页面那一格记配置的 `hidden`)——记在 `plan.hiddenMobile`;
2. **本环节字段权限说「隐藏」**(`perms[field.key] === 'hidden'`)——记在 `plan.dropped`。
权限问的是"这个人此刻能不能看",配表的人说了不算,所以它压在配置之上。
3. **这一格配的「显示条件」此刻不成立**——记在 `plan.dropped`。只有待办那一屏给得出那份表单值,
单据详情与设计器面板给不出,那一档就不评(判据与分寸见 §4.2)。
不在闸里的两件事:**整单「默认隐藏」**(见 §2 与 §4.1,清单点过名就摆,没点名算 `dropped`)、
**本环节要人填的那几格**(`needKeys`,由顶上那个「本环节要填」的填写块负责,这一节里不重复摆——
两版都一样)。
### 4.1 为什么这一版把它从闸里摘出来
原话:**「手机端配置的字段显示,感觉还是被默认隐藏遮住了——手机这边完全按手机端的配置来展示,
我配置哪些字段显示就展示。」** 生产那张单上 `PMS项目编号 / PMS项目名称 / VDI项目编号 / 行政项目编号 /
定制项目编码…` 全挂着「默认隐藏」(电脑上不占位,取数照跑),于是清单上每一行都写着「展示」、
底下统计也把这几格算成"上屏",手机上那一格却一个都不出现——配了和没配一个样。
摘出来之后仍留了一道"没表态就不摆"(`fields[].show` 只有点过「展示」才写),
因为这两件事本来就不同:**默认隐藏是配表的人在电脑上定的,这一屏是他在手机上定的**,
谁最近表过态听谁的。真想让某一格在哪儿都不露,属性面板那颗「手机上不展示」比它更直接,
而那一颗压得住 `show`。
那一页外部页面还多一档:环节把整个「标签页」那一格藏了,或者只藏了那一页
(`formPerms` 里那个 `标签页格子key#页签key`),卡片都不摆,记进 `plan.dropped`。
@ -160,16 +218,60 @@ if (mobile) return planByMobileLayout(mobile)
单据详情那一屏(`MobileWorkView.vue`)原本就没第二条路了,于是那条入口收进顶栏的 `···`
——**要的是"只有一节",不是"这一单在手机上看不全"**。待办那一屏的 `···` 本来就有这一条。
这一版给它补了一句:**摆哪几格改成跟摘要共用 `mobileVisibilityOf`**,短名也照配置里的
`fields[].label` 念。它自己的分节、空值留行、外部页面给卡片那些一条没动——
但摘要里摆得出来的格子,到「完整单据」里不该因为整单「默认隐藏」又消失一次。
两屏对不上号比哪儿少摆几格难查得多。待办那一屏的 `···` 也跟着这条走:摘要末尾那一行还在时
不重复列,配置说不要那一行时才挪进 `···`。
### 4.2 「显示条件」也归这一句判据管:只有办单那一屏给得出那份值
原话:**「我的电脑端与手机端表单中默认隐藏,是不是都可以根据表单中字段的判断来控制是否展示呢?」**
电脑上那一寸早就挪到条件后面了(`formruntime.hidden_by_default` / `formRuntime.hiddenByDefault`:
勾了「默认隐藏」又配了「显示条件」的格子归条件管,见 `README.md`「字段自己也能说『我默认不显示』」
那一段)。手机上没挪——`mobileVisibilityOf` 与 `useFormPlan` 里那三处读的都是裸 `field.hidden`,
`visibleWhen` 一个字都不评。于是同一张单两屏各说各话:`费用类型` 在电脑上一拨条件就露出来,
手机上划到底也没有它;反过来条件已经翻走的格子,电脑上不摆了,手机上还留着一行谁也改不动的值。
现在四道闸一句排到底,与桌面 `effectivePerm` 一一对应:**手机上不展示 → 本环节隐藏 →
显示条件不成立 → 整单默认隐藏**,前两道压得住后两道。判据多出来的那个取值叫 `cond`,
摘要、完整单据、面板统计都据它把这一格算进"收起"。
**给得出那份值的才评条件**,这是分寸不是偷懒:
* **待办那一屏给**(`MobileTaskView` 里 `canProcess ? ctx.formData : null` 那一句)。办单的人正在改
条件里那些值,格子就该跟着露跟着藏,与桌面 `TaskDetailView` 那句 `:readonly="!canProcess"` 同一判据;
这条待办已经不在他手上(已办、挂起、只是回来看看),退回下一条那一寸。
* **单据详情那一屏不给"正在填的那一份",但手上还有存过的那一份**(`MobileWorkView` 传下来的 `data`)。
那一屏说的是"存过的都摊开给他看",所以条件在这一屏只**放行**不**收**:勾了「默认隐藏」又配了
显示条件的那一组,按存过的那份值评,成立就上屏;只配了条件、没勾默认隐藏的格子照旧摊开,
不凭条件把已经存了值的一行划走。判据 `utils/formRuntime.readbackHidden`,桌面只读渲染读的是
同一句,两屏不分家。**这一寸是 2026-11 补的**:从前这两屏连条件都不评(那句
`props.readonly ? null : model.value` 明摆着承认算不了),于是 `出差备案申请` 按「项目分类」
放行那八格项目 / 客户,办理那一屏露得好好的,办结之后回看一格不剩。
* **设计器面板给不出值,但也不按回看那一寸报**:那儿问的是"这一格归谁管",所以按
`hiddenByDefault` 报——条件格在清单上显示成「按显示条件」而不是「电脑端默认隐藏」,
那颗开关点出去写的是格子上的 `mobileHidden`,面板不代它记一笔 `show`。要记也没用:
`show` 压的是整单默认隐藏那一档,而那一档对配了条件的格子本来就不说话;更糟的是那一笔
会把回看那一屏里本不露的格子凭空放出来。
后端这一头不用跟着改:`service/formruntime.field_hidden` 一直都算联动,提交收哪些键
(`editable_keys`)、必填缺哪些(`missing_required`)、阈值额度挡不挡人(`quota.hidden_keys`)
认的都是这一句。改的只是手机上那两屏读不读它。
## 5. 验收
不改代码就能看的两条:
```bash
cd frontend && pnpm dev
# 配过的样子:http://localhost:3000/preview-mobile.html?screen=detail&form=custom
# 配过的样子(含"电脑上默认隐藏、清单点了名"那一格 PMS项目编号;VDI 那格没点名,不摆):
# http://localhost:3000/preview-mobile.html?screen=detail&form=custom
# 节名留空(整屏就这一节,那一行标题不摆):http://localhost:3000/preview-mobile.html?screen=detail&form=custom&title=none
# 没配的样子(对照):http://localhost:3000/preview-mobile.html?screen=detail&form=tabs
# 面板本身:http://localhost:3000/preview-mobile.html?screen=panel
# 面板本身(清单上那颗筛选、搜字段名、两格"电脑端默认隐藏"的角标):
# http://localhost:3000/preview-mobile.html?screen=panel
```
`title=none` 这一档看的是「配了开关但没起名字」:节名回落到第一个页签名(那张假单子有页签,
@ -177,15 +279,19 @@ cd frontend && pnpm dev
预览台是 dev only 的(`src/dev/mobilePreview.ts`),吃真的版式组件、真的词条、真的 Tailwind,
数据用 `mobileFixtures.ts` 那份假报销单——**不打后端、不碰数据库**。
`form=custom` 那份配置照面板存盘的形状补齐:清单没点名的格子一律标成 `mobileHidden`,
所以那一屏摆的正好是清单上写了「展示」的那几条——与在真设计器里点过一遍的表单同形。
测试(`cd frontend && npx vitest run`,全套 1363 条):
测试(`cd frontend && npx vitest run`,全套 1579 条):
| 文件 | 盯什么 |
| --- | --- |
| `utils/mobileLayout.spec.ts` | 配置读不读得出来、清单顺序、摆法回落、删格补格对账、外部页面那一格的键与开关 |
| `components/oa/mobile/useFormPlan.spec.ts` | 只出一节、系统取数不再并走、空值照样摆、四道闸、置顶上限、明细两档、入口开关、外部页面那张卡片与它的两道闸、节名是配置起的还是兜底的、部门那一格只念部门名 |
| `components/oa/mobile/MobileFormSummary.spec.ts` | 屏幕上真是那样:不折叠、`—`、明细逐条、缩略图、卡片带对 `job`/`activity`/`slotKey`、开关没开时还是从前那版、节名没配就不摆那一行标题 |
| `components/oa/design/MobileLayoutPanel.spec.ts` | 清单对得上现在这张表、改动当场 emit、上不上屏写的是 `mobileHidden`(外部页面那一行例外,写配置的 `hidden`) |
| `utils/mobileLayout.spec.ts` | 配置读不读得出来、清单顺序、摆法回落、删格补格对账、外部页面那一格的键与开关,以及**那一句判据的整张真值表**(默认隐藏点没点名 / 环节说隐藏 / 环节明给只读 / `mobileHidden` 压过 `show` / 条件成立与翻走的四种问法:`{data}` 评条件、`{data, readback}` 只放行不收、不给值不评、`{design}` 按"条件说了算"报) |
| `components/oa/mobile/useFormPlan.spec.ts` | 只出一节、系统取数不再并走、空值照样摆、三道闸、整单默认隐藏点名的那格上屏、条件成立时它自己就上屏而条件翻走后与普通条件格一起下去(配了版式与自动归置两条路各一条、`condData` 给不给两种)、回看那一屏拿存过的那份值只放行「默认隐藏 + 显示条件」那一组、置顶上限、明细两档、入口开关、外部页面那张卡片与它的两道闸、节名是配置起的还是兜底的、部门那一格只念部门名 |
| `components/oa/mobile/MobileFormSummary.spec.ts` | 屏幕上真是那样:不折叠、`—`、明细逐条、缩略图、卡片带对 `job`/`activity`/`slotKey`、开关没开时还是从前那版、节名没配就不摆那一行标题、电脑上「默认隐藏」那格点过名的摆出来而没点名的不出现、条件格在办单屏跟着条件露与划、回看屏按存过的值把「默认隐藏 + 条件」那组摆回来而普通条件格照旧摊开 |
| `components/oa/mobile/MobileFormReader.spec.ts` | 「完整单据」跟摘要同一句判据:清单点了名的默认隐藏格也摆、勾掉的两屏都不摆、配过的短名两屏念同一个名字、条件不成立的那几格只在办单那一屏消失(回看那一屏只放行不收) |
| `components/oa/design/MobileLayoutPanel.spec.ts` | 清单对得上现在这张表、改动当场 emit、上不上屏写的是 `mobileHidden`(外部页面那一行写配置的 `hidden`,电脑上默认隐藏那一行写配置的 `show`,配了显示条件那一行两笔都不写、角标写「按显示条件」)、底部那句统计与清单同一句判据、搜与筛、筛着时排序停用 |
| `components/oa/mobile/MobileFlow.spec.ts` | 审批记录**整条不折叠**:十二环的单子摆十三行、没有「展开更早」那颗钮、发起那一行在最前 |
| `views/oa/design/FormDesignerView.mobile.spec.ts` | 配完存得出去(`content.layout.mobile`)、重开读得回来、进撤销栈与未保存、删掉的格子不留死配置 |
后端那一头只验一件事:这份配置存出去还在。`clean_option_source(clean_formats(content))`

View File

@ -304,6 +304,33 @@ Authorization: Bearer {oat_…} ← 那一段是流
卡片由一个纯函数从环节配置生成,**设计器「外部审批」页签里展示的那张、事件里递出的这份、
对接文档里的示例,出自同一处**——三处各写一份的文档一定会漂。
## 4.4 `task.completed` 里的 `processingType`:这一步到底怎么结束的
订阅了 `task.completed` 的系统都卡在同一个地方:它不敢决定要不要把**自己手上那条待办**
收掉,更不敢替用户记一笔「已同意」。信封里的 `processingType` 就是回答这一句的,
一共七个取值:
| `processingType` | 这一环是怎么结束的 | 第三方该怎么理解 |
| --- | --- | --- |
| `normal` | 持有人自己按了那颗钮(OA 界面,或这条 `decide`) | 有人真表过态,按 `route` 记结论 |
| `auto` | 会签凑够票 / 或签别人先点了,系统替剩下那几条收尾 | **没有第二个人表态**,别记成「某某也同意了」 |
| `goBack` | 退回(含退回发起人) | 单据往回走了:收掉待办,不算同意 |
| `transfer` | 转办:待办换人,原主人那条结束 | 换人,不是办完 |
| `addBefore` | 加签:这一环临时多几个人 | 原那条结束,新几条在路上 |
| `terminate` | 整单终止 / 作废 | 这张单没有下一环了 |
| `move` | **管理员干预改道**:这一环被换路,待办随之结束 | 没人同意过;往前还是往后,看随后的 `task.arrived` |
判据一句话说死:**除 `normal` 以外,一律不许当成「有人同意了」**。认不出的取值按
「这一步结束了、原因未知」处理——待办收掉,结论不动。前六档一直在推,`move` 是
2026-11 干预那一篇补的(见
[`intervention-todo-and-message-settlement-design.md`](./intervention-todo-and-message-settlement-design.md))。
同一批变更里还有一条要提前打招呼:`task.arrived` 的**幂等键带上了待办号**(原先是
`hook:事件:单号:环节名`)。同一个环节第二次到达——改道回来、退回重走——以前会被那句
去重吞掉,订阅方手里只剩一条已经作废的待办号,照着它调 `decide` 必然失败;现在会再推
一条,`task.id` 是新的。一直按 `idem` 去重的订阅方会照常收到这第二条,正是它们缺的那个数。
历史 `idem` 不重算。
## 4.5 不订阅事件也能动手:拉取式定位(`/open/nodes/locate`)
§4 那条路是**推**:OA 在单走到那一环的瞬间把卡片递过去。但对方系统跑在自己的定时任务、

View File

@ -52,8 +52,10 @@ Hub 只认两种收件人标识:`user_id`(`users.hub_user_id`,人员主键
## 2. 事件
`channels.EVENTS` 六项,**取值与 `oa_notification.type` 完全一致**——同一个"新的待办"在站内信和
邮箱里必须是同一件事,两套取值迟早对不上:
`channels.EVENTS` 七项,**取值与 `oa_notification.type` 一致**——同一个"新的待办"在站内信和
邮箱里必须是同一件事,两套取值迟早对不上。只有一档例外:`rerouted` 在站内仍旧是 `control`
(挂起 / 恢复 / 改数据 / 改道共用站内那一类留痕,不该拆成四档),只有往外发的那一路单独立一个名,
好让渠道能只勾「流程被干预改道」而不必把整类 `control` 都推出去:
| 事件 | 含义 |
| --- | --- |
@ -63,6 +65,7 @@ Hub 只认两种收件人标识:`user_id`(`users.hub_user_id`,人员主键
| `completed` | 办结结果 |
| `expire` | 待办超时 |
| `meeting` | 会议提醒 |
| `rerouted` | 流程被干预改道(站内那条是 `control`;存量渠道的 `events` 里没这个值,默认一句都不往外推,要谁勾谁) |
渠道上勾事件,不勾就一条不发。全局还有一个总开关(系统设置 → `notify_channels_enabled`),
关掉之后站内信照写、渠道一条不入队——**入队前先看开关**,所以关掉它不会给办结、提交这些热路径
@ -172,7 +175,48 @@ engine.notify() ──同一事务──▶ oa_notification(站内信)
`hub_wecom` 是个例外的一半:Hub 给的是**逐人投递结果**(送到企微了没有)而不是已读,
界面上有个「回查送达」按钮按 `msg_key` 去问一次,仍然不承诺"他看过了"。
## 8. 验收
## 8. 站内信自己的生命周期:事项办完,提醒就该退
渠道那一层管"同一句话怎么再送一份出去",这一节管**站内信这一份在本系统里活多久**。
用户报的是最直白的一种现象:待办全部办完,右上角铃铛里那叠通知还挂着四条
「您有新的待办」,小红点不灭;按了「全部已读」,列表照旧摆在原处。
根因不在界面,在库:`oa_notification` 只在写进去的那一刻有人看。`engine.notify()`
发完就不管,接口只有「点开算已读」与「全部已读」两个手动口子;而**待办本身是会消失的**
——`_complete_task` 直接删行、或签把同级一起结掉、转办与交接换持有人、终止与办结清空整单,
每一条都不回头动站内信。于是这张表变成一份只进不出的流水,越堆越厚。
判据只有一句:**一条提醒值不值得摆着,看它指向的那件事还在不在收件人自己手上**。
落在 `app/service/notify_settle.py::settle()`,两条 UPDATE:
| 类型 | 什么时候收尾 |
| --- | --- |
| `task` / `press` / `expire` | 那条待办(`oa_notification.task`)已经不在收件人名下——办完、转走、被或签结掉、整单终止都算。没记待办号的老数据退一步按「这一单上还有没有我的待办」判 |
| `read` | 这一单上已经没有收件人的待阅(`mark_read` 与办结搬档都是删行) |
| `completed` / `control` / `meeting` / `integration` / `check` | **永远不收**:说的是已经发生的一件事,不指向任何要办的东西。终止那句「待办已终止」就是 `control`,它是新消息而不是过期提醒 |
三处取值与判据的对应关系值得记一下:这三类正好是 `channels.HUB_TASK_EVENTS`
(点开落待办页、要人办事的那一族),而 `EVENTS` 里除 `rerouted` 之外的事件名与
`oa_notification.type` 一字不差——同一件"新的待办"在站内信、邮箱、企微里必须是同一件事,
两套取值迟早对不上。`rerouted` 那一条例外见 §2。
**收尾挂在读出口,不挂在写出口。** 待办消失有七八条路子(办结、或签自动结、转办、
交接、退回、撤回、终止、管理员改派),在引擎里逐处挂钩子等于留七八个"漏挂一处就再报一次"
的坑,而且升级前那些早就该退的存量通知一条也补不回来。收在 `GET /notification`、
`GET /notification/unread/count`、`GET /statistics/workbench` 三个出口,
一条 UPDATE 判完,八条路子连历史数据一起管住。代价是"读一次库会写一次已读",
换来的是列表、角标、工作台那个数字**永远是同一份账**;没未读时那条 COUNT 直接回 0,
一条 UPDATE 都不许多跑(这颗角标 15 秒问一次)。
收尾是**标已读**(补 `read_time`),不是删行:投递记录 `oa_notify_delivery.notification`
要能回查对应的那条站内信,"谁在什么时候收到过什么"也不该因为事项办结就从库里蒸发。
界面这一侧跟着收一次口径:铃铛下拉、手机版通知弹层、首页那张通知卡片**只摆没读过的**。
这一屏是"还有什么没告诉你",不是历史归档——读过一条就退场,事项办完的那条由后端收尾;
要翻旧账去待办 / 已办 / 待阅 / 单据详情。以前这里连着已读的一起摆,
「全部已读」按下去列表纹丝不动,正是截图那一张的观感。
## 9. 验收
原本挂在 `backend/tests/oa_platform.py` 的那一整套(SMTP 桩 + 机器人桩)随测试目录一起
在 2026-10 清掉了,留着是说明这一层原本验到哪:事件订阅过滤、没邮箱落 `skipped` 并说明原因、
@ -213,4 +257,5 @@ Hub 缺 `home_url` 时摘掉深链降级成纯提醒而其它 `400` 不瞎降级
```bash
cd backend && PYTHONPATH=. python3 scripts/check_notify_hub.py
cd backend && PYTHONPATH=. python3 scripts/check_notify_hub_api.py # 这条要连开发库
cd backend && PYTHONPATH=. python3 scripts/check_notify_settle.py # §8 站内信生命周期(内存 sqlite,不碰生产库)
```

View File

@ -19,7 +19,7 @@
| 定时 / 延迟环节 | 已有 | `delay` 环节 + `wake_delays()` |
| 退回、加签、转办、撤回、催办、终止、代理、交接 | 已有 | `engine.py` 各动作 + `oa_agent` / `oa_handover` |
| 抄送(到达时 / 办结时,可按条件只抄部分人) | 已有 | 环节 `config.ccRules`,每条可带 `expression` |
| 审批评论、附件、已读 | 已有 | `oa_work_comment` / `oa_attachment` / `oa_read` |
| 审批评论、附件、已读 | 已有 | `oa_work_comment` / `oa_attachment` / `oa_read`;批注、审批意见、「抄送需处理」的处理意见都能带图片/文件(`oa_attachment.type = comment / opinion / read`),在途与归档同一判据(详情报文的 `can_comment` + `engine.add_comment` 再判一次) |
| 版本快照与回滚 | 已有 | `oa_process_version`,回滚接口 |
| 编号规则 | 已有 | `oa_serial_number`,`next_serial()` |
| 空审批人兜底(转发起人 / 自动通过 / 报错) | 已有 | 环节 `config.emptyApprover` |
@ -39,9 +39,10 @@
| 能力 | 状态 | 落脚 / 说明 |
| --- | --- | --- |
| 字段级「默认隐藏」(不显示但照常存值) | 已有 | 字段 `hidden`,表单设计器上那个开关;环节 `formPerms` 显式给别的权限就盖过来,口径 `service/formruntime.effective_perm` |
| 字段级「默认隐藏」(不显示但照常存值) | 已有 | 字段 `hidden`,表单设计器上那个开关;环节 `formPerms` 显式给别的权限就盖过来,口径 `service/formruntime.effective_perm`;配了「显示条件」的格子归条件管;手机上「摆不摆」全项目只有一句判据 (`utils/mobileLayout.mobileVisibilityOf`,见 `docs/mobile-form-layout-config.md` §4.2) |
| 外部取数的时机 | 已有 | 字段 `fetch.revalidateAfter`(填单页到点自动重取,绕开数据源缓存)与 `fetch.freezeAfterStart`(流程发起后不再调、不再改这几格;判据是「还在不在开始环节」)。口径 `service/fetch.applies_at` 与 `utils/formFetch.fetchAppliesAt`,验收 `scripts/check_fetch_freeze.py` |
| 一个字段用多个外部数据源的合集 | 已有 | 字段 `fetch.sources`(最多 8 个)+ `merge`:`first` / `sum` / `min` / `max` / `join`(`separator`);缺源时只有 `first` 继续,其余按 `onError` 处理。口径 `service/fetch.field_sources` `merge_values`,前端镜像 `utils/formFetch` |
| 明细表的列逐行取数 | 已有 | 列上那份 `fetch` 与主表字段同一形状、同一执行器,按行各跑一次:入参读「整张单 + 这一行」(同名列以本行为准,与本行公式同一作用域),`picks` 只落在这张表的其它列,报错点明第几行,整张表被本环节藏起来时 `onError=block` 降级。留痕按 `表名.列名` 记、底下挂逐行那几次外呼。口径 `service/fetch.row_fetch_fields` `_apply_rows` 与 `utils/formFetch.rowFetchScope`,见 `docs/form-data-integration-design.md` §9.2,验收 `scripts/check_row_fetch.py` |
| 31 种字段类型 | 已有 | `api/design.py` `FIELD_TYPES`,前端同步在 `types/index.ts`、`utils/formLayout.ts`、`FieldLibrary.vue` |
| 明细表(子表格)+ 行级必填校验 + 最少行数 | 已有 | `service/formruntime.py` |
| 计算公式字段(含循环引用检测) | 已有 | `engine/expressions.py`、`schema_problems()` |
@ -61,6 +62,7 @@
| 打印视图 / 打印模板 | 已有 | 路由 `/print/work/:job` → `views/oa/PrintWorkView.vue`,复用只读表单渲染 + `@media print` |
| 列表数据导出 CSV | 已有 | `api/export.py`:`GET /export/works`、`GET /export/tasks`,UTF-8 BOM,同一张表单时摊开表单列 |
| 关联审批单(引用历史单) | 已有 | 字段 `type=relation` 存对方 `job`;`GET /work/related` 挑选、`GET /work/summaries` 回显 |
| 关联带出(把挂着的那几张单的值写进本单) | 已有 | 字段 `linkFill`(来源=流程单据那一格上);主表字段按合并档合成一个值、明细表一单一行;`backend/app/service/linkfill.py`,方案见 [relation-link-fill-design.md](relation-link-fill-design.md) |
| **自定义报表 / 数据看板** | 缺口 | 只有固定统计页 |
| **明细表内的字典级联与带出** | 缺口 | 级联、带出、清失效值目前只覆盖主表单字段 |
| **富文本 / 手写批注 / 电子签章** | 缺口 | 无对应字段与控件 |
@ -96,6 +98,7 @@
| 按比例会签 | 环节 `mode=ratio` + `passCount` / `passRatio`,`engine._ratio_votes()` | 够票即放行;有人明确退回仍立刻退回,比例只决定同意要几个人 |
| 汇聚 N 票放行 | 汇聚环节 `passCount` / `passRatio`,`tickets.required_votes()` | 配额抄进票箱,退回重跑仍是同一口径 |
| 关联审批单 | `type=relation` + `GET /work/related` / `GET /work/summaries` | 挑选范围限「我发起 / 我办过 / 我被抄送」,存对方 job |
| 关联带出(含挂多张) | 字段 `linkFill.rules[{pick,to,agg}]` + `service/linkfill.apply`(挂在 `_apply_form_runtime`,公式之前) | 挂几张都行:主表那一格按 `agg` 合成一个值,明细表一单一行(行上 `_link` 认来源),只在挂着的那串值变了时重排 |
| 批量审批 | `POST /task/batch-execute` + 待办列表多选 | 逐条事务:一条失败只回滚那一条,原因原样带回界面 |
演示与验收:`backend/scripts/demo_newcap.py` 往开发库搭三套演示流程(签名与关联 / 比例会签 / 汇聚放行),

View File

@ -3,7 +3,13 @@
> 相关:[external-data-simplification.md](external-data-simplification.md)(字典怎么吃外部数据源)、
> [form-data-integration-design.md](form-data-integration-design.md)(五种取数形态)、
> [data-binding-unification-design.md](data-binding-unification-design.md)(这一篇的候选来源
> 与「字段上的外部取数」为什么是两个配置项、它们底下共用的是哪一层)。
> 与「字段上的外部取数」为什么是两个配置项、它们底下共用的是哪一层)、
> [relation-link-fill-design.md](relation-link-fill-design.md)(来源 = 流程单据那一格挑中之后的
> 那几张单,值怎么倒过来写进这一张单的主表字段与明细表)、
> [designer-panel-dialogs.md](designer-panel-dialogs.md)(这一栏在界面上长在哪儿:属性侧栏
> 只留一行入口,候选来源、显示映射、关联带出那三块摊在同一扇门里),
> [option-source-routing-design.md](option-source-routing-design.md)(**同一格挂好几套候选来源**,
> 按这张单上的值换一家:`optionRoutes` 那份有序清单与「带出的值也收下」那一档)。
> 这一篇讲三件事:**一格的候选从哪儿来**、**这一行给人看哪一列 / 往数据里写哪一列**、
> **用什么姿势挑**,以及为什么这三件事本来就该是一件事。
@ -21,6 +27,8 @@
| 新接口 | 没有。流程单据走现成的 `GET /work/related` + `GET /work/summaries`,外部数据源走现成的 `GET /data-source/options`,字典走 `POST /process/dicts/values` |
| 越界校验的边界 | 手填 / 字典判「值必须在候选里」;流程单据与外部数据源**不判**——服务端手上永远只有搜出来的那一页 |
| 唯一口径在哪 | 前端 `src/utils/optionSource.ts` + `src/utils/optionMap.ts`,后端 `backend/app/service/dicts.py`(`source_kind_of` / `constrains_values` / `stored_of` / `shown_of`)。控件只有一只:`components/oa/OptionPicker.vue`;设计器只有一栏:`components/oa/design/OptionSourcePanel.vue` |
| 同一格换一家 | `field.optionRoutes`:一份**有序清单**,每条 = 一个触发条件 + 一套候选来源配置,自上而下第一条成立的用它,都不成立回落到上面这三格——「报销类型是差旅时问差旅字典、是招待时问 ERP 的费用科目」不必再摆三格(见 [option-source-routing-design.md](option-source-routing-design.md)) |
| 带回来的值不在候选里 | `field.allowOutsideValue`(默认关):勾上之后外部取数 / 关联单据带出 / 字典带出写进来的那个值不清、不拦,界面上补一行「带出」候选站着 |
| 第四维(只做给看) | `field.picker`:下拉那一档与弹出框那一档**各看哪几列**(主显示列 / 副标题几列 / 行尾徽标),外加弹出框的搜索框开关、搜索列、每页条数、标题。纯展示——存出去的值一个字节都不变(见 §8) |
| 左侧两格组件 | 「下拉框」(`select`) 挂表单自己的数据(手填选项 / 数据字典),「下拉选择」(`picker`) 挂别处的数据(外部数据源 / 流程单据)。同一只挑选器,两种定位;定位只是**给挑的清单**,不是技术边界(见 §8) |
| 关联审批单去哪了 | 它就是「来源 = 流程单据、姿势 = 弹出框」那一格。原来的 `RelationPicker.vue` 删了,弹窗那套(搜索、单号 · 流程 · 发起人、状态角标)原样搬进 `OptionPicker` |
@ -65,7 +73,7 @@
| --- | --- | --- | --- |
| `manual` 手填选项 | 选项的 `value` | 就写在字段的 `options` 上 | 判 |
| `dict` 数据字典 | 字典项 `value` | `dictCode` 那本字典(字典自己可以是手工的,也可以是从外部数据源同步下来的) | 判,含级联上级过滤 |
| `process` 流程单据 | 对方单据的 `job` | `GET /work/related`(限「我发起 / 我办过 / 我被抄送」,管理员不限),`relationProcess` 可限定只看某个流程 | **不判** |
| `process` 流程单据 | 对方单据的 `job` | `GET /work/related`(限「我发起 / 我办过 / 我被抄送」,管理员不限),`relationProcess` 可限定只看某个流程,`relationStatuses` 限定只看哪几种状态(**默认只给归档通过的**,见 §11) | **不判** |
| `dataSource` 外部数据源 | 源给的编码 | `GET /data-source/options`,即列表型源 + 关键词按需搜,限流 / 缓存 / 留痕都在后端 | **不判** |
表里那四列都只是**默认**:同一条候选的别一列也能当值、当显示文字,改不改由 §4 那一维定。
@ -178,7 +186,7 @@ AI 起草、流程副本那几条不进设计器的路也是这个结果。
| 设计器 | `frontend/src/components/oa/design/OptionSourcePanel.vue` | 来源 → 就地配它自己的东西 → 挑选方式,外加数据源「试搜一页」;配完想直接看填出来的样子,`/design/forms/{id}?view=preview` 一步进预览 |
| 左侧两格 | `frontend/src/components/oa/design/FieldLibrary.vue` + `utils/optionSource.ts` 的 `OFFERED_SOURCE_KINDS` | 「下拉框」与「下拉选择」两格各自悬停说一句分工;`offeredSourceKinds` / `sourceKindChoicesOf` 决定这两格里各能挑哪几种来源(已经在用的那一条永远留着) |
| 接线 | `FormFieldControl.vue` / `FieldInspector.vue` / `LinkagePanel.vue` | 选择类字段一律走 `OptionPicker`;原来散在中间的选项编辑器、联动面板里的字典来源、关联审批单那块流程范围,合成上面那一栏 |
| 明细列 | `FieldInspector.vue` 列编辑区 | 两栏窄版:来源 + 挑选方式,下面跟着摆该来源那一格(字典下拉保留原有那行「能选到什么」预览) |
| 明细列 | `FieldInspector.vue` 列编辑区 | 一列一张卡,卡里摊成一张 12 栏网格:标题 / 类型 / 标识 / 必填 / 只读 / 删除钉在第一行,来源 + 挑选方式与它那几格跟着并排(字典下拉保留「能选到什么」那一行预览,只是挪到了字典那一格下面);用不上的格子不摆,后面的往前靠(那一列锁不锁见 `form-field-catalog.md` §2.8) |
| 后端把关 | `service/dicts.py` / `service/formruntime.py` | `source_kind_of` / `holds_list_value` / `constrains_values` / `effective_options` / `stored_of` / `shown_of` / `project_options` / `option_map_problems` / `picker_display_problems` / `option_source_problems` |
| 后端清洗 | `api/design.py::clean_option_source` | 保存时按来源收掉不属于它的键,与 `clean_formats` 同一位置同一套道理 |
| 导出 | `api/export.py` | 来源不是流程单据的关联格不再拿单据名册去翻,按候选来源翻标签 |
@ -289,3 +297,100 @@ src/components/common/Select.spec.ts src/components/oa/design/OptionSourcePanel.
`Select.spec.ts` 盯那只下拉加复数之后最容易被挤坏的地方(单选点完还是发单值并收起弹层、
多选连着勾不关弹层、摘标签与清空发的是什么、窄格子里「+N」、跨页挑中的靠 `known` 念名字),
以及换来源时只清「看哪几列」那几格、搜索与每页条数留着。
## 10. 挂上来的那几张单点得开(2026-11)
关联审批单选完只看得见一串名字,想看那张单得记住单号回列表里搜——PC 与手机都撞这堵墙。
这一层不加配置项:**「来源 = 流程单据」这一条来源,名字本身就是链接**,落在 `/work/:job`
(路由名 `work-detail`)。判据与实现只此一处,`frontend/src/components/oa/OptionPicker.vue`:
- `workHref(job)` 按路由名解析,将来路径改了不必回来改这里;没挂 router 的场合(组件单测、
内嵌预览)退回路径写法。注入用的是 `inject(routerKey, null)` 而不是 `useRouter()`——
后者不带默认值,没挂 router 时会在控制台留一条 warning。
- 四个来源里只有 `process` 那一支给 `PickRow.href`,字典与外部数据源没有单据可开,一个链接都不加。
- `optionMap` 改存了单号那一列时,先经 `knownIndex` 翻回 job 再拼地址;翻不回就不给地址——
一个开不去的链接比一句念得出单号的死文字更坑人(`processHref`)。
链接画在哪儿,跟着「这一格此刻是什么样子」一处一处补:
| 那一格此刻 | 点哪儿 | 怎么画 |
| --- | --- | --- |
| 只读 · 一串值 | 标签牌上的名字 | 真 `<a target="_blank">`(牌子在 `div[role=button]` 里,套得住 `a`) |
| 只读 · 单个值 | 那一句话,多条时逐句分开,不是一整段死文字 | 同上 |
| 编辑 · 弹出框 | 挂在框里那排标签的名字 | 同上,`@click.stop` 不让它顺手把挑选弹窗也打开 |
| 编辑 · 下拉多选 | 框里那颗标签的名字 | `Select` 的触发器本身是 `<button>`,套不住 `a`:`span[role=link][tabindex=0]` + `window.open`,回车一样点得开 |
| 编辑 · 下拉单选 | 框里那一句话 | 走 `Select` 已有的 `selected` 插槽,仍是真 `<a>` |
手机端两处都跟着这一份实现走,不另写一套。审批那一屏本来就走 `FormRenderer` → `OptionPicker`,
自动就有了;「完整单据」那一屏(`mobile/MobileFormReader.vue`)原来只念 `useFormPlan.fieldText`
算出来的文本,关联那一格于是把 job 原样摊在 390px 的屏上——现在那一格单独走 `OptionPicker`
的只读态,念回标题,也点得开。`/work/:job` 是 PC 与手机共用的那一条路由(`WorkDetailView`
自己按设备切 `MobileWorkView`),所以一个地址两头都打得开;开在**新标签页**是有意的——
从填单那一屏跳走会把手上还没提交的这张单弄丢。
字号:单据标题动辄「某某某发起的某某流程」再加单号、流程名、发起人,默认的 `.field-tag`(12px)
在窄格子里两三个就占满一行。`source === 'process'` 时这一排牌子收一档(`.picker-dense`:11px,
内边距与图标跟着缩)。类名挂在只读那一块的根上,下拉与弹出框两档透给 `Select` / `ComboTrigger`
的根节点;**规则本身写在全局 `style.css` 里、挨着 `.field-tag`**,不写成组件里的 scoped 样式——
牌子是这两只通用控件画的,收在全局一处,既不用赌 scoped 样式穿不穿得进子组件,也不用给它们
各加一个「要不要小字」的开关。**全局那条 `.field-tag` 一个字没动**:人员选择器与附件还要它
本来的样子。
顺手修掉一个真 bug:`resolveJobs` 要先经 `knownIndex` 把存着的值翻回 job,而那一趟
`watch(immediate)` 以前挂在 `knownIndex` 定义**之前**——「改存单号」的那一格一进来就撞 TDZ,
吃一个 unhandled rejection,摘要再也取不到。症状只是念不出标题,所以一直没人看见。
钉在这儿的行为:`OptionPicker.spec.ts`「关联的单据点得开」(只读两档的 `href` 与 `target`、
弹出框点名字不顺手开弹窗、下拉那颗标签走 `window.open`、存单号时链接仍落在真 job 上、
字典与外部数据源一个链接都不给、挂了 router 时按名字解析)、`Select.spec.ts`
「框里那颗标签点得开」(有 `href` 才画链接、`known` 里补的落点也算数、回车开单但不改选择)、
`MobileFormReader.spec.ts`「手机上关联的那几张单」(念回标题 + `/work/J1`、问不到摘要退回存着的值、
空着仍留一行破折号)。
没做的两件事:手机端**摘要**那一屏与明细表里的关联列仍然是一行文本——`useFormPlan` 那两版
明写了「不渲染控件」,值全靠 `fieldText` 算,而它手上没有取摘要的路由。逐格读本来就走
「完整单据」。要把摘要那一屏也换成控件,得先给它一条取摘要的路。
## 11. 挂上来的单得是走完的那一种(2026-11-10)
「关联已审批流程」这个名字承诺的是**已经批完的单子**,而它当时的候选是把两张表混在一起搜的:
在办表 `oa_work`(只有 `running`)加归档表 `oa_work_completed`(`completed` 是走完归档通过、
`terminated` 是被人中途终止、`canceled` 是作废)。于是报销单能挂上一张走到一半被终止的借款单,
而"被终止"这件事往往发生在挂上之后——审批人点开对照时才发现依据是一张没走完的单子。
配置项就一格:`relationStatuses`,三档的清单,界面上是一排复选框。
| 档位 | 给人看的说法 | 落到库里 |
| --- | --- | --- |
| `completed` | 已办结归档 | 归档表 `status == 'completed'` |
| `running` | 还在办 | 在办表 |
| `closed` | 已终止 / 已作废 | 归档表 `status in ('terminated', 'canceled')` |
定下来的几件事:
- **默认只给 `completed`**。没配过的表单一个新字段都不加,读出来就是这一档——名字说
「已审批」,候选就该是审批完的。要放宽(比如借款单还在走就想先挂上)在设计器那一排勾上,
三档全勾等于不限,接口上就是不加状态条件。
- **这一档只管候选列不列它,不判已存的值**。单据是挂上之后才被终止的,按这一档拦提交等于
回头骂填单的人;回显走 `GET /work/summaries`,按 job 直接问摘要,照旧念得出标题和
「已终止」那个角标。这与 §2 那句「搜出来的来源不判越界」是同一条分寸。
- **摊到两张表时谁不沾就不查谁**:只勾归档通过那一档,在办表一个候选都出不了,
那条 UNION 分支整个不发出去(`relation_status_tables` 回 `None` 就是"这张表别查")。
- **接口上不加新参数**:还是 `GET /work/related?status=…`,只是这一句现在收逗号分隔的档位,
也认历史那种单据状态原值(`terminated` 归到 `closed`),老调用方读出来还是同一批单子。
- **换候选来源时这一档跟着 `relationProcess` 一起清**(前端 `optionSourcePatch` /
后端 `clean_option_source`),换成字典还留着一份"单据状态"是看不见的东西里最容易骗人的那种。
- **勾到一种都不剩在保存那一刻挡**:「至少勾一种状态:一种都不勾,这一格永远搜不到候选」。
运行时真读到空清单仍退回默认那一档,不让一只已经存下来的表单变成永远为空的挑选器。
- 措辞前后端各写一份(后端在 `service/dicts.py`,由 `formruntime` 转调),
`check_binding.py` 第 5 段逐句对。
设计器那一排复选框之外,填单弹窗在搜索框底下写一句「这一格只列已办结归档的单据」:
搜不到自己那张单的人,第一反应是"我没权限"或者"系统漏了单子",多写这一行比让人回设计器翻便宜。
钉在这儿的行为:后端 `PYTHONPATH=. python3 scripts/check_binding.py`
(「关联审批单能挂哪几种状态的单据」那一段:默认值、认不出的档位、老写法的状态原值、
两张表怎么摊、几句校验措辞);前端 `OptionPicker.spec.ts`
「来源=流程单据:候选只列哪几种状态的单据」(默认只问归档通过的、配了放宽就问那两档、
弹窗里那句说明、换了档位重捞一页、已选单据不受这一档影响)与 `OptionSourcePanel.spec.ts`
「关联审批单能挂哪几种状态的单据」(那一排复选框、勾回默认就把键抹掉、取样例按同一档取)。

View File

@ -0,0 +1,459 @@
# 同一格挂好几套候选来源:按这张单上的值换一家(`optionRoutes`)
> 相关:[option-source-design.md](option-source-design.md)(一格的候选从哪儿来、显示与存值、
> 挑选方式那三维;这一篇是第四维「同一格换一家」),
> [data-binding-unification-design.md](data-binding-unification-design.md)(候选来源与「字段上的
> 外部取数」为什么是两格、共用的是哪一层内核;这一篇给那两层各补一句「什么时候才用」),
> [field-self-visibility-design.md](field-self-visibility-design.md)(显示条件、回看那一屏、
> 藏起来的必填格),[form-field-catalog.md](form-field-catalog.md)(字段属性清单)。
>
> 用户那句原话:**「我一个组件中为什么不能配置多个外部数据源、数据字典等等,我通过表单中字段
> 来判断我该组件中该用什么数据源?」** 这一篇讲四件事:为什么以前一格只能有一个来源、
> 现在这一格按什么顺序决定问谁要候选、命中那一家怎么把它那几列带进别的格子(§5),
> 以及顺手补上的两头——带回来的值不在这格候选里也能收下、配了显示条件之后回看那一屏与必填不再打架。
## 0. 一页看完
| 问题 | 结论 |
| --- | --- |
| 需求 | 同一格候选能配好几套(多张外部数据源 / 多本数据字典 / 手填那几条混着来),**按这张单上某个字段的值决定用哪一套** |
| 以前 | 一格一答:`optionSource` 只能是一个值。要换家只有两条路——摆三格再拿显示条件把另外两格藏起来(三格 = 三个字段名 = 三份导出列 + 三套环节权限),或者去对面求一个聚合接口 |
| 现在 | 字段上多挂一份**有序清单** `field.optionRoutes`:每一条 = 一个触发条件(`when`)+ 一套候选来源配置。自上而下第一条成立的用它;一条都不成立**回落到字段自己那一份**——也就是改动前的行为 |
| 条件用什么写 | 就是联动那一份结构化条件(`{match, rules}`,与 `visibleWhen` 同一口径、同一个 `conditionOk`),设计器里拼得出来,前端算得出来,提交时后端再算一遍 |
| 上限 | 一格最多 8 条(`MAX_OPTION_ROUTES`,两边同一个数)。再多就不是「换一家」而是该做聚合接口了,而且清单越长越没人说得清哪一条会赢 |
| 脏条目 | **当没配**:认不出的来源、配到一半的空条目、第 9 条起多出来的都丢掉。宁可回落,也不要让填单的人对着一只永远为空的挑选器 |
| 外部取数那一头 | 同一分寸:`fetch.sources[].when`(单源老写法也能挂)。设计期检查看**全量**清单,运行时只跑**成立的那几条**;一条都不成立=这一格这回不取数,不是失败,值留在原来那一份上 |
| 那一家的带出往哪儿写 | 外部数据源那一条自带一份 `fill`(源 / 入参 / 带出去向),运行时摊成一条取数条目跑同一个执行器,只多一个 `fillOnly`:只写带出去向,不盖这一格刚挑中的那一个值;没自带照旧回落字段那份 `fetch`。字典那一条走 `autoFill`,读的是**命中那一本**的附加值,命中不是字典那一条时一个字都不带(见 §5) |
| 带回来的值不在候选里 | 新增字段级开关 `field.allowOutsideValue`(默认关=老行为)。勾上之后:页面不清值、提交不判越界、界面上给那一行补一条「带出」候选让它站得住 |
| 回看那一屏 | 改成「按存过的那份值评条件」:条件成立摊开;**条件不成立且这一格空着**收掉;有值一律摊开。「提交流程之后所有字段都显示了」收掉的正是空着、又不适用这一单的那一行 |
| 必填不再死锁 | 因**显示条件不成立**被收走的系统带出格(`auto` / `formula` 勾了必填)不再算必填;勾了「默认隐藏」又没配条件的照旧仍然要有值 |
| 老表单 | 一个字节都不用改:没挂清单的格子走的还是原来那一条路,`allowOutsideValue` 默认关 |
| 新接口 | 没有。候选还是走现成的 `POST /process/dicts/values` / `GET /data-source/options` / `GET /work/related`,只是**问哪一家**由这一单的取值决定 |
| 真收过的一张单 | 生产上「出差备案申请」27 格里 16 格是四家同构字段,收成 4 格,逐家比对过,见 §12 |
| 唯一口径在哪 | 前端 `src/utils/optionSource.ts`(`optionRoutesOf` / `matchedOptionRoute` / `optionFieldView` / `optionRouteProblems`)+ `src/utils/formFetch.ts`(`activeFetchEntries`);后端 `backend/app/service/dicts.py`(`routes_of` / `matched_route` / `option_view` / `route_problems`)+ `backend/app/service/binding.py`(`entry_active` / `active_entries`)|
| 验收 | `PYTHONPATH=. python3 scripts/check_option_routes.py`(不碰库)+ 前端那五份 spec,见 §11 |
## 1. 为什么以前一格只能配一个来源
不是漏了一颗复选框,是那套设计的**前提**就是一格一答。三件事叠在一起:
1. **「候选从哪儿来」被做成一维一答。** `optionSource` 是一个枚举,
`effective_options(field, data, cache)` 的签名里没有「此刻」这一维——它只读字段上那一份配置,
算出「这一格能点什么」。要支持多套,就得先回答「同一时刻这一格按哪一套说话」。
2. **「存的是哪一列」跟着来源走。** `optionMap` 的合法列名按来源给(字典给 `value` / `extra.*`,
流程单据给 `job` / `serial` / `title`),判越界、字典带出、标题与导出翻译、条件分支的候选值全都
读**同一份** `stored_of` / `shown_of`。一格两答,「这一格存的是编码还是物料号」当场没有定义。
3. **越界与失效值只有一条判据。** `constrains_values` 决定「值必须在候选里」还是「对面说了算」:
手填 / 字典判越界,流程单据与外部数据源不判。两个来源同时在场,这句话就一会儿真一会儿假。
于是历史上换一家只有两条路,代价都实测过:
- **摆三格 + 显示条件**:三个字段名 → 三份导出列、三套环节权限、三处必填与阈值,
办结之后「报销科目」这个概念在数据里裂成三列,报表要 UNION 回来;
- **对面做一个聚合接口**:OA 这边一个字不用改,但排期在对面,而且聚合接口只有一套候选列,
「这一家想按物料编码存、那一家想按主键存」配不出来。
这一层给的是第三条路:**顺序 + 回落**。同一时刻仍然只有一套候选在场,上面那三条前提一条都不破。
## 2. 语义:有序清单,第一条成立的说话,全不成立回落
```jsonc
{
"key": "expenseItem",
"type": "select",
"optionSource": "dict",
"dictCode": "acct_common",
"optionRoutes": [
{ "source": "dict", "when": { "rules": [{ "field": "expenseType", "op": "eq", "value": "travel" }] },
"dictCode": "acct_travel" },
{ "source": "dataSource", "when": { "rules": [{ "field": "expenseType", "op": "eq", "value": "meet" }] },
"dataSourceCode": "erp_meet", "dataSourceArgs": { "dept": "{form:dept}" },
"optionMap": { "valueKey": "extra.code", "labelKey": "label" },
"note": "招待这一头问 ERP 要费用科目" }
]
}
```
四条规矩,两边一字不差:
- **有序**:自上而下第一条 `when` 成立的用它。`when` 缺省=恒成立,所以它天生是「其余情况」
那一档——放最前会压死后面所有条,设计器把这一条的按钮下面直接写成
「无条件(其余情况都用这一条,请放最后)」。
- **回落**:一条都不成立就用字段自己那一份(`optionSource` / `dictCode` / `options` / …)。
回落这一句是整个特性的地基:老表单没挂清单,走的正是这条路。
- **只动来源那一维**:命中之后摊出来的是**一张视图**(`option_view` / `optionFieldView`),
只换 `optionSource` 与那一种来源自己那几格(外带那一条的 `optionMap`)。挑选方式(`pickerStyle`)、
能不能选好几个(`multiple`)、关联带出(`linkFill`)、额度、阈值、显示条件这些与来源无关的格子
原样留着——「这一格怎么用人」和「候选从哪儿来」仍然是两件事。
- **脏条目当没配**:`routes_of` 只留这一类型挑得了的来源、只留属于它那一种的那几格;
非数组、空条目、第 9 条起一律丢。丢完没剩就把 `optionRoutes` 这个键整个抹掉,
别留一份空清单让下一任以为配过什么。
**这一层不新增任何一条候选口径**。它只把「字段」换成「此刻那一份视图」,再喂给
`source_kind_of` / `effective_options` / `stored_of` / `constrains_values` 这些既有函数——
「命中哪一条」算错的可能性只有一处,不会多出一套「路由自己的候选算法」。
## 3. 两条链路必须算出同一个结果
界面按 A 家的候选渲染、提交按 B 家判越界,是这一整套最容易犯的错,所以每一处都改成先取视图:
| 这一格此刻要问谁 | 前端 | 后端 |
| --- | --- | --- |
| 渲染哪一只控件、候选清单 | `FormRenderer.routedField()` → `optionsOf` → `effectiveOptions` | `dicts.effective_options(field, data, cache)` |
| 级联上级筛候选 | `formLinkage.effectiveOptions` | 同上(`cascadeFrom` 也来自那一条) |
| 判越界(提交那一刻) | `formLinkage.dropStaleSelections` | `formruntime.selection_problems` → `_has_option_rule(field, data)` |
| 要不要把关(手填/字典 vs 搜出来的) | `optionSource.constrainsValues(field, data)` | `dicts.constrains_values(field, data)` |
| 字典带出取哪一本的附加值 | `formLinkage.applyAutoFill`(逐字段先摊视图) | `dicts.apply_auto_fill`(逐字段先取视图) |
| 只读、标题、导出翻名字 | 候选清单自己念 | `dicts.option_labels(field, value, cache, sep, data)` |
| 手机「完整单据」那一屏(关联单据念标题) | `MobileFormReader.routedField()` | —— |
| 上游变了要重算哪几格 | `formLinkage.conditionDependencies`(含路由 `when` 与路由 `cascadeFrom`) | `dicts.condition_dependencies` |
| 一趟预取哪几本字典 | `FormRenderer.dictCodes()` | `dicts.codes_of` / `_field_dict_codes` |
| 删字典前「哪些表单在用」 | —— | `dicts.used_by_forms`(只挂在路由里的字典也算在用) |
| 删数据源前「哪些表单在用」 | —— | `fetch.used_by_forms`(扫路由里的 `dataSourceCode`) |
| 设计期逐条体检 | `optionSource.optionSourceProblems`(含 `ctx.rows` 判源健康) | `formruntime.option_source_problems` → 逐条 `_source_config_problems(route_view(...))` |
设计器保存那一刻还有一步清洗(`api/design.py:clean_option_source`):每条只留属于它那一种来源的
那几格、`relationStatuses` 全勾不留、认不出的 `optionMap` 列退回默认、备注留着(只给配表单的人看),
一条有效都不剩就把整个键抹掉。主表字段与明细列走同一句。
翻名字那三条路(只读渲染、单据标题、导出)以前只吃字段自己那一份配置,现在统一带上这一单的值:
`exportfmt.cell_text(..., data=)`、`titles._field_text(..., data=)`、`api/export.py`、
`detail_export.py` 四处调用都传了 `data`;明细表里那一列按**同一行**里别的列命中,与桌面
`routedField(column, row)` 同一个口径。`check_option_routes.py` 第 10 段把这四处的 `data=`
钉在源码里——谁把它摘掉,那一段当场变红。
## 4. 外部取数那一头:条目上的「什么时候调这一条」
同一句话在「取一个值」那一头也缺:`fetch.sources` 那份多源清单是**每一次都全跑**,
「费用类型 = 差旅才问差标接口」配不出来,只能为每种组合各建一条源。补的是同一个形状:
```jsonc
{ "fetch": { "sources": [
{ "source": "travel_api", "when": { "rules": [{ "field": "expenseType", "op": "eq", "value": "travel" }] } },
{ "source": "erp_balance" }
] } }
```
两头分工,这一寸不能含糊:
- **设计期检查看全量**(`binding.entries`):那张源还在不在、入参引用掉没掉在地上、
条件点名的字段还在不在——都跟此刻的取值无关;
- **运行时只跑成立的**(`binding.active_entries` ↔ `formFetch.activeFetchEntries`):
条件判定用的就是联动那一份 `conditionOk` / `condition_ok`,不会界面上调了、提交时后端没调。
**空命中的语义是「这一格这回不取数」**,不是失败:一条都不成立时不走「取不到怎么兜」那一档、
留痕里不记失败、值留在原来那一份上。这与「配了源但源停了」是两件事——后者该拦人、该记失败。
## 5. 带出挂在「那一条候选」上(`optionRoutes[].fill`)
用户的第二句追问:**「一个组件中为什么不能配置多个外部数据源、数据字典等等,我配置了多个
该如何设置带出的值填入对应的字段呢?」** 换一家的意思从来不只是换一份候选清单,而是
**换一整套答案**——挑的是 ERP 那家供应商,开户行和信用额度就得回 ERP 查。
§4 那条路(`fetch.sources[].when`)配得出这个结果,但要抄两遍:候选那一格写「费用类型 = 差旅
问 ERP」,取数那一条再写一遍「费用类型 = 差旅问 ERP 开户行」。两处判据一旦漂开,症状是最难查
的那种——**候选换了家、带出还是上一家的**:界面上一切正常,带回来的值来自另一套主数据。
所以这一层把带出挂到**那一条路由自己身上**:
```jsonc
{ "optionSource": "dataSource", "dataSourceCode": "crm_vendors",
"optionRoutes": [{
"source": "dataSource", "when": { "rules": [{ "field": "expenseType", "op": "eq", "value": "travel" }] },
"dataSourceCode": "erp_vendors", "dataSourceArgs": { "dept": "{form.dept}" },
// 这一家自己的带出:问哪一家 / 带什么入参 / 哪几个键写进哪几格
"fill": { "source": "erp_bank", "args": { "code": "{form.vendor}" },
"picks": { "bank": "bankName", "limit": "creditLimit" } }
}] }
```
运行时它被**摊成一条普通的取数条目**丢给同一个执行器(同一个入参写法、同一份留痕、同一条
「带出去向那一格还在不在」的闸),只多记一个 `fillOnly` 记号。对面是前端
`utils/formFetch.fetchConfigOf` ↔ 后端 `service/fetch.config_of`,两边必须算出同一份,
否则就成了「界面上按 A 家带出、提交时按 B 家覆盖」。口径逐条:
- **只写带出去向**:`fillOnly` 那一份**不往这一格写值**——这一格那一个值是人在候选里挑的,
取回来的数盖不得;`picks` 里指着自己那一行的老配置也不写(`fetch._run_entries(own_key=)` ↔
`formFetch.fetchPickWrites(hits, live, selfKey)`),设计期还会单独说一句「不能把值带进自己」;
- **命中那条自带就只跑它那一份**:字段上那份 `fetch` 这一回不再跑,同一格不被盖两次;
- **回落不破**:一条都不成立、或命中的那条没自带带出,读的就是字段上那份 `fetch`
(= 改动前行为,老表单一个字节不改);
- **源默认跟着这一条**:`fill.source` 留空 = 就问这一条候选那一家;另填一家才另问
(「候选问 A 家的清单、那几列在 B 家」是真有的配法,不值得为它再摆一条候选路由);
- **入参默认跟着这一条**:`fill.args` 留空 = 沿用这一条筛候选那一份 `dataSourceArgs`。
为什么还要单独一栏:候选的入参**不许**引用这一格自己(拿这一格筛这一格是个死圈),
而带出恰恰常常要 `{form.这一格}`——「按刚选中的这一行去问另外几列」;
- **失败策略 / 发起后冻结 / 多久算旧 / 分隔符**四档一律沿用字段那份 `fetch`:
它们问的是「这一格怎么待人」,跟从哪家取数无关;合并方式(`merge`)不参与,
这一份本来就不往这一格写值;
- **留痕照记**:记在这一格名下(`data._fetch.<字段名>`),形状与非路由带出一模一样,
事后看得出这一笔是哪家答的、有没有部分失败;
- **设计期逐条体检**:门牌写「第 N 条候选来源的带出」,走的是外部取数那同一套判据
(`binding.entry_problems`)——源在不在、是不是取值型、带出的键在不在源声明的可带出键里、
入参引用掉没掉在地上、带出去向那一格还在不在,另加一句「不能把值带进自己」。
**为什么 `linkFill` / `autoFill` 不跟着挂一层**:字典带出读的就是**此刻命中那一条**的字典,
关联单据带出读的是实际挂上的那张单——那两条本来就跟着各自的对象走,再各配一份 `fill`
只会让人以为有两处要配。
### 5.1 字典躺在路由里时,那一头的带出走 `autoFill`
「一家外部数据源 + 一家数据字典」是生产上最常见的一对,而字典那一头的带出以前**配不出来**:
「联动」面板里那一栏 `v-if="field.dictCode"`,只认字段上那本字典,字典只挂在路由里时整栏不出现;
就算从接口直传写了 `autoFill`,保存那一刻还会被当上一家的残骸清掉(`clean_option_source` 只认
字段自己声明的那一种来源);界面带出读的也是字段上那本 `dictCode`。三处叠在一起的症状是
**界面带 A 本的附加值、提交带 B 本的**,以及「怎么配都带不出来」。
四处一起改,口径只有三条:
- **带出跟着命中的那一条**:`formLinkage.applyAutoFill` 与 `dicts.apply_auto_fill` 都先摊视图再读
`dictCode`,命中哪一本就带那一本的附加值;**命中的那一条不是字典**(外部数据源那一家)时
一个字都不带——那一条要往别的格子上写东西走它自己的 `fill`。少了这道闸,「没有字典就把这一格
自己的值搬过去」那一条兜底会把人刚挑中的编码盖到「名称」那一格上(对面前端 items 为空,本来
也什么都不写);
- **不再当残骸**:字段自己声明的不是字典、但候选路由里挂着字典(`dicts.dict_route_codes` ↔
`optionSource.dictRouteCodesOf`)时,`autoFill` 是那一档唯一的配法,保存那一刻留着它;
两处都没字典才洗掉,并且设计期说一句「配了字典带出,可这一格没挂数据字典(字段上与候选来源
那几条里都没有),这一档不起作用」——不让人以为勾上就万事大吉;
- **那一栏跟着这几本字典出现**:`LinkagePanel` 用的是「字段上那本 + 路由里那几本」的并集,
「能带哪些列」也把这几本的附加值列一起列出来(命中哪本取哪本,但一栏里得看全)。
附加值列名两本不一样时不用改配置:带出去向写「取哪一列」,命中的那一本没有那一列就**不写**,
不会因为换了家就凭空冒出一个值。
## 6. 带回来的值不在候选里也收下(`allowOutsideValue`)
下拉框的候选以前是硬边界:值不在清单里,页面 `dropStaleSelections` 把它清成空、
提交 `selection_problems` 判「取值已不在可选范围内」。可这一格的答案常常本来就是**系统写的**:
外部取数(`fetch`)、关联单据带出(`linkFill`)、字典带出(`autoFill`)三种带出都排在提交校验之前。
拿本地清单去判对面给的那个值并不讲理,而症状最难看:「明明带回来了,格子却是空的」。
给一颗字段级开关,勾上之后:
1. 页面不清这一格的值(`dropStaleSelections` 跳过它);
2. 提交不判越界(`selection_problems` 跳过它);
3. 界面上给那个值补一行候选,标成「带出」——不补就是一行空白,人不知道值还在。
这一行只用于显示,人选它和不改它存的是同一个值,不新增任何能选的东西。
三句设计期的话(两边同一句措辞):
- 值由带出写入、候选又来自手填 / 字典且**没勾**这一档 → 说交叉规则,一次给三条解法:
把带回来的值补进清单、把候选来源改成外部数据源 / 流程单据,**或勾上这一档**;
- 勾了这一档却**什么都没带出** → 说「这一档暂时不起作用」,别让人以为勾上就万事大吉;
- 这一档只认真布尔值,且只属于有候选来源的那几类字段(`clean_option_source` 收残骸)。
那两句共同依赖一句判据:**这一格的值是不是系统写进来的**(`formruntime.filled_by_label` ↔
`optionSource.filledByLabel`)。它判的是**有没有一条带出的落点在这一格上**,不是「这一格有没有配
带出」——`autoFill` 与 `linkFill` 都配在发起那一格身上、写进的是别的格子,光看有没有配会把人挑的
那一格说成是系统写的(生产上「项目名称」配了字典带出,反被提醒「这一格的值由字典带出写入」);
`fetch` 同理,只有条目自带的 `pick`(取一个值写进这一格)或 `picks` 点到这一格才算,候选路由那一条
自带的 `fill` 是 `fillOnly`、永远不写自己。落点也可能在**隔壁那一格**身上:给了同表字段清单
(`rows` / `ctx.peers`)时,别的字段的 `autoFill[].to`、`linkFill.rules[].to`、取数 `picks` 与路由
`fill` 指着这一格,一样算「这一格由系统写」——否则一张靠隔壁带出喂值的下拉会被说成「这一档暂时不
起作用」,人把勾去掉,提交那一刻又被判越界,两头各骗一次。明细列那种 `表.列` 的写法不算指着主表
这一格。
**默认关**。它只影响「带回来的值」,不放开给人乱填:这一格由人输入时,控件仍然只能从候选里挑。
## 7. 顺手修的两头:回看那一屏与必填
同一批反馈里的第三条:「配了显示条件,提交流程之后回看页所有字段都显示;改成默认隐藏 + 显示条件,
表单校验又过不去。」两句是同一处判据的两端。
- **回看那一屏**(`formRuntime.readbackHidden`,只读渲染:单据详情 / 打印 / 手机完整单据):
环节明写 hidden → 收;环节给了其它权限 → 摊(那一环特意要看见它);勾了「默认隐藏」→
按存过的那份值评条件;**没勾默认隐藏但配了显示条件、按存过值评不成立、且这一格为空** → 收。
有值一律摊开——条件翻走了不代表那一笔没填过,收起来才是让存过的东西凭空消失。
- **必填不再死锁**(`formruntime.hidden_by_condition` ↔ `formRuntime.hiddenByCondition`):
`auto` / `formula` 这两类没有录入框、权限永远算只读,字段自己勾了必填说的是「必须算得出值」。
老判据连**因显示条件不成立**被收走的格子一起催「还没填写」——屏幕上没有那一格,提交永远过不去。
现在这一格不算这一笔;勾了「默认隐藏」又没配条件的(单据编号、金额大写)照旧仍然要有值。
保留的那一寸要说明白:**有值但条件已翻走的格子,回看页仍然摊开**。这是刻意的(少一行比多一行
难发现,而那一笔值确实存过)。真要按存过值全收干净,得再给一颗字段级开关,别默认改。
## 8. 在设计器里长在哪儿
配的人只需要记三件事,其余都是替他把字写进去:
1. **「按哪一格换一家」**:那一栏下面挑一个字段点「一家一档」,它有 N 个取值就铺出 N 条卡片,
触发条件(`when`)当场替写好,备注也替写成那一档的人话;
2. **每家问谁**:卡片里逐条挑各家的字典 / 数据源——这是唯一只有配的人才知道的信息;
3. **带出去哪儿**:外部数据源那几家,在第一家的卡片里配好「这一家的带出」,点
「把这一家的带出套给其余几家」(各家问的还是各家那一家);字典那几家,点卡片上那颗
「这一家的带出去『字典带出』里配」,门替他打开、那一块描一圈,带出只配一份。
生产上「出差备案申请」那四家(PMS / VDI 已经是字典,行政 / 定制 现在靠取数写名称)收拢成
一格时按这三步走,不必再摆八格拿显示条件轮流露面。**最省事的走法是把那四家都变成字典**:
行政 / 定制 那两张列表型数据源各存成一本「从数据源同步」的字典(`DictType.source = data_source`,
见 [dict 那一头的说明](option-source-design.md)),四家就都是卡片里的一条 `dict`,带出只配一份
「字典带出」,`fetch.sources[].when` 与 `allowOutsideValue` 都不用上。留着取数那一头也行
(就是 §4 那份条目条件),只是配的地方从一处变两处。
- 属性侧栏「候选来源」那一栏下面多一栏「同一格换一家候选」
(`components/oa/design/OptionRoutesEditor.vue`):一条一张卡片,左边那颗按钮是触发条件
(点开的弹窗与「满足条件才显示」是同一只 `LinkageConditionDialog`,能引用同表其它字段与本字段),
右边是上移 / 下移 / 删除;卡片里挑来源,来源下面就地配它自己的那几格(手填的选项 / 哪本字典带级联 /
哪个流程带状态档 / 哪张列表型数据源带入参),再加一条「显示为 / 存为」和一句备注。
「再加一家候选」的起点跟着上面那套固定来源走,配的人少挑一次;配满 8 条时那句提示替掉那颗按钮。
- 那一张卡片挑的是外部数据源时,下面再多出一栏「这一家的带出」(同一只 `SourceBindingEditor`,
带「带出去向」那一头):默认就问上面那一家、默认沿用上面筛候选那一份入参,都能就地改;
能挑的源只有取值型那几家,能写进去的格子里没有这一格自己。三张表都空 = 这一条只给候选,
写回时整块不留(`pickFill` 还顺手做两处去重:与上面同一家不存 `source`、入参与上面一模一样不存 `args`)。
- 同一栏底部一颗复选框「带出的值不在候选里也收下」(`allowOutsideValue`)。
- 「联动」面板里的「字典带出」那一栏不再只认字段上那本字典:候选路由里挂着字典的格子也出现,
可选的附加值列是那几本的并集(`LinkagePanel.vue`,见 §5.1)。
- 「外部取数」面板里每一条源多一个按钮「什么时候调这一条」,配完在那一行摘要成人话,
旁边一颗 × 一句话摘掉(`components/oa/design/FetchPanel.vue`)。
- 「**并成一格**」管的是来路那一头:多选上那几格「同一个字段的几家」(每一格都只挂一条
「某字段等于某一个值」的显示条件、指的是同一个字段、取值互不重复),属性栏就多出一颗按钮,
一次把那 16 格收成 4 格(`utils/formMerge.ts` 写配置,`FormDesignerView.vue:mergeSelection`
只动画布)。判据一条没新增,存的还是 `optionRoutes[].when` / `fetch.sources[].when` /
`autoFill` / `fetch.picks` 那几份本来就要存的东西。三条分寸写死在代码里:
**留哪一格**——内容最多的那一格(有字典的优先,只读取数格垫底),名字与标题都用它的,
因为导出列、报表、对外回写读的都是字段名,留一个比换一个新名字少坏一片;想换个中性名字,
并完再在属性面板改字段名,`utils/formRename` 会把指着它的带出一起搬走。
**先搬落点再删格子**——`fetch.picks` 与 `autoFill[].to` 记的都是别的格子的名字,
趁那几格还在表上搬才不会漏,漏一处就是「候选换了家、带出还写着上一个名字」;搬完顺手
去掉因此重复的那条带出,删完格子再走一遍 `formPrune` 清掉没有归宿的。
**带回来的值要收得下**——往别的格子写值的那几处落点也改了名字,那些格子自己有候选时,
当场替它们勾上「带出的值不在候选里也收下」,否则要等保存那一刻才被门牌拦住。
点完弹一句实话:清单里几家、取数条目几条、跟着搬的带出几处、删掉几格,外加「哪几家的
必填 / 只读跟着留下来的那一格变了」——并格躲不掉的就是这一句,不满意用工具栏那颗撤销。
- 「一家一档」与「套给其余几家」是**写配置的便利**,不是新的一层判据:它们写出来的就是
`optionRoutes[].when` 与 `optionRoutes[].fill` 那几份本来就要存的东西,运行时一个字没改
(`OptionRoutesEditor.vue` 的 `splitByField` / `copyFill`,与手工改走同一句 `fillForRoute`,
两边不会写歪成两份)。一家一档只认「当下数得出取值」的那几格(手填那几条、或一本数据字典),
取值比 8 家还多的那一格直接说「该在对面做一个聚合接口」,不硬铺。
- 卡片上那颗跳转把「字典那一家的带出在另一栏里配」这一寸藏处消掉:
`OptionRoutesEditor` → `OptionSourcePanel` → `FieldInspector`(开「联动」那扇门 + 计数)
→ `LinkagePanel`(描一圈那块,`revealAutoFill`)。
- 「挂了这一份清单」= 这一格有候选来源:保存那道「选项类字段未配置任何选项」的闸两边都改口
(`api/design.py` 的 `form_problems` ↔ `utils/formLayout.ts` 的 `validateFields`)。收拢出来的
那一格常常**故意**把自己那一份留空——「先选项目分类,再问那一家要候选」,分类没选的那一刻
本来就没得挑;什么都没配的照旧要拦,老规矩没被一起放宽。
- 设计期检查一栏都不少:清单本身、那一条的来源配没配到底、那一张源停没停用、
候选入参引用掉没掉在地上,报错门牌写成「第 N 条候选来源:……」,不与字段自己那一份串门牌。
## 9. 老表单与迁移
一个字节都不用动:
- 没挂清单 → `routes_of` 回空,`option_view` 原样返回字段本身;
- 没写 `allowOutsideValue` → 关,越界与清值行为与今天一字不差;
- 外部取数条目上没有 `when` → 恒成立,`active_entries` 与 `entries` 给同一份清单;
- 那一条候选没写 `fill` → 这一格带的还是字段上那份 `fetch`,与挂路由之前一字不差;
- 清洗只在保存那一刻做,且不替历史做主:只动明写过这些键的字段。
## 10. 已知边界
- **路由不参与「这一格能不能配这个来源」的收窄**:`sourceKindsOf` 那一份清单是唯一口径,
这一类型挑不了的那一条直接当没配(不是报错到保存不下来),设计期那一句只说一次;
- **级联上级只属于字典那一条**:换到别的来源时上一家的 `cascadeFrom` 不进视图,
路由里那一条自己带的那一份才算;
- **字典带出(`autoFill`)仍然是字段级的**:读法跟着**命中那一条**的字典走(§5.1),但配的地方
只有一处。两本字典的附加值列名不一样时,用那一条自己的 `optionMap`,或把带出配在值域较宽的那一头
上——命中那一本没有那一列就不写;
- **带出只有「外部数据源」那一条说得上**:字典那一家走 `autoFill`、流程单据那一家走 `linkFill`,
两条都读此刻命中的那一个对象;换来源时这份 `fill` 当残骸清掉(`optionRoutePatch` ↔ `clean_routes`);
- **失败策略与冻结那四档没有「按条」一说**:它们问的是这一格怎么待人,永远沿用字段那份 `fetch`。
真要「差旅那家取不到就挡提交、其余放过」,那种需求该在对面把两家合成一个接口;
- **带出不参与这一格自己的值**:`fillOnly` 那份不写这一格,`merge` 因此也无从谈起;
想让取回来的值就落在这一格上(人不挑、系统直接写),那是字段级 `fetch` 的活,别挂到路由上;
- **8 条封顶**:超过就是「换一家」变成了「做聚合」,那种需求该在对面做一个接口;
- **手填且不带条件的候选本来就不判越界**(后端 `_has_option_rule` 只认会随别的字段变的那三类候选),
所以 `allowOutsideValue` 真正救的是字典那一头——页面清值那一步两边都管。
## 11. 验收清单
后端(不碰库,`cd backend && PYTHONPATH=.`):
```bash
python3 scripts/check_option_routes.py # 命中与回落、视图、清洗、把关与带出、上游、必填、条目条件、前后端常量与措辞
python3 scripts/check_option_route_fill.py # 那一家的带出:合成、只写带出去向、回落、失败策略、设计期、清洗、前后端对齐
python3 scripts/check_binding.py # 取数内核与候选来源那一份,含交叉规则那一句
python3 scripts/check_self_visible.py # 显示条件那一份判据
python3 scripts/check_hidden_field_rules.py
```
前端(`cd frontend`):
```bash
npx vitest run src/utils/optionSource.routes.spec.ts src/utils/formFetch.when.spec.ts src/components/oa/FormRenderer.optionRoutes.spec.ts src/components/oa/design/OptionRoutesEditor.spec.ts src/components/oa/design/FetchPanel.when.spec.ts
# §5 那一份
npx vitest run src/utils/optionSource.fill.spec.ts src/utils/formFetch.routeFill.spec.ts src/components/oa/design/OptionRoutesEditor.fill.spec.ts
# §5.1 那一份(字典躺在路由里时的带出)
npx vitest run src/utils/formLinkage.fill.spec.ts src/utils/optionSource.routes.spec.ts src/components/oa/design/LinkagePanel.routedFill.spec.ts
# §12 那一份(挂了清单就不必再自己抄一份选项;多选那几格并成一格)
npx vitest run src/utils/formLayout.routed-options.spec.ts src/utils/formMerge.spec.ts src/components/oa/design/FieldInspector.merge.spec.ts
```
## 12. 一张真实表单:出差备案申请 16 格收成 4 格
生产上那张「出差备案申请」(`FormElement 927e88ea…`,27 格)是这一层功能存在的理由本身。
四种项目分类各摆一行同构字段,配的是同一件事:
| 干的那件事 | PMS | VDI | 行政 | 定制 |
| --- | --- | --- | --- | --- |
| 项目名称 | `project_pms`(字典 `pms_project`) | `project_scc`(字典 `SCC_Project`) | `project_xz`(只读取数 `xz_code`) | `project_dz`(只读取数 `Code_dz`) |
| 项目编码 | `project_code_pms` | `project_code_SCC` | `project_code_xz` | `project_code_dz` |
| 最终客户名称 | `customer_name_pms` | `customer_scc` | `customer_xz` | `customer_dz` |
| 项目阶段 | `project_stage_pms`(字典 `project_stage`) | `project_stage_scc` | `project_stage_xz` | `project_stage_dz` |
16 格各自挂一条「`project_type` 等于哪一个分类」的显示条件互相藏起来,代价是三个字段名家族、
三份导出列、四套环节权限——`开始` 那一环的 `formPerms` 里已经堆了 11 条指向早就不存在的字段名
(`project_dms`、`project_jd_*`、`customer_name_dms`……)。
收拢后是 4 格,`project_type` 决定问哪一家:
```jsonc
// 项目名称(select,必填)——分类挑哪一家,就换成那一家的候选
"optionRoutes": [
{ "when": { "...": "project_type == PMS" }, "source": "dict", "dictCode": "pms_project", "optionMap": {"labelKey": "label", "valueKey": "label"} },
{ "when": { "...": "project_type == VDI" }, "source": "dict", "dictCode": "SCC_Project", "optionMap": {"labelKey": "label", "valueKey": "label"} }
],
// 行政 / 定制那两家问的是「取一个值」那种源,列不出候选 → 条目条件,落点都写收拢后那一个名字
"fetch": { "sources": [
{ "when": { "...": "project_type == XZZH" }, "source": "xz_code", "pick": "project", "picks": { "code": "project_code" } },
{ "when": { "...": "project_type == DZKFXM" }, "source": "Code_dz", "pick": "project", "picks": { "code": "project_code" } }
]},
// 字典那两家的带出仍旧只有一份:命中的那一本有那一列才写,没有就一个字都不动
"autoFill": [
{ "pick": "value", "to": "project_code" },
{ "pick": "extra.customerName", "to": "customer_name" },
{ "pick": "extra.stageName", "to": "project_stage" }
],
"allowOutsideValue": true // 行政 / 定制带回来的名称不在这格的候选里,得收得下
```
设计器里有两条路走到这一张单:手动照 §8 那三步配(一家一档 → 逐条挑各家 → 带出只配一份),
或者框选同构的那四格点「**并成一格**」(§8 倒数第二条,一次把条件、来源、带出与落点都搬好);
`backend/scripts/collapse_trip_form.py` 把这张单**照表上真实的字段**算了一遍并逐家比对,
默认一个字都不改:
```bash
cd backend
OA_ENV=prod PYTHONPATH=. python3 scripts/collapse_trip_form.py --json /tmp/new.json # 看对照与校验
OA_ENV=prod PYTHONPATH=. python3 scripts/collapse_trip_form.py --write --perms # 确认过再落库
```
它会打印四家各自的「收拢前 / 收拢后」对照(问哪一家、候选几条、带出写哪几格、写进来的值),
走的是运行时那同一套判据(`option_view` / `effective_options` / `apply_auto_fill` /
`fetch.apply_form`),落库前再按设计器保存那一条路检一遍。生产库上跑的结果:
PMS 247 条、VDI 2473 条候选一字不差,`project_code` 带回来的值两边同一个,
行政 / 定制 两家两边都不落值——比对四家全「一致」。
**收拢躲不掉的几件事**,脚本都会当场说出来,别等填单的人发现:
1. **必填与只读只剩一份**:跟着当基准的那一家走。这张单上「最终客户名称」原来只有 PMS 必填,
收拢后四家都必填;「项目名称」原来行政 / 定制是只读取数格,收拢后跟着 PMS 变成可挑的候选格。
2. **环节权限要重挂**:那 16 条挂在消失了的字段名上,`--perms` 会把它们折到 4 格上
(认得出旧名字的搬走,认不出的报出来),其余环节没列上的格子按字段自己的配置走。
3. **导出列、报表、对外回写读的都是字段名**:16 个名字变 4 个,那几头得一起对一遍。
在途的老单不受影响——发起那一刻设计就冻在 `oa_process_snapshot` 里了。
4. **换一家不会把上一家带出来的值擦掉**:`apply_auto_fill` 只在挑中那一刻写,
命中的那一本没有那一列就一个字都不动。所以 VDI 换成 PMS 之后,客户与阶段还留着 VDI 那份。
最干净的解法还是 §8 那句:把那几家都变成**从数据源同步的字典**、各家都带上那几列附加值,
这样每一家都把这三格重写一遍,谁都不留残值。
5. **顺手发现的一个真问题**:`xz_code` / `Code_dz` 那两条 SQL 比的是 `:project_type = '行政综合X项目'`
(字典的**名称**),而表单存的是**编码** `XZZH` / `DZKFXM`,所以这两家的名称与编码在生产上一直是空的;
今天这张单和收拢后一样空,收拢本身没有让它变坏。要么把 SQL 改成比编码,要么回到第 4 点那本字典。

View File

@ -847,6 +847,7 @@ ORM 那条 Core `update()` 也不带 Python 侧默认值,改之前改之后都
| 写路径(引擎、办结迁移、抄送) | `python3 -m advance_cash --run`(自己建单、自己删单) |
| 批量处理 / 挂起恢复 / 待阅处理 / 评论 / 标题预览 `app/api/runtime.py` | `python3 scripts/check_action_surface.py` |
| 环节抄送建待阅 `engine.apply_activity_cc` / `create_reads` 的 `held` | `python3 scripts/check_cc_reads.py` |
| 待阅处理带附件 / 归档件补批注 `engine.mark_read` 的 `attachments`、`claim_attachments` 认归档单、`_job_response` 的 `can_comment` | `python3 scripts/check_cc_action_files.py` |
| 引擎里 `db.flush` 的作用范围 `_log` / `notify` / `_arrive_manual` | `python3 scripts/check_flush_defer.py` |
| 跨进程租约 `app/service/leader.py` / 准备开 `OA_WORKERS` | `python3 scripts/check_leader_lease.py` |
| 写回什么时候真的发出去 `service/outbox.py`(`wake` / `_mark_wake` / `run_due` / `refresh_pending`)与 `main.py` 调度线程的睡眠 | `python3 scripts/check_outbox_wake.py` |

View File

@ -69,6 +69,15 @@
留着任何一样,改道后的单据都可能带着上一条路的残余状态走。
- **目标环节解析不到处理人就整笔回滚**。宁可让管理员回去把这一环的审批人配好再来一次,
也不能留下一张「停在环上却谁都没有」的单子——那比原地不动危险得多。
- **还挂着在跑的嵌入子流程时先停手**(2026-11 补)。父单停在调用环节时自己没有待办,待办全在
子单上,而改道清空 token 会把等子单回来那张票一起清掉——子单从此没人认领,办完也回不去。
默认拒并说清是哪张子单、卡在谁手上,勾了「一并终止」才 ``cascade_children`` 动手。
改道之后旧环节还剩什么、已经推出去的消息各自什么下场,是另一篇:
[`intervention-todo-and-message-settlement-design.md`](./intervention-todo-and-message-settlement-design.md)
(去向卡、``operator=actor`` 留在已办行上、``rerouted`` 那一档可勾渠道事件,判据
``check_intervention_move.py``)。上面那句「``processing_type`` 记 ``move``」在那一篇里补齐了
读的一侧:前端两张处理方式表认得 ``move``,已办那一列不会再印出裸的原值。
## 4. 修正表单数据:跟办单同一把尺
@ -190,6 +199,10 @@ POST /admin/work/{job}/transfer 整单改派 {identities, opinion}
7. 改数据改到标题那一格:单据、在途待办、待阅三处一起改名,监控列表按新标题搜得到这张单;
规则开了自动重算时,改它引用的字段照样重算一句并写回那一格;``refresh=false`` 时改普通字段
不许替这张单重取名字。这一条有常驻判据:``PYTHONPATH=. python3 scripts/check_intervention_title.py``。
8. 改道留下的残留与已推送消息的下场:旧环节待办一次收干净并进已办(行上写着是谁收的)、
站内信当场收尾、子流程要么拒要么一并终止、停在半路的第三方表态作废、点开旧卡片答得出
这一步的去向。常驻判据:``PYTHONPATH=. python3 scripts/check_intervention_move.py``,
口径见 [`intervention-todo-and-message-settlement-design.md`](./intervention-todo-and-message-settlement-design.md)。
外加仓库里那三条守卫:``check_globals.py``、``check_route_guards.py``、
``check_schema_snapshot.py``(改了 ``models.py`` 记得先 ``dump_schema.py`` 再回归),

View File

@ -0,0 +1,250 @@
# 关联带出:挂上审批单之后,把那几张单里的值写进这一张单的明细表与主表
> 相关:[option-source-design.md](option-source-design.md)(「候选来源 = 流程单据」这一格
> 是怎么来的,`relation` 为什么退化成其中一档)、
> [data-binding-unification-design.md](data-binding-unification-design.md)(取数写法与合并
> 口径共用的是哪一层,为什么路径解析只许有一份)、
> [form-data-integration-design.md](form-data-integration-design.md)(「从另一个流程带数据」
> 那条源——它带的是**这一张单去读那一张单**,这一篇带的是**挂在这一张单上的那几张单**)。
> 这一篇讲一件事:**关联审批单挂上之后,那些单子的数据怎么落到当前表单的格子里**,
> 包括挂好几张的时候该怎么办。
## 0. 一页看完
| 问题 | 结论 |
| --- | --- |
| 需求 | 关联审批流程之后,把那边单据里的值写进**这一张单**的主表字段或明细表;挂多张也要能带 |
| 配在哪 | 就配在「候选来源 = 流程单据」那一格上:字段多一个 `linkFill`,不新增字段类型、不新增一栏开关 |
| 从哪儿进 | 四个入口进的是同一栏(§2.5):设计器顶上「关联带出」总览、画布上那两枚角标、明细表属性里的「带进这张表的关联字段」、那一格自己的属性面板 |
| 从哪取 | `pick`:`work.单号` 这类单据本体,`data.金额` 这类对方表单字段,写法与「从另一个流程带数据」一字不差(同一份 `fetch.pick_path`,含 `[字段=值]` 筛行与 `sum()` 聚合) |
| 写到哪 | `to`:主表字段名,或 `明细表key.列key`。**两类去向行为不一样**,这是整件事的核心 |
| 挂一张 | 两路都一样:那一格 / 那一行取那一张单的值 |
| 挂多张(主表) | 「几个数变成一个」:按配的那一档合(`first` 默认 / `join` 拼接 / `sum` / `min` / `max`),口径就是外部取数那一句 `binding.merge` |
| 挂多张(明细表) | 「一单一行」:按关联顺序补行,取消关联的删行,行上记 `_link` = 那张单的 `job` |
| 两类单要一起挂 | 挂**两个关联字段**(报销单一格、采购单一格),各配各的映射;带进同一张明细表也各带各的行——删行只认「这一行的来源还挂在不在别的格子上」 |
| 人在明细表里改过 | 没配带出的那一列一个字不动;配到带出的那一列按来源盖回去;**关联没变时整趟不动**,人删掉的那一行不会在下一环被复活 |
| 什么时候算 | 每次提交都算(`engine._apply_form_runtime`,排在公式之前),明细那一趟只在**关联那串值变了**时重排 |
| 谁说了算 | 后端。填单页那份即时预览(`POST /work/relation-values` + `utils/linkFill.ts`)只用来显示,前端往那几格里塞什么都白塞 |
| 带出来的格能必填吗 | 能。带出排在必填校验之前,靠它过闸才是正经用法;带不出值时必填真的会把提交挡住 |
| 越界与脏数据 | 挂着的那张单查不到了(未发起就删了 / 单号写歪):不替它编一行,主表那一格跳过它,不报错也不挡人 |
| 谁能配 | 只有**主表**字段。明细列里那一格挂的也可以是单据,但「这一行的那张单 → 另一张表的几行」在界面上没人能预期,那一层要带数据走「从另一个流程带数据」 |
| 老表单 | 一个字都不用改:没有 `linkFill` 就是今天的行为;换了候选来源,那份配置跟着上一家一起被清掉 |
| 新接口 | 一个:`POST /work/relation-values`(只为预览;提交路径上一个都不多) |
| 验收 | `PYTHONPATH=. python3 scripts/check_link_fill.py`(纯函数,不连库,含两格带同一张明细表)、`PYTHONPATH=. python3 scripts/check_link_fill_submit.py`(真提交,连库,31 项)、`npx vitest run src/utils/linkFill.spec.ts src/components/oa/FormRenderer.linkFill.spec.ts src/components/oa/design/LinkFillOverviewPanel.spec.ts src/components/oa/design/LinkFillPanel.reveal.spec.ts src/views/oa/design/FormDesignerView.linkFillEntry.spec.ts` |
| 唯一口径在哪 | 后端 `backend/app/service/linkfill.py`;前端镜像 `frontend/src/utils/linkFill.ts`;设计器那一栏 `components/oa/design/LinkFillPanel.vue`(属性面板与总览弹窗共用它,不存在第二份编辑器) |
## 1. 为什么是「字段上的一层配置」
「挂上关联之后,那些单子里的值落到这一张单的哪里」这件事,直觉上有三种做法,都不对:
- **做成一张新单据(子流程 / 表单模板)**:把对方的字段抄一遍摆在自己表单上。结果是同
一个金额在三处存着,对方的单改了这里不会跟着改,谁也不认错。
- **做成一个新字段类型「带出」**:那一格只能装带出来的值,于是「带出来的金额」和
「我自己填的备注」得是两类格子,明细表那一列还得再来一类。字段类型本来只管
**装单个值还是一串值**,别让它再管值的来源。
- **在流程上配一张映射表**(像「从另一个流程带数据」那样挂在源上):那条源的主语是
「我去读那一个流程里的某一单」,条件(哪个流程、按什么筛、取哪一条)都得自己配;
关联带出的主语是**这一格已经挂着的那几张单**,条件就在这一格里,再配一遍只会配歪。
所以它长在这一格上:`optionSource` 说候选从哪儿来,`optionMap` 说看哪一列存哪一列,
`linkFill` 说**挑中之后的那些单据,值往哪里写**。三者都是字段上的正交配置,都只在
`clean_option_source` 那一趟里被收干净——`linkFill` 直接进 `SOURCE_OWNED_KEYS[process]`,
换了来源就跟着残骸一起被抹掉,与 `dictCode` / `dataSourceCode` 同一分寸。
## 2. 配置长什么样
```jsonc
{
"key": "orders", "type": "relation", "optionSource": "process",
"linkFill": {
"process": "<可选:设计器按哪个流程列字段名,不限制能挂谁的单>",
"rules": [
{ "pick": "work.serial", "to": "src_serial", "agg": "join", "separator": " / " },
{ "pick": "data.amount", "to": "total", "agg": "sum" },
{ "pick": "data.amount", "to": "items.amount" },
{ "pick": "data.reason", "to": "items.note" }
]
}
}
```
`pick` 读的是**对方那张单**:`service/processdata.py` 本来就把一张单据整形成
`{"work": {…}, "data": {…}}` 喂给取数那一层,这里共用同一份整形与同一条路径解析,
所以 `data.报销明细.sum(金额)`、`data.明细[部门=研发部].金额` 这些写法照用。
`to` 写的是**这一张单**,先整串认主表字段名,认不出才按第一个点拆成 `表.列`
(主表字段名允许带点,禁了等于改一遍所有老表单,所以把歧义定死在「整串优先」这一侧)。
一条规则只写进一格;两条抢同一格在保存那一刻就报「后一条永远盖掉前一条」。
上限:一格 30 条规则、一次 50 张单(超了是配错了,不是配少了)。
## 2.5 入口:四个地方,进的是同一栏
配置长在关联那一格上,这是数据该待的地方;**入口不能只长在那儿**。第一次用这件事的人问的
从来不是「`linkFill` 怎么写」,而是「我在哪儿设」,而她可能站在三个位置上问:想先把整张表单
核对一遍的人、已经挂上单据想接着补映射的人、站在明细表那一侧问「这几列谁来填」的人。只给
一个入口等于只答第二个人。四个入口,进去的是同一栏:
| 站在哪儿 | 看得见的东西 | 点下去到哪儿 |
| --- | --- | --- |
| 设计器顶上 | 「关联带出」那颗,角标写 `N 条` / `N 格待配` / `还没挂` | 总览弹窗 `LinkFillOverviewPanel.vue`:挂单据的格子配没配都列,每行说清几条、限定哪条流程、落到哪几格,就地展开改 |
| 画布上 | 关联那一格标「关联带出」(悬停:几条 → 落到哪儿),明细表那一格标「被带出」(悬停:被谁带的) | 双击那一格 = 选中它并把带出那一栏滚到眼前 |
| 明细表属性里 | 「带进这张表的关联字段」那一栏:哪一格 → 哪几列,一条一行 | 「去那一格」跳到那个关联字段并展开那一栏;还没人带时列出的是**可以**去配的那几格 |
| 关联那一格属性里 | 「候选来源」那一行(角标写来源类型与几条带出) | 弹窗里摊开的那一栏,就地改(见 [designer-panel-dialogs.md](designer-panel-dialogs.md)) |
三条钉住的分寸:
- **总览不另造编辑器**。它吃的是属性面板里那份 `LinkFillPanel`——同一份落点清单、同一句
「按同名自动配」、同一套校验措辞,只是摊在**不选中任何格子也开得动**的地方。两处各写一份,
早晚变成两套说法。
- **「跳到那一格」要真到位**。选中那一格只是第一步:那一栏现在藏在「候选来源」那扇门里,
人到了还得自己找门、开门、再往下滚。所以那一下同时记下「跳的是哪一格」
(`revealLinkFill` + `revealLinkFillKey`),被跳到的那一格**先把门打开**、再滚到眼前并描
一圈,选中一变就作废——否则下一个点开的关联字段跟着闪。门是 `design/SidePanel.vue`
那个 `reveal` 入参开的,不是这一栏自己特殊。
- **落点那句摘要只算一次**。`linkFillWhereNames` / `describeLinkFillWhere` 把名字收在一处,
角标的悬停说明、面板里那句「挂几张补几行」、总览那一行念的必须是同一份账。
「写进对应的字段」这句话最短的路是**按同名自动配**(`autoLinkFillRules`):对方表单里的字段名
(或显示名)跟这张表单上同名的那一格配起来,对不上的不动、已经配过的不抢、对方那张明细表不猜。
落点清单里不给挑「另一格关联审批单」——那一格存的是**挂着哪几张单**,把带出来的值写进去等于
把刚挑上的关联抹掉,下一趟提交连它自己都要带不出东西(`NOT_TARGET_TYPES` 与 `SKIP_TARGETS`
同一份清单);老表单真有这么写的照旧算得出,只是设计器不再递这个选项。
## 3. 主表那一路:几张单变成一个值
主表那一格只装得下一个值,挂了三张单就得说清「三个数怎么变成一个」。做法是照搬
外部取数那一套合并档(`first` / `join` / `sum` / `min` / `max`),落到
`binding.merge` 那一句——与「同一个字段从三个源取值怎么合」用的是同一把尺,不另造说法。
`sum` / `min` / `max` 要求那一格装得下数(`number` / `money` / `formula`),否则保存时说得出来。
**这一路与明细剩几行无关**:人把明细里带出来的行删了一半,`sum` 出来的还是那三张单的
金额合计,因为主表那几格读的是关联的那串单,不是明细表。要「按明细那几行合计」,
用公式去 `sum(items.amount)`,那是另一件事。
## 4. 明细那一路:一单一行
明细表装得下多行,于是「挂几张带几行」是天然形状。每一行带一格 `_link` = 带它来的
那张单的 `job`,这是**这一行是谁带出来的**唯一凭据:
| 这一次提交里 | 怎么办 |
| --- | --- |
| 新挂上一张单 | 在**末尾**补一行,行上每一列都在(没配的列留一个形状正确的空),配到的列取对方的值 |
| 取消一张单的关联 | 那一行跟着删(`_link` 对上才删) |
| 还挂着、行还在 | 只刷**配到带出的那几列**,其它列一个字不动;人排的次序不动 |
| 还挂着、行被人删了 | 补回来(加在末尾)——这一行属于那张单,人的删除留给「取消关联」去表达 |
| 人自己加的行(没有 `_link`) | 一动不动,也不占 `_link` 的账 |
| 挂着 `maxRows` | 补完裁到上限,与 `normalise_rows` 同一口径 |
`_link` 以下划线开头,等于声明「这是服务端自己写的留痕」:导出、打印、明细导出只认
配好的列,看不见它;`engine.without_trace_keys` 会在页面回传时把这类键丢掉;
`normalise_rows` 为它单开了一个口子(那一格不在列清单里,却是认行的凭据,整表时丢掉
就等于下一次带出认不出旧行,会把人改过的行当新行重排)。
`row_is_empty` 也认它:对方那张单里这一列本来没填,带出来的行可能是全空的,
但行还是那一张单的,按空行丢掉就等于把关联弄丢了。
**一张明细表可以被两个关联字段各带几行。**「挂两类单子」在真实表单上就是两格——报销单一格、
采购单一格,两格里的字段名根本不是一套,各配各的映射才对;而它们带出来的行落在同一张表上。
于是删行的凭据不能只看自己这一格:那一行的来源只要还挂在**别的**关联字段身上
(那一串值存的可能是 `job`,也可能是单号,绕一层换成 `job` 再比),这一格就不许动它——
否则后处理的那一格会把前一格刚补的那几行当成「自己这边取消关联了」删干净
(后端 `linkfill._protector` ↔ 前端 `syncRows` 的 `keep`)。主表那几格同理只按自己那一格
挂着的那串单算,两格各写各的落点;两条带出跨格抢同一格时按字段顺序,后者覆盖前者。
## 5. 什么时候重算:只在「关联那串值变了」时重排行
整趟对账只在**关联那串值与上一次不一样**时做。判据是 `data["_linkfill"][字段名]`——
上一次带出用的是哪一串,服务端自己写进留痕;这一次现读的那串与它对不上,才重排。
不这么做会怎样:带出发生在**每一次提交**上,如果每趟都对账,第二环的处理人只要提交一次,
他在第一环里手工删掉的那一行就被复活了。于是这条分寸写死在两处(前后端同一句判断):
- **关联没变** → 明细一行都不重排,人也就能改得,连配到带出的那一格都改得(改完就是
这一单的数,不再被盖);
- **关联变了** → 整趟对账:补的补、删的删、留下的行按来源刷新配到的那几列。
为什么记「这一格存着的那串值」而不是「查得到的那几张单」:挂上一张暂时查不到的单
(草稿被删、单号写歪)也算「关联变了」,得重排一次;按查得到的算会让这一轮什么也没发生,
等那张单哪天又查得着了,行早就跟关联对不上了。
主表那一路每趟都算(它只是几个数合成一个,没有「把人的活儿重做一遍」的问题),
明细那一路才要这一道闸。
## 6. 谁说了算:后端排在必填之前
```
_apply_form_runtime: autoFill → fetch(外部取数)→ linkfill(这一层)→ 公式 → 额度 → 阈值 → 必填校验
```
**预览那一趟带一道可见性闸,引擎那一份不带。**`POST /work/relation-values` 照
`GET /work/summaries`(也就是这一格回显本来就走的那条路)的分寸:只回与当前登录人相关的
那几张单,不相干的静默少回——这一格不能变成翻别人单据的口子。多认一档「确实挂在正在填的
这张单上」(请求带上 `work`):办理环节的人常常与对方那张单无关,而那些单是发起那一环替他
挂上的,少了这一档,带出那一栏对他就是一片空白。引擎那一路压根没有「谁在看」这个参数
(`works_by_values`),所以第二环提交照样算得出值——显示可以比落库保守,反过来不行。
排在这里有三个理由:公式要读到刚补好的那几行明细(`sum(items.amount)` 这类);额度与
阈值读的是带出之后的数;必填校验排在最后,所以「关联带出来的那一格」可以直接勾必填,
带不出值时那一趟提交真的被挡下——这是正经用法,不是巧合。
权威在后端意味着前端那一份只是显示。填单页上挑完关联要立刻看见行补出来,做法是:
1. `utils/linkFill.ts.linkFillPicks` 把这屏上所有 `pick` 并成一句,`POST /work/relation-values`
一次问回来 `[{job, value, values: {pick: 值}}]`(**路径解析只在后端有一份**,前端再镜像一遍
就是第五份解析器,而这一层刚花力气收成一份);
2. `applyLinkFill` 把回体交给与后端同一分寸的镜像实现,写回 `modelValue`;
3. 触发只盯一句 `linkFillSignal`(各关联字段此刻那串值压成的字符串),别的格子动一下
不重问;同值不重发,防抖 300 ms,连着挑几条只发最后一趟;几个关联字段并成**一趟**
问(值去重、`pick` 去重),回来的账按 `value` 分回各格;发出去之前记下此刻那串关联,
回来时人已经改过就不 apply(与外部取数那一路同一脾气);
4. 提交之后服务端那一份覆盖一切。界面上那一栏写得明明白白:手改那一格没用。
**分账认的是「问出去的那一句」,不是 `job`。** 那一格存 job 还是存单号由
`optionMap.valueKey` 说了算(费用报销单上「请选择出差备案流程」存的就是单号
`CCBAYZJ20261110000002`),于是预览发出去的那一串本身就可能是单号。回体里 `job`
永远是那张单的号,`value` 才是这一格存下来的那一句:只按 `job` 认领,一张也对不上号,
明细表一行都不补、主表那几格全空,而提交时引擎那一份算得出来——**界面空着、数据里有**
是最难查的那一种。钉这一条的是 `FormRenderer.linkFill.spec.ts` 里「那一格存的是单号」
那一条,与 `scripts/check_link_fill.py` 的「预览取值」。
## 7. 边界与校验
保存这一刻挡下来的四类毛病(`linkfill.problems` ↔ `utils/linkFill.linkFillProblems`,措辞一字不差):
来源不是「流程单据」(存得下来但永远不带)、`pick` 看不出要从哪一列取、`to` 指的格子
不在表单上了(格子名会被复用,把别的单的数盖到同名新格子上比少带一格危险)、
`sum` / `min` / `max` 配上装不下数的那一格。两条带出抢同一格也说得出。
`clean_option_source` 那三处收残骸:明细列上的 `linkFill` 整份丢掉;换了候选来源跟着
上一家一起丢;写歪的规则、认不出的合并档在 `clean` 里收掉,一条有效规则都不剩时整格抹掉
(留一份空 `rules` 只会让下一任以为配过什么)。
**查不到的那张单**(未发起就被删——`engine.delete_unstarted` 是把 `oa_work` 那一行
整个删掉的,归档表里也没有):主表那一格跳过它继续算剩下的,明细不替它编一行,不报错、
不挡人。它带来的那一行在关联变化时跟着 `_link` 对不上而删掉。
## 8. 已知不做
- **明细列上的关联带出**:那一格挂的也可以是单据,但「这一行的那张单 → 另一张表的几行」
是一行生一批行,明细表本身放不下这件事,界面上没人能预期。那一层要带数据走
「从另一个流程带数据」(`fetch`),它本来就是为「按当前行的条件去读一条」设计的。
- **反向回写**:只往这张单里带,不改对方那张单。带出去的数在对方改了之后要不要跟着变,
答案是「下一次提交时跟着变」,不是实时。
- **带出链**:关联带出的目标格可以同时是字典带出 / 外部取数的目标,但不进「关联带出 →
另一个关联字段的关联」这种环——链子长到要收敛判据时,多半是该在对方那张单上做一个
汇总口径,而不是在这里抄几十列。
## 9. 落点
| 层 | 位置 |
| --- | --- |
| 后端权威 | `backend/app/service/linkfill.py`(配置整形 / 校验 / 取值 / 落库四段) |
| 引擎挂钩 | `backend/app/engine/engine.py:_apply_form_runtime`(一行:`linkfill.apply`) |
| 行口径 | `backend/app/service/formruntime.py`(`ROW_LINK_KEY`、`max_rows_of`、`normalise_rows`、`row_is_empty`、`validate_schema`) |
| 保存整形 | `backend/app/api/design.py`(`SOURCE_OWNED_KEYS`、`clean_option_source`) |
| 预览接口 | `backend/app/api/runtime.py`(`POST /work/relation-values`)、`schemas.RelationFillBody` |
| 前端镜像 | `frontend/src/utils/linkFill.ts` |
| 设计器 | `frontend/src/components/oa/design/LinkFillPanel.vue`(挂在 `OptionSourcePanel.vue` 里,总览弹窗也吃它) |
| 填单预览 | `frontend/src/components/oa/FormRenderer.vue`(`linkFillSignal` → `runLinkFills`) |
| 设计器入口 | `frontend/src/components/oa/design/LinkFillOverviewPanel.vue`(顶上工具栏那颗,见 §2.5);画布那两枚角标在 `FormSheetCanvas.vue`,明细表那一侧的清单在 `FieldInspector.vue`(`table-link-fill` 那一栏) |
| 入口那几笔账 | `frontend/src/utils/linkFill.ts`(`linkFillSourceFields` / `linkFillTotalRules` / `linkFillWhereNames` / `describeLinkFillWhere` / `linkFillIntoTable` / `autoLinkFillRules`) |
| 删字段 / 改名 | `frontend/src/utils/formPrune.ts`、`formRename.ts` 跟着 `linkFillTargets` 一起清 |
| 验收 | 后端 `check_link_fill.py`(不连库)+ `check_link_fill_submit.py`(真提交);前端 `utils/linkFill.spec.ts`、`components/oa/FormRenderer.linkFill.spec.ts`、`design/LinkFillOverviewPanel.spec.ts`、`design/LinkFillPanel.reveal.spec.ts`、`views/oa/design/FormDesignerView.linkFillEntry.spec.ts` |

View File

@ -193,6 +193,7 @@ where account = :applicant
| 用在哪 | 配法 | 效果 |
| --- | --- | --- |
| 字段带出 | `fetch` 指向 SQL 源 | 填单时取一次给看,提交时后端再取一次并覆盖;`revalidateAfter` 到点自动重取、`freezeAfterStart` 发起后不再改(见 [form-data-integration-design.md](form-data-integration-design.md) §9.1) |
| 明细列逐行带出 | 列上那份 `fetch` 指向 SQL 源 | 一行查一次:入参读「整张单 + 这一行」,值与 `picks` 只落在这张表的列上(§6 第 4 条;口径见 form-data-integration-design.md §9.2)。SQL 通道 200 行上限在这里几乎用不上——每行本来就只要一行 |
| 一行带多格 | 同一行的其它列填进 `map_extra` + `picks` | 选成本中心,余额、负责人、科目名一起落进各自的格子 |
| 多源合成 | 一格挂几个源(`sources` + `merge`) | ERP 接口 + 本库 SQL 两张源凑一个值:first / sum / min / max / join |
| 候选下拉 | `kind=search` 的 SQL 源 | 大列表下拉直接查库搜:`LIKE CONCAT('%', :keyword, '%')`,`:keyword` 由搜索框给,不用配入参 |
@ -206,8 +207,12 @@ where account = :applicant
2. **不能往外写**:`direction=out` 直接拒。写回是 [outbound-integration-design.md](outbound-integration-design.md)
那一摊(模板、发件箱、重试、成功判定),一条 SELECT 替代不了它。
3. **不碰 `auto` 那 12 个 key**:见 §1 末。它们该管发起人相关,且要能塑形成登录账号 / 部门路径。
4. **不做结果集控件**:明细表不能整表由 SQL 填。那是"一次查一批、每行装进一格"的新形态,
有了需求再设计,别在带出这一格里塞个表格编辑器。
4. **不做结果集控件**:明细表仍然不能**整表**由一条 SQL 填。那是"一次查一批、每行装进一格"
的新形态,有了需求再设计,别在带出这一格里塞个表格编辑器。
2026-11 补的是另一件事:**明细列可以逐行取数**(列上挂 `fetch`,一行一调,
见 [form-data-integration-design.md](form-data-integration-design.md) §9.2)。两者不是一回事——
前者是"一条查询生出 N 行",后者是"已有的 N 行各自去问一次",边界照旧划在**行的增减由人决定**
这一句上:取数只往已经在表里的那些行上写值,不替你新增行、也不删行。
5. **前端那份入参识别只是提示**:`utils/sqlParams.ts` 认 `:name` 只为边写边提醒,
保存与执行都以后端 `sqlsource.mask` 那份为准;判例两边对着写,漂了测试就红。
6. **金额列转 float**:`Decimal` 进不了 JSON 与留痕那一列,与 `work.data` 一直是 float 元同口径。

View File

@ -2,6 +2,11 @@
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<!--
IE 在内网里默认可能掉进"兼容性视图",那一档按 IE7 的盒子模型画,栅格全歪。
这一句把它按回本机最新的内核;老内核认不认识这一句都不影响别的浏览器。
-->
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<link rel="icon" type="image/svg+xml" href="/logo.svg" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
<!-- PWA:装到桌面之后是一条独立的 App 任务栏,地址栏没有了,
@ -20,12 +25,75 @@
try {
var saved = localStorage.getItem('theme')
var dark = saved === 'dark' || (!saved && window.matchMedia('(prefers-color-scheme: dark)').matches)
document.documentElement.classList.toggle('dark', dark)
// 不用 classList.toggle(name, force):IE 11 认不出第二个参数,深色档会变反。
if (dark) document.documentElement.classList.add('dark')
else document.documentElement.classList.remove('dark')
} catch (e) {
/* 隐私模式里 localStorage 会抛:照着浅色画就是 */
}
})()
</script>
<!--
老内核闸门。跑不了这套界面就别让它空转骨架屏:骨架屏是会一直闪的那幅样子,
人对着一片闪只能猜"网慢",实际上这一档引擎根本画不出来(Vue 3 的响应式要 Proxy,
Tailwind 的色板要 CSS 变量,两者都补不出来)。判据与 src/utils/legacyCompat.ts
的 probeRuntime() 同一套,浏览器口径见 docs/frontend-design.md §15。
这一整段必须是 ES5:语法本身解析不了的话,告示也就没人看见了。
还有一条踩过坑的规矩:这段写在 head 里,那时候 body 与 #app 都还不存在,
一上来就往 body 上挂东西会抛异常,而异常是 catch 掉的——闸门等于没装上。
所以先只往 <html> 上打标记,那句人话等 body 长出来再画。
-->
<script>
(function () {
var g = typeof window !== 'undefined' ? window : this
var missing = []
if (typeof g.Proxy !== 'function') missing.push('Proxy')
if (typeof g.Symbol !== 'function') missing.push('Symbol')
if (typeof g.Promise !== 'function') missing.push('Promise')
var cssVars = false
try {
cssVars = !!(g.CSS && g.CSS.supports && g.CSS.supports('--oa-compat', '0'))
} catch (e) {
cssVars = false
}
if (!cssVars) missing.push('CSS 变量')
if (!missing.length) return
// 标记先打上:骨架屏是靠 CSS 藏起来的,早一拍就不会闪。
document.documentElement.setAttribute('data-legacy-engine', '1')
var draw = function () {
try {
if (document.querySelector('[data-legacy-gate]')) return
var notice = document.createElement('div')
notice.setAttribute('data-legacy-gate', '')
notice.style.cssText =
'display:block;box-sizing:border-box;max-width:640px;margin:12vh auto;padding:24px;' +
'border:1px solid #e5e7eb;border-radius:12px;background:#fff;color:#111827;' +
"font:14px/1.7 -apple-system,'Segoe UI','Microsoft YaHei',sans-serif"
notice.innerHTML =
'<div style="margin:0 0 8px;font-size:18px;font-weight:600">当前浏览器内核过旧,这一页画不出来</div>' +
'<p style="margin:0 0 12px">这套办公界面要用到 <code>Proxy</code> 与 CSS 变量,老内核缺了它们就无法正确渲染:系统带出值、明细表、金额与日期都可能空着。</p>' +
'<p style="margin:0 0 12px">请改用 <strong>Microsoft Edge</strong>、<strong>Chrome</strong>、<strong>Firefox</strong> 或 360 浏览器的极速模式打开;如果开着 Edge 的「IE 模式」,切回 Edge 模式即可。</p>' +
'<p style="margin:0;color:#6b7280;font-size:12px">检测到缺失:' + missing.join('、') + '</p>'
var app = document.getElementById('app')
if (app) {
app.innerHTML = ''
app.appendChild(notice)
} else if (document.body) {
document.body.appendChild(notice)
}
} catch (e) {
/* 连告示都画不出来的引擎,只能留给下一位了 */
}
}
// addEventListener 本身也是要看一眼的:IE 8 只有 attachEvent,那句人话得换个门等
if (document.readyState !== 'loading') draw()
else if (document.addEventListener) document.addEventListener('DOMContentLoaded', draw, false)
else if (g.addEventListener) g.addEventListener('load', draw, false)
else if (g.attachEvent) g.attachEvent('onload', draw)
else draw()
})()
</script>
<style>
/* 首屏骨架:免登落地要先拿一次性票据换会话,这段等待不该让人看见一张登录页。
320ms 之内能进站就压根不画它(靠 animation-delay 撑着),网络慢时才替上那片空白。
@ -39,6 +107,8 @@
animation: boot-reveal 1ms linear 320ms forwards;
}
.dark .boot-shell { background: #020617; }
/* 闸门拉下之后,这幅会一直闪的占位就该消失:脚本里的异常都 catch 了,不能指望它自己收尾 */
[data-legacy-engine] .boot-shell { display: none; }
.boot-bar,
.boot-tabs {
display: flex;
@ -88,6 +158,11 @@
</style>
</head>
<body>
<noscript>
<div style="max-width:640px;margin:12vh auto;padding:24px;border:1px solid #e5e7eb;border-radius:12px;background:#fff;color:#111827;font:14px/1.7 sans-serif">
这一页要靠 JavaScript 才能列出待办与表单,请在浏览器里允许脚本运行后刷新。
</div>
</noscript>
<div id="app">
<!-- 这一份是挂载前的占位,app.mount() 会把它整块换掉。
画的是"进站的壳子"而不是登录页:从企业微信卡片点进来的人不该先撞见一张登录卡。 -->

View File

@ -1,4 +1,5 @@
import { http } from './client'
import { eachGlobalMatch } from '@/utils/legacyCompat'
import type {
DataSource,
DataSourceLogEntry,
@ -138,13 +139,16 @@ export function processFields(process: string): Promise<{
return http.get('/design/data-sources/process-fields', { process })
}
/** 模板里 `{arg.x}` 与 `{form.x}` 那两种写法(与后端渲染模板同一把尺子)。 */
const ARG_FORM_TOKEN = /\{(?:arg|form)[.:]\s*([^}]+?)\s*\}/g
/** 从请求体模板里读出这个源声明了哪些入参(``{arg.x}`` / ``{form.x}``)。 */
export function declaredArgs(source: DataSource | null | undefined): string[] {
if (!source) return []
const found = new Set<string>()
const walk = (value: unknown): void => {
if (typeof value === 'string') {
for (const match of value.matchAll(/\{(?:arg|form)[.:]\s*([^}]+?)\s*\}/g)) found.add(match[1])
eachGlobalMatch(value, ARG_FORM_TOKEN, (match) => found.add(match[1]))
} else if (Array.isArray(value)) {
value.forEach(walk)
} else if (value && typeof value === 'object') {

View File

@ -1,3 +1,5 @@
import { httpOrigin } from '@/utils/url'
const DEFAULT_API_BASE_URL = '/api/v1'
const API_BASE_URL = normalizeAPIBaseURL(import.meta.env.VITE_API_BASE_URL)
@ -52,13 +54,7 @@ export function trimAPIBase(url: string): string {
export function buildGatewayUrl(path: string): string {
const suffix = normalizePath(path)
try {
const origin =
typeof window === 'undefined'
? new URL(getAPIBaseURL()).origin
: new URL(getAPIBaseURL(), window.location.origin).origin
return `${origin}${suffix}`
} catch {
return suffix
}
// httpOrigin:原生 URL 在的照它规范化,不在的(IE 那一档)自己拆,拆不出来才回相对路径
const origin = httpOrigin(getAPIBaseURL(), typeof window === 'undefined' ? '' : window.location.origin)
return origin ? `${origin}${suffix}` : suffix
}

View File

@ -149,6 +149,23 @@ export function workSummaries(jobs: string[]): Promise<WorkSummary[]> {
return http.get<WorkSummary[]>('/work/summaries', { jobs: jobs.join(',') })
}
/**
* 关联带出的即时预览:按这一格挂着的那几张单,回每一条 `pick` 取到的值。
*
* 只用来显示。提交时引擎按同一份配置再算一遍并覆盖(`service/linkfill.apply`),
* 与外部取数那一格同一分寸。路径解析只有后端一份实现,前端不再镜像一遍。
*
* `work` 传正在填的那张单的 job(发起页还没有就不传):后端那一道可见性闸多认一档
* 「确实挂在正在填的这一单上的」,办理环节的人才不会看着带出那一栏一片空白。
*/
export function relationValues(
values: string[],
picks: string[],
work = ''
): Promise<{ items: { job: string; value: string; values: Record<string, unknown> }[] }> {
return http.post('/work/relation-values', { values, picks, work })
}
export interface WorkSummary {
job: string
serial: string
@ -197,13 +214,36 @@ export function adminResume(job: string, opinion = ''): Promise<WorkItem> {
return http.post<WorkItem>(`/admin/work/${job}/resume`, { opinion })
}
/** 干预改道:把整张单子搬到指定环节重走,当前待办全部结掉进已办。 */
/** 干预改道:把整张单子搬到指定环节重走,当前待办全部结掉进已办。
*
* ``cascadeChildren`` 只在这张单还挂着在跑的子流程时用得上:不勾的话引擎会停手
* (子单上的待办会就此没人认领),勾了才把这些子单一并终止。
*/
export function adminMove(
job: string,
activity: string,
opinion = ''
opinion = '',
cascadeChildren = false
): Promise<StepResult & { current_activity_names: string }> {
return http.post(`/admin/work/${job}/move`, { activity, opinion })
return http.post(`/admin/work/${job}/move`, { activity, opinion, cascade_children: cascadeChildren })
}
/** 改道页签打开时先问一句:这一单上还有什么会跟着一起被搬走(只读,什么都不改)。 */
export interface RerouteBlockers {
children: {
job: string
serial: string
title: string
activity_name: string
holders: string[]
}[]
/** 引擎那句原话:预检与真动手撞上同一句判据,界面不会与引擎各讲一套 */
blocker: string
staged_decisions: { app_name: string; activity_name: string; decision: string }[]
}
export function adminRerouteBlockers(job: string): Promise<RerouteBlockers> {
return http.get<RerouteBlockers>(`/admin/work/${job}/reroute-blockers`)
}
/** 修正表单数据:只交改动的那几项,改了什么写进流转记录。 */
@ -250,8 +290,8 @@ export function listReadCompleted(
return http.get<PageResult<ReadItem>>('/read/completed', query, options)
}
export function viewRead(id: string, opinion = ''): Promise<void> {
return http.post(`/read/${id}/view`, { opinion })
export function viewRead(id: string, opinion = '', attachments: string[] = []): Promise<void> {
return http.post(`/read/${id}/view`, { opinion, attachments })
}
/**
@ -291,9 +331,12 @@ export function removeComment(commentId: string): Promise<void> {
return http.del(`/work/comments/${commentId}`)
}
/** 抄送需处理:必须填处理意见,登记后进已阅。 */
export function handleRead(id: string, opinion: string): Promise<void> {
return http.post(`/read/${id}/handle`, { opinion })
/**
* 抄送需处理:必须填处理意见(可随附图片/文件),登记后进已阅。
* 附件是前端先传到 /attachment 拿到的 id,服务端按「本人上传且没被别人认领」认领。
*/
export function handleRead(id: string, opinion: string, attachments: string[] = []): Promise<void> {
return http.post(`/read/${id}/handle`, { opinion, attachments })
}
export function listDrafts(query: Record<string, unknown> = {}): Promise<DraftItem[]> {

View File

@ -272,6 +272,7 @@ import { useVirtualizer, observeElementRect as observeElementRectDefault } from
import { useI18n } from 'vue-i18n'
import type { Column } from './types'
import Icon from '@/components/icons/Icon.vue'
import { compareDisplayText } from '@/utils/format'
const { t } = useI18n()
@ -512,11 +513,6 @@ type PersistedSortState = {
order: 'asc' | 'desc'
}
const collator = new Intl.Collator(undefined, {
numeric: true,
sensitivity: 'base'
})
const getSortableKeys = () => {
const keys = new Set<string>()
for (const col of props.columns) {
@ -634,7 +630,7 @@ const compareSortValues = (a: any, b: any): number => {
const aStr = toSortableString(a)
const bStr = toSortableString(b)
const res = collator.compare(aStr, bStr)
const res = compareDisplayText(aStr, bStr)
if (res === 0) return 0
return res < 0 ? -1 : 1
}

View File

@ -0,0 +1,32 @@
<template>
<span data-test="link-text">
<!-- 段与段之间不摆任何空白:值里本来是什么样子,上屏还是什么样子 -->
<template v-for="(seg, index) in segments" :key="index">
<a v-if="seg.href" :href="seg.href" target="_blank" rel="noopener noreferrer" class="break-all text-primary-600 underline decoration-primary-300/70 underline-offset-2 active:opacity-70 dark:text-primary-300" data-test="link-text-href" @click.stop>{{ seg.text }}</a>
<template v-else>{{ seg.text }}</template>
</template>
</span>
</template>
<script setup lang="ts">
/**
* 一串值里认得出的网址就地变成点得开的链接,认不出的照普通文字摆。
*
* 手机上尤其需要这一层:桌面能把光标挪到链接上看真地址、能划词复制,手机上点不到就是点不到。
* 判据不在这里,全在 utils/linkText,这一只组件只负责按段渲染。
*/
import { computed } from 'vue'
import { linkSegments } from '@/utils/linkText'
const props = withDefaults(
defineProps<{
/** 要上屏的那串值 */
text?: string | number | null
/** 这一格本来就是链接格子(`type === 'url'`):整串当一个地址看,裸域名也认 */
wholeUrl?: boolean
}>(),
{ text: '', wholeUrl: false }
)
const segments = computed(() => linkSegments(props.text, { wholeUrl: props.wholeUrl }))
</script>

View File

@ -261,3 +261,46 @@ describe('几千项的字典:本地筛得动', () => {
expect(model.value).toBe('V000000')
})
})
describe('框里那颗标签点得开(候选带了落点的那些)', () => {
const WORKS = [
{ value: 'J1', label: '出差备案申请', href: '/work/J1' },
{ value: 'J2', label: '差旅费报销' }
]
it('写了 href 的那一项画成链接,点开的是新标签页;没写的还是死文字', async () => {
const openSpy = vi.spyOn(window, 'open').mockImplementation(() => null)
const { wrapper, update } = setup({ multiple: true, options: WORKS, modelValue: ['J1', 'J2'], linkTitle: '打开这一张单' })
const [first, second] = chips(wrapper)
expect(first.find('[data-test="select-chip-link"]').attributes('title')).toBe('打开这一张单')
expect(second.find('[data-test="select-chip-link"]').exists()).toBe(false)
await first.get('[data-test="select-chip-link"]').trigger('click')
expect(openSpy).toHaveBeenCalledWith('/work/J1', '_blank', 'noopener')
// 点名字是去看那张单,不是改选择、也不是把弹层打开
expect(update).not.toHaveBeenCalled()
expect(wrapper.find('button.field-trigger').attributes('aria-expanded')).toBe('false')
openSpy.mockRestore()
})
it('known 里补的落点也算数:跨页挑中的那几条一样点得开', async () => {
const openSpy = vi.spyOn(window, 'open').mockImplementation(() => null)
const { wrapper } = setup({ multiple: true, remote: true, options: [], known: [{ value: 'J9', label: '用车申请', href: '/work/J9' }], modelValue: ['J9'] })
await chips(wrapper)[0].get('[data-test="select-chip-link"]').trigger('click')
expect(openSpy).toHaveBeenCalledWith('/work/J9', '_blank', 'noopener')
openSpy.mockRestore()
})
it('键盘也点得开:回车开单,退格摘标签,两件事不串', async () => {
const openSpy = vi.spyOn(window, 'open').mockImplementation(() => null)
const { wrapper, model } = setup({ multiple: true, options: WORKS, modelValue: ['J1'] })
const link = chips(wrapper)[0].get('[data-test="select-chip-link"]')
await link.trigger('keydown', { key: 'Enter' })
expect(openSpy).toHaveBeenCalledWith('/work/J1', '_blank', 'noopener')
await link.trigger('keydown', { key: 'Backspace' })
expect(openSpy).toHaveBeenCalledTimes(1)
// 挂在按钮里的链接不许把选择改掉
expect(model.value).toEqual(['J1'])
openSpy.mockRestore()
})
})

View File

@ -1,5 +1,5 @@
<template>
<div class="relative" ref="containerRef">
<div class="relative min-w-0" ref="containerRef">
<button
ref="triggerRef"
type="button"
@ -26,7 +26,20 @@
<!-- 多选:已选的挂在框里,一颗一颗摘;格子太窄时多出来的收进「+N」,不把整行顶高 -->
<template v-if="multiple">
<span v-for="chip in visibleChips" :key="chipKey(chip.value)" class="field-tag select-chip">
<span class="select-chip-label">{{ chip.label }}</span>
<span
v-if="chip.href"
role="link"
tabindex="0"
class="select-chip-label select-chip-link"
:title="linkTitle || chip.label"
data-test="select-chip-link"
@click.stop="openChip(chip.href)"
@mousedown.stop
@keydown.enter.stop.prevent="openChip(chip.href)"
>
{{ chip.label }}
</span>
<span v-else class="select-chip-label">{{ chip.label }}</span>
<span
role="button"
tabindex="-1"
@ -227,6 +240,12 @@ const props = withDefaults(
* 早就不在候选里了,框里还得念出它叫什么,不能空着一个编码让人以为没选上。
*/
known?: SelectOption[]
/**
* 候选带了 `href`(关联单据那一类)时,框里标签上悬停说的那句话。
*
* 不给就用名字本身当提示——标签会截断,全名总得看得见。
*/
linkTitle?: string
}>(),
{
disabled: false,
@ -241,7 +260,8 @@ const props = withDefaults(
remote: false,
loading: false,
multiple: false,
known: () => []
known: () => [],
linkTitle: ''
}
)
@ -428,6 +448,17 @@ const labelIndex = computed(() => {
const labelOf = (value: Scalar): string => labelIndex.value.get(String(value ?? '')) ?? String(value ?? '')
/** 值 → 点得开的那个地址:只有调用方在候选上写了 `href` 的这几项有(关联单据那一类)。 */
const hrefIndex = computed(() => {
const index = new Map<string, string>()
;[...(props.known ?? []), ...(props.options as any[])].forEach((option) => {
if (option === null || option === undefined) return
const href = String((option as any).href ?? '')
if (href) index.set(String(getOptionValue(option) ?? ''), href)
})
return index
})
/** 框里此刻有哪几项(多选那一串;单选那一格不参与,别拿一个值冒充一串)。 */
const selectedValues = computed<Scalar[]>(() => {
if (!props.multiple) return []
@ -436,7 +467,19 @@ const selectedValues = computed<Scalar[]>(() => {
return raw === null || raw === undefined || raw === '' ? [] : [raw]
})
const chips = computed(() => selectedValues.value.map((value) => ({ value, label: labelOf(value) })))
const chips = computed(() =>
selectedValues.value.map((value) => ({
value,
label: labelOf(value),
href: hrefIndex.value.get(String(value ?? '')) ?? ''
}))
)
/** 点开框里那颗标签指向的那张单:新标签页,手上这张不丢。 */
function openChip(href: string) {
if (props.disabled || !href) return
window.open(href, '_blank', 'noopener')
}
/** 明细格子里只留得下一颗标签的位置,多出来的收进「+N」;正常格子摊得开,就不收。 */
const COMPACT_TAG_LIMIT = 1
const visibleChips = computed(() =>
@ -791,6 +834,12 @@ onUnmounted(() => {
@apply max-w-[12rem] truncate;
}
/* 标签上那个名字点得开(关联单据):颜色跟牌子一致,靠下划线与光标说它不是死文字 */
.select-chip-link {
@apply cursor-pointer underline-offset-2;
@apply hover:underline focus:underline focus:outline-none;
}
/* 牌子上那颗 ×:不能真用 <button>(触发器本身已经是一只按钮,按钮不许套按钮) */
.select-chip-x {
@apply flex flex-shrink-0 cursor-pointer items-center justify-center rounded p-0.5;

View File

@ -35,7 +35,13 @@
>
<div class="flex items-center justify-between px-2 py-1.5">
<span class="text-sm font-semibold text-gray-900 dark:text-white">{{ t('workbench.notifications') }}</span>
<button type="button" class="text-xs text-primary-600 hover:underline" @click="markAllRead">
<!-- 面板只摆没读过的,没有未读时这颗钮也就没活干 -->
<button
v-if="unread > 0"
type="button"
class="text-xs text-primary-600 hover:underline"
@click="markAllRead"
>
全部已读
</button>
</div>
@ -176,7 +182,8 @@ function toggleTheme() {
async function loadNotifications() {
try {
const [page, count] = await Promise.all([
supportAPI.listNotifications({ page: 1, page_size: 12 }),
// 只摆没读过的那几条:这条面板是「还有什么没告诉你」,不是历史归档
supportAPI.listNotifications({ page: 1, page_size: 12, unread_only: true }),
supportAPI.unreadCount()
])
notifications.value = page.items

View File

@ -19,7 +19,19 @@
<span class="flex min-w-0 flex-1 flex-wrap items-center gap-1.5">
<template v-if="multiple && items.length">
<span v-for="item in items" :key="item.id" class="field-tag">
<span class="max-w-[16rem] truncate">{{ item.label }}</span>
<a
v-if="item.href"
:href="item.href"
target="_blank"
rel="noopener"
class="max-w-[16rem] truncate hover:underline"
:title="item.linkTitle || item.label"
data-test="combo-tag-link"
@click.stop
>
{{ item.label }}
</a>
<span v-else class="max-w-[16rem] truncate">{{ item.label }}</span>
<span v-if="item.note" class="flex-shrink-0 text-primary-500">{{ item.note }}</span>
<button
type="button"
@ -33,7 +45,19 @@
<span v-if="!text" class="truncate text-gray-400 dark:text-dark-400">{{ placeholder }}</span>
</template>
<span v-else class="min-w-0 truncate" :class="hasText ? '' : 'text-gray-400 dark:text-dark-400'">
{{ hasText ? text : placeholder }}
<a
v-if="textHref && hasText"
:href="textHref"
target="_blank"
rel="noopener"
class="hover:underline"
:title="textLinkTitle || text"
data-test="combo-text-link"
@click.stop
>
{{ text }}
</a>
<template v-else>{{ hasText ? text : placeholder }}</template>
</span>
</span>
@ -70,12 +94,19 @@ export interface ComboTag {
label: string
/** 那行小字:单号、编码之类,跟在标签后面帮人认出是哪一条 */
note?: string
/** 给这个名字挂的落点(如关联单据那一页):有它才把名字画成链接 */
href?: string
/** 悬停那句话:说清这一点会开新标签页,手上这张单不会丢 */
linkTitle?: string
}
const props = withDefaults(
defineProps<{
/** 单个值时框里念的那句话 */
text?: string
/** 那一句话的落点:与 `items[].href` 同一件事,只是单选框里只有一句话可点 */
textHref?: string
textLinkTitle?: string
/** 多个值时框里挂的那排标签 */
items?: ComboTag[]
multiple?: boolean
@ -91,6 +122,8 @@ const props = withDefaults(
}>(),
{
text: '',
textHref: '',
textLinkTitle: '',
items: () => [],
multiple: false,
placeholder: '',

View File

@ -167,6 +167,7 @@ import {
} from '@/api/embeds'
import { failureMessage } from '@/api/client'
import { formRefs } from '@/utils/binding'
import { httpOrigin } from '@/utils/url'
import type { EmbedActionRequest, EmbedWritebackOutcome } from '@/utils/embedBridge'
import { embedAck, embedHandshake, embedNonce, embedParamsPush, readEmbedMessage } from '@/utils/embedBridge'
import {
@ -1163,11 +1164,8 @@ function ackWriteback(outcome: EmbedWritebackOutcome | null) {
watch(() => props.writebackResult, ackWriteback)
function safeOrigin(url: string): string {
try {
return new URL(url, window.location.origin).origin
} catch {
return ''
}
// 回填用的 targetOrigin:老内核没有 URL 也要能认,否则外部页写回来的值会被丢掉
return httpOrigin(url, window.location.origin)
}
function measureNarrow() {

View File

@ -0,0 +1,55 @@
// @vitest-environment jsdom
/**
* 链接格子:填的时候要看得见「打开」,看的时候那一串字本身就点得开。
*
* 手机上这是硬需求——屏幕里没有地址栏、也没法划词,一串摆成纯文本的网址等于让人手抄。
*/
import { describe, expect, it } from 'vitest'
import { mount } from '@vue/test-utils'
import { createI18n } from 'vue-i18n'
import zh from '@/i18n/locales/zh'
import FormFieldControl from './FormFieldControl.vue'
import type { FormFieldDef } from '@/types'
const i18n = createI18n({ legacy: false, locale: 'zh', messages: { zh } })
function control(field: FormFieldDef, value?: unknown, readonly = false) {
return mount(FormFieldControl, { props: { field, value, readonly }, global: { plugins: [i18n] } })
}
const field: FormFieldDef = { key: 'doc', label: '制度原文', type: 'url' }
describe('链接格子', () => {
it('只读态那一串字就是链接,裸域名补上协议再指过去', () => {
const wrapper = control(field, 'oa.example.com/policy/2026', true)
const link = wrapper.get('a')
expect(link.attributes('href')).toBe('https://oa.example.com/policy/2026')
expect(link.attributes('target')).toBe('_blank')
expect(link.text()).toBe('oa.example.com/policy/2026')
})
it('有人往链接格写了一句话:退回普通文字,不摆一条点不通的链接', () => {
const wrapper = control(field, '见内网制度页', true)
expect(wrapper.find('a').exists()).toBe(false)
expect(wrapper.text()).toBe('见内网制度页')
})
it('填的时候底下给一条「打开链接」,值一改就跟着改', async () => {
const wrapper = control(field, 'https://a.com/x')
const box = wrapper.get('input[type=url]')
expect(box.element.value).toBe('https://a.com/x')
const open = wrapper.get('[data-test="url-open"]')
expect(open.attributes('href')).toBe('https://a.com/x')
expect(open.text()).toContain('打开链接')
await box.setValue('www.b.com/doc')
expect(wrapper.emitted('update:value')?.at(-1)?.[0]).toBe('www.b.com/doc')
await wrapper.setProps({ value: 'www.b.com/doc' })
expect(wrapper.get('[data-test="url-open"]').attributes('href')).toBe('https://www.b.com/doc')
})
it('还没填的时候不给「打开链接」,也别留一条点开是空页的', () => {
const wrapper = control(field, '')
expect(wrapper.find('[data-test="url-open"]').exists()).toBe(false)
expect(wrapper.get('input[type=url]').exists()).toBe(true)
})
})

View File

@ -21,9 +21,10 @@
</div>
<p v-else-if="field.type === 'textarea'" class="whitespace-pre-wrap">{{ display || '--' }}</p>
<a
v-else-if="field.type === 'url' && display"
:href="display"
v-else-if="field.type === 'url' && urlHref"
:href="urlHref"
target="_blank"
rel="noopener noreferrer"
class="break-all text-primary-600 hover:underline dark:text-primary-300"
>
{{ display }}
@ -83,6 +84,7 @@
:multiple="multiple"
:options="options"
:process="relationProcess"
:statuses="relationStatuses"
:source-code="dataSourceCode"
:source-args="dataSourceArgs"
:form-data="formData"
@ -183,6 +185,30 @@
:placeholder="field.placeholder"
@update:model-value="emit('update:value', $event)"
/>
<!--
链接格子:填的人要的是「填完还点得开」。输入框里那串字手机上点不动,
所以底下另给一条真链接——裸域名也认,协议缺了由 utils/linkText 补。
-->
<div v-else-if="field.type === 'url'" class="min-w-0" data-test="url-field">
<input
type="url"
:class="inputClass"
:placeholder="placeholder"
:value="text"
@input="emit('update:value', ($event.target as HTMLInputElement).value)"
/>
<a
v-if="urlHref"
:href="urlHref"
target="_blank"
rel="noopener noreferrer"
class="mt-1 inline-flex max-w-full items-center gap-1 break-all text-xs text-primary-600 active:opacity-70 dark:text-primary-300"
data-test="url-open"
>
<Icon name="externalLink" class="h-3.5 w-3.5 flex-shrink-0" />
<span>{{ t('form.openLink') }}</span>
</a>
</div>
<input
v-else-if="htmlInputType(field.type)"
:type="htmlInputType(field.type)"
@ -327,9 +353,10 @@ import LocationField from './LocationField.vue'
import MarkdownBlock from './MarkdownBlock.vue'
import RichTextEditor from './RichTextEditor.vue'
import { htmlInputType } from '@/utils/formLayout'
import { toHref } from '@/utils/linkText'
import { acceptOf, displayUnit, formatNumber, locationText, monthsStyleOf, monthsText, rangeText, weekText } from '@/utils/formRuntime'
import { hasOptions } from '@/utils/formLinkage'
import { carriesOptionSource, holdsListValue, pickerStyleOf, sourceKindOf } from '@/utils/optionSource'
import { carriesOptionSource, holdsListValue, pickerStyleOf, relationStatusesOf, sourceKindOf } from '@/utils/optionSource'
import type { DeptOption } from '@/utils/deptOptions'
import type { Attachment, AttachmentItem, DictItem, FormFieldDef } from '@/types'
@ -429,6 +456,8 @@ const pickerStyle = computed(() => pickerStyleOf(props.field, optionSource.value
const monthsStyle = computed(() => monthsStyleOf(props.field))
const multiple = computed(() => holdsListValue(props.field))
const relationProcess = computed(() => String(props.field.relationProcess ?? ''))
/** 这一格能挂哪几种状态的单据(没配就是只给归档通过的),口径在 utils/optionSource.ts。 */
const relationStatuses = computed(() => relationStatusesOf(props.field))
const dataSourceCode = computed(() => String(props.field.dataSourceCode ?? ''))
/** 候选来源那张源还要按哪些字段筛(写法在填单时现算,口径在 utils/binding)。 */
const dataSourceArgs = computed(() => props.field.dataSourceArgs)
@ -441,6 +470,8 @@ const showsPickedTags = computed(
() => props.field.type === 'relation' || optionSource.value === 'process' || optionSource.value === 'dataSource'
)
const numberValue = computed(() => Number(props.value ?? 0) || 0)
/** 链接格子(只读那串字 / 编辑态那条「打开」)真正指去的地址;认不出来就是空串,不摆链接 */
const urlHref = computed(() => (props.field.type === 'url' ? toHref(text.value, { bareHost: true }) : ''))
/** 星级列的满星数:跟主表一样吃 max,配歪了退回 5。 */
const starCount = computed(() => {

View File

@ -0,0 +1,128 @@
// @vitest-environment jsdom
/**
* 值还没到之前,框里那一句归谁写。
*
* 用户那句原话:「我不希望组件里面有这样的说明。除非是有个地方让我可以配置里面展示的文字。」
* 指的就是系统带出那一格空着时框里那句「提交后由系统自动填写」——组件自己编的话,配表的人
* 既删不掉也换不了。现在只有一个地方说话:属性面板那一栏(普通格子叫「占位提示」,系统带出与
* 公式叫「没值时显示的文字」,写的都是同一个 `placeholder`),没配就给全平台那句空值标记
* ``--``——不编话不等于什么都不说:同屏空着的申请部门、各档金额都写 ``--``,只这一格留一片
* 空白,读起来像字段没了(2026-11 那句「创建表单为什么看不到流程编号了」)。
* 判据在 `FormRenderer.emptyTextOf` / `emptyCellText`,钉这几条:空着不编话、空着给 ``--``、
* 配了照写、值到让位、等后端算的带出格也不垫小字、画布那一屏仍然看得见这一格带的是什么。
*/
import { describe, expect, it, vi } from 'vitest'
import { flushPromises, mount } from '@vue/test-utils'
import { createPinia, setActivePinia } from 'pinia'
import { createI18n } from 'vue-i18n'
import zh from '@/i18n/locales/zh'
import FormRenderer from './FormRenderer.vue'
import { useAuthStore } from '@/stores/auth'
import type { FormFieldDef, FormSchema, User } from '@/types'
vi.mock('@/api', () => ({
orgAPI: { simpleUnits: vi.fn(async () => []) },
dictAPI: { dictValues: vi.fn(async () => ({})) },
supportAPI: { deleteAttachment: vi.fn(async () => ({})) }
}))
vi.mock('@/api/dataSources', () => ({ fetchValue: vi.fn(async () => { throw new Error('不该取数') }) }))
vi.mock('@/api/quota', () => ({ quotaOptions: vi.fn(async () => []) }))
const i18n = createI18n({ legacy: false, locale: 'zh', messages: { zh }, missingWarn: false, fallbackWarn: false })
async function open(fields: FormFieldDef[], data: Record<string, unknown> = {}, props: Record<string, unknown> = {}) {
const pinia = createPinia()
setActivePinia(pinia)
useAuthStore().$patch({
user: { id: 'u1', account: 'zhangsan', display_name: '张三', organization_name: '软件开发事业部' } as unknown as User,
token: 'token'
} as never)
const schema = { fields, layout: { columns: 12, grid: 12 } } as unknown as FormSchema
const wrapper = mount(FormRenderer, {
props: { schema, modelValue: data, perms: {}, readonly: true, ...props },
global: { plugins: [pinia, i18n] }
})
await flushPromises()
return wrapper.text()
}
/** 单据编号:`serial` 前端算不出来,运行时就是"值还没到"那一档 */
const serial = (extra: Partial<FormFieldDef> = {}): FormFieldDef =>
({ key: 'code', label: '流程编号', type: 'auto', auto: 'serial', row: 1, col: 1, span: 12, ...extra }) as FormFieldDef
describe('值没到之前框里那句话:只认字段上配的,没配就不写', () => {
it('系统带出那格空着时不再自带「提交后由系统自动填写」', async () => {
const text = await open([serial()])
expect(text).toContain('流程编号')
expect(text).not.toContain('提交后由系统自动填写')
expect(text).not.toContain('自动填写')
})
/**
* 空着那一格给的是 ``--``,不是真空。这一条是从上面那条长出来的:把组件编的那句话拿掉之后,
* 系统带出与公式成了屏上唯一会显示成一片空白的格子,而同屏其余空格子都写 ``--``——
* 一片空白让人以为这一格坏掉了,而 ``--`` 只说"这儿还没值",谁都不骗。
*/
it('空着给的是同屏那句空值标记 --,不是真空', async () => {
expect(await open([serial()])).toContain('--')
const amount = { key: 'amount', label: '申请金额', type: 'number', row: 2, col: 1, span: 6 } as FormFieldDef
const total = { key: 'total', label: '含税合计', type: 'formula', formula: "data.get('amount') * 1.06", row: 2, col: 7, span: 6 } as FormFieldDef
expect(await open([amount, total])).toContain('--')
const activity = { key: 'node', label: '当前环节', type: 'auto', auto: 'activityName', row: 4, col: 1, span: 12 } as FormFieldDef
expect(await open([activity])).toContain('--')
})
it('配了那一栏就照写——想要那句说明的人自己写回去,一个字不变', async () => {
expect(await open([serial({ placeholder: '提交后由系统自动填写' })])).toContain('提交后由系统自动填写')
expect(await open([serial({ placeholder: '受理号稍后生成' })])).toContain('受理号稍后生成')
// 配了那句话就不必再写 --
expect(await open([serial({ placeholder: '受理号稍后生成' })])).not.toContain('--')
})
it('值到了,那一句自己让位', async () => {
const text = await open([serial({ placeholder: '提交后由系统自动填写' })], { code: 'CCBAYZJ20261111001' })
expect(text).toContain('CCBAYZJ20261111001')
expect(text).not.toContain('提交后由系统自动填写')
})
it('公式那格同一句:没算出结果时不自带「填写相关字段后自动算出」,配了才写', async () => {
const amount = { key: 'amount', label: '申请金额', type: 'number', row: 2, col: 1, span: 6 } as FormFieldDef
const total = { key: 'total', label: '含税合计', type: 'formula', formula: "data.get('amount') * 1.06", row: 2, col: 7, span: 6 } as FormFieldDef
expect(await open([amount, total])).not.toContain('填写相关字段后自动算出')
// 回看那一屏读的是存下来的那个数:值在,那句话就让位
const archived = await open([amount, { ...total, placeholder: '自动计算' }], { amount: 100, total: 106 })
expect(archived).toContain('106')
expect(archived).not.toContain('自动计算')
// 填写那一屏当场算得出:写的还是算出来的数,不是那句话
const live = await open([amount, { ...total, placeholder: '自动计算' }], { amount: 100 }, { readonly: false })
expect(live).toContain('106')
expect(live).not.toContain('自动计算')
})
it('等后端算的自动带出格(直属上级)也不在框底下垫那句小字', async () => {
const leader = { key: 'leader', label: '直属上级', type: 'user', auto: 'creatorLeader', readonly: true, row: 3, col: 1, span: 12 } as FormFieldDef
const text = await open([leader], {}, { readonly: false })
expect(text).toContain('直属上级')
expect(text).not.toContain('自动填写')
})
it('当前环节名称这类随环节变的值:算得出来写环节名,算不出来不再写「当前环节名称」四个字充数', async () => {
const activity = { key: 'node', label: '当前环节', type: 'auto', auto: 'activityName', row: 4, col: 1, span: 12 } as FormFieldDef
expect(await open([activity], {}, { activityName: '部门主管审批' })).toContain('部门主管审批')
expect(await open([activity])).not.toContain('当前环节名称')
expect(await open([activity], {}, { placeholder: undefined })).not.toContain('当前环节名称')
})
/**
* 画布那一屏不掺这一栏:它答的是"这一格带的是哪个来源",而框里那句话在运行时多半轮不到说话
* (值一到就让位)。配的正文要到「预览」那一屏看——预览走的就是上面这条运行时渲染路径。
*/
it('画布照旧写来源名,配了那句也不去盖它;预览(非 design)那条路才写配的正文', async () => {
const dept = { key: 'apply_part', label: '申请人部门', type: 'auto', auto: 'creatorUnit', row: 1, col: 1, span: 12 } as FormFieldDef
expect(await open([dept], {}, { design: true })).toContain('发起人部门')
expect(await open([{ ...dept, placeholder: '系统带出,不用填' }], {}, { design: true })).toContain('发起人部门')
// 编号那一格前端算不出来,运行时那一屏(也就是设计器的「预览」)写的就是配的正文
const code = { key: 'code2', label: '单据编号', type: 'auto', auto: 'serial', placeholder: '提交后生成', row: 2, col: 1, span: 12 } as FormFieldDef
expect(await open([code], {}, { readonly: false })).toContain('提交后生成')
})
})

View File

@ -0,0 +1,177 @@
// @vitest-environment jsdom
/**
* 「公式带入后允许修改」那一档落到填单那一屏长什么样。
*
* 用户那句原话:**"表单中明细表中引用公式带入的值,为什么不能编辑?我需要可编辑。"**
* 公式列的格子原先是一句文本(`cellFormulaText`),并且每次改动都被 `applyRowFormulas`
* 重算一遍——光给个框没用,敲进去的数会在下一轮重算里被盖掉。所以这一屏要钉的是两件事:
*
* 1. 那一格真是录入框,公式先把数摆在框里;
* 2. 人改过的那一格从此归他:主表那一格再动、下一轮重算都绕着走;清空或点恢复才交回公式。
*
* 没点这一档的列必须保持原样(一句文本、表头一枚锁),否则这一改动就把几百张存量表单的
* 明细表变成了能乱改的计算格。
*/
import { describe, expect, it, vi } from 'vitest'
import { flushPromises, mount } from '@vue/test-utils'
import { createPinia, setActivePinia } from 'pinia'
import { createI18n } from 'vue-i18n'
import zh from '@/i18n/locales/zh'
import FormRenderer from './FormRenderer.vue'
import FormFieldControl from './FormFieldControl.vue'
import { useAuthStore } from '@/stores/auth'
import type { FormFieldDef, FormSchema, User } from '@/types'
vi.mock('@/api', () => ({
orgAPI: { simpleUnits: vi.fn(async () => []) },
dictAPI: { dictValues: vi.fn(async () => ({}) ) },
supportAPI: { deleteAttachment: vi.fn(async () => ({}) ) },
workAPI: {
relationValues: vi.fn(async () => ({ items: [] })),
listRelatedWorks: vi.fn(async () => ({ items: [], total: 0 })),
workSummaries: vi.fn(async () => [])
}
}))
vi.mock('@/api/dataSources', () => ({ fetchValue: vi.fn(async () => { throw new Error('不该取数') }) }))
vi.mock('@/api/quota', () => ({ quotaOptions: vi.fn(async () => []) }))
const i18n = createI18n({ legacy: false, locale: 'zh', messages: { zh }, missingWarn: false, fallbackWarn: false })
/** 收款金额 = 本行数量 × 本行单价 + 主表那个运费。 */
function fieldsOf(editable: boolean | undefined): FormFieldDef[] {
return [
{ key: 'freight', label: '运费', type: 'money', span: 6, row: 1, col: 1 },
{
key: 'detail',
label: '费用明细',
type: 'table',
span: 12,
row: 2,
col: 1,
columns: [
{ key: 'qty', label: '数量', type: 'number' },
{ key: 'price', label: '单价', type: 'number' },
{
key: 'payAmount',
label: '收款金额',
type: 'money',
formula: 'qty * price + freight',
formulaEditable: editable
}
]
}
]
}
const ROWS = [
{ qty: 2, price: 30, payAmount: 60 },
{ qty: 1, price: 10, payAmount: 10 }
]
function schema(fields: FormFieldDef[]): FormSchema {
return { fields, layout: { columns: 12, grid: 12 } } as unknown as FormSchema
}
async function open(editable: boolean | undefined, data: Record<string, unknown>) {
const pinia = createPinia()
setActivePinia(pinia)
useAuthStore().$patch({
user: { id: 'u1', account: 'zhangsan', display_name: '张三' } as unknown as User,
token: 'token'
} as never)
const wrapper = mount(FormRenderer, {
props: { schema: schema(fieldsOf(editable)), modelValue: data },
global: { plugins: [pinia, i18n] }
})
await flushPromises()
return wrapper
}
function lastEmit(wrapper: ReturnType<typeof mount>): Record<string, unknown> {
const list = ((wrapper.emitted('update:modelValue') ?? []) as unknown[][]).map((args) => args[0] as Record<string, unknown>)
return list[list.length - 1] ?? {}
}
function rows(payload: Record<string, unknown>): Record<string, unknown>[] {
return (payload.detail as Record<string, unknown>[]) ?? []
}
function amounts(payload: Record<string, unknown>): unknown[] {
return rows(payload).map((row) => row.payAmount)
}
/** 明细里第一行的收款金额那一格(前两格是勾选框与行号,第三列往后按列序排)。 */
function cellInput(wrapper: Awaited<ReturnType<typeof open>>) {
return wrapper.findAll('tbody tr').at(0)!.findAll('td').at(4)!
}
function cellControl(wrapper: Awaited<ReturnType<typeof open>>) {
return wrapper
.findAllComponents(FormFieldControl)
.filter((item) => item.props('field')?.key === 'payAmount')
.at(0)
}
describe('点了「允许修改」的公式列:那一格是录入框', () => {
it('公式摆在框里,表头给一枚 fx 而不是那枚锁', async () => {
const wrapper = await open(true, { freight: 0, detail: ROWS.map((row) => ({ ...row })) })
const cell = cellInput(wrapper)
expect(cell.find('input').exists()).toBe(true)
expect(cell.find('input').element.getAttribute('value')).not.toBeNull()
const heads = wrapper.findAll('thead th')
expect(heads.at(4)!.find('[data-test="table-column-formula-editable"]').exists()).toBe(true)
expect(heads.at(4)!.find('[data-test="table-column-locked"]').exists()).toBe(false)
})
it('没点这一档:还是那一句文本,表头一枚锁,谁也别想敲', async () => {
const wrapper = await open(undefined, { freight: 0, detail: ROWS.map((row) => ({ ...row })) })
expect(cellInput(wrapper).find('input').exists()).toBe(false)
expect(cellInput(wrapper).text()).toContain('60')
const heads = wrapper.findAll('thead th')
expect(heads.at(4)!.find('[data-test="table-column-locked"]').exists()).toBe(true)
})
})
describe('改过的那一格归人,没动的归公式', () => {
it('敲一个数进去:值与「这一格归我管」那份凭据一起写回', async () => {
const wrapper = await open(true, { freight: 0, detail: ROWS.map((row) => ({ ...row })) })
await cellControl(wrapper)!.vm.$emit('update:value', 888)
await flushPromises()
const payload = lastEmit(wrapper)
expect(amounts(payload)).toEqual([888, 10])
expect(rows(payload)[0]._manual).toEqual(['payAmount'])
expect(rows(payload)[1]._manual).toBeUndefined()
})
it('主表那个运费再动一次:自己改的那一格不动,另一行照旧跟着涨', async () => {
const wrapper = await open(true, { freight: 0, detail: ROWS.map((row) => ({ ...row })) })
await cellControl(wrapper)!.vm.$emit('update:value', 888)
await wrapper.setProps({ modelValue: lastEmit(wrapper) })
await wrapper.setProps({ modelValue: { freight: 100, detail: rows(lastEmit(wrapper)) } })
await flushPromises()
expect(amounts(lastEmit(wrapper))).toEqual([888, 110])
})
it('把那一格清空:凭据跟着撤,公式重新接管', async () => {
const wrapper = await open(true, { freight: 0, detail: ROWS.map((row) => ({ ...row })) })
await cellControl(wrapper)!.vm.$emit('update:value', 888)
await wrapper.setProps({ modelValue: lastEmit(wrapper) })
await cellControl(wrapper)!.vm.$emit('update:value', '')
await flushPromises()
const payload = lastEmit(wrapper)
expect(amounts(payload)).toEqual([60, 10])
expect(rows(payload)[0]._manual).toBeUndefined()
})
it('那颗「恢复公式值」点一下:数回到算出来的那个,凭据也撤掉', async () => {
const wrapper = await open(true, { freight: 0, detail: ROWS.map((row) => ({ ...row })) })
await cellControl(wrapper)!.vm.$emit('update:value', 888)
await wrapper.setProps({ modelValue: lastEmit(wrapper) })
expect(wrapper.find('[data-test="formula-reset-0-payAmount"]').exists()).toBe(true)
await wrapper.find('[data-test="formula-reset-0-payAmount"]').trigger('click')
await flushPromises()
const payload = lastEmit(wrapper)
expect(amounts(payload)).toEqual([60, 10])
expect(rows(payload)[0]._manual).toBeUndefined()
})
})

View File

@ -0,0 +1,213 @@
// @vitest-environment jsdom
/**
* 挑完关联之后,填单页上那一趟即时预览到底问了什么、写回了什么。
*
* 对面是 `backend/app/service/linkfill.py`(提交时服务端按同一份配置重算并覆盖),
* `utils/linkFill.spec.ts` 钉的是那一份算法,这一份钉的是**接上填单页之后**那三件:
*
* 1. **一次问一趟**:这一屏上所有 `pick` 并成一个请求发出去(路径解析只在后端有一份),
* 回体里的值写进主表那一格、并按「一单一行」补出明细的行;
* 2. **只盯关联那串值**:别的格子改一下不重问,多挂一张才再问一趟——否则每敲一个字
* 都要去问一遍那几张单;
* 3. **设计态与只读态不发**:那两屏没有人正在挑关联,问了也没人看。
*/
import { beforeEach, describe, expect, it, vi } from 'vitest'
import { flushPromises, mount } from '@vue/test-utils'
import { createPinia, setActivePinia } from 'pinia'
import { createI18n } from 'vue-i18n'
import zh from '@/i18n/locales/zh'
import FormRenderer from './FormRenderer.vue'
import { workAPI } from '@/api'
import { useAuthStore } from '@/stores/auth'
import type { FormFieldDef, FormSchema, User } from '@/types'
vi.mock('@/api', () => ({
orgAPI: { simpleUnits: vi.fn(async () => []) },
dictAPI: { dictValues: vi.fn(async () => ({})) },
supportAPI: { deleteAttachment: vi.fn(async () => ({})) },
workAPI: {
relationValues: vi.fn(async () => ({ items: [] })),
listRelatedWorks: vi.fn(async () => ({ items: [], total: 0 })),
workSummaries: vi.fn(async () => [])
}
}))
const i18n = createI18n({ legacy: false, locale: 'zh', messages: { zh }, missingWarn: false, fallbackWarn: false })
const RELATION: FormFieldDef = {
key: 'orders',
label: '关联报销单',
type: 'relation',
span: 6,
optionSource: 'process',
linkFill: {
rules: [
{ pick: 'work.serial', to: 'src_serial', agg: 'join' },
{ pick: 'data.amount', to: 'items.amount' }
]
}
}
function schema(fields: FormFieldDef[]): FormSchema {
return { fields, layout: { columns: 12, grid: 12 } } as unknown as FormSchema
}
const FIELDS: FormFieldDef[] = [
RELATION,
{ key: 'src_serial', label: '来源单号', type: 'text', span: 6 },
{ key: 'remark', label: '备注', type: 'text', span: 6 },
{
key: 'items',
label: '明细',
type: 'table',
span: 12,
columns: [{ key: 'amount', label: '金额', type: 'money' }]
}
]
const ITEMS = [
{ job: 'J1', values: { 'work.serial': 'BX-001', 'data.amount': 100 } },
{ job: 'J2', values: { 'work.serial': 'BX-002', 'data.amount': 2300.5 } }
]
async function mountForm(props: Record<string, unknown> = {}, fields: FormFieldDef[] = FIELDS) {
const pinia = createPinia()
setActivePinia(pinia)
useAuthStore().$patch({
user: { id: 'u1', account: 'zhangsan', display_name: '张三', organization_name: '研发中心' } as unknown as User,
token: 'token'
} as never)
const wrapper = mount(FormRenderer, {
props: { schema: schema(fields), modelValue: {}, ...props },
global: { plugins: [pinia, i18n] }
})
await flushPromises()
// 那一趟预览防抖 300ms 才发
await new Promise((resolve) => setTimeout(resolve, 450))
await flushPromises()
return wrapper
}
function relationValues() {
return vi.mocked(workAPI.relationValues)
}
function lastEmit(wrapper: Awaited<ReturnType<typeof mountForm>>) {
return wrapper.emitted('update:modelValue')?.at(-1)?.[0] as Record<string, unknown>
}
beforeEach(() => {
relationValues().mockReset()
// 照着真后端的脾气来:只回这一串值里查得到的那几张,顺序也按关联顺序
relationValues().mockImplementation(async (values: string[]) =>
({ items: ITEMS.filter((item) => values.includes(item.job)) }))
})
/** 照着填单页上那只父组件的样子把上一次写回的值接住,再改一两格传回去。 */
function threaded(wrapper: Awaited<ReturnType<typeof mountForm>>, change: Record<string, unknown>) {
return { ...(lastEmit(wrapper) ?? {}), ...change }
}
describe('挑完关联那一趟预览', () => {
it('这一屏上所有 pick 并成一趟发出去,回的值写进主表那一格并补出明细的行', async () => {
const wrapper = await mountForm({ modelValue: { orders: ['J1', 'J2'] } })
expect(relationValues()).toHaveBeenCalledTimes(1)
// 第三个参数是正在填的那一张单:后端拿它多认一档"确实挂在这一单上"的可见性
expect(relationValues()).toHaveBeenCalledWith(['J1', 'J2'], ['work.serial', 'data.amount'], '')
const written = lastEmit(wrapper)
expect(written.src_serial).toBe('BX-001、BX-002')
expect((written.items as Record<string, unknown>[]).map((row) => row._link)).toEqual(['J1', 'J2'])
expect((written.items as Record<string, unknown>[]).map((row) => row.amount)).toEqual([100, 2300.5])
// 留痕跟着写:提交时后端拿它对「关联变了没有」,界面与引擎认的是同一本账
expect((written._linkfill as Record<string, unknown>).orders).toEqual(['J1', 'J2'])
})
it('那一格存的是单号:回来的账按问出去的那一句认领,明细表照样补行', async () => {
// 费用报销单上「请选择出差备案流程」就是这一档:optionMap.valueKey = serial
const fields = FIELDS.map((field) =>
field.key === 'orders' ? { ...field, optionMap: { labelKey: 'title', valueKey: 'serial' } } : field
)
relationValues().mockImplementation(async (values: string[]) => ({
// 真后端的脾气:按单号也认得那张单,回来的 job 是 job、value 才是问出去的单号
items: ITEMS.map((item) => ({ ...item, value: `BX-00${item.job.slice(1)}` })).filter((item) =>
values.includes(item.value)
)
}))
const wrapper = await mountForm({ modelValue: { orders: ['BX-001', 'BX-002'] } }, fields)
expect(relationValues()).toHaveBeenCalledTimes(1)
expect(relationValues().mock.calls.at(-1)?.[0]).toEqual(['BX-001', 'BX-002'])
const written = lastEmit(wrapper)
expect(written.src_serial).toBe('BX-001、BX-002')
// 行上的来源标记仍是那张单的 job:提交时后端按同一分寸对账
expect((written.items as Record<string, unknown>[]).map((row) => row._link)).toEqual(['J1', 'J2'])
expect((written.items as Record<string, unknown>[]).map((row) => row.amount)).toEqual([100, 2300.5])
})
it('只盯关联那一串值:改别的格子不重问,多挂一张才再问一趟', async () => {
const wrapper = await mountForm({ modelValue: { orders: ['J1'] } })
expect(relationValues()).toHaveBeenCalledTimes(1)
await wrapper.setProps({ modelValue: threaded(wrapper, { remark: '自己写的备注' }) })
await new Promise((resolve) => setTimeout(resolve, 450))
await flushPromises()
expect(relationValues()).toHaveBeenCalledTimes(1)
await wrapper.setProps({ modelValue: threaded(wrapper, { orders: ['J1', 'J2'] }) })
await new Promise((resolve) => setTimeout(resolve, 450))
await flushPromises()
expect(relationValues()).toHaveBeenCalledTimes(2)
expect(relationValues().mock.calls.at(-1)?.[0]).toEqual(['J1', 'J2'])
})
it('取消全部关联时不再去问,界面上那几行与那几个数跟着撤', async () => {
const wrapper = await mountForm({ modelValue: { orders: ['J1'] } })
expect(relationValues()).toHaveBeenCalledTimes(1)
// 人自己加的那一行不是带出生来的,撤带出不能顺手把它一起删掉
await wrapper.setProps({
modelValue: threaded(wrapper, { orders: [], items: [{ amount: 999 }, ...(lastEmit(wrapper).items as object[])] })
})
await new Promise((resolve) => setTimeout(resolve, 450))
await flushPromises()
expect(relationValues()).toHaveBeenCalledTimes(1)
const written = lastEmit(wrapper)
expect(written.src_serial).toBe('')
expect((written.items as Record<string, unknown>[]).map((row) => row._link)).toEqual([undefined])
// 留痕也跟着改成空串那一串,提交时后端认的是同一本账
expect((written._linkfill as Record<string, unknown>).orders).toEqual([])
})
it('没挂任何单时一趟都不问', async () => {
await mountForm({ modelValue: { remark: '还没挑关联' } })
expect(relationValues()).not.toHaveBeenCalled()
})
it('两格关联字段并成一趟问,回来的账各归各的', async () => {
relationValues().mockImplementation(async (values: string[]) => ({
items: [{ job: 'J1', values: { 'work.serial': 'BX-001', 'data.amount': 100 } },
{ job: 'J9', values: { 'work.serial': 'CG-009', 'data.amount': 500 } }].filter((item) =>
values.includes(item.job))
}))
const fields: FormFieldDef[] = [
RELATION,
{ key: 'buys', label: '关联采购单', type: 'relation', span: 6, optionSource: 'process',
linkFill: { rules: [{ pick: 'work.serial', to: 'buy_serial' }] } },
{ key: 'src_serial', label: '来源单号', type: 'text', span: 6 },
{ key: 'buy_serial', label: '采购单号', type: 'text', span: 6 },
{ key: 'items', label: '明细', type: 'table', span: 12,
columns: [{ key: 'amount', label: '金额', type: 'money' }] }
]
const wrapper = await mountForm({ schema: schema(fields), modelValue: { orders: ['J1'], buys: ['J9'] } })
expect(relationValues()).toHaveBeenCalledTimes(1)
expect(relationValues().mock.calls.at(-1)?.[0]).toEqual(['J1', 'J9'])
// 两条 pick 并成一份清单,重复的去掉
expect(relationValues().mock.calls.at(-1)?.[1]).toEqual(['work.serial', 'data.amount'])
const written = lastEmit(wrapper)
expect(written.src_serial).toBe('BX-001')
expect(written.buy_serial).toBe('CG-009')
expect((written.items as Record<string, unknown>[]).map((row) => row._link)).toEqual(['J1'])
})
it('设计态与只读态不发这一趟:那两屏没人正在挑关联', async () => {
await mountForm({ modelValue: { orders: ['J1'] }, design: true })
await mountForm({ modelValue: { orders: ['J1'] }, readonly: true })
expect(relationValues()).not.toHaveBeenCalled()
})
})

View File

@ -0,0 +1,218 @@
// @vitest-environment jsdom
/**
* 渲染那一屏真的按这张单的取值换候选来源(``optionRoutes``)。
*
* 判据在 ``utils/optionSource`` 与 ``utils/formLinkage`` 里都钉过了,这一份要钉的是**界面**:
* 「报销类型是差旅时科目问差旅字典,是招待时只想让人挑两个词」这一类配法,读的就是
* modelValue 里那一格此刻的值,所以驱动那一格一改,候选就得整批换家;三本字典(字段自己那本
* + 路由里那两本)要在同一趟里拉全,否则命中一条才去拉,下拉点开是空的、转一下才有。
* 顺带钉「带出的值不在候选里也收下」在界面上的那副样子:补一行「带出」候选让值站得住。
*/
import { describe, expect, it, vi } from 'vitest'
import { flushPromises, mount } from '@vue/test-utils'
import { createPinia, setActivePinia } from 'pinia'
import { createI18n } from 'vue-i18n'
import zh from '@/i18n/locales/zh'
import FormRenderer from './FormRenderer.vue'
import FormFieldControl from './FormFieldControl.vue'
import { useAuthStore } from '@/stores/auth'
import type { DictMap, FormFieldDef, FormSchema, User } from '@/types'
const DICTS: DictMap = {
acct_common: [
{ value: 'C1', label: '通用科目一' },
{ value: 'C2', label: '通用科目二' }
],
acct_travel: [
{ value: 'T1', label: '火车票' },
{ value: 'T2', label: '住宿费' }
]
}
const dictValues = vi.fn(async (codes: string[]) => {
const out: DictMap = {}
codes.forEach((code) => {
if (DICTS[code]) out[code] = DICTS[code]
})
return out
})
vi.mock('@/api', () => ({
orgAPI: { simpleUnits: vi.fn(async () => []) },
dictAPI: { dictValues: (...args: unknown[]) => dictValues(args[0] as string[]) },
supportAPI: { deleteAttachment: vi.fn(async () => ({})) }
}))
vi.mock('@/api/dataSources', () => ({ fetchValue: vi.fn(async () => { throw new Error('不该取数') }) }))
vi.mock('@/api/quota', () => ({ quotaOptions: vi.fn(async () => []) }))
const i18n = createI18n({ legacy: false, locale: 'zh', messages: { zh }, missingWarn: false, fallbackWarn: false })
const TRAVEL = { match: 'all', rules: [{ field: 'expenseType', op: 'eq', value: 'travel' }] } as never
const MEET = { match: 'all', rules: [{ field: 'expenseType', op: 'eq', value: 'meet' }] } as never
const FIELDS: FormFieldDef[] = [
{
key: 'expenseType',
label: '报销类型',
type: 'select',
options: [
{ value: 'travel', label: '差旅' },
{ value: 'meet', label: '招待' }
],
row: 1,
col: 1,
span: 6
},
{
key: 'expenseItem',
label: '报销科目',
type: 'select',
// 字段自己那一份 = 其余情况的兜底候选
optionSource: 'dict',
dictCode: 'acct_common',
optionRoutes: [
{ source: 'dict', when: TRAVEL, dictCode: 'acct_travel' },
{ source: 'manual', when: MEET, options: [{ value: 'M', label: '自己填一个' }] }
],
row: 1,
col: 2,
span: 6
}
]
function schema(): FormSchema {
return { fields: FIELDS, layout: { columns: 12, grid: 12 } } as unknown as FormSchema
}
async function open(data: Record<string, unknown> = {}, props: Record<string, unknown> = {}) {
const pinia = createPinia()
setActivePinia(pinia)
useAuthStore().$patch({
user: { id: 'u1', account: 'zhangsan', display_name: '张三' } as unknown as User,
token: 'token'
} as never)
const wrapper = mount(FormRenderer, {
props: { schema: schema(), modelValue: data, perms: {}, ...props },
global: { plugins: [pinia, i18n] }
})
await flushPromises()
return wrapper
}
/** 报销科目那一格:控制它的是第二个 FormFieldControl */
function itemControl(wrapper: ReturnType<typeof open> extends never ? never : any) {
return wrapper.findAllComponents(FormFieldControl)[1]
}
const valuesOf = (control: any) => (control.props('options') as { value: string }[]).map((item) => String(item.value))
describe('候选来源跟着这张单的取值换家', () => {
it('命中哪一条就摆哪一家的候选', async () => {
const wrapper = await open({ expenseType: 'travel' })
const control = itemControl(wrapper)
// 传给控件的字段本身也被换成那一条的视图:控件里那一层算标签、判样式都读它
expect(control.props('field').dictCode).toBe('acct_travel')
expect(valuesOf(control)).toEqual(['T1', 'T2'])
})
it('驱动那一格一改,候选整批换家(同一格,不用重挂)', async () => {
const wrapper = await open({ expenseType: 'travel' })
expect(valuesOf(itemControl(wrapper))).toEqual(['T1', 'T2'])
await wrapper.setProps({ modelValue: { expenseType: 'meet', expenseItem: 'T1' } })
await flushPromises()
// 换成手填那一条:上一家的编码不再站着(这一格没勾「带出也收下」)
expect(valuesOf(itemControl(wrapper))).toEqual(['M'])
})
it('一条都不成立时回落到字段自己那一份,与改动前一字不差', async () => {
const wrapper = await open({ expenseType: 'other' })
const control = itemControl(wrapper)
expect(control.props('field').dictCode).toBe('acct_common')
expect(valuesOf(control)).toEqual(['C1', 'C2'])
})
it('路由里那几本字典与字段自己那本一趟拉全,不等命中才去拉', async () => {
dictValues.mockClear()
await open({ expenseType: 'travel' })
const asked = dictValues.mock.calls
.flatMap((call) => call[0] as string[])
.filter((code, index, all) => all.indexOf(code) === index)
.sort()
// 一次问完这两本(命中哪一条才去拉的话,下拉点开是空的、转一下才有)
expect(asked).toEqual(['acct_common', 'acct_travel'])
})
})
describe('带回来的值不在候选里也收下:界面上要念得出来', () => {
const outside = (extra: Partial<FormFieldDef> = {}): FormFieldDef[] => [
{
key: 'level',
label: '职级',
type: 'select',
optionSource: 'manual',
options: [{ value: 'P5', label: 'P5' }],
row: 1,
col: 1,
span: 6,
...extra
} as FormFieldDef
]
it('勾了那一档:候选外的那个值补一行「带出」站着,不再是一片空白', async () => {
const wrapper = mount(FormRenderer, {
props: {
schema: { fields: outside({ allowOutsideValue: true }), layout: { columns: 12, grid: 12 } } as never,
modelValue: { level: 'P9-带出' },
perms: {}
},
global: { plugins: [createPinia(), i18n] }
})
await flushPromises()
const options = wrapper.findAllComponents(FormFieldControl)[0].props('options') as { value: string; label: string }[]
expect(options.map((item) => item.value)).toEqual(['P5', 'P9-带出'])
expect(options[1].label).toContain('带出')
})
it('没勾那一档:不补这一行,值仍由清值那一步收掉(默认关,老表单不变)', async () => {
const wrapper = mount(FormRenderer, {
props: {
schema: { fields: outside(), layout: { columns: 12, grid: 12 } } as never,
modelValue: { level: 'P9-带出' },
perms: {}
},
global: { plugins: [createPinia(), i18n] }
})
await flushPromises()
const options = wrapper.findAllComponents(FormFieldControl)[0].props('options') as { value: string }[]
expect(options.map((item) => item.value)).toEqual(['P5'])
})
it('候选是搜出来的那一家时不插这一行:那两头压根不判越界', async () => {
const wrapper = mount(FormRenderer, {
props: {
schema: {
fields: [
{
key: 'material',
label: '物料',
type: 'picker',
optionSource: 'dataSource',
dataSourceCode: 'erp',
allowOutsideValue: true,
row: 1,
col: 1,
span: 6
} as unknown as FormFieldDef
],
layout: { columns: 12, grid: 12 }
} as never,
modelValue: { material: 'M-001' },
perms: {}
},
global: { plugins: [createPinia(), i18n] }
})
await flushPromises()
const options = wrapper.findAllComponents(FormFieldControl)[0].props('options') as { value: string }[]
expect(options).toEqual([])
})
})

View File

@ -0,0 +1,98 @@
// @vitest-environment jsdom
/**
* 办结之后回看那一屏(只读渲染)摆哪几格。
*
* 生产上 `出差备案申请` 那一单:八格项目 / 客户 / 阶段全勾了「默认隐藏」、又全按「项目分类」
* 配了「显示条件」。办理那一屏跟着条件露得好好的,办结之后再打开就是一句"字段没了"——
* 回看渲染那句 `props.readonly ? null : model.value` 承认自己算不了条件,可那份值就躺在
* `modelValue` 里。这一份钉的是修完之后那一屏的四种下场,与
* `utils/formRuntime.hidden.spec.ts`(判据本体)、`mobileLayout.spec.ts`(手机上那一屏)
* 对上同一句话:回看屏只往宽放,凭存过的值把「默认隐藏 + 显示条件」那一组摆回来,
* 不拿条件去收已经存了值的格子。
*/
import { describe, expect, it, vi } from 'vitest'
import { flushPromises, mount } from '@vue/test-utils'
import { createPinia, setActivePinia } from 'pinia'
import { createI18n } from 'vue-i18n'
import zh from '@/i18n/locales/zh'
import FormRenderer from './FormRenderer.vue'
import { useAuthStore } from '@/stores/auth'
import type { FormFieldDef, FormSchema, User } from '@/types'
vi.mock('@/api', () => ({
orgAPI: { simpleUnits: vi.fn(async () => []) },
dictAPI: { dictValues: vi.fn(async () => ({})) },
supportAPI: { deleteAttachment: vi.fn(async () => ({})) }
}))
vi.mock('@/api/dataSources', () => ({ fetchValue: vi.fn(async () => { throw new Error('不该取数') }) }))
vi.mock('@/api/quota', () => ({ quotaOptions: vi.fn(async () => []) }))
const i18n = createI18n({ legacy: false, locale: 'zh', messages: { zh }, missingWarn: false, fallbackWarn: false })
/** 按「项目分类」放行:这就是那八格的配法 */
const whenType = (value: string) => ({ rules: [{ field: 'project_type', op: 'eq', value }] })
const FIELDS: FormFieldDef[] = [
{ key: 'reason', label: '出差事由', type: 'textarea', row: 1, col: 1, span: 12 },
{ key: 'project_type', label: '项目分类', type: 'select', row: 2, col: 1, span: 6 },
{ key: 'project_pms', label: 'PMS项目名称', type: 'select', hidden: true, visibleWhen: whenType('PMS'), row: 3, col: 1, span: 6 },
{ key: 'project_scc', label: 'VDI项目名称', type: 'select', hidden: true, visibleWhen: whenType('VDI'), row: 3, col: 7, span: 6 },
{ key: 'area_cf', label: '出发地', type: 'text', row: 4, col: 1, span: 6 },
{ key: 'project_xz', label: '行政项目名称', type: 'text', hidden: true, row: 4, col: 7, span: 6 }
]
function schema(): FormSchema {
return { fields: FIELDS, layout: { columns: 12, grid: 12 } }
}
async function open(data: Record<string, unknown>, props: Record<string, unknown> = {}) {
const pinia = createPinia()
setActivePinia(pinia)
useAuthStore().$patch({
user: { id: 'u1', account: 'zhangsan', display_name: '张三' } as unknown as User,
token: 'token'
} as never)
const wrapper = mount(FormRenderer, {
props: { schema: schema(), modelValue: data, perms: {}, ...props },
global: { plugins: [pinia, i18n] }
})
await flushPromises()
return wrapper.text()
}
/** 单子办结时存下来的那一份:项目分类是 PMS,四个项目的值都带过 */
const PMS = { reason: '客户巡访', project_type: 'PMS', project_pms: '智慧园区', project_scc: 'SCC-01', area_cf: '北京', project_xz: '行政A' }
describe('办结回看那一屏:条件把「默认隐藏 + 显示条件」那一组放回来', () => {
it('条件成立的那一格摆出来,隔壁条件不成立的那一格仍旧不露', async () => {
const text = await open(PMS, { readonly: true })
expect(text).toContain('PMS项目名称')
expect(text).toContain('智慧园区')
expect(text).not.toContain('VDI项目名称')
})
it('没配条件的「默认隐藏」一个字都不改:值存着也不上这一屏', async () => {
expect(await open(PMS, { readonly: true })).not.toContain('行政项目名称')
})
it('已经存了值的条件格不凭条件收:回看屏讲的是"存过的都摊开"', async () => {
// 出发地没配条件,照旧摊开;把项目分类改走,PMS 那一格按默认隐藏那一寸退回不露
const flipped = await open({ ...PMS, project_type: 'VDI' }, { readonly: true })
expect(flipped).toContain('出发地')
expect(flipped).not.toContain('PMS项目名称')
expect(flipped).toContain('VDI项目名称')
})
it('环节明着要回去的那一格,条件翻走了也摊开(与从前那句保守口径同寸)', async () => {
const text = await open({ ...PMS, project_type: 'VDI' }, { readonly: true, perms: { project_pms: 'readonly' } })
expect(text).toContain('PMS项目名称')
// 而环节明写隐藏是最高优先级:条件成立也不给看
expect(await open(PMS, { readonly: true, perms: { project_pms: 'hidden' } })).not.toContain('PMS项目名称')
})
it('办理那一屏走的是另一句判据:联动往严收,两屏各说各的话', async () => {
// 能改值的这一屏:条件不成立就不摆,跟回看屏只放行不一样
expect(await open({ ...PMS, project_type: 'VDI' })).not.toContain('PMS项目名称')
expect(await open(PMS)).toContain('PMS项目名称')
})
})

View File

@ -0,0 +1,162 @@
// @vitest-environment jsdom
/**
* 明细列的逐行取数:填单页上那一趟即时带出,到底是不是**每行各问一次、各写各行**。
*
* 配的是最真实的那张单:收款明细里「开户银行 / 银行帐号」按本行的收款人去 ERP 查。
* 对面是后端 `service/fetch.py::_apply_rows`(提交时逐行重取并覆盖),这两份必须问同一个
* 问题、拿同一个答案。钉这六件:逐行各发一次、各写各行、带出落在同一行的另一列、
* 同名列以本行为准、主表那一格一个都不许被盖、冻结那一档照旧管得住明细行。
*/
import { beforeEach, describe, expect, it, vi } from 'vitest'
import { flushPromises, mount } from '@vue/test-utils'
import { createPinia, setActivePinia } from 'pinia'
import { createI18n } from 'vue-i18n'
import zh from '@/i18n/locales/zh'
import FormRenderer from './FormRenderer.vue'
import { fetchValue } from '@/api/dataSources'
import { useAuthStore } from '@/stores/auth'
import type { FormSchema, User } from '@/types'
vi.mock('@/api', () => ({
orgAPI: { simpleUnits: vi.fn(async () => []) },
dictAPI: { dictValues: vi.fn(async () => ({})) },
supportAPI: { deleteAttachment: vi.fn(async () => ({})) }
}))
vi.mock('@/api/dataSources', () => ({
fetchValue: vi.fn(async () => ({ ok: true, value: '', extras: {}, ms: 5 })),
quotaOptions: vi.fn(async () => [])
}))
const i18n = createI18n({ legacy: false, locale: 'zh', messages: { zh }, missingWarn: false, fallbackWarn: false })
/** 一行收款明细:收款人 + 开户行 + 银行帐号(后两格由取数写)。 */
function row(payee: string) {
return { payee, bankName: '', bankAccount: '' }
}
function columns() {
return [
{ key: 'payee', label: '收款人', type: 'text' },
{ key: 'bankName', label: '开户银行', type: 'text' },
{
key: 'bankAccount',
label: '银行帐号',
type: 'text',
fetch: {
source: 'erp_bank',
args: { account: '{form.payee}' },
picks: { bank: 'bankName' },
onError: 'keep'
}
}
] as Record<string, unknown>[]
}
function schema(cols: Record<string, unknown>[] = columns()) {
return {
fields: [
{ key: 'payee', label: '报销人', type: 'text', span: 6 },
{
key: 'items',
label: '收款明细',
type: 'table',
span: 12,
columns: cols
}
],
layout: { columns: 12, grid: 12 }
} as unknown as FormSchema
}
async function fill(modelValue: Record<string, unknown>, props: Record<string, unknown> = {}, cols?: Record<string, unknown>[]) {
const pinia = createPinia()
setActivePinia(pinia)
useAuthStore().$patch({
user: { id: 'u1', account: 'zhangsan', display_name: '张三', organization_name: '研发中心' } as unknown as User,
token: 'token'
} as never)
const wrapper = mount(FormRenderer, {
props: { schema: schema(cols), modelValue, ...props },
global: { plugins: [pinia, i18n] }
})
await flushPromises()
// 面板上那次带出是防抖 400ms 之后才发的
await new Promise((resolve) => setTimeout(resolve, 600))
await flushPromises()
return wrapper
}
/** 最后一次写出去的那份数据里的明细行。 */
function rowsOf(wrapper: Awaited<ReturnType<typeof fill>>) {
const written = wrapper.emitted('update:modelValue')?.at(-1)?.[0] as Record<string, unknown>
return (written.items ?? []) as Record<string, unknown>[]
}
beforeEach(() => {
vi.mocked(fetchValue).mockReset()
vi.mocked(fetchValue).mockImplementation(async (_code: string, args: Record<string, unknown>) => ({
ok: true,
value: `账号-${args.account}`,
extras: { bank: `开户行-${args.account}` },
ms: 5
}))
})
describe('明细列的逐行取数', () => {
it('两行各发一次,问的是本行的收款人,值各写各的那一行', async () => {
const wrapper = await fill({
payee: '报销人',
items: [row('zhangsan'), row('lisi')]
})
expect(vi.mocked(fetchValue).mock.calls.map((call) => (call[1] as Record<string, unknown>).account)).toEqual([
'zhangsan',
'lisi'
])
const rows = rowsOf(wrapper)
expect(rows[0]).toMatchObject({ bankAccount: '账号-zhangsan', bankName: '开户行-zhangsan' })
expect(rows[1]).toMatchObject({ bankAccount: '账号-lisi', bankName: '开户行-lisi' })
wrapper.unmount()
})
it('与主表同名的那一列以本行为准,主表那一格一个都不许被盖', async () => {
const wrapper = await fill({ payee: '表头的报销人', items: [row('zhangsan')] })
expect(vi.mocked(fetchValue).mock.calls[0]?.[1]).toEqual({ account: 'zhangsan' })
const written = wrapper.emitted('update:modelValue')?.at(-1)?.[0] as Record<string, unknown>
expect(written.payee).toBe('表头的报销人')
wrapper.unmount()
})
it('本行没填收款人时读主表那一格(按单号、按部门查那一类入参本来就长在表头)', async () => {
const wrapper = await fill({ payee: 'zhangsan', items: [{ bankName: '', bankAccount: '' }] })
expect(vi.mocked(fetchValue).mock.calls[0]?.[1]).toEqual({ account: 'zhangsan' })
expect(rowsOf(wrapper)[0]).toMatchObject({ bankAccount: '账号-zhangsan' })
wrapper.unmount()
})
it('入参一格都算不出来时不发这一趟(等一等,不拿空值去问上游)', async () => {
const wrapper = await fill({ payee: '', items: [{ bankName: '', bankAccount: '' }] })
expect(fetchValue).not.toHaveBeenCalled()
expect(wrapper.emitted('update:modelValue')).toBeUndefined()
wrapper.unmount()
})
it('整张明细表没有一行:一次都不外呼', async () => {
const wrapper = await fill({ payee: 'zhangsan', items: [] })
expect(fetchValue).not.toHaveBeenCalled()
wrapper.unmount()
})
it('勾了「流程发起后冻结」的列,进了办理环节一次都不外呼', async () => {
const cols = columns()
cols[2].fetch = { ...(cols[2].fetch as object), freezeAfterStart: true }
const wrapper = await fill({ payee: 'zhangsan', items: [row('zhangsan')] }, { atStart: false }, cols)
expect(fetchValue).not.toHaveBeenCalled()
wrapper.unmount()
})
it('回看与办理那一屏(只读)不外呼,明细列与主表那一格同一分寸', async () => {
const wrapper = await fill({ payee: 'zhangsan', items: [row('zhangsan')] }, { readonly: true })
expect(fetchValue).not.toHaveBeenCalled()
wrapper.unmount()
})
})

View File

@ -0,0 +1,190 @@
// @vitest-environment jsdom
/**
* 明细表「本行公式」吃得到主表字段之后,填单那一屏的实时性。
*
* 这一列的数只有前端会算,所以主表那一格(手填的、公式算的、外部带回来的)一变,
* 明细里那些算出来的格子必须跟着变——不跟着变就是屏幕上摆着一个旧数字骗人。
* 反过来也一样要紧:算完跟原来一样就别写回,否则一次改动触发一轮又一轮,
* 配歪成环的那两张表能把页面拖进没完没了的更新里。
*/
import { describe, expect, it, vi } from 'vitest'
import { flushPromises, mount } from '@vue/test-utils'
import { createPinia, setActivePinia } from 'pinia'
import { createI18n } from 'vue-i18n'
import zh from '@/i18n/locales/zh'
import FormRenderer from './FormRenderer.vue'
import FormFieldControl from './FormFieldControl.vue'
import { useAuthStore } from '@/stores/auth'
import type { FormFieldDef, FormSchema, User } from '@/types'
vi.mock('@/api', () => ({
orgAPI: { simpleUnits: vi.fn(async () => []) },
dictAPI: { dictValues: vi.fn(async () => ({}) ) },
supportAPI: { deleteAttachment: vi.fn(async () => ({}) ) },
workAPI: {
relationValues: vi.fn(async () => ({ items: [] })),
listRelatedWorks: vi.fn(async () => ({ items: [], total: 0 })),
workSummaries: vi.fn(async () => [])
}
}))
vi.mock('@/api/dataSources', () => ({ fetchValue: vi.fn(async () => { throw new Error('不该取数') }) }))
vi.mock('@/api/quota', () => ({ quotaOptions: vi.fn(async () => []) }))
const i18n = createI18n({ legacy: false, locale: 'zh', messages: { zh }, missingWarn: false, fallbackWarn: false })
/** 收款金额 = 本行数量 × 本行单价 + 主表那个运费。 */
const FIELDS: FormFieldDef[] = [
{ key: 'freight', label: '运费', type: 'money', span: 6, row: 1, col: 1 },
{
key: 'detail',
label: '费用明细',
type: 'table',
span: 12,
row: 2,
col: 1,
columns: [
{ key: 'qty', label: '数量', type: 'number' },
{ key: 'price', label: '单价', type: 'number' },
{ key: 'payAmount', label: '收款金额', type: 'money', formula: 'qty * price + freight' }
]
}
]
const ROWS = [
{ qty: 2, price: 30, payAmount: 60 },
{ qty: 1, price: 10, payAmount: 10 }
]
function schema(fields: FormFieldDef[]): FormSchema {
return { fields, layout: { columns: 12, grid: 12 } } as unknown as FormSchema
}
async function open(
fields: FormFieldDef[],
data: Record<string, unknown>,
extra: Record<string, unknown> = {}
) {
const pinia = createPinia()
setActivePinia(pinia)
useAuthStore().$patch({
user: { id: 'u1', account: 'zhangsan', display_name: '张三' } as unknown as User,
token: 'token'
} as never)
const wrapper = mount(FormRenderer, {
props: { schema: schema(fields), modelValue: data, ...extra },
global: { plugins: [pinia, i18n] }
})
await flushPromises()
return wrapper
}
function emits(wrapper: ReturnType<typeof mount>): Record<string, unknown>[] {
return ((wrapper.emitted('update:modelValue') ?? []) as unknown[][]).map((args) => args[0] as Record<string, unknown>)
}
function lastEmit(wrapper: ReturnType<typeof mount>): Record<string, unknown> {
const list = emits(wrapper)
return list[list.length - 1] ?? {}
}
function amounts(payload: Record<string, unknown>): unknown[] {
return (payload.detail as Record<string, unknown>[]).map((row) => row.payAmount)
}
/** 明细第一行的第几列那一格(前两格是勾选框与行号)。 */
function cellInput(wrapper: ReturnType<typeof mount>, column: number) {
return wrapper.findAll('tbody tr').at(0)!.findAll('td').at(2 + column)!.find('input')
}
function control(wrapper: ReturnType<typeof mount>, key: string) {
return wrapper.findAllComponents(FormFieldControl).find((item) => item.props('field')?.key === key)
}
describe('本行公式跟着主表那一格实时变', () => {
it('打开一张算好的单子,一个字都不许替人改', async () => {
const wrapper = await open(FIELDS, { freight: 0, detail: ROWS.map((row) => ({ ...row })) })
expect(emits(wrapper)).toEqual([])
})
it('主表那一格换了(父组件直接换整份数据:公式、带回、别人系统回填都走这条路):明细整表重算', async () => {
const wrapper = await open(FIELDS, { freight: 0, detail: ROWS.map((row) => ({ ...row })) })
await wrapper.setProps({ modelValue: { freight: 100, detail: ROWS.map((row) => ({ ...row })) } })
await flushPromises()
expect(amounts(lastEmit(wrapper))).toEqual([160, 110])
})
it('在运费那一格里改数字:明细跟着变,不用回明细再动一次格子', async () => {
const wrapper = await open(FIELDS, { freight: 0, detail: ROWS.map((row) => ({ ...row })) })
await control(wrapper, 'freight')!.vm.$emit('update:value', 50)
await wrapper.setProps({ modelValue: lastEmit(wrapper) })
await flushPromises()
expect(amounts(lastEmit(wrapper))).toEqual([110, 60])
})
it('改明细本行的数量:按最新的主表值算,老写法照常', async () => {
const wrapper = await open(FIELDS, { freight: 5, detail: ROWS.map((row) => ({ ...row })) })
await cellInput(wrapper, 0)!.setValue('3')
const next = lastEmit(wrapper)
expect((next.detail as Record<string, unknown>[])[0].qty).toBe(3)
expect(amounts(next)).toEqual([95, 15])
})
it('主表那一格还空着:直接取它的那一列留空,屏幕上不摆一个假的 0', async () => {
const copy: FormFieldDef[] = [
FIELDS[0],
{
...FIELDS[1],
columns: [
{ key: 'qty', label: '数量', type: 'number' },
{ key: 'payAmount', label: '收款金额', type: 'money', formula: 'freight' }
]
}
]
const rows = [{ qty: 1, payAmount: 5 }, { qty: 2, payAmount: 5 }]
const wrapper = await open(copy, { freight: 5, detail: rows })
await wrapper.setProps({ modelValue: { freight: '', detail: rows } })
await flushPromises()
// 主表空着就留空,别在只读格子里摆一个没人填过的 0。
expect(amounts(lastEmit(wrapper))).toEqual(['', ''])
})
it('只读回看那一屏不替人改数据', async () => {
const wrapper = await open(FIELDS, { freight: 0, detail: ROWS.map((row) => ({ ...row })) }, { readonly: true })
await wrapper.setProps({ modelValue: { freight: 100, detail: ROWS.map((row) => ({ ...row })) } })
await flushPromises()
expect(emits(wrapper)).toEqual([])
})
it('配成环(本行公式取主表公式字段、那个公式字段又合计这一列)也不会没完没了', async () => {
const cyclic: FormFieldDef[] = [
{ key: 'freight', label: '合计', type: 'formula', formula: "total(detail, 'payAmount')", span: 6, row: 1, col: 1 },
{
key: 'detail',
label: '费用明细',
type: 'table',
span: 12,
row: 2,
col: 1,
columns: [
{ key: 'qty', label: '数量', type: 'number' },
{ key: 'payAmount', label: '收款金额', type: 'money', formula: 'freight' }
]
}
]
const wrapper = await open(cyclic, { freight: 5, detail: [{ qty: 1, payAmount: 5 }] })
/** 扮演一个立刻把组件写回的数据当 props 传回来的父组件:环就在这个来回里转。 */
async function push(data: Record<string, unknown>) {
await wrapper.setProps({ modelValue: data })
await flushPromises()
return lastEmit(wrapper)
}
let payload = { freight: 7, detail: [{ qty: 1, payAmount: 5 }] }
for (let round = 0; round < 16; round += 1) payload = await push(payload)
const settled = emits(wrapper).length
expect(settled).toBeGreaterThan(0)
expect(settled).toBeLessThan(24)
for (let round = 0; round < 6; round += 1) await push(payload)
// 追到轮数上限就停下来,之后一个字都不再动。
expect(emits(wrapper).length).toBe(settled)
})
})

View File

@ -0,0 +1,116 @@
// @vitest-environment jsdom
/**
* 渲染那一屏真的跟着「自己这一格的值」一起露和藏。
*
* 判据在 ``utils/formLinkage`` 与 ``utils/formRuntime`` 里都钉过了,这一份要钉的是**界面**:
* 「外部带回来的合同编号有值才露这一格」这一类条件,读的就是 modelValue 里那一格此刻的
* 值,所以带出把值写进来的那一刻,格子得自己冒出来;反过来回看那一屏(只读渲染)按存过的
* 那份值评条件,存过就摊开。这两条都是以前没有的能力——清单里压根挑不到自己。
*/
import { describe, expect, it, vi } from 'vitest'
import { flushPromises, mount } from '@vue/test-utils'
import { createPinia, setActivePinia } from 'pinia'
import { createI18n } from 'vue-i18n'
import zh from '@/i18n/locales/zh'
import FormRenderer from './FormRenderer.vue'
import { useAuthStore } from '@/stores/auth'
import type { FormFieldDef, FormSchema, User } from '@/types'
vi.mock('@/api', () => ({
orgAPI: { simpleUnits: vi.fn(async () => []) },
dictAPI: { dictValues: vi.fn(async () => ({})) },
supportAPI: { deleteAttachment: vi.fn(async () => ({})) }
}))
vi.mock('@/api/dataSources', () => ({ fetchValue: vi.fn(async () => { throw new Error('不该取数') }) }))
vi.mock('@/api/quota', () => ({ quotaOptions: vi.fn(async () => []) }))
const i18n = createI18n({ legacy: false, locale: 'zh', messages: { zh }, missingWarn: false, fallbackWarn: false })
/** 「本字段有值才显示」:用户要的那一句 */
const whenOwnValue: FormFieldDef['visibleWhen'] = { rules: [{ field: 'contractNo', op: 'notEmpty' }] }
const FIELDS: FormFieldDef[] = [
{ key: 'reason', label: '申请事由', type: 'textarea', row: 1, col: 1, span: 12 },
{ key: 'contractNo', label: '合同编号', type: 'text', row: 2, col: 1, span: 6, visibleWhen: whenOwnValue },
{ key: 'contractNote', label: '合同说明', type: 'text', row: 3, col: 1, span: 6, visibleWhen: whenOwnValue, required: true },
// 带回来越多越好、平时不露的那一类:默认隐藏 + 判自己有没有值
{
key: 'contractArchive',
label: '合同扫描件',
type: 'attachment',
hidden: true,
visibleWhen: { rules: [{ field: 'contractArchive', op: 'notEmpty' }] },
row: 4,
col: 1,
span: 6
}
]
function schema(): FormSchema {
return { fields: FIELDS, layout: { columns: 12, grid: 12 } }
}
async function render(data: Record<string, unknown>, props: Record<string, unknown> = {}) {
const pinia = createPinia()
setActivePinia(pinia)
useAuthStore().$patch({
user: { id: 'u1', account: 'zhangsan', display_name: '张三' } as unknown as User,
token: 'token'
} as never)
return mount(FormRenderer, {
props: { schema: schema(), modelValue: data, perms: {}, ...props },
global: { plugins: [pinia, i18n] }
})
}
describe('这一格按自己的值露不露', () => {
it('还没值就不露,值一写进来它自己冒出来', async () => {
const wrapper = await render({ reason: '采购' })
await flushPromises()
expect(wrapper.text()).not.toContain('合同编号')
expect(wrapper.text()).not.toContain('合同说明')
await wrapper.setProps({ modelValue: { reason: '采购', contractNo: 'HT-2026-011' } })
await flushPromises()
expect(wrapper.text()).toContain('合同编号')
expect(wrapper.text()).toContain('合同说明')
})
it('藏起来的格子不参与必填:没带回来时不向人要这一笔', async () => {
const wrapper = await render({ reason: '采购' })
await flushPromises()
expect(wrapper.text()).not.toContain('合同说明')
// 值带回来了,那一格才露出来,必填的星号跟着一起到
await wrapper.setProps({ modelValue: { reason: '采购', contractNo: 'HT-2026-011' } })
await flushPromises()
expect(wrapper.text()).toContain('合同说明')
})
/**
* 回看那一屏按存过的那份值评条件,只多收一种:**条件不成立且这一格本来就空着**。
* 有值的一律摊开——条件翻走了不代表那一笔没填过,收起来等于让存过的东西凭空消失。
* 只敲了空格算没值,两边一把尺子(后端 dicts._is_empty)。勾没勾「默认隐藏」都走这一句。
*/
it('回看那一屏按存过的值评:有值摊开,空着且条件不成立才收', async () => {
const stored = await render({ reason: '采购', contractNo: 'HT-2026-011' }, { readonly: true })
await flushPromises()
expect(stored.text()).toContain('合同编号')
// 只敲了几个空格=没值,那一行既不适用这一单又空着,回看页不再摆它
const blank = await render({ reason: '采购', contractNo: ' ' }, { readonly: true })
await flushPromises()
expect(blank.text()).not.toContain('合同编号')
const withArchive = (value: string) => ({ reason: '采购', contractArchive: value })
const filled = await render(withArchive('a.pdf'), { readonly: true })
await flushPromises()
expect(filled.text()).toContain('合同扫描件')
const empty = await render(withArchive(' '), { readonly: true })
await flushPromises()
expect(empty.text()).not.toContain('合同扫描件')
})
it('环节明写隐藏仍然最高:自引用那句放不开环节锁死的格子', async () => {
const wrapper = await render({ reason: '采购', contractNo: 'HT-2026-011' }, { perms: { contractNo: 'hidden' } })
await flushPromises()
expect(wrapper.text()).not.toContain('合同编号')
})
})

View File

@ -0,0 +1,91 @@
// @vitest-environment jsdom
/**
* 明细表里锁着的那一列,在填单那一屏长什么样。
*
* 设计器配的是列上那份 `readonly`(明细列属性面板上那颗「只读」开关),这一份钉的是它落到
* 填单页之后的三件看得见的坏处:
*
* 1. 那一格还是能敲字的录入框 → 人改了、提交时被后端按台账或带出盖回去,白改一趟;
* 2. 锁着与能填的两列长得一模一样 → 只能一格格试点才知道,界面上没有一句话;
* 3. 锁着的列还挂着必填那颗红星 → 屏幕上催他填一格根本填不动的格子。
*/
import { describe, expect, it, vi } from 'vitest'
import { flushPromises, mount } from '@vue/test-utils'
import { createPinia, setActivePinia } from 'pinia'
import { createI18n } from 'vue-i18n'
import zh from '@/i18n/locales/zh'
import FormRenderer from './FormRenderer.vue'
import { useAuthStore } from '@/stores/auth'
import type { FormFieldDef, FormSchema, User } from '@/types'
vi.mock('@/api', () => ({
orgAPI: { simpleUnits: vi.fn(async () => []) },
dictAPI: { dictValues: vi.fn(async () => ({})) },
supportAPI: { deleteAttachment: vi.fn(async () => ({})) },
workAPI: {
relationValues: vi.fn(async () => ({ items: [] })),
listRelatedWorks: vi.fn(async () => ({ items: [], total: 0 })),
workSummaries: vi.fn(async () => [])
}
}))
const i18n = createI18n({ legacy: false, locale: 'zh', messages: { zh }, missingWarn: false, fallbackWarn: false })
const TABLE: FormFieldDef = {
key: 'items',
label: '明细',
type: 'table',
span: 12,
columns: [
{ key: 'note', label: '事由', type: 'text', required: true },
{ key: 'src', label: '来源', type: 'text', required: true, readonly: true }
]
}
function schema(fields: FormFieldDef[]): FormSchema {
return { fields, layout: { columns: 12, grid: 12 } } as unknown as FormSchema
}
async function mountForm(model: Record<string, unknown>) {
const pinia = createPinia()
setActivePinia(pinia)
useAuthStore().$patch({
user: { id: 'u1', account: 'zhangsan', display_name: '张三' } as unknown as User,
token: 'token'
} as never)
const wrapper = mount(FormRenderer, {
props: { schema: schema([TABLE]), modelValue: model },
global: { plugins: [pinia, i18n] }
})
await flushPromises()
return wrapper
}
/** 明细第一行的那些格子:前两格是勾选框与行号,往后按列序排。 */
function cells(wrapper: Awaited<ReturnType<typeof mountForm>>) {
return wrapper.findAll('tbody tr').at(0)!.findAll('td')
}
describe('明细表里锁着的那一列', () => {
it('那一格不再是录入框,表头给一句"锁着"的说法;能填的那一列照旧', async () => {
const wrapper = await mountForm({ items: [{ note: '', src: '系统带出' }] })
const row = cells(wrapper)
expect(row.at(2)!.find('input').exists()).toBe(true)
expect(row.at(3)!.find('input').exists()).toBe(false)
expect(row.at(3)!.text()).toContain('系统带出')
const heads = wrapper.findAll('thead th')
expect(heads.at(2)!.find('[data-test="table-column-locked"]').exists()).toBe(false)
expect(heads.at(3)!.find('[data-test="table-column-locked"]').exists()).toBe(true)
expect(heads.at(3)!.find('[data-test="table-column-locked"]').attributes('title')).toContain('锁着')
// 一行里既能填又不能填的格子挨着摆,锁着的那一列铺一层底色,扫一眼就知道哪几格点得动
expect(row.at(2)!.classes()).not.toContain('bg-gray-50/70')
expect(row.at(3)!.classes()).toContain('bg-gray-50/70')
})
it('锁着的列不挂必填那颗红星:后端那一列也不卡必填', async () => {
const wrapper = await mountForm({ items: [{ note: '', src: '系统带出' }] })
const row = cells(wrapper)
expect(row.at(2)!.text()).toContain('*')
expect(row.at(3)!.text()).not.toContain('*')
})
})

View File

@ -0,0 +1,186 @@
// @vitest-environment jsdom
/**
* 明细列那几样新配置落到填单与看单那一屏之后,人看见的是什么。
*
* 对面是设计器(`FieldInspector` 列卡里「更多配置」那一栏)与后端
* (`service/formruntime.py`:藏着的列不卡必填)。这一份钉的是渲染那三件:
*
* 1. 藏起来的那一列连表头都不出现,屏幕上数不出它,值却还在(不丢、不挡提交);
* 2. 列宽与对齐按列上的写法走,看单那一屏跟填单那一屏同一张表;
* 3. 合计只念点了名的那几列,数字照列自己的格式写,一格没填也不骗人说"合计 0";
* 4. 最多一行的那张表进来就有那一行,不用先点一下「+」。
*/
import { describe, expect, it, vi } from 'vitest'
import { flushPromises, mount } from '@vue/test-utils'
import { createPinia, setActivePinia } from 'pinia'
import { createI18n } from 'vue-i18n'
import zh from '@/i18n/locales/zh'
import FormRenderer from './FormRenderer.vue'
import { useAuthStore } from '@/stores/auth'
import type { FormFieldDef, FormSchema, User } from '@/types'
vi.mock('@/api', () => ({
orgAPI: { simpleUnits: vi.fn(async () => []) },
dictAPI: { dictValues: vi.fn(async () => ({})) },
supportAPI: { deleteAttachment: vi.fn(async () => ({})) },
workAPI: {
relationValues: vi.fn(async () => ({ items: [] })),
listRelatedWorks: vi.fn(async () => ({ items: [], total: 0 })),
workSummaries: vi.fn(async () => [])
}
}))
const i18n = createI18n({ legacy: false, locale: 'zh', messages: { zh }, missingWarn: false, fallbackWarn: false })
function schema(fields: FormFieldDef[]): FormSchema {
return { fields, layout: { columns: 12, grid: 12 } } as unknown as FormSchema
}
async function mountForm(fields: FormFieldDef[], model: Record<string, unknown>, extra: Record<string, unknown> = {}) {
const pinia = createPinia()
setActivePinia(pinia)
useAuthStore().$patch({
user: { id: 'u1', account: 'zhangsan', display_name: '张三' } as unknown as User,
token: 'token'
} as never)
const wrapper = mount(FormRenderer, {
props: { schema: schema(fields), modelValue: model, ...extra },
global: { plugins: [pinia, i18n] }
})
await flushPromises()
return wrapper
}
const TABLE: FormFieldDef = {
key: 'items',
label: '明细',
type: 'table',
columns: [
{ key: 'note', label: '事由', type: 'text', help: '按发票上的项目写' },
{ key: 'qty', label: '数量', type: 'number', width: 96, align: 'right', aggregate: 'sum' },
{ key: 'code', label: '物料编码', type: 'text', hidden: true }
]
}
describe('明细列在表格上的摆法', () => {
it('藏着的那一列整列不出现:表头、格子、空态那行的跨度都不算它', async () => {
const wrapper = await mountForm([TABLE], { items: [{ note: '打车', qty: 2, code: 'M-1' }] })
const heads = wrapper.findAll('[data-test="table-rows"] thead th, table thead th').map((node) => node.text())
expect(heads.join('|')).toContain('事由')
expect(heads.join('|')).not.toContain('物料编码')
expect(wrapper.html()).not.toContain('M-1')
// 值没丢:藏在 model 里,提交照样带着走
expect((wrapper.emitted('update:modelValue') ?? []).length).toBeGreaterThanOrEqual(0)
})
it('列说明挂在表头那枚提示上,不占格子的高度', async () => {
const wrapper = await mountForm([TABLE], { items: [{ note: '打车' }] })
const help = wrapper.find('[data-test="table-column-help"]')
expect(help.exists()).toBe(true)
expect(help.attributes('title')).toBe('按发票上的项目写')
})
it('列宽与对齐按列上的写法落到 th / td 上', async () => {
const wrapper = await mountForm([TABLE], { items: [{ note: '打车', qty: 2 }] })
const head = wrapper.findAll('thead th').find((node) => node.text().includes('数量'))
// 96 是列上点的那一档;表头那行字比它窄,所以底宽就是 96
expect(head!.attributes('style')).toContain('min-width: 96px')
expect(head!.classes()).toContain('text-right')
// 前两格是勾选框与行号;第三格是「事由」,第四格才是「数量」——藏着的那一列压根没摆出来
const cells = wrapper.findAll('tbody tr').at(0)!.findAll('td')
expect(cells).toHaveLength(4)
expect(cells[3]!.classes()).toContain('text-right')
})
it('只念点了合计的那一列,数字照列自己的格式写', async () => {
const wrapper = await mountForm([TABLE], {
items: [
{ note: 'a', qty: 2 },
{ note: 'b', qty: 10.5 }
]
})
const foot = wrapper.findAll('[data-test="table-aggregate"]')
expect(foot).toHaveLength(1)
expect(foot[0].text()).toContain('合计')
expect(foot[0].text()).toContain('12.5')
})
it('一格都没填时不摆那行数字:念「合计」的列空着,说了反而骗人', async () => {
const wrapper = await mountForm([TABLE], { items: [{ note: 'a', qty: '' }] })
expect(wrapper.find('[data-test="table-aggregate"]').exists()).toBe(true)
expect(wrapper.find('[data-test="table-aggregate"]').text()).toContain('0')
})
it('看单那一屏(只读)跟填单是同一张表:藏的不出现,合计照样念', async () => {
const wrapper = await mountForm(
[{ ...TABLE, readonlyStyle: 'collapsed' }],
{ items: [{ note: 'a', qty: 2, code: 'M-1' }, { note: 'b', qty: 3, code: 'M-2' }] },
{ readonly: true }
)
expect(wrapper.html()).not.toContain('物料编码')
expect(wrapper.find('[data-test="table-fold"]').text()).toContain('数量')
expect(wrapper.find('[data-test="table-fold"]').text()).toContain('5')
await wrapper.find('[data-test="table-fold"]').trigger('click')
expect(wrapper.findAll('[data-test="table-aggregate"]')).toHaveLength(1)
})
it('段头那句「合计」跟着点了求和的那一列走,不再念第一个数值列', async () => {
const field: FormFieldDef = {
key: 'items',
label: '明细',
type: 'table',
readonlyStyle: 'collapsed',
columns: [
{ key: 'qty', label: '数量', type: 'number' },
{ key: 'fee', label: '运费', type: 'money', aggregate: 'sum' }
]
}
const wrapper = await mountForm([field], { items: [{ qty: 7, fee: 2 }, { qty: 1, fee: 3 }] }, { readonly: true })
const fold = wrapper.find('[data-test="table-fold"]').text()
expect(fold).toContain('运费')
expect(fold).toContain('5')
expect(fold).not.toContain('8')
})
})
describe('最多一行的明细表先把那一行摆好', () => {
it('进这一屏就有一行可填,不必先点「+」', async () => {
const one = { ...TABLE, maxRows: 1 }
const wrapper = await mountForm([one], {})
const emitted = wrapper.emitted('update:modelValue')
expect(emitted).toBeTruthy()
const next = emitted!.at(-1)![0] as Record<string, unknown>
expect(Array.isArray(next.items)).toBe(true)
expect((next.items as unknown[]).length).toBe(1)
expect(wrapper.findAll('tbody tr').length).toBeGreaterThan(0)
})
it('补出来的那一行与点「+」同源:默认值与自动带出的列照样落', async () => {
const one: FormFieldDef = {
key: 'one',
label: '抬头',
type: 'table',
maxRows: 1,
columns: [{ key: 'unit', label: '部门', type: 'text', auto: 'creatorUnit', readonly: true }]
}
const wrapper = await mountForm([one], {})
const next = wrapper.emitted('update:modelValue')!.at(-1)![0] as Record<string, Record<string, unknown>[]>
expect(next.one[0]).toHaveProperty('unit')
})
it('只有一行这件事不该发生在改不动的那一屏:只读态与环节锁着的表都不补', async () => {
const one = { ...TABLE, maxRows: 1 }
const readonlyView = await mountForm([one], {}, { readonly: true })
expect(readonlyView.emitted('update:modelValue')).toBeUndefined()
const lockedView = await mountForm([one], {}, { perms: { items: 'readonly' } })
expect(lockedView.emitted('update:modelValue')).toBeUndefined()
})
it('已经有行的表不多补,多行的表也不管', async () => {
const one = { ...TABLE, maxRows: 1 }
const filled = await mountForm([one], { items: [{ note: '打车', qty: 1 }] })
expect(filled.emitted('update:modelValue')).toBeUndefined()
const many = await mountForm([TABLE], {})
expect(many.emitted('update:modelValue')).toBeUndefined()
})
})

View File

@ -0,0 +1,119 @@
// @vitest-environment jsdom
/**
* 明细表在流程提交之后(只读那一屏)先摊开还是先收折。
*
* 用户的原话是「明细表填写的时候是展开状态,流程提交后希望都是收折的,给个地方能配置」。
* 这一份钉的是配了之后到底落在哪几屏、没配的单子凭什么不变:
*
* 1. 存量表单没写 `readonlyStyle` → 只读那一屏跟以前一样整张摊开,连段头都不多摆一行;
* 2. 配了 `collapsed` → 先给一行段头(共几行、合计多少),点一下才摊开,再点收回;
* 3. 填单那一屏永远摊开:收着的表没有录入框,人没法往里敲字;
* 4. 打印那一份永远摊开:纸上没有"点一下"这回事,收着的那些行等于根本没印出来。
*/
import { describe, expect, it, vi } from 'vitest'
import { flushPromises, mount } from '@vue/test-utils'
import { createPinia, setActivePinia } from 'pinia'
import { createI18n } from 'vue-i18n'
import zh from '@/i18n/locales/zh'
import FormRenderer from './FormRenderer.vue'
import { useAuthStore } from '@/stores/auth'
import type { FormFieldDef, FormSchema, User } from '@/types'
vi.mock('@/api', () => ({
orgAPI: { simpleUnits: vi.fn(async () => []) },
dictAPI: { dictValues: vi.fn(async () => ({})) },
supportAPI: { deleteAttachment: vi.fn(async () => ({})) },
workAPI: {
relationValues: vi.fn(async () => ({ items: [] })),
listRelatedWorks: vi.fn(async () => ({ items: [], total: 0 })),
workSummaries: vi.fn(async () => [])
}
}))
const i18n = createI18n({ legacy: false, locale: 'zh', messages: { zh }, missingWarn: false, fallbackWarn: false })
function tableField(readonlyStyle?: FormFieldDef['readonlyStyle']): FormFieldDef {
return {
key: 'items',
label: '明细',
type: 'table',
span: 12,
...(readonlyStyle ? { readonlyStyle } : {}),
columns: [
{ key: 'note', label: '事由', type: 'text' },
{ key: 'amount', label: '金额', type: 'money' }
]
}
}
const ROWS = [
{ note: '打车', amount: 30 },
{ note: '住宿', amount: 400 },
{ note: '餐费', amount: 120 }
]
function schema(field: FormFieldDef): FormSchema {
return { fields: [field], layout: { columns: 12, grid: 12 } } as unknown as FormSchema
}
async function mountForm(field: FormFieldDef, props: Record<string, unknown> = {}) {
const pinia = createPinia()
setActivePinia(pinia)
useAuthStore().$patch({
user: { id: 'u1', account: 'zhangsan', display_name: '张三' } as unknown as User,
token: 'token'
} as never)
const wrapper = mount(FormRenderer, {
props: { schema: schema(field), modelValue: { items: ROWS }, readonly: true, ...props },
global: { plugins: [pinia, i18n] }
})
await flushPromises()
return wrapper
}
/** 只读那一屏的行数区(v-show 收着时它带 display:none)。 */
const rowsArea = (wrapper: Awaited<ReturnType<typeof mountForm>>) => wrapper.find('[data-test="table-rows"]')
const foldBar = (wrapper: Awaited<ReturnType<typeof mountForm>>) => wrapper.find('[data-test="table-fold"]')
describe('明细表在只读那一屏的开合', () => {
it('没配过的明细表照旧整张摊开,不多摆一行段头', async () => {
const wrapper = await mountForm(tableField())
expect(foldBar(wrapper).exists()).toBe(false)
expect(rowsArea(wrapper).attributes('style') ?? '').not.toContain('display: none')
expect(wrapper.findAll('tbody tr')).toHaveLength(ROWS.length)
})
it('配了提交后收折:先给一行「共 N 行 · 合计」,点一下才摊开', async () => {
const wrapper = await mountForm(tableField('collapsed'))
const bar = foldBar(wrapper)
expect(bar.exists()).toBe(true)
expect(bar.attributes('aria-expanded')).toBe('false')
expect(bar.text()).toContain('共 3 行')
// 收着的时候审批人也要看得见合计,不然这一档就变成"想看总数得先点开"
expect(bar.text()).toContain('550')
expect(rowsArea(wrapper).attributes('style')).toContain('display: none')
await bar.trigger('click')
expect(foldBar(wrapper).attributes('aria-expanded')).toBe('true')
expect(rowsArea(wrapper).attributes('style') ?? '').not.toContain('display: none')
expect(wrapper.findAll('tbody tr')).toHaveLength(ROWS.length)
await foldBar(wrapper).trigger('click')
expect(rowsArea(wrapper).attributes('style')).toContain('display: none')
})
it('填单那一屏永远摊开:收折那一档不给录入框消失的机会', async () => {
const wrapper = await mountForm(tableField('collapsed'), { readonly: false })
expect(foldBar(wrapper).exists()).toBe(false)
expect(wrapper.find('[data-test="table-add-row"]').exists()).toBe(true)
// 三行明细各有一个事由录入框,一张都没被收掉
expect(wrapper.findAll('tbody tr')).toHaveLength(ROWS.length)
})
it('打印那一份配了收折也全摊开:纸上没有"点一下摊开"这回事', async () => {
const wrapper = await mountForm(tableField('collapsed'), { flattenTabs: true })
expect(foldBar(wrapper).exists()).toBe(false)
expect(rowsArea(wrapper).attributes('style') ?? '').not.toContain('display: none')
expect(wrapper.findAll('tbody tr')).toHaveLength(ROWS.length)
})
})

File diff suppressed because it is too large Load Diff

View File

@ -136,11 +136,61 @@
<p class="input-label">{{ t('monitor.intervene.moveTarget') }}</p>
<Select v-model="moveTarget" :options="activityOptions" :placeholder="t('monitor.intervene.moveTarget')" />
</div>
<!-- 会跟着一起被搬走的东西先摆出来:子流程那张子单上的待办改道管不着,
第三方停在半路的表态改道会作废,已经推出去的消息收不回来。 -->
<div
v-if="blockers && blockers.children.length"
class="rounded-xl border border-red-200 bg-red-50 px-3 py-2.5 dark:border-red-900/50 dark:bg-red-900/20"
>
<p class="flex items-start gap-1.5 text-xs leading-relaxed text-red-700 dark:text-red-200">
<Icon name="exclamationTriangle" class="mt-0.5 h-3.5 w-3.5 flex-shrink-0" />
<span>{{ t('monitor.intervene.moveChildren', { count: blockers.children.length }) }}</span>
</p>
<ul class="mt-1.5 space-y-1 pl-5">
<li v-for="child in blockers.children" :key="child.job" class="text-xs text-red-700/90 dark:text-red-200/90">
<span class="truncate">{{ child.title }}</span>
<span v-if="child.serial"> · {{ child.serial }}</span>
<span v-if="child.activity_name">
→ {{ t('monitor.intervene.moveChildAt', {
activity: child.activity_name,
holders: (child.holders || []).join('、') || '-'
}) }}
</span>
</li>
</ul>
<label class="mt-2 flex items-center gap-2 text-xs text-red-700 dark:text-red-200">
<input v-model="cascadeChildren" type="checkbox" class="h-3.5 w-3.5 rounded" />
{{ t('monitor.intervene.moveCascade') }}
</label>
</div>
<p
v-if="blockers && blockers.staged_decisions.length"
class="rounded-xl bg-gray-50 px-3 py-2 text-xs leading-relaxed text-gray-600 dark:bg-dark-800/60 dark:text-dark-300"
>
{{ t('monitor.intervene.moveStaged', { count: blockers.staged_decisions.length }) }}
</p>
<p v-if="pending.length" class="text-xs leading-relaxed text-gray-500 dark:text-dark-400">
{{ t('monitor.intervene.moveOutbound', { count: pending.length, persons: personCount }) }}
</p>
<!-- 落点把表态交给了外部系统:改过去之后 OA 侧不会有同意按钮,先说一句。 -->
<p
v-if="targetLock"
class="rounded-xl bg-gray-50 px-3 py-2 text-xs leading-relaxed text-gray-600 dark:bg-dark-800/60 dark:text-dark-300"
>
{{ t('monitor.intervene.moveExternal', { text: targetLock.text }) }}
</p>
<div>
<p class="input-label">{{ t('monitor.intervene.reason') }}</p>
<TextArea v-model="reason" :rows="2" :placeholder="t('monitor.intervene.reasonPlaceholder')" />
</div>
<button type="button" class="btn btn-primary btn-sm" :disabled="!running || !moveTarget || busy" @click="doMove">
<button
type="button"
class="btn btn-primary btn-sm"
:disabled="!running || !moveTarget || busy || blockedByChildren"
@click="doMove"
>
<Icon name="shuffle" class="mr-1 h-4 w-4" />{{ t('monitor.intervene.moveConfirm') }}
</button>
</div>
@ -262,6 +312,7 @@ import PeoplePicker from '@/components/oa/PeoplePicker.vue'
import FormRenderer from '@/components/oa/FormRenderer.vue'
import { taskAPI, workAPI } from '@/api'
import type { TaskItem, WorkDetail } from '@/types'
import type { RerouteBlockers } from '@/api/work'
import { formatDateTimeToMinute } from '@/utils/format'
import { badgeClass, runAction, workStatusLabel, workStatusVariant } from '@/utils/oa'
import { personText } from '@/utils/personLabel'
@ -282,6 +333,10 @@ const picked = ref<string[]>([])
/** 正在给谁换人:某条待办的 id,或 :data:`ALL` 表示整单。 */
const picker = ref('')
const moveTarget = ref('')
/** 改道预检:在跑的嵌入子流程与停在半路的第三方表态(只在面板打开时问一次) */
const blockers = ref<RerouteBlockers | null>(null)
/** 子单还在跑时管理员点的头:勾了这一并终止,不勾引擎停手 */
const cascadeChildren = ref(false)
const draft = ref<Record<string, unknown>>({})
const terminateOpen = ref(false)
/** 改完表单之后标题会换成哪一句;口径在后端 titles.preview_refresh,与保存时引擎算的是同一段。 */
@ -291,6 +346,14 @@ let titleToken = 0
const running = computed(() => detail.value?.status === 'running')
const pending = computed<TaskItem[]>(() => detail.value?.tasks ?? [])
const personCount = computed(() => new Set(pending.value.map((item) => item.identity)).size)
const blockedByChildren = computed(
() => Boolean(blockers.value?.children.length) && !cascadeChildren.value
)
/** 落点那一环开了外部审批:那一环的表态在外部系统里发生,OA 侧点不到同意那颗钮。 */
const targetLock = computed(() => {
const lock = detail.value?.activity_nodes?.[moveTarget.value]?.oa_lock
return lock?.locked ? lock : null
})
/** 只有「要人办」的环节落得下去:判断、汇聚、延时、结束那些由引擎自己走。 */
const activityOptions = computed(() =>
@ -367,6 +430,10 @@ async function reload() {
if (value && !activityOptions.value.some((item) => item.value === moveTarget.value)) {
moveTarget.value = value.activity
}
// 预检问不到不该挡住干预本身:拿不到就当没有子单,真动手时引擎那句会拦住
blockers.value = value && value.status === 'running'
? await workAPI.adminRerouteBlockers(props.job).catch(() => null)
: null
}
watch(
@ -380,9 +447,12 @@ watch(
terminateOpen.value = false
titleToken++
titleNext.value = ''
blockers.value = null
cascadeChildren.value = false
return
}
moveTarget.value = ''
cascadeChildren.value = false
reload()
},
{ immediate: true }
@ -469,7 +539,13 @@ watch(draft, () => askTitleNext())
function doMove() {
const target = activityOptions.value.find((item) => item.value === moveTarget.value)
act(
() => workAPI.adminMove(props.job, moveTarget.value, note(t('monitor.intervene.moveDefault'))),
() =>
workAPI.adminMove(
props.job,
moveTarget.value,
note(t('monitor.intervene.moveDefault')),
cascadeChildren.value
),
t('monitor.intervene.moveDone', { name: target?.label ?? '' })
)
}

View File

@ -205,8 +205,8 @@ interface Item {
interface Props {
modelValue: string
placeholder?: string
/** 写进 oa_attachment.type,说明这条附件是随批注还是随审批意见发出去的 */
purpose?: 'comment' | 'opinion'
/** 写进 oa_attachment.type,说明这条附件是随批注、审批意见还是处理意见发出去的 */
purpose?: 'comment' | 'opinion' | 'read'
busy?: boolean
disabled?: boolean
error?: string

View File

@ -10,6 +10,7 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'
import { flushPromises, mount } from '@vue/test-utils'
import { createPinia, setActivePinia } from 'pinia'
import { createI18n } from 'vue-i18n'
import { createMemoryHistory, createRouter } from 'vue-router'
import zh from '@/i18n/locales/zh'
import OptionPicker from './OptionPicker.vue'
import Select from '@/components/common/Select.vue'
@ -29,12 +30,12 @@ const DIALOG_STUB = {
template: '<div v-if="show" class="dialog-stub"><slot /><slot name="footer" /></div>'
}
function mountPicker(props: Record<string, unknown>) {
function mountPicker(props: Record<string, unknown>, extraPlugins: unknown[] = []) {
const i18n = createI18n({ legacy: false, locale: 'zh', messages: { zh } })
return mount(OptionPicker, {
props: props as never,
global: {
plugins: [i18n],
plugins: [i18n, ...(extraPlugins as never[])],
stubs: { BaseDialog: DIALOG_STUB, SearchInput: true }
}
})
@ -391,6 +392,55 @@ describe('显示哪一列、存哪一列', () => {
})
})
describe('来源=流程单据:候选只列哪几种状态的单据', () => {
it('默认只问归档通过的:半路被终止的单子不再混进「关联已审批流程」里', async () => {
mountPicker({ source: 'process', style: 'dialog', multiple: true })
await flushPromises()
expect(api.listRelatedWorks).toHaveBeenCalledWith(expect.objectContaining({ status: 'completed' }))
})
it('这一格放宽到在办,就问那两档;三档全勾等于不限', async () => {
mountPicker({ source: 'process', style: 'dialog', statuses: ['completed', 'running'] })
await flushPromises()
expect(api.listRelatedWorks).toHaveBeenCalledWith(expect.objectContaining({ status: 'completed,running' }))
api.listRelatedWorks.mockClear()
mountPicker({ source: 'process', style: 'dialog', statuses: ['completed', 'running', 'closed'] })
await flushPromises()
expect(api.listRelatedWorks).toHaveBeenCalledWith(expect.objectContaining({ status: 'completed,running,closed' }))
})
it('弹窗里写清这一格只列哪几档;三档全勾就不啰嗦这一句', async () => {
const narrow = mountPicker({ source: 'process', style: 'dialog', multiple: true })
await flushPromises()
await narrow.get('[data-test="option-picker-trigger"]').trigger('click')
expect(narrow.get('[data-test="picker-scope-note"]').text()).toContain('这一格只列已办结归档的单据')
const open = mountPicker({ source: 'process', style: 'dialog', statuses: ['completed', 'running', 'closed'] })
await flushPromises()
await open.get('[data-test="option-picker-trigger"]').trigger('click')
expect(open.find('[data-test="picker-scope-note"]').exists()).toBe(false)
})
it('换了能挂的档位就重捞一页,不把上一档的候选留在屏上', async () => {
const wrapper = mountPicker({ source: 'process', style: 'dialog', multiple: true })
await flushPromises()
expect(api.listRelatedWorks).toHaveBeenCalledTimes(1)
await wrapper.setProps({ statuses: ['running'] })
await flushPromises()
expect(api.listRelatedWorks).toHaveBeenLastCalledWith(expect.objectContaining({ status: 'running' }))
})
it('已选中的单据不看这一档:回显照旧按 job 问摘要,念得出「已终止」那一档', async () => {
api.workSummaries.mockResolvedValue([{ job: 'J9', title: '被终止的报销单', status: 'terminated' }])
const wrapper = mountPicker({ source: 'process', style: 'dialog', multiple: true, modelValue: ['J9'] })
await flushPromises()
expect(api.workSummaries).toHaveBeenCalledWith(['J9'])
expect(wrapper.get('.field-trigger').text()).toContain('被终止的报销单')
})
})
describe('各档看哪几列 + 弹出框搜索', () => {
it('下拉里只写名称,弹出框里多写「编码 · 规格」——存的值一个字节都不变', async () => {
const options = [
@ -490,4 +540,122 @@ describe('各档看哪几列 + 弹出框搜索', () => {
await titled.find('[data-test="option-picker-trigger"]').trigger('click')
expect(titled.findComponent(DIALOG_STUB).props('title')).toBe('从 ERP 挑一件')
})
})
})
describe('关联的单据点得开', () => {
/** 「关联已审批流程」存了两条时的摘要回显。 */
const summaries = [
{ job: 'J1', title: '出差备案申请', serial: 'CCBAYZJ20261104000002', process_name: '出差备案流程', creator_person: '佟鑫', status: 'approving' },
{ job: 'J2', title: '差旅费报销', serial: 'FYBX202611040003', process_name: '费用报销流程', creator_person: '张锦杰', status: 'finished' }
]
it('只读那一排:每条名字都是指向 /work/:job 的链接,开在新标签页', async () => {
api.workSummaries.mockResolvedValue(summaries)
const wrapper = mountPicker({ source: 'process', modelValue: ['J1', 'J2'], disabled: true })
await flushPromises()
const links = wrapper.findAll('[data-test="relation-open"]')
expect(links.map((node) => node.attributes('href'))).toEqual(['/work/J1', '/work/J2'])
expect(links[0].attributes('target')).toBe('_blank')
expect(links[0].text()).toBe('出差备案申请')
// 单据那一类的牌子收一号字(关联组件里标题太长,默认字号两三个就占满一行)
expect(wrapper.get('.picker-dense').exists()).toBe(true)
})
it('只读单选:那一句话一样点得开,多条时逐句分开、不是一整段死文字', async () => {
api.workSummaries.mockResolvedValue(summaries)
const single = mountPicker({ source: 'process', modelValue: 'J2', disabled: true })
await flushPromises()
expect(single.get('[data-test="relation-open"]').attributes('href')).toBe('/work/J2')
const many = mountPicker({ source: 'process', modelValue: ['J1', 'J2'], disabled: true, multiple: false })
await flushPromises()
expect(many.findAll('[data-test="relation-open"]')).toHaveLength(2)
expect(many.text()).toContain('、')
})
it('编辑态弹出框:挂在框里的标签点名字开单,点别处仍是重开挑选', async () => {
api.workSummaries.mockResolvedValue(summaries)
const wrapper = mountPicker({ source: 'process', style: 'dialog', multiple: true, modelValue: ['J1'] })
await flushPromises()
const link = wrapper.get('[data-test="combo-tag-link"]')
expect(link.attributes('href')).toBe('/work/J1')
expect(link.text()).toBe('出差备案申请')
await link.trigger('click')
// 名字那一下不该顺手把挑选弹窗也打开
expect(wrapper.find('.dialog-stub').exists()).toBe(false)
await wrapper.get('[data-test="option-picker-trigger"]').trigger('click')
expect(wrapper.find('.dialog-stub').exists()).toBe(true)
})
it('编辑态下拉:候选带上落点,框里那颗标签点得开', async () => {
api.workSummaries.mockResolvedValue(summaries)
const open = vi.spyOn(window, 'open').mockImplementation(() => null)
const wrapper = mountPicker({ source: 'process', style: 'dropdown', multiple: true, modelValue: ['J1', 'J2'] })
await flushPromises()
expect(wrapper.findComponent(Select).props('known')).toEqual([
{ value: 'J1', label: '出差备案申请', href: '/work/J1' },
{ value: 'J2', label: '差旅费报销', href: '/work/J2' }
])
const chips = wrapper.findAll('[data-test="select-chip-link"]')
expect(chips.map((node) => node.text())).toEqual(['出差备案申请', '差旅费报销'])
await chips[1].trigger('click')
expect(open).toHaveBeenCalledWith('/work/J2', '_blank', 'noopener')
open.mockRestore()
})
it('改存了单号:链接仍落在那张单的 job 上,认不出来时宁差不给地址', async () => {
// 这一格的候选里搜得到 YZ2026-001 那张(beforeEach 那一页),所以翻得回 J1
const known = mountPicker({
source: 'process',
style: 'dialog',
modelValue: ['YZ2026-001'],
optionMap: { valueKey: 'serial', labelKey: 'title' },
disabled: true
})
await flushPromises()
expect(known.get('[data-test="relation-open"]').attributes('href')).toBe('/work/J1')
// 翻不回 job 就别点:一个开不去的链接比一句念得出单号的死文字更坑人
api.workSummaries.mockResolvedValue([])
const unknown = mountPicker({
source: 'process',
modelValue: ['YZ-没见过的'],
optionMap: { valueKey: 'serial', labelKey: 'title' },
disabled: true
})
await flushPromises()
expect(unknown.findAll('a')).toHaveLength(0)
expect(unknown.text()).toContain('YZ-没见过的')
})
it('别的来源没有单据可开:字典与外部数据源一个链接都不给', async () => {
const dict = mountPicker({
source: 'dict',
modelValue: ['a'],
options: [{ value: 'a', label: '甲' }],
disabled: true
})
expect(dict.findAll('a')).toHaveLength(0)
// 不收字号:那两排的牌子还跟着人员选择器、附件一个长相
expect(dict.find('.picker-dense').exists()).toBe(false)
const remote = mountPicker({ source: 'dataSource', modelValue: ['M1'], disabled: true })
await flushPromises()
expect(remote.findAll('a')).toHaveLength(0)
})
it('挂了 router 时按路由名解析:将来 /work/:job 改了路径也点得开', async () => {
const router = createRouter({
history: createMemoryHistory(),
routes: [
{ path: '/work/:job', name: 'work-detail', component: { render: () => null } },
{ path: '/:pathMatch(.*)*', component: { render: () => null } }
]
})
api.workSummaries.mockResolvedValue([summaries[0]])
const wrapper = mountPicker({ source: 'process', modelValue: ['J1'], disabled: true }, [router])
await flushPromises()
expect(wrapper.get('[data-test="relation-open"]').attributes('href')).toBe('/work/J1')
})
})

View File

@ -1,14 +1,44 @@
<template>
<!-- 只读态:一串值念成标签牌,单个值念成一句话 -->
<div v-if="disabled" class="min-w-0">
<!--
只读态:一串值念成标签牌,单个值念成一句话。
来源是流程单据时这两个名字都点得开——挑中一张单之后想看那张单,是本字段最常见的一下点击,
以前只能记住单号再去列表里搜。开在新标签页,看完整张单退回来,手上填的这一张还在。
-->
<div v-if="disabled" class="min-w-0" :class="dense && 'picker-dense'">
<div v-if="multiple && picked.length" class="flex flex-wrap gap-1.5">
<span v-for="item in picked" :key="item.value" class="field-tag">
<Icon :name="rowIcon" class="h-3.5 w-3.5 flex-shrink-0" />
<span class="truncate">{{ item.title || item.value }}</span>
<a
v-if="item.href"
:href="item.href"
target="_blank"
rel="noopener"
class="truncate hover:underline"
:title="openWorkHint"
data-test="relation-open"
@click.stop
>
{{ item.title || item.value }}
</a>
<span v-else class="truncate">{{ item.title || item.value }}</span>
</span>
</div>
<span v-else-if="picked.length" class="break-words">
{{ picked.map((item) => item.title || item.value).join('、') }}
<template v-for="(item, index) in picked" :key="item.value">
<span v-if="index">、</span>
<a
v-if="item.href"
:href="item.href"
target="_blank"
rel="noopener"
class="hover:underline"
:title="openWorkHint"
data-test="relation-open"
>
{{ item.title || item.value }}
</a>
<span v-else>{{ item.title || item.value }}</span>
</template>
</span>
<span v-else class="text-gray-400">--</span>
</div>
@ -54,9 +84,27 @@
:remote="searchable"
:loading="loading"
:empty-text="emptyText"
:link-title="multiple ? openWorkHint : ''"
:class="dense && 'picker-dense'"
data-test="option-picker-select"
@update:model-value="emitValue(toArray($event))"
@search="onRemoteSearch"
/>
>
<!-- 单选那一格框里就一句话,点它就是点那张单;多选那一排点在各自的标签上 -->
<template v-if="singleWorkHref" #selected>
<a
:href="singleWorkHref"
target="_blank"
rel="noopener"
class="truncate hover:underline"
:title="openWorkHint"
data-test="relation-open"
@click.stop
>
{{ picked[0]?.title || text }}
</a>
</template>
</Select>
<!--
弹出框:框本身仍是那只输入框(点开之后才有搜索与副标题那一套)。
@ -66,7 +114,10 @@
<template v-else>
<ComboTrigger
data-test="option-picker-trigger"
:class="dense && 'picker-dense'"
:text="multiple ? '' : picked[0]?.title ?? ''"
:text-href="singleWorkHref"
:text-link-title="openWorkHint"
:items="multiple ? pickedTags : []"
:multiple="multiple"
:placeholder="placeholder || pickLabel"
@ -82,6 +133,7 @@
<BaseDialog :show="show" :title="dialogTitle" @close="show = false">
<div class="space-y-3">
<SearchInput v-if="hasSearch" v-model="keyword" :placeholder="searchHint" @search="reload" />
<p v-if="scopeNote" class="text-xs text-gray-400 dark:text-dark-500" data-test="picker-scope-note">{{ scopeNote }}</p>
<!--
多选那一排交代「勾了几条」,顺手给两只手:候选是搜出来的,手上永远只有这一页,
跨页挑的人得看得见自己已经勾到第几条,也不必一条一条点完这一屏。
@ -180,8 +232,9 @@
* 手填与字典那两条路的候选由调用方给(联动过滤后的那一份),映射也在那一头就投影好了;
* 这一层只投影自己捞的那两条(单据、外部数据源),免得同一份映射套两遍。
*/
import { computed, ref, watch } from 'vue'
import { computed, inject, ref, watch } from 'vue'
import { useI18n } from 'vue-i18n'
import { routerKey } from 'vue-router'
import BaseDialog from '@/components/common/BaseDialog.vue'
import SearchInput from '@/components/common/SearchInput.vue'
import Select from '@/components/common/Select.vue'
@ -192,6 +245,7 @@ import type { WorkSummary } from '@/api/work'
import { extraNotes, useDataSourceOptions } from '@/composables/useDataSourceOptions'
import { bindingArgsKey, resolveBindingArgs } from '@/utils/binding'
import { runAction, workStatusLabel } from '@/utils/oa'
import { RELATION_STATUSES, RELATION_STATUS_DEFAULT, RELATION_STATUS_LABEL_KEYS } from '@/utils/optionSource'
import {
DEFAULT_VALUE_KEYS,
applyOptionMapOf,
@ -215,6 +269,8 @@ interface PickRow {
/** 那行小字:单据是「单号 · 流程 · 发起人」,外部数据源是多带出来的那几个键 */
note: string
badge: string
/** 这个名字点得开的那个地址:只有「来源=流程单据」且认得出是哪张单时才有 */
href: string
}
/**
@ -238,6 +294,11 @@ const props = withDefaults(
options?: Option[]
/** 来源=流程单据:只允许挂某个流程的单子时传流程 id */
process?: string
/**
* 来源=流程单据:候选只列这几档状态的单据(归档通过 / 还在办 / 已终止或作废)。
* 默认只给归档通过的——「关联已审批流程」挑到一张半路被终止的单子是常见的坑。
*/
statuses?: string[]
/** 来源=外部数据源:列表型源的 code */
sourceCode?: string
/** 来源=外部数据源:还要按哪些字段筛(`{form.x}` 那一份写法) */
@ -261,6 +322,7 @@ const props = withDefaults(
multiple: false,
options: () => [],
process: '',
statuses: () => [...RELATION_STATUS_DEFAULT],
sourceCode: '',
sourceArgs: undefined,
formData: undefined,
@ -276,6 +338,9 @@ const props = withDefaults(
const emit = defineEmits<{ 'update:modelValue': [value: string[] | string | null] }>()
const { t } = useI18n()
// 没挂 router 的场合(组件单测、内嵌预览)取到 null,workHref 那一步退回路径写法。
// 不用 useRouter():它不带默认值,注入不到时会在控制台留一条 warning。
const router = inject(routerKey, null)
const localOptions = computed<Option[]>(() => props.options ?? [])
@ -327,6 +392,28 @@ const searchHint = computed(() =>
: t('common.searchPlaceholder')
)
const rowIcon = computed(() => (props.source === 'process' ? 'document' : 'list'))
/** 悬停那句话:说清楚这一点开的是新标签页,手上正填的这一张不会丢。 */
const openWorkHint = computed(() => t('form.relationOpenWork'))
/**
* 单据那一类的牌子收一号字。
*
* 一张单的标题动辄「某某某发起的某某流程」再加单号、流程名、发起人,默认的 `.field-tag`
* 在窄格子里两三个就把整行占满,还挤掉了同排别的格子。只收这一只组件里的牌子——
* 全局那条 `.field-tag` 人员选择器与附件还要用它的本来样子。
*/
const dense = computed(() => props.source === 'process')
/**
* 单据落在哪一页:`/work/:job`(见 router/index.ts 的 `work-detail`)。
*
* PC 与手机共用这一条——WorkDetailView 自己按设备换成手机版那一屏,所以一个地址两头点得开。
* 按路由名解析,将来路径改了不用回来改这里;没挂 router 时退回路径写法。
*/
function workHref(job: string): string {
if (!job) return ''
const resolved = router?.resolve({ name: 'work-detail', params: { job } })
return resolved && resolved.matched.length ? resolved.href : `/work/${encodeURIComponent(job)}`
}
/** 这一格里此刻存的值(按 `valueKey` 存进来的那一份,不一定是来源的主键)。 */
const storedValues = computed<string[]>(() => {
@ -381,6 +468,21 @@ watch(
// ---------------------------------------------------------------- 流程单据
const processRows = ref<WorkSummary[]>([])
/** 问候选列表时那句 `status`(三档全给等于不限,后端认得出档位也认得出状态原值)。 */
const statusQuery = computed(() => (props.statuses ?? []).join(','))
let loadedStatusQuery: string | null = null
/**
* 弹窗里那句「这一格只列……」。
*
* 搜不到自己那张单的人,第一眼总以为是自己没权限或系统漏了单子;把这一档写在
* 搜索框底下,比让人回设计器翻一遍配置便宜。三档全勾时不说。
*/
const scopeLabels = computed(() => RELATION_STATUSES.filter((item) => (props.statuses ?? []).includes(item)))
const scopeNote = computed(() =>
props.source === 'process' && scopeLabels.value.length && scopeLabels.value.length < RELATION_STATUSES.length
? t('form.relationScopeNote', { scopes: scopeLabels.value.map((item) => t(RELATION_STATUS_LABEL_KEYS[item])).join('、') })
: ''
)
/** job → 摘要:弹窗里搜到的、以及只读回显批量取到的都存在这儿,取不到就显示 job 本身。 */
const jobCache = ref<Record<string, WorkSummary>>({})
const processLoading = ref(false)
@ -389,9 +491,16 @@ async function loadProcess(keyword: string) {
processLoading.value = true
try {
const page = await runAction(() =>
workAPI.listRelatedWorks({ keyword, process: props.process, page: 1, page_size: pageSize.value })
workAPI.listRelatedWorks({
keyword,
process: props.process,
status: statusQuery.value,
page: 1,
page_size: pageSize.value
})
)
processRows.value = page?.items ?? []
loadedStatusQuery = statusQuery.value
remember(processRows.value)
} finally {
processLoading.value = false
@ -421,16 +530,6 @@ async function resolveJobs(values: string[]) {
remember(found ?? [])
}
watch(
() => [props.source, storedValues.value.join(','), props.process],
() => {
if (props.source !== 'process') return
if (searchable.value && props.style === 'dialog' && !processRows.value.length) void loadProcess('')
void resolveJobs(storedValues.value)
},
{ immediate: true }
)
// ---------------------------------------------------------------- 一条候选 → 一行
/** 单据这一行的原始数据:optionMap 挑的就是这几个键(口径见 utils/optionMap)。 */
@ -482,10 +581,21 @@ function rowOfProcess(job: string): PickRow {
value: mapped.value || job,
title: shown.title || mapped.label || job,
note: shown.notes.join(' · '),
badge: badgeOfProcess(raw, shown.badge)
badge: badgeOfProcess(raw, shown.badge),
href: processHref(job)
}
}
/**
* 这一条存着的值能不能翻成一张点得开的单。
*
* 存的本来就是 job(关联审批单默认那一档)时直接拿去拼地址;改存了别的列(单号之类)
* 而这一张又还没拿到摘要,就翻不回 job——宁可不给地址,也别让人点进一张「单据不存在」。
*/
function processHref(job: string): string {
return storesCanonical.value || jobCache.value[job] ? workHref(job) : ''
}
function rowOfRemote(storedOrId: string): PickRow {
const id = storesCanonical.value ? storedOrId : remoteIdOfStored.value.get(storedOrId) ?? storedOrId
const row = remote.known.value[id]
@ -501,7 +611,8 @@ function rowOfRemote(storedOrId: string): PickRow {
value: mapped.value || storedOrId,
title: shown.title || mapped.label || storedOrId,
note: shown.notes.join(' · '),
badge: shown.badge
badge: shown.badge,
href: ''
}
}
@ -528,7 +639,8 @@ function rowOfLocal(value: string): PickRow {
value,
title: shown.title || value,
note: shown.notes.join(' · '),
badge: shown.badge
badge: shown.badge,
href: ''
}
}
@ -560,12 +672,34 @@ const knownRows = computed<PickRow[]>(() => {
const knownIndex = computed(() => new Map(knownRows.value.map((row) => [row.value, row])))
// 存的值要先经 knownIndex 翻回 job 才问得到摘要,所以这一趟 watch 只能挂在它后面:
// 早期版本挂在前头,immediate 那一次正撞上 knownIndex 还没初始化(TDZ),
// 「改存单号」的那一格一进来就吃一个 unhandled rejection,摘要再也没取到过。
watch(
() => [props.source, storedValues.value.join(','), props.process, statusQuery.value],
() => {
if (props.source !== 'process') return
// 换了能挂哪几档,手上那一页就不是那一档的候选了:重新捞一页,别拿旧的给人挑
const stale = loadedStatusQuery !== null && loadedStatusQuery !== statusQuery.value
if (searchable.value && props.style === 'dialog' && (stale || !processRows.value.length)) void loadProcess('')
void resolveJobs(storedValues.value)
},
{ immediate: true }
)
const picked = computed<PickRow[]>(() =>
storedValues.value.map((stored) => knownIndex.value.get(stored) ?? rowOf(stored))
)
/** 框里那排标签。 */
const pickedTags = computed(() => picked.value.map((row) => ({ id: row.value, label: row.title || row.value, note: row.note })))
/** 框里那排标签:认得出是哪张单的几条,名字给一个落点。 */
const pickedTags = computed(() =>
picked.value.map((row) => ({
id: row.value,
label: row.title || row.value,
note: row.note,
...(row.href ? { href: row.href, linkTitle: openWorkHint.value } : {})
}))
)
/** 弹窗与下拉里此刻能挑的候选。 */
const rows = computed<PickRow[]>(() => {
@ -586,7 +720,12 @@ const rows = computed<PickRow[]>(() => {
})
const dropdownOptions = computed(() =>
rows.value.map((row) => ({ value: row.value, label: row.title, description: row.note }))
rows.value.map((row) => ({
value: row.value,
label: row.title,
description: row.note,
...(row.href ? { href: row.href } : {})
}))
)
/**
@ -596,12 +735,19 @@ const dropdownOptions = computed(() =>
* 框里还得念得出它们叫什么,不能空着一串编码让人以为没选上。
*/
const knownOptions = computed(() =>
knownRows.value.map((row) => ({ value: row.value, label: row.title || row.value }))
knownRows.value.map((row) => ({
value: row.value,
label: row.title || row.value,
...(row.href ? { href: row.href } : {})
}))
)
/** 下拉那只框里此刻念的值:一串还是一句,跟着这一格存的形状走。 */
const dropdownModel = computed(() => (props.multiple ? storedValues.value : text.value))
/** 单选那一格框里那一句话的落点(多选那一排各点各的标签,用不着这一个)。 */
const singleWorkHref = computed(() => (props.multiple ? '' : picked.value[0]?.href ?? ''))
const loading = computed(() =>
props.source === 'dataSource' ? remote.loading.value : props.source === 'process' ? processLoading.value : false
)

View File

@ -0,0 +1,85 @@
<template>
<!--
明细表表尾那一行「合计 / 平均 / 最大 / 最小 / 计数」。
只念列上点了名的那几列,没配的列留白——这一行不是"每列都得给个数",而是设计者
点名要看的几列。数字照列上那份格式(小数位、千分位、货币)写,跟格子里一个写法,
免得出现「格子里 1,200.50、表尾 1200.5」两套。
行本身用 <tr> 而不是 <tfoot>:宿主那张表的行都画在 <tbody> 里,插一道 tfoot 要跨
填单与看单两个画法,而这一行本来就跟着行一起横向滚,落在 tfoot 里反而不滚。
宽度仍取 columnMinWidth 那份口径:表头撑不开的列,表尾那句「合计」也不该撑开它。
-->
<tr class="border-t border-gray-200 bg-gray-50/70 text-xs dark:border-dark-700 dark:bg-dark-900/40">
<td
v-for="lead in leadCells"
:key="`lead-${lead}`"
class="px-1 py-1 text-center tabular-nums text-gray-400 dark:text-dark-400"
:title="t('form.tableColumnAggregateHint')"
>
<template v-if="lead === leadCells">&Sigma;</template>
</td>
<td
v-for="column in visibleTableColumns(field)"
:key="`agg-${column.key}`"
class="border-l border-gray-100 px-2 py-1 dark:border-dark-700"
:class="columnAlignClass(column)"
:style="{ minWidth: columnMinWidth(column) }"
>
<span v-if="aggregateOf(column)" class="tabular-nums" data-test="table-aggregate">
<span class="mr-1 font-normal text-gray-400 dark:text-dark-400">{{ labelOf(column) }}</span>
<b class="text-gray-800 dark:text-dark-100">{{ aggregateOf(column) }}</b>
</span>
</td>
</tr>
</template>
<script setup lang="ts">
/**
* 明细表的合计行。纯展现:不改任何一格的值,也不参与提交那道闸——本行公式算出来的
* 还是它自己那份公式,这里只是把已经落定的值汇总一遍给人看。
*
* 判据都在 utils/formRuntime.ts(columnAggregate / aggregateValue / visibleTableColumns),
* 后端 service/formruntime.py:column_total 是同一把尺子的镜像。
*/
import { computed } from 'vue'
import { useI18n } from 'vue-i18n'
import {
aggregateValue,
columnAlignClass,
columnAggregate,
columnMinWidth,
formatNumber,
rowsOf,
visibleTableColumns
} from '@/utils/formRuntime'
import type { FormFieldDef } from '@/types'
const props = withDefaults(
defineProps<{
/** 那张明细表:列定义从它身上取 */
field: FormFieldDef
/** 这张单里这一格的值(行对象数组),由宿主把 model[field.key] 递进来 */
value?: unknown
/** 列前面那几格非列单元格:看单只有「序号」= 1,填单还有勾选框 = 2 */
leadCells?: number
}>(),
{ value: undefined, leadCells: 1 }
)
const { t } = useI18n()
const rows = computed(() => rowsOf(props.value))
/** 这一列念出来的数(已按列自己的格式排好);没配合计回空串,那一格留白。 */
function aggregateOf(column: FormFieldDef): string {
if (!columnAggregate(column)) return ''
return formatNumber(aggregateValue(rows.value, column), column)
}
/** 那一档叫什么:合计 / 平均 / 最大 / 最小 / 计数。 */
function labelOf(column: FormFieldDef): string {
const kind = columnAggregate(column)
return kind ? t(`form.tableAggregate.${kind}`) : ''
}
</script>

View File

@ -0,0 +1,59 @@
<template>
<!-- 点开一条已经不存在的待办:这一屏要说清"它怎么没的、现在归谁、还要不要我管",
而不是只丢一句"已被处理"。文案在 utils/taskVanished.ts,桌面与手机版式读同一份。 -->
<div class="rounded-lg border border-gray-200 bg-gray-50 px-4 py-4 dark:border-dark-700 dark:bg-dark-900/40">
<div class="flex items-start gap-3">
<span class="mt-0.5 flex h-8 w-8 flex-shrink-0 items-center justify-center rounded-lg bg-white dark:bg-dark-800">
<Icon :name="notice.icon" class="h-4 w-4 text-gray-500 dark:text-dark-300" />
</span>
<div class="min-w-0 flex-1">
<h3 class="text-sm font-semibold text-gray-900 dark:text-dark-100">
{{ t(notice.titleKey, notice.titleParams || {}) }}
</h3>
<p class="mt-1 truncate text-xs text-gray-500 dark:text-dark-400">
{{ vanished.title }}<span v-if="vanished.serial"> · {{ vanished.serial }}</span>
</p>
<ul class="mt-2 space-y-1">
<li
v-for="(line, index) in notice.lines"
:key="index"
class="text-xs leading-relaxed text-gray-600 dark:text-dark-300"
>
{{ t(line.key, line.params || {}) }}
</li>
</ul>
<div class="mt-3 flex flex-wrap items-center gap-2">
<RouterLink
v-if="notice.openWork"
:to="`/work/${encodeURIComponent(vanished.job)}`"
class="btn btn-primary btn-sm"
>
<Icon name="document" class="mr-1 h-4 w-4" />{{ t('task.vanishedOpenWork') }}
</RouterLink>
<slot name="actions" />
</div>
</div>
</div>
</div>
</template>
<script setup lang="ts">
import { computed } from 'vue'
import { useI18n } from 'vue-i18n'
import type { VanishedTask } from '@/types'
import { vanishedNotice } from '@/utils/taskVanished'
import Icon from '@/components/icons/Icon.vue'
const props = defineProps<{ vanished: VanishedTask }>()
const { t } = useI18n()
// 认不出这是哪一种下场(老数据、没见过的 processing_type)时退到"已被处理"那一句
const fallback = computed(() => ({
icon: 'inbox' as const,
titleKey: 'task.taskHandled',
titleParams: undefined,
lines: [] as { key: string; params?: Record<string, string | number> }[],
openWork: Boolean(props.vanished?.job)
}))
const notice = computed(() => vanishedNotice(props.vanished) || fallback.value)
</script>

View File

@ -6,7 +6,7 @@
{{ multi ? t('form.fetchOnMulti', { count: entries.length }) : t('form.fetchOn') }}
</span>
</div>
<p class="input-hint">{{ t('form.fetchPanelHint') }}</p>
<p class="input-hint">{{ hint || t('form.fetchPanelHint') }}</p>
<!-- 一格挂几个源:每个源自己一份入参、自己一份带出去向,最后按下面的口径合成一个值 -->
<div
@ -38,6 +38,36 @@
:self-key="field.key"
@update:model-value="setEntry(index, $event)"
/>
<!--
这一条什么时候才调。清单里那几条本来就按顺序跑,加一句条件就是把它当路由用:
「费用类型 = 差旅才问差标接口,= 招待才问 ERP」不必再为每种组合另建一条源。
-->
<div class="mt-1.5 flex items-center gap-1.5">
<button
type="button"
class="min-w-0 flex-1 rounded-lg border border-gray-200 px-2 py-1 text-left dark:border-dark-600"
:data-test="`fetch-when-${index}`"
@click="editingWhen = index"
>
<span class="block text-[10px] font-semibold uppercase tracking-wider text-gray-400">
{{ t('form.fetchWhen') }}
</span>
<span v-if="whenText(entry)" class="block truncate text-xs text-gray-700 dark:text-dark-200">
{{ whenText(entry) }}
</span>
<span v-else class="block text-xs text-gray-400">{{ t('form.fetchWhenAlways') }}</span>
</button>
<button
v-if="entry.when"
type="button"
class="btn btn-ghost btn-icon h-7 w-7 flex-shrink-0 text-gray-400"
:title="t('form.fetchWhenClear')"
@click="clearWhen(index)"
>
<Icon name="x" class="h-3.5 w-3.5" />
</button>
</div>
</div>
@ -49,6 +79,17 @@
{{ t('form.fetchMultiLimit', { max: MAX_FETCH_SOURCES }) }}
</p>
<LinkageConditionDialog
:show="editingWhen >= 0"
:title="t('form.fetchWhenTitle')"
:condition="editingWhen >= 0 ? entries[editingWhen]?.when : undefined"
:fields="conditionFields"
:self-key="field.key"
@close="editingWhen = -1"
@apply="applyWhen"
@clear="applyWhen(undefined)"
/>
<div v-if="multi" class="border-t border-gray-100 pt-2 dark:border-dark-700">
<label class="input-label">{{ t('form.fetchMerge') }}</label>
<Select :model-value="merge" :options="mergeOptions" @update:model-value="setMerge(String($event))" />
@ -108,11 +149,36 @@ import Select from '@/components/common/Select.vue'
import Toggle from '@/components/common/Toggle.vue'
import { listDataSourcesCached } from '@/api/dataSources'
import SourceBindingEditor from './SourceBindingEditor.vue'
import LinkageConditionDialog from './LinkageConditionDialog.vue'
import { entryParse } from '@/utils/binding'
import { MAX_FETCH_SOURCES, REVALIDATE_CHOICES, fetchEntries, revalidateSeconds, writableTargets } from '@/utils/formFetch'
import type { DataSource, FetchFieldConfig, FetchMerge, FetchSourceEntry, FormFieldDef } from '@/types'
import { LINKAGE_OP_KEYS, describeLinkageCondition } from '@/utils/formLinkage'
import type {
DataSource,
FetchFieldConfig,
FetchMerge,
FetchSourceEntry,
FormFieldDef,
LinkageCondition,
LinkageOp
} from '@/types'
const props = defineProps<{ field: FormFieldDef; siblings: FormFieldDef[] }>()
const props = defineProps<{
/** 正在配取数的那一格(主表字段,或明细表的一列) */
field: FormFieldDef
/** 带出去向能挑哪些格子:主表字段传整张表单,明细列传这张表的其它列 */
siblings: FormFieldDef[]
/**
* 入参写法能引用哪些格子。默认与 ``siblings`` 同一份(主表那一格本来就只能引用整张表单)。
*
* 明细列那一格必须分开朗:它的入参读的是「整张单 + 这一行」,所以主表字段与本行的列都算
* 引用得到(同名列以本行为准,跟本行公式同一分寸),而带出去向只许落在本表的列上。
* 后端镜像在 ``service/fetch.py::problems``(``keys`` 与 ``target_keys`` 分开传那一段)。
*/
argFields?: FormFieldDef[]
/** 面板顶上那句话:明细列那一档要说的是逐行取数,与主表那一格不是同一句话 */
hint?: string
}>()
const emit = defineEmits<{ (e: 'patch', values: Record<string, unknown>): void }>()
const { t } = useI18n()
@ -128,11 +194,24 @@ interface EntryDraft {
picks: Record<string, string>
pick: string
extras: Record<string, string>
/** 这一条什么时候才调;没配 = 每次都调(后端 ``binding.entry_active`` 读的是同一句话) */
when?: LinkageCondition
}
const sources = ref<DataSource[]>([])
/** 面板编辑的就是字段上那份 `fetch`:一屏改完整份写回去(后端只认这一份)。 */
const entries = reactive<EntryDraft[]>([])
/** 正在配触发条件的那一条;-1 = 弹窗没开 */
const editingWhen = ref(-1)
/**
* 触发条件能引用的格子:与入参写法引用的是同一份清单。
*
* 明细列那一档读的是「整张单 + 这一行」,所以那份清单本来就把主表字段与列都算进来
* (``argFields`` 就是为这件事单开的),条件跟着它走才不会界面上一套、运行时无效。
*/
const conditionFields = computed<FormFieldDef[]>(() =>
props.argFields?.length ? props.argFields : props.siblings
)
const merge = ref<FetchMerge>('first')
const separator = ref('')
const onError = ref('')
@ -146,11 +225,12 @@ const configured = computed(() => entries.some((item) => item.source))
const multi = computed(() => entries.filter((item) => item.source).length > 1)
const canAdd = computed(() => configured.value && entries.length < MAX_FETCH_SOURCES)
/** 入参引用与带出去向都只在同一张表单的字段名里判 */
const siblingKeys = computed(() => props.siblings.map((item) => item.key))
/** 入参能引用的那一份格子清单(明细列那一档 = 整张表单 + 这张表的列) */
const argFields = computed(() => props.argFields ?? props.siblings)
const siblingKeys = computed(() => argFields.value.map((item) => item.key))
/** 选人字段单挑出来:那一格交的是账号数组,SQL 的入参要包一层 account */
const siblingPersonKeys = computed(() =>
props.siblings.filter((item) => String(item.type ?? '') === 'user').map((item) => item.key)
argFields.value.filter((item) => String(item.type ?? '') === 'user').map((item) => item.key)
)
@ -208,7 +288,9 @@ function commit() {
args: Object.fromEntries(Object.entries(entry.args || {}).filter(([, value]) => String(value ?? '').trim())),
picks: Object.fromEntries(Object.entries(entry.picks || {}).filter(([, value]) => String(value ?? '').trim())),
// 这两处覆盖没填就不写键:字段上那份 fetch 保持老形状,别拖一堆空字段
...entryParse({ pick: entry.pick, extras: entry.extras })
...entryParse({ pick: entry.pick, extras: entry.extras }),
// 触发条件同理:没配过就不写这个键,存量表单一个字节不动
...(entry.when?.rules?.length ? { when: entry.when } : {})
}))
.filter((entry) => entry.source)
if (!list.length) {
@ -239,6 +321,33 @@ function blank(): EntryDraft {
return { source: '', args: {}, picks: {}, pick: '', extras: {} }
}
/** 这一条现在什么时候才调(配了条件就说清条件,没配就说「每次都调」)。 */
function whenText(entry: EntryDraft): string {
return describeLinkageCondition(
entry.when,
{
label: (key) => conditionFields.value.find((item) => item.key === key)?.label || key,
type: (key) => conditionFields.value.find((item) => item.key === key)?.type ?? 'text',
optionLabel: () => ''
},
(op) => t(`form.${LINKAGE_OP_KEYS[op as LinkageOp] ?? 'linkageValue'}`)
)
}
function applyWhen(condition?: LinkageCondition) {
const current = entries[editingWhen.value]
if (current) current.when = condition?.rules?.length ? condition : undefined
editingWhen.value = -1
commit()
}
function clearWhen(index: number) {
const current = entries[index]
if (!current || !current.when) return
current.when = undefined
commit()
}
/** 面板编辑的就是那几份:整份换掉这一个源,再写回字段。 */
function setEntry(index: number, entry: FetchSourceEntry) {
const current = entries[index]
@ -293,7 +402,8 @@ function loadFromField() {
args: { ...(item.args || {}) },
picks: { ...(item.picks || {}) },
pick: String(item.pick ?? ''),
extras: { ...(item.extras || {}) }
extras: { ...(item.extras || {}) },
when: item.when
}))
entries.splice(0, entries.length, ...(list.length ? list : [blank()]))
merge.value = (raw.merge || 'first') as FetchMerge

View File

@ -0,0 +1,105 @@
// @vitest-environment jsdom
/**
* 「这一条数据源什么时候才调」在面板上的那一下。
*
* 取数那头的多源清单是 2026-10 配好的,缺的正是**按这张单上的值决定调不调**:
* 「报销类型 = 差旅才问差标接口」。钉三件事:条件写回来落在这一条的 ``when`` 上(不是新开
* 一份配置)、没配过的那一格一个字节都不动(存量表单不因此多一堆空键),以及读回来时
* 配过的看得见、能一句话摘掉。判据在运行时那一头(``utils/formFetch.activeFetchEntries``
* ↔ 后端 ``fetch.active_field_sources``),这一份只管面板写的形状对不对。
*/
import { describe, expect, it, vi } from 'vitest'
import { flushPromises, mount } from '@vue/test-utils'
import { createI18n } from 'vue-i18n'
import zh from '@/i18n/locales/zh'
import FetchPanel from './FetchPanel.vue'
import LinkageConditionDialog from './LinkageConditionDialog.vue'
import { listDataSourcesCached } from '@/api/dataSources'
import type { FormFieldDef } from '@/types'
vi.mock('@/api/dataSources', async (importOriginal) => ({
...(await importOriginal<typeof import('@/api/dataSources')>()),
listDataSourcesCached: vi.fn(async () => [
{ code: 'travel_api', name: '差标接口', kind: 'fetch', enabled: true },
{ code: 'erp', name: 'ERP 主数据', kind: 'fetch', enabled: true }
])
}))
const i18n = createI18n({ legacy: false, locale: 'zh', messages: { zh }, missingWarn: false, fallbackWarn: false })
const SIBLINGS: FormFieldDef[] = [{ key: 'expenseType', label: '报销类型', type: 'select' }]
function open(fetch?: Record<string, unknown>) {
const wrapper = mount(FetchPanel, {
props: { field: { key: 'amount', label: '金额', type: 'money', fetch } as unknown as FormFieldDef, siblings: SIBLINGS },
global: { plugins: [i18n] }
})
return flushPromises().then(() => wrapper)
}
function patched(wrapper: Awaited<ReturnType<typeof open>>) {
const events = wrapper.emitted('patch') as { fetch: Record<string, unknown> }[] | undefined
return events?.at(-1)?.[0]?.fetch
}
describe('这一条什么时候才调', () => {
it('没配过的老配置读回来是「每一次都调」,写回去也不多一个 when 键', async () => {
vi.mocked(listDataSourcesCached).mockClear()
const wrapper = await open({ source: 'erp', args: {}, picks: {} })
expect(wrapper.find('[data-test="fetch-when-0"]').text()).toContain('无条件(每一次都调)')
// 清掉那颗按钮压根不摆
expect(wrapper.find('button[title="去掉这个条件"]').exists()).toBe(false)
await wrapper.find('[data-test="fetch-when-0"]').trigger('click')
wrapper.findComponent(LinkageConditionDialog).vm.$emit('apply', { match: 'all', rules: [] })
await flushPromises()
expect('when' in (patched(wrapper) ?? {})).toBe(false)
})
it('条件写回来落在这一条的 when 上,界面上念得出是哪一格等于什么', async () => {
const wrapper = await open({ source: 'travel_api', args: {}, picks: {} })
await wrapper.find('[data-test="fetch-when-0"]').trigger('click')
const dialog = wrapper.findComponent(LinkageConditionDialog)
expect(dialog.props('show')).toBe(true)
// 条件只能引用同表其它字段与这一格自己
expect((dialog.props('fields') as FormFieldDef[]).map((item) => item.key)).toContain('expenseType')
dialog.vm.$emit('apply', { match: 'all', rules: [{ field: 'expenseType', op: 'eq', value: 'travel' }] })
await flushPromises()
expect(patched(wrapper)?.when).toEqual({ match: 'all', rules: [{ field: 'expenseType', op: 'eq', value: 'travel' }] })
expect(wrapper.text()).toContain('报销类型')
})
it('配过的读回来看得见,一句话能摘掉', async () => {
const wrapper = await open({
source: 'travel_api',
args: {},
picks: {},
when: { match: 'all', rules: [{ field: 'expenseType', op: 'eq', value: 'travel' }] }
})
expect(wrapper.find('button[title="去掉这个条件"]').exists()).toBe(true)
await wrapper.find('button[title="去掉这个条件"]').trigger('click')
await flushPromises()
expect('when' in (patched(wrapper) ?? {})).toBe(false)
})
it('多源清单里那几条各配各的条件', async () => {
const wrapper = await open({
source: 'travel_api',
merge: 'first',
sources: [
{ source: 'travel_api', when: { match: 'all', rules: [{ field: 'expenseType', op: 'eq', value: 'travel' }] } },
{ source: 'erp' }
]
})
expect(wrapper.find('[data-test="fetch-when-0"]').text()).toContain('报销类型')
expect(wrapper.find('[data-test="fetch-when-1"]').text()).toContain('无条件')
await wrapper.find('[data-test="fetch-when-1"]').trigger('click')
wrapper.findComponent(LinkageConditionDialog).vm.$emit('apply', {
match: 'all',
rules: [{ field: 'expenseType', op: 'eq', value: 'meet' }]
})
await flushPromises()
const sources = patched(wrapper)?.sources as { source: string; when?: unknown }[]
expect(sources.map((item) => item.source)).toEqual(['travel_api', 'erp'])
expect(sources[1].when).toEqual({ match: 'all', rules: [{ field: 'expenseType', op: 'eq', value: 'meet' }] })
})
})

Some files were not shown because too many files have changed in this diff Show More