Go to file
kangwenjing ae3f544fd6 chore: 部署镜像升到 202611030927
发起流程页那张卡片下面的「在途流程 / 累计办结」改成只算本人发起的单。
清单接口 GET /api/v1/process/processes 新增 count_scope=mine(口径同「我发起的」
列表:creator_identity = 登录账号,走 idx_oa_work_creator 现成索引前缀),
发起页带上它;设计器的流程清单不传,仍看全系统那一版。

镜像按 deploy/k8s/README.md 那条指令构建:--platform linux/amd64 + --load,
已推到 docker.oa.unissense.tech/public/unis_oa:202611030927 与 :latest
(同一 digest sha256:f88b197e…,Harbor 侧确认只有 linux/amd64 那一个平台)。
2026-11-03 09:29:03 +08:00
backend feat: 新增多选月份字段类型,统一品牌名从 UniSOA 改为 UnisOA 2026-11-03 09:20:59 +08:00
deploy chore: 部署镜像升到 202611030927 2026-11-03 09:29:03 +08:00
design feat: 新增多选月份字段类型,统一品牌名从 UniSOA 改为 UnisOA 2026-11-03 09:20:59 +08:00
docs feat: 新增多选月份字段类型,统一品牌名从 UniSOA 改为 UnisOA 2026-11-03 09:20:59 +08:00
frontend feat: 新增多选月份字段类型,统一品牌名从 UniSOA 改为 UnisOA 2026-11-03 09:20:59 +08:00
sql feat: 新增多选月份字段类型,统一品牌名从 UniSOA 改为 UnisOA 2026-11-03 09:20:59 +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: 新增多选月份字段类型,统一品牌名从 UniSOA 改为 UnisOA 2026-11-03 09:20:59 +08:00
README.md feat: 新增多选月份字段类型,统一品牌名从 UniSOA 改为 UnisOA 2026-11-03 09:20:59 +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          # 统一响应与异常
│   │   ├── 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_db_dsn.py         # 拼 DSN 的对账:口令带 @ : / # % 空格时还连得上库吗
│   ├── scripts/check_binding.py        # 取数内核与候选来源:写法解析、源健康判据、前后端措辞对账
│   ├── 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_person_ref.py     # 认人只认登录账号:认不出就不是一个人,改名不影响历史
│   ├── scripts/check_identity_refs.py  # 配置里的引用不能还压着身份 DN:岗位角色成员要真解析得出人
│   ├── scripts/check_memberships.py    # 一个人挂几处岗位:反查与正向解析同口径、且不随人数排队
│   ├── scripts/check_cc_reads.py       # 环节抄送建待阅:几条规则合起来只读一趟 oa_read,没得抄一趟都不问
│   ├── scripts/check_flush_defer.py    # 引擎 flush 只刷该刷的那几行:同一张单办两遍,逐行逐列与整刷对齐
│   ├── scripts/check_simulate_paths.py # 设计器逐环节试算:配好的路由能不能真的解析出审批人
│   ├── scripts/check_log_timeline.py   # 流转日志时间线:留痕不倒挂、上一条不每趟回库
│   ├── scripts/check_completed_dedup.py # 已办按单折叠:一张单只摆一条,次数与角标/导出/工作台四处同口径
│   ├── scripts/check_delete_unstarted.py # 待办上删掉还没发起的单:谁能删、删干净没有、额度、嵌页面的账与给第三方的那一句一起收尾
│   ├── scripts/check_begin_resubmit_todo.py # 退回到发起人又重新提交:同一张单在「我的待办」里只留一条(开始环节提交三条路共用)
│   ├── scripts/check_leader_lease.py   # 多副本那把租约:过期可接管、别人抢不走、库读不动时后台照跑
│   ├── scripts/check_outbox_wake.py    # 写回投递的即时性:入队当场叫醒、回滚不空叫、一轮把一张单排着的发干净
│   ├── scripts/check_hub_breaker.py    # Hub 不回话时的自保闸:冷却、探测、自检绕开、并发第一波限量(本地造假 Hub)
│   ├── scripts/check_job_payload.py    # 单据详情:定义并发拆开问再拼回,顺序/表单清单/归档分支与串着问一字不差
│   ├── scripts/check_org_tree_managers.py # 部门树的负责人:复用已读进内存的人员行,停用/系统账号/范围外三种照样写得出名字
│   ├── scripts/check_pool_reset.py     # 连接归还口径:还回池子的连接一律已自己收尾(含一次故意的脏归还反向自检)
│   ├── scripts/check_dict_import.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   # 部署自查:这一趟读的是哪几份配置文件(不连库、不起服务)
│   ├── 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/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/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/platform-open-api-design.md  # 开放平台:外部系统调 OA 的钥匙 / 作用域 / 限流 / 留痕,与事件推送的分工
├── docs/notification-channels-design.md # 消息渠道:邮件与钉钉/飞书/企微群机器人,投递留痕、退避重试与死信
├── docs/mobile-pwa-design.md         # 移动端:为什么是 PWA、离线外壳只兜底不缓存接口、底部导航与安全区
├── docs/process-intervention-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 账号对齐
└── 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,不会漏。

