新增主题色选择器组件,支持青、蓝、靛蓝、紫、玫红、橙六种颜色选项 前后端适配主题色存储与同步,用户偏好新增 color 字段 登录页与个人设置界面适配主题色展示,样式表按主题色拆分多套配色 完善相关国际化文案与测试用例,优化登录页面布局适配主题色切换 |
||
|---|---|---|
| backend | ||
| deploy | ||
| design | ||
| docs | ||
| frontend | ||
| sql | ||
| .dockerignore | ||
| .gitignore | ||
| Dockerfile | ||
| README.md | ||
| docker-compose.yml | ||
| permission-integration.md | ||
| third-party-integration.md | ||
README.md
UnisOA 流程审批平台
把 O2OA 的完整流程审批模块(x_processplatform_*)与首页门户
(x_component_Homepage 依赖的 x_cms / x_hotpic / x_meeting / x_calendar /
x_file 五个后端)用 Python 重写,前端复用 sub2api 的 Vue3 设计体系
(组件、配色、暗色模式、表格与弹窗规范),组成一套可以独立运行的 OA 系统。
- 后端:FastAPI + SQLAlchemy 2 + PyMySQL,接口前缀
/api/v1,统一响应体{code, message, data} - 前端:Vue 3 + TypeScript + Vite + Tailwind + vue-i18n,构建产物由后端直接托管
- 数据库:MySQL 8(默认
192.168.124.202:3306/unis_oa),启动时自动建表并写入种子数据; 建库只认[database] create_allowlist点名的库名,一个环境一个库 - 单端口访问:
pnpm build之后只需访问 http://127.0.0.1:8000,前后端同源
目录结构
unisoa/
├── backend/
│ ├── app/
│ │ ├── main.py # 应用装配、建表与种子、定时调度、前端静态托管
│ │ ├── config.py # 配置入口:按 OA_ENV 挑 config.<环境>.toml,叠在 config.toml 上
│ │ ├── dbconfig.py # 运行配置注册表:取值分层、中文说明、校验、存库即生效
│ │ ├── llmconfig.py # 大模型接入目录:5 种报文协议 + 24 家服务商预设、地址/模型/密钥清洗
│ │ ├── cors.py # 现读现判的跨域中间件(改了来源不用重启)
│ │ ├── db.py # engine / SessionLocal / 建库建表
│ │ ├── models.py # 41 张 oa_* 表 + users,对应 O2OA 实体(含大模型接入 oa_ai_provider)
│ │ ├── storageconfig.py # 文件存放位置:按配置指纹重建客户端 + 密钥掩码
│ │ ├── schemas.py # 入参模型(camelCase -> snake_case)
│ │ ├── serializers.py # 出参(snake_case)与分页封装
│ │ ├── deps.py # 鉴权、“当前身份”、权限点与数据范围
│ │ ├── permissions.py # 权限码目录、内置角色、数据范围展开
│ │ ├── query.py # 查询参数归一化(三态布尔)
│ │ ├── envelope.py # 统一响应与异常
│ │ ├── public_config.py # 登录页与首屏共用的那份公开配置(接口与 index.html 注入同一个口径)
│ │ ├── web_shell.py # 发 index.html 时把它注进头里:画第一笔之前就知道该画哪一屏
│ │ ├── seed.py # 组织/人员/分类/表单/流程种子 + 一次性数据修复
│ │ ├── engine/
│ │ │ ├── engine.py # 流程引擎:流转、签核、退回、加签、转办、撤回、催办…
│ │ │ ├── definition.py # 流程定义校验与自动排版
│ │ │ ├── expressions.py # 条件表达式沙箱(受限 eval)
│ │ │ └── tickets.py # 并行/汇聚 token 记账
│ │ ├── storage/ # 文件存储层:base / local / minio_store / http / preview
│ │ ├── api/ # auth / authrole / org / design / runtime / support / portal / hub / config / export / ai
│ │ └── service/ # org.py 组织树与人员引用(库里存登录账号,见 docs/person-reference-design.md),
│ │ # hub.py 统一身份客户端,hub_sync.py 组织人员同步与到点判定,
│ │ # sync_jobs.py 同步定时任务:排期算法与「同步定时任务」页共用它,
│ │ # sso_state.py 免登 state 的发放与两层校验,
│ │ # sso_handoff.py 免登回调与前端之间的一次性短码,
│ │ # llm.py 大模型客户端(五种报文收发、错误中文化、失败补试)
│ ├── scripts/dev-api.sh # 开发启动脚本
│ ├── scripts/dump_schema.py # 从实库重新导出 sql/schema.sql
│ ├── scripts/check_schema_snapshot.py # 对账:sql/schema.sql 与 models.py 是否还一致
│ ├── scripts/check_schema_bootstrap.py # 启动建表补列体检:空库建得出全部表、删掉的表/列/索引同一趟补得回来
│ ├── scripts/check_index_gaps.py # 会长大的表上,单独出现的等值过滤列有没有打头索引(不建要写下理由)
│ ├── scripts/check_seed_repairs.py # 出厂种子体检:把六类历史数据各打坏一次,看修不修得回来、修好还动不动
│ ├── scripts/migrate_to_users_table.py # 老库 oa_person -> users 结构迁移(带备份)
│ ├── scripts/migrate_identity_refs.py # 配置与运行态里残留的身份 DN -> 登录账号(认不出的一律不动)
│ ├── scripts/gen_portal_covers.py # 重新生成首页信息封面素材
│ ├── scripts/apply_portal_covers.py # 给已初始化过的库挂上封面
│ ├── scripts/check_route_guards.py # 扫路由表:有没有接口漏掉了登录/权限校验
│ ├── 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_relation_scope.py # 关联流程那两档:候选只列我发起的(含管理员、含挂在路由上那一档)+ 那一行读对方表单的哪几格(列名清洗、落成文本、摘要里那个 data 键)、前后端常量与措辞对账
│ ├── 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、预受理号复用与那三档回写、响应里有哪几栏可挑与对方回传过的键名
│ ├── scripts/check_embed_decide.py # 第三方回写审批结论:跑真流程真待办,验出口、验办理人、验"已被人办掉回 200"
│ ├── scripts/check_embed_abandon.py # 「这一页被放弃时通知对方删草稿」三条腿的入口:路由通到判据、新开一页不复用已发起那趟旧账、过期兜底只补一次、删单与删草稿发同一套参数
│ ├── scripts/audit_storage.py # 对象存储对账:孤儿对象、待补删账本、本地文件搬进 MinIO
│ ├── scripts/perf_guard.py # 只读接口全扫描:5xx、读缓存开/关报文一致、分页边界、每接口语句条数对账
│ ├── scripts/perf_budget.json # 上一条的基线:每个接口该问几条语句(`--save-budget` 重写)
│ ├── scripts/check_readcache.py # 只读缓存的作废规则、每个调用点的即时性、认人/已办/待办那三份共用清单
│ ├── scripts/check_shared_cache.py # Redis 那层:批量读/预取与逐个同口径、作废当场生效、冷缓存下只问一条 IN
│ ├── scripts/check_design_cache.py # 流程定义缓存:命中与现查同一定义、改了设计当场生效、未提交的不进缓存
│ ├── scripts/check_presence_guard.py # 空表探针与表单快照:作废只认提交、本 Session 写过的当场看得见、少排队不改答案
│ ├── scripts/check_selector_kinds.py # 设计器那两问(它是哪一类/和谁重名):跳档省往返、改了组织当场重来
│ ├── scripts/check_write_payload.py # 写接口收尾:报文在提交前拼完、报文与库里逐字段一致、拼不出来就回滚
│ ├── scripts/check_action_surface.py # 批处理/挂起/待阅/评论四条写路径端到端:逐条成事、挂起真冻住、两种待阅口径不互顶
│ ├── scripts/check_notify_hub.py # 经 Hub 代发企业微信:假 Hub 钉住预算、幂等键、逐人原因分档与请求级错误
│ ├── scripts/check_notify_hub_api.py # 同一路的接口层:真 TestClient + 假 Hub,验 meta、保存校验、测试发送与回查
│ ├── scripts/check_notify_landing.py # 卡片点开那一跳的落地侧:ticket+redirect 验票、短码一次性、深链只认站内
│ ├── scripts/check_notify_wake.py # 渠道提醒与订阅事件什么时候真的发出去:入队提交当场叫醒、回滚与没排上不空叫
│ ├── scripts/check_person_ref.py # 认人只认登录账号:认不出就不是一个人,改名不影响历史
│ ├── 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_cc_entries_to_read.py # 抄送一律先进待阅:六个入口只有一个出口、办结那一档不搬已阅、需处理不被「点开」顶掉,加签转办不往待阅里塞
│ ├── scripts/check_read_batch.py # 批量登记待阅:只盖章那一趟不洗掉需处理的、一条失败不带走整批、逐条原因带得回、角标跟着降
│ ├── scripts/check_done_cc_split.py # 已办 / 已阅分家:办完的抄送归已办(done_source=cc)、看过的归已阅、历史行不回填、已办按(单 × 来源)折叠、处理意见选填
│ ├── scripts/check_inbox_read.py # 统一待办(取件箱):三档的列表 / 筛选 / 计数一致、红点从亮起熄灭到升级重亮、只需阅看过即离待办进已阅、混批缺意见单独一档
│ ├── scripts/check_task_batch_read.py # 待办批量已读与「按筛选取整片」:盖时间戳不等于表态、列表与批量同一把尺、五档账目不合并、探针行跑完自己清干净
│ ├── scripts/check_flowmap_cc.py # 轨迹图上那份抄送与转发:配置对每个环节都露、实况按人并一行、只认 read_type=cc、未阅/未处理两本账算对;办结之后的转发另开一本账,不混进环节那一格;逐人处理时上传的附件也带着走、按人去重合并
│ ├── scripts/check_flush_defer.py # 引擎 flush 只刷该刷的那几行:同一张单办两遍,逐行逐列与整刷对齐
│ ├── scripts/check_simulate_paths.py # 设计器逐环节试算:配好的路由能不能真的解析出审批人
│ ├── scripts/check_log_timeline.py # 流转日志时间线:留痕不倒挂、上一条不每趟回库
│ ├── scripts/check_completed_dedup.py # 已办按(单 × 来源)折叠:一张单的一档来源只摆一条,次数与角标/导出/工作台四处同口径
│ ├── scripts/check_done_current_step.py # 已办那一列「当前环节」:读单据此刻的现账而不是行上那份快照、单据往前走当场跟着变、落定报结局、说不清就不猜、一页一条 UNION ALL、CSV 与页面同口径
│ ├── scripts/check_detail_export.py # 流程明细导出:未操作者五类口径、按流程分表与合并表头、七项筛选与两条上限
│ ├── scripts/check_delete_unstarted.py # 待办上删掉还没发起的单:谁能删、删干净没有、额度、嵌页面的账与给第三方的那一句一起收尾
│ ├── scripts/check_begin_resubmit_todo.py # 退回到发起人又重新提交:同一张单在「我的待办」里只留一条(开始环节提交三条路共用)
│ ├── scripts/check_starter_submit_action.py # 发起人那一环说「提交」还是「同意」:is_starter_step 真的到了环节简报与站内信,第一次走到起草环节不许被念成被退回
│ ├── scripts/check_todo_starter_unit.py # 待办行上的两个部门各归各:unit_name 是本环节处理人的,creator_unit_name 是发起人的,转办/加签/依次审批都不许丢
│ ├── scripts/check_read_starter_snapshot.py # 待阅/已阅行上的两个人各归各:creator_person 是发起人,sender 是把它递给我的人(自动抄送时是当次经手人),抄送/分享/转发/@/归档抄送/搬档都不许丢
│ ├── scripts/check_todo_work_status.py # 待办按「所属单据的流程状态」筛:筛的是单据那一头而不是待办自己那份 pending,挂起另算一档,列表/批量整片/导出三条口共用同一份条件
│ ├── scripts/check_dedup_rerun.py # 驳回之后重走:驳回前那几票一概不算,同一轮里批过的照常算(回头线判据统一)
│ ├── scripts/check_form_change_noise.py # 改了表单的留痕:数字型字段按数值比,0.0 → 0 那种尾零写法不算人改的
│ ├── scripts/check_leader_lease.py # 多副本那把租约:过期可接管、别人抢不走、库读不动时后台照跑
│ ├── scripts/check_outbox_wake.py # 写回投递的即时性:入队当场叫醒、回滚不空叫、一轮把一张单排着的发干净
│ ├── scripts/check_hub_breaker.py # Hub 不回话时的自保闸:冷却、探测、自检绕开、并发第一波限量(本地造假 Hub)
│ ├── scripts/check_hub_sync_details.py # 同步记录要能核对:改名/让位/认回部门计数成列、名单有界、提示按条留底;三条熔断底线跟着配置走
│ ├── scripts/check_hub_sync_shell_units.py # Hub 换主键留下的空壳部门:判据、删不掉的三种原因、一键清理只删干净的
│ ├── scripts/check_job_payload.py # 单据详情:定义并发拆开问再拼回,顺序/表单清单/归档分支与串着问一字不差
│ ├── scripts/check_org_tree_managers.py # 部门树的负责人:复用已读进内存的人员行,停用/系统账号/范围外三种照样写得出名字
│ ├── scripts/check_pool_reset.py # 连接归还口径:还回池子的连接一律已自己收尾(含一次故意的脏归还反向自检)
│ ├── scripts/check_dict_import.py # 字典项批量导入:一行一个结论、导入不停用没出现的项、顺序不被导入打乱
│ ├── scripts/check_dict_manual.py # 外部来源字典上的手工补充:这一项归谁、同步不许碰人补的那一项、接手与交还
│ ├── scripts/check_quota_import.py # 额度台账批量导入总额:维度就是这笔账的身份证,缺键/重复/归属人认不出各挡各的
│ ├── assets/portal_covers/ # 首页热点封面图(种子数据的一部分)
│ ├── scripts/demo_linkage.py # 往开发库建一套「字典 + 联动 + 审批规则」演示表单与流程并当场跑一遍
│ ├── scripts/demo_newcap.py # 往开发库建一套「签名 / 关联单 / 比例会签 / 汇聚放行」演示流程并当场跑一遍
│ ├── config.toml # 基础配置:各环境公共的出厂值(逐项中文注释)
│ ├── config.dev.toml # 测试档:本地测试库、演示数据、开发密钥(不设 OA_ENV 就读它)
│ ├── 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 前端框架
├── Dockerfile # 镜像:前端 pnpm 构建 + 后端 uvicorn(TZ 烤成 Asia/Shanghai、非 root、密钥不进镜像)
├── docker-compose.yml # 单机容器部署:OA_ENV=prod、配置目录只读挂载、storage 命名卷
├── .dockerignore # 密钥文件一律不进镜像(backend/config.*.toml 全排除)
├── deploy/config/ # 部署机上的配置目录,挂进容器 /etc/unisoa(config.toml + config.prod.toml)
├── sql/schema.sql # 60 张表的结构快照(含 `users` 用户表,`python3 backend/scripts/dump_schema.py` 导出)
├── sql/backup/ # 结构迁移前自动导出的老表 INSERT 备份
├── docs/architecture.md # 引擎语义与接口明细
├── docs/complex-process-design.md # 复杂流程(并行 / 子流程 / 定时)设计说明
├── docs/approval-dedup-design.md # 同一个人重复出现怎么办:四档策略、「批过」的口径与设计期审批体检
├── docs/todo-inbox-unified-design.md # 一张待办装下所有要我看的东西:三档并页、红点语义、「待阅」的消失,PC 与手机两版版式
├── docs/prod-process-flow-and-signoff-matrix.md # 生产环境流程梳理:发起→办结全流程(含抄送)+ 流程权限签批表(环节矩阵 / 动作总表 / 角色与数据范围)
├── docs/oa-capability-review.md # 对照主流 OA 的能力清单与缺口
├── docs/hub-integration.md # 统一身份(Hub)登录校验、免登、权限对接与用户同步的配置文档
├── docs/person-reference-design.md # 「这个人是谁」存什么:只存也只认登录账号,认不出就不是一个人
├── docs/attachment-preview.md # 附件与审批随附文件的预览设计(三条渲染路线、接口、编码、错误分级)
├── docs/llm-integration.md # 大模型接入:服务商目录、报文协议、密钥口径、代理直连与排障
├── docs/llm-usage-design.md # 大模型怎么用:AI 助手页设计 + 全系统落点、红线、分期与验收设计
├── docs/integration-master-plan.md # 外部系统集成总方案:入站取数 / 额度管控 / 审批后反写三条线的总图与排期
├── docs/form-data-integration-design.md # 表单字段从外部系统取数:五种形态、数据源注册表、快照口径与分期
├── 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 # 上面两篇的说明书:谁在哪个界面配哪一栏、对方要调什么、配完怎么验、出问题查哪一行
├── docs/quota-control-design.md # 额度管控:预算与备用金的台账、在途占用核销、提交时超支判定
├── docs/outbound-integration-design.md # 审批通过后反写业务系统:反写环节、幂等重试、对账与补偿
├── docs/node-writeback-config.md # 中间环节写回怎么配:到达时 / 审批通过后 / 被退回时 / 被撤回时、只发部分单据、失败卡控与边界
├── docs/goback-target-writeback-design.md # 「本环节被退回时」再筛两道:退回到哪个环节才发、这一退是谁按的(含第三方调接口退回)
├── docs/integration-contract.md # 给上游看的接口契约:字段、金额单位、幂等键、批量与对账口径
├── docs/expense-thirdparty-field-update.md # 费用报销:财务在第三方改审定金额怎么回写 OA(decide 带 data、生产配置与可写字段清单)
├── docs/platform-open-api-design.md # 开放平台:外部系统调 OA 的钥匙 / 作用域 / 限流 / 留痕,与事件推送的分工
├── docs/notification-channels-design.md # 消息渠道:邮件、三家群机器人、自定义回调,与经 Hub 代发的企业微信应用消息;投递留痕、退避重试与死信
├── docs/mobile-pwa-design.md # 移动端:为什么是 PWA、离线外壳只兜底不缓存接口、底部导航与安全区
├── 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:四条路线、命名与权限口径、分期与验收(方案)
├── docs/nas-file-access-design.md # 在 OA 里直接打开 NAS 文件:权限权威源与判定、服务账号护栏、NAS 账号与 OA 账号对齐
├── docs/starter-submit-action-design.md # 驳回之后发起人那颗钮:为什么是「同意」,凭什么改成「提交」(判据一处、只改说法不改账)
└── design/ # 单文件静态设计稿(浏览器直接打开):index.html 整体视觉、ai.html AI 助手与场景嵌入
快速开始
1. 准备数据库
无需手工建库。本机开发默认读测试档,确认 backend/config.dev.toml 的 [database]
指向可连通的 MySQL 即可(部署机上对应的文件是 config.prod.toml,见「多套环境」一节):
[database]
host = "192.168.124.202"
port = 3306
user = "root"
password = "unissense"
name = "unis_oa"
首次启动会自动 CREATE DATABASE、建表并写入种子数据。若目标账号没有建库权限,
先手工建库,或直接执行 sql/schema.sql。
建库这一步有白名单卡着:[database] create_allowlist(OA_DB_CREATE_ALLOWLIST),
一个环境一个库,出厂默认只有 unis_oa,生产档在自己的配置里点名 unis_oa_prod。
目标库不存在、而库名不在白名单里时后端直接启动失败并说明怎么改,不会在 MySQL 上
凭空多出一个库——库名打错一个字就多一个全套表 + 演示数据的库,这种库没人认领也说不清
来历(2026-10 一次性攒出过六个)。库已经存在时这道闸不管事,照常连;
填 * 是不设限的口子。需要临时库的工具不走这条路:一律自己 CREATE、
收尾自己 DROP,所以临时库是"删掉之后自己建回来"的——少建这一步,那套实例会直接
拒绝启动。共享库上平时只有开发库一个。
用户表是 users(字段:id account email password_hash display_name avatar_url
organization_id role status last_login_at created_at updated_at,接了统一身份再
加 source hub_user_id hub_synced_at 三列镜像列),id 与部门表 oa_unit.id 都是
BIGINT UNSIGNED 自增主键,status 取 1=active / 0=disabled / 2=pending / 3=rejected,
只有 1 能登录;source 取 local(本地建的号,同步永不触碰)/ hub(统一身份同步来的号)。
部门表 oa_unit 用同一套口径:code(组织编码)+ status(1=启用,其余为停用,
取代原来的 enabled 开关),同步来的部门另带 hub_org_id。
个人收款账户单独一张 oa_bank_account(account bank_name pay_account):开户行名称与
收款账号是 Hub 不下发的本地数据,人在「个人资料」里自己填,报销、打款那一类单据取的就是这一行。
它按 users.account 挂,所以账号跟着 Hub 改名时这一行会随改名一起搬走(和按账号/姓名存的审批岗位
走同一套搬运,见 docs/hub-integration.md)。故意不建外键:users
行删得掉(删人带 force),而同步改的正是 account 这一列本身,写上 REFERENCES users(account)
会让每次账号改名都被外键顶回去、整趟人员同步失败;删人时那一行跟着删,见 api/org.py::delete_person。
接口出入参用的是同一套列名:人员对象返回 display_name / avatar_url /
organization_id / status,部门名与部门路径是派生字段 organization_name /
organization_path,人员列表的筛选参数是 keyword / organization_id / status / role。
组织与人员的同步口径见 docs/hub-integration.md:身份只认 Hub 的
user_id(本地账号会跟着 Hub 改名,按账号/姓名存的审批岗位也会跟着搬),部门骨架归 Hub、
负责人与简称等扩展字段归本地;权限与角色配好之后再跑全量同步不会掉权限,口径与例外见
docs/hub-integration.md §6.3。
已经跑过老结构(oa_person + 32 位十六进制主键)的库,用下面的命令就地升级,
脚本会先把老表整表导出到 sql/backup/,再搬数据并把散落在流程、日志、附件里的
旧 id 引用改成新 id:
cd backend
python3 scripts/migrate_to_users_table.py --dry-run # 先看会动哪些列
python3 scripts/migrate_to_users_table.py # 真正迁移
python3 scripts/migrate_identity_refs.py --dry-run # 配置里还压着身份 DN 的引用(岗位角色成员等)
python3 scripts/migrate_identity_refs.py # 换成登录账号(写库前整表备份进 backups/)
python3 scripts/migrate_identity_refs.py --runtime # 运行态与历史行那一档(待办/待阅/站内信/日志)
python3 scripts/dump_schema.py # 刷新 sql/schema.sql
2. 配好文件存放位置
上传附件与首页信息资讯的附件固定走 MinIO(网盘暂不考虑,固定本地磁盘),
MinIO 的连接信息写在 backend/config.toml 的 [storage.minio]:
[storage.minio]
endpoint = "192.168.124.210:9000" # 只写 主机:端口,不带 http://
access_key = "minioadmin"
secret_key = "minioadmin"
bucket = "unisoa" # 需先在 MinIO 控制台建好
upload_path = "unisoa" # 上传路径:文件都落在桶里这个目录下
也可以先跳过这步:启动后端后进「系统管理 → 系统设置 → 文件存放位置」, 在页面上填地址、账号、密码和上传路径,点「测试连接」再点「保存」—— 存进数据库,下一次请求就按新参数走,不用重启、也不用改文件。 没配好之前不会挡启动,文件先落本地磁盘。详见《文件存放位置》。
传上来的附件与审批意见随附的图片/文件都进 MinIO,并且在流程里直接预览:图片、PDF、
音视频由浏览器直出,Word / Excel / PPT / 文本 / Markdown / CSV 由后端读出正文、前端按
类型渲染,压缩包和 .doc/.xls/.ppt 只给下载。审批时既能选文件也能直接 Ctrl/⌘+V
贴截图。设计细节见 docs/attachment-preview.md。
3. 启动后端
cd backend
pip install -r requirements.txt
python3 -m uvicorn app.main:app --host 127.0.0.1 --port 8000
# 或: ./scripts/dev-api.sh (默认 0.0.0.0:8000)
4. 构建并使用前端
cd frontend
pnpm install
pnpm build # 产物 frontend/dist,由后端 SPA 托管
打开 http://127.0.0.1:8000 即可,无需第二个端口。
前端热更新开发(可选):pnpm dev 默认跑在 3000 端口,/api、/v1、/setup
反代到 http://127.0.0.1:8000,可用 VITE_DEV_PORT / VITE_DEV_PROXY_TARGET 覆盖。
5. 重新部署
改完后端要重启(未开 --reload);前端改完 pnpm build 即可,同一端口刷新生效。
响应头策略由后端给出,直接 pnpm preview 或换 Nginx 时需保持一致:
| 路径 | Cache-Control |
原因 |
|---|---|---|
/assets/*(Vite 带内容哈希) |
public, max-age=31536000, immutable |
文件名即版本号,永不相同内容同名 |
index.html 与其余非哈希文件 |
no-cache |
每次校验,避免部署后拿到旧 app shell |
部署后旧标签页里的路由仍指向已被替换的哈希 chunk,点击会取到 404。
src/router/chunkReload.ts 捕获这类加载失败,对未完成的这一次跳转做整页重载,
拿到新的 index.html 自愈;同一目标只重试一次,防止死循环。
配置项
配置分两层,各管各的事:
| 层 | 放在哪 | 什么时候读 | 改了要不要重启 | 怎么改 |
|---|---|---|---|---|
| 引导配置 | backend/config.toml + config.<环境名>.toml |
启动时读一次 | 要重启 | 编辑当前环境的配置文件 |
| 运行配置 | 数据库 oa_system_setting 的 config:{组} 行 |
取值时现读(进程内快照,默认缓存 2 秒) | 不用重启,保存即生效 | 系统设置页 / PUT /api/v1/config/{组} |
引导配置(14 项,改了要重启)
都是「还没连上数据库就必须知道」的东西:MySQL 在哪、进程听哪个端口、JWT 用什么密钥签。 界面上它们只读,并写着「改这里要重启」。
| 配置项 | 配置文件里 | 环境变量 | 默认值 |
|---|---|---|---|
| MySQL 地址 | [database] host / port |
OA_DB_HOST / OA_DB_PORT |
127.0.0.1 / 3306 |
| MySQL 账号 | [database] user / password |
OA_DB_USER / OA_DB_PASSWORD |
root / 空 |
| 库名 | [database] name |
OA_DB_NAME |
unis_oa |
| 启动时自动建表 | [database] auto_create_schema |
OA_AUTO_CREATE_SCHEMA |
true |
| 允许新建的库名 | [database] create_allowlist |
OA_DB_CREATE_ALLOWLIST |
unis_oa(库不存在且名字不在这里 → 启动失败,不建库) |
| JWT 密钥 / 算法 | [security] jwt_secret / jwt_algorithm |
OA_JWT_SECRET / OA_JWT_ALGORITHM |
开发值 / HS256 |
| 监听地址 | [server] host / port |
OA_HOST / OA_PORT |
0.0.0.0 / 8000 |
| 初始超管 | 账号与口令都在数据库里;配置文件只在首次建号时用 [seed] admin_account / admin_password 兜底 |
OA_ADMIN_ACCOUNT / OA_ADMIN_PASSWORD |
admin / admin123(本部署改名 localadmin,把 admin 让给统一身份;账号名记在 system.admin_account,见 hub-integration.md 5.1) |
| 是否种演示数据 | [seed] demo_data |
OA_SEED_DEMO |
true |
这 14 项各环境必然不一样(库地址、密钥、要不要种演示数据),所以写在当前环境那一份
配置文件里,公共的 config.toml 不放。文件缺失或写错都不挡启动,全部回落默认值并在日志里说明。
多套环境:本机测试档,部署时选生产档
同一份代码要在自己机器、测试机、生产上跑,就用环境分档的配置文件,用 OA_ENV 说一声
跑在哪一档。每一档读两份,后一份逐段盖在前一份上面(深合并:环境文件里只写跟公共值
不一样的键,没写的沿用 config.toml):
| 文件 | 谁用 | 里面写什么 |
|---|---|---|
config.toml |
所有环境 | 公共基础值:档位开关、站点名与描述、签名算法、监听地址端口(等于内置默认值的键不再抄进来,全量见 config.toml.example) |
config.dev.toml |
本机 / 测试(OA_ENV 没设时的默认档) |
测试库地址账号、开发 JWT 密钥、演示数据开关、MinIO(本地管理员与应急名单已改存数据库,不在这里) |
config.prod.toml |
生产 | 生产库、真密钥、demo_data = false、生产 Hub 与免登两件套(app_code / integration_key)、MinIO(从模板复制,不进仓库) |
config.test.toml / config.staging.toml |
想要就加 | 文件名里的环境名随便起,OA_ENV 写什么就读 config.<那个>.toml |
仓库里现在已有一份填到能直接起服务的 config.prod.toml:生产库名与测试库分开
(unis_oa_prod,避免手滑连错库)、JWT 密钥与超管初始口令都是新生成的随机值、
demo_data = false,Hub 与统一门户免登的键(base_url / directory_key / app_code /
integration_key)也照 config.dev.toml 的口径配齐了。只剩两样只能找 Hub 管理员领:
生产站点的目录密钥(文件里现在那把在 https://hub.oa.unissense.tech 上会被拒)与免登
应用密钥(现在留空,填上免登才是开着的)。里面每条 TODO 都是上线前要动的地方,
OA_ENV=prod python3 backend/scripts/what_config.py 会先把引导配置那几条替你过一遍。
| 想干什么 | 怎么做 |
|---|---|
| 本机开发 | python run.py 或 ./scripts/dev-api.sh,什么都不用设,默认 OA_ENV=dev |
| 部署用生产档 | OA_ENV=prod ./scripts/prod-api.sh;systemd 里给进程一个 OA_ENV=prod;容器部署见「用 Docker 部署」 |
| 写全名 | OA_ENV=production、OA_ENV=staging 都认(大小写无所谓) |
| 配置文件不放代码目录 | OA_CONFIG_DIR=/etc/unisoa,去那儿找 config.toml 与 config.<环境名>.toml |
| 只认某一个文件 | OA_CONFIG=/etc/unisoa/config.prod.toml,此时只读它,分档文件一概不看(老用法与测试脚本用这个) |
生产档(prod / staging / gray)启动时会做一轮上线体检,下面这些一看就是开发值的
引导配置会在日志里点名,系统设置页顶部也会红字列出来:占位或空的 JWT 签名密钥、
还开着演示数据、MySQL 账号没口令、内置超管还是默认口令。只提醒不拦启动,先把服务
起得来才谈得上改配置。
怎么确认线上用的到底是哪一份。 四个地方都会告诉你答案,从"还没起服务"到"服务跑着了":
| 什么时候 | 怎么看 |
|---|---|
| 起服务之前 / 发版后自查 | python3 scripts/what_config.py(不连库、不起服务,纯按环境变量算给你看) |
| 启动日志 | 第一行就写着档位与读了哪几份文件,scripts/prod-api.sh 起的服务还会在 exec 前先打一遍 |
| 服务在跑、想机器确认 | GET /api/v1/system/info(要登录)里的 bootstrap.env 与 bootstrap.layers |
| 界面上看 | 系统设置页底部「引导配置」卡片:紫色徽章是当前环境名,下面列出叠了哪几份文件 |
what_config.py 的输出长这样,哪一项的出厂值来自基础文件还是本环境文件都写着:
$ OA_ENV=prod python3 scripts/what_config.py
环境 prod(OA_ENV=prod)
这一档算生产,启动会做上线体检
主文件 /srv/unisoa/backend/config.prod.toml
配置文件 按顺序叠,后一份盖在前一份上:
[读到] /srv/unisoa/backend/config.toml —— 公共基础值,各环境共用
[读到] /srv/unisoa/backend/config.prod.toml —— 本环境差异,逐键盖在基础值上
MySQL prod-db.internal:3306/unis_oa 账号 oa 口令已配 自动建表关 (本环境文件)
令牌签名 已配(64 位,本环境文件) 算法 HS256
上线体检 全部通过
加 --check 就有体检告警时返回退出码 1,可以在上线脚本里当闸门
(scripts/prod-api.sh 也认这个:OA_STRICT_CONFIG=1 OA_ENV=prod ./scripts/prod-api.sh)。
服务起来后的日志是这个样子:
config: 环境=prod(OA_ENV 没设时默认 dev),配置文件按顺序叠:/etc/unisoa/config.toml[读到] + /etc/unisoa/config.prod.toml[读到]
WARNING 上线体检:【prod】JWT 签名密钥还是出厂的占位值 change-me-in-production:请在 config.prod.toml 里改掉…(OA_JWT_SECRET)
最容易踩的一种情况是忘了给 OA_ENV:默认档是 dev,服务会安安静静连测试库起来。
上面任何一处看到 环境=dev 就是这个原因,systemd 里补 Environment=OA_ENV=prod 即可;
用 scripts/prod-api.sh 起的话它本身就默认 prod,不会漏。
分档还带来一个常用动作:把生产配好的表单与流程搬一份到测试环境,用
backend/scripts/migrate_design.py。它按 config.<档位>.toml 各连一条库,源库那条会话一开就
是 READ ONLY 事务(真往里写会被 MySQL 顶回来,脚本自己也只发 SELECT),目标库先把要动的行
整包备份成 gzip JSON,再一个事务写完,任何一步报错整体回滚:
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,不是名字。审批人存的
是角色名 / 部门名 / 登录账号,所以两个环境各自的人和组织一行都不用搬,脚本只把落地后点名点
不到的角色、部门、账号如实报出来。目标库多出来的一律不删(这是搬迁不是清理),已存在的
整行覆盖;唯一反过来的是审批角色的成员名单——测试环境通常故意把「总经理」这类岗指给测试
账号,所以只补缺的角色、不拿生产的真员工盖下去。
上线步骤(部署机上):
cd backend
cp config.prod.toml.example config.prod.toml # 填生产库、jwt_secret、Hub、MinIO
OA_ENV=prod ./scripts/prod-api.sh # 或者 systemd/docker 里设 OA_ENV=prod
容器里更省事的写法是密钥一个都不写文件,全用环境变量注入(OA_DB_PASSWORD、
OA_JWT_SECRET、OA_MINIO_SECRET_KEY……),配置文件只当兜底 —— 环境变量本来就是最高一层。
机器扛不住时先加 HTTP 进程数,就一个变量:OA_WORKERS=4 ./scripts/prod-api.sh
(写在配置文件的 [server] workers 也一样,默认 1,不设就是现在这样)。它只加 HTTP
进程,延时唤醒、Hub 同步、写回投递这些后台任务仍只有一个进程在跑,不用怕重复发凭证。
返回体不小的只读接口实测 1 → 4 进程能到三倍吞吐,发起与审批这类写路径基本不涨。
那笔连接账(进程数 × 池子 vs max_connections)与实测数字在
docs/multi-worker-deployment.md 第 5.1 节;启动时后端自己会把账算一遍,超了就在日志里喊。
两份文件各写哪些项:仓库里的 config.toml 与 config.dev.toml 都只写跟内置默认值不一样
的项,以及运维要一眼看到或偶尔要动的开关;其余项不写就是内置默认值。
全量清单在 config.toml.example,每一项旁边都有中文注释与环境变量名;
生产档的骨架(含上线清单)在 config.prod.toml.example。
老版本的 backend/.env 与 backend/storage.toml 已经退役:引导配置与运行配置的出厂值都收进了
分档配置文件(config.toml + config.<环境名>.toml)一处,界面能改的那些则进了数据库。
这两个文件已从仓库删掉,如果部署机上还留着,
后端启动时会在日志里提醒一句「不再被读取」然后忽略它们,不会被误当成生效配置。
运行配置(123 项,存库即生效)
| 组 | 界面上的名字 | 项数 | 都管什么 |
|---|---|---|---|
site |
站点信息 | 5 | 站点名、Logo、描述、系统访问地址(发出去的邮件与群消息里的单据链接用它拼全链接)、是否开放注册 |
security |
登录令牌 | 3 | 访问令牌分钟数、刷新令牌天数、空闲多久要求重新登录 |
hub |
统一身份登录 | 33 | Hub 地址与开关、九个接口各走什么路径、登录模式(含只允许门户免登)、验 token、免登三件套(应用编码 / 应用密钥 / 门户地址)、目录密钥与服务端凭证、Hub 不回话时的两道自保闸(冷却秒数与同时等待上限,见 docs/hub-integration.md §14)、应急总闸… |
approval |
审批口径 | 1 | 是否严格按环节配置找人(关掉会往上级与部门兜底) |
hub_sync |
组织人员同步 | 25 | 定时同步总开关(只在界面上配,文件与环境变量不认)与排期(频率 / 时间 / 每周哪几天 / 每月哪几天 / 间隔分钟)、失败补试、增量同步(周期 / 单批条数 / 落后回全量)、停用策略、单次人数上限、按编码认领本地部门、账号让位、三条熔断底线(离职停用人数底线 / 部门停用个数底线 / 让位名单的清单人数下限)… 都在「同步定时任务」这一页配 |
ai |
大模型能力 | 3 | 调不调大模型的总闸、失败补试次数、日志里记不记提示词原文 |
hub_perm |
统一身份权限 | 16 | 从 Hub 取角色 / 权限码 / 数据范围。默认关:关着时权限完全按本系统角色矩阵走 |
storage |
文件存放位置 | 16 | MinIO 地址账号密钥桶与上传路径、本地根目录、大小与扩展名限制、超时 |
outbound |
对外发送 | 3 | 消息渠道总闸(关掉只留站内信)、事件推送总闸(关掉不再往外部系统推流程事件)、开放接口调用留痕保留天数。开关在这里,"发到哪个邮箱、推给哪个地址"在「消息通知」与「开放平台」两个页面里配 |
redis |
共享缓存与限流 | 13 | 启用总闸、连接串或五项分开填、键前缀、读写超时、连接池上限、限流计数走不走 Redis、失效通知走不走 Redis、字典选项共享多久。没填照样跑,退路见 docs/redis-integration.md |
server |
跨域与接口 | 1 | cors_origins 允许的来源 |
每一项的取值优先级固定是:
环境变量 OA_* > 数据库(界面上保存过的) > config.<环境名>.toml > config.toml > 代码默认值
三条规矩值得记住:
- 配置文件里的值不入库。启动只读一遍当前环境的配置文件做统计,不往库写一个字;
config:*行里永远只有你在界面或接口上真正保存过的那几项,而且是逐键存 —— 保存site_name只动site_name,同组其它项不跟着落库。想把某一项改回配置文件里的 出厂值,保存时把值传null(界面上的按钮叫「改回出厂值」),那一行空了就整行删掉。 - 环境变量最高,并且会钉住这一项。
OA_*设了值就压过库和文件,配置页把该项标成env_locked(输入框禁用并说明是哪个变量),页面底部还会列出全部生效的变量名。 容器 / CI 注入密钥走这条路,docker -e也能覆盖。 - 密钥只进不出。
minio_secret_key、hub_service_token、hub_service_password在任何只读接口里都只回空串加一个secret_set布尔;保存时留空 = 沿用旧值, 不是清空(真要清空得先在界面上点「改回出厂值」)。操作日志里也只记改了哪一项,不记密钥值。 大模型接入的api_key是同一套口径,只是它存在oa_ai_provider而不在config:*里 (见 docs/llm-integration.md)。
常用的运行配置环境变量(完整 58 项的名字与环境变量对照,GET /api/v1/config 里每一项都带着,
config.toml 里也逐项写了注释):
| 变量 | 默认值 | 说明 |
|---|---|---|
OA_SITE_NAME / OA_SITE_LOGO / OA_SITE_DESCRIPTION |
见 config.toml |
站点名 / Logo / 描述 |
OA_REGISTER_ENABLED |
false |
是否开放自助注册 |
OA_ACCESS_TOKEN_MINUTES / OA_REFRESH_TOKEN_DAYS |
720 / 30 |
令牌有效期(新签的令牌立刻按新值发) |
OA_SESSION_IDLE_MINUTES |
0 |
空闲多久要求重新登录(分钟),0 = 不启用。对接统一门户后建议开:Hub 登出不会回收本系统已建的会话。开了之后访问令牌有效期会被压到不超过这个窗口 |
OA_CORS_ORIGINS |
localhost:3000 | 允许的来源,逗号分隔;本机任意端口始终放行 |
OA_MAX_UPLOAD_MB / OA_ALLOWED_EXTENSIONS |
200 / 不限 |
单文件大小上限、扩展名白名单 |
OA_MINIO_ENDPOINT / ..._ACCESS_KEY / ..._SECRET_KEY / ..._BUCKET |
空 | MinIO 连接 |
OA_MINIO_UPLOAD_PATH |
空 | 上传路径(对象键前缀) |
OA_STORAGE_FALLBACK |
true |
MinIO 连不上时是否退回本地磁盘 |
OA_LOCAL_ROOT |
storage |
本地磁盘落盘根目录 |
OA_HUB_ENABLED / OA_HUB_BASE_URL |
false / 空 |
统一身份(Hub)总闸与地址 |
OA_HUB_LOGIN_MODE |
hybrid |
hub 只认 Hub / hybrid 优先 Hub、挂了回退本地 / sso 只允许统一门户免登(不收账号密码)/ local 不查 Hub |
OA_HUB_LOCAL_ACCOUNTS |
admin |
应急通道:这些账号只用本地口令登录,账号名也不被统一身份接管(本部署填 localadmin) |
OA_HUB_DIRECTORY_KEY |
空 | 拉全量组织人员的长期密钥,随请求头 X-Directory-Key 带出,同步就靠它 |
OA_HUB_SERVICE_TOKEN(或 OA_HUB_SERVICE_ACCOUNT + ..._PASSWORD) |
空 | 老的 Bearer token 口径,没配目录密钥时才用 |
OA_HUB_SYNC_WHEN / OA_HUB_SYNC_TIME |
daily / 01:00 |
定时全量同步的频率(daily/weekly/monthly/interval)与时间点,配套 ..._WEEKDAYS / ..._MONTHDAYS / ..._INTERVAL_MINUTES(见「同步定时任务」)。「允许定时同步」那个总开关不在这里,只在界面上配 |
OA_HUB_SYNC_OFFBOARD / OA_HUB_SYNC_MEMBER_LIMIT |
true / 5000 |
Hub 消失的人是否停用 / 单次人员上限 |
OA_HUB_SYNC_OFFBOARD_GUARD_PERCENT |
40 |
离职停用熔断:一趟里等着停用的人超过本地同步账号总数的这个百分比(且超过 20 人)时,这一趟一个都不停用,只报数并标成 partial;0 = 关掉。Hub 换环境/重导数据时不至于把整家公司判成离职。同一个百分比也管部门:要停用的部门超过 max(5, 同步部门数 × 百分比) 时一个都不停 |
OA_HUB_SYNC_RECLAIM_LOST_ACCOUNTS |
true |
僵尸账号让位:已停用、且这一趟完整清单里查无此人的同步账号,把登录名腾开(改成 hub-lost-<user_id>-<原名>,人与权限都不动),Hub 的现任主人当趟就能拿回账号名。只在人数对得上的全量同步里生效:增量事件、被截断或突然缩水的清单(Hub 正在清库/重导)一律不让位 |
OA_HUB_SYNC_BIND_LOCAL_BY_CODE |
true |
本系统自建的部门若编码与 Hub 某个部门一一对上,就认成同一个部门(补 hub_org_id),不另建重名部门 |
OA_HUB_DIRECTORY_NEEDS_TOKEN |
false |
老口径:目录接口除密钥外还要带 Bearer token 时打开 |
OA_HUB_PASSWORD_MANAGED_BY_HUB |
false |
密码归 Hub 管,本地不再设/改登录密码 |
OA_HUB_APP_CODE + OA_HUB_INTEGRATION_KEY |
空 | 免登两件套:Hub 注册应用时给的应用编码与应用密钥明文(票据校验用,随 X-Integration-Key 带出),三项凑齐(含 base_url)免登才生效 |
OA_HUB_SSO_ENABLED / OA_HUB_SSO_STATE_REQUIRED / OA_HUB_PORTAL_URL |
true / false / 空 |
免登开关 / 是否只认从本系统发起的免登(比对 state)/ 统一门户首页(留空用 base_url) |
OA_HUB_PERM_ENABLED / ..._MODE / ..._APPLICATION_ID |
false / shadow / 空 |
统一身份权限:开关 / shadow 只对照、enforce 以统一身份为准 / 问哪个应用的权限(留空用免登那个应用编码) |
OA_HUB_PERM_CACHE_SECONDS / ..._SCOPE_MODE / ..._ADMIN_QUERY / ..._KEEP_LOCAL |
60 / merge / true / true |
按人缓存秒数 / 数据范围取较大还是照抄 Hub / 没有本人令牌时由服务端代查 / Hub 没给可识别权限码时保留本地权限 |
OA_HUB_PERM_PATH_ROLES / ..._PERMISSIONS / ..._DATA_SCOPE / ..._DIRECTORY_SCOPED |
见文档口径 | 问「我自己」的四条:角色、权限码、数据范围、按数据权限导出组织人员 |
OA_HUB_PERM_PATH_ADMIN_ROLES / ..._ADMIN_PERMISSIONS / ..._ADMIN_ROLE_PERMISSIONS / ..._ADMIN_USER_ROLES / ..._ADMIN_USER_DATA_SCOPE |
见文档口径 | 服务端代查与权限目录登记用的五条({role_id} / {user_id} 调用时填值) |
OA_HUB_SYNC_CHANGES_ENABLED / ..._INTERVAL_SECONDS / ..._LIMIT |
true / 45 / 200 |
增量同步:按游标轮询变更流水的开关、周期(秒)、单批条数 |
OA_HUB_PATH_CAPTCHA / ..._LOGIN / ..._VERIFY_TOKEN / ..._ME / ..._DIRECTORY |
见文档口径 | Hub 登录侧九条接口路径里的头五条,Hub 换前缀或挂网关时改这里 |
OA_HUB_PATH_DIRECTORY_CHANGES / ..._TICKET_VERIFY / ..._APPS / ..._LAUNCH |
见文档口径 | 另外四个:变更流水、免登票据校验、可见应用列表、发起免登跳转({code} 换成应用编码) |
OA_HUB_DISABLED |
false |
应急总闸:打开后登录与同步一律回本地。界面上就能切(系统设置 → 统一身份应急总闸,保存即生效);这个变量一旦设了值,界面上的开关会被钉成灰的 |
OA_HUB_SYNC_LOCKED_ACCOUNTS |
admin |
只读名单:统一身份的管理员账号在 OA 里不许改、不许停用、不许删(内置超管另外永远只读) |
OA_CONFIG_CACHE_SECONDS |
2 |
进程内配置快照的存活秒数;多实例部署时想跟得更紧就调小 |
改完多久生效
本进程保存成功后快照立刻失效,同一次请求返回里就带着新值;其它进程(多 worker、多实例)
最多 OA_CONFIG_CACHE_SECONDS 秒后自己跟上,也可以直接 POST /api/v1/config/reload 强制重读。
跨域来源由中间件每个请求现读,存储客户端按配置指纹重建,Hub 配置每次现拼 ——
所以附件落点、上传上限、Hub 开关、令牌有效期、跨域名单这些改完都不需要重启。
配置相关的接口(除 /settings/public 外都要登录,写操作要 system:setting):
| 接口 | 作用 |
|---|---|
GET /config |
全部 7 组配置:值、中文说明、范围、每一项的来源(env/database/file/default) |
GET|PUT /config/{组} |
读 / 保存一组。{"values": {"项": 值}},值传 null = 改回出厂值 |
POST /config/reload |
丢掉进程内快照,立刻重读库 |
GET|PUT /hub/config |
只操作 hub + hub_sync 两组(统一身份的专用入口) |
GET /settings、PUT /settings/{key} |
老接口,仍按 site / storage 等键读写,值与 config:* 同一份 |
GET /system/storage、POST /system/storage/test、POST /system/storage/reload |
存储配置、探活(可带未保存的参数先试)、重读 |
GET /system/info |
一眼看清:配置在库哪张表、revision、缓存秒数、生效的环境变量、每组存了几项 |
统一身份(Hub)的登录校验、定时同步与一键同步的全部配置项、落库规则和排障清单, 见 docs/hub-integration.md。 大模型接入的目录、协议、密钥口径与排障清单,见 docs/llm-integration.md。
用 Docker 部署
镜像是代码 + 前端产物,配置和密钥不在镜像里:backend/config.*.toml 被
.dockerignore 整个排除(只留不含密钥的 backend/config.toml 当低一层基础值),
真东西运行时挂进 /etc/unisoa。所以同一个镜像可以从测试一路推到生产,
换档不用重新打包。
一键起来:
cp backend/config.prod.toml.example deploy/config/config.prod.toml # 填生产库、密钥、Hub、MinIO
docker compose up -d --build # 档位已在 compose 里写死 OA_ENV=prod
docker compose logs | head # 看 config: 环境=prod 那一行,确认叠了哪几份
docker compose exec unisoa-api python scripts/what_config.py # 随时再自查一遍
不想用 compose 就自己 docker build -t unisoa:latest . + docker run,
参数照 docker-compose.yml 抄(-e OA_ENV=prod、配置目录只读挂载、storage 卷)。
用哪一档:两个开关,随你用一个。 优先级是环境变量 > 文件:
| 开关 | 在哪 | 什么时候用 |
|---|---|---|
OA_ENV=prod |
docker-compose.yml 的 environment,或 docker run -e OA_ENV=prod |
默认走这条。compose 里那一行改成 staging 就读 config.staging.toml |
[env] name = "prod" |
挂载目录里的 deploy/config/config.toml |
不方便传环境变量时改文件即可,仓库里这份已经写着 prod;OA_ENV 一旦给了就以它为准 |
配置文件在容器里叠四层,后一份盖在前一份上(OA_CONFIG_DIR=/etc/unisoa 已烤进镜像):
| 顺序 | 路径 | 谁提供 | 放什么 |
|---|---|---|---|
| 1 | /app/backend/config.toml |
镜像(跟代码同版本) | 公共基础值,各环境共用,不含密钥 |
| 2 | /etc/unisoa/config.toml |
挂载目录 | 只写覆盖项,通常只有 [env] name;不想要这层可以删掉 |
| 3 | /app/backend/config.prod.toml |
镜像 | 永远没有——密钥文件不进镜像,这一层是空的 |
| 4 | /etc/unisoa/config.prod.toml |
挂载目录 | 本档全部真东西:库地址账号口令、jwt_secret、Hub 目录密钥、MinIO |
口令也可以完全不落盘,在 compose 的 environment 里注 OA_DB_PASSWORD /
OA_JWT_SECRET / OA_MINIO_SECRET_KEY(环境变量是最高一层,压过所有文件)。
what_config.py 在容器里跑出来长这样,一眼能看出连的是哪台库、密钥来自哪份文件:
$ docker compose exec unisoa-api python scripts/what_config.py
环境 prod(环境变量 OA_ENV=prod)
这一档算生产,启动会做上线体检
主文件 /etc/unisoa/config.prod.toml
配置文件 按顺序叠,后一份盖在前一份上:
[读到] /app/backend/config.toml —— 公共基础值,各环境共用
[读到] /etc/unisoa/config.toml ——
[缺这档] /app/backend/config.prod.toml ——
[读到] /etc/unisoa/config.prod.toml —— 本环境差异,逐键盖在基础值上
MySQL prod-db:3306/unis_oa 账号 oa 口令已配 自动建表开 (本环境文件)
上线体检 全部通过
只想临时试一把,用 OA_CONFIG=/etc/unisoa/x.toml(只读那一份,分档文件一概不看)。
上线想拿体检当闸门:OA_STRICT_CONFIG=1 + python scripts/what_config.py --check,
有告警就退出码 1。
几个坑,都是实测踩过的:
| 坑 | 说明 |
|---|---|
| 时区 | 审批超时、定时同步时间点、单号日期都按 datetime.now() 算。镜像已把 TZ=Asia/Shanghai 与 tzdata 烤进去;自己换基础镜像重打时记得带上,否则 01:00 的同步会挪到北京时间 09:00 |
127.0.0.1 不是宿主机 |
容器里的 127.0.0.1 是容器自己。MySQL / MinIO 在宿主上就写局域网地址或 host.docker.internal,[database] host 照抄本机测试档那份会连不上 |
storage 卷权限 |
进程以 uid 10001 跑。命名卷(compose 里的 unisoa-storage)没问题;Linux 上换成宿主目录直挂要先 chown -R 10001:10001 那个目录,否则网盘文件与 MinIO 兜底写不进去 |
docker exec 里的自查 |
入口脚本没 -e OA_ENV 时自己兜 prod,而 docker exec 起的进程只看到容器环境,会照 config.toml 的 [env] name 报档位。想两边口径完全一致就给容器一个 -e OA_ENV=prod(compose 里已经给了),要么就统一用文件那个开关 |
| 配置目录只读 | :ro 挂进去的,容器写不了(故意的,免得密钥被进程改)。要在界面改的运行配置一律进数据库,不写文件 |
| 依赖装不上 | 前端是 pnpm 11(package.json 的 packageManager 钉版本,Node 24 起),构建脚本白名单在 frontend/pnpm-workspace.yaml 的 allowBuilds。国内网络用 --build-arg NPM_REGISTRY=https://registry.npmmirror.com --build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple 提速,compose 里已经带上,境外构建删掉那两行即可 |
| 探活 | 健康检查打的是匿名接口 /api/v1/settings/public,不登录就通;关掉统一身份、开着维护开关都不影响它,别换成需要登录的地址 |
镜像里没有任何环境的口令。发版前想确认一遍:
docker run --rm unisoa:latest python scripts/what_config.py,
默认档 dev 会直接报「档位 dev 的差异文件一个都没找到」,说明确实没带进去。
演示账号
| 账号 | 密码 | 姓名 | 部门 | 角色 |
|---|---|---|---|---|
admin |
admin123 |
系统管理员 | 综合管理部 | 超级管理员(并担任总经理审批) |
zhangsan |
123456 |
张三 | 研发中心 | 普通员工(流程里的部门审批人) |
lisi |
123456 |
李四 | 研发中心 | 普通员工(人事备案) |
zhouba |
123456 |
周八 | 研发中心 | 普通员工 |
zhaoliu |
123456 |
赵六 | 综合管理部 | 普通员工(流程里的部门审批人) |
sunqi |
123456 |
孙七 | 财务部 | 普通员工(财务审核) |
wangwu |
123456 |
王五 | 市场部 | 普通员工 |
「权限角色」列是菜单/接口/数据范围的权限(见下方《权限角色》),种子数据把 admin 放进
超级管理员、其余 6 人放进 普通员工。它与岗位角色(oa_role,供流程环节的候选人生成规则
使用)是两套东西,互不影响。想验证效果,把某人加进内置的 部门负责人(本部门及下级 + 流程监控
- 统计分析)即可,菜单和数据会立刻跟着变。
内置两条已发布流程:
- 请假申请:填写申请 → 条件分支(
days > 3走总经理审批,否则直达人事备案)→ 人事备案(或签)→ 结束 - 费用报销:填写报销 → 并行网关(部门审核 + 财务审核·会签)→ 汇聚网关 → 条件分支(
amount >= 5000总经理复核)→ 出纳付款 → 结束
与 O2OA 的对应关系
| O2OA(Java) | 本项目(Python) |
|---|---|
x_processplatform_core_entity content.Work / Task |
models.Work / models.Task(oa_work / oa_task) |
content.WorkCompleted / TaskCompleted |
oa_work_completed / oa_task_completed(办结后从活动表迁出) |
content.Read / ReadCompleted |
oa_read / oa_read_completed(待阅件) |
content.Draft / Attachment / Handover |
oa_draft / oa_attachment / oa_handover |
content.SerialNumber |
oa_serial_number(YYYYMMDD + 6 位流水) |
element.Activity + Begin/Manual/Choice/Parallel/Merge/Split/Script/Invoke/Embed/Delay/End/Cancel |
oa_activity,由 engine/engine.py 逐类型实现 |
element.*Properties(ManualProperties 等) |
oa_activity.config(JSON) |
element.Form / File |
oa_form |
element.Application |
oa_process |
ticket.Tickets / SignalStack |
engine/tickets.py + oa_work.tokens |
x_processplatform_assemble_designer |
api/design.py |
x_processplatform_assemble_surface |
api/runtime.py |
x_processplatform_service_processing |
engine/engine.py + main.py 内的延时/超期调度线程 |
x_processplatform_core_express |
engine/expressions.py(受限表达式求值) |
x_processplatform_assemble_bam |
api/support.py 的统计接口 |
x_organization_core_entity |
models.Unit/User/Identity/Role/Group + service/org.py(人员账号落在 users 表) |
x_organization_core 的角色与访问控制(UnitPerson + role/admin) |
models.AuthRole PersonAuthRole + api/authrole.py,权限码见 app/permissions.py |
x_cms_assemble_control(信息资讯/栏目) |
models.CmsChannel CmsDocument + api/portal.py |
x_hotpic_assemble_control(热点新闻) |
oa_cms_document.is_hot,首页 hotpics 字段 |
x_meeting_assemble_control(会议与邀请答复) |
models.Meeting MeetingAttendee |
x_calendar_assemble_control(日程) |
models.Schedule(shared_identities 多人可见) |
x_file_assemble_control(网盘) |
models.PortalFile + app/storage/(网盘固定落本地磁盘) |
x_component_Homepage(首页装配) |
GET /portal/home 一次拉齐 + components/portal/* |
首页门户
对齐 O2OA 首页(x_component_Homepage)的布局与内容源,一个请求 GET /portal/home
拉齐五块面板,切换 tab / 翻页时才打各自的列表接口:
| 面板 | 内容 | 对应 O2OA 模块 |
|---|---|---|
| 待办中心 | 待办 / 已办 / 已阅 / 拟稿 / 我发起的 五个 tab + 发起流程(待阅那一格随待阅列表一起撤了:抄送 / 转发就在待办那一格里,红点也在) | x_processplatform_assemble_surface |
| 信息资讯 | 热点新闻轮播 + 按栏目的最新信息 + 更多信息 | x_cms_assemble_control x_hotpic_assemble_control |
| 我的会议 | 我的会议 / 会议邀请两个 tab,接受 / 拒绝(带确认框)、取消会议 | x_meeting_assemble_control |
| 日程 | 月历(有日程的日期带圆点)+ 当日列表 + 「{姓名},您好!今天您有 N 个日程」 | x_calendar_assemble_control |
| 网盘文件 | 列表 + 上传 + 下载,按人员引用(登录账号)共享 | x_file_assemble_control |
布局与 O2OA 一致:右列日程通高,左列 2×2 为「信息资讯 / 我的会议」+「待办中心 / 网盘文件」, 窄屏自动折成一列。配套的持久页面在侧栏「门户中心」分组下:信息资讯、我的会议、我的日程、网盘; 管理员另有「系统管理 → 信息发布」(含栏目管理)。
- 会议、日程、网盘的可见性一律按人员引用判定,共享对象存登录账号数组(口径见 docs/person-reference-design.md;只存也只认登录账号,对不上账号的字符串不当成一个人)
- 组织者是自动到场的参与人(
role=organizer、status=accepted),取消会议是软删 - 信息正文按 HTML 存储,前端用 DOMPurify 白名单过滤后渲染
- 写权限:栏目与信息只有管理员能改;会议 / 日程 / 网盘按归属人或管理员
- 封面图片按资讯的落点走存储层(默认 MinIO,
minio://<bucket>/<上传路径>/portal/cover/…),oa_cms_document.cover存的是 uri 而不是文件名;GET /cms/documents/{id}/cover走存储层回读, 老数据里裸文件名会自动回退到local://portal/cover/再找一次。两条上传入口 (POST /cms/covers、POST /cms/documents/{id}/cover)都走同一个store_cover。 首页热点封面由assets/portal_covers/经app.seed.stage_cover交给存储层, 换图后python3 scripts/gen_portal_covers.py重新生成即可自动同步
文件存放位置
三类文件的落点在代码里定死,界面上不再让用户挑选:
| 用途 | 落点 | 说明 |
|---|---|---|
| 表单「上传附件」 | MinIO | 每次上传都走对象存储 |
| 首页「信息资讯」(封面 + 正文附件) | MinIO | 同上 |
| 「网盘」文件 | 本地磁盘 | 网盘暂不接对象存储 |
所以真正要配的只有 MinIO 的连接参数与两个存储护栏,共 15 项,全在 storage 组里:
出厂值写在 backend/config.toml 的 [storage] / [storage.local] / [storage.minio]
(逐项中文注释),界面上改过之后就存在数据库里,改完立刻生效。
| 配置项 | 出厂值在哪 | 说明 |
|---|---|---|
minio_endpoint / minio_access_key / minio_secret_key / minio_bucket |
[storage.minio] |
地址只写 主机:端口,不带 http://;桶要预先建好 |
minio_upload_path |
[storage.minio] upload_path |
上传路径:对象键前缀,留空放桶根 |
minio_secure / minio_region / minio_presigned_ttl_seconds / minio_public_base_url |
[storage.minio] |
可选项;presigned_ttl_seconds>0 时下载走预签名 |
minio_connect_timeout_seconds / minio_read_timeout_seconds |
[storage.minio] |
连不上时多久放弃 |
local_root |
[storage.local] root |
本地后端的落盘根目录,网盘与兜底都写这里 |
max_upload_mb / allowed_extensions |
[storage] |
单文件上限与扩展名白名单,两个都是存库即生效的准入闸门 |
fallback_to_local |
[storage] |
MinIO 连不上时退回本地磁盘并告警;改成 false 就宁可上传失败也不落错地方 |
对象键布局是 <上传路径>/<用途>/<YYYYMM>/<uuid>.<ext>,数据库里只存 uri
(minio://bucket/key、local://相对路径),不存绝对路径 —— 所以后期换 MinIO、
改上传路径、甚至整体退回本地磁盘都不用洗库,先前已经落下的对象按各自 uri 继续读。
MinIO 没配全(缺 endpoint / access_key / bucket)时不会挡启动:日志里警告一句,
fallback_to_local=true 就落本地磁盘。设置页顶上有 MinIO 与本地磁盘两个探活状态,
「测试连接」还能带上表单里尚未保存的参数先试再存。
设置页的接口都要 system:setting:GET /system/storage 看配置与探活、
PUT /config/storage 保存(写进 oa_system_setting 的 config:storage 行)、
POST /system/storage/test 探活、POST /system/storage/reload 强制重建存储客户端。
三条安全边界值得记住:
- SecretKey 只从请求进、不从响应出。
GET只回secret_key_set布尔值,保存时该字段 留空表示沿用旧值;其余字段「没出现」= 不改、「出现且为空串」= 用户真的清空了。 - 配置项存的是数据库,
GET /system/storage会一并回config_path(库里的哪一行)、bootstrap_file(出厂值那份文件)、revision和env_overrides/env_locks清单, 被OA_MINIO_*之类环境变量占用的键会直接列出来,免得对着一个改了不生效的输入框纳闷。 - 每次保存都往操作日志写一条
config_update,记下是谁在什么时候改了哪一项; 日志里只有地址、桶名这类非敏感值,不会带 SecretKey。
上传产生的对象不会在桶里越攒越多:资讯换封面时上一张会被删掉,删除资讯时封面一起删,
编辑到一半放弃时前端调用 DELETE /cms/covers 把先上传的那张放掉。仍然留在桶里的对象
只有真正被引用的那些;老数据里指向别处的 uri 不受影响。
信息资讯的附件
「制度、方案」这类信息不必把全文抄进正文,直接传文件就行。附件单独记在
oa_cms_attachment(不复用流程那张 oa_attachment:那张表挂的是 job / work / activity,
语义完全不同),字节走同一个存储网关,落点 <上传路径>/portal/attachment/<YYYYMM>/<uuid>.<ext>,
默认 MinIO。一条附件可以先上传后挂接(POST /cms/covers 那套「先传后存」照搬过来),
所以编辑到一半关页面不会在桶里留下垃圾:挂在草稿上没被认领的附件,下次上传时顺手清掉超过
24 小时的。
正文与附件的关系只有一条规则:oa_cms_document.body_attachment 指定「以这份附件为正文」,
没指定且正文为空时自动取第一个附件。详情页据此决定是把图片 / PDF 直接摊开、还是给一张
「可预览可下载」的文件卡片,列表与首页则用回形针角标提示「这条有附件」。
删除是双向对称的:从附件列表里摘掉一条,行和对象一起删;删除整条资讯,附件先清干净再删正文;
换正文附件时旧的那份照删。唯一的例外是同一份字节被别处引用着(比如同一张图既是封面又是
别的资讯的正文附件),这时只删引用不删对象——判定来自 app/service/storage_gc.py 的
references(),它会把 LOCATION_COLUMNS 注册表里所有存 uri 的列都扫一遍。
删除失败(MinIO 抖动、网络断了)不让它悄悄丢掉:对象删不成就把 uri 记进
oa_storage_pending_delete 等下次补删,设置页与 GET /system/storage 都会显示这条
「待补删」计数,POST /system/storage/sweep 手动催一次,正常路径上每次删除也会顺带重试
旧账(有节流)。
python3 scripts/audit_storage.py 是这套回收机制的体检工具,默认只报告不动手:
python3 scripts/audit_storage.py --prefix portal # 列出桶里没人引用的对象与库里指向别处的 uri
python3 scripts/audit_storage.py --prefix portal --delete # 删掉孤儿对象(只碰满 24 小时以上的)
python3 scripts/audit_storage.py --retry # 只补删待删账本
python3 scripts/audit_storage.py --fix-legacy # 老数据里的裸文件名 / 绝对路径补成 local:// uri
python3 scripts/audit_storage.py --to-minio # 把本该进 MinIO 却落在本地磁盘的文件搬进去
年龄闸门(--min-age-minutes,默认 1440)是为了不误伤正在上传的对象:一个刚传上来、
还没挂到任何记录上的附件,在账本眼里和孤儿对象长得一模一样。网盘的文件始终被排除在
--to-minio 之外——那是配置上就定死走本地磁盘的。
表单设计
设计中心 → 表单设计 里可以直接建表单,字段类型见 utils/formLayout.ts 的 FIELD_TYPES
(44 类,按 基础录入 / 选择类 / 选人 / 附件 / 系统带出 / 排版占位 五段摆在左侧字段库里,
每一类存什么值、条件能比什么、明细列能不能用,全在 docs/form-field-catalog.md),
支持上移 / 下移 /
复制 / 删除,每个字段可配字段名、类型、必填、只读、占位提示、说明文字,数字字段另有最小值 /
最大值 / 步长 / 小数位 / 单位。
-
「值还没到时框里写什么」只有一栏说话:
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现拼,只读、打印、导出同一句。 这一格长什么样由配的人挑(字段上的pickerStyle,与设计器里「挑选方式」同一套取值): 下拉多选(默认,半行放得下)、弹出框多选(手机上好点,点确定才写回)、平铺点选 (12 个月摊开,一眼看全,代价是一整行)。回归PYTHONPATH=. python3 scripts/check_months_style.py。 -
这一轮长出来的 8 格:
richtext富文本(存 Markdown 原文,右边看排版)、month月份、year年份、timerange时间段、week星期、location定位、group分组标题、spacer空白占位;另外把手写签名摆回了左侧字段库——它的控件、只读态、导出、打印 早就写好了,唯独字段库没登记,于是界面上谁也加不出这一类字段(META现在标成Record<FieldType, ChipMeta | null>,漏登记 typecheck 直接红)。 -
老组件长的三样本事:文本那三类(
text/textarea/richtext)能配字数上限与 校验正则(按整格匹配,re.fullmatch);附件与图片能配允许类型 / 最多几个 / 单个多大; 日期区间与时间段会判起止先后,颠倒的提交挡下。前端挡的是体验(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 §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 §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 §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 §6 第 4 条)。顺带一件小事:配了逐行 取数的那一列就算勾着「只读」,也不再被「锁着却没有任何来源」那句黄字念——那一格的答案本来就是 查出来的,锁着才对。设计见 docs/form-data-integration-design.md §9.2 与 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 §2.9,钉在FormRenderer.tableReadonlyStyle.spec.ts与FieldInspector.tableReadonlyStyle.spec.ts。 -
定位不接地图服务:
location存浏览器原生定位给的经纬度 + 一句人写的地址 ({lng, lat, address}),因为本平台没配任何地图 key。台式机 / 没授权 / 非 https 页面 取不到位置时,只写一句地址也算填了(locationFilled↔formruntime.location_filled)。 -
清单分叉的闸门:同一份类型清单散在前端 5 处、后端 4 处,以前少改一处不会报错, 只会在界面上悄悄少一格。
utils/fieldCatalog.spec.ts直接读后端源码把两边对齐钉成断言: 类型全集、明细列清单、"没有录入控件"那份、能力分组、中英两名、明细列底宽,一处不点名就不算过。 -
嵌别的系统的页面(
type: embed,已实现):同一个功能不必在 OA 再开发一遍,把对方系统的页面直接嵌进表单这一格。 设计定稿在 docs/embed-page-field-design.md——地址与密钥只在外部数据源注册表里 (provider=embed,设计者没有手填 URL 的地方)、参数由后端渲染(参数名白名单就是那条源自己声明的 那几份模板——地址模板那一档就是地址本身,接口那一档算上请求体与请求头,没写{arg.x}的名字拼不进去)、 免登走一次性短码且以看单那个人 的身份进去、上线前先探一次X-Frame-Options/frame-ancestors,探不通就整块退成一张「新窗口打开」 的卡片而不是留个白框。地址有两种来路(url_mode):照那条源的地址模板拼,或者先调对方的接口、 用它回的那条链接(§2.4)——对方那一页是按这张单现生成的(同样的参数下次就是另一个链接)时只有这一条路; 这一档只多一道闸:取回来的链接只认这条源登记过的来源,其余口径(调用在后端、参数后端算、 熔断限流留痕)与取数共用同一份,kind=link的留痕让"接口没答话"和"页面打不开"是两句可对答的话。这一格不产生值(连地址快照都不存,那条地址上挂着免登短码),但它的key是环节字段权限的挂点——发地址之前后端按当前人和当前环节重算一遍可见性,挡住也留痕。 要带过去的那几格还空着时这一页根本不打开:段头与卡片上说出「先填:申请人、报销月份」, 那一次注定挨一句xxx is required的取链接请求也不发(发出去还要记进熔断那本账); 属性面板「什么时候能让这一页打开」可改成「任何时候」,判据与例外见 docs/embed-page-field-design.md §6。 只读场合(已办、代看、单据详情、我的发起)默认是「只沿用已有那一页」(embed.readonly=auto,三档:button一次都不问 /auto只认库里已有那一页 /frame一律现问):这一屏只问一句"库里有没有 对面那一条地址",有就地嵌进来,一次建页接口都不打、一条短码都不发、一笔留痕都不记;没存过就 还是那张卡片,不替你在对面新建一页——要建就点卡片上那颗「打开」,点了就地嵌。这一档存在的理由 是那句原话:"点开嵌入页面还是不能直接在表单中展示"与"只是看一眼,对面又多一份草稿"两头都要顾:frame顾前者不顾后者,button反过来,auto只在已经有那一页时才装框。认不出的值退回auto。 打印那一份不吃这一档,纸上印不出 iframe,也犯不为一张纸发一条短码。 回看屏那一句请求还多带viewOnly=true,两句都只让后端少做事 / 只往严收窄:给的是配置的 查看页那一条地址(link=auto因此不再问"他手上还有没有待办"),而当前环节把这一格设成 「隐藏」不再把这一屏拒在门外——过去回看屏吃的那句"这一格在当前环节是隐藏的"说的本来是 "办这一环的人不必看它",不是"连发起人从此不许看见它";办理屏照旧挡,两边说同一句话。 判据在service/embed.py:readonly_of与utils/formRuntime.ts:embedReadonly(同一份三档), 契约在EmbedLaunchBody.reuse_only/view_only,钉它的是backend/scripts/check_embed_readonly_auto.py与EmbedFrame.readonly.spec.ts。 自动加载之后紧接着那一问是每次打开是不是同一趟:那一屏必须把job递到这一格上, 否则后端把这次打开当成「发起页、还没单据」,会话落进最宽那一档(人 + 格子 + 源),{auto:serial}那几位还算成空值,每点开一次就换一个预受理号——对面系统里就是新的一页、 多一份没人认领的草稿(WorkDetailView.vue那句:job与FormRenderer.readonly-embed.spec.ts一起钉着这件事)。默认口径是接上同一趟,并且复用这一刻把存活期按这次打开往前推一次。 紧接着还有第二问,而且是生产上撞出来的那一句:「我在后面节点打开嵌入页面查看的时候,发现又 帮我新建了一个草稿在第三方系统中。后面的节点难道不应该看的就是第一次返回的那个查看页面么?」 ——会话是按人认的,而对面那一页原来只记在第一个打开它的人那一趟上,于是换一个人点开就是 第二张草稿。现在那一页单独记在这张单上(oa_embed_page:源 + 格子 + 单唯一一行, 活得和这张单一样长),后面每个环节、每个来看的人都回到第一次建出来的那一页, 一次接口都不打(linkShared+linkPage说的是"那一页是谁在哪一环建的"); 换人仍然新开一趟——共用一页不等于共用凭据,预受理号、令牌、decide各是各的。 属性面板那一栏因此是三档(embed.reopen):只用第一次那一页(默认)/ 每个人各用一趟 (旧口径same,对方按打开的人建东西才要)/ 每次开新的一页(new)。 反过来那一问是这一页能不能操作,四档(embed.interactive):一直能操作(默认)/ 只在发起那一屏能操作(start,治"开始节点能填、其余环节只许看",不用逐环节勾权限)/ 跟着环节权限走(perm,去「表单与字段权限」里给这一格点只读,「全部只读」那颗也连它一起锁)/ 一直只展示(view)。点不动那几档是真的把鼠标事件收掉(pointer-events: none), 并且当场说一句为什么点不动。对方那一页「什么按钮都点不动」也可能是沙箱少给了一项, 属性面板「这一页在框里还能做什么」按项放开(embed.sandbox,六项白名单, 确认框 / 下载 / 整页跳转那一类),而不是把整串sandbox交给人手填。 还有第三问是递哪一条地址(embed.link):对方那个接口每调一次建一张页、一次回好几条 地址(编辑页 / 查看页,有时还有打印页那种)时,默认「按人自动选」(auto)只在"这张单的 发起人、且此刻还有他要做的事"那一个人身上给编辑页,审批人 / 已办 / 代看 / 办结回看一律 查看页;edit/view两档是明确要谁都一样时才用,此外还能点名要源上另外登记的那几条 ——登记在源上(url_links:键名 + 给人看的名字 + 它在响应里的位置或地址模板),属性面板 那个下拉的候选就从那一份长出来,能挑哪几条永远等于管理员登记了哪几条。 判据在后端(service/embed.py:link_kind_for),/embed/launch回的link与linkName说的是实际给出去的那一条,以及它在管理员那里叫什么——这一格要的那一条这条源给不出时 会退回edit并说实话。上面那句"给不出"原来只覆盖"这条源没配那一栏",漏了生产上真撞的那一式: 「在我的发起、我的已办中点开流程,嵌入的页面无法打开」。那条源(url_mode=api)一次回两条, 填报页data.fill_url与审阅页data.review_url,而单据没进审阅之前审阅页回的是空串—— 「键在、值是空的」原来被当成"这一栏配歪了、取不到",于是"要的那一条配了位置却没取到"= 整次打开失败,界面收到一句「那个接口没有回链接」;而只读场合按口径一律要审阅页, 结果是流程在途时谁都打不开,配得越对越打不开。现在空串说的是"对方这一趟没有这一页", 走退路并回linkWanted(这一屏要的是哪一条)与linkAbsent(那一条是对方没回,不是没配), 那一框下面那句灰字因此说得清是"等一等就有"还是"去把那一栏补上"。 这一档也多了一档专门治"只读场合还去递建页接口":「发起那一屏之外都给查看页」 (embed.link=start)只问一条判据——这一屏手上有没有这张单。发起页给填报页让他接着填, 单据一存在(我的发起 / 我的已办 / 待办审批页 / 办结回看)一律查看页,连发起人自己也一样 (auto那一档在他还有代办时给他填报页,管不了这一句)。 那几条一次调用全部取回、钉在这一趟的会话上(oa_embed_session.url_extra,早先那两列url_edit/url_view还在):第一次问回来就存下,同一趟再打开一次接口都不打 (linkReused),「打开一次就在对面新建一页」断的就是这一句;沿用的是"这一屏要的那一条 已经有了"这个前提,所以要的是查看页、存过的却只有填报页、而这一栏在这条源上确实配了位置, 就再问一次(service/embed.py:build_url里那一句stale)——不然"等对方有了那一页, 再点开就是它"永远兑不了,那正是「已经进审阅了,已办里点开还是填报页」;多问的那一次只用来 补空,认过的那几条不被顶掉(同一张单上这一格始终指同一张页,与stamp_links只补空 同一把尺子),问不成也照旧递手上那一页,不把已经能看的那一屏关在门外;同一张单换到后面的节点、 换成另一个人点开也一次都不打(那一页在oa_embed_page上,linkShared), 要带的值换了且这一格翻成reopen=same、这一格翻成reopen=new、这一趟过期或被放弃, 才重新问一次。同一次响应里那几个不是地址的值 (如data.flow_number)可以在源上「顺手带回的那几个值」(url_meta)点几个名,摆到那一框 下面当一行灰字看,只读,不进单据数据——要往单子里写字得走取数或回写那两条正路。 那一串data.printUrl不必背:接口取链接那一档把「响应里有哪几栏」摊成人能挑的清单—— 服务端service/fetch.py:sample_paths摊那一次真调用回来的响应(「测试连通」回的paths, 配置页上那颗「看有哪几栏能挑」就是它),浏览器utils/jsonPaths.ts摊贴进「样例响应」的那段 JSON, 两边写的都是fetch.pick_path认的那一种;components/oa/design/PathPicker.vue拿这份候选把 「链接在响应里的位置」那几格换成下拉(选项后面跟着那一栏此刻的值),摊不出来就还是输入框。 回写那一侧同样有份能对答的东西:GET /embed/sources回remoteKeys——这条源最近真回传过的 键名(回写留痕里只存名字,值一个字不入库),属性面板「对方字段名」那一栏靠它当候选。 部署闸门在[embed](总闸 / CSP / 附加来源 / 短码秒数);口径由backend/scripts/check_embed.py与frontend/src/utils/embed.spec.ts钉着。 两条数据通道都通了:进来的除地址模板那份参数之外,填单人改了引用的那几格还会推oa:params(不重载那个页面,值变了只标一句「还是按旧值打开的」);出去的是oa:result回填——默认关, 属性面板点过名的格子才收,再过"这一格在当前环节露不露、这个人本来改不改得动"那几道闸并按类型 收值,挂额度与阈值的格子一律不收(外部系统只能提供值,不能决定流转)。协议与对接那份照抄清单 在 docs/embed-page-field-design.md §5.1 / §5.2 / §11.1, 口径由frontend/src/utils/embedBridge.spec.ts与backend/scripts/check_embed_api.py钉着。 -
嵌进来的那一页能替人做哪几件事(已实现):回填只解决「把值搬进来」,剩下三件它搬不动—— 流程创建页还没保存就返回了、双方按哪一号对上话;第三方那一页操作完了怎么触发 OA 发起; 第三方自己审完了怎么算这一步通过。补的那一层是嵌入会话(
oa_embed_session): 免登短码 60 秒、用一次即烧,只回答「站在屏幕前的是谁」,而这三件事都需要一个跨调用稳定、 能指代「那一趟打开」的东西。会话带两份对外可见的东西——会话令牌(凭据,只存哈希、可作废) 与预受理号prekey(话题,印在对方工单上、电话里念得出来;未保存的发起页上那是双方唯一 共有的标识,建议当成第三方草稿表的外键)。四条分寸一条都不是审美问题: 能力由后端算(embed_session.scopes_for:这一格勾了哪几件事 + 这条源配没配应用密钥 + 此刻这个人有没有待办,前端与第三方都只是被告知);令牌只在验票那一刻交付(配了密钥的源, 前端一个凭据都摸不着——浏览器那句「说话的是我刚装载的 frame」证明得了 frame 是谁, 证明不了拿钥匙的那台机器是谁);发起去重是双向的(第三方拿bizKey=prekey调POST /open/works会被认成重复并回原单,人在 OA 里点了发起也会把这张单记回那一趟, 两个方向都挡住才不生第二张);回写审批只说方向不说出口(agree/refuse/submit, OA 按这一环真实存在的出口用最长匹配判边——「不同意」里含着「同意」,按「含不含」判会把 驳回出口匹成同意,三个出口的环节会真走错分支而两边日志都写着成功;匹不唯一就回候选不猜)。 落格与办理全部走原来的路:值经回填那五道闸,办待办经engine.execute_task,环节字段权限、 必填、额度、闸门一条都不因为「来的不是浏览器」少跑。 反着的那一档也在:人在发起页没保存就返回时,OA 可通知对方删掉它按预留单号建的那张草稿 (DELETE+ 一个单号键,凭证就是双方共用那把密钥)。配置只有一处:那条「可嵌入页面」上 一次选择——挑一条现成的写回通道(地址、方法、鉴权、什么算发成功都照它),或直接填地址; 表单那一格默认不参与,只留一句「这张单不发」。发不发仍由后端判,已发起、挂着 OA 草稿、 那个号落在别的草稿上,一律不发(删错草稿比不删糟得多),404 按「那边没有这张单」记成功。 配法(配在数据源、配在表单那一格、第三方调哪三条接口)与整套取舍在 docs/embed-action-design.md,照着配的那份说明书(谁配哪一栏、 每栏填什么、排查表)在 docs/embed-configuration-guide.md, 对方那一面的口径在 docs/integration-contract.md §7.1;口径由backend/scripts/check_embed.py(含出口匹名那一段、「这一页被放弃时通知对方」那一段,以及 「说明书与代码同源」那一段——说明书里那些环境变量名、接口路径、消息名、那一档的那几个 配置名一旦和代码漂开就红)、backend/scripts/check_embed_api.py(段名「这一趟的凭据与那三档 回写」,注册表那一段还钉着「通知挑错了记录」那几种配法)与backend/scripts/check_embed_decide.py(真流程真待办,末尾那几项钉的是那句删草稿的通知 发得对不对、那个值取哪儿、能不能骑在地址上、什么情况下不该发)与backend/scripts/check_embed_abandon.py(那三条腿的入口:POST /embed/abandon、POST /embed/link-draft+DELETE /draft/{id}、POST /job/{job}/delete真通到判据;新开的那 一页不许复用「已发起成一张单」那一趟的旧账——复用了就会被「这一趟已经发起成一张单」挡下, 界面上样样正常而对面那张草稿永远没人删;过期又没人报时兜底补一次、且只补一次;删一张还没 发起的单发出去的那一句,方法、地址与请求体那几栏与删草稿那一条配的是同一份,号取这张单的 单号,同一个号一次删除只通知一次)钉着。 第三方替人发起之后OA 这一屏自己会走(生产那句:"在嵌入页面中我点击提交后,OA 系统会生成 一条已发起流程,但是创建中的本条流程还停留在编辑页面,并没有刷新或者关闭正在创建的页面, 这会让人误解流程并没有发起。"):对方报一句话过来就当场问一次「这一趟成单了吗」并按 0.4 / 1.2 / 3 秒追问几拍(对面成单要过他们自己的后端,前后差一两秒,只问一次容易问早了), 平时那一拍从二十秒一路收到两秒——问的是POST /embed/state,一次查库,不打对面那个建页 接口、不发短码、也不记"打开"留痕,而且只在发起页、还没成单、页面在眼前这三条都成立时才跑。 对方那边点提交那一刻最准的一句话是新加的oa:submitted(§嵌页面的那几条浏览器消息): 它不动 OA 任何数据、不逼对方带 nonce,发的就是"我刚交了,你去看一眼",那一屏因此是 当场问、当场走,而不是等下一拍;没发这句的对接方靠两秒那一拍也只是一两秒的事。 问到之后发起页收起「发起」那颗(再点就是一张重复单)、把单号与发起时间摆出来,并 立刻replace到那张单的详情页——原来是数八秒,实际效果是让刚听见消息的人在屏幕前 多坐八秒;那句交代改挂在跳转之前的一次 toast 上(toast 归全局那层,跳过去之后还在, 人落到详情页看见的是「已发起 + 单号」)。跳不过去时(别的闸拦了这次 replace)那块牌子 就是全部的交代。判据在frontend/src/components/oa/EmbedFrame.started.spec.ts(那几拍、两秒那一拍、oa:submitted与"已经发起就不再问")与frontend/src/views/oa/StartFormView.spec.ts(当场跳走、 那句交代只说一次、跳不过去时牌子还管事), 后端那一句「这一趟成单了吗」由backend/scripts/check_embed_view_link.py末尾那几项钉着。 -
数字金额的「单位」(
number/money/formula与明细表的这两类列):只是贴在数字框 里侧的那一小截灰字后缀(1,200.00 元后面的「元」),不是值。填成一个数字(曾被填成11) 就分不清是单位还是填单人自己填的数,所以设计器就地报错、保存与/validate一起挡 (formruntime.unit_problem,前端镜像在utils/formRuntime.ts),渲染这层还兜一道display_unit:库里已经躺着的老表单不会被追溯重写,配歪的一律不贴、退回默认单位。 -
手写签名(
type: signature):审批人在待办里用鼠标 / 触控板 / 手指直接签, 控件是components/oa/SignaturePad.vue(笔画轨迹可撤销、容器变宽不糊),值以 PNG 的 data URL 随单据存进data。只读态渲染成图片,打印单一起出,导出 CSV 时只落「已签名」 而不会把 base64 灌进表格。 -
候选来源、显示与存值、挑选方式(
select/picker/radio/checkbox/relation共用一套,主表与明细列同一份口径):一格的候选从哪儿来(field.optionSource:手填选项 / 数据字典 / 流程单据 / 外部数据源)、这一行给人看哪一列、往数据里存哪一列 (field.optionMap:labelKey/valueKey,写成value、job、extra.spec、data.报销金额这种点路径)、 用什么姿势挑(field.pickerStyle:下拉选项 / 弹出框 / 平铺,或auto让它自己选)、 每种姿势各看哪几列(field.picker:下拉那一档与弹出框那一档各配主显示列 / 副标题几列 / 行尾徽标,弹出框还有搜索框开关、搜索列、每页条数、标题——纯展示,存出去的值一个字都不变) 是四个各自独立的维度,字段类型只管这一格装单个值还是一串值。 以前这是三条互不认识的路:选项手填在options、绑一本dictCode、关联审批单自己一条relationProcess,于是「下拉框想要能搜索、带副标题的弹出框」和「关联审批单想挂一张物料字典」 都没有入口。现在都在components/oa/design/OptionSourcePanel.vue那一栏里配完:先挑来源, 来源下面就地配它自己的东西(手填的选项一条两格:显示文字与存的值 / 哪本字典带级联上级 / 哪个流程 / 哪张列表型数据源,数据源那儿还有一个「试搜一页」当场看上游通不通), 再一栏定「显示为 / 存为」(components/oa/design/OptionMapEditor.vue,拿一条真候选演出 「显示「螺栓 M8」,保存 M1」),同一栏里再按「下拉里 / 弹出框里」两档各配一遍看哪几列 (切换的是同一批候选,改的是这一行长什么样),最后一栏定挑选方式,勾得上「可以选好几个」。 左侧摆成两格组件:「下拉框」(select) 只挂表单自己的数据(手填选项 / 数据字典), 「下拉选择」(picker) 只挂别处的数据(外部数据源 / 流程单据)——同一只挑选器、两种定位。 定位是设计器给挑的清单(OFFERED_SOURCE_KINDS),不是技术边界:sourceKindsOf那一份 四类来源都认,老表单里「下拉框挂了数据源」照旧读得出、渲染得动,设计器下拉里也把 「此刻在用的那一条」留着(sourceKindChoicesOf),只是新配的字段各按定位挑。 「关联审批单」不再单列一格——它就是「来源 = 流程单据」那一格,老表单照旧渲染。 控件也只剩一只components/oa/OptionPicker.vue,三种姿势画的是同一只输入框——样式收在全局.field-trigger,Select与新的ComboTrigger.vue共用一份:下拉点开是一列选项(多于 5 条自己出 搜索框,远程来源改成按需搜;勾了「可以选好几个」就是多选下拉——行首一颗勾、勾完不收起、 挑中的挂在框里一颗一颗摘,明细那种窄格子只留一颗、其余收进「+N」),弹出框点开才有搜索与 「一行两到三样信息 + 状态角标」(多选时已选的挂在那只框里,点一下摘掉),平铺就是原来那排 radio / 多选,编辑与只读同一套回显。多选下拉跨页挑中的那几条靠Select的known念得出名字—— 搜出来的来源手上只有这一页,被下一次搜索冲掉不等于没选中。 「存哪一列」不是只管显示:判越界、字典带出、标题与导出翻译、条件分支与联动的候选值、 给 AI 起草的合法取值、写回报文的枚举翻译都按存的那一列算(dicts.stored_of/shown_of), 级联上级存的不是编码时先翻回编码再比归属(parent_codes)。界面上直接不给、保存也挡的 硬规矩只剩一条:搜出来的候选不给平铺(摊开的前提是知道一共多少条)。 「一串值的格子不给下拉」以前也在,那是因为一只Select只装得下一个值;现在它会画勾选框了, 三种姿势都装得下一串值——勾不勾「可以选好几个」只改变默认哪种姿势(候选在手里的给下拉、 搜出来的给弹出框),不改变能挑哪几种。取值把关跟着来源走:手填与字典照旧判「值必须在候选里」, 流程单据与外部数据源不判——服务端手上永远只有搜出来的那一页,照它清值会把人刚选中的 单子清成空。换来源时上一家那几格一并清掉(optionSourcePatch/api/design.clean_option_source, 只动明写过optionSource的字段,不替历史做主);optionMap同理——跟默认一模一样的不留、 这一来源给不出的列不认,退回默认列渲染。口径前端在utils/optionSource.ts+utils/optionMap.ts、后端在service/dicts.py(source_kind_of/constrains_values/stored_of/shown_of),设计期检查formruntime.option_source_problems, 设计取舍见 docs/option-source-design.md。 候选来源=外部数据源时还能带上下文入参(field.dataSourceArgs,写{form.x}就按同一张表单里 别的格子筛候选,搜索走POST /data-source/options,老 GET 留给移动端与开放接口)。它和 「字段上的外部取数」是两个配置项——一个管挑(值域,取不到不挡人)、一个管写(取值,取不到就 留空并标原因),但底下共用同一层内核(service/binding.py+utils/binding.ts):取值写法、 多源清单与合并、「那张源还在不在 / 停用没停用 / 是不是列表型」只此一份判据。两边各自都配得对、 凑一起会咬人的配法也在保存这一刻就说:值由外部取数写入而候选又是判越界的手填 / 字典(提交时 必定拦在填单的人面前),以及候选入参引用了不存在的字段。取舍见 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 §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,钉在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取同样的写法。两头一个字都没写,上游每次收到的就是同一句话, 界面上看到的不是「配错了」而是「搜索框搜不动」(2026-11 生产上 SCC 商机那一格:地址写死, 2434 条商机每次全量回来)。SQL 通道例外,:keyword由后端每次替它绑上(service/sqlsource.py); 样例数据与流程列表两条通道根本没有「上游按关键词搜」这回事,不提醒。判据只此一份 (utils/binding.ts.searchKeywordReachable,后端那条兜底在service/fetch._body_has_keyword), 配源那一屏当场说得出来——地址下面与「入参」那一页各一句,并给一键把写法补到地址末尾, 钉在DataSourceView.spec.ts;到线上一趟的回归在check_fetch_url_args.py末尾那一段——那一段 顺带把「调用留痕里看不见搜的是什么」也修了:keyword撞上了「键名里有key就当密钥抹掉」 那条规则(fetch._looks_secret),排查搜索问题翻留痕时只看得到一次次空入参。 -
关联审批单(
type: relation):把别的单据挂到这张单上,存的是对方job。 今天它就是「候选来源 = 流程单据、挑选方式 = 弹出框」那一格,表现跟以前一模一样: 挑选走GET /work/related,回显走GET /work/summaries(按这一格配的存值列认回单据:界面把by(存的是哪一列)与process(限的哪条流程)一起报过去,于是跳转与「存为」选哪一列无关),relationProcess限定只允许挂某个流程的单。 候选按「这是谁发起的」收(field.relationScope):默认created只列我发起的单据, 不再把一批我只是批过 / 被抄送过的别人的单也摊出来(管理员也一样,这一档问的是事实不是权限); 想回到老口径就选related(我发起 / 我办过 / 我被抄送那一片)。这一档只管候选列不列它, 已经挂上的那几张照旧念得出名字(回显不跟着收窄)。 那一行还能读对方表单里的某一格(列名写data.字段名):以前候选只有标题 / 单号 / 流程名 / 发起人 那四列,几张「某某发起的报销申请」摆在一起认不出人;现在「显示为 / 存为」与两档展示列 (主显示 / 副标题 / 徽标 / 搜索列)都能挑那条流程表单里的字段,设计器列清单的是GET /design/data-sources/process-fields(与关联带出问的同一句)。点了哪几列才把表单正文读回来、 且只回点名的那几列(GET /work/related?fields=…,一行最多 8 列),翻成人话走的是导出那把尺 (exportfmt.cell_text:字典编码落名称、附件落文件名、明细表压一行),回的是嵌套形状, 前端按点路径直接读。两条的口径与取舍在 docs/option-source-design.md §12。 挂上来的每一条都点得开:只读那排标签的名字、编辑态挂在框里的标签、下拉里那颗标签、 单选时框里那一句话,名字上挂的都是/work/:job(target="_blank"——看完整张单退回来, 手上填的这一张还在)。PC 与手机共用这一条路由(WorkDetailView自己按设备换手机版那一屏), 所以手机上一样打得开;手机上那三屏(摘要两版 + 「完整单据」mobile/MobileFormReader.vue) 以前把 job 原样摊成一串码,现在都走同一只OptionPicker的只读态(收成mobile/MobileRelationValue.vue,判据useFormPlan.opensWork),念回标题、点得开那张单, 明细里那一列关联的流程也一样。只有「来源 = 流程单据」这一条给链接;存的是 job、单据编号、 还是限定流程之后对方表单里那一格,都认得回同一张单(GET /work/summaries的by/process, 取舍见 §13),实在认不出是哪张单才宁可不给(processHref)。 这一排的牌子还收了一号字(.picker-dense,11px):单据标题太长,默认字号两三个就占满一行, 而全局那条.field-tag是人员选择器与附件共用的,不动它。取舍见 docs/option-source-design.md。 挑流程不再在一长串流程名里翻:先选流程类型、再在那个类型里选流程 (components/oa/design/ProcessPicker.vue,类型带条数、没归类的单独一档「未分类」、草稿标出来; 选中流程会把类型筛子钉到那一类,手动换类型且当前流程不在该类就清空)。明细表列上同一套组件换 两栏窄版,数据源那边的「来源流程」也是它,存下来的仍然只有流程 id。 换成别的来源就是另一回事了:挂字典(存字典项编码,级联、附加值带出、越界校验、导出翻译 全跟着来,等于一个「值由字典管的多选框」)、挂列表型外部数据源(几千个物料里搜一条, 存源给的编码)。原来的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。 -
联动跟着字段的变化一起动:级联下级给哪些项、显隐 / 必填 / 只读、字典带出那几格, 判的都是当下这一份表单数据,所以一改就动,不必等人点一下别的格子。判据挂在数据上 而不是挂在某一条写入通道上——公式算出来的金额、外部取数、别的系统回填,都不经过录入框, 以前只在「人在框里点了一下」那条路上重算,于是这三条通道改完上级,下级的老值还留在单子上。 带出与「下级选岔了的值」要反复扫到没人再改才算收口:带出去向常常同时是下一层的上级 (选物料带出单价,单价那一格又决定下一格),只扫一遍结果就取决于字段在表单上的先后顺序 (
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; 钉在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只往 附加值里找,于是「把字典的键值也写进别的格子」这件事在界面上根本没地方说。放开之后老配置 一个字节都不用改:裸键名仍旧先按附加值读(price就是extra.price),value/label这两个名字归候选自己的列(与optionMap的allowedColumn同一把尺子,同一个键名在两栏里 必须是同一个意思),真想要附加值里那个同名的键就写全extra.value。设计器那一栏也从手填 输入框换成挑列的下拉:名称 / 键值 / 这本字典附加值里出现过的那几个键,仍可自己敲点路径, 老那句裸price会标成「附加值 · price(旧写法)」而不是甩回一串看不出所在的字符。 判据utils/optionMap.ts:pickFillValue↔ 后端dicts.py:pick_fill_value,一字不差 (scripts/check_binding.py那一段拿同一批断言钉两边)。 -
系统带出(
type: auto):发起人、工号、部门、部门负责人、直属上级、流程名称、单号、 当前日期 / 时间这些由系统填的格。每一格都能自带一条生成规则(field.autoRule), 详见「自动值怎么生成」。 要取别的系统里的数据(ERP 成本中心、HR 职级、MES 工单)走另一条路:管理员在 「流程设计 → 外部数据源」(/design/data-sources,权限design:datasource)把接口注册成一个源, 字段属性面板里那块「外部取数」挑源、配入参、勾「带进表单哪几格」;上游接口还没开发时先把源 选成「样例」通道,用一份样例响应把整条链路配完验通,接口就绪只改通道和地址。 一格能挂好几个源再合成一个值(fetch.sources+fetch.merge,最多 8 个): 「ERP 有就用 ERP,没有问 CRM」是first,「三个系统的余额看总数」是sum, 「按最紧的那一家卡」是min/max,「多个单号并排显示」是join(fetch.separator定分隔符)。空返回不算取到,不会把合计拉成 0;少调成一个源时只有first继续往下走, 其余口径按整体的失败策略处理(残缺的合计比取不到更危险)。数值合并一律按分算再折回来, 前端显示与提交后落在work.data的是同一个数。老表单那份单源写法 (fetch.source/args/picks)继续有效,配了sources才切到合集形状, 设计器在只剩一个源时又自动写回单源形状。口径在service/fetch.field_sources与merge_values,前端镜像是utils/formFetch.fetchEntries与mergeFetchValues。 反过来一张源回好几列时也够用:字段上fetch.pick说这一格要取响应里的哪一条路径、fetch.extras再补几列想要的一起带出去,留空就是跟随数据源上声明的那份解析规则, 两处覆盖都只改这一格——不用为同一张接口的第二种用法另注册一条源,也不用去改一张 正被别的字段共用的源。覆盖跟着请求一起发到后端(POST /data-source/fetch多收这两个键), 填单页显示的那一列与提交时重算的那一列必然是同一列;带覆盖的解析另占一份缓存键。 带出去向记的是格子名,所以删格子时指向它的带出会跟着清掉(外部取数的picks、字典带出、 额度那三格、阈值的标记格),改之前存下的老表单在打开设计器时同样自愈一次;那条掉在地上的去向 在界面上照原样列出来并标红、旁边给一个当场清掉的口,不再装作「不带出」;运行时也只往还存在的 格子写(后端binding.live_target一把闸管四处),免得field_text_2这种键名被新字段复用之后 被旧带出悄悄盖掉。只收写入方向:{form.x}那种读的写法照旧留着让人自己改。 配置页不用一格一格手打了:超时 / 重试 / 缓存 / 限流 / 静默这五个数字打包成可靠性画像 (实时数值 / 主数据 / 慢接口 / 上游很脆,默认值只有service/presets.py一份), 贴一段上游答应给你的响应就能反推出列表节点、值取自哪一列、显示名取自哪一列、 还能多带出哪几个键(认不出的留空不猜);新建一张源时那段响应先给你摆好一份 (presets.SAMPLES,按通道与类型给形状:SQL 就是一行列名、流程通道是data.字段, 换类型换通道跟着换,人贴过真实返回就不盖,编辑老源不摆),不用对着空框想象 JSON 树; 方向是「只取数」时连「写回判定」那一页都不再出现,反过来方向是「往外写」时收起「解析」那一页 (报文由写回模板渲染,这张源上没有"值在响应哪一格"这回事),「入参」那页则明说这几行只给 「测试连通」用、不进真报文;往外写的源开着影子模式时连测试都不外呼,避免点一下测试就在上游落一张真单子。 固定请求头、入参、可带出键都是一行一条的表格(跟 Postman 调接口那张表一个形状: 勾选停用、备注、常用项、批量文本编辑),重复键、只有值没名字、会被「鉴权方式」盖掉的Authorization当场在那一行下面说出来,入参页下面还把即将发出去的报文摆给你看; 表格多出来的备注与停用行记在oa_data_source.param_meta,发请求时后端一个都不看。 选项是「列表里挑一条」的,还有第二条更省事的路:数据字典把选项来源选成外部数据源, 绑一张列表型数据源同步进字典项,表单那边照旧只填字典编码——级联、字典带出、提交校验 一行都不用改,上游挂了选项停在最后一次同步那份。 上游缺项时人能在 OA 里补(外部字典照旧给「加字典项 / 导入」):归属记在oa_dict_item.source(manual人补的 /data_source同步写的 / 空 = 分家前的老行, 归上游),判据只在dicts.item_is_manual一处。于是同步一律不碰人补的那一项—— 不覆盖、不停用、不挪顺序,上游后来也给了同一个取值也只让开并在报告里点一名 (preserved,想并回上游那份就点「交还给同步」);上游那一项则仍旧只读, 真要自己定就先点「接手为手工维护」。导入进来的新行同样标成manual, 撞上上游那一项的原样放过(synced),否则下一次同步一盖就成了留不住的假象。 字典列表上那本外部字典会标出手工补了几项,别让它悄悄混进上千条里。口径见 docs/external-data-simplification.md, 守卫见scripts/check_dict_manual.py。 要带的是另一个流程里那张单(填报销单时把上次批完的请假单里的出差日期、目的地点进来), 不用为它注册一个 HTTP 源绕一圈:数据源多一条通道provider=process(service/processdata.py)。 来源流程选一个、匹配条件按本表单字段写几条({form.x}),带出去向照旧是pick/map_extra, 于是多源合集、调用留痕、提交时服务端覆盖全是现成的。四条分寸:默认只查调用人自己的单 (scope=own;要跨人查必须显式改all且这个源得配min_permission,保存时和运行时各挡一道)、 默认只认批完的单(status=completed,在途单的数字随时会变,抄进另一张单等于拿草稿当依据)、 匹配条件只在最近 300 单里按内存筛(work.data是 JSON 列,不赌 MySQL 各版本把"1200"与1200比大小的隐式口径;候选够不够界面上一句话说得清)、一条源最多 8 个匹配条件 (再多说明该去对面做一个查询接口,而不是在这里堆条件)。 同一块面板下面还有「提交时判阈值」:本格的值与常量、另一个字段或业务系统取回的数比 (本次申请 > 取回的余额),命中以后挡提交 / 只提醒,判定在后端做,改前端绕不过去。 命中那句红字只读格也说——阈值最爱配的正是公式格(费用合计)与业务系统提交时现取回来的 余额格,它们永远只读,以前红字只写在编辑态那一支,于是「只提醒」一个字都没露过面。挂在谁后面 还可以挑:threshold.showAfter指到发起人真在看的那一格(一般是金额格)后面,那一格不存在或 当前环节没显示就退回本格下面说,挂错地方最多是看不见,不参与「能不能提交」的判定。 "这一格在本环节被藏起来时"也不再挡提交(threshold.onHidden,默认skip;额度quota.onHidden同一把尺子)。治的是那句原话:"阈值、闸门这些设置要是字段隐藏的时候可以 正常提交,要是在某个环节字段展示出来了,在审批同意的时候再生效配置的规则。"断点在 界面不说、后端真挡那一缝:必填本来就跳过藏起来的格子,界面那句红字本来就只给渲染出来的 格子说,唯独threshold.apply_check/quota.apply_and_check不看这一格露不露——于是 审批人点「同意」被一条屏幕上根本没出现的规则挡死,看不见、改不动、也没有那句话可照着改。 现在「藏起来」用的是与必填同一份判据(环节权限设成隐藏、字段自己勾了默认隐藏、联动条件没 放行、整页标签页被藏,都算:判据只有一处formruntime.field_hidden,与必填、与那句红字 同一把尺子),并且是挂在这一格身上的规则一起跟着走,一共六句:阈值命中挡提交、 额度超支硬闸、额度的维度算不出来、这笔额度还没入账、这笔额度记在别人名下、 外部取数失败(fetch.onError=block)。后四句原本连问都不问这一格露不露, 是用户那句"不管什么条件"里剩下的那截。四条分寸: 默认 skip 且存量配置跟着换(没配过的表单从此不挡,故意的); 只降级挡不挡——阈值仍然算、标记格照写,额度仍然占、台账仍然记、quotaOver照样落格, 取数照旧发起、那一格的值留在原来那一份上,条件分支读到的还是最新那一份(唯一例外: 账本记在别人名下那一组连账都不占,不能把这张单的钱挂到别人的头上); 要每个环节都拦一道的流程翻回block(额度上限那种红线,环节藏格子只是不想让他改, 不是放过他)——阈值那一档在面板上就能挑,额度那一档写在配置里(quota.onHidden=block), 取数那一句没有这个开关,要软一点就把onError配成keep/zero; 闸门(gate)不在这一改里:它挂在环节上(oa_activity.config.gate), 判的是"外部系统审过了没有"(核验台账状态 + 附件指纹),一条字段藏起来与否都不改变 那张凭证有没有被审过。判据在backend/scripts/check_hidden_field_rules.py(那几把尺子、 真流程、外加那四句原本不看"露不露"的拦截:藏起来的环节能过、露出来的环节被挡、 放行那一次额度照样被占、翻回block藏起来也挡)。 必填那一句现在是前后端各判一遍、用的是同一把尺子:后端formruntime.missing_required, 前端utils/formRuntime.ts:missingRequiredFields(发起页读开始环节那份formPerms——useStartForm.startPerms,审批页读node.form_perms,两边都先过一遍标签页展开)。 断的是发起页那一半:它以前只看字段自己勾没勾必填,于是开始环节明明把那一格藏了, 屏幕上没有它、那颗「发起」却按不动,还喊一句"请先填写它";同一份配置在审批页也是 同样的两处各算一套。现在这一格在这一环不存在,就不在这张单子的功课里—— 唯一的例外照旧留在后端那一句里:字段自己勾了「默认隐藏」的系统带出与公式 (编号、金额大写)仍然要有值,藏起来不等于可以不生成;环节显式接管那一格才算放手。 但「因显示条件不成立」被收走的那一格不算这一笔(2026-11 补的这一寸):那种配法说的是 「这一单用不到它」——既没有录入框,又不适用这一单,再催一句「还没填写」就是让人对着一片 空白找输入框。生产上「默认隐藏 + 显示条件 + 必填」的系统带出格就是这么把自己钉死的: 办理那一屏按条件露,条件一翻走提交永远过不去。判据只有一句 (formruntime.hidden_by_condition↔utils/formRuntime.hiddenByCondition), 钉在check_option_routes.py第 8 段与formRuntime.hidden.spec.ts。 带出、阈值、额度这三样对每个字段都开着(口径只有一处:utils/fieldCapabilities.ts, 41 种字段类型按「这一格装得下什么」分组,只有标题 / 分隔线 / 说明文字 / 分组标题 / 空白格 这几样纯排版挂不上): 装得下一个数或一句话的比大小、比先后;装一串或一个对象的(多选、部门、日期区间、明细表) 只给「有没有填」这一档;开关只给「是 / 否 / 没填」。明细表不再停在这一档:可以再挑某一列, 说清是任一行到线还是整列合计过线,右边还能挑本表另一列(本次冲销 > 还未冲), 逐行命中时红字与标记格说的是超得最多的那一行。比较符按要比的那一样东西给 (thresholdOpsFor,口径同后端threshold.ops_for_field), 额度也不要求这一格是数值格——本次花掉的钱永远来自额度配置里的金额来源,不是宿主字段自己。 画布上每格标出挂了哪几样(阈值 / 额度 / 带出三个角标),后端service/threshold.py与service/quota.py按同一份口径再判一遍,配置里出现这一格比不了的比较符会当场报出来。 见 docs/form-data-integration-design.md §5、 docs/integration-master-plan.md §4.7。 -
藏起来的那一格不占位:环节把某个字段设成隐藏之后,展示页不该在它原来那一格的位置上留一片 空白,没藏的格子按阅读顺序提上来把洞补住(发起页 / 审批页 / 单据详情 / 打印 / 设计器「预览」 共用同一份摆位,判据只有一处
utils/formLayout.ts:closeHiddenGaps,接入点是FormRenderer.vue:reclaim)。三条分寸: 只有「被藏起来那几格原本盖住的列」算洞——设计者在设计稿上自己留空的那半行不是洞, 顺手填上去等于替他改了版式,全公司没配过这件事的表单跟着变形; 整行格子(分隔条 / 分组标题 / 整宽说明 / 空白格)是一道墙,补位不许越过它, 把下一节的字段拽到上一节去比留一道缝更糟(墙那一格自己被藏起来时只是那一行没了, 不借这个机会把两节并成一片); 格子只往前提、不往后挪,宽度一格不改——塞不进洞的那一格就留在原地,绝不为了补位 把谁挤到下面去;行号最后连着发一次(CSS Grid 是显式落位的,中间空一行就是一道gap-y的缝), 而index不重编号:v-for的 key 挂在它身上,重编号会让没挪动的格子整个重建, 人正打着字的那一格跟着掉焦点。 设计器画布照旧按设计稿摆——那一屏本来就该看得见藏起来的格子,行号也要和拖拽对得上, 要看补完的效果切「预览」。标签页每一页各补各的位(翻到第二页不该看见上一页的洞)。 手机端本来就是单列竖排、藏掉的格子直接不渲染,没有这件事。守卫见utils/formLayout.gaps.spec.ts(不变量:格子不少、宽度不改、行号连续、不压格子、只往前提, 外加老表单那份span+columns)与components/oa/FormRenderer.gaps.spec.ts(环节权限藏、字段自己勾「默认隐藏」、联动藏三条路都汇到同一份摆位;一格都不藏时一格都不动)。 -
字典项一次贴一批(
POST /process/dicts/{编码}/items/import):建完字典正是往里填选项的时候, 二十个选项一格一格点最磨人,所以字典项那排工具条上补了「导入」,新建完一本手工字典还直接把它摆出来。 从 Excel 复制几行贴进来,或选一个.xlsx/.csv文件(Excel 在前端用xlsx拍平成制表符, 只在真选了表格文件才加载它,不新增上传接口、不在服务端落临时文件);第一行是表头就按名字认列 (取值 / 编码、显示名 / 名称、上级、排序、启用、附加值,中英文都认),没表头就按 「取值 / 显示名 / 上级 / 排序 / 启用 / 附加值」的位置读,用的是哪几列当场说清。 导之前先出一张结论表:每一行是新增 / 覆盖 / 跳过 / 没收(附一句为什么),行号按你贴进去那段文本数 (空行与表头都算),改完再导对得上;判据与后端逐条落库时是同一套(utils/dictImport.ts↔service/dicts.import_items),不会出现「预览说三条、导进去两条」。取值已存在时跳过还是覆盖由你选, 两种都不删没出现的项——导入是"再补一批",不是"这就是全部",这一条跟「选项来自外部数据源」的 同步正好相反(那边上游撤了要停用)。顺序也不抢:给了排序就用给的,没给就接在现有最大序号后面。 外部来源的字典也能导(上游缺几十项时一行一行敲太累):导进来的新行标成手工维护, 撞上同步那一项的原样放过并单独数一格(synced),预览上那一行写的是「这一项由同步维护, 导入不动它」——覆盖它只是自欺,下一次同步又盖回来。 附加值两种写法都收({"price": 12}或price=12;unit=个,分隔只认半角分号与换行,中文句子里的 全角;是值的一部分);上级写显示名也认得出来,换成对应取值,找不到就说第几行找不到; 「停用」认停用 / 否 / 0 / false / off / no,写不明白按启用,不替人猜。超长是挡下来说原因, 不截一半——取值是要存进单据数据里的,截掉了没人看得出来。守卫见scripts/check_dict_import.py。 -
额度总额一次贴一批(
POST /design/quotas/defs/{编码}/totals):年初那本预算几十上百笔, 一格一格点「导入总额」最磨人,所以台账那一栏上补了同一套读法——从 Excel 复制几行贴进来, 或选一个.xlsx/.csv文件(utils/tableImport.ts,与字典项导入共用那一份底层: Excel 在前端拍平成制表符,不新增上传接口、不在服务端落临时文件);三五行的小批量还能切「逐行填写」。 列名按这个额度定义自己的维度键认(project、年度这些就是列名),再加「总额 / 名称 / 归属人 / 归属部门」,总额(元)这种带单位的写法也算;没表头就按「维度… / 总额 / 名称」的位置读, 认不出的列会说是哪几列,不悄悄丢。金额认1,234.00 元/¥1234/(500)(会计红字), 读不懂就报「不是一个数字」而不猜成 0——猜错是把人家的预算清零。 导之前先出一张结论表:每一行是新增 / 覆盖 / 跳过 / 没收(附一句为什么),行号按贴进去那段文本数 (空行与表头都算);判据与后端逐条落库同一套(utils/quotaImport.ts↔service/quota.import_totals)。 台账里已有这一组维度时改成这个数(这本账一直的说法)还是只补没有的,由你选,两种都不动 没出现的那些额度行。维度就是这笔额度的身份证:少一个键、多一个键都会落成一笔对不上账的新额度, 所以缺哪个键就说是哪个键;新总额压到已经占用/核销的数以下会先说一句「导完可用会变负」。 归属人认登录账号、姓名、用户主键,认得出才落到person——scope=self的额度没归属人, 填单人在下拉里根本看不见它。这一列界面自己判不了(要查人),所以贴完就拿着去GET /design/quotas/owners对一遍人员名册:查无人与重名的那几行在预览里就标成没收, 那句原因与导入结果一字不差,不会「预览说新增 3 笔、导完变 2 笔」;不替人挑一个, 也没查到的写法不乱判。守卫见scripts/check_quota_import.py。 -
流程标题(
type: title):这一格的值就是work.title,一张表单只能有一个(多放一个 保存就被挡)。字段上titleMode两选一:rule按标题规则生成、manual交给发起人自己填; 选rule时规则就能在这张表单里直接配(工具栏「标题规则」一键到那一格, 字段属性面板里「流程标题生成规则」那块卡片默认展开, 写法、变量点选、实时预览用的就是design/TitleRuleEditor.vue那一套,存在field.titleRule); 表单里有这一格时,发起页顶部那只独立的标题输入框不再出现。规则怎么写、两条规则同时存在时 听谁的、后续谁能改,见「流程标题怎么生成」。
放得下去、看得见位置:右侧「放置位置」画布用的就是审批页那个 FormRenderer,
所以画布里的宽度与顺序不会和真正发起流程时长得不一样。画布上
- 画布是一块带边框的面板,顶部有「第 1 列 / 第 2 列」虚线标尺,双栏时中间再画一条竖向对齐 参考线,标题栏写着「共 N 行 · 双栏」;
- 每个字段是一张圆角小卡片,卡片里字段类型是青色标签,后面跟着
第 N 行 · 第 i/2 列的位置角标(.chip-position),整行的写整行; - 整行字段被半行字段挤到下一行时,空出来的格子画成 45° 斜纹的「空位」,一眼看得出被谁挤了;
- 点画布里的字段会选中左侧对应的字段,反之亦然;
- 「布局列数」可在双栏 / 单栏之间切换,切完整张画布重新排;
- 左侧字段行统一成「序号 + 字段名 + 图标按钮组(上移 / 下移 / 复制 / 删除) + 灰色小字
类型 · 位置 · 必填」,图标按钮收在一组里不再散开。
这些装饰只在设计器里出现(FormRenderer 的 design 分支),发起流程与审批页用的仍是同一
个组件的运行时分支,data-field-key / data-position 两个调试属性照常保留。
保存前会挡这些问题:字段名为空或重复、缺字段标题、下拉/单选/多选没配选项、
数字最小值大于最大值、非法布局列数、自动值的生成规则写歪(位数越界、归零周期不认识、
前后缀过长)。同样的规则前后端各跑一份
(utils/formLayout.ts 的 validateFields 与 api/design.py 的 form_problems),
POST /process/forms/validate 也走同一份,所以预览说能存的就一定存得下。
新建时字段名自动取 field_text、field_select_2 这种不会撞车的名字。
自动值怎么生成
表单里「系统带出」那一类的值一直是代码写死的:单据编号永远是 YYYYMMDD + 6 位流水、
按月归零,想改成「QG20260920-0001」得改代码。现在这个口子开给设计表单的人,
规则存在字段自己的 autoRule 上(service/numbering.py 是唯一口径):
{"prefix": "QG", "date": "YYYYMMDD", "length": 4, "period": "day", "suffix": "-X"}
// -> QG20260920-0001
- 入口:
表单设计 → 选中那一格 → 「自动值生成规则」(字段库里「自动带出」带「规则」 标记,配过的格子在画布上直接写着QG · YYYYMMDD · 4); - 编号(
auto: serial)吃整套:前缀、日期段(可选「不要日期段」或自定义写法, 认YYYY MM DD HH mm ss)、流水位数 1-12、归零周期按天 / 按月 / 按年 / 不归零、后缀; - 当前日期 / 时间(
today/now)只认时间写法,其余系统值只认前后缀—— 「部门-姓名」这种拼接是标题规则的事,这里不重复造一套模板语法; - 默认口径没变:不配规则仍是「当天日期 + 6 位流水、按月归零」,老流程一条都不用迁移;
- 计数器照旧落在
oa_serial_number的(流程, 周期)唯一键上,周期按所选归零档位算, 所以按天和按月是两本账,各自从 1 开始; - 规则跟着表单走:编号规则写在表单那个「单据编号」字段上(以流程的默认表单为准), 同一张表单挂到别的流程上不必重配;
- 预览不占号:设计器那块「下一个编号」走
POST /process/form-serial/preview, 只读当前计数器,反复调也不会把流水号吃掉一格;表单还没挂流程时给的是「本期第一个」的 样子,界面会这么说明; - 写歪当场挡:位数越界、归零周期不认识、前后缀过长、规则不是对象,保存表单就被挡回来,
不悄悄替人改好(前端
utils/autoRule.ts与后端numbering.problems同一把尺子)。
标题规则里的 {单号} 读的就是这条规则拼出来的编号——两处永远是一件事。
流程编号什么时候排出来
上一条讲的是编号长什么样(写在表单那格的 autoRule 上)。什么时候排是另一件事:
先内部流转、批完最后一级才登记文号,是不少单位的行文规矩;反过来,拟稿阶段就要在拟稿箱里
看见单号,也好催人补齐。所以这一条配在流程上(oa_process.serial_config),
不配在表单格上——同一张表单挂两条流程,可以一条发起就编号、一条批完才编号。
入口:流程设计 → 流程信息(meta 面板)→ 「流程编号」,五档(下表从上到下,占号时刻越来越晚):
at |
什么时候排 | 用在什么场合 |
|---|---|---|
create |
打开新建填写页就占号 | 编号在填单全程都要看得见(纸上要印、电话里要报);代价最大,见下 |
draft |
创建流程时存草稿就占号 | 拟稿箱、草稿列表里要看得见单号 |
start(默认) |
发起那一刻 | 出厂口径,与加这个功能之前一字不差 |
activity |
走到指定环节才排 | 先内部流转、到某一环才登记文号 |
none |
不自动排 | 单号由文控另行登记,或本平台不用编号 |
activity 那一档还要点名哪一个环节、以及到达时还是批完时(when:
enter / leave);指到「开始环节 + 到达时」等同于发起时排,引擎认下来,
不让人配一条永远不触发的配置。配好的时机同时写在三处:设计器 meta 面板那句摘要、
流程图画布上那一环的节点摘要(轮到它排号时才写)、以及审批记录里
排定流程编号 那一条留痕(谁、什么时候排上的号)。
几处一起跟着动的地方,少一处就是界面与库里各说一套:
- 一本账:草稿占号、发起排号、指定环节补号走的是同一个计数器
(
numbering.take),先起草稿再发起、直接从接口发起、走到环节才补,都不会谁把流水号 排回 1。代价是弃掉的草稿会跳号,所以create/draft两档默认都不开;同一条草稿只占一次, 存第二遍不许多吃一个号(oa_draft.serial记下占到的那个)。 create靠一张短命凭条:号是在「单子还不存在」的那一刻被吃掉的,所以POST /job/serial/reserve除了号还回一张 15 分钟的凭条(ticket),提交或存草稿时原样交回,那个号才正式落到这张单上。 服务端只认自己签的这张条:手填的号、别的流程的号、过期的、同一张交第二次的,一律当没预约过, 那一张单子照旧在发起那一刻排号(引擎顺手把表单里那一格改成真号)。号是不是已经被用掉, 只在本流程内查——计数器按「流程 + 周期」各记一本账,两条流程排出字面相同的号是常态, 按全局查会把别人用过的号当成被占过,凭条白白作废。发起页是一打开这一页就去占号: 点开新建页就是在创建一张单子,那一格「单据编号」不该等人填了两格才有值。代价也就摆在那儿—— 点开看了一眼又关掉的人照样跳号,所以这一档要流程自己挑,默认不开。- 已排过的号永不重排:退回重走、环节被重复触发,一张单也只占一个号
(
engine.issue_serial一进来就判work.serial)。 - 补号那一刻四件事一起办:
work.serial落库、表单里那格「单据编号」填上、 在途与已归档的待办待阅补上单号、标题按规则重算一次——模板里写了{单号}的单子, 这一刻之前那句标题一直缺着号,这里补回来(发起人亲手写过的标题仍然不动)。 所以「编号晚排」不会把标题里的单号弄丢,只是那一刻之前标题上确实还没有号—— 办理页在标题下面写明「提交后会更新为 …」,不让人以为标题写坏了。 - 保存时把关:选了
activity却没点环节、环节后来被删了、写的时机不认识, 设计器当场红框、后端numbering.timing_problems同一把尺子。写歪的时机读的时候 仍旧宽容收回默认(老数据、接口写的、手改库的都可能撞上来),只有写才拦。 none那一档是真不给号:work.serial一直空着,详情页与打印页那一格写明「还没排号」, 不拿流水号糊一个上去;标题里的{单号}那一段也就一直空着,由模板自己的空值兜底接管。
申请人 / 申请部门 / 审批人怎么自动带出
「系统带出」那一格是只读文本,可表单里更常见的需求是:这格本来就该是个选人控件、
部门控件,只是值不用人挑。现在 auto 这个来源也能写在普通字段上
({"type": "dept", "auto": "creatorUnit"}),带出来的值按字段类型塑形:
| 字段类型 | 能带出的系统值 | 存进去的形状 |
|---|---|---|
选人 user |
发起人 / 直属上级 / 部门负责人 | 登录账号数组 ["zhangsan"] |
部门 dept |
发起人部门 / 发起人部门全称 | 部门路径 公司\部门 |
| 文本 / 多行文本 / 隐藏 | 发起人工号、部门、流程名称、单号、当前时间… | 文本 |
| 日期 / 日期时间 | 当前日期 / 当前时间 | 2026-10-12 / 2026-10-12T16:20 |
- 入口:
表单设计 → 选中那一格 → 「自动带出」;画布上这一格带着「自动带出」角标, 悬停就写地带的是什么值; - 带完还能不能改看字段自己的「只读」:配上来源默认锁死,勾上「带出后允许填写人修改」
才放开——环节权限、后端提交时的取值过滤(
formruntime.editable_keys)认的都是这一条, 不另设第二套开关; - 只读回显按类型念:选人那一格念「姓名(账号)」(
utils/personLabel.ts),部门那一格念部门名, 也就是路径末段(components/oa/mobile/useFormPlan.ts:deptText与桌面那格的下拉 label 同一个口径), 不把整条组织路径摊给人看;星期几、多选月份、定位这三类桌面与手机共用utils/formRuntime那三份读法(weekText/monthsText/locationText),手机上不会看到1-7与['2026-10'], 也不会因为落到兜底那句而整格念成空的;金额与数字两边都读formatNumber(千分位 / 小数位 / 货币按格子配置),金额没配单位也补「元」,明细里的金额列与合计同一个口径; - 存的是身份不是姓名,所以申请人、审批人这两格能直接当「按表单字段找人」的来源用,
也能进条件分支;只读回显顺手补了一处:选人字段那一格存的是一串登录账号,详情页、打印页
统一念成「姓名(账号)」(
utils/personLabel.ts); - 谁算哪一段:发起人、工号、所在部门、流程名称、此刻的日期时间,发起页在登录态里
当场就填好;直属上级和部门负责人要查组织库,由引擎发起时写进
work.data(service/autofill.py是唯一口径),那一刻界面上那一格就空着——不拿猜出来的人名糊上去, 也不自带一句说明(空着那一格写的是全平台那句--,不是真空);想在框里留一句话, 是「没值时显示的文字」那一栏的事(见「表单设计」那一节); 单据编号(auto: serial)也归"当场给不出"这一类:真号要看编号时机(oa_process.serial_config.at), 配成「新建填单时就生成」那一档时发起页当场占一个号、当场亮在格子里 (POST /job/serial/reserve,凭条随提交或存草稿交回),其余几档在发起页就是--, 表单设计器的「预览」里则给一个按规则算出来的样子(只读不占号); - 只在发起那一次带:前端只在没有单据可挂时(发起页、草稿)填自己,办到第二环节的 表单里登录态那个人是审批人不是发起人,不能拿他当申请人;草稿里填过的、替别人提单时 改过的申请人一律不动;这一格被环节配成只读时,这次提交的值在落库前就被丢掉, 仍然回到「空着 → 系统补」;
- 写歪当场挡:来源写在这类字段带不出来的值上(比如部门字段要带「流程名称」),
保存表单就被挡回来,前端
utils/autoPreset.ts与后端autofill.problems同一把尺子。
表单与流程怎么对上
只有一条规则:流程认一张默认表单(process.latest_form),人工环节需要时再覆盖它
(activity.form),其余都是这条规则的派生结果,不再各查各的。
默认表单是在流程这一处定一次的:环节默认一律沿用,画布和属性面板都不会逼着每个环节 再点一遍同一张表单。
表单是独立资产:新建表单不挑分类、也不挑流程,建完就进表单库;关联只在流程设计里做, 流程设计器的两处表单下拉列的是全平台所有表单,按「本流程的 → 通用 → 其他流程的」分组, 超过 5 张自动带搜索框,选中即关联。
- 表单在新建流程那一刻就定下来:弹窗里「新建一张(推荐)/ 用已有的」二选一。挑了已有的
就直接拿它当默认表单,不再顺手多建一张没人要的起手表单;没挑才现建一张只有一个「申请事由」
字段的默认表单,建完就能直接发起。
POST /process/processes的latest_form就是这个选择, 指到一张不存在的表单会被当场挡下来。 - 环节那一格常态只有一行「沿用默认表单 · 费用报销单」:既没有分段开关也没有表单下拉,
免得每个环节看起来都像被要求做一次表单选择(「这一环节跟着默认表单走、字段权限在那张
表单上配」收进悬停提示,不占版面)。确实要换一张才点右边「换一张」展开下拉,旁边留一个
「改回沿用」。流程还没定默认表单时那一格不给你在环节上各选一张,而是换成「去选默认表单」,
点了直接跳到流程信息那唯一一处。数据上空 = 沿用,运行时回落的就是
activity.form or work.form,发起页用的则是latest_form。 - 把默认表单又点了一遍不算单独指定:保存设计时就收回成沿用(
_inherit_form),复制流程 同样这么收。设计数据里不留重复绑定,界面才敢如实说「谁沿用、谁单独指定」。 - 流程信息面板给一句「N 个环节沿用默认表单 · M 个环节单独指定」,有重复绑定时另加一句提醒, 并给「让 N 个环节都沿用默认表单」一键收口(画布卡片只有两行摘要,放不下表单那一行, 要看名字点环节)。
- 绑定只写流程这一侧:把一张表单设为某流程的默认表单,不会改动表单本身,同一张表单
可以同时被任意多条流程选走。表单上只剩一个内部归属位(
oa_form.process),记录 「这张表单是谁家自建的」,只用于删流程时的清理和复制流程时的分叉,不参与可见性; 只有建流程自动带的那张会被写上,表单设计器已经不摆这个选择器。 - 「谁在用这张表单」不靠归属位猜,由
_form_usages从process.latest_form与activity.form反查,挂在表单的used_by上:表单列表拿它渲染「使用中的流程」, 表单设计器拿它提示改动会波及谁。 - 发起页读的就是
latest_form,与引擎发起时写进work.form的那张是同一张;审批页再用activity.form or work.form。GET /process/forms?process=一次给全部表单,只按 「默认表单 → 本流程表单 → 通用表单 → 别家流程的表单」排序,取第一条不会再取错。 - 引用关系是硬的:表单被流程默认表单或某个环节用着就删不掉,报错点名到具体环节; 删流程时只有它自建的表单跟着删,独立表单原样留着等下一条流程来选;复制流程只给自建的 表单另建一份,独立表单继续共用,要一份能改的变体就在表单列表里点「复制」。
- 老库里「有自己的表单却没绑默认表单」的流程,启动时由
seed._backfill_default_forms补一次绑定。 - 流程设计器的「默认表单」一侧有三个图标:新建(就地建一张起步表单并选为默认表单, 画布仍要点保存才落库)、刷新(在别处改了表单不必来回跳转)、打开表单设计; 人工环节的「使用表单」一侧也有「打开表单设计」,画布有未保存改动时先问一句, 改完靠返回按钮原路回来。
节点配置弹在哪里
流程设计器右侧那一栏只摆摘要 + 入口:每个环节一格,标题行是环节名,下面按分组一行
一句现状(「审批人 部门主管 · 3 人」「字段权限改了 3 项」),控件本体在
components/oa/design/NodeConfigDialog.vue 里按分组展开——左边竖向 tab 选分组,右边一块
面板摊开这一组的控件,tab 上的琥珀色圆点标出「这组还没配完」。分组按环节类型给
(utils/nodeConfig.ts 的 nodeGroups):人工环节有审批人 / 表单 / 会签与加签 / 抄送 /
配额 / 路由,网关与汇聚只留放行条件,脚本、服务调用、子流程、延时各拿自己那一组,
结束环节只剩基本信息与抄送写回。双击画布上的节点同样开这个弹窗,右栏那一格
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。
「表单与字段权限」那一格开始环节也有。 面板本体在 components/oa/design/FormPermsPanel.vue,
人工环节与发起环节共用同一份判据(逐格四档 + 「标签页」整片 / 每一页那两层隐藏 + 「全部只读」
那颗按钮 + 换表单时收掉不存在的字段),存的都是同一份 activity.config.formPerms。
运行时一直肯发起环节这一份——engine.create_job 把 definition.begin 一起交给
_apply_form_runtime 与 _validate_form:藏起来的格子不上发起页、也不参与必填,提交上来的
值也不收,挂在它上面的阈值 / 额度按"看不见不挡人"放行;发起页读的是同一份
(useStartForm.startPerms)。以前缺的只是设计器里那一格:它只长在人工环节上,
于是"发起那一刻哪几格不给看、哪几格不用填"一直没有地方配。
这一藏只管发起那一刻,不管事后:WorkDetailView.vue 与 PrintWorkView.vue 渲染那张表单时
压根不递环节权限(TaskDetailView.vue 才递当前环节那一份),所以发起人回到「我的发起」
或单据详情看这张单,发起环节藏起来的那几格照样原样摊给他看——"看自己发起的流程要看得见全"
是刻意的,钉在 NodeInspector.begin-perms.spec.ts 最后那两句。要某一格从头到尾都不露,
用的不是这一档,是表单设计里那一格自己的「默认隐藏」(全局默认,回看那一屏也不显示;
只有那一格同时配了「显示条件」时例外,见下面那一段)。
发布期那份格式校验
(definition._check_form_perms)也因此从"只查人工环节"改成每种环节都查——
发起环节把权限值写歪(read_only 这种)过去没人管,运行期那一格按「没配过」走,
人在界面上点了「只读」却发现照样能改。钉它的是
NodeInspector.begin-perms.spec.ts 与 check_hidden_field_rules.py 末尾那两句。
字段自己也能说「我默认不显示」。 表单设计器的字段属性上有个「默认隐藏」
(field.hidden):不用挨个环节点权限,整张流程默认都看不到这一格,而值照常存、
系统带出与公式照总算(编号、金额大写、给分支当条件用的中间值都属这类)。它是默认值
不是锁:哪个环节要显示,在该环节字段权限里显式给只读 / 可编辑 / 必填就盖过来了;
环节显式隐藏(formPerms 写了 hidden)仍是最高优先级。口径只算一次,
在 service/formruntime.effective_perm,前端镜像是 utils/formRuntime.effectivePerm。
必填在这一格上换个说法:不显示但仍要有值的系统带出 / 公式字段照旧要求算得出值,
普通字段被默认隐藏时必填不再生效(要它必须填,就先别让那一环看不到它)。
但「默认隐藏」只在那一格没配「显示条件」时才说话。 勾了默认隐藏又配了显示条件,说的本是
同一件事的两头——"平时不露,条件成立才露",讲话的是条件;旧口径把默认值排在条件前面,
于是这种配法在每一个环节都不露,除非每个环节都显式点名它,提交时那一格的值还跟着被丢掉
(editable_keys 认的就是隐藏判据)。生产上 费用报销单.feiyong_type 就是这么消失的:
勾了默认隐藏、条件是按三条部门路径放行,而整条流程没有一个环节点名它,谁也看不见它;
出差备案申请 那六格项目 / 客户只是靠发起与审批环节显式给了可编辑才露出来,
条件同样成立的部门主管那一环(formPerms 是空的)一格都不显示。现在这一寸挪到条件后面
(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),点它是删键而不是
写 'editable'——显式 editable 会把字段自己的必填盖掉,这俩不能混为一谈。
FormPermsPanel 里那段「字段列表变了就收掉不存在的字段权限」的清理,只在
确实拿到了字段时才动手:表单列表还没到 / 请求失败 / 环节解析不到表单时拿到的是空数组,
老写法把它当成「字段全被删了」,当场把 formPerms 清成 {},下次保存设计就把清空后的
结果落进了库——这就是「权限配好、刷新又全变可编辑」的来路。空列表因此一律原样留着,
界面上「一张表单都没有」与「这张表单还没有字段」也是两句话。
字段权限给了一颗「全部只读」。 一张表单十几个字段逐格点只读太慢,而审批环节常常就是要整屏
锁死,所以面板右上角多一颗「全部只读」(process.setAllReadonly):一次把本环节还填得动的字段
写成 readonly,顺带把已配成可编辑 / 必填的也收过来。它不动三类格子——环节上已设为隐藏的
(翻成只读等于把人特意藏起来的格子重新摆出来)、字段自己勾了「默认隐藏」而本环节没点名它的
(显式给只读正是把那一格放出来的做法,不该由批量动作代劳)、分隔线 / 说明 / 隐藏 / 取数 / 公式
这些本来就没有录入框的(运行时本来就只读,写进 formPerms 只是噪音)。没配过的「沿用」会被
写成显式只读,其余已配的键原样保留;列不出字段时这一颗不出现,本环节已经全是只读时它是灰的。
保存设计这件事只有一套口径
以前"保存"在流程设计器里有三副面孔:工具栏的「保存设计」存画布,右侧「流程信息」另有一颗 只存名称分类的保存,连线面板也摆一颗「保存」,点了只改内存,提示还老实写着「路由已更新, 还没存到服务器上」—— 三处凑一起,没人读得懂,于是"配了路由、刷新又没了"。现在口径是这样:
- 落库只有一条路:
save()一次送走环节 + 路由 + 默认表单 + 流程级审批规则 + 流程信息。 工具栏那颗、⌘/Ctrl+S、右侧「保存到服务器」、自动保存、校验与发布前的静默保存,全走它; 并发撞上同一拍时共用同一次请求,不出现两份设计互相盖。 - 不真的落库的动作不再叫保存:连线面板那颗改成「加到画布 / 应用到画布」,提示是 「路由已改到画布上」,不再冒充存档。
- 手停下来就自动送:
composables/useDesignAutosave.ts里那一拍是 1.5s,每改一笔都往后推, 拖框途中不写库;工具栏那朵云可以关(记在localStorage),关掉就回到只有手动保存。 自动保存成功不弹「保存成功」,状态本来就挂在标题旁边。 - 没落库随时看得见:标题旁边那颗状态点说「都存好了 / N 处未保存 / 正在保存 / 没存上」,
悬停给出
utils/designDiff.ts数出来的分布(环节几处、路由几处、默认表单、审批规则、 画布摆法、流程信息几处)——只说"有改动"跟没说一样,说清是哪几处才敢让人关页面。 自动保存失败时红字留着,同一句失败原因只播一次(每停一下重试一次,刷屏等于没说)。 - 环节配置弹窗的落款报的是服务器上的事实:「改动会自动存到服务器」/「这一环节的改动已经存到 服务器 · 14:32」/「自动保存没成功:……」,由设计器按全局状态给,弹窗自己不再判断。
改流程、改表单,不会拽动已经在路上的单子
以前会。设计器停手 1.5s 就把环节、路由、审批规则自动存进 oa_activity / oa_route,
而引擎每一步都现读这三张表——有人改图,一张走到一半的单当场就换了脚下的图:环节改名、
出口少一条、审批规则换档、表单多一个必填。oa_process_version 那张表救不了这件事,
它是发布历史,给人看、给人回滚,运行时从不参与。
现在每张单在发起那一刻领一份不可变的设计快照(oa_process_snapshot:流程 / 环节 /
路由 + 那几张环节用到的表单内容),这张单之后只认它:
- 在途单眼里的环节、出口、字段权限、审批规则(
skipStarter/dedup/ 前瞻去重)、 编号时机、标题规则、表单字段与必填,全部停在它出发时那一版; - 办结归档不解锁:冻结引用跟着搬进
oa_work_completed.design_snapshot,这张单走完 之后照旧认它自己那一版——回头打开一张去年办结的报销单,看到的仍是它当时那套环节与 表单;改流程改表单不会把一张已经落定的单改写,连流程后来被删了也删不掉它那一版图; - 新发起的单照旧从当前设计出发——「保存即生效」这条口径没动,只是把生效范围说明白了: 新发起的单据;
- 快照按内容寻址(sha256 指纹):设计没再改动时,一百张同时在途的单共用一行,不是一张一份;
- 读快照走进程内缓存,快照不可变所以不必失效,审批那条热路径上比原先现读三张表还省一趟;
- 升级不迁数据:这套机制之前发起的老单身上没有快照引用,照旧现读当前设计
(
design_snapshot为空 = 跟着当前设计走); 这套机制之前归档的单也不迁:启动时seed._backfill_archived_design_snapshots拿 同一张单的已办行(oa_task_completed.design_snapshot)把这份引用抄回来,抄不上的留空 照旧现读;标记system.archived_design_snapshot记的是看到过的最高办结时刻,往后的 启动只问归档表有没有比它更新的行——没有就一句都不做:既不每趟全扫那张只长不删的归档表, 也不会把滚动发布窗口里老进程刚归档的那几张单永久留在门外; - 快照行被清了也不报错,回退现读——宁可让一张孤零零的老单跟着新图走, 也不能让它因为查不到快照而连环节都打不开;
- 总闸在「系统设置 → 流程设计 → 发起时冻结流程设计」(运行配置
design_pin_enabled, 默认真,改完即生效不用重启):关掉只是新单不再冻快照、回到每一步都现读当前设计的旧口径, 已经冻上的在途单仍认自己那一版,不会中途被换图。排查「这次改图到底影响了谁」时好用。
界面上看得见:单据详情页标题旁多一枚灰角标,只在「这张单出发之后确实有人动过设计」时出现,
在途的说「按第 3 版设计在走」、已经办结的说「按第 3 版设计办结」,悬停说清改动只对之后的
新单生效;流程设计器那个版本号徽标上挂了同一套话的落款。接口上 GET /job/{job} 多了
design_pinned / design_version / process_version / design_touched_after_start 四个字段,
归档件(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 守着(57 条,其中第 3b / 3c 组守的是「手机端那一屏跟当下表单内容与环节字段权限」这条例外),
其中第 9~12 组守的就是归档这道坎:引用跟着搬、归档详情页报的是冻结那一版、没有引用的
老归档单照旧现读、启动回填按办结时刻的高水位往前推、快照与流程一起没了也不能把人锁在
门外,以及删流程只清没人认领的那几版快照——归档单认着的那一版留在库里。
还跟着当前配置走的三件事,说清楚免得踩:
- 外部审批接口开没开(环节那格
openApprove打开没有、对哪个应用开口):管理员当场 关掉,第三方在 OA 之外的表态就当场收不进来。这一格是「闸口」不是「图纸」,跟着人走。 界面上那句「这一环的审批在外部系统里进行」也照当下算(node_approve.lock_states_for_process一次查库读实库那行),不拿冻结那一版的配置拦人——否则横幅拦着审批人、引擎其实还收得住。 - 字典项、外部数据源、额度台账、人员与部门这类引用数据:本来就是设计之外的事实, 改了照常即时生效,在途单也跟着变(选项、额度余额这些停在过去反而对不上账)。
- 手机端审批那一屏摆的是哪几格(两处配置:表单里那几栏展示配置——哪几格上屏、顺序、每格怎么摆、
显示条件;流程设计器「环节 → 字段权限」——隐藏 / 只读 / 可编辑 / 必填):改完当场见效,
已经在路上的单子在手机上跟着变。这是「改表单不影响在途单」唯一开在摆法上的一道口子——
该填哪几格、必填缺哪几格、提交校验、桌面详情、打印、导出、引擎认值读的仍是这张单冻住的那一份。
报文上多出来的那两份叫
forms_live/activity_perms_live,只给冻过结的在途单,只装真改了的那几张 (口径与取舍见docs/mobile-approval-layout.md§4.5)。
权限角色
菜单、接口、数据范围三层都由「权限角色」说了算,一处配置全链路生效,改完立即生效(不用重新登录, 前端下一次请求就带着新的权限码)。
权限码:32 个,分 5 组(权威来源是 GET /auth-roles/catalog,app/permissions.py 定义,
前端 constants/permissions.ts 只负责翻中文)。285 个接口里 159 个直接挂权限点,其余是「只做
自己那份事」的自助接口(要求登录 + service 层判断归属);完全匿名的只有登录、刷新令牌、健康检查、
公开配置、资讯封面图和前端 SPA 壳子,python3 scripts/check_route_guards.py 会把漏网的接口报出来。
分组只是界面上的归类,权限码本身是完整字符串,下表写的是码值全文:
| 分组 | 权限码 |
|---|---|
| 办公事务 | work:workbench work:start work:todo work:done work:created work:read work:draft work:agent work:handover work:profile |
| 门户中心 | portal:home portal:document portal:meeting portal:schedule portal:file portal:manage |
| 流程设计 | design:process design:form design:category design:quota design:datasource design:integration design:openapi |
| 组织架构 | org:unit org:person org:role org:authrole |
| 监控与系统 | monitor:work monitor:export statistics:view log:view system:setting system:notify |
/auth/me 与登录响应一并返回 permissions / data_scope / roles。前端拿它决定侧栏渲染哪些
菜单、路由是否放行(受控路由都带 meta.permission,无权限时按「首页 → 工作台 → 待办 →
个人资料」落到第一个有权的页面);后端用 Depends(require_permission("…")) 把同一批权限码钉在
每个接口上,前端藏起来的入口在后端同样进不去。
数据范围:self(仅本人)/ unit(本部门)/ unit_and_below(本部门及下级)/
custom(自定义部门)/ all(全部数据)。前四档算的是「登录人自己在组织架构上的位置」,
只有 custom 是管理员在角色上直接勾一批部门:data_unit_ids 存部门 id,
data_unit_children 决定这些部门连不连带下级,data_include_self 决定要不要始终带上
本人的数据(默认带上,免得配完连自己的单子都找不到)。
一个人可以有多个角色,权限取并集、数据范围也取并集——自定义[研发中心] + 本部门
两边都看得见,不会因为「谁更宽」把另一边挤掉;对外播报的 data_scope 只是最宽的那一档,
真正过滤用的是合并后的授权(permissions.DataGrant)。已按范围收敛的查询:
组织架构树、部门列表、人员列表、流程监控(全部流程与全部待办:在途的与已归档的同一张列表里都能筛到)、
流程干预(挂起 / 恢复 / 改道 / 整单催办与改派 / 修正表单数据)、
管理员的终止与超期催办也只能动自己范围内的实例——监控列表里筛不到的单子,凭一个 job 也改不到它头上。
内置角色(builtin,不可删除):
| 角色 | 数据范围 | 权限 |
|---|---|---|
| 超级管理员 | all |
* 全权限 |
| 部门负责人 | unit_and_below |
17 项:日常办公 + 门户 + 流程监控 + 统计分析 |
| 普通员工 | self |
15 项:日常办公 + 门户 |
自定义角色在 系统管理 → 权限角色 里建:名称 / 数据范围 / 排序 / 描述 + 按分组勾选的权限矩阵
(每组和全局都有全选 / 清空),成员用「角色成员」弹窗按姓名或账号勾选。后端会挡掉未知权限码和重名。
数据范围选 自定义 时,弹窗里会多出「可见部门」那一块:整棵组织架构树按部门勾选(勾父部门
连整棵子树一起勾,只勾中一部分时父节点显示半选态),支持按名称/路径搜索、展开收起、标出已停用
部门,旁边是 含下级部门 与 包含本人数据 两个开关。部门清单走 GET /auth-roles/scope-units,
它是权限配置专用的全集——不按配置者自己的数据范围裁剪,否则管理员就只能圈到自己那一支。
后端同样会把三道关:部门 id 必须真实存在、改回其它口径时清空部门集合、
一个部门都没勾又关掉「包含本人数据」直接拒(那种角色会把持有人锁死在系统外)。
没配任何角色的存量人员按 普通员工 兜底(要真正禁用某人,用人员管理里的状态开关把
users.status 改成 0,而不是清空角色;2/3 是预留的待审核与已拒绝,同样挡在登录外)。
历史遗留的 role=admin 仍算超级管理员,新用户的默认角色是 member。
统一身份与用户同步
登录、组织人员和 Hub 统一身份平台对齐,几件事各自有开关,全部配置项与落库规则 写在 docs/hub-integration.md:
-
从统一门户免登进来:配好
OA_HUB_APP_CODE+OA_HUB_INTEGRATION_KEY(Hub 注册 应用时那一次下发的编码与密钥明文)就通了。用户在门户点本系统卡片 → Hub 签发一次性ticket并 302 到/sso→ 前端把票据交给POST /auth/sso/login→ 本系统后端带X-Integration-Key调POST /api/v1/auth/tickets/verify换sub→ 按sub认人/建号 → 换发本地 JWT。票据只在服务端到服务端这一步消费、永不重试,落地后立刻history.replaceState把票据从地址栏抹掉;Hub 说人停用时本地跟着停用并清掉刷新令牌, 不回落到旧会话。发起端会先在 HttpOnly Cookie 里写一条随机state,落地时精确比对 (OA_HUB_SSO_STATE_REQUIRED=true则强制要求)。OA_HUB_LOGIN_MODE=sso时本系统 彻底不收账号密码,登录页只留「前往统一门户」,应急本地账号那扇门仍在(口径见对接指南 1.4)。 -
登录问 Hub:
OA_HUB_ENABLED=true后,账号密码由 Hub 判定,登录页会出现 Hub 下发的验证码;拿到 token 再调一次token/verify复核,Hub 侧已停用的人即使口令 正确也拒登。hybrid(默认)只在 Hub 连不上时才回退本地口令,Hub 明确说密码错就是 错,不再拿本地口令兜一层。OA_HUB_LOCAL_ACCOUNTS(默认admin)是应急通道, 保证内置超管在 Hub 里没有对应账号时照样进得来;这一栏里的账号名也不会被统一身份接管。 本部署把内置超管改成localadmin专做应急,admin让给统一身份同步并走 Hub 登录 (docs/hub-integration.md 5.1)。 -
权限也可以问 Hub:
OA_HUB_PERM_ENABLED=true之后,角色、权限码与数据范围能从 统一身份平台问出来(《Hub 权限接口交互文档》)。有本人 Hub 令牌(Hub 口令登录)就问/me/roles、/me/permissions、/me/data-scope;免登进来的用户手上没有令牌,就由服务端 拿同步凭证代查admin/users/{id}/roles与.../data-scope。shadow(默认)只把 Hub 的 口径显示出来给管理员对账,enforce才真的参与判定;本地超管永不被降级,Hub 一个可识别 权限码都没给时保留本地权限,Hub 挂了也照本地权限走。本系统的角色矩阵不会被 Hub 覆盖, 关掉开关立刻回到对接前的行为。「组织管理 → 权限角色」页顶部的面板能看到自己在 Hub 上的 权限、和本系统权限目录对账、一键把缺的权限码登记过去、按账号代查(口径见 docs/hub-integration.md §9)。 -
本地会话自己管:Hub 那边登出不会回收已经建好的下游会话,也没有单点登出,所以
OA_SESSION_IDLE_MINUTES(默认0= 不启用)管空闲多久要求重新登录:访问令牌有效期被压到 不超过这个窗口,服务端按刷新令牌的「最近活动时间」判定,前端挂POST /auth/session/touch心跳,人真在操作就不会掉线,一动不动到点就清本地会话送回登录页(只允许免登时就是重回门户)。 -
定时全量同步(默认每晚 1 点,频率可配,见下面的「同步定时任务」):
GET /api/v1/auth/directory一次拿回完整组织树和全量 人员,按hub_user_id→account的顺序对号入座。对端表结构与本地一致,所以account/display_name/organization_id/status直接对齐;本地同名账号会被 「认领」而不是插成重复行。Hub 里停用或消失的人只置为「已停用」,永不删行;source='local'的账号与role='admin'的超管不参与同步。人员清单被member_limit截断时只写不撤,Hub 返回空清单时整趟放弃,避免误伤一片账号。 这一趟跑成过就不再跑,失败了按OA_HUB_SYNC_RETRY_MINUTES补试,每次执行都记在oa_hub_sync_run。记录要能核对:改名、僵尸账号让位、按编码认回部门这三类动作各自成列 (renamed/reclaimed/units_rebound),名单级明细存details(每类前 20 条 + 完整总数 + 按条原文的提示,message那 2000 字裁掉后半句也不丢信息),只改了名的一趟不算「无变更」。 验收见backend/scripts/check_hub_sync_details.py。 -
几十秒内跟改:
GET /api/v1/auth/directory/changes按游标轮询变更流水 (OA_HUB_SYNC_CHANGES_*,默认每 45 秒),人与部门的小改动不必等排期全量。游标只在 一批真的落干净(has_more=false)之后才往前推;流水被裁剪、本地落后过多,或收到只带id与status/parent_id的组织事件时,直接改拉一次全量重对齐。事件主键只认entity_id(data里的键名随来源变化),页面上「拉取变更」按钮能手动跑一趟, 进度与落后条数在GET /api/v1/hub/status的changes段。 -
点一下就能同步:「人员管理」页头有「立即同步」按钮 (
POST /api/v1/hub/sync,org:person权限),走同一条同步逻辑但永远强拉,用于 入职、调动、离职这类要立刻看到效果的场景;点完给出新增/更新/停用/部门变更的汇总, 并能翻最近几次同步历史。 -
卡住了有出口:
oa_hub_sync_run里那个「进行中」有两种卡法。后端被 kill、容器被驱逐会把那条running丢在没人收尾的地方,同步历史一直显示「进行中」、「立即同步」也跟着按不动——这种残留由 后端启动时清一次、GET /api/v1/hub/status读状态时顺带清(判据是「开始超过 30 分钟且没有任何副本 持同步锁」,见hub_sync.STALE_RUN_GRACE_SECONDS)。想叫停真在跑的那一趟就点页面上的「终止」 (POST /api/v1/hub/sync/cancel,org:person):它先广播一个停止信号(本进程 + Redis,按时间戳 比对,只认「这一趟开始之后按的」),正在跑的那一趟在下一个检查点自己收手——拉完目录、写完部门、 写完人员各一次,另加每 25 行看一次,几秒内就停;同时把挂着「进行中」的记录一律标成「已终止」、 强制放行跨副本那把同步锁,不用干等它一小时 TTL 到点。停下来的那趟记成「已终止」而不是「失败」, 因此不会被失败补试重新捞起来跑;「已终止」只说这一趟没跑完,已经写进库的人员与部门不回滚, 下一趟照常从 Hub 全量重对齐。返回里stopping=true说明终止时确实有一趟在跑、马上会停手。 验收见backend/scripts/check_hub_sync_cancel.py。 -
"明明没同步,却提示「已有同步任务正在执行,请稍后再试」":这句话只可能由本进程那把
threading.Lock抛出来(跨副本 Redis 那把挡下来的是另一句「另一个副本正在跑同步」),而页头按钮的busy只是页面加载时读到的一次running快照、不轮询,所以后台那趟增量同步(默认每 45 秒,与手动 同步共用同一把锁)撞上时,界面上看着什么都没跑、点下去却被挡回来 —— 等几秒再点是正常的。不正常的是 漏锁:sync_users/_pull_changes先拿锁、再写那条「进行中」的记录,这一段原先在收尾那个try之外,库断了或表结构落后(Unknown column 'oa_hub_sync_run.renamed')就让异常从这段漏出去, 本进程那把锁从此永久握着:跨副本那把最多一小时自己过期,这把只能等重启,于是每一次同步(连调度线程 每几十秒那趟增量一起)都只剩这一句提示,而同步历史里连一条记录都不会有。现在这一段自己负责交还锁, 失败就当场如实报库的错误,不会再伪装成"有任务在跑"。 验收见backend/scripts/check_hub_sync_lock_leak.py。 -
换过主键的部门能一键收尾:Hub 挪了
organization_id之后,本地靠「编码 + 名称」认回原部门, 旧的那一具就脱成停用的空壳子(同名同码、身份已被在职部门接走,同步既不再认它也不会合并)。GET /api/v1/org/units/shells列出这些壳子并逐条说明删不掉的原因(挂着人 / 有下级 / 被权限角色当数据范围),POST /api/v1/org/units/shells/cleanup只删三样都干净的那几具, 删除前逐条重算判据,不认前端传来的旧名单;体检对话框上直接给按钮。 验收见backend/scripts/check_hub_sync_shell_units.py。
同步定时任务
排期不进 crontab、不建表、不改表结构,就是 hub_sync 那一组运行配置:
系统管理 → 同步定时任务(/settings/sync-jobs,权限 system:setting)上配,
保存即生效,下一轮调度判断就按新排期走,不用重启后端。「人员管理」页头「立即同步」
旁边也有入口跳过去。
- 总开关只在这一页:
hub_sync_enabled(「允许定时同步」)以前也能由配置文件或部署 模板给值,结果是它被悄悄关掉、定时任务不跑而界面上查不出谁关的。现在环境变量与配置 文件都不认它(出厂模板里没这一行,文件里残留的会在启动日志点名说不生效),默认开着, 只有这一页保存的值管用;被它挡住时页面上那句话会直接指出在哪一格打开。 升级注意:老部署若在环境变量里写着OA_HUB_SYNC_ENABLED=false,升级后这一行不再 管用(界面上没存过就是默认开着,定时同步会开始跑)。要停同步就去界面上关,或者用仍然 认环境变量的应急总闸OA_HUB_DISABLED。 - 四档频率(
hub_sync_when):每天在指定时间、每周选几天、每月选几天、按间隔(从上一趟跑完算起隔多少分钟)。配套hub_sync_time/hub_sync_weekdays/hub_sync_monthdays/hub_sync_interval_minutes, 环境变量OA_HUB_SYNC_WHEN/..._WEEKDAYS/..._MONTHDAYS/..._INTERVAL_MINUTES。每月选了 30/31 号在短月顺延到当月最后一天,不会整月一次 都不跑;档位名或日期写歪了退回默认(每天 / 周一到周五 / 每月 1 号),不会让同步 因为一处笔误悄悄停掉。 - 页面上就答得出「下一次什么时候跑」:全量与增量两张卡片各自给「下一次执行 /
下一次轮询」加倒计时、往后 3 次的时间、当前口径、近 30 天跑了几趟,被什么挡住了
也直说(应急总闸关闭 / 未启用统一身份 / 没填站点地址 / 定时同步关闭),下面是最近
执行记录。数据来自
GET /api/v1/hub/schedule(org:person,只读),跟后台调度 线程算的是同一段代码(service/sync_jobs.py),不会两边各算一套。 - 补跑有窗口:应用停机错过排期点,只在排期点之后 12 小时内补
(
sync_jobs.LATE_GRACE_HOURS)——错过一个月的 monthly 不会在三天后突然补一趟, 而是等下一个排期。手动「立即同步」不占排期那一趟的坑,挡不掉也不会顶掉下一次排期。 - 失败补试沿用
hub_sync_retry_minutes/hub_sync_retries(间隔与当天次数上限)。 - 改造前只有「每天 HH:MM」这一档,那一档的判定口径一条没变。
大模型接入
系统管理 → 大模型接入(/settings/ai-models,权限 system:setting)里一条接一家:
服务商、接口地址、密钥、模型清单、采样参数、启停与默认接入,存在 oa_ai_provider,
保存即生效,不用重启后端。目录清单、逐项字段、密钥口径、代理与直连、排障表见
docs/llm-integration.md。
- 五种报文协议:OpenAI 兼容(Chat Completions)、Azure OpenAI、Anthropic Messages、
Google Gemini、Ollama 原生。目录预置 24 家(国内厂商 12、海外厂商 6、本地私有化 4、
网关与自定义 2),选一家就带出厂接口地址、密钥栏叫法、常用模型清单和一句话提醒;
目录里没有的选
自定义 / 其他网关,先挑协议再填地址与密钥,一样能接。 - 四个「试」:
测试连通(先列模型再发一条很短的对话,两步各验什么摊开给你看, 结论写回这条接入的「最近测试」)、拉取模型清单(把服务商那边的模型名抄回来)、试运行(真发一句话,回正文、用的模型、耗时与 token 用量)、先试一次(还没保存 就拿当前表单试,不写库)。测不通也回 200 加一句中文结论,不会只甩个 400 弹提示。 - 密钥只进不出:接口只回「配了没有」和这家的鉴权方式;保存时留空 = 不改这一项; 操作日志只写字段名不写值;服务商回的错误原文出门前先过一遍脱敏。与 MinIO、Hub 的密钥同一套口径。
- 总闸与补试是运行配置里新增的一组
ai(现在共 7 组,界面上叫「大模型能力」, 系统设置页和这页页头的卡片是同一份数据):ai_enabled决定业务功能能不能真的去调模型,关着不影响页面上的测试与试运行, 方便先把接入验通再打开;ai_retries只补「连不上、超时、5xx、限流」这类错;ai_log_prompt控制日志里带不带提示词原文。环境变量OA_AI_*,出厂模板config.toml.example的[ai]段。 - 本机模型不被代理劫走:目标是回环或内网地址时忽略
http_proxy直连,本机开着 Ollama / vLLM / LM Studio 就接得上,不必先去改no_proxy。 - 业务侧入口是
service/llm.py的generate(prompt, rows=启用中的接入):总闸关着、 没有启用的接入都会明确报错。截至目前还没有业务功能接它,接入、测试、密钥管理这 一整套已经可用。
大模型怎么用
接入只是把管子接上,真正让人用上的是**「AI 助手」页面**加散在各页面的场景按钮: 单据摘要、审批要点与风险、审批意见草稿、资讯摘要这类小入口,共用一套开关、权限、 脱敏与审计口径。页面长什么样、系统里哪些地方该用与明确不该用、分几期做、怎么验收, 见 docs/llm-usage-design.md; 设计稿 design/ai.html 浏览器直接打开就能点。
引擎能力
环节类型:开始、人工审批、条件分支、并行网关、汇聚网关、数据拆分、脚本、服务调用、子流程、延时、结束、取消。
流转语义:
-
或签(
mode: any,任一人办理后其余自动办结)、会签(mode: all,全部办理)、 依次审批(mode: serial,按顺序一个接一个) -
按比例会签(
mode: ratio+passCount/passRatio):三人评审配「2 票放行」, 同意凑够 2 票当刻就往下走,还没表态的人自动结掉并写明「同意已达标」; 有人明确选退回路由时仍然立刻退回,比例只决定「同意要几个人」 -
汇聚网关默认等所有支线到齐,也可以配
passCount/passRatio改成「到 N 票就放行」, 没办完的支线不再挂着;配额在分叉时抄进票箱,退回重跑仍是同一口径 -
条件免审(环节
config.skipRules):一条规则 = 一个条件(与分支条件同一套表达式)+ 免审范围,scope: matched只免掉点到的那几个人(来源仍是找人那套taskValues),scope: all整环免审; 被免掉的人不派待办、收不到消息 -
条件必批(环节
config.mustRules):命中条件的人这一环必须批,不在审批人来源里也会被加进来, 且免审规则与「前面批过就跳过」的去重都摘不掉他。只把他写在这里、不写进审批人来源, 就是「满足条件他才批,不满足就不用批」 -
重复出现的同一个人是一档策略,不是几个各开各的开关。界面(流程设置与环节右栏都叫 「重复出现的同一个人」)四选一:
each每次都签 /first只签第一次 /last只签最后一次 /once只签一次;流程级配默认、环节上可逐个覆盖,环节上多一档「跟随流程设置」=删掉那两个键。 继承是按方向一个个来的(环节只钉了一个方向时另一个仍跟流程默认走),所以右栏显示的是 算完流程默认之后真正生效的那一档,只钉了一个方向时下面会写明为什么和单独钉的那档不一样。 存储不动,还是那两个方向相反的开关(环节skipApproved往回看、skipAhead往前看;流程级approval_config.dedup=all与dedupAhead=all/any),折算口径两边一致:engine.repeat_policy(后端)与utils/approvalDedup.ts(前端) -
往回看与往前看不冲突,也抵消不掉对方:往回看那档以「已办」为凭,而往前看跳过的环节根本不 产生已办,所以同一个人这张单一定至少真签一次。四档的实在差别要在有「躲不掉的环节」时才 看得出来——起草环节和退回到达的环节一律不许往前看跳过(那两张待办是落脚点),命中的必批规则 保下的人也不跳。张三一个人跑完「填写申请→初审→终审」:
each签 3 次、first签在填写申请、last反而签 2 次(躲不掉的填写申请 + 最后那一次)、once签 1 次且签在最早躲不掉的那一环。 只想让他签一次就选once,选last是「把签字挪到最后一次」,不是「只签一次」。 算法在engine/lookahead.py(不碰库,纯图分析),日志措辞在engine/engine.py -
往前看的判定口径
approval_config.dedupAhead:默认all只在后面每一条路径都一定经过他时 才免掉前面这一环——或签、按比例会签、解析不出人的环节、免审条件碰得到他的环节都会让「一定」 不成立,这时前面照常派待办;any是「有一条后续路径可能用到他就跳」,省待办更狠但分支 一拐弯他可能一次都没批过(环节skipAheadScope单独改口径)。dedupAheadKeepOne再兜一层: 整环的人都被前瞻免掉时留第一个人在这一环签 -
往后看认路由上写的条件(
engine.forecast_routes,与_pick_choice/route_guard_ok同一套口径):条件分支按当前这份表单收敛成引擎真会走的那一条,适用条件不成立的出口先剪掉—— 否则画了条件分支就永远「有一条路不经过他」,配得再死也免不掉重复签字。两处例外都往保守方向: 条件当场算不出来(字段还没填、式子写坏)算「说不准」,那条出口留着;退回路由不算往前走 (退回是把单子打回去,不是批完,与试跑service/simulator.py一致),后面那一环的免审条件 也只按人判:规则点的是别人,就不该拖住整环说「他可能不签」(口径在engine.rule_reach) -
「前面已经批过」认的是亲手表态(
engine._approved_persons),四种"看着像批过"都不算:processing_type != normal(或签 / 按比例会签凑够票后被系统代结的、转办出去的、加签转走的、 终止掉的)、走回头线出去的那一票、开始环节那一张「提交」、dedupSince基线之前的老票。 前两条的判据统一成definition.is_back_route(goBack/reject/ 没标语义但绕回自己那条边), 与设计器画布、审批记录、前瞻用的是同一把尺子——以前这一处只认decision == "goBack",而设计器 那颗「驳回」下拉写的是reject,于是驳回的人在"谁批过"这一问里被当成同意过的人 -
驳回之后重走,驳回前那几票一概不算:往回走的那一下由
_advance把dedupSince推到此刻 (挂在_advance而不是go_back上,是因为"按下一条线往外走"只在这里表达一次——界面提交、 开放接口代点头、超时自动驳回、第三方回写全都从这儿过;只挂在go_back上时画成「驳回」那条线 就漏在外面)。治的是这一条现场:财务经理 14:41 点了驳回,15:45 重新提交,紧接着同一秒里 财务经理 / 财务总监 / 补充确认信息 / 总经理 / 部门主管一路「自动跳过 · 同意」,理由清一色 「审批人去重:某某前面已经批过」——连驳回的人自己都被算成"前面已经批过",一张刚被打回去的 单几乎没再看一眼就自己走完了。开始环节那张「提交」不算谁批过一步是同一处的第二件事: 第一次发起压根没有开始环节的已办,退回来再提交时多出来一张,两次算出来的人不一样,就会出现 「刚点完提交,自己那个确认环节被自己免掉」这种第一次没发生过的跳过。同一轮之内的去重 照旧生效(上一轮批过的人要重新表态,这一轮刚批过的人还是照常免掉),守卫见scripts/check_dedup_rerun.py(标reject的驳回线与连语义都没标的那条各跑一遍真流程) -
这套规矩在设计期就看得见结果,不必发一单才发现谁被跳过了:
service/dedupaudit.py拿画布上 当前这份设计(含还没保存的改动)按组织现在的找人结果试算一遍,逐个人给出「会签两次 / 已自动跳过 / 要人确认 / 分支互斥」四档结论。接口POST /process/processes/{id}/dedup-audit, 界面是流程设计器右栏的「审批体检」页签:点环节直接跳到画布那一环、环节上挂「谁在这里会被自动 跳过」的角标、工具栏那个红色数字是没管住的组数、发布前再拦一句,还给一个能直接按下去的最小修法 (改流程默认那一档,或把钉死了「不许跳」的那几环退回跟随流程设置)。判定不复算规则,直接调repeat_policy/ahead_scope/approval_flags,只有「后面这一环躲不躲得开」按图算,口径与lookahead的必经判定一致,路由上的分支条件同样由engine/conditions.py读进图里:走到某一环 得先满足什么、哪条分支在前提下已经堵死,都参与「会不会两次都走到」「后面必经他吗」这两问; 条件只对不上、同一张单根本走不到一起的那一对,单独列在impasses里并说明凭什么排除。 每对重复还带一个cause说清是哪一档没管住(policy_off没配 /ahead_unproven往后看不敢断定 /first_node起草环节躲不掉 /concurrent并行同展 /must_rule必批规则),并点名挡路的那条分支(blockers:哪个环节的哪条出口、它看哪个字段), 前三种一键修法管得着——橙色的「要人确认」里那种「策略开着、只是被 分支卡住」同样给一键修法,不再只有红色才出声。靠发起人 / 上一环节处理人 / 表单 / 脚本找人的 环节标dynamic,那条结论带「这条是试算」,但降的是「判得准不准」不是「管没管住」: 往回看管住的一对,运行时换成谁都管得住,就按「已管住」报,不让配好了的策略一直挂着橙灯。详见 docs/approval-dedup-design.md -
谁被免审、谁被必批加进来,都写成一条流转日志(
skip/skipPart/mustPart), 审批记录里排成一步(免审的环节照样占序号,写清为什么没经他批),轨迹图上那一环也标成skipped并带上原因——见service/flowmap.py与utils/approvalRecord.ts -
抄送在流程步骤上有落点(原话:「流程中没有展示出抄送信息,每一个环节配置的抄送 信息也需要在流程步骤体现出来」)。每个环节带一份
cc:people是这一单实际抄给了谁 (送达时间、看没看、要不要他处理、谁送的、留了什么话),rules是这一环配了哪几条 抄送(时机 / 要不要处理 / 有没有条件 / 对象来源),两条分开给——没走到的那一支也有 配置,走到了也可能一条都没抄出去(条件没命中、找不到人、要抄的人正好在这一环办事)。 判据见service/flowmap.py::attach_cc,只认read_type='cc':分享与批注 @ 我是别人 手工点的,与环节配置无关,不挂到这一环名下。这一格现在有五处摆法,共用
frontend/src/utils/flowCc.ts那一份说法(人名裁几个、 欠账怎么报、配置逐条怎么念、悬浮提示说什么、逐人的处理结果怎么说)。各处自己再拼一遍, 迟早长成「图上说抄送 2 人、记录里只列一个名」:-
流转轨迹图(
FlowTrajectory):环节卡片那一行摆人名加欠账人数;只配了规则没抄到 人时只在角上留一枚邮戳,不说成已送达。卡片尺寸与设计器共用,撑高会连带挪走连线端口, 所以与处理人并排那一格抄送先让位、只报一个人,那本账留在悬浮提示里; -
点中环节那一栏(
FlowNodeDetail):逐人说清看没看、办没办、谁送达、留了什么话, 再把配置逐条摆全;配了规则却一个人都没抄到时,四种可能都写出来,不让人以为页面坏了; -
审批记录那条时间线(
ApprovalRecord与手机端MobileFlow):挂着环节的每一步 (审批步骤、整环跳过、按条件加减人那几条)下面都有「抄送 谁谁 +N · 未阅 / 未处理」 那一行(配了规则还没抄出人的那一步也在,只报条数)。这一处只摆实况,不摆配置 (原话:「审批记录里面,这一环配置的抄送不需要展示出来」)——时间线答的是 「这一环抄没抄、谁看没看」,「这一环本来配了哪几条」是流程配置,看上一栏那个环节 面板就够,记录里再抄一遍只把事实挤下去。数据按环节 id 从同一份flow.nodes[].cc接回来 (utils/approvalRecord.ts的ccLookup),不认环节名——环节会改名,日志里那个名字 快照是当时那一份。轨迹图没给(老 payload、只喂已办列表的那些调用方)就没这一行, 比摆一句「未配抄送」诚实;批注与引擎事件不属某一个环节,那两类行上没有它。手机端 那一栏同样不折叠:已发生的每一行都摊开,只是不再跟着摊配置。这一条时间线后来被追问了四回(原话:「办结时的抄送记录以及收到抄送的人的处理结果 呢?没有在审批记录中展示么?」、「转发的处理结果也需要在审批记录中展示出来」、 「流程所有环节都需要考虑」、「抄送收到消息的人处理时上传的附件、图片都需要展示在 审批记录中」),补了三样:
- 逐人的处理结果:那一句「抄送 2 人 · 1 人未阅」只报数量,被问「陈妮到底办没办」
还是答不上来。所以抄送块里一个人一行,说
已阅于几点/未阅/已处理于几点/已阅 · 待处理(ccResultBrief),后面跟他回的那句还是抄送人的来意 (ccPersonOpinion——mark_read在本人填意见那一趟会把那句话覆盖成他写的那句, 所以「已处理」的那句是他的回复,没处理的那句是别人的来意,标错等于把话记错人)。 两个时刻由后端cc_of_read一起给出(view_time/handle_time),没给就只说状态, 界面上不编一个时间出来。转发那几行读同一份说法(forwardLineBrief),一处改了 两处一起改; - 他处理时上传的附件与图片:只收文字意见不够——「已登记台账,回执见附图」那句里
的图从前只在被抄人自己的已阅列表里看得到,审批记录这一屏读的人压根不知道有附件。
后端把待阅行上那份引用快照原样带出来(
flowmap.cc_of_read的attachments, 就是engine.mark_read(attachments=[…])→claim_attachments()落在oa_read/oa_read_completed上的那一列,形状与前端AttachmentRef一致, 不重查附件表);一个人被同一环抄过两次时两行的附件按 id 去重合并 (_merge_attachment_refs)。界面上每个人那一行下面挂AttachmentGallery(data-test="oa-record-cc-files"),转发那几行同样带(oa-record-forward-files); 手机端文件名常驻、「附件 N」点开才拉缩略图,打印件只列文件名——纸上印不出可点开的图; - 没有审批记录的那些环节自己成一行(
utils/approvalRecord.ts::ccEntries): 结束(办结)、作废、开始这三类环节不派生待办,既不在已办里也不在整环跳过里, 主线上一行都没有;而引擎办结时恰恰把「办结抄送」记在结束环节身上 (engine._finish_work拿结束环节调apply_activity_cc)。不单独成行,那几条 抄送在审批记录里就一个字都看不见。角标跟着环节类型说「办结时的抄送 / 作废时的 抄送 / 抄送送达」,此刻还停着没人签的那一环(到达时那档已经抄出去了)也照样成行, 所以它不再挂在末尾那句「等谁处理」底下——两处各摆一次反而像抄了两回。 没走到的那一支不成行:那一支只有配置没有事实,摊在时间线里会读成「抄过了」。
- 逐人的处理结果:那一句「抄送 2 人 · 1 人未阅」只报数量,被问「陈妮到底办没办」
还是答不上来。所以抄送块里一个人一行,说
-
打印件(
PrintWorkView):审批表多一列抄送。纸上没人能点开环节、也没有悬浮提示, 人名一个都不裁,每个人后面跟着他的处理结果,再跟一句他随意见上传的文件名;配置只报条数不逐条摆全——逐条摆会把一张 A4 撑成两页,而打印要答的是「这一环抄过谁」,不是复核设计稿。没有审批记录的那些环节的 抄送也补几行进那张表(ccEntries同一份判据),否则纸上签完字以后抄给谁查不出来; -
发起之前的「流程环节」那一圈(
StartFormView):单子还没建,没有送达那本账, 摆的是配置——「这一单会被谁看到」是发起之前就该答得出的问题。设计器那份config.ccRules由ccRulesOfConfig折成同款简报,缺省与判据照cc_rule_briefs抄 (when缺省arrive,conditional认表达式填没填)。办结抄送配在结束 / 作废环节上, 被那一圈的type !== 'end'摘在圈外,单独补几行露出来。
跟着一起钉住的两句分寸:结束 / 作废环节上存的
when就是arrive,说的却是办结那 一刻(设计器那颗钮写「办结时」),照字面念成「到达环节时」会被读成「单子还没办完就抄 了」,所以时机那一句跟着环节类型走(ccWhenLabel);试跑预测那一趟没有「送达」这件 事,未阅那本账不编,只报「预计抄送」与要不要处理。守卫:scripts/check_flowmap_cc.py(51 项,第 8 节钉的是逐人两个时刻与办结抄送落点,第 9 节是随处理意见一起交上来的附件)、utils/flowCc.spec.ts、utils/flowForwards.spec.ts、ApprovalRecord.cc.spec.ts、ApprovalRecord.forward.spec.ts、FlowTrajectory.cc.spec.ts、FlowNodeDetail.cc.spec.ts、PrintWorkView.cc.spec.ts、MobileFlow.spec.ts -
-
抄送条件(环节
config.ccRules[].expression):每条自动抄送规则都能带一个条件 (与分支条件、条件免审同一套表达式),这一单命中才抄这一条;留空=无条件,到点就抄, 老配置的行为一个字都不变。人工环节、结束/作废环节的办结抄送同一个口径, 条件算不出来按「不抄」处理,免得表达式写错时把单子扫给不该看的人 -
退回:退回上一环节 / 退回指定环节 / 直接退回发起人,可指定退回后的走向。退回发起人 不受环节
goBackConfig.type影响,永远在候选最后;提交人在开始环节拿到一条待办, 改完重新提交就从开始环节那条出口重新往下走(嵌入子流程与发起人身份丢失时不给这一项) -
加签:前加签 / 后加签 / 并加签,支持指定多人
-
转办与委托办理,被转办人办结后原办理人回到已办并可撤销转办
-
已办撤回(在下一环节尚未处理时回退)
-
「我的已办」按单折叠:同一张单办过几次也只摆一条,摆最近那次表态,旁边标「已处理 N 次」, 历次意见与流转在详情的审批记录里一条不少。流水账不改写法——审批记录要逐条回放、按比例会签 要逐票数票、撤回已办按行号定点撤,三件都按行算——折叠放在读这一侧(
service/completed.py)。 列表总数、导出 CSV(多带一列「处理次数」)、首页角标、工作台那个「我的已办」一起改成数单 不数行:两处口径不一样时,人只会以为系统把数据弄丢了 -
「我的已办」那一列「当前环节」说的是这张单此刻停在哪个环节、压在谁手上(不是本人办过的 那一步;已经走完的写已办结 / 已终止 / 已作废)。已办行上冻着的那一份
current_activity_name只在归档那一刻整批写一次,引擎每次往前走刷的是待阅行,在途单读出来一直是空串——所以读这一侧 按work现问oa_work/oa_work_completed(service/completed.progress,两表并成 一条UNION ALL,一次来回问完一页,导出那一路按 500 个号切刀),一行历史都不回填。 原先独占一列的「流转路由」收进「处理环节」那一格下面当小徽标,两列各让宽(190 / 200 像素), 导出 CSV 同步多带「当前环节」那一列(插在「环节」右边) -
催办(累计次数与催办时间)、管理员代催办
-
待办按所属单据的流程状态筛(
GET /task/processing?work_status=,逗号分隔多选): 待办行上那份status只有pending一个值,说的是这条待办办没办完,答不出「这张单 现在还在走么」,所以这一档回查两张流程表——在途认oa_work,办结 / 终止 / 作废认oa_work_completed,取值与流程监控、「我发起的」、明细导出同一套。另认paused一档 (挂起是运行中的冻住开关,不进status,判据是oa_task.pause,与行上那枚「已挂起」 角标同一份)。列表、批量「全选这一片」、导出 CSV 三条口共用这一份条件:筛出几条就批几条、 导几条,界面上看得见却筛不出的行不会存在 -
终止流程、已阅件、草稿箱、附件上传下载
-
待办是一张取件箱(原话:「所有抄送需处理的流程都推送至待办里面去……每条流程都有一个标识(红点) 表示还未读,读了之后红点消失,但是还是在待办里面。只有单条、批量处理后才会移到已办中」 「转发需处理的也是全部推送至待办中」「界面就不需要待阅列表了」):
GET /task/inbox把三档并成一页按送达时间倒序——approval(我自己的待办,oa_task)、cc_action(抄送 / 转发需处理,oa_read.requires_action=1)、cc_read(只需阅)。三档互斥、 加起来就是整张列表,界面上一排档位各带条数。每行出参直接带unread,前端不自己比时间戳: 待办那档认view_time,抄送那两档认新加的oa_read.seen_time——view_time在已阅档上 是 NOT NULL、语义是已阅时刻,"打开过但还没办完"不能算已阅,复用它是把两件事压成一格。 已读不是已办:红点灭了行照旧在待办里,只有单条 / 批量处理才离开;只需阅那一条看过即归进 已阅。_refresh_read把不需处理改成需处理时清seen_time——看过一眼之后这事变成我的,红点要重亮。 批量两个口子按档位分头走再并成一份账单(POST /task/inbox/seen盖时间戳、POST /task/inbox/execute待办走出口、抄送登记处理意见)。界面上不再有「待阅」那一屏:/read只剩已阅一档,手机首页那张「待阅」卡一并删掉(同一批东西给两个入口,人反而要分清 哪边才是真的)。为什么选并页不选"抄送也搬进oa_task"、PC 与手机各自的版式怎么定,见 docs/todo-inbox-unified-design.md;守卫scripts/check_inbox_read.py、views/oa/TodoListView.inbox.spec.ts -
办完的抄送进已办,看过的才算已阅(原话:「为什么抄送、转发需处理的消息,处理后到了已阅 里面。应该是抄送、转发需处理的消息处理后才已办中。抄送、转发无需处理的消息处理后才会到已阅里面, 顺便考虑历史处理的处理」):判据
oa_read_completed.requires_action本来就有,从前只是读侧 没拿它分家。已办(GET /task/completed)接着读第二本账——=1那几条翻成已办那一份形状 (done_source="cc"、processing_type="cc",没有出口也撤不回),已阅(GET /read/completed) 只回=0,那一格从前用来挑需处理的action参数一并摘掉。不搬库、不回填:改版之前办完、 一直躺在已阅里的那几条,今天自动出现在已办,回滚也只是回到读法不同;也不往oa_task_completed插行——那张表是审批流水,「他签过没」(engine._approved_persons)、 按比例会签数票、撤回已办按行号定点撤,三套判据都按行算,插一行没出口的表态会让它们一起说谎。 已办按(单 × 来源)折叠:同一张单的审批表态与抄送处理各摆一条、各数各的次数,总数跟着换成 组数(与分组同一条语句,页眉的数和翻得到的条数不会分家)。首页那张「已办」卡、工作台那一行、 导出 CSV(多一列「类型」:审批办理 / 抄送处理)四处同口径。核账见sql/upgrade/20261117_done_cc_split.sql(只有SELECT,一条UPDATE都没有),守卫scripts/check_done_cc_split.py -
抄送需处理那句处理意见改成选填(原话:「处理的时候会弹出弹框,这里希望不是必填, 用户可以选择不填写」):必填的是「本人按下了处理」这一颗钮,不是那几个字——逼人编一句「已阅」 只是把档案写脏。留空(含只有空格)照旧落
handle_time,也不覆盖抄送时对方写的那句来意 (「请补充说明」);「标记已读」那一趟(handling=False)仍不动需处理的那几条,skipped说的是「需要你点「处理」确认」。单条/read/{id}/handle、批量/read/view/batch、 统一待办/task/inbox/execute三个口子同一口径 -
流程代理(休假期间自动代为处理)、待办交接
-
超时与超期提醒:延时环节唤醒 + 超期标记 + 调度线程
-
批量审批:
POST /task/batch-execute一次提交多条待办,逐条复用单条流转、逐条提交, 某条因为必填没填而失败只回滚那一条,失败原因原样带回界面逐条列明 -
批量标记待办已读:
POST /task/view/batch(engine.mark_tasks_viewed)只给oa_task.view_time盖一个时间戳,不表态、不流转——单子还压在人手上,出口、超时、 审批记录一概不动。这一格从前只有进详情页才盖得上(POST /task/{id}/view),一屏十几条 「先看一眼、待会儿再批」的要点十几下。分开两颗钮是有原因的:混在一颗上,人只会挑那颗 看着更狠的去按,于是只想看一眼的几条被顺手批掉。也正因为不表态,它比批量审批安全得多: 不需要共同出口、不撞必填校验,误操作最多是把「什么时候看的」写得早了一点——但界面上 仍要先确认一次,代理与交接的场合那一格是要拿来说话的(谁什么时候看到的) -
批量能按当前筛选取整片:两个批量口子都收
scope(task_ids与scope同时给以task_ids为准——屏幕上勾着什么就动什么)。scope里那几个字段与GET /task/processing(待阅那边是GET /read/processing)一字不差,走的是同一份_task_conditions: 表头那只勾只勾得到已经翻到的几页,「还有 N 条没翻到」时批量就成了假省力。同一把尺量出来 的结果是「列表筛出几条 = 动了几条 + 因超限留下几条」,不会出现页眉写着 12 条、批量只办 8 条; 身份那道闸也在这份条件里——别人名下的筛不到,也就批量不到。「批量标记已读」默认只在viewed=0那一沓里取(整片里早被点开的那些本来就没什么可动,留着只会占掉 50 条的额度, 把真要处理的几条挤成超限),配套的「只看未读」开关落在GET /task/processing?viewed=0 -
五档账目各归各,不合并:
marked(成了几条)/already(本来就是这状态)/skipped(要额外条件、这条没动,带逐条原因)/truncated(超单次上限 50,一条都没碰)/failed(真没办成,逐条原因)。混档的代价是人以为这一批出了错,回头把整批重勾一遍;truncated不直接 400,勾上就是要办整批,先让他看见差多少再自己勾第二批。界面那一头 待办与待阅共用同一套措辞(utils/oa.ts::reportBatchOutcome),两页不会各说一套。 守卫scripts/check_task_batch_read.py(39 项)与views/oa/TodoListView.batchRead.spec.ts(13 条); 待阅那一路另有scripts/check_read_batch.py(36 项)与views/oa/ReadListView.batch.spec.ts(14 条) -
流程展示步骤默认全部展示、不隐藏(原话:「流程展示步骤中我希望全部事件默认是 全部展示,不隐藏」)。三处默认值一起翻过来,判据一个字都不动,只是不再默认收着:
- 审批记录里那颗「全部事件」(桌面
ApprovalRecord与手机MobileFlow的showAll) 默认true:网关分流、脚本、服务调用、干预改道、办结这些引擎事件一开屏就排在时间线 里。收着等于让看图的人自己脑补这一单怎么走的,而它恰恰是「这一单到底怎么走的」的一半; 那颗钮留着,用途反过来——点一下只留审批步骤,title两档各说一句(recordEventsHint/recordEventsHintOff); - 只读轨迹图上每条出口的条件默认全摆(
FlowTrajectory的showAllLabels默认true)。 判据与设计器同一句used || showAllLabels || lit,谈的只有默认值:设计器有那颗 「精简连线标签」的钮点得回来,只读图没有——在那里收起等于彻底看不见,而「这一单为什么 没走那条分支」的答案恰好挂在那句条件上; - 手机端那条流转线整条摊到底(早先就撤了「展开更早 N 条」那颗钮),抄送那一栏也不折叠。
没跟着翻的两档,免得被当成同类一起改掉:设计器画布上那颗「精简连线标签」还是用户自己按 (那是排版偏好,不是信息缺失);批注框里「同时通知」那一栏照旧默认收着——那是偶尔用一次 的输入项,不是被藏起来的事实
- 审批记录里那颗「全部事件」(桌面
-
待阅只有「进」和「出」两道门:进——环节自动抄送(到达 / 办完 / 办结三档)、审批人手工 抄送、分享、批注 @ 这六个入口只有一个出口,一律先落
oa_read,一条都不许直接进已阅档、 也不许只发一句站内信就把人打发掉(站内信是按「这一单上还有没有我的待阅」收尾的,待阅没落地 提醒也挂不住);出分两档、去两个地方——无需处理的那几条点开单据即登记 (POST /read/view按整件一起登记),界面上归已阅;需处理(requires_action) 的那几条只有本人按下POST /read/{id}/handle那颗「处理」才办得掉(随附那句意见可留空), 界面上归已办,点开单据与单条「标记已读」都顶不掉它。 单据归档那一刻现抄的抄送、以及归档前没被打开过的老待阅,都只是补completed/work_completed两个归档标记,行照旧停在oa_read:oa_read_completed.view_time是 NOT NULL,搬进已阅档等于替人编一个「已阅时间」,档案里从此分不出「看过」与「没打开」, 勾了需处理的还会被悄悄勾掉。加签与转办不产生待阅——那两条给的是待办。 处理确认那一趟以本人写的那句为准:从前「先写的占住、后写的丢掉」,抄送时那句来意 (「请补充说明」)会把那一格占住,本人填的处理意见凭空蒸发,像是根本没处理过 (engine.mark_read的handling)。守卫scripts/check_cc_entries_to_read.py -
批量登记待阅:
POST /read/view/batch一次勾几条,服务端逐条走单条那一份判定 (engine.mark_reads_batch:一条一个存档点、坏一条只回滚那一条、一批上限 50), 判定不在批量这一层重写,也不许把「需处理」放宽成「点开就算」——只盖章那一趟 (handling=False,界面上那颗「标记已读」)碰到需处理的就跳过(原样留在待阅里,skipped_items报得出是哪几条、为什么),不是失败;「批量处理」那一趟把它们一起办掉, 共用的那句意见留空也算表过态;不存在或不是本人名下的那几条只算它们自己失败,其余照常登记并提交。 回的是条数与逐条原因(marked/handled/skipped/failed/already/truncated), 不是一个成败布尔值:整批回滚会让已经办成的那几条从头再勾一遍。另两档各钉一件事——already:勾到时那一条早已在本人已阅里(列表页被页签缓存住、刚在单据页里看过的那一条 还挂在勾选里,很常见),那是办完了不是办砸了,混进failed会让人以为这一批出了错;truncated:超过单次上限 50 被切掉的条数,一条都没碰,不进上面任何一档——不报出来就是 「勾 60 条回 50 条已阅」,剩下 10 条没人提,人以为整批都办了;也不直接 400,勾上就是要办整批, 先让他看见差多少,再自己勾第二批。那句共用的处理意见与随附文件只跟着「需处理」那几条走: 只登记「我看过了」的那几条不吃这句话、也不被盖handle_time,否则一句「已核对」就成了 N 张单子的处理意见,档案里从此分不清谁真的表过态。界面那一头原是待阅列表(views/oa/ReadListView.vue) 上的「批量已阅」与「批量处理」两颗钮(桌面走DataTable多选、手机走MobileCardList的选择档), 2026-11 待阅并进取件箱之后这两颗钮长在待办那一屏(views/oa/TodoListView.vue+POST /task/inbox/seen/POST /task/inbox/execute),判定还是这三条写路径,一份没重写: 前者只登记看过、连一句意见都不发;后者必须本人自己写字,空着就拦下——抄送人那句来意不许顶替 本人的处理意见。三条跟着一起钉住:- 勾的是看得见的这几条:
selected跟着feed收窄——翻页、改筛选、切待阅 / 已阅档位, 凡是把某几条挪出眼前的那一下,那几个勾就一并收掉。钮上「已选 N 条」与真发出去的那一串 取的是同一份selectedRows,从此不可能「写着 3 条、实发 1 条」还静默少办; - 连着点不会发两批:四颗钮全吃
batchBusy(batchLocked),submitBatch进来第一件事 就是认这把锁。少了它,手快两下会发出两批,第二批整批落进already,界面上多冒一句 「之前已经登记过了」,越看越糊涂; - 「只登记已阅」这一趟不吃附件(后端口径如此),但图是人传好的:框里已经挂着图 / 文件时
点它会被挡下来给一句说法——要么连着意见一起提交,要么先把附件去掉,不静默丢。
真失败那几条也不只报个数:后端逐条带回来的原因,第一句(
errors[0].message)直接跟在提示里 说给人听,最常见的两种(不是本人名下 / 这条根本不存在)一句就能说清,别让人自己去猜; - 一张图要跟着那一批走:勾 5 条需处理的待阅、贴一张截图,那一句和那张图属于这一批,
不属于第一条。一条附件行只认一个
business_id,于是claim_attachments多一个clones(只给批量这一路用):第一条认领原行,后认领的几条各插一条指针行——只复制 内容列、storage还是同一个 URI,MinIO 里仍是一份字节,归属互不覆盖。少这一档就是 「两条一起处理,第二条报『附件已被其它批注使用』」,一批只办得成一条。批注与单条处理 意见不吃这一档,一张图被两条批注抢仍然是错误(docs/attachment-preview.md§8)。
完事按条数报(登记几条、处理几条、几条因为要写意见没动,早已登记的与超限没碰的各提醒一句), 再把勾清干净、重拉列表与右上角角标;跳单据页顺手带上
from=read,新标签页直达、刷新之后 站内没来路时,那颗「返回」才靠这一句认得回待阅(composables/useReturnTo.ts:站内来路 > 地址上那句 from > 调用方给的备选,且 from 只认表里点名的那几个值);守卫scripts/check_read_batch.py(36 项)、views/oa/ReadListView.batch.spec.ts(14 条)、composables/useReturnTo.spec.ts(4 条)与stores/tabs.spec.ts(7 条) - 勾的是看得见的这几条:
-
办结之后发起人还能把它转给别人看:
POST /work/{work_id}/forward(engine.forward_completed)。 办结那一刻待办全被收走,cc_task那条通道(要一张还在手上的待办)就此走不通;而「这张单办完了, 我还想让它进某某的待阅」是办结之后仍然会提的需求。share_work虽然也认归档件,但它没有一道 身份闸——任何登录用户拿到work_id都能把别人的单分享出去。这一条通道补的就是这两块:只服务 归档件(在途件挡回「请到待办里抄送」,否则等于开一条绕过环节「允许抄送」配置的后门)、 只有发起人本人(或管理员)按得动。来源仍写read_type="cc",不新增枚举:待阅列表、导出、 筛选、i18n 认的是 cc / share / comment 那三种,"转发"与"抄送"在待阅里本就是同一种东西(一条别人 递过来的单据提醒),界面来源那一格照旧显示「抄送」;但站内信与推送上头那句标题另给一句 「某某 转发了这张已办结的单据:…」(create_reads多一个可选head,不传就照来源那一类 取,六个既有入口的标题一个字都不变)——借通用那句,人只当是流程里顺手抄来的,看不出是谁 在办结之后又递了一次。默认requires_action=False(点开单据即转已阅,与上面那条口径同一条线),要对方写处理意见才转得掉的 显式勾上。附言不许空着——待阅里那句附言是人分辨"这条是谁、为什么发我"的唯一一句话,空着就只剩 「某某 抄送给您」一片空白,与他自己收到的普通抄送分不开,所以引擎兜一句「{发起人} 转发了这张 已办结的单据」。一次最多 50 人(FORWARD_LIMIT),超了宁挡不切:这批人是他自己挑着点下的, 静悄悄少发几个,界面上照样回「成功」。 按钮摆不摆只认详情报文里的can_forward(api/runtime.py,与can_terminate/can_start/can_comment并排),界面不自己再拼一遍「已归档 + 是发起人」——两边各算一套迟早对不上。 有一处两列同源的坑值得记下来:旗标比的是row.creator == user.person_id(users表行 id), 引擎那道闸比的是subject.creator_identity == actor.ref(登录账号)。同一张正常发起的单上两列 同源、认哪个都一样,但账号那一列会被人/组织同步改写(scripts/migrate_identity_refs.py --runtime那一档重写运行态的creator_identity),两列就有对不上的一天。旗标那一堆全站都吃person_id, 不为这一条单动它,于是把引擎那道闸放宽成任一命中即放行:闸比旗标严一分,造出来的是 「按钮摆出来、一点就 ENGINE_ERROR」;宽一分,最多是多按得动一次——方向上宁宽勿严。 桌面(WorkDetailView头部那颗oa-forward)与手机(「···」抽屉里那一项)汇到同一份提交逻辑sendForward,手机上那一层只 emit 不自己发请求,否则会长成「电脑上转完会刷新、手机上转完没反应」; 条数按后端回来的count算,不自己数人头(有人本来就在待阅里时,两个数并不一样)。转发的记录也排在流程步骤里(原话:「转发的信息记录也需要在这里面展示出来」)。 库里一条转发就是
read_type="cc"的一条待阅,光看来源那一格分不出它与环节配出来的抄送, 于是service/flowmap.py把它拆成两格给:flow.forwards:整张单一条账,一次转发一行(谁转的、转给谁、送达时间、看没看、要不要 处理、留了什么话)。它不挂任何一个环节——归档件没有「当前环节」可言,硬塞进某一环的cc.people里,图上就会念出「这一环抄给过一个办结之后才被转来看的人」,那是假话;flow.nodes[].cc.people[].forwarded:环节那一格只在人身上留一个记号,说「这人后来 还被转发过一次」。同一个人被抄过又被转发过时两本账各记各的,sent不重复加人。
摆法是五处,与抄送同一批落点(说法共用
utils/flowCc.ts,判据共用utils/flowForwards.spec.ts钉的那一份):轨迹图画布下方一条横幅(在图外,理由同上)、点中环节那一栏作一句旁注加人身上 的徽标、桌面审批记录单列一步「办结之后」(kind === 'forward',逐条摆,不并成「转发 2 人」, 因为「转给了谁」恰恰就是被问的那一句)、手机端MobileFlow同一条目、打印件另开一段。 转发不受「全部事件」那颗钮收放:它是这一单真发生过的送达,不是一条引擎噪声。 库里那一格是oa_read.forwarded/oa_read_completed.forwarded两个布尔列(ensure_columns自动补列,老数据默认 0),mark_read与_finish_work搬档时原样带过去,_refresh_read只在同一行已经落过转发时才把它 OR 住——归档件上重新点开一条老待阅 不该把抄送归属抹掉。守卫:scripts/check_flowmap_cc.py(51 项,第 7 节整段是转发,第 8 节是逐人处理结果与办结抄送落点,第 9 节是处理时上传的附件)与 前端utils/flowForwards.spec.ts、ApprovalRecord.forward.spec.ts。发起与闸那一段原有的守卫与 用例照旧:那条跨层断言(三个角色各读一次旗标、再照旗标去转,外加把两套身份列各自漂移的 样子都摆一遍)在check_forward_completed.py里,另有views/oa/WorkDetailView.forward.spec.ts(8 条)与components/oa/mobile/MobileWorkView.forward.spec.ts(4 条) -
全程留痕:办结时间、流转轨迹与工作日志
审批通过之后怎么把结果送回业务系统
报销单办结要在 ERP 开凭证、领料单审批要回写 MES——这条反写链路整个是配出来的, 加一次写回不改代码。三层配置,从「哪个系统」到「发什么」到「什么时候发」:
| 层 | 配在哪 | 配什么 |
|---|---|---|
| L1 接口注册 | 「流程设计 → 外部数据源」把方向选成「往外写」 | 一个系统一行:服务地址、鉴权、超时重试,以及怎么算成功(code == 0 这种判定)、上游凭证号在响应哪里取 |
| L2 写回模板 | 「流程设计 → 集成写回」(/design/integrations,权限 design:integration) |
一个接口一条:方法 + 接口路径(拼在 L1 那个服务地址后面,同一个系统的建凭证 / 查凭证 / 冲销共用一份密钥与限流)、报文映射(哪个字段取自表单哪格)、哪些单才发(按表单字段值筛,一张单按字段发不同系统就靠它)、响应回来的值写回单据哪格、失败策略、幂等键、冲销模板;「什么时候发」这一格只问三条终态(办结 / 终止 / 作废可以多勾,也可以一条都不勾),页面底部当场列出这条模板什么时候真的会发 |
| L3 流程挂载 | 流程设计器里选中环节(每种环节都有这一格,含发起与结束),展开「写回挂载」——环节那一刻要发,只在这儿配 | 这个环节发哪几个模板、四个时刻随便勾(到达本环节时 / 本环节审批通过后 / 本环节被退回时 / 本环节被撤回时,一条规则可以同时勾好几个,一份映射管四刻;「被退回时」还能再筛两道——退落到哪一环才发、这一退是谁按的(第三方调接口退回来的单独一档)、一个环节可以再加一条规则(几种时机、几套条件各判各的)、只有部分单据要回写就加一条结构化条件(还能给单个模板各加一条,按字段值把单分流到不同系统)、失败了是继续走还是挡住处理人;面板底部同时列出这张单配在办结 / 终止 / 作废那一刻的模板与没配冲销的那几个 |
映射里能写的东西:{form.x} 取表单、{item.x} 取明细当前行、{work.serial} 取单据信息、
{activity.id} 取触发这条报文的那一环(与幂等键里 {event_key} 同一个环节;要把环节 id 交给对方
让他回调用那一环的审批接口就写它,三条终态那一刻没有环节、是空串)、
{action.phase_name} / {action.route} / {action.opinion} 取是哪一个时刻、走的哪一条线、这一次填的意见(三条终态那一刻没有按钮,是空串)、{auto:today:YYYY-MM-DD} 取系统值、{cents:form.amount} 金额换成分、{attach:form.f:urls}
附件、dictMap 拿数据字典把「差旅费」翻成上游科目码、when 让某一行只在满足条件时才发、
each 把明细表逐行铺成数组。选好表单点「按表单字段生成映射」,这些行会按字段名先铺一遍,
剩下照着上游的字段名改。上游接口还没开发时把数据源选成「样例」通道或打开影子模式,
报文照渲染照留档,就是不打出去,链路能先配完验通。
「什么时候发」这一格不问环节:配一张写回模板的人只知道自己要发什么,那一刻还没决定它要挂在 哪个环节上——被追问时机,只能挑一个最像的顶上;而环节 id 是每条流程自己的主键,复制流程、按版本 恢复、导到别的环境都会换掉它,绑在模板上的那条写回从此静默不发,发件箱里连一条记录都不留。 所以模板这一格只回答「这张单走进终态(办结 / 终止 / 作废)时要不要发」,三条可以多勾(一条模板 同时管办结与终止,不用再复制两份映射),也可以一条都不勾——那不算是没配完,是时机还没定: 这条模板要么被挂在某个环节上,要么只在集成页人工重推。环节那一刻的时机、条件、要发的字段、失败 策略全在 L3 那一格。模板页底部当场给出「什么时候真的会发」= 勾中的终态 + 被挂在哪些环节的哪一时刻,
两处合起来才是答案;存量那批「模板自己点名到达某环节」的配置照旧发,页面上一个按钮把它们一次搬进
环节(写挂载与撤声明同一事务,中间不留"两边都没配"的空档)。除这两处之外还有第五个时刻:
「流程终止时」既不挂环节(终止不是画布上的一环),又不能只写在模板上(终态模板按绑定表单自动找齐,
同一张表单挂两条流程时,"终止时要通知上游"没法只给其中一条配),所以它配在流程自己身上——
流程设计 → 流程信息 → 终止,形状与环节挂载完全一致,只是时刻固定 terminate。
trigger_of 认 terminate / terminated 两种写法,幂等键里带 event_key=terminate 这一段,与模板
自己勾了终止那条(event_key 为空)天然两个键:同一个模板两处都配就各发一条,设计器与保存流程时
都会就地提醒,不替人猜要发几条。这一格也算第三处绑定点:模板页底部那份「什么时候真的会发」如今
合并四处(模板勾的终态 + 旧写法点名的环节 + 环节挂载 + 流程这一格终止挂载),少合并一处就是在这屏
对着人说"这条模板终止时不会发"而它其实每次都发;集成页的配置体检也扫这一格(模板是保存之后才被删、
被停用的,保存那道闸管不到)。细节见下一节与 docs/node-writeback-config.md §1 §3 §5.5.1。
退回与撤回也是触发点:界面上有「退回」「撤回」两颗钮,报文里以前却没有这两个时刻——想告诉上游
"这张单被打回去了",只能挂到收单那一环的「到达时」,归属当场错位(对面分不清是正常到达还是被打回)。根因是
go_back() / reset_task() 自己派待办、不走 _advance,那两个时刻压根没有钩子。现在 goBack 挂在
按退回的那一环上、recall 挂在被撤回那条已办所属的环节上(发起环节也有这一刻 = 发起人撤回自己的
提交),与动作同一事务入队;leave 的语义一字未动(退回与撤回都不算批完,也不会触发收单那一环的到达)。
幂等键只给这两刻补一截时刻段,arrive / leave 的存量键一个字节都没变,勾多个时刻不会平白多打一条。
哪些环节能勾哪一刻、那颗按钮开没开怎么参与判定,见 docs/node-writeback-config.md §1.5 §13。
退回还能再筛两道:退落到哪一环才发(goBackTo:@starter / @prev / 指定环节)与这一退是谁按的才发(goBackVia:oa / oa_confirm / open / embed)。判的是引擎真正算出来的那个落点,不是画布那条线的终点;第三方调 /open/* 退回来与审批人在待办页点退回走的是同一个钩子,所以那一路同样筛得到,对面也能从 {action.via} 看出这条回声是自己刚干的事。两格都不写 = 任何退回都发(存量配置零迁移),都写是 AND;默认幂等键不看落点与来源,要各发一条就在自定义键里加 {target} / {via}。见 docs/node-writeback-config.md §14 与 docs/goback-target-writeback-design.md。
配好的写回会烂:上面那些校验只在保存那一刻生效,而这一片的病绝大多数躺在"上一次保存时还是好的"
那些行里——环节 id 被复制流程换掉了、挂载点名的模板被删了、挂在环节上又勾了终态。三处都不报错,
发件箱一条记录都不留,只有单子走到那一刻才发现。所以集成页顶部有一条配置体检:后端复用保存时
同一把尺子扫全库(GET /design/integrations/audit),逐条点名并带着跳过去处理的位置(模板那一类
直接打开编辑器,挂载那一类跳流程设计器);命令行版 scripts/check_writeback_config.py 先报现库、
再把八种病各造一遍自证(体检工具自己没人验过,它那句"一切正常"和最初的"没人发现"是同一种失效),
现库有病就退出码非 0。口径见 docs/node-writeback-config.md §7.5。
投递不跟着审批请求走:办结与入队是同一个事务(单子过去了报文不会丢,单没过报文先发出去也不行),
提交那一刻把后台投递线程当场叫醒(跨副本走一条 Redis 广播),15/60 秒那一档轮询退回兜底,
所以"单办完了、上游还没收到"只剩毫秒级;一张单排着几条时一轮就按顺序发完,不是一条一等一个周期。
后台线程按退避 1m/5m/30m/2h/6h 重发,同一张单严格有序,X-Idempotency-Key + 本地唯一键挡重复。
重试次数用满进死信并给当时办单的人和模板负责人发待阅;进程如果停在「发送中」,重启后先当
结果未知、绝不盲发第二遍,要人打电话问过上游再点「人工确认」落定。发件箱里每条都能看
当时的报文、响应、耗时、第几次重试,改完模板点「重推」(必须填原因,且按新模板重新渲染)。
配置期不用猜:报文预览(不发送)、试跑 dry-run(真发一次到测试环境,报文与响应留在模板上给同行抄)、 报文历史、导入导出(L1 + L2 一套 JSON,测试环境配好导到生产,只换密钥和域名)。 设计期把写歪的配置挡在保存之前,前后端同一把尺子:字段不存在、明细表指错、 幂等键少了模板编码、响应回写的字段审批人还能改、环节挂的模板已被删——都当场说清楚。
口径与缺口见 docs/outbound-integration-design.md, 给上游看的接口契约见 docs/integration-contract.md。 对账(按天问上游「今天有哪些单」与发件箱比差异)与灰度压测还没做,缺哪几项写在那份文档 §14。
上面那一整节讲的都往外走的正常路径:单子一级级批上去、批完定局、发凭证。「终止」是这条路上 唯一一处没走正常路径就散场的时刻,而它既不是一条路由、也不是画布上的一个环节,挂不到任何一环上, 所以「终止那一刻要调用哪几条回写模板」以前没地方配。它自己占一节,见下一节。
流程终止:谁能按、按到什么时候为止、按下去要发什么
起因是一张真实的报销单(2026-11-04):单子已经走到「部门主管」,主管一次都没打开过待办,发起人自己在 「我发起的」把整张单终止了,第二天主管来问"为什么给我终止了"。审批记录上那一行是红底一枚「终止」、 处理人写着主管本人、意见栏写着「流程终止」,谁都读得出是主管终止了自己的审批。读错的原因在档案表上: 终止前引擎要把当时还挂着的待办逐张强行结掉再归档,归档行照旧落在原持有人名下(他的已办里得看得见 这张单),而这张表压根没有一列写"是谁按的终止",意见那一格又拿系统兜底那四个字填上了发起人留空的原因。 终止这个动作一直是发起人随时能按——单子哪怕跑到最后一环、在别人手上搁了三天也照样能按,按下去可以 不留原因、不通知任何人、上游业务系统也不知道这张单没了。现在这三件事都能在流程上说一句。
入口两处在流程设计里,模板本体仍在集成页:
| 配在哪 | 配什么 | 落在哪 |
|---|---|---|
| 流程设计 → 流程信息(meta 面板)→「终止」 | 发起人的终止钮开不开、到什么时候为止不再许他终止、终止那一刻调用哪几条回写模板 | oa_process.terminate_config |
| 流程设计 → 选中环节 →「允许终止」 | 单据正停在这一环时发起人能不能终止(与「允许退回」「允许撤回」同一开关家族) | oa_activity.config.allowTerminate |
「允许终止」这一格以前就有,但只是一句谎话:接口把它回给前端、类型里也写着,设计器没有对应的勾, 前端没有任何一处读它,引擎更不看它——关掉了照样终止得动。现在它是引擎尊重的硬闸。
窗口四档单选(until):
until |
什么时候之前还允许发起人终止 | 用在什么场合 |
|---|---|---|
always(默认) |
随时都能 | 出厂口径,与这套配置存在之前一字不差 |
notHandled |
别人(不含发起人自己)还没办完过任何一步 | 单没落到任何人手上时,终止与撤回没多大分别;有人签了字就该走「退回」 |
beforeActivity |
还没走到指定环节(含这一环) | 「过了部门主管这关就别想反悔」。判据是到过,不是"还停在那儿"——单子从那一环流走之后再让终止,前面那位主管的表态就白做了 |
withinHours |
发起之后 N 小时之内(1-8760) | 报销单隔夜就没人再动,专治"第二天想起来才反悔" |
三条口径先说死,免得日后当成 bug 提:
- 只管发起人,不管管理员。监控页那颗「终止」是干预手段(单子办错了要收尾),与发起人收拾自己
交出去的那张单是两件事;管理员与
/open/*那两条路只受"是不是发起人或管理员"这一条老约束。 - 关掉就是界面不出现 + 引擎同样挡。只藏按钮不挡接口,等于留一个能绕过规矩的口子;只挡接口不藏
按钮,用户要点一次才知道不让。「我发起的」列表、单据详情、手机端三处读的都是引擎那一份判据
(
service/terminate.starter_blocker),界面上那句"为什么按不动"与引擎挡下时抛的那一句同源。 列表那一档只看开关(每行多算一次窗口要问库,代价不值),窗口类的判据留给详情页与引擎。 until是单选,不是能叠的清单。四档各有各的用处,叠起来的解释成本比收益高;既想"过某环节" 又想"超 N 小时",就挑更严格的那一条写清楚。
按下去之后引擎做五件事(原来只有前两件):
- 把还挂着的待办逐张结掉归档,并在档案行上写明是谁终止的(
oa_task_completed.operator/operator_name;本人自己办的那些照旧留空,两者分得开); - 往流转日志旁挂一条
terminate留痕,把操作人与原因落在单子上——审批记录据此在那一行下面显示 「由 X 终止」,读者不会再以为处理人自己撤了; - 给每一个待办被清掉的人发一条站内信。以前终止只给发起人自己发一句「流程已办结」,被清掉的人那边 永远挂着一条"等待您在【部门主管】环节处理",点进去是一张已归档的单,谁都不知道还要不要办;
- 按流程那一格入队写回,与终止同一事务(
event=terminated、event_key=terminate); - 照旧处理冲销:配了「冲销模板」就自动反向冲一条,没配就只在原报文上挂
needs_reversal让人工去上游 收尾,机器不猜这张凭证该不该作废。
终止原因在界面接口上改成必填(管理员干预与开放接口保留默认文案),空着时那四个字「流程终止」
再也不会冒充别人的意见。存量流程一条都不用迁移:terminate_config 空 dict 就等于"发起人随时能终止、
终止时不多发一条写回"。生产库上线要先跑 sql/upgrade/20261104_terminate_config.sql(加那三列;没开
auto_create_schema 时新后端读 oa_process 就会报 Unknown column)。判据只有一份,在
backend/app/service/terminate.py;验收 backend/scripts/check_terminate_control.py 全程跑在内存
sqlite 上(55 项:谁按得动、窗口怎么算、留痕与通知、终止那一刻的写回与冲销、这一格在合并清单与全库体检里
看得见、列表那一列的开关),一条语句都不碰生产库。
反过来:外部系统怎么调 OA,OA 怎么主动通知人
上面那条是"审批结果送出去"的业务凭证那一路(报文格式由上游定、发错要冲销)。 平台还留着另外几条路——往外三条、往里一条,配的地方与对账口径都不一样,别混:
| 你要做的事 | 走哪条 | 配在哪 |
|---|---|---|
| 办结之后按对方格式生成一张凭证 | 反写模板 oa_integration |
「集成配置」页,字段一格格映射 |
| 单据有动静就通知外部系统一声 | 事件订阅 oa_open_webhook(七个事件,HMAC 签名,默认不带表单数据) |
「开放平台」页 |
| 外部系统主动查/发起/代办 | 开放接口 /api/v1/open/*(应用令牌 + 五个作用域 + 限流与调用留痕) |
「开放平台」页建应用 |
| 同一条待办提醒送到邮箱 / 钉钉飞书企微群 | 消息渠道 oa_notify_channel(七个事件各渠道订阅,含「流程被干预改道」) |
「消息通知」页 |
| 待办推到个人手机上,点开就是那条待办 | hub_wecom 渠道:交给统一身份 Hub 代发企业微信应用消息(本系统不持有企微密钥,卡片点开回到现成的免登回调) |
「消息通知」页,见 docs/hub-integration.md §15 |
三条外发路共用同一套投递底线:与业务动作同一事务入队 → 提交那一刻把后台投递线程当场叫醒 →
退避重发 → 重试用满进死信 → 停在"发送中"当结果未知、绝不盲发第二遍。叫醒那一步原先只有写回
发件箱有(service/outbox.py),消息渠道与事件订阅只能干等下一个轮询周期——量过:一条企业微信推送
从入队到发出等了 28~60 秒,而真发那一次只用 1 秒,慢的不是发送,是没人叫醒。现在三条路共用
service/wake.py 这一个通路(本进程直接置事件,跨副本发一条 Redis 广播),15/60 秒那一档轮询退回
"叫不醒也要发出去"的兜底;一轮投递另有 20 秒的时间预算,一个慢 SMTP 网关拖不住整队消息,
没发完的下一轮接着发。验收:scripts/check_notify_wake.py。
订阅方挂了不该让审批人办不成单,所以入队这一步永远不把异常抛回业务代码。设计文档:
docs/platform-open-api-design.md、
docs/notification-channels-design.md。
两个容易踩的分寸写在文档里,这里点名:
收件人不做配置项(站内信发给谁、这一路就发给谁,账号没邮箱、没绑企业微信就在投递记录里
落一条 skipped 并说清去哪补,不静默丢);群机器人一批发一条(三个人会签不会往群里甩三条
一模一样的消息),但推到人手机上的 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 §8;
验收 backend/scripts/check_notify_settle.py(内存 sqlite,38 项:真转办、真或签、
真终止之后通知跟着退,另钉住待办还挂着时一条都不许多收)。
装到手机桌面上(PWA)
前端是可安装的 PWA:/manifest.webmanifest + 图标 + 一层只兜底的服务工作者。
规矩是外壳可以缓存、接口一个字节都不缓存——缓存一份待办列表看着像"能离线办公",
实际是让人对着一张早就被退回的单子签字。窄屏(<1024px)换成底部标签栏,
导航项与侧边栏同一套权限码,待办角标共用一份计数;iPhone 上输入框字号钉 16px,
免得获得焦点时页面自己放大。装之前要 HTTPS(内网用自签证书也行,手机得装上根证书)。
边界与真机验收清单见 docs/mobile-pwa-design.md。
浏览器页签上那一枚与左上角那块 "OA" 磁贴是同一张图:矢量 favicon.svg、给不认 SVG
图标那几档内核兜底的 favicon.ico、装到桌面上那几张 PNG,全部由
frontend/scripts/gen-icons.py 一处生成——改主色或改字形跑一次就整套对齐,不用一张一张 P。
「站点信息 → Logo 路径」另填了地址就以它为准(老地址 /logo.svg 也照新样子重写了一遍,
此前存过这一格的环境不改配置就跟着换过来)。
手机上把单子批掉(竖屏版式)
从企微卡片点进来的多半是待办详情,那一页在 <768 的屏上换一套版式:抬头先答完四问
(这一单是什么、谁提的、多少钱、卡在哪一步几号到期),本环节要填的格子提到最前,
四十几格按类型归置——空值不渲染、系统取数折成一行、明细收成「12 条 · 合计」(点一下就在这一行
底下逐条摊开、再点收回,不再推一层全屏弹层,口径见 docs/mobile-form-layout-config.md §2),
底下只吸三颗:同意 / 退回 / ···,办完关掉这一张回待办列表——列表重新挂载就重新取一次,剩下的几条摆在眼前。
弹层一律从屏幕下沿推上来,
每条出口上写着它去哪儿。判据只有宽度,而且只作用于版式:审批逻辑仍是桌面那一份
(TaskDetailView provide 出去,components/oa/mobile/ 只负责摆),后端零改动。
手机上打开系统第一眼就是这一屏:utils/returnPath.ts 的 landingPath() 按设备挑表、再按权限挑那条真进得去的
——手机上 工作台 → 待办 → 我的 → 门户,桌面照旧门户第一。「普通员工」那一档没有 work:workbench,
写死落 /workbench 只会被守卫打回门户新闻页,那看着就像手机版式没做;这类人现在落进待办那张卡片流。
门户在抽屉侧栏里仍点得到。
首页那一屏(/workbench)在手机上换成五张小卡片——待办 / 已办 / 待阅 / 已阅 / 我发起的,
一张对一个列表,数字与点进去那张列表同口径(待办待阅取角标那份计数,已办与我发起的取工作台统计,
已阅取已阅列表的 total);底部标签栏只剩 首页 / 待办 / 我的 三格,「发起流程」搬到首页那五张
卡片底下那颗钮。桌面上那套统计卡 + 快捷发起 + 概览走 v-else,一行没动。
手机上那条顶栏(汉堡 + 站点名 + 通知 + 语言 + 深色 + 头像)整条不挂了,在 390 上它比正文还高:
子页面只留一行 44px 的细栏(components/layout/MobileTopBar.vue:返回 + 页名,底部三格那几页连细栏都不要),
其余几件事各有去处——通知是首页抬头那颗铃铛与「我的」那一行(同一张底部弹层)、语言/深色/字号在
「我的」→ 外观、其余入口在「我的」按权限分组列出、退出也在那儿。左侧那个抽屉在手机上整块不挂(AppSidebar v-if="!phoneShell",它的拉手本来就在顶栏那颗汉堡上;
768~1023 那一档汉堡与抽屉照旧)。「我的」这一格(ProfileView.vue 手机档)
因此是新画的一屏:身份、通知、收款账户、入口几组、外观、添加到主屏幕、退出,末尾钉着构建号;
桌面上那一版一个字没动。详情抬头砍到一行(左边几枚徽章、右端一枚发起人标,单号挪到审批记录末尾),
审批记录换成 components/oa/mobile/MobileFlow.vue 那条竖向时间线(默认只摆最近三步、发起那一行永远留着、
末尾高亮「此刻卡在谁手上」,数据仍出自 utils/approvalRecord),更多操作里去掉「打印审批单」,
提示条贴底居中且不摆关闭叉,登录成功那一句在手机上不发。
详情页不给「打印审批单」也不给「刷新」:打印是回到电脑上的事;刷新那颗图标在屏幕最上沿、
离拇指最远,撤掉之后换成 composables/useMobileRefresh.ts 两条道——往下拉这一把手势
(usePullToRefresh:只到顶继续下拖才接管,顶栏正中浮一枚「继续下拉 / 松开刷新 / 正在刷新…」的胶囊;
待办详情只认主动下拉,免得抹掉正在填的字),加上只读那一屏回到前台自己取一次
(useRefreshOnReturn)。列表页与首页仍留那颗刷新按钮,那是几十条数据的入口,得给个显式口子。
单据详情那一屏(/work/:job:已办、我发起的、待阅、通知弹层、流程监控点进来是同一个落点)原先只有
桌面那一版,从「我发起的」点开自己提的单子看到的还是那一整块说明——按第 13 版设计在走、
流程名 · 单号 · 发起人:×(部门)、发起时间、打印审批单 / 刷新 / 催办 / 终止流程 摊两排——
所以它也分了两档(components/oa/mobile/MobileWorkView.vue,只读):那一整块在手机上一个字都不摆,
抬头就一行(徽章 + 右端发起人标)加关键数字,「表单内容 / 审批记录」两页签,画布换成同一条竖时间线
但不给批注框,吸底那一行只在真办得动时才挂、且只那一颗(提交发起 / 催办),
流程干预(要 monitor:work)、终止流程、看电脑版与字号全收进顶栏那个 ···,
两个要写意见的都在下推层里写;这一页同样标了 meta.chromeless。判据仍由 WorkDetailView 一处算完
递下去,桌面那一版(同一个文件的 <div v-else>)一个字没动。
手机上「完整单据」那一屏不再借桌面的 FormRenderer(它的段头位置按桌面 12 列网格的行号算,
390 上全错配,几段的段头会一起堆到最顶上),换成 components/oa/mobile/MobileFormReader.vue:
一格一行、空着也留一行、分节先认页签名再认分隔条(生产上那张费用报销单就是靠一张「标签页」
分两页的,原先这一层只认分隔条,三十几格全挤进一节「表单内容」),外部系统那一页整节给一张
「打开」卡片。哪几格上这一屏现在能在表单设计器里逐格定:属性面板「默认隐藏」旁边多了
「手机上不展示」(field.mobileHidden,只影响手机版式,电脑 / 打印 / 导出 / 必填照旧,
画布上挂 手机不展示 角标;框选一片还能用多选面板那两颗一次收掉——那张报销单 32 格,逐格点没人受得了)。
新键由后端原样存回,没动后端一行。
手机上「表单内容」那一屏原先只能做减法(逐格藏),摆成什么样定不了——一句原话是「表单内容里
分费用报销基本信息、系统取数、完整单据,我就希望只有费用报销基本信息,但里面展示哪些字段、
怎么排放要有地方配」。表单设计器工具栏因此多了一颗「手机端」(角标写此刻是「自动」还是
「已配置」):勾上「按这份配置展示」,手机上就只认那份清单——几格上屏、从上到下的顺序、
每格的摆法(一行 / 整段 / 置顶大字 / 缩略图 / 只写数量 / 收成一行 / 逐条展开)在那张清单里一次配完,
两颗粒子改一格;清单上那颗「展示 / 不展示」写的还是格子上的 mobileHidden,与属性面板那颗同源。
配置存在 content.layout.mobile,后端一行没动(clean_formats 原样存回 layout 里的东西)。
没勾这一档的表单走的还是上面那套按字段类型的自动归置,一个字没变;勾了之后环节字段权限、
本环节要填的那几格照旧压得住(整单「默认隐藏」这一档改了口径,见下面一段;格子自己那句「显示条件」
在待办那一屏也照样算数——它跟电脑上同一时刻露、同一时刻藏,回看那一屏拿存过的那份值只把
「默认隐藏 + 显示条件」那一组摆回来、其余照旧摊开,见 docs/mobile-form-layout-config.md §4.2),
末尾「完整单据」按配置给不给——不给的话
那条路收进顶栏的 ···,要的是"只有一节",不是"这一单在手机上看不全"。
这一档又收掉两处手机上的废话:节名没配、整屏又只有这一节的时候不摆那一行标题(从前那行写的是
代码补的「表单内容」,可上面那排页签已经写着这三个字,等于同一句话占两行,还搭上「11 项」和一颗
没用的折叠箭头;现在 planForm 给每一节标 generic,摘要与「完整单据」两屏同一个口径,
好几节的时候节名照摆——那时候它是把正文分开的记号)、
部门那一格只念部门名(库里存的是组织路径 紫光汇智\软件开发事业部,从前这一格和选人格子共用
读法,路径被当人员引用问了一遍姓名接口,回来拼成「路径(路径)」摊三行;现在 deptText 取路径末段,
与桌面只读态取的部门下拉 label 是同一个名字)。取舍、口径与验收见
docs/mobile-form-layout-config.md。
这一档上线后又挨了一句原话:「手机端配置的字段显示,感觉还是被默认隐藏遮住了——手机这边完全
按手机端这边的配置来展示,就是我只配置哪些字段显示就展示。」 生产那张单上 PMS项目编号 / PMS项目名称 / VDI项目编号 / 行政项目编号 / 定制项目编码… 全挂着「默认隐藏」(电脑上不占位,
取数照跑),于是面板上每一行都写着「展示」、底下那句统计也算它们上了屏,手机上却一格都不出现。
现在**「默认隐藏」不再压住手机端这一屏**:清单上给它点上「展示」,配置里记一笔
fields[].show: true,手机上就摆;没点过的仍旧不摆——否则开关一开,整张表里藏着的格子会一次性涌出来。
环节那边明着给了只读 / 可编辑 / 必填也算它要露出来(与桌面 effectivePerm 同一句话),
而环节说「隐藏」谁都压不动:那一档问的是这个人此刻能不能看。于是摆不摆的判据收成一整块
(utils/mobileLayout.ts:mobileVisibilityOf),摘要、「完整单据」、设计器那张清单、底下那句
"上屏几格"读的都是它——从前分在四地各写一遍,才会有"面板写着展示、手机上没有那一格"这种对不上号。
「完整单据」那一屏也跟着改:清单点了名的默认隐藏格它照样摆,配过的短名两屏念同一个名字。
面板那头顺手补了好用的:清单顶上那颗筛选(全部 / 已上屏 / 已收起)与搜字段名(三十几格翻不动,
筛着时上移下移停用),每行那颗「展示 / 不展示」挂 tooltip 说清是谁拦的,电脑上默认隐藏的格子
顶着「电脑端默认隐藏」那枚角标——它现在说的是"这里点一下就能翻案",不是"配了也没用"。
再后又挨了一句原话:「手机端展示是否可以将我在表单中配置的分组那个组件也展示出来,这样我
在手机端也可以看出来表单字段是哪个分组,这样手机端看着也比较舒服。」 「分组标题」
(type: 'group')那一格在电脑上有抬头、有色标、有一道线,手机上整块是丢的:自动归置那一版
只认分隔条,配了手机端版式之后更是硬成一节,配表的人在长表单上切好的三四段,到手机上是一整坨,
那些名字等于白起。现在手机上出几节由表单上摆的「分组标题」决定——摆几枚切几段,段名照那一格
写的名字(没写用桌面那句「分组标题」,不摆 key),摘要两版与「完整单据」三屏切的是同样的段。
判据收成一处(utils/mobileLayout.ts:mobileSectionMarkers),并且按格子在表单上的次序认:
在清单里把「目的地」挪到「报销事由」前面,它仍旧属于原来那一段,不会跟着清单漂进别人的段里;
段的先后则由清单里第一次出现这一段的位置决定,那串仍旧大致是手机上从上到下。「按配置摆」那一屏
不认分隔条(它压根不在清单里,一道看不见的线不该切段),另两屏分隔条照旧算标记、谁离得近听谁的。
那一格不进清单——它没有值、没有摆法、没有那颗「展示 / 不展示」,列进去只会多一行空转的设置。
配了版式之后「这一节的名字」只管第一个分组之前那一截,那一截没格子时这一节整个不摆;
整段被闸掉也不留一个只有标题的空段。给了一整节滚到底的退路:面板上那颗「严格只出一节(不分段)」
(layout.mobile.singleSection,表单上一枚分组都没摆时这颗开关不出现)。折叠状态认段身份
(PlanGroup.key)不认段名那几个字,改完段名再改回来不会把摊开的状态漂到别的段上。
后端照旧一行没动(还在 content.layout.mobile 里)。守卫:mobileLayout.spec.ts(那枚标记
怎么认)、useFormPlan.spec.ts(三屏切同样的段、清单里挪格子不换段、singleSection 退回一节)、
MobileFormSummary.spec.ts(两段两行标题、每段自己折自己)、MobileLayoutPanel.spec.ts
(那一格不进清单、有分组才多那颗开关),预览台 form=custom&groups=on[&single=1] 直接眼看。
这一档上线后又挨了一句原话:「手机端的审批表单我希望根据表单配置的展示规则而变化,
而不是一发起就冻结。手机端需要跟随调整而变化。」 单据发起那一刻整份设计冻进
oa_process_snapshot(含那几张表单的内容),这是「改图改表单不影响在途单」的落点,
代价是配表的人改了「哪几格展示、什么顺序、每格怎么摆、显示条件」,手机上那一屏看不着,
得等这张单走完。现在手机端审批那一屏读的是「此刻」那份表单内容:待办详情那一屏的摘要与
「完整单据」、在途单与办结单的单据详情,改完当场见效(办结回看从前只跟在途单,一办结就换脸,
2026-11-16 补平:「办结后手机端展示应该和手机端审批界面一致」);桌面只读渲染、打印、明细导出、必填校验、
环节字段权限、引擎落库认的那些格照旧读冻住的那一张——单据是凭证,「这一屏给这个人看哪几格」
可以跟着配置动,「这张单当时该填什么、他改了哪几格」不能因为别人改了表单当场换掉。
分叉只开在摆法这一寸,口径与验收见 docs/mobile-approval-layout.md §4.5。
后端只多一份报文(runtime._job_response 的 forms_live,键是 form_id -> 此刻的 content):
冻过结的单都算(在途与办结一起),只装真改了的那几张,没人动过就是 {}(报文与这一改动前逐字节一致);
内容走 autofill.form_content 那层进程内快照,没人改表单时一条 SQL 都不排,设计器保存那一刻
那层快照当场作废,所以是「保存即见效」。认的是同一张表——把环节换成另一张表单(id 变了)
不算调整,在途单照旧看自己冻住那一张。办结件回看时字段权限认本人最后办完的那一环
(归档行没有 activity 那一列,这一屏从前压根不递字段权限,审批时被那一环「隐藏」按住的格子
一办结就凭空冒出来);只认本人办过的那一环,没办过单的人照旧"存过的都摊开",不拿别人那一环的
「隐藏」收他的格子。认环节分两把尺:凭证认这张单最后停过的那一环(与谁在看无关,桌面 /
打印 / 导出跟着它认表),摆法认本人办过的那一环——并成一把会让同一张归档单因"谁在打开"换凭证。
守卫:check_design_pin.py 第 3b / 3c / 9 组、e2e_mobile_parity.py(发一张单 → 设计接口改配置
→ 一路办到落定,比对办结前后那两份报文)、MobileTaskView.liveForm.spec.ts、
WorkDetailView.spec.ts、WorkDetailView.mobileParity.spec.ts(含一条把 MobileTaskView 与
MobileWorkView 真挂起来、逐格比两屏「完整单据」的);设计器版本号那颗 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,填写块与必填仍读冻住的那一份。「认哪一环的权限」与「认哪一张表」一样只留一处写法
(utils/mobileLayout.ts:mobilePermsRead()),两页各写一遍迟早又长成两套。生产上执行董事那张单从 11 格变 22 格、部门主管
那张从 9 格变 17 格,财务总监那张字段权限本来没改,只跟着表单内容与显示条件走(25 → 20 格)。
新增守卫:check_design_pin.py 第 3c 组、mobileLayout.spec.ts(含那个空 form 回落与
mobilePermsRead 那三份)、MobileTaskView.liveForm.spec.ts、WorkDetailView.spec.ts、
WorkDetailView.mobileParity.spec.ts(最后一份里有一条把审批屏与回看屏逐格对照)各补了相应的回归。
手机上的审批记录不再折叠(原话:「审批记录不要收折,直接往下面展示,收折了让人误以为缺少环节」)。
从前那条时间线只摆最近三步,其余收进一颗「展开更早 N 条」,批了七八环的单子打开只看得见两环加一颗钮,
人以为这张单少走了几环——省下的那两三屏不值这个误会,那颗钮连同 RECENT 一起删了,整条从头摊到底
(发起那一行照旧在最前,长意见还是先给两行加一颗「展开」,改单与附件照旧折成一行)。
待办列表那头又挨了一句**「手机端也需要有批量处理的功能」。桌面那一套(表头复选框 + 工具栏那颗按钮)
在 390 上摆不开,手机上把它做成一档**:顶栏一颗「批量处理」按下去整张列表进选择档,卡片左边那颗勾
替掉右边的「去批」和箭头,点卡片是勾上 / 取消而不是进详情(一次批三条不该点六下);操作位在屏幕下沿
那一横条——全选 / 清空 + 已选 N 条 + 「批量处理 N」,全在拇指底下;那一层照手机上「动作一律从下沿
推上来」那条规矩走 MobileSheet,出口不做下拉(浮在 bottom sheet 里会被截掉半截)而做一排按钮,意见底下摊引擎逐条回的
失败原因,改完可以只重试那几条。判据与桌面共用一条:能勾的是 !oa_locked(这一环的表态已交给外部系统),
全选不硬塞它,手动勾上照样交——那句失败原因写清了去哪儿办,比界面挡着不吭声好;退档把勾收掉,
一批全办完自动退出选择档。提交时按攒下的那一沓(useMobileFeed 的 feed)找单子,不按当前页找,
不然往下滑过三页勾 25 条会莫名少一截。桌面那一版一个字没动,两条分支共用 openBatch / confirmBatch
与那份「可用出口 = 每条被选待办路由名的交集」。
后来待阅也做了批量,那一横条上就成了两颗动作钮:MobileCardList 多一个 secondaryLabel
与一路 batch-read 事件,待办上是「标记已读」+「批量处理」,待阅上是「批量已阅」+「批量处理」,
两页各填各的文案、共用同一条下沿。少了这第二颗,手机上「先看一眼」还是得点十几下——
桌面加了钮而手机没加,等于把最需要省力的那一档漏掉。「已选几条」也交给外面传(selectionCount):
整片选中那一档下没有行级勾可数,只数屏幕上勾着的几条会少报。
另一处顺手修的:没配核验闸门的单子不再摆「外部核验」那块面板(后端一直发着 configured,
是前端没认;真送过一次审的单子仍然照摆)。
预览台 frontend/preview-mobile.html(dev only,screen=home|list|detail|work|profile,
form=tabs 换成生产上那张分页 + 外部页面的报销单,form=custom 换成配了手机端版式那一档作对照
(再叠 groups=on 看「分组标题」切成几段、&single=1 看「严格只出一节」),screen=panel 单摆设计器那个「手机端」面板,open=reader 直接把「完整单据」点开),
screen=list 加 select=on|sheet 直接停在批量选择档 / 再把批量那一层推上来,
设计稿 design/mobile-approval.html,取舍与验收见 docs/mobile-approval-layout.md。
发版有没有生效不用猜:首屏问候语下面那串 12 位数字就是构建号,构建时 --build-arg OA_APP_BUILD=$TAG
把镜像 tag 烤进产物,手机上那一串跟 kubectl get deploy 里的 tag 对上,就说明这台手机跑的就是这一版。
更多操作里点过「看电脑版」的,底部标签栏头顶会多一颗「看手机版」把它退回来。
一次开几张单子(页签、列表条件与切回来的那一屏)
批一沓单子的人是来回切的:从待办点开一张、再点下一张,回来的路上还要记得上一张看到哪儿。
原先路由出口就一个 <RouterView />,一屏顶一屏——点开 B 单再退回来,A 单不剩什么,
连列表上刚筛好的那一格都重画成默认值。这一档做三件事:打开过的页面留一格、
列表那一屏留活、筛出来的条件留得住。
页签的身份是路径,不是完整地址(stores/tabs.ts)。这一句定了所有细节:
/read?tab=done 与 /read 是同一张页签——待阅列表换档只是把档位写回地址,
不该在页签条上多出第二张;而 /work/A 与 /work/B 路径就不同,两张单子各占一格,
这才是要的「像开多个页签」。点页签回到离开时那个地址(fullPath),
写进 URL 的状态原样还原,没写进 URL 的由还活着的那份组件带着。页签不设上限、不自动关
(原先是 12 张一封顶、超了裁掉最早那张不是当前页的,开第 13 张单子就把人回得去的那一格悄悄
吃掉了——关页签是人的决定,不该账本替人做主;页签条本来就横向滚动,摆不下是滚不滚的问题);
工作台钉住不给关,页签条上总得留一格
让人回得去;清单存 sessionStorage(unisoa_work_tabs_v1)——换一趟浏览器该从干净开始。
标题两种来源:页面自带的路由 meta.titleKey(跟着中英切换翻),单据类页面等后端把标题带回来
由 composables/useTabTitle.ts 回填,回填过的优先——页签上写「差旅报销 · 张三」比写
「单据详情 ×3」有用。为什么不直接读 document.title:那是整个浏览器标签页一句话,
切到哪张变成哪张,而页签条要并排摆十几张,每张都得记着自己那句。
components/layout/TabBar.vue 只管摆和点:只剩一张页签时整条不摆(那一格就是当前页本身,
摆出来只是一条没有信息的横条),手机上也不摆(底下已经有底部标签栏,390 上再叠一条横向滚动的
条子会把正文挤没,手机上「返回列表」本来就是拇指最熟的那条路)。摆不摆只留一把尺子:判据
只在 AppLayout 那一处 tabBarShown,组件自己那句 v-if 去掉了——两处各判一次「摆不摆」,
迟早有一处忘了跟上另一处。右键与右端那颗「更多」叫出的
是同一份菜单(关闭 / 刷新这一页 / 关闭其它 / 关闭全部),而关掉只认中键——别写成「派发
auxclick 就关」:右键那一跳同样会派发 auxclick(实测 button=2 一样发),照那句写就成了
一边弹菜单一边把那一格删掉,菜单是为一张已经不存在的页签打开的,所以那一手只认
event.button === 1(用例钉在 AppLayout.tabs.spec.ts)。当前页签常常滚在可视范围外,
切过去顺手把它滚进来,不然看着像「点了没反应」。高度也只留一处常量:stores/tabs.ts 的
TAB_BAR_HEIGHT——TabBar 摆自己那一格读它,AppLayout 算 CSS 变量 --app-tabbar-h 也读它
(从前 2.5rem 与 h-10 两处各写一遍,改一处漏一处,表格页就差出那一截)。AppLayout 把这一段
传下去(摆页签条时取它,没摆就是 0),凡是照
「一屏刚好装下」算高度的地方都读它:TablePageLayout 那一句
calc(100vh - 4rem - 4rem)、断网提示条吸顶的位置,还有设计器与字典那三页
(FormDesignerView / ProcessDesignerView / DictListView,它们原先各写一句
calc(100vh-8rem),页签条一出现就多出一段 40px 的整页滚动条),以及发起页那条钉在页头下面的
工作条(StartFormView,吸顶位置原先写死 top-16=一个顶栏高,页签条一出现就把这条压住)。
页签条在不在,各处自己猜一次是早晚要漂的口径;这一条口径由
components/layout/tabBarOffset.guard.spec.ts 当闸门扫一遍源码:凡是贴顶栏吸顶、或按
calc(100vh 算死高度而没读 --app-tabbar-h 的文件,当场报出来——漏一处不是报错,是那一屏
差出 40px,得靠人眼在真机上发现。
落到登录页清空(tabs.reset()):页签上还写着上一张单据的标题,留着会让下一个人以为它没办完;
同一处接着调 clearAllPersistedTableStates() 把 sessionStorage 里那些列表条件一起清掉——
页签清了、筛选没清,下一个人进门看见的还是上一个人筛的「已驳回 + 第 7 页」。
列表那一屏过一道缓存(AppLayout.vue 的 KeepAlive)。要不要留活只写在路由上:
meta.cache: true 标的是列表页与工作台(待办 / 已办 / 我发起的 / 待阅 / 草稿 / 代理 / 交接 /
资讯 / 会议 / 日程 / 网盘),判据与「为什么单据详情不标」一起记在 router/meta.d.ts 里:
详情页读的是当前地址上的 :job / :id,藏着的那一份会跟着别人的地址把自己的数据改掉——
人在 A 单,切去看 B 单,回来 A 单就成了 B 单。所以详情页照样占一格、照样点得回去,
只是每回点都重新拉一遍。「刷新这一页」不要求每个页面自己实现一套,靠的都是换 key 重新挂:
进缓存那一档钥匙是「路径 + 刷新序号」(tabs.instanceKey),不换路径也能被要求重来一次;
不进缓存那一档钥匙上只带刷新序号、不带路径(tabs.nonce)——待办详情、单据详情、设计器
本来就是照「同一个实例换一张单」写的,里面 watch 着 :job / :id 自己重拉,把路径写进
key 等于每换一张单整页重挂,那些 watch 全成了死代码,浏览器前进后退与「批完开下一张」
也跟着变味。
留活之后有两件事跟着变味,都在这儿记一笔,别等下一次改页签再踩:
- 只在 setup 里读一次地址的页面,读不到后来那次导航。
KeepAlive切回来不重新挂载, setup 只跑一次:待阅那一档原先就在 setup 里读一次?tab=done,于是手机首页那张「已阅」 卡片(MobileHome带?tab=done过来)点进去会停在待阅档。补的是ReadListView里一道watch,判据先认「地址还落在自己这一格」(比对route.path与自己挂载时那条路径)—— 不先认这一句,人在别的单据页(那边 query 里没有tab)会把藏着的那一屏莫名改回待阅。 标了cache的页面里只有这一处靠 query 定初始态,别处再这么写要自己补这一道。 - 悄悄重拉不许把骨架顶上,也不许留下没人关的骨架。切回这一格按当前条件重拉一次是
useTableLoader里onActivated那一发(load({silent:true}),不碰loading,否则 表体整段换成骨架、刚恢复好的滚动位置又被压回顶上)。但它与别的发共用同一个AbortController:静默这一发会 abort 掉在途的普通请求并接管控制器,那一发的收尾 认不出自己——若收尾那句再叠一个&& !silent,两下都不关loading,骨架就一直挂着 (切个页签再点一下分页就能撞上)。收尾只认「这一发还是当前那一发」, 用例钉在useTableLoader.persist.spec.ts。
关掉一张页签,它那份缓存要作废(tabs.remove 里给那一格刷一个序号):只把它从清单上抹掉
等于没删——布局层认的是「路径 + 序号」这把钥匙,KeepAlive 里还留着上一趟那个实例,重新点开
就复用了它,那套筛选也跟着回来,与「关掉这一页」这句话正好相反;刷一次序号,下次点开才是
干净的新一屏。「关闭其它 / 关闭全部」走的是同一条删除口径,一起作废。
切走时把滚动位置记进 store(窗口那一格与表体里 .table-scroll-container .table-wrapper
那一格都记,桌面表格是在表体里滚的,只记窗口等于回到列表还是从第一行看起),回来等一帧画完
滚一次、隔 240ms 再补一次。
留活那一档的 max 写的是 CACHE_MAX = 32。页签不封顶之后,这一格不能再照页签数算,
它真正要养活的只有路由上标了 cache: true 的那十几张列表页,多出来的额度是留给「换钥匙」的:
关掉一张或刷新一张都会换一次钥匙,而旧钥匙那一份还躺在缓存里等 LRU 挤出去。写得太小,
多关多刷几回就会把还开着的页签的留活挤掉——页签条上看着一切正常,切回去筛选与滚动全重头,
而这种事只在用过一阵之后才露头,最难被当场发现;真给成无限大,刷新一百次就是攒一百份活组件。
这一层的账本本身另有 stores/tabs.spec.ts(7 条)
钉着:同一张单子反复点开只占一格、换档改写地址不另开一格、开四十张也不自动关、工作台钉住不给关、
关掉之后钥匙换号(再点开是干净的一屏)、刷新只换序号(路径不进那一档的钥匙)、账本跟着这一趟
会话走,中途换人 reset 清干净。
切回列表悄悄重拉一次(useTableLoader 的 onActivated):躺在缓存里的这段时间,
单子早被别人办掉了,切回来若还是走时那份数,人就会对着一条已经办完的待办再点一次「同意」。
按当前条件与当前页重拉,不跳回第一页、不闪加载态;只管宽屏——手机上列表是一条越拉越长的流水
(useMobileFeed),重新拉一遍会把人划了两屏的位置收回顶上,而那边本来就有下拉刷新这条正路。
这一发长在 useTableLoader 里,走它的列表页(待办 / 已办 / 我发起的 / 待阅 / 资讯 / 网盘)
白拿;自己写 load() 的那六页(草稿、代理、交接、会议、日程、工作台)没有分页与页码,
套不上那个加载器,于是各接一发 composables/useRefreshOnActivate.ts(第一次进这一屏仍由
onMounted 自己拉;与加载器那一份唯一的差别是不挑宽窄屏——这六页既不接 useMobileFeed
那条流水、也没有下拉刷新,照搬「只管宽屏」那条判据,手机上这一屏就永远停在走时那份数)。重拉认的是"当前这一屏"而不是默认那一屏:
会议按当前那一档(scope)、日程按当前看的那一月与那一天,切回来不该把人弹回「当月今天」。
load() 因此都多了一个 silent:这几页用 DataTable,loading 一真就把真实的行整段换成
骨架,刚恢复好的滚动位置又被压回顶上——重拉是悄悄重拉,不是再来一次加载态。
新加一屏标 cache 却忘了接重拉不会报错,只会让人对着已办完的单再点一次「同意」,
所以这一条由 router/cachedRoutes.spec.ts 扫路由表钉住:每一个 cache: true 的组件文件里
必须有那一发(走加载器或显式 useRefreshOnActivate,两条道任认一条)。
筛选条件存在这一趟会话里(composables/usePersistedTableState.ts)。钥匙是路由路径:
「哪一屏」路由上已经写得清清楚楚,不该再让每个列表页自己报一个名字。这一句带一个限定:
useOAList 只在这一屏标了 meta.cache 时才默认拿它当钥匙——留不留条件与留不留活本来就是
同一件事,判据因此与 AppLayout 那道 KeepAlive 共用一句,不留两把尺子。消息渠道、操作日志、
组织人员那三个管理页没标 cache,本来每进一次都是新的一屏,跟着带上次的条件是无端端变味。
流程监控是这一句的一个例外,而且是显式声明的例外:它也不留活(监控摆着上一趟那份数比
重新拉一次更误事),但管理员的用法就是筛一轮「超时 + 某个流程 + 一段时间」再挨个点进去查,
每从单据详情退回来都从头筛一遍是白费劲,于是它自己传一把 persistKey——留条件、不留 DOM。
要单独给某一页换钥匙就显式传 persistKey,要它从空白开始就传空串;挂在组件外的少数用法
拿不到路由,也没有钥匙,退回原来的行为。这一屏的档位另算:「全部流程 / 全部待办」两档
共用同一套条件,所以档位写进地址(?tab=task,与待阅的 ?tab=done 同一句),只留条件而
把人放回默认那一档,等于把待办那档筛出来的东西端给流程那档看。用 sessionStorage 而不是 localStorage:
前者关标签页就没了,正好是「这趟看到的」的语义;后者会把三个月前某次筛的「已驳回 + 第 7 页」
一直端给今天早上打开电脑的人。三条判据值得写下来:
- 每次发请求记一笔(
load()里),不在十几处回调里各写一次——条件与页码改哪条都会过这里; 窄屏那一趟只把条件写进去、页码按第 1 页记:手机上翻到的那一页是流水里的一段, 同一把钥匙回到桌面上不该把它带过去; - 只按
initialParams的形状取键(pickPersistedParams):设计改了、某个筛选条件撤掉之后, 库里那条老键不该又自己长回请求里; - 宽屏连页码一起还原,窄屏只还原条件(
useViewport.ts:isNarrowViewport(),与lg同一条线): 宽屏一页一格才谈得上回到第 7 页,手机上第 7 页是流水里的一段,还原过去只会让第一屏 只有那二十行、还告诉人「到底了」。
还原出来的那一页可能已经不在了:这一趟没人在,别人办掉一半,第 7 页只剩 3 页。load()
按报文里的 pages 校一道,越界就落到最后一页、把这一笔跟着写回存储,再补一发——
这一发收在同一趟请求的生命周期里(一个最多两轮的循环),不另起一次 load():另起会换上
自己的 AbortController,头一发收尾时认不出自己那一发,骨架就一直挂着不撤。不校就是
一屏空表配一句「第 7 页」,得人手点一下才醒。
「悄悄」那一趟走的是 load({ silent: true }):它不碰 loading,收尾也不撤。一碰,DataTable
就把真实那几十行整段换成骨架(两者是 v-if / v-else 互斥的),表体当场塌成五行,布局层刚
恢复好的那一格滚动位置又被压回顶上——「切回来还在原来那一屏」与「切回来是现在的数」
这两条主线就此互相打掉。
还有一处不写出来一定踩:几乎所有列表页都在 onMounted 里调 reload(),照字面意思
「回到第一页」会把刚还原的页码当场洗掉,用户看到的是「条件留住了,页没了」。所以还原出来的
那一页记在 restoredPage 里,挂载后那一趟补拉认它,之后改条件才算真的要回第一页。
守卫:components/layout/AppLayout.tabs.spec.ts(9 条)盯两张单子各占一格且页签上写的是
单据标题、点页签回到那一张而不是另一张的地址、关掉当前这格落回隔壁、列表页留活而单据详情
每回都重新拉、关掉一张列表页签再点开来是干净的一屏而不是上一趟那份筛选、两张单据换着看是
同一个实例换数据(不整页重挂,否则详情页那些 watch 白写)、右键叫菜单那一下不该顺手把
格子关掉(右键也派发 auxclick)、只剩一张时不摆这一条;
composables/useTableLoader.persist.spec.ts(6 条)盯第二次进来带着上一次的条件与页码发请求、
挂载后那句 reload 不许把还原的页码打回第一页、窄屏只还原条件、每发一次请求记一次且
形状之外的老键不会自己长回来、还原出来的那一页已经不在了就收回到最后一页、没给钥匙的列表
照旧从空白条件开始(详情页那种「每次都要看最新的」);views/oa/MonitorView.persist.spec.ts
(6 条)盯不留活那一档的例外口径:条件与页码带得回来、重新挂载不用再筛一遍、点了「重置」
之后不许从存储里长回来、?tab=task 带着档位回来并打对接口、同一个实例上地址回到 /monitor
档位要跟着退回默认那一档(不缓存那一档换 query 不重挂,setup 里那一次读取不够)、不带 tab
的地址照旧落在「全部流程」。
多副本部署(--workers N / 两台机器)
后台任务不再默认"只有一个进程在做":谁拿到库里的租约谁跑(oa_worker_lease,
时钟取 SELECT NOW()、TTL 至少三轮、退出时主动交还),建表与初始化数据用 MySQL 命名锁串行
(那张租约表自己还没建出来之前不能用租约),投递在租约之外再叠一层行级认领。
OA_SCHEDULER=off 是给"这个副本只接接口"留的口子,不是用来防止重复执行的。
要一致的是引导配置、jwt_secret(不一致的表现是"隔几次就掉登录")和库;不需要粘滞会话。
附件必须放 MinIO/S3 并关掉 fallback_to_local,否则 A 副本收的文件 B 副本读不到。
还留着的单进程假设(进程内取数缓存、配置 60 秒缓存等)逐条列在
docs/multi-worker-deployment.md §6,没装死。
流程标题怎么生成
流程标题不必是死的一句「某某的XX流程」。配置入口只有一处——
表单设计 → 工具栏「标题规则」——照着公司行文习惯改,比如
{日期:YYYY-MM-DD} {部门}-{发起人} {流程名称}。口径只有一份(service/titles.py),
设计器预览、发起页预填、引擎发起、后续环节重算走的是同一段代码。
- 默认(
mode: default):不配规则时照旧——表单里叫title/subject/name的字段先用,没有就「某某的XX流程」,老流程行为不变。 - 模板(
mode: template):{变量}拼标题。右侧变量按「表单字段 / 流程 / 发起人 / 日期时间」分组(这张表单里用的字段排在最前面、默认摊开),按钮上写的是人在表单里 看到的中文名、旁边带真实字段名,点一下把变量插到光标处,不必手打,也不必记住英文名。 搜索框按中文名也能筛。{日期:YYYY年MM月DD日}换日期格式,认YYYY MM DD HH mm ss;{申请事由|30}只取前 30 个字,长事由不至于顶爆列表那一行;{申请事由|未填写事由}竖线后写文字是空值兜底,字段空着标题也不留窟窿; 竖线两段可以同写,顺序随意;{{}}双写输出字面大括号;- 明细表取首行那一格:
{费用明细.事项}; - 英文字段名与中文标签等价,
{reason}与{申请事由}算同一个变量。 系统变量:流程名称 / 流程别名 / 流程分类 / 单号 / 当前环节 / 发起人 / 工号 / 部门 / 部门全称 / 部门负责人 / 直属上级 / 日期 / 时间 / 日期时间 / 年 / 月 / 日 / 星期。 表单字段这一组来自画布上那份还没保存的字段清单:刚拖进来的字段当场就能点成变量; 排版类(分隔线 / 说明)、附件 / 图片 / 签名和标题字段自己不进变量表(标题引用自己是自己套自己)。 「单据编号」这类自动字段既能被标题引用,自己也能带生成规则,见「自动值怎么生成」。
- 表达式(
mode: expression):复用环节条件那套受限表达式(engine/expressions.py), 按金额分段、按部门换前缀这类逻辑才需要它,上下文是data/work/user。
两个开关加一条手改保护管住标题归谁说了算:
editable关掉后发起页的标题框只读,规则算成什么样就是什么样;refresh打开后,后面环节改了表单字段会按同一规则重算,在途的待办与待阅一起改名 (待办列表、待阅列表、站内信读的都是各行自己那一份title,不回查单据);- 发起人亲手改过的那句记在
work.variables.titleManual,开了自动重算也不盖他写的。
标题也可以是表单里的一个字段。 想让用户在单据表单里看得见、改得动标题,就去
表单设计 拖一个 流程标题 字段(type: title,一张表单只能有一个,多余的保存时被挡)。
这一格的值就是 work.title,标题从此只有一处出处:
- 发起时规则算出来的一切都写回这一格,发起页顶部那只独立的标题输入框自动让位, 不会再出现两处标题打架;
- 字段上的「这一格的标题怎么来」两选一:
rule按标题规则生成(受规则里editable管)、manual由发起人自己填(比流程级开关更具体,规则只在这一格空着时补一句); - 发起页里这一格随表单实时重算:没人动过它时,改了别的字段它就跟着规则换一句; 亲手改过之后不再被规则盖掉;
- 后续环节里改这一格等于改标题:引擎采纳他写的这句、同步在途的待办与待阅,并从这一刻起
不再自动重算(等同
titleManual);谁能改由该环节的「表单字段权限」决定; - 管理员在流程监控的「修正表单」里改这一格同样算改标题:走的是与办单同一句
titles.refresh(engine._refresh_title),单据、在途待办、待阅三处一起改名——已办 / 已阅不动, 那是那个人当时批过的快照;判据scripts/check_intervention_title.py; - 存草稿取同一句:这一格写着什么,拟稿箱里就叫什么,发起前后不会换名字。
规则界面上只有一处可配。 就在表单那一格上(field.titleRule):
表单设计 → 工具栏「标题规则」,或者直接选中画布里那格「流程标题」。
流程设计器里不再提供标题配置——标题是表单那一格的事,流程侧只负责把规则交给引擎。
oa_process.title_config 这个字段仍然留着(形状与 field.titleRule 完全一致,
接口和老数据还认它),但界面上没有入口,也不再由流程设计器读写。
为了不必先知道"标题规则藏在哪",表单设计器把它摆在明面上:
- 表单设计器工具栏常驻一只「标题规则」按钮,徽章写着当前口径(默认 / 模板 / 表达式); 点它 = 选中画布里那格「流程标题」并把规则面板摊开,表单里还没有那一格时先替你加上;
- 画布那一格把口径写在格子上:
模板角标 +· {部门}-{发起人}-{流程名称},不点进去也看得出; - 字段库里的「流程标题」独占一行并带「规则」标记,加字段时就知道它带着规则;
- 规则面板是一块默认展开的高亮卡片,标题行写着生成方式与模板原文,收起来也不丢口径;
- 流程上真带着一条历史遗留的规则(接口或旧版本写的)时,面板会当场用琥珀色提醒它盖住了 这一格,不再把人指向一个已经不存在的入口。
生效顺序是:
- 流程上带着旧规则(
oa_process.title_config.mode != default)→ 仍用流程那条;这种数据 只能来自接口或旧版本,界面上已无处可配,新配的规则不会走到这一步; - 流程没配 → 用字段自带的那条,配在表单上的好处是规则跟着表单走, 同一张表单挂到别的流程上不用重配;
- 两条都没有 → 老口径(表单里的
title/subject/name,否则「某某的XX流程」), 没写过titleRule的老表单与老流程行为一字不差。
设计器手上那份还没保存的草稿永远优先,改哪儿预览哪儿。两处设计器都看得见是谁在生效:
流程设计器在流程那条是「默认」而表单带了一条时,标签页里会写明「此刻沿用的是表单里『XX』的那条」;
表单设计器在流程另配了一条时,会提示这里配的会被盖掉。预览结果里的 source
(draft / process / field / default)说的就是这件事。
标题永远得有一句:模板大括号没配对、变量名不存在、表达式跑挂,都退回默认口径并把原因
留在预览的 error 里,不会为了一句标题把整张单卡住;但保存时先挡一道
(TITLE_RULE_INVALID),设计器改坏模板当场红框,不用等发起人发起才发现。
maxLength(默认 120,上限 300)负责压掉换行与截断,emptyText 是「算出来是空」时
的最后兜底。变量清单与实时预览走两个接口:GET /process/processes/{id}/title/variables
(变量 + 表单样例值)、POST /job/title/preview(设计器 use_sample: true 用样例补空,
发起页按当前填的内容算)。规则配在表单上时还有表单作用域的同款两个接口:
POST /process/form-title/variables、POST /process/form-title/preview,请求体是
{form, name, fields}——form 是已保存表单的 id(新建还没保存留空),fields 是设计器画布上
那份还没保存的字段清单,于是新建的表单、刚拖进来还没保存的字段也都当场能点变量、能预览;
{流程名称} 依次借所属流程的名字、画布上这个表单名、库里那张表单的名字顶上。
两个设计器都只读这几个接口,不自己拼变量表。
标题是随表单实时走的,不是发起那一刻算完就定死。 四个地方都在改完那一下当场换一句
(发起页与设计器那份在 composables/useAutoTitle.ts,一份实现共用;口径仍是 service/titles.py):
- 发起页:表单里那一格随填随改,公式、带出、级联算完的值都算得进来;
- 表单设计器的「预览」页:填两个字段就能看到规则跟着动,配完不必先保存再发起一张测试单。 这一份用的是画布上还没保存的规则与字段清单,改哪儿预览哪儿;
- 办理页:后面那一环改了表单字段、而规则又开了「自动重算」时,标题框下面写一句 「提交后会更新为 …」——只说,不写回。提交之前那一句还是上一个环节的,改了字段就当场改口 会让人以为已经改了。
- 监控页的干预面板「修正表单」:管理员改完那几格,表单下方写一句「保存后标题会变成 …」,
说的就是
fix_data落库那一刻会做的那一步——同样只说,不提前写回。
这几处守的是同三条分寸:只覆盖系统自己写的那一句(字段里是人亲手写的就原样留着,
规则收了修改权限时反过来——那一格归规则说了算);没人动过的标题格在问后端之前先从数据里
摘掉(否则规则再怎么改,后端念回来的都是上一轮那句老的,标题从此不再跟着表单走);
防抖 + 迟到不回写(一路打字只问一次,回来的答案只配给当下这份数据)。
办理页与干预面板那一句走 POST /job/{job}/title/preview:按这一单此刻的数据 + 将要提交的那份
改动算,只读不写库。问得动的人:发起人、手里有待办的人,以及监控页数据范围里看得见这张单的人
(有 monitor:work 时按 /admin/work/{job}/data 同一道数据范围筛判)。
接口一览
前缀 /api/v1,除 POST /auth/login、POST /auth/refresh、GET /settings/public 外都需要
Authorization: Bearer <token>。完整清单见 docs/architecture.md。
| 分组 | 代表接口 |
|---|---|
| 认证 | GET /auth/captcha POST /auth/login POST /auth/sso/state POST /auth/sso/login(门户免登)POST /auth/refresh GET /auth/me PUT /auth/me PUT /auth/me/bank-account(个人资料里的开户行与收款账号)POST /auth/permissions/refresh |
| 组织 | 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 POST /work/relation-values(关联带出预览:按挂着的那几张单回每条 pick 取到的值)GET /task/processing(每行带 deletable:本人创建、还停在开始环节、没压在别人手上;`viewed=0 |
| 导出 | 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(POST /read/{id}/view 单条标记已读 · POST /read/{id}/handle 需处理那条点「处理」才办得掉,随附那句意见可留空,办完归已办 · POST /read/view 点开整件单据顺手登记 · POST /read/view/batch 批量登记:逐条成事、上限 50 条,ids 与 scope(按待阅列表那一份筛选取整片)二选一,超限与早已登记各单列 truncated / already) · POST /work/{work_id}/forward 已办结的单子由发起人转发给别人:只认归档件、只认发起人与管理员,转出去落待阅) · GET /read/completed(只回不需处理那几条,即已阅;需处理的在 /task/completed,action 参数已摘)/worklog /statistics/* /settings /system/storage /system/storage/test /system/storage/reload /operation-logs |
| 门户 | GET /portal/home;/cms/channels /cms/documents(含封面上传);/meetings /meetings/coming /meetings/invited /meetings/{id}/answer;/schedules /schedules/month /schedules/day;/files /files/{id}/download |
| 网盘 | GET|POST /files;PUT|DELETE /files/{id};GET /files/{id}/download(scope=mine|shared|mine_only,固定落本地磁盘) |
前端
沿用 sub2api 的设计体系与通用组件,OA 业务页面为新增:
-
复用层:
components/common/*(DataTable、TablePageLayout、BaseDialog、ConfirmDialog、Pagination、Select、StatCard、DateRangePicker、SearchInput)、style.css中的.btn/.input/.card/.badge/.tabs/.switch/.page-header/.stat-*、 主色可换的 Tailwind 主题(默认 teal 青,色板是style.css里那几组--primary-*, 换档只换<html data-accent>,见「主题色」那一节)、暗色模式、useTableLoader分页与请求取消、Pinia store 骨架 -
OA 新增:
components/oa/FormRenderer.vue(按表单定义渲染 12 种字段,design模式 额外画出卡片化的字段、空位斜纹与「第 N 行 · 第 i/2 列」角标,审批页用的就是同一个组件)、utils/formLayout.ts(字段落位算法:行/列/占几格、被挤到下一行留出的空位、字段名去重、设计校验)、components/oa/ApprovalRecord.vue(审批记录:发起 + 审批步骤 + 批注 + 引擎事件并成一条时间线, 排序与判定在utils/approvalRecord.ts;开头那行「谁提交的」由startOfWork(detail)从单据详情 与create那条流转日志凑出来,不占审批序号)、components/oa/PeoplePicker.vue(组织选人)、components/oa/SignaturePad.vue(手写签名)、components/oa/OptionPicker.vue(选择类字段与关联审批单共用的候选挑选器:下拉 / 弹出框 / 平铺 × 手填 / 字典 / 单据 / 外部数据源)、components/common/ExportButton.vue(列表导出)、views/oa/PrintWorkView.vue(审批单打印视图/print/work/:job)、utils/oa.ts(状态词表)、composables/useOAList.ts(列表加载 + 错误提示) -
流程设计器:
components/oa/design/NodeConfigDialog.vue(环节配置弹窗:左侧分组 tab + 右侧控件面板)、utils/nodeConfig.ts(分组清单与摘要文案,纯函数)、components/oa/design/NodeInspector.vue(同一份控件支持rail摘要 /panel展开两种形态) -
平台化与移动端:
views/oa/design/DataSourceView.vue(外部数据源)、views/oa/design/QuotaListView.vue(额度定义)、views/oa/design/IntegrationView.vue(反写模板)、views/oa/design/OpenPlatformView.vue(应用 / 事件订阅 / 接口文档 / 事件留痕 / 调用留痕五个页签)、views/oa/NotifyChannelView.vue(消息渠道与投递记录),表单检查器里的三块面板components/oa/design/{FetchPanel,ThresholdPanel,WritebackPanel}.vue; PWA 与窄屏:public/manifest.webmanifest+public/icons/(scripts/gen-icons.py生成)、sw.template.js(构建时发成dist/sw.js并盖版本戳,见vite.config.ts的serviceWorkerPlugin)、composables/usePwa.ts(接住安装事件、点刷新才接管)、composables/useMobileNav.ts(与 Tailwindlg同一条断点、底部要让出的高度)、components/layout/MobileTabBar.vue; 竖屏审批版式:composables/useMobileShell.ts(手机版式总闸<768、chromeless判据、 字号三档与「看电脑版」)、composables/useMobileRefresh.ts(详情页没有刷新按钮之后怎么取新数据: 下拉手势的接管条件与回到前台补一次)、components/oa/mobile/(MobileTaskView只排版式,taskContext.ts是它与TaskDetailView之间唯一的接口,useFormPlan.ts管表单怎么归置 (摘要planForm与「完整单据」readerSections两份共用同一套页签 / 分隔条分节判据),MobileFormReader.vue是「完整单据」那一屏的手机原生读法(一格一行、空值也留、外部页面那节给一张卡片),MobileWorkView.vue是手机上那张只读单据详情(/work/:job),MobileFlow.vue是手机上那条竖向流转时间线、MobileHome.vue是首页那五张卡片,MobileNotificationSheet.vue是读通知那张弹层,未读数与桌面顶栏共用stores/app.ts里那一份)、components/layout/MobileTopBar.vue(手机上替代整条顶栏的那一行 44px:返回 + 页名); 桌面外壳(页签与列表状态):stores/tabs.ts(页签身份 = 路径、不封顶不自动关、工作台钉住不给关、sessionStorage存这一趟、「刷新这一页」= 换组件 key)、components/layout/TabBar.vue(顶栏底下那一横条:点 / 中键关 / 右键与「更多」那份菜单;只剩一张不摆,手机上也不摆)、composables/useTabTitle.ts(详情页把单据标题回填到那一格,中英切换只翻页面自带的那句)、components/layout/AppLayout.vue里那道按路由meta.cache决定留不留活的KeepAlive(判据与「单据详情为什么不标」记在router/meta.d.ts)、composables/usePersistedTableState.ts(筛选条件与页码按路由路径存sessionStorage, 每次发请求记一笔、只按initialParams的形状取键)、useTableLoader的persistKey与回到这一屏时的静默重拉(onActivated,只管宽屏)、useOAList默认拿route.path当钥匙、useViewport.ts:isNarrowViewport()(列表加载器不在组件 setup 里,拿不到那一对 ref) -
权限层:
constants/permissions.ts(权限码分组与中文名)、stores/auth.ts的can/canAny/dataScope/roleNames、api/authrole.ts、views/oa/org/AuthRoleListView.vue(权限矩阵 + 成员勾选);AppSidebar.vue按权限过滤菜单,路由守卫按meta.permission放行 -
门户新增:
components/portal/PanelShell.vue(面板外壳:标题 + tab + 更多 + 翻页)、TaskPanelNewsPanelMeetingPanelSchedulePanelFilePanel,utils/sanitize.ts的sanitizeHtml(文章正文白名单过滤) -
存储:
SettingsView.vue的「文件存放位置」卡片(三类文件各自的当前后端、探活结果、 测试连接、重读配置),api/support.ts的storageStatus/storageTest/storageReload -
页面:首页、工作台、发起流程、我的待办/已办/发起/待阅/草稿、流程详情、任务处理、流程代理、 待办交接、个人资料、流程监控、统计分析、系统设置、大模型接入、同步定时任务、操作日志、流程设计器(可视化画布)、 表单设计、流程分类、组织架构、人员管理、岗位角色、权限角色;门户侧另有信息资讯列表/详情/发布、 我的会议、我的日程、网盘
-
统一身份:
api/hub.ts(状态含sso/changes两段、一键同步、拉取变更、体检、自检)、components/oa/HubSyncButton.vue(人员管理页头:「立即同步」+「同步前体检」+「拉取变更」, 带同步结果与历史,启用统一身份且有system:setting时旁边还有跳「同步定时任务」的入口; 有同步卡在「进行中」时再多一颗「终止」;体检对话框把会动到什么摆成数字格子——真停用多少人/部门、 熔断线算到几个、几个登录名改名、几个僵尸账号让位、几个重名壳子部门,并点名是哪几个)、views/oa/SyncScheduleView.vue(「同步定时任务」页:排期、增量轮询、执行记录,外加同步落库口径 这一段——同步部门、带上已停用的组织、按编码认领本地部门、离职停用与它的熔断百分比、账号让位、 版本没变就跳过、保护本地管理员、单次人数上限、建号补全域名、统一身份管理员账号; 改完按每一项所属的组分别保存,保存即生效),components/oa/HubStatusCard.vue(接入状态卡:模式、同步时间、 凭证来源、免登通道、增量游标、上次结果、测试连接)、components/oa/HubKillSwitchCard.vue(系统设置页的「统一身份应急总闸」开关:就是配置项hub_disabled,打开后一律回本地、保存即生效;被OA_HUB_DISABLED钉住时开关置灰并写明 摘掉变量之后按哪一稿走;关掉要先弹确认,弹层里可以先自检一次);views/oa/SyncScheduleView.vue+components/oa/SyncJobPanel.vue(/settings/sync-jobs「同步定时任务」:左边全量与增量两个任务各自的排期表单——频率 四档分段控件、时间、星期/几号 chip 多选、间隔分钟、补试间隔与次数,字段名与说明一律 取后端配置元数据,底部只提交改动过的项;右边状态面板给下一次执行/轮询与倒计时、往后 3 次、当前口径、被什么挡住、近 30 天次数、增量游标与落后条数、立即执行入口), 数据源api/hub.ts的getSchedule(); 免登两页:utils/ssoLanding.ts(/sso落地那一样凭证在这里换会话——main.ts一进来就 发出去,与语言包、路由块并行下载,路由守卫等它回来直接送人进站,所以从企微卡片点进来 不会再闪一屏「正在确认你的统一门户身份」;一个凭证只兑一次、兑完history.replaceState抹掉地址栏、失败不重试)与views/auth/SsoCallbackView.vue(只剩失败态:照稳定原因码说 一句人话 + 送回门户,等待态是index.html里那幅进站骨架,320ms 之内不出现);views/auth/LoginView.vue(Hub 开启时显示 Hub 下发的验证码、登录失败自动换一张;hub.sso_only时不渲染账号密码,只留「前往统一门户」,?local=1保留应急本地口令入口。版面抄统一门户那边 EDRS 的登录页:宽屏左边一整栏讲系统、 右边一块半透明磨砂只放登录,底下「其他登录方式」那一排圆钮就是回门户的那条第三方入口 (点的还是原来那颗「前往统一门户」走的那条路:先让后端写 state,再整页跳), 样式集中在style.css的.login-*那一组,底色跟着主题色走;components/layout/AuthLayout.vue是那层壳子,右上角两颗是语言与深浅);utils/portal.ts是唯一的「整页跳去统一门户」出口,utils/sessionIdle.ts挂空闲心跳与本地超时计时(后端没配OA_SESSION_IDLE_MINUTES时什么都不做);components/oa/HubPermissionPanel.vue(权限角色页顶部:自己在 Hub 上的角色/权限码/数据范围、 与本地权限目录对账 + 一键登记、按账号代查;hub_perm_enabled关着时整块不渲染) -
大模型接入:
api/ai.ts(目录 / 接入 CRUD / 测试连通 / 拉模型清单 / 试运行 / 草稿试跑 / 总闸读写)、views/oa/AiProviderView.vue(/settings/ai-models:页头的能力总闸卡片、 接入列表带「最近测试」与行内测试连通 / 试运行、新增编辑弹窗按服务商带出厂预设、 底部「先试一次」拿没保存的表单试跑并把两步验证摊开显示);侧边栏在「系统设置」下面 多一项「大模型接入」 -
多语言:
src/i18n/locales/{zh,en}.ts,fallbackLocale: 'zh',中文为默认与基准语言- 文案里的字面大括号要转义:线上跑的是 vue-i18n 运行时版 + JIT 现编(
vite.config.ts里的 alias 与__INTLIFY_JIT_COMPILATION__),t()在组件 render 里编译失败是直接抛错的,一抛那一整块面板就没了, 而开发构建只 warn——所以「本地好的、打包后少一块」多半是文案里的{...}。插值名必须是 ASCII 标识符, 给人看的括号写{'{'}…{'}'} - 取不到词条不报错也不弹窗,只把
form.yearPlaceholder这样一串裸 key 印在人脸上。中英两份 「谁也不许多谁也不许少」(i18n/localeParity.spec.ts)看不见第三种情形——代码里问了一句 谁都没答:改词条的人动的是locales/,用词条的人动的是组件,两边各改各的就漏。i18n/unresolvedKeys.spec.ts补的是这一格:扫全部src/**/*.{vue,ts}里字面量的t('a.b'),逐条走两棵树,任何一环取不到就报出「文件 + key」。它自己不发明写法, 动态拼出来的 key(t(`${x}.title`))归各自那道闸门看住
- 文案里的字面大括号要转义:线上跑的是 vue-i18n 运行时版 + JIT 现编(
-
主题色(整体颜色):一整套界面的主色只有
style.css里那十一组--primary-*(RGB 三元组),tailwind.config.js把primary-*全部指到这些变量上并交出<alpha-value>, 所以bg-primary-500/30这类带透明度的写法照旧生效,换一处就换整套。用哪一套由<html data-accent="…">决定,色板本身只住在 CSS 里(六套:青(默认)/ 蓝 / 靛蓝 / 紫 / 玫红 / 橙), JS 只带一个 id:utils/themeColor.ts认档、写属性、顺手把<meta name="theme-color">对上;index.html那段防闪脚本在画第一笔之前就把属性写上(认不出的值不写,落回默认青), 因此不会出现"先青后蓝闪一下"。存法与深色档、字号同一班车——本地oa.accent是缓存,users.preferences.color才是权威,登录后由adoptPreferences接回来, 换设备、清缓存、从企微换入口进来都还是自己挑的那一版;后端只认schemas.ACCENT_COLORS那六个值,认不出的整档丢掉。入口三处共用components/common/AccentColorPicker.vue(顶栏「外观」、桌面「个人设置」、手机「我的」)。 CSS 变量到不了的两处也问同一本账:统计页画在 canvas 上的线与柱子、页签上那枚内置 "OA" 图标, 由accentColor(600)/accentRgba(600, .18)现问浏览器「当前这一档的--primary-600算出来是哪三个数」,换档时上层那些computed跟着重算,图会当场改颜色;流程、日程、 未知后缀文件在没配色时的兜底同样走这条路(配过的颜色是数据,不跟着换), 日程接口也不再替空颜色填上旧的#0d9488。只有DEFAULT_ACCENT_RGB一份是抄下来的, 用在样式表还没下载的那一瞬,themeColor.spec.ts会把style.css抠出来逐档比对,抄漏了当场红。 加一档颜色要在两处对齐:style.css里补一份同名色板 +utils/themeColor.ts的ACCENT_OPTIONS加一条(含两份 locale 里那两个名字),只动 JS 那一头会静默退回默认青,utils/themeColor.spec.ts钉的就是这层对应关系
自检
仓库里不留测试代码:backend/tests/ 那 42 套验收脚本、backend/scripts/run_all.py、
frontend/src/**/__tests__/ 的 96 个 spec 与 vitest.config.ts 已在 2026-10-15 清掉,
整包(含删前的 package.json)存在 backups/removed-tests-20261015-145736/,
要恢复照里面的 MANIFEST.md 拷回对应子树即可。剩下的都是守卫不是测试:它们对
静态事实(路由表、结构快照、符号引用、类型)与接口报文负责,不造假数据、不改业务数据,
所以跟着代码一起留着。改完代码随手跑不连库的那几条:
cd backend
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/check_relation_scope.py # 关联流程(来源=流程单据)那两档:候选范围默认只列我发起的(脏值退默认、管理员也照收、挂在某一条路由上那一档不被当残骸清掉、两张表上那条 SQL)、那一行读对方表单的哪几列(data. 前缀、8 列封顶、按字段类型翻成人话、没点列不多带一个 data 键)、前后端常量与措辞(不碰库)
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 # 第三方回写「审完了」:发起真单据→拿会话令牌回写→引擎那本账真记上了(跑完自己删干净)
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 # 写回什么时候真的发出去:入队提交当场叫醒 / 回滚不空叫 / 一轮发干净一张单(影子模式,跑完自己删干净)
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 里等值过滤:会长大的表上不能没索引还没理由
python3 scripts/check_seed_repairs.py # 动过出厂种子(app/seed.py)里那些先探一眼再动手的修复,自建临时库
python3 scripts/dump_schema.py # 上一条报不一致时,用它重新导出快照
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 # 浏览器口径闸门:带出值/展示这条链不许用回没有兜底的写法
pnpm vitest run src/utils/themeColor.spec.ts src/components/common/AccentColorPicker.spec.ts # 动过主题色(style.css 那几组 --primary-* / utils/themeColor / 那一排圆点):六档与色板一一对应、点一档就换 <html data-accent> 并留在本地、认不出的值不换画面也不写盘
pnpm vitest run src/utils/branding.spec.ts # 动过主色 / 左上角那块 "OA" 磁贴 / index.html 里那两句图标链接:浏览器页签上那一枚必须还是同一张图(换主色要重跑 frontend/scripts/gen-icons.py)
pnpm vitest run src/stores/tabs.spec.ts src/components/layout/AppLayout.tabs.spec.ts src/composables/useTableLoader.persist.spec.ts src/views/oa/MonitorView.persist.spec.ts src/views/oa/ReadListView.batch.spec.ts # 动过页签 / KeepAlive / 列表条件持久化 / 待阅批量:两张单子各占一格且写的是单据标题、列表页留活而详情页每回重新拉、关掉那张之后钥匙换号、条件与页码带得回来(窄屏只带条件、越界那页收回去)、批量只发看得见的这几条
pnpm vitest run src/views/oa/TodoListView.batchRead.spec.ts src/views/oa/TodoListView.batch.spec.ts src/views/oa/ReadListView.batch.spec.ts # 动过待办 / 待阅那两颗批量钮与「全选这一片」:批量已读只交「动哪几条」不发出口不发意见、按下去先确认一次、五档各说一句人话、整片那一档交的是条件不是几个 id、手机端那一横条上第二颗钮还在(少了 `secondary-label` 手机上就退回点十几下)
pnpm vitest run src/components/oa/mobile/MobileFormSummary.spec.ts # 动过手机端摘要:明细那一行点了就地摊开、两档摊出来逐字同一份、换一张单子不把上一张的展开带过来
pnpm vitest run src/components/oa/mobile/MobileRelationValue.vue src/components/oa/mobile/MobileFormSummary.spec.ts src/components/oa/mobile/MobileFormReader.spec.ts src/components/oa/mobile/useFormPlan.spec.ts # 动过手机上关联的那几张单:摘要与「完整单据」都念回标题、名字点得开 /work/:job、明细里那一列同一条路、空着仍留一行破折号
连库的那几条要能连上开发库才跑得动,全部只读业务数据:一条语句都不写, 个别几条自己建一张临时单再自己删干净(会先把要动的行列出来)。改动碰到下面这些 地方就对应跑一条:
cd backend
python3 scripts/perf_guard.py # 全站只读接口扫一遍:5xx、分页边界、只读 POST,顺带对一遍语句条数
python3 scripts/perf_guard.py --ab # 动过只读缓存 / 预取 / 批量读:再加逐字节 A/B,开缓存必须给同一份报文
python3 scripts/perf_guard.py --dups # 想知道还有没有「一次请求里串着重复问同一张表」的接口:只报告,不算故障
python3 scripts/check_readcache.py # 动过 app/readcache.py 的调用点、作废规则,或认人/已办/待办那三份共用清单
python3 scripts/check_shared_cache.py # 动过 Redis 那层(app/cache.py)的批量读、预取、失效广播,或字典批量预取(dicts.DictCache.prefetch)
python3 scripts/check_design_cache.py # 动过流程定义缓存(app/designcache.py)或 definition.load
python3 scripts/check_presence_guard.py # 动过空表探针与表单快照(app/presence.py)或它那四个调用点(事件订阅/通知渠道/流程代理/卡人报文)
python3 scripts/check_selector_kinds.py # 动过设计器那两问(org.selector_kind_of / selector_kind_conflict)或去重体检的整批预热
python3 scripts/check_write_payload.py # 动过写接口的收尾顺序(app/api/runtime.py::_commit)或序列化口径
python3 scripts/check_action_surface.py # 动过批量处理 / 挂起恢复 / 待阅处理 / 评论 / 标题预览(app/api/runtime.py 那几段)
python3 scripts/check_person_ref.py # 动过认人口径(app/service/personref.py)
python3 scripts/check_dict_import.py # 动过字典项批量导入(service/dicts.import_items / api/dicts 那条 import)
python3 scripts/check_dict_manual.py # 动过字典项归属(models.DictItem.source / dicts.item_is_manual / apply_items / set_item_source)
python3 scripts/check_quota_import.py # 动过额度台账的批量导入(service/quota.import_totals / api/quota 那条 totals)
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_entries_to_read.py # 动过「抄送一律先进待阅」那三句(engine.create_reads 那六个入口 / mark_read 的 handling / mark_reads_for_work 与归档标记):六个入口与两档出口各跑一遍真单子,加签转办不往待阅里塞也钉住(连开发库,跑完自己删干净)
python3 scripts/check_read_batch.py # 动过批量登记待阅(POST /read/view/batch / engine.mark_reads_batch):需处理的不被批量洗成已阅、一条失败不带走整批、逐条原因带得回、登记完角标跟着降、一张图跟着一批走(连开发库,跑完自己删干净)
python3 scripts/check_task_batch_read.py # 动过待办批量这一路(POST /task/view/batch / engine.mark_tasks_viewed / _batch_selection 与 _task_scope_ids 那两份筛选 / GET /task/processing?viewed=):批量已读只盖 view_time 不表态(出口、超时、审批记录、单据状态一个字不许动)、重盖不许顶掉第一次那个时间戳、别人名下与查无此条各归 failed 且带逐条原因;「按筛选取整片」与列表共用同一份 _task_conditions,动了几条 + 超限几条 = 列表共几条,一条不许两头都不在;五档(marked / already / skipped / truncated / failed)各归各不合并(连开发库;探针行是**提交**进去的,rollback 退不掉,开头与结尾各按 __batch_scope_ 那串身份清一次)
python3 scripts/check_cc_action_files.py # 动过抄送需处理带附件(engine.mark_read 的 attachments / claim_attachments 认归档单)或归档件补批注(engine.add_comment / _job_response 的 can_comment):全程在未提交事务里跑,库里不留一行
python3 scripts/check_forward_completed.py # 动过办结之后的转发(engine.forward_completed / POST /work/{work_id}/forward / 详情报文 can_forward):只认归档件、身份闸、转出去落待阅、要求处理的点开不算完、旗标与闸同进退(连开发库,跑完自己删干净)
python3 scripts/check_flush_defer.py # 动过引擎里 db.flush 的作用范围(_log / notify / _arrive_manual)
python3 scripts/check_simulate_paths.py # 动过审批人解析 / 环节路由 / 试算
python3 scripts/check_log_timeline.py # 动过流转日志留痕
python3 scripts/check_completed_dedup.py # 动过「我的已办」按(单 × 来源)折叠(app/service/completed.py 与四处计数):全程在未提交事务里跑,库里不留行
python3 scripts/check_done_cc_split.py # 动过已办 / 已阅分家(app/service/completed.py 的 groups_subquery/collapse、serializers.read_completed_as_done、api/runtime.py 的 list_completed/list_read_completed/_done_filters、export 的 DONE_COLUMNS、portal/support 那两处计数、engine.mark_read 的意见选填):需处理的归档行只许出现在已办、不需处理的只许出现在已阅,改版前那条"老写法留下的行"不回填也要自己挪位,意见留空照样办得掉;全程在未提交事务里跑,库里不留行
python3 scripts/check_done_current_step.py # 动过「我的已办」那一列「当前环节」(app/service/completed.py 的 progress / api/runtime.py 的 list_completed 与 _progress_fields / api/export.py 的 DONE_COLUMNS 与 _done_lines / frontend 的 DoneListView.vue):在途单那一格读的是单据此刻的现账(不是 oa_task_completed 那份只在归档时才写的快照),单据往前走要当场跟着变,落定的报结局、查不着的不猜、停在自动环节上退认游标,一页只多一条 UNION ALL,CSV 那一列与界面同一个答案;全程在未提交事务里跑,库里不留行
python3 scripts/check_detail_export.py # 动过流程明细导出(app/service/detail_export.py 与 app/api/export.py 的 /export/detail/*):未操作者五类口径各造一条真行验命中与不命中,分表与合并两种表头、七项筛选、两条上限一起对;自己建流程与单据,跑完删干净
python3 scripts/check_delete_unstarted.py # 动过「删除还没发起的单」(engine.delete_unstarted / deletable_task_ids / POST /job/{job}/delete,含删单那一刻给第三方那一句通知):建自己的流程与单据,跑完删干净
python3 scripts/check_begin_resubmit_todo.py # 动过开始环节提交(engine.start_from_begin:界面那颗「提交」、第三方 auto 回写、发起人确认第三方备好的表态三条路共用):退回到发起人再提交之后,这张单在「我的待办」里只许留一条,且这一步照常进已办与审批记录(建自己的流程与单据,跑完删干净)
python3 scripts/check_todo_work_status.py # 动过待办列表那一只「流程状态」筛选(api/runtime.py::_task_work_status_conditions 与 _task_conditions 上的 work_status / api/export.py 的 /export/tasks):筛的是**所属单据**的流程状态(待办行上那份 status 只有 pending 一个值),在途认运行表、办结/终止/作废认归档表、已挂起认 Task.pause 那份冻结标记;多选是并集、脏值不掺进来、整串认不出时对出空列表而不是没筛过的全量;列表、批量「全选这一片」、导出 CSV 三条口用同一份条件(内存 sqlite,不碰开发库)
python3 scripts/check_todo_starter_unit.py # 动过待办行上的部门(models.Task.creator_unit_name / engine._arrive_manual、add_task、transfer、_spawn_next_serial 那五处建待办 / serializers.task):待办列表「发起人」那一格读的是发起人的部门(抄自单据),不是本环节处理人的;换人之后的新待办照旧带着发起人的部门(内存 sqlite,不碰开发库)
python3 scripts/check_read_starter_snapshot.py # 动过待阅行上的发起人(models.Read.creator_person / creator_unit_name 与 oa_read_completed 同名两列 / engine._subject、create_reads、_refresh_read、mark_read、_finish_work / serializers.read_row / service/inbox 的搜索 / api/export._inbox_lines):统一待办与已阅列表「发起人」那一格画的是这张单的发起人(抄自单据),不是把它递给我的那位经手人;环节自动抄送、手工抄送、分享、批注 @ 我、归档抄送、再抄一次、登记已阅、办结搬档八条路一起对,导出 CSV 那一列与界面同一份账(内存 sqlite,不碰开发库)
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 调度线程的睡眠与叫醒)
python3 scripts/check_notify_wake.py # 动过外发任务的叫醒通路(service/wake.py,或 channels.enqueue_for / events.emit / channels.resend 里的 mark,或 main.py 调度线程的睡眠与叫醒)
python3 scripts/check_hub_breaker.py # 动过 Hub 传输层与熔断(app/service/hub.py)——不连库、不碰真 Hub
python3 scripts/check_hub_sync_details.py # 动过同步记录的落库与回显(hub_sync.run_details / _finish / serialize_run)或三条熔断底线(dbconfig + hubconfig)
python3 scripts/check_hub_sync_shell_units.py # 动过空壳部门判据与一键清理(hub_sync.find_shell_units / api/org.py 的 /units/shells*)
python3 scripts/check_job_payload.py # 动过单据详情的拼装(runtime._job_response / definition.build)
python3 scripts/check_design_cache.py # 动过详情页什么时候问设计缓存(runtime._job_response 与 definition.design_cache_enabled)
python3 scripts/check_org_tree_managers.py # 动过部门树/部门列表补负责人姓名(api/org.py::_managers_by_id)
python3 scripts/check_pool_reset.py # 动过连接池归还口径([database] pool_reset)——默认只扫常用接口,--all 扫全站
python3 -m advance_cash --run # 写路径端到端:跑两张真单据把两条分支走通,跑完自己删单
python3 scripts/check_embed_api.py --base http://127.0.0.1:8000/api/v1 得对着一个
真在跑的 API 进程跑(它验的是过完路由与序列化才看得见的东西),只建自己那几条带时间戳
编码的数据源,跑完连自己发过的短码与留痕一起删掉。
性能为什么这么花、动哪一层要跑哪一条,见 docs/performance-optimization.md。
约定与注意
- 认人只认登录账号:库里"是谁"这一列存的一律是
users.account,身份 DN 只做展示; 老前端若还发X-Identity头,后端收了不参与判定(一人多身份那套口径连同oa_identity表在 2026-10 一起下线,见docs/person-reference-design.md) - 时间基准:全链路使用服务器本地 naive 时间(
models.localnow),历史 UTC 数据在 首次启动时一次性平移并由system.timestamp_clock记录,避免审批时间相差 8 小时 - 办结迁移:流程办结后
oa_work/oa_task的行会迁入oa_work_completed/oa_task_completed,因此活动表为空是正常状态,不是数据丢失 - 审批人可以直接挂岗位角色:环节属性的「处理人来源」可选身份 / 人员 / 岗位角色 / 分组 / 部门 / 发起人 / 上一环节 / 表单字段,选岗位角色时下拉里就带着成员,面板下方「现在会解析到」实时列出这批 配置当前会落到谁、哪些名字在组织里已经找不到。角色换人不用改流程。它与决定菜单和数据范围的 「权限角色」是两套,见《权限角色》
- 配的是什么来源就照那个来源解析(
service/org.py,系统设置「审批口径 → 严格按配置找人」, 默认开):type=role就按岗位角色认,同名部门 / 分组一个都不掺进来,这一类里根本没有这个名字时 也不换个类别接着找——只认这一行写的本来就是一个身份串,其余如实报「解析不到」,由环节上明配的 「空审批人」兜底接住(宁可这一环没人批、设计器报红,也不能把待办派给配置里没写的人)。同一项还管住 两处「顺手多走一步」:「部门负责人」只认这个部门自己登记的负责人,不逐级往上级部门找;「直属上级」 只认登记过的直属上级,不拿部门负责人顶替。关掉这一项恢复老口径。解析不到时预览会说清原因, 例如「副总经理」不是岗位角色,它是部门——要派部门里的人就把这一行的来源换成部门 - 筛选参数:
enabled/expired接受1/0/true/false,缺省表示不过滤 - 脚本沙箱:表达式与脚本先过 AST 语法节点白名单,再过滤双下划线属性与危险名字,
运行期只注入
data/form/work/user/context与一批安全内置函数 (lenintminsumcontainsdays_betweennow…),表单字段还会作为裸变量直接可用, 因此条件里写days > 3、amount >= 5000即可;保存时由expressions.validate_script校验 sql/schema.sql由python3 backend/scripts/dump_schema.py从实库导出,改了models.py之后重新跑一次; 忘了跑会被python3 backend/scripts/check_schema_snapshot.py拦下——生产库交给 DBA 手工建表时,快照落后一列 就是新库第一次登录报Unknown column,而本机测试库早被启动补列修好了,只有快照对账查得出来