Go to file
kangwenjing 71458e2c32 feat: 新增主题色功能,支持用户自定义界面主色调
新增主题色选择器组件,支持青、蓝、靛蓝、紫、玫红、橙六种颜色选项
前后端适配主题色存储与同步,用户偏好新增 color 字段
登录页与个人设置界面适配主题色展示,样式表按主题色拆分多套配色
完善相关国际化文案与测试用例,优化登录页面布局适配主题色切换
2026-11-19 09:12:22 +08:00
backend feat: 新增主题色功能,支持用户自定义界面主色调 2026-11-19 09:12:22 +08:00
deploy feat: 统一待办与界面偏好功能迭代 2026-11-18 09:30:05 +08:00
design feat: 新增手机端完整交互界面与流程终止配置功能 2026-11-04 15:25:17 +08:00
docs feat: 新增主题色功能,支持用户自定义界面主色调 2026-11-19 09:12:22 +08:00
frontend feat: 新增主题色功能,支持用户自定义界面主色调 2026-11-19 09:12:22 +08:00
sql feat: 手机端关联审批单三处点得开,页签图标与OA磁贴统一 2026-11-18 14:37:18 +08:00
.dockerignore init 初始化 2026-11-02 13:57:31 +08:00
.gitignore chore: 导入 unis-oa 项目代码 2026-10-13 16:29:41 +08:00
Dockerfile feat: 新增管理员改道事件与处理意见附件支持 2026-11-13 10:37:44 +08:00
README.md feat: 新增主题色功能,支持用户自定义界面主色调 2026-11-19 09:12:22 +08:00
docker-compose.yml feat: 新增多选月份字段类型,统一品牌名从 UniSOA 改为 UnisOA 2026-11-03 09:20:59 +08:00
permission-integration.md chore: 导入 unis-oa 项目代码 2026-10-13 16:29:41 +08:00
third-party-integration.md chore: 导入 unis-oa 项目代码 2026-10-13 16:29:41 +08:00

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)。不单独成行,那几条 抄送在审批记录里就一个字都看不见。角标跟着环节类型说「办结时的抄送 / 作废时的 抄送 / 抄送送达」,此刻还停着没人签的那一环(到达时那档已经抄出去了)也照样成行, 所以它不再挂在末尾那句「等谁处理」底下——两处各摆一次反而像抄了两回。 没走到的那一支不成行:那一支只有配置没有事实,摊在时间线里会读成「抄过了」。
    • 打印件(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 完全一致, 接口和老数据还认它),但界面上没有入口,也不再由流程设计器读写。 为了不必先知道"标题规则藏在哪",表单设计器把它摆在明面上:

  • 表单设计器工具栏常驻一只「标题规则」按钮,徽章写着当前口径(默认 / 模板 / 表达式); 点它 = 选中画布里那格「流程标题」并把规则面板摊开,表单里还没有那一格时先替你加上;
  • 画布那一格把口径写在格子上:模板 角标 + · {部门}-{发起人}-{流程名称},不点进去也看得出;
  • 字段库里的「流程标题」独占一行并带「规则」标记,加字段时就知道它带着规则;
  • 规则面板是一块默认展开的高亮卡片,标题行写着生成方式与模板原文,收起来也不丢口径;
  • 流程上真带着一条历史遗留的规则(接口或旧版本写的)时,面板会当场用琥珀色提醒它盖住了 这一格,不再把人指向一个已经不存在的入口。

生效顺序是:

  1. 流程上带着旧规则(oa_process.title_config.mode != default)→ 仍用流程那条;这种数据 只能来自接口或旧版本,界面上已无处可配,新配的规则不会走到这一步;
  2. 流程没配 → 用字段自带的那条,配在表单上的好处是规则跟着表单走, 同一张表单挂到别的流程上不用重配;
  3. 两条都没有 → 老口径(表单里的 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 (与 Tailwind lg 同一条断点、底部要让出的高度)、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 + 更多 + 翻页)、 TaskPanel NewsPanel MeetingPanel SchedulePanel FilePanel, 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`))归各自那道闸门看住
  • 主题色(整体颜色):一整套界面的主色只有 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 与一批安全内置函数 (len int min sum contains days_between now …),表单字段还会作为裸变量直接可用, 因此条件里写 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,而本机测试库早被启动补列修好了,只有快照对账查得出来