上线步骤(部署机上):

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)一处,界面能改的那些则进了数据库。 这两个文件已从仓库删掉,如果部署机上还留着, 后端启动时会在日志里提醒一句「不再被读取」然后忽略它们,不会被误当成生效配置。

运行配置(113 项,存库即生效)

组 界面上的名字 项数 都管什么
site 站点信息 5 站点名、Logo、描述、系统访问地址(发出去的邮件与群消息里的单据链接用它拼全链接)、是否开放注册
security 登录令牌 3 访问令牌分钟数、刷新令牌天数、空闲多久要求重新登录
hub 统一身份登录 32 Hub 地址与开关、九个接口各走什么路径、登录模式(含只允许门户免登)、验 token、免登三件套(应用编码 / 应用密钥 / 门户地址)、目录密钥与服务端凭证、Hub 不回话时的两道自保闸(冷却秒数与同时等待上限,见 docs/hub-integration.md §14)、应急总闸…
approval 审批口径 1 是否严格按环节配置找人(关掉会往上级与部门兜底)
hub_sync 组织人员同步 20 定时同步总开关(只在界面上配,文件与环境变量不认)与排期(频率 / 时间 / 每周哪几天 / 每月哪几天 / 间隔分钟)、失败补试、增量同步(周期 / 单批条数 / 落后回全量)、停用策略、单次人数上限、按编码认领本地部门… 都在「同步定时任务」这一页配
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_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), 支持上移 / 下移 / 复制 / 删除,每个字段可配字段名、类型、必填、只读、占位提示、说明文字,数字字段另有最小值 / 最大值 / 步长 / 小数位 / 单位。

  • 多选月份(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 逐行复用同一份口径)。

  • 定位不接地图服务: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 这种点路径)、 用什么姿势挑(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。 下拉里打字要真的搜得动:候选搜索那一趟发出去的入参表里永远有 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,relationProcess 限定只允许挂某个流程的单。 挑流程不再在一长串流程名里翻:先选流程类型、再在那个类型里选流程 (components/oa/design/ProcessPicker.vue,类型带条数、没归类的单独一档「未分类」、草稿标出来; 选中流程会把类型筛子钉到那一类,手动换类型且当前流程不在该类就清空)。明细表列上同一套组件换 两栏窄版,数据源那边的「来源流程」也是它,存下来的仍然只有流程 id。 换成别的来源就是另一回事了:挂字典(存字典项编码,级联、附加值带出、越界校验、导出翻译 全跟着来,等于一个「值由字典管的多选框」)、挂列表型外部数据源(几千个物料里搜一条, 存源给的编码)。原来的 components/oa/RelationPicker.vue 没有别的用途了,弹窗那套原样 搬进 OptionPicker,少一份各写各的实现。

  • 联动跟着字段的变化一起动:级联下级给哪些项、显隐 / 必填 / 只读、字典带出那几格, 判的都是当下这一份表单数据,所以一改就动,不必等人点一下别的格子。判据挂在数据上 而不是挂在某一条写入通道上——公式算出来的金额、外部取数、别的系统回填,都不经过录入框, 以前只在「人在框里点了一下」那条路上重算,于是这三条通道改完上级,下级的老值还留在单子上。 带出与「下级选岔了的值」要反复扫到没人再改才算收口:带出去向常常同时是下一层的上级 (选物料带出单价,单价那一格又决定下一格),只扫一遍结果就取决于字段在表单上的先后顺序 (utils/formLinkage.applyLinkage ↔ 后端 dicts.apply_auto_fill,两边同一本账、同样收敛)。

  • 系统带出(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,发请求时后端一个都不看。 选项是「列表里挑一条」的,还有第二条更省事的路:数据字典把选项来源选成外部数据源, 绑一张列表型数据源同步进字典项,表单那边照旧只填字典编码——级联、字典带出、提交校验 一行都不用改,上游挂了选项停在最后一次同步那份。口径见 docs/external-data-simplification.md。 要带的是另一个流程里那张单(填报销单时把上次批完的请假单里的出差日期、目的地点进来), 不用为它注册一个 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,两边都先过一遍标签页展开)。 断的是发起页那一半:它以前只看字段自己勾没勾必填,于是开始环节明明把那一格藏了, 屏幕上没有它、那颗「发起」却按不动,还喊一句"请先填写它";同一份配置在审批页也是 同样的两处各算一套。现在这一格在这一环不存在,就不在这张单子的功课里—— 唯一的例外照旧留在后端那一句里:字段自己勾了「默认隐藏」的系统带出与公式 (编号、金额大写)仍然要有值,藏起来不等于可以不生成;环节显式接管那一格才算放手。 带出、阈值、额度这三样对每个字段都开着(口径只有一处: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。

  • 字典项一次贴一批(POST /process/dicts/{编码}/items/import):建完字典正是往里填选项的时候, 二十个选项一格一格点最磨人,所以字典项那排工具条上补了「导入」,新建完一本手工字典还直接把它摆出来。 从 Excel 复制几行贴进来,或选一个 .xlsx / .csv 文件(Excel 在前端用 xlsx 拍平成制表符, 只在真选了表格文件才加载它,不新增上传接口、不在服务端落临时文件);第一行是表头就按名字认列 (取值 / 编码、显示名 / 名称、上级、排序、启用、附加值,中英文都认),没表头就按 「取值 / 显示名 / 上级 / 排序 / 启用 / 附加值」的位置读,用的是哪几列当场说清。 导之前先出一张结论表:每一行是新增 / 覆盖 / 跳过 / 没收(附一句为什么),行号按你贴进去那段文本数 (空行与表头都算),改完再导对得上;判据与后端逐条落库时是同一套(utils/dictImport.ts ↔ service/dicts.import_items),不会出现「预览说三条、导进去两条」。取值已存在时跳过还是覆盖由你选, 两种都不删没出现的项——导入是"再补一批",不是"这就是全部",这一条跟「选项来自外部数据源」的 同步正好相反(那边上游撤了要停用)。顺序也不抢:给了排序就用给的,没给就接在现有最大序号后面。 附加值两种写法都收({"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);
  • 谁算哪一段:发起人、工号、所在部门、流程名称、此刻的日期时间,发起页在登录态里 当场就填好;直属上级和部门负责人要查组织库,由引擎发起时写进 work.data (service/autofill.py 是唯一口径),那一刻界面上写明「提交后由系统自动填写」, 不拿猜出来的人名糊上去;
  • 只在发起那一次带:前端只在没有单据可挂时(发起页、草稿)填自己,办到第二环节的 表单里登录态那个人是审批人不是发起人,不能拿他当申请人;草稿里填过的、替别人提单时 改过的申请人一律不动;这一格被环节配成只读时,这次提交的值在落库前就被丢掉, 仍然回到「空着 → 系统补」;
  • 写歪当场挡:来源写在这类字段带不出来的值上(比如部门字段要带「流程名称」), 保存表单就被挡回来,前端 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,右栏在弹窗打开期间不挂载,两处不会各持一份状态。

「表单与字段权限」那一格开始环节也有。 面板本体在 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),环节显式隐藏的优先级不变, 回看与打印那一屏手上没有这一份数据、算不了条件,仍保守按隐藏算。钉在 check_hidden_field_rules.py 与 formRuntime.hidden.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} 与它共用同一个拼装函数)一样带着这四个字段。

口径都写在 app/engine/definition.py:pin() 拍照,for_work(db, 单据或待办) 取 「这张单眼里的那一版」。引擎与接口里凡是手里有单据 / 待办的地方都走 for_work,手里只有 流程 id 的地方(设计器、流程模拟、发起那一刻)走 load 读当前设计;两条路拼定义用的是 同一个 build,不会长出两种行为。回归由 scripts/check_design_pin.py 守着(46 条), 其中第 9~12 组守的就是归档这道坎:引用跟着搬、归档详情页报的是冻结那一版、没有引用的 老归档单照旧现读、启动回填按办结时刻的高水位往前推、快照与流程一起没了也不能把人锁在 门外,以及删流程只清没人认领的那几版快照——归档单认着的那一版留在库里。

还跟着当前配置走的两件事,说清楚免得踩:

  • 外部审批接口开没开(环节那格 openApprove 打开没有、对哪个应用开口):管理员当场 关掉,第三方在 OA 之外的表态就当场收不进来。这一格是「闸口」不是「图纸」,跟着人走。 界面上那句「这一环的审批在外部系统里进行」也照当下算(node_approve.lock_states_for_process 一次查库读实库那行),不拿冻结那一版的配置拦人——否则横幅拦着审批人、引擎其实还收得住。
  • 字典项、外部数据源、额度台账、人员与部门这类引用数据:本来就是设计之外的事实, 改了照常即时生效,在途单也跟着变(选项、额度余额这些停在过去反而对不上账)。

权限角色

菜单、接口、数据范围三层都由「权限角色」说了算,一处配置全链路生效,改完立即生效(不用重新登录, 前端下一次请求就带着新的权限码)。

权限码: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 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。

  • 几十秒内跟改: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。

同步定时任务

排期不进 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 且不是走退回路由回去的那张已办才算数。或签 / 按比例会签凑够票后被系统代结的、转办出去的、 加签转走的、把单子打回去的,都没在这张单上表过态——后面再遇到他,该批还得让他批
  • 这套规矩在设计期就看得见结果,不必发一单才发现谁被跳过了: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
  • 抄送条件(环节 config.ccRules[].expression):每条自动抄送规则都能带一个条件 (与分支条件、条件免审同一套表达式),这一单命中才抄这一条;留空=无条件,到点就抄, 老配置的行为一个字都不变。人工环节、结束/作废环节的办结抄送同一个口径, 条件算不出来按「不抄」处理,免得表达式写错时把单子扫给不该看的人
  • 退回:退回上一环节 / 退回指定环节 / 直接退回发起人,可指定退回后的走向。退回发起人 不受环节 goBackConfig.type 影响,永远在候选最后;提交人在开始环节拿到一条待办, 改完重新提交就从开始环节那条出口重新往下走(嵌入子流程与发起人身份丢失时不给这一项)
  • 加签:前加签 / 后加签 / 并加签,支持指定多人
  • 转办与委托办理,被转办人办结后原办理人回到已办并可撤销转办
  • 已办撤回(在下一环节尚未处理时回退)
  • 「我的已办」按单折叠:同一张单办过几次也只摆一条,摆最近那次表态,旁边标「已处理 N 次」, 历次意见与流转在详情的审批记录里一条不少。流水账不改写法——审批记录要逐条回放、按比例会签 要逐票数票、撤回已办按行号定点撤,三件都按行算——折叠放在读这一侧(service/completed.py)。 列表总数、导出 CSV(多带一列「处理次数」)、首页角标、工作台那个「我的已办」一起改成数单 不数行:两处口径不一样时,人只会以为系统把数据弄丢了
  • 催办(累计次数与催办时间)、管理员代催办
  • 终止流程、待阅件、草稿箱、附件上传下载
  • 流程代理(休假期间自动代为处理)、待办交接
  • 超时与超期提醒:延时环节唤醒 + 超期标记 + 调度线程
  • 批量审批:POST /task/batch-execute 一次提交多条待办,逐条复用单条流转、逐条提交, 某条因为必填没填而失败只回滚那一条,失败原因原样带回界面逐条列明
  • 编号规则:办结时间、耗时(秒)、流转轨迹与工作日志全程留痕

审批通过之后怎么把结果送回业务系统

报销单办结要在 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 那一格。模板页底部当场给出「什么时候真的会发」= 勾中的终态 + 被挂在哪些环节的哪一时刻, 两处合起来才是答案;存量那批「模板自己点名到达某环节」的配置照旧发,页面上一个按钮把它们一次搬进 环节(写挂载与撤声明同一事务,中间不留"两边都没配"的空档)。

退回与撤回也是触发点:界面上有「退回」「撤回」两颗钮,报文里以前却没有这两个时刻——想告诉上游 "这张单被打回去了",只能挂到收单那一环的「到达时」,归属当场错位(对面分不清是正常到达还是被打回)。根因是 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。

反过来:外部系统怎么调 OA,OA 怎么主动通知人

上面那条是"审批结果送出去"的业务凭证那一路(报文格式由上游定、发错要冲销)。 平台还留着另外几条路——往外三条、往里一条,配的地方与对账口径都不一样,别混:

你要做的事 走哪条 配在哪
办结之后按对方格式生成一张凭证 反写模板 oa_integration 「集成配置」页,字段一格格映射
单据有动静就通知外部系统一声 事件订阅 oa_open_webhook(七个事件,HMAC 签名,默认不带表单数据) 「开放平台」页
外部系统主动查/发起/代办 开放接口 /api/v1/open/*(应用令牌 + 五个作用域 + 限流与调用留痕) 「开放平台」页建应用
同一条待办提醒送到邮箱 / 钉钉飞书企微群 消息渠道 oa_notify_channel(六个事件各渠道订阅) 「消息通知」页

三条外发路共用同一套投递底线:与业务动作同一事务入队 → 后台线程退避重发 → 重试用满进死信 → 停在"发送中"当结果未知、绝不盲发第二遍。订阅方挂了不该让审批人办不成单, 所以入队这一步永远不把异常抛回业务代码。设计文档: docs/platform-open-api-design.md、 docs/notification-channels-design.md。

两个容易踩的分寸写在文档里,这里点名: 收件人不做配置项(站内信发给谁、这一路就发给谁,账号没邮箱就在投递记录里落一条 skipped 并说清去哪补,不静默丢);群机器人一批发一条(三个人会签不会往群里甩三条一模一样的消息)。

装到手机桌面上(PWA)

前端是可安装的 PWA:/manifest.webmanifest + 图标 + 一层只兜底的服务工作者。 规矩是外壳可以缓存、接口一个字节都不缓存——缓存一份待办列表看着像"能离线办公", 实际是让人对着一张早就被退回的单子签字。窄屏(<1024px)换成底部标签栏, 导航项与侧边栏同一套权限码,待办角标共用一份计数;iPhone 上输入框字号钉 16px, 免得获得焦点时页面自己放大。装之前要 HTTPS(内网用自签证书也行,手机得装上根证书)。 边界与真机验收清单见 docs/mobile-pwa-design.md。

多副本部署(--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 打开后,后面环节改了表单字段会按同一规则重算,在途待办的标题一起改 (待办列表与站内信读的都是 task.title);
  • 发起人亲手改过的那句记在 work.variables.titleManual,开了自动重算也不盖他写的。

标题也可以是表单里的一个字段。 想让用户在单据表单里看得见、改得动标题,就去 表单设计 拖一个 流程标题 字段(type: title,一张表单只能有一个,多余的保存时被挡)。 这一格的值就是 work.title,标题从此只有一处出处:

  • 发起时规则算出来的一切都写回这一格,发起页顶部那只独立的标题输入框自动让位, 不会再出现两处标题打架;
  • 字段上的「这一格的标题怎么来」两选一:rule 按标题规则生成(受规则里 editable 管)、 manual 由发起人自己填(比流程级开关更具体,规则只在这一格空着时补一句);
  • 发起页里这一格随表单实时重算:没人动过它时,改了别的字段它就跟着规则换一句; 亲手改过之后不再被规则盖掉;
  • 后续环节里改这一格等于改标题:引擎采纳他写的这句、同步下一环节待办,并从这一刻起 不再自动重算(等同 titleManual);谁能改由该环节的「表单字段权限」决定;
  • 存草稿取同一句:这一格写着什么,拟稿箱里就叫什么,发起前后不会换名字。

规则界面上只有一处可配。 就在表单那一格上(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):

  • 发起页:表单里那一格随填随改,公式、带出、级联算完的值都算得进来;
  • 表单设计器的「预览」页:填两个字段就能看到规则跟着动,配完不必先保存再发起一张测试单。 这一份用的是画布上还没保存的规则与字段清单,改哪儿预览哪儿;
  • 办理页:后面那一环改了表单字段、而规则又开了「自动重算」时,标题框下面写一句 「提交后会更新为 …」——只说,不写回。提交之前那一句还是上一个环节的,改了字段就当场改口 会让人以为已经改了。

三处守的是同三条分寸:只覆盖系统自己写的那一句(字段里是人亲手写的就原样留着, 规则收了修改权限时反过来——那一格归规则说了算);没人动过的标题格在问后端之前先从数据里 摘掉(否则规则再怎么改,后端念回来的都是上一轮那句老的,标题从此不再跟着表单走); 防抖 + 迟到不回写(一路打字只问一次,回来的答案只配给当下这份数据)。 办理页那一句走 POST /job/{job}/title/preview:按这一单此刻的数据 + 将要提交的那份改动算, 只读不写库,也没办过的人(发起人、有待办的人)都能问。

接口一览

前缀 /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 GET /task/processing(每行带 deletable:本人创建、还停在开始环节、没压在别人手上)/task/completed POST /task/{id}/execute POST /task/batch-execute /goback /addtask /transfer /press POST /job/{job}/terminate
导出 GET /export/works?scope=created|admin GET /export/tasks?scope=processing|completed(CSV,带 UTF-8 BOM)
支撑 /attachment /attachment/{id}/download /draft /notification /read /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-*、 teal 主色的 Tailwind 主题、暗色模式、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
  • 权限层: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 时旁边还有跳「同步定时任务」的入口; 有同步卡在「进行中」时再多一颗「终止」)、 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(); 免登两页:views/auth/SsoCallbackView.vue(/sso 落地页:票据换会话、history.replaceState 抹掉地址栏票据、失败不重试只送回门户)与 views/auth/LoginView.vue(Hub 开启时显示 Hub 下发的验证码、登录失败自动换一张;hub.sso_only 时不渲染账号密码,只留「前往统一门户」, ?local=1 保留应急本地口令入口);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 标识符, 给人看的括号写 {'{'} … {'}'}

自检

仓库里不留测试代码: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_binding.py            # 取值写法 / 多源合并 / 数据源健康判据,顺带对一遍前后端共用的那几句措辞
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_writeback_revisit.py  # 环节写回重发:提交时/到达时/审批通过后各发一次,退回改值再提交与撤回后重办能否再发(影子模式,跑完自己删干净)
python3 scripts/check_writeback_trigger.py  # 「什么时候发」拆两处:终态可多勾 / 一条都不勾是合法态 / 旧写法一键搬进环节(跑完自己删干净)
python3 scripts/check_outbox_wake.py        # 写回什么时候真的发出去:入队提交当场叫醒 / 回滚不空叫 / 一轮发干净一张单(影子模式,跑完自己删干净)
python3 scripts/check_writeback_config.py   # 写回配置全库体检:先报现库哪几条会静默不发/多发,再把八种病各造一遍自证(--report 只报不当闸门)
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

连库的那几条要能连上开发库才跑得动,全部只读业务数据:一条语句都不写, 个别几条自己建一张临时单再自己删干净(会先把要动的行列出来)。改动碰到下面这些 地方就对应跑一条:

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_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_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_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_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_hub_breaker.py        # 动过 Hub 传输层与熔断(app/service/hub.py)——不连库、不碰真 Hub
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,而本机测试库早被启动补列修好了,只有快照对账查得出来