发起流程页那张卡片下面的「在途流程 / 累计办结」改成只算本人发起的单。 清单接口 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 那一个平台)。 |
||
|---|---|---|
| backend | ||
| deploy | ||
| design | ||
| docs | ||
| frontend | ||
| sql | ||
| .dockerignore | ||
| .gitignore | ||
| Dockerfile | ||
| README.md | ||
| docker-compose.yml | ||
| permission-integration.md | ||
| third-party-integration.md | ||
README.md
UnisOA 流程审批平台
把 O2OA 的完整流程审批模块(x_processplatform_*)与首页门户
(x_component_Homepage 依赖的 x_cms / x_hotpic / x_meeting / x_calendar /
x_file 五个后端)用 Python 重写,前端复用 sub2api 的 Vue3 设计体系
(组件、配色、暗色模式、表格与弹窗规范),组成一套可以独立运行的 OA 系统。
- 后端:FastAPI + SQLAlchemy 2 + PyMySQL,接口前缀
/api/v1,统一响应体{code, message, data} - 前端:Vue 3 + TypeScript + Vite + Tailwind + vue-i18n,构建产物由后端直接托管
- 数据库:MySQL 8(默认
192.168.124.202:3306/unis_oa),启动时自动建表并写入种子数据; 建库只认[database] create_allowlist点名的库名,一个环境一个库 - 单端口访问:
pnpm build之后只需访问 http://127.0.0.1:8000,前后端同源
目录结构
unisoa/
├── backend/
│ ├── app/
│ │ ├── main.py # 应用装配、建表与种子、定时调度、前端静态托管
│ │ ├── config.py # 配置入口:按 OA_ENV 挑 config.<环境>.toml,叠在 config.toml 上
│ │ ├── dbconfig.py # 运行配置注册表:取值分层、中文说明、校验、存库即生效
│ │ ├── llmconfig.py # 大模型接入目录:5 种报文协议 + 24 家服务商预设、地址/模型/密钥清洗
│ │ ├── cors.py # 现读现判的跨域中间件(改了来源不用重启)
│ │ ├── db.py # engine / SessionLocal / 建库建表
│ │ ├── models.py # 41 张 oa_* 表 + users,对应 O2OA 实体(含大模型接入 oa_ai_provider)
│ │ ├── storageconfig.py # 文件存放位置:按配置指纹重建客户端 + 密钥掩码
│ │ ├── schemas.py # 入参模型(camelCase -> snake_case)
│ │ ├── serializers.py # 出参(snake_case)与分页封装
│ │ ├── deps.py # 鉴权、“当前身份”、权限点与数据范围
│ │ ├── permissions.py # 权限码目录、内置角色、数据范围展开
│ │ ├── query.py # 查询参数归一化(三态布尔)
│ │ ├── envelope.py # 统一响应与异常
│ │ ├── 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 完全一致,
接口和老数据还认它),但界面上没有入口,也不再由流程设计器读写。
为了不必先知道"标题规则藏在哪",表单设计器把它摆在明面上:
- 表单设计器工具栏常驻一只「标题规则」按钮,徽章写着当前口径(默认 / 模板 / 表达式); 点它 = 选中画布里那格「流程标题」并把规则面板摊开,表单里还没有那一格时先替你加上;
- 画布那一格把口径写在格子上:
模板角标 +· {部门}-{发起人}-{流程名称},不点进去也看得出; - 字段库里的「流程标题」独占一行并带「规则」标记,加字段时就知道它带着规则;
- 规则面板是一块默认展开的高亮卡片,标题行写着生成方式与模板原文,收起来也不丢口径;
- 流程上真带着一条历史遗留的规则(接口或旧版本写的)时,面板会当场用琥珀色提醒它盖住了 这一格,不再把人指向一个已经不存在的入口。
生效顺序是:
- 流程上带着旧规则(
oa_process.title_config.mode != default)→ 仍用流程那条;这种数据 只能来自接口或旧版本,界面上已无处可配,新配的规则不会走到这一步; - 流程没配 → 用字段自带的那条,配在表单上的好处是规则跟着表单走, 同一张表单挂到别的流程上不用重配;
- 两条都没有 → 老口径(表单里的
title/subject/name,否则「某某的XX流程」), 没写过titleRule的老表单与老流程行为一字不差。
设计器手上那份还没保存的草稿永远优先,改哪儿预览哪儿。两处设计器都看得见是谁在生效:
流程设计器在流程那条是「默认」而表单带了一条时,标签页里会写明「此刻沿用的是表单里『XX』的那条」;
表单设计器在流程另配了一条时,会提示这里配的会被盖掉。预览结果里的 source
(draft / process / field / default)说的就是这件事。
标题永远得有一句:模板大括号没配对、变量名不存在、表达式跑挂,都退回默认口径并把原因
留在预览的 error 里,不会为了一句标题把整张单卡住;但保存时先挡一道
(TITLE_RULE_INVALID),设计器改坏模板当场红框,不用等发起人发起才发现。
maxLength(默认 120,上限 300)负责压掉换行与截断,emptyText 是「算出来是空」时
的最后兜底。变量清单与实时预览走两个接口:GET /process/processes/{id}/title/variables
(变量 + 表单样例值)、POST /job/title/preview(设计器 use_sample: true 用样例补空,
发起页按当前填的内容算)。规则配在表单上时还有表单作用域的同款两个接口:
POST /process/form-title/variables、POST /process/form-title/preview,请求体是
{form, name, fields}——form 是已保存表单的 id(新建还没保存留空),fields 是设计器画布上
那份还没保存的字段清单,于是新建的表单、刚拖进来还没保存的字段也都当场能点变量、能预览;
{流程名称} 依次借所属流程的名字、画布上这个表单名、库里那张表单的名字顶上。
两个设计器都只读这几个接口,不自己拼变量表。
标题是随表单实时走的,不是发起那一刻算完就定死。 三个地方都在改完那一下当场换一句
(composables/useAutoTitle.ts 一份实现,三处共用;口径仍是 service/titles.py):
- 发起页:表单里那一格随填随改,公式、带出、级联算完的值都算得进来;
- 表单设计器的「预览」页:填两个字段就能看到规则跟着动,配完不必先保存再发起一张测试单。 这一份用的是画布上还没保存的规则与字段清单,改哪儿预览哪儿;
- 办理页:后面那一环改了表单字段、而规则又开了「自动重算」时,标题框下面写一句 「提交后会更新为 …」——只说,不写回。提交之前那一句还是上一个环节的,改了字段就当场改口 会让人以为已经改了。
三处守的是同三条分寸:只覆盖系统自己写的那一句(字段里是人亲手写的就原样留着,
规则收了修改权限时反过来——那一格归规则说了算);没人动过的标题格在问后端之前先从数据里
摘掉(否则规则再怎么改,后端念回来的都是上一轮那句老的,标题从此不再跟着表单走);
防抖 + 迟到不回写(一路打字只问一次,回来的答案只配给当下这份数据)。
办理页那一句走 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(与 Tailwindlg同一条断点、底部要让出的高度)、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 + 更多 + 翻页)、TaskPanelNewsPanelMeetingPanelSchedulePanelFilePanel,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 标识符, 给人看的括号写{'{'}…{'}'}
- 文案里的字面大括号要转义:线上跑的是 vue-i18n 运行时版 + JIT 现编(
自检
仓库里不留测试代码: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与一批安全内置函数 (lenintminsumcontainsdays_betweennow…),表单字段还会作为裸变量直接可用, 因此条件里写days > 3、amount >= 5000即可;保存时由expressions.validate_script校验 sql/schema.sql由python3 backend/scripts/dump_schema.py从实库导出,改了models.py之后重新跑一次; 忘了跑会被python3 backend/scripts/check_schema_snapshot.py拦下——生产库交给 DBA 手工建表时,快照落后一列 就是新库第一次登录报Unknown column,而本机测试库早被启动补列修好了,只有快照对账查得出来