71 KiB
UnisOA 架构与接口参考
面向二次开发的详细说明。上手运行请看 ../README.md。
1. 请求生命周期
浏览器 ── axios ──► /api/v1/...
│
├─ envelope 统一响应 {code, message, data}
├─ bearer_token → decode_token → current_user
│ └─ 认人只用登录账号 → CurrentUser.ref(X-Identity 那套已下线)
├─ api/*.py 参数与权限
└─ engine/engine.py 变更 oa_* 运行态并写 WorkLog / Notification
- 所有列表接口返回
{items, total, page, page_size, pages} - 业务错误统一走
envelope.bad_request / not_found / forbidden / unauthorized, HTTP 状态码与code一致,前端utils/oa.errorMessage直接取message - 出参一律 snake_case,入参由
schemas.CamelModel接受 camelCase
1.1 配置取值分层
app/dbconfig.py 是唯一入口,55 项运行配置(站点 / 令牌 / 统一身份 / 同步 / 存储 / 跨域)
按固定顺序取:
环境变量 OA_* > 数据库 oa_system_setting 的 config:{组} 行 > config.<环境名>.toml > config.toml > 代码默认值
- 每项都带来源标记(
env/database/file/default),接口和设置页都直接说这一项 是谁给的;被环境变量设了值的项标env_locked,界面上禁用并写明变量名 - 配置文件里的值不入库:
prepare()启动时只读一遍做统计,界面上保存过什么,config:*行里才有什么,而且是逐键存;值传null就是删掉那一键、回到出厂值 - 免重启:进程内快照默认缓存 2 秒(
OA_CONFIG_CACHE_SECONDS),本进程保存后立刻失效; CORS 由app/cors.py:LiveCORSMiddleware每个请求现读,存储客户端按配置指纹重建, Hub 配置按revision现拼 - 只有 13 项引导配置留在配置文件里(MySQL 地址账号、监听端口、JWT 密钥、初始超管、
是否种演示数据)—— 连上库之前就得知道的东西,界面上只读、改了要重启。这 13 项各环境
必然不同,所以实际写在
config.<环境名>.toml里,公共的config.toml只放各环境一致的值 - 配置文件按
OA_ENV分档:app/config.py读config.toml再叠config.<环境名>.toml(深合并,只覆盖写到的键),本机不设就是dev档;OA_CONFIG=<文件>时只读那一个文件。 生产档启动做上线体检(占位密钥 / 演示数据没关 / 空口令点名),每项出厂值还带file_layer说明来自基础文件还是本环境文件 - 容器里多一个配置目录:镜像只带不含密钥的
config.toml(config.*.toml被.dockerignore挡在镜像外),运行时把运维那份挂进OA_CONFIG_DIR=/etc/unisoa, 顺序是「镜像内基础值 → 挂载目录基础值 → 挂载目录本档文件」。档位仍由OA_ENV决定,没有环境变量时认挂载config.toml里的[env] name,同一镜像测试生产通用 (见 README「用 Docker 部署」) - 档位可自查:
scripts/what_config.py只按环境变量算出"读的是哪几份文件、哪一项来自 哪一份",不连库不起服务,发版流程里当确认用;--check有告警时退出码 1,scripts/prod-api.sh用OA_STRICT_CONFIG=1就能拦住没配好的上线 - 老版本的
hub/site/runtime三个整包键由migrate_legacy()在首次启动时逐项并进 对应的config:*行后删除
app/config.py:settings 是个活对象:__getattr__ 直接转 dbconfig.value(),
所以老调用点(settings.site_name、settings.hub_base_url、settings.access_token_minutes…)
不用改就跟着变热。
2. 数据模型
设计与运行分离,共 60 张表:用户表叫 users,其余沿用 oa_* 前缀(结构见
../sql/schema.sql,由 python3 backend/scripts/dump_schema.py 从实库导出)。
组织与权限 users oa_unit oa_role oa_group oa_agent oa_handover
oa_auth_role oa_person_auth_role
用户表 users:id / account(唯一 uk_users_account)/ email / password_hash /
display_name / avatar_url / organization_id(外键指向 oa_unit,部门删掉即置空)/
role(默认 member,admin 为超级管理员)/ status(1=active, 0=disabled, 2=pending, 3=rejected,登录只放行 1)/ last_login_at / created_at / updated_at(datetime(3),
由 MySQL 维护默认值与 ON UPDATE)。索引:uk_users_account、idx_users_email、idx_users_status。
统一身份(Hub)另加三列镜像:source(local 本地建号,同步永不触碰 / hub 同步来的号)、
hub_user_id(Hub 侧主键)、hub_synced_at(最后一次同步时间),部门表对应的镜像列是
oa_unit.hub_org_id。部门名与部门路径不落库,由 organization_id 关联 oa_unit 派生成
organization_name / organization_path。
部门表 oa_unit:列名同样对齐 Hub 导出的组织节点——code(组织编码,对应导出的
code)/ name / status(1=启用,其余为停用/待审核,与 users.status 同一套数字,
取代原来的 enabled 布尔列)/ hub_org_id(导出的 organization_id,本地自建部门为
NULL,同步永不接管)。path / distinguished_name 仍是 O2OA 口径(部门全路径 + DN),
Hub 那套按 id 拼的 /1/2/ 路径与 member_count 不落库。
字段命名:users / oa_unit 的列名就是接口字段名,人员对象出入参一律用
display_name / avatar_url / organization_id / status,部门用 code / status,
不再有 name / avatar / unit_id / enabled 这套旧名;流程表里的
unit_name / unit_path 是它们自己的列(建单那一刻的部门快照),不跟着改名。
待办行上有两个部门,别混:oa_task.unit_name 是本环节处理人的部门(建待办时按
处理人的 org ref 抄,转一次手就跟着换一次),oa_task.creator_unit_name 才是发起人的
部门(建待办时抄自 oa_work.creator_unit_name,与 design_snapshot 同一种快照口径)。
「待办」列表「发起人」那一格读的是后者——2026-11-13 那次把审批人的部门戴到了发起人头上,
就是因为它读了前者。已办侧只有前者:那一格画的本来就是经办人。判据:
backend/scripts/check_todo_starter_unit.py。
待阅行上有两个人,也别混:oa_read.creator_person / creator_unit_name 是这张单的
发起人与其部门(建待阅时抄自 oa_work[.completed],快照口径同上),oa_read.sender 说的是
「谁把这一条递到我手上」——手工抄送 / 分享 / 转发 / 批注 @ 我时是操作人本人,环节上配的自动
抄送规则触发时是当次经手人(engine.create_reads 里 actor.person_name if actor else creator_person)。所以归档抄送的 sender 就是最后一环的审批人,它从来不是发起人;
2026-11-17 那次统一待办「发起人」那一整列画成最后一个审批人,就是因为待阅行没有前者、
界面只能拿后者顶上。oa_read_completed 同名两列由 mark_read / _finish_work 整行搬过去。
判据:backend/scripts/check_read_starter_snapshot.py;存量回填:
sql/upgrade/20261117_read_creator_snapshot.sql。
状态与列宽:users.status 和 oa_unit.status 是同一套数字(0 停用 / 1 正常 /
2 待审核 / 3 已拒绝,models.UserStatus、models.UnitStatus),列上带注释,四态在
人员列表、组织树、审批人解析、设计器审批人目录里都按这一个口径出。列宽(account 190、
display_name 100、oa_unit.code 190、name 255、path 与各类 DN 512)由写入口
(统一身份同步、人员/部门录入)负责裁或拒绝,别让 MySQL 在写库那一刻报错。
主键类型:users.id 与 oa_unit.id 是 BIGINT UNSIGNED AUTO_INCREMENT;O2OA 那套流程表
保留 32 位十六进制主键,其 person / creator / owner_person 等列存的是用户 id 的字符串形式,
所以按主键取人之前要先 models.as_id() 转一次。老库升级用
python3 backend/scripts/migrate_to_users_table.py(先 --dry-run,会把老表导出到
sql/backup/ 再重建)。
角色与群组没有中间表,成员直接存在 JSON 列里:oa_role.list_auth、
oa_group.list_identity、oa_group.list_person。同一个人可以同时挂进多处岗位与分组,
这就是本平台里"一个人几个身份"的全部含义(O2OA 那张一人多身份的档案表已整张下线,
见下段)。反过来那一问——这个人挂在几处——由 org.memberships_for 批量答,人员管理页
那一列「岗位角色」读的是 GET /org/persons/roles:成员值就是本人账号的算直挂名,绕经部门 /
别的岗位名进来的标出来路,认不出的字符串不算成任何人的岗位(与引擎"认不出的人不派活"
同一个门)。分组那两列成员后端按并集读,界面上并成一个名单编辑,保存统一落回
list_identity(值不丢,只是并成一列存)。口径由 backend/scripts/check_memberships.py 钉住。
库里"是谁"的那串字符串是登录账号(users.account,唯一键 uk_users_account):
待办、已办、权限判定、表单里的选人格子全部按账号匹配,口径见
person-reference-design.md。O2OA 那套 DN 串
公司\部门\姓名\身份名(如 优尼森科技\研发中心\张三\zhangsan)只剩展示与打印在用,
由 users + oa_unit 现算;那张"一人多身份"的 oa_identity 档案表已在 2026-10 整张下线。
设计态 oa_category oa_form oa_process oa_activity oa_route oa_script oa_process_version oa_process_snapshot(最后一张是单据发起那一刻冻下的设计:oa_work / oa_task / oa_task_completed / oa_work_completed 各带一列 design_snapshot 指回它,在途与已归档的都认自己那一版,见 README「改流程、改表单,不会拽动已经在路上的单子」)
运行态 oa_work oa_task oa_work_completed oa_task_completed
oa_work_log oa_read oa_read_completed oa_draft oa_attachment
oa_serial_number oa_notification oa_operation_log oa_system_setting
oa_refresh_token
流程办结时,oa_work / oa_task 的活动行会迁入 oa_work_completed /
oa_task_completed(oa_task 清空、oa_task_completed 保留全部环节),
与 O2OA 的 Work → WorkCompleted 行为一致。因此“活动表为空”不代表没有历史数据。
门户态 oa_cms_channel oa_cms_document oa_cms_attachment oa_meeting
oa_meeting_attendee oa_schedule oa_file
对应 O2OA 首页依赖的五个后端模块。可见性一律按人员引用判定:归属人命中
owner / owner_person,或 shared_identities 这个 JSON 数组里含当前账号(口径见
person-reference-design.md)。JSON 匹配统一走
func.json_contains(col, json_string(value)),其中 json_string 会做真正的 JSON 编码——
值里带反斜杠或引号时,手工拼 "..." 会被 MySQL 判成非法转义(错误 3141)。
文件本身不进库,库里只存 uri:minio://<bucket>/<key> 或 local://<相对路径>;
不带 scheme 的裸值是历史数据,读取时回退到本地目录。oa_attachment 存表单附件,
oa_cms_attachment 存信息资讯的附件(oa_cms_document.body_attachment 指向其中一条时,
这份附件就是正文),oa_file 存「网盘」页的上传记录,oa_cms_document.cover 存信息资讯的
封面。三类文件各有固定落点:附件与信息资讯走 MinIO,网盘走本地磁盘。
对象删不掉时 uri 进 oa_storage_pending_delete 等补删,删之前也会先确认没有别的表还在引用
同一份字节,规则见 app/service/storage_gc.py。MinIO 的地址、账号、密码与上传路径
是 storage 组的运行配置,出厂值在当前环境配置文件的 [storage.minio]
(本机是 backend/config.dev.toml,生产是 config.prod.toml),
界面上保存后进数据库(PUT /config/storage → oa_system_setting 的 config:storage 行),
改完按配置指纹重建客户端,立刻生效不用重启,见
../README.md 的《文件存放位置》。
MinioStore 的对象键一律过一遍 MinioConfig.key(),所以 upload_path(别名 prefix)
对写入真正生效,uri_for() 与 save() 算出来的是同一个位置——两者以前不一致时,
seed 的「已存在就跳过」永远判不中,每轮启动都把同一批封面重复上传一遍。
2.1 权限与数据范围
oa_auth_role 存角色(permissions JSON 数组 + data_scope + builtin),
oa_person_auth_role 是人员与角色的多对多中间表(复合主键 + 级联外键)。这一对和
oa_role(岗位角色,供流程候选人生成用)是两回事,别混用:权限角色回答“这个人能用哪些菜单、
能看哪些数据”,成员是人员;岗位角色回答“这类事该谁做”,成员是一批身份,流程环节按角色名解析。
前端菜单里是两条入口(系统管理 → 权限角色 / 组织管理 → 岗位角色),审批人只认后者。
app/permissions.py 是权限码的唯一定义处:resolve_grant()(resolve() 是它的口径字符串壳)
把一个人的多个角色合成「权限码集合 + 一份数据授权」,clean_codes() / clean_scope() /
clean_unit_ids() 负责入口校验,scope_unit_ids() / scope_person_ids() /
scope_identity_values() 把范围展开成可比较的 id 与登录账号,in_scope_clause() 与 scoped()
把它拼成 SQL 条件。
data_scope 五档:self(本人账号)、unit(本部门)、unit_and_below(本部门及下级)、
custom(角色上勾的部门,见 oa_auth_role.data_unit_ids)、all(不加工条件)。
scope 那一个字符串只够展示与对外播报,过滤靠 DataGrant:本部门口径、自定义部门集合、
要不要带上本人、按部门圈人还是只看本人,四块各自独立。多角色走 merge_grant() 求并集
(不是取最宽),统一身份权限那一层叠上来时同理——合并模式并进来、覆盖模式整份作废,
入口是 CurrentUser.apply_scope()。
新增一列 oa_auth_role.data_unit_ids 时踩到的坑记在这儿:ensure_columns() 给不能写
DEFAULT 的 JSON 列回填时,default=list 是 callable 默认值、is_scalar 为 False,
按名字猜形状会把新加的 JsonList 列统统回填成 {};现在直接认 list / dict 两个内置函数。
接口层遵守一条硬规矩:每个接口要么挂 require_permission("…"),要么至少 Depends(current_user)
(本人数据类接口靠登录态 + service 层的所有权判断收敛),完全匿名的接口只能写进
scripts/check_route_guards.py 的白名单。这条规矩由脚本直接扫 app.main.app.routes 校验,
不靠人记:python3 scripts/check_route_guards.py。
唯一的例外是选人用的精简目录 GET /org/persons/simple:发起流程填「选人」字段、转办、待办
交接、会议邀请都要跨部门找人,所以它只要求登录、不受数据范围裁剪,但只回 id / 账号 / 姓名 /
部门名 / 身份 DN 这几样,等同于组织架构图上本来就看得见信息;带完整属性的人员管理列表
(GET /org/persons)仍然要 org:person 并按 data_scope 过滤。
三处容易踩的地方,改动这段代码时务必留意:
- 部门前缀匹配靠
oa_unit.path做LIKE '前缀%',而 MySQL 的LIKE默认转义符恰好就是\,path 里的反斜杠必须成对翻倍,否则unit_and_below会一条都匹配不上(这个 bug 是 接数据范围时挖出来的,此前只影响“下级部门”这类查询)。翻倍逻辑收在service/org.py的path_prefix_pattern(),不要退回手写f"{path}\%"。 - JSON 列一律用
models.JsonDict/models.JsonList(MutableDict/MutableList包装过的JSON)。新加 JSON 列也要用它们,否则原地append不被 SQLAlchemy 跟踪,改动静默丢失。 api/org.py的POST /org/units早先只flush()不commit(),新建部门在请求结束时被 回滚掉(接口返回成功、库里没有)。现在写操作统一提交,新增写接口时别只flush。
3. 流程定义
一条流程 = 1 个 oa_process + N 个 oa_activity + N 个 oa_route,
整体通过 PUT /process/processes/{id}/design 原子保存,发布前用
POST /process/processes/{id}/validate 做静态校验。
3.1 环节类型
type |
说明 | 关键 config |
|---|---|---|
begin |
开始,自动流转到下一环节 | form(可选,随流程默认表单) |
manual |
人工审批,产生待办 | mode taskValues taskScript first allowGoBack allowAddTask allowTerminate goBackConfig expireType expireValue emptyToCreator processingTaskOnceUnderSamePerson beforeArriveScript afterArriveScript |
choice |
条件分支,按路由表达式择一 | 无,逻辑在路由的 expression 上 |
parallel |
并行网关,多路同时下发 | 无 |
merge |
汇聚网关,等待前序全部到达 | 无 |
split |
数据拆分,按数组扇出子待办 | dataPath |
script |
脚本环节,改写表单数据 | script |
invoke |
服务调用 | method url headers data timeout resultPath |
embed |
子流程 | process title |
delay |
延时等待 | minutes |
end |
结束,触发办结与归档 | 无 |
cancel |
取消流程 | 无 |
manual.mode:any 或签(任一人办理即通过,其余同环节待办以 processing_type=auto
自动办结)、all 会签(全部办理才流转)、join 汇聚式办理。
3.2 处理人 taskValues
taskValues 是 [{type, data, containsSub}] 数组,多项结果取并集去重。
identity / person / role / group / post 都走同一个名字解析器
org.resolve_identity_names,它按 登录账号 → 人员姓名 → 部门 path 或名称 → 角色名 →
群组名 的顺序尝试,认不出的那一条直接丢掉——一串对不上账号的字符串不是一个人,
不能当成一个审批人发出去。要把"认不出"报出去请用 org.split_selectors。
type |
data 含义 |
|---|---|
identity |
登录账号 |
person |
人员姓名/账号 |
role |
角色名,如 部门负责人 |
group |
群组名 |
unit |
部门名或部门 path,配 containsSub 决定是否含下级 |
creator |
流程发起人(data 留空) |
prev |
上一环节处理人 |
prevunit |
上一环节处理人所在部门 |
form |
从表单字段读取人名/账号,data 为字段路径,支持 a.b 与 a[].b |
taskScript 在上述结果之上追加,返回登录账号列表(认不出的值不派工),可读取 data、work、user。
同一份换算有两套出口,共用 org.resolve_selector_row,不会各算各的:
- 引擎侧
org.resolve_task_identities只交认得出的人:认不出的值不进审批人清单,环节按配好的 空审批人兜底(emptyApprover)收场,不会给一个不存在的人派待办 - 设计器侧
org.preview_selectors严格:认不出的值进unknown,配合org.approver_directory(岗位角色 / 分组 / 部门 + 各自解析后的成员)在保存前就告诉设计者“这个角色现在是谁、有没有写错”
unit 的名字解析对结尾分隔符不敏感(优尼森科技\研发中心 与 研发中心 都能命中),
设计器的部门选项存的是去掉结尾 \ 的完整 path,同名部门也不会撞车。
3.3 路由与表达式
oa_route 描述一条出线:from_activity → to_activity,name 是待办上的按钮文案,
alias 为别名,expression 在 choice 出线上必填;decision 置为 goBack 时这条线
按退回处理(等价于走 go_back,回到 goBackConfig 指定的环节),也可以在环节的
config.routeDecisions 里按路由名批量声明。
同名出线是允许的,而且多数时候本来就该同名(分支上的同一个动作不必叫成
「同意-大额」「同意-常规」):同一环节上的几条同名出线在待办上就是同一个按钮,
审批人只按一次,引擎在这些同名出线里取第一条 expression 成立的,都不成立再走那条
没写条件的——与 choice 选路共用 engine._route_by_condition,不会出现两套规则。
于是校验只拦两种真会出事的写法:同名出线语义不一致(一条 agree 一条 goBack,
这张票算哪一票说不清),或同名出线全没写条件、走的时候分不出该走哪条。
parallel / split 的出线条条都要走,引擎不在它们之间挑,因而不受这两条约束。
调用方若要点定某一条而不交给引擎按条件挑,routeName 直接传那条出线的 id。
表达式由 engine/expressions.py 求值:先做 AST 语法节点白名单校验,再过滤
__class__ __globals__ 等双下划线属性与 _BLOCKED_NAMES,运行期只注入
_SAFE_FUNCTIONS(len int float str min max sum round sorted
any all contains startswith upper today now days_between get …)
以及 data / form / work / user / context。表单顶层字段会平铺为裸变量,
所以 days > 3、amount >= 5000 可直接书写。保存时 validate_script 会返回错误文案。
3.4 退回配置
{"type": "prev", "data": "", "way": "step"}
type:prev退回上一环节,define退回data指定的环节way:step逐步回退(回到被退回环节重新办理),jump直接跳转allowGoBack=false时前端不出现退回按钮,后端goback直接拒绝allowTerminate管的是发起人那颗「终止」钮:单据正停在这一环时它为false,界面不出现按钮、 引擎terminate同样拒绝(与allowGoBack一个待遇)。发起人能不能终止还有一层流程级的规矩 (开关 + 四个时间窗口 + 终止那一刻的写回),存oa_process.terminate_config,见 README「流程终止」GET /task/{id}/goback-targets给出当前可选的退回目标,回行带is_starter
「退回发起人」不在 goBackConfig 的管辖之内:type 收窄的是能退回到哪几个审批环节,
开始环节(发起人)永远挂在候选最后,prev 也只把审批环节收到上一环。退到开始环节后,
_arrive_manual 不走审批人解析、免审与去重,直接给提交人派一条 activity_type=begin 的待办;
他改完表单重新提交,单子照旧从开始环节那条出口往下走(jump 那条「直返本环节」的约定照样生效)。
两种情况不给这个落点:嵌入子流程是引擎替父单开的、没有当场提交的人;
creator_identity 空了(组织数据被清过)也不能派一条没人办得动的待办。
回头线(goBack / reject)与图遍历口径
出口路由的 decision 里,goBack 与 reject 是「往回走」的那两种语义,词表只有
一份:engine/definition.py::BACK_DECISIONS(环节上的 routeDecisions 覆盖同样算,
判定入口是 definition.is_back_route)。凡是回答「我前面还有哪些环节」「往前走
能到哪」的遍历都必须绕开它们——那种边把下游连回上游,照它走下去,一张图上只要有
一条驳回线,被它连回来的那个环节后面的整条下游就都成了"上游"。
踩过的实单:费用报销画了「财务经理 --驳回(reject)--> 发起人」,部门主管点退回,
goback_candidates 把刚到达过的财务经理算成上一环节,单子被推到下一步,审批记录
末尾于是写着「停在「财务经理」,等待 张梅 处理」。走图不绕回头线的地方一共有五处,
口径统一在 definition 这一侧:
definition.upstream_ids(退回候选的唯一筛子,engine.upstream_activities只是转发)definition.downstream_ids(撤回已办要收回的那一段,engine.downstream_activities)definition.forward_routes→engine._first_merge(并联/拆分配对汇聚环)engine.lookahead._routes(「后面还要他批吗」,免审与去重靠它)service/simulator.py::_forward(设计器试跑预测,口径与上一条一致)
设计期也要说清楚,否则画布上看着像退回、运行时是一次审批通过(算一票同意、触发
「本环节审批通过后」的写回与排号、也不收回后面已派的待办)。definition.validate
有两条:闭了环却没标 decision 的那条线,以及标了 goBack 却把线画到自己前面去的
(退回的执行取候选环节或 goBackTarget,那条线的终点运行时走不到)。设计器侧
utils/flowGraph.ts::backRouteIssues 是同一套话术的镜像,红点与后端发布校验对得上。
reject 管的只是图怎么读(它不该被当成往前走完的一段),不改这一点下去发生什么:
标成 reject 的那条线仍然是一次普通流转——照常记一条 normal 已办、在按比例会签里
算一票(_ratio_votes 只把 goBack 排除)、也会被卡住的写回与提交闸门拦下(
going_back 同样只认 goBack)。要的是「打回重做」那一整套(收回本分支后面的在途待办
与 token、不留同意票、不触发「本环节审批通过后」、写一条 goBack 留痕),标 goBack。
回归:python3 scripts/check_goback_upstream.py(真跑一遍发起→审批→撤回→退回,
钉住落点必须在前面)、python3 scripts/check_process_cycles.py(一份口径、设计期
两条校验、网关配对不被带偏,并把库里每一条流程的每一个人工环节扫一遍)。
3.5 计算公式与实时预览
type=formula 的字段的值不由人填,由表达式算:
- 服务端是唯一口径:
service/formruntime.py的compute_formulas()在每次发起、 提交、干预后按当时的data重算,逐条覆盖,所以后面的公式能引用前面刚算出来的值; 单条算错只把那一格留空并记进data._formulaErrors,不卡流程。设计保存时design.py的formula_cycle_problems()拦循环引用 - 前端只是预览:
utils/formRuntime.ts的compileFormula()把设计器里那份 Python 风味表达式翻成受限 JS(data.get('x')/data['x']/ 裸字段名 → 沙箱取值,orandnotis notNone→ JS 写法,A if C else B→ 三元,floatintroundlensumtotalcountrowsgetmoney_cndays_between等 → 与_SAFE_FUNCTIONS同口径的助手),再在只拿得到 表单数据和助手的沙箱里执行,不碰全局对象 - 翻不了就不猜:下标、
in、推导式、lambda、属性访问、多个三元等 写法一律code=null,界面显示「这条公式预览算不了,提交时由服务端计算」, 而不是给一个看着像样的错数(旧版把未知字段当 0 就是这个问题) - 展示口径:算得出的一律显示实时值,前面一个绿点(
formulaIsLive); 依赖还没填齐不再补「还差:字段名」那一行——没填就是 0,那行小字只是噪音, 只有预览翻不了的写法(formulaPreviewBlocked)才提示「以服务端为准」; 数字怎么写由字段自己配(numberFormat:自动千分位 / 原样数字 / 固定小数位 / 货币), 配了uppercase再带一行中文大写;鼠标停上去是「公式 / 当前取值 / 结果」; 数一变闪一下(.formula-pulse)。只读视图(审批详情、打印)显示存下来的值,不带绿点 - 明细表的「本行公式」只有前端会算:列上写
formula后这一格变成只读, 由applyRowFormulas()在每次增删改行后重算,跑两轮好让total(本明细, 列名)这种跨行写法看到新算的值;这类写法在设计器校验里就必须能预览通过。 公式能引用的东西就是喂进沙箱的那份数据:本行的各列(列标识裸写或data.get('列'))、 主表的字段(第三参formData,与列同名的以本行的值为准)、以及这张明细表自己 (total(明细标识, 列名))。主表那一格(手填的、公式算的、外部带回的)一变,FormRenderer按rowFormulaSignal把带公式列的表整表重算,算完跟原来一样就不写回; 本行公式引用主表公式字段、那个公式字段又合计这一列时两边会互相追着涨, 所以连追 8 轮还没稳住就停下来。服务端不重算这一列,接口直接提交的报文得自带算好的数 - 口径由
src/utils/__tests__/formFormula.spec.ts(含线上费用报销单那三条公式)、src/utils/__tests__/formNumberFormat.spec.ts(四种数字写法与系统带出字段的必填判定) 与src/components/oa/__tests__/FormRendererFormula.spec.ts(改数即变、写回 model、 缺依赖不啰嗦、预览算不了才提示、只读态取存量)守住, 本行公式那一层由src/utils/formRuntime.rowFormula.spec.ts(能吃谁、同名谁说了算)与src/components/oa/FormRenderer.rowFormula.spec.ts(主表一变整表跟着变、只读态不动数据、 配成环也停得下来)守住
4. 流转算法
engine._advance() 是一个“到达循环”:沿着路由离开当前环节,然后不断尝试
_arrive(),直到出现三种停机条件之一——产生了人工待办(工作 park)、
命中 end/cancel(办结)、或没有可用出线。
关键点:
- token 记账。
oa_work.tokens保存并行分支状态(engine/tickets.py),parallel出网关时为每条出线复制 token,merge入网关按前序计数聚合, 计数未满则本轮不产生待办。退回与撤销通过tickets的 reset/prefix 收敛, 避免“半个分支还活着”。 - 表单作用域。
oa_task.form决定该环节可见与可写的表单;取值为activity.form or work.form,因此环节未单独绑定时沿用流程的latest_form, 设计器里表现为“使用表单:无 · 沿用流程默认表单”。 - 同代人合并。
processingTaskOnceUnderSamePerson打开时,若下一环节处理人与 刚办理的人是同一个账号,则自动以auto类型办结并继续流转(自己审批自己)。 - 空处理人兜底。
emptyToCreator=true时若解析不出处理人,交回发起人; 否则按流程异常终止并写oa_work_log。 - 留痕。
oa_work_log是“到达轨迹”,每次进入一个新环节写一行,type取create(发起)、normal(人工办理后流转)、auto(同人自动办结)、parallel/split(并行与拆分下发)、merge(汇聚)、goBack(退回)、reset(撤销转办回滚)、embed(进入子流程)、delay(延时唤醒); 前端不再单开一个「流转轨迹」页签:utils/approvalRecord.ts把这份日志与审批记录、 批注并成一条时间线,ApprovalRecord.vue里这些没有审批步骤对应的引擎事件(网关 / 脚本 / 子流程 / 撤回 / 办结)默认就一起排进来(2026-11 改的:收起来等于让看图的人 自己脑补这一单怎么走的),那颗「全部事件」钮反过来只用来收起这些事件、只留审批步骤,MobileFlow同一口径。create那条说的是「谁提交了这张单」,它不当引擎事件排,而是由startOfWork(detail)拼成时间线开头那一行发起(发起人、部门、提交时间,标题认开始环节当时的名字): 发起不是一次审批,所以它不占序号,「共 N 步」仍然只数审批过与被跳过的环节。 其余干预操作各有落点:加签与转办体现在新生成的oa_task与oa_task_completed.act(create/add)以及empower_from_identity/empower_to_identity, 催办累加oa_task.press_count并发通知,终止把oa_work.status置为terminated后归档;接口级的写操作另记oa_operation_log。 - 编号。
oa_serial_number以YYYYMMDD为键做行锁式自增,得到20260911000003这样的可读编号;job是全流程共享的 32 位 hex,work/task各自独立。
5. 签核与干预语义
| 操作 | 接口 | 语义 |
|---|---|---|
| 办理 | POST /task/{id}/execute |
校验路由属于该环节、按需写回表单,再走 _advance |
| 退回 | POST /task/{id}/goback |
依 goBackConfig 回到上一/指定环节,生成新待办并通知 |
| 加签 | POST /task/{id}/addtask |
before 前加签(先由他人办)、after 后加签、together 并加签;原待办挂起等待 |
| 转办 | POST /task/{id}/transfer |
待办改派给他人,记录 empower_from_identity / empower_to_identity,转办人可在已办撤销 |
| 撤销转办 | POST /taskcompleted/{id}/reset |
从已办回滚,待办回到原办理人 |
| 已办撤回 | 由已办的 撤回 按钮触发 |
仅当下一环节尚未实际办理时允许,回退到撤回人 |
| 催办 | POST /task/{id}/press |
累加 press_count、更新 press_time、给处理人发通知 |
| 终止 | POST /job/{job}/terminate |
发起人或管理员终止,活动表迁出为 terminated |
| 删除 | POST /job/{job}/delete |
只开给还没发起流转的单(本人创建、还停在开始环节、没有别人的待办或需处理抄送压在上面):连单带号从运行表里抹掉,不归档、界面上再也找不到它;已经流转过的单删不掉,那种单要的是终止。收尾四样:额度还回去、外部表态作废、嵌页面那本「已发起成单」的账收回、给第三方发一句「这张单删了」(参数与删草稿那一条同一个人配的同一份,见 service/embed_session.abandon_on_work_deleted) |
| 管理员介入 | POST /admin/work/{job}/terminate POST /admin/task/{id}/press |
需要 admin 角色 |
| 抄送 / 转发 | POST /read/{id}/view POST /read/{id}/handle POST /read/view POST /read/view/batch POST /task/inbox/seen POST /task/inbox/execute |
2026-11 起「待阅」不再是一屏:这三档(我自己的待办 / 抄送需处理 / 只需阅)并成一张统一待办(取件箱),读模型 service/inbox.py,口径与设计见 todo-inbox-unified-design.md。oa_read 上新加 seen_time(只说「本人打开过」,与 view_time 那个已阅时刻分两格)管这一侧的红点,_refresh_read 把不需处理改成需处理时清它——看过一眼之后这事变成我的,红点要重新亮。/read/* 三条写路径本身没动,只是调用方换成了待办那一屏。以下讲的是进出规则,与摆在哪一屏无关:抄送一律先进待阅档(现在就是待办里那一档):环节自动抄送(到达 / 办完 / 办结)、手工抄送、分享、批注 @ 六个出口都落 oa_read,没有一条直接进已阅档;归档那一刻现抄的与没人打开过的老待阅只补 completed / work_completed 两个标记,行照旧停在 oa_read(oa_read_completed.view_time 是 NOT NULL,搬档等于替人编一个「已阅时间」)。出两档:无需处理的点开单据即转已阅(/read/view 按整件登记),需处理(requires_action)的只能由本人走 handle 填处理意见才算办完(attachments 随意见一起登记),点开单据与单条 view 都顶不掉它;处理确认那一句以本人写的为准,不再被抄送时那句来意占住。/read/view/batch 是同一套判定的批量口子:engine.mark_reads_batch 逐条走 mark_read、一条一个存档点、坏一条只回滚那一条(整批不回滚),没给意见的需处理那几条算跳过不算失败,逐条原因回给界面,一批上限 50。批次之外单列两档:already 是勾到时早已在本人已阅里的那几条(列表页被页签缓存住时的常客,办完了不是办砸了,不混进 failed),truncated 是超过上限被切掉的条数(一条都没碰,不进任何一档,不报出来人以为整批都办了)。那句共用的处理意见与随附文件只跟着「需处理」那几条走:只登记「我看过了」的那几条不吃这句话、也不被盖 handle_time。守卫 scripts/check_read_batch.py(31 项)。加签与转办不产生待阅。办结之后还有一条入口:POST /work/{work_id}/forward(engine.forward_completed)——办结时待办全被收走、cc_task 那条通道走不通,而 share_work 虽认归档件却没有身份闸,于是这一条只服务归档件(在途件挡回「请到待办里抄送」,免得开一条绕过环节「允许抄送」的后门)、只有发起人本人或管理员按得动;来源仍是 cc(不新增枚举),默认不要求处理、可显式要求,一次上限 50 人且宁挡不切。按钮只认详情报文里的 can_forward,而引擎那道闸认两套身份列(creator 行 id 或 creator_identity 账号)任一命中即放行——闸比旗标严会造出「按钮摆出来、一点就报错」,方向上宁宽勿严。守卫 scripts/check_forward_completed.py(32 项,含那条跨层断言:三个角色各读一次旗标再照旗标去转);另两道守卫 scripts/check_cc_entries_to_read.py、scripts/check_read_batch.py |
6. 定时调度
main.py 启动一个 daemon 线程(60 秒一轮):
- 唤醒
oa_work.wake_time到期的delay环节,继续_advance - 依据
expireType(minute/hour/day)+expireValue计算expire_time, 超时后把oa_task.expired置为true,工作台的“超期待办”计数与筛选用它 - 到
OA_HUB_SYNC_TIME(默认凌晨01:00)后从统一身份平台拉一次全量组织人员, 判断口径在service/hub_sync.py:due_now:当天跑成过就不再跑,失败按OA_HUB_SYNC_RETRY_MINUTES/OA_HUB_SYNC_RETRIES补试,每次执行落一行oa_hub_sync_run。开关、字段映射与保护规则见 hub-integration.md
7. 通知
引擎在产生待办、退回、催办、办结、待阅时写 oa_notification;
未读数由 GET /notification/unread/count 提供,前端顶栏轮询。
点击通知按 task 优先跳待办详情,否则按 job 跳流程详情。
8. API 参考
前缀 /api/v1。除标注外均需 Authorization: Bearer <token>。
auth
GET /auth/captcha 免鉴权,登录页验证码(Hub 开启时转发 Hub,本地模式回 required=false)
POST /auth/login 免鉴权,body {account|email, password, captcha_id, captcha_answer};响应 data.via 标明 hub 还是 local
POST /auth/refresh 免鉴权,body {refresh_token}
POST /auth/logout 服务端记录登出
GET /auth/me 当前用户,含 permissions / data_scope / roles / bank_account
PUT /auth/me 修改资料,注意参数走 query
PUT /auth/me/bank-account 个人资料里的开户行与收款账号
POST /auth/password 修改密码
POST /auth/permissions/refresh 重算一遍权限(统一身份权限那层改了口径时用)
hub(统一身份,配置见 hub-integration.md)
GET /hub/status 当前开关/模式/同步时间/凭证来源/上次结果(不含密钥)
GET /hub/config PUT /hub/config 统一身份配置:读 / 保存并立即生效,需要 system:setting
POST /hub/sync 一键同步组织人员,需要 org:person
GET /hub/sync/runs?limit=20 最近 N 次同步记录,需要 org:person
POST /hub/probe 连通性与同步凭证自检,需要 system:setting
GET /hub/directory/preview 只读体检:拉一次全量做对比,不写库
org
GET /tree 组织树(部门 + 人员 + 岗位,按数据范围收敛)
GET /units POST/PUT/DELETE /units/{unit_id}
GET /persons POST/PUT/DELETE /persons/{person_id} 列表按数据范围收敛
GET /persons/simple 轻量人员下拉
GET /roles POST/DELETE /roles/{role_id}
GET /groups POST/DELETE /groups/{group_id}
GET /agents POST/DELETE /agents/{agent_id} 流程代理
GET /handovers 待办交接记录
POST /handovers 发起待办交接
auth-roles(全部需要 org:authrole)
GET /auth-roles/catalog 权限码分组与数据范围(前端渲染矩阵用)
GET /auth-roles 角色列表,含成员与 member_count
POST /auth-roles 新建自定义角色
PUT /auth-roles/{role_id} 改名/描述/数据范围/权限/启停
DELETE /auth-roles/{role_id} 删除(内置角色拒绝)
PUT /auth-roles/{role_id}/members 整体覆盖成员 {person_ids: []}
design(按 design:* 权限点把关)
GET/POST/PUT/DELETE /process/categories[/{id}]
GET/POST /process/forms GET/PUT/DELETE /process/forms/{id}
POST /process/forms/validate
GET/POST /process/processes GET/PUT/DELETE /process/processes/{id}
PUT /process/processes/{id}/design 整体保存环节与路由
POST /process/processes/{id}/validate 静态校验
POST /process/processes/{id}/publish 发布并生成版本
POST /process/processes/{id}/disable 停用
POST /process/processes/{id}/copy 复制流程
GET /process/processes/{id}/versions 版本列表
GET /process/versions/{version_id} 版本快照
POST /process/script/validate 脚本安全校验
GET /process/approvers 岗位角色/分组/部门 + 解析后的成员
POST /process/approvers/preview 按 taskValues 预览会解析到谁
GET/POST /process/scripts
runtime
POST /job 发起流程(body: process, title, data, draft?)
GET /job/{job} 按 job 取概要
PATCH /job/{job} 修改标题/数据(限可编辑范围)
POST /job/{job}/terminate 终止
POST /job/{job}/delete 删掉本人创建、还没发起流转的那张单(判据见 engine.unstarted_delete_reason;同时给对方发一句删掉他们在这一趟里建的东西,见 embed_session.abandon_on_work_deleted)
GET /work/created 我发起的
GET /work/{work_id} 流程详情:接受 work id、task id 或 job
GET /task/processing 我的待办(只 oa_task;keyword/process/category/activity/expired/viewed/work_status/日期/分页)
GET /task/inbox **统一待办**:我自己的待办 + 抄送需处理 + 只需阅,并成一页按送达时间倒序(kind/source/viewed/expired/work_status/日期/分页),每行带 inbox_kind 与 unread(那枚红点)
POST /task/inbox/seen 批量「看过了」:按档位分头盖时间戳(待办 view_time / 抄送 seen_time),只需阅那几条顺手归进已阅;不表态不流转
POST /task/inbox/execute 批量「处理」:待办逐条走出口流转,抄送需处理登记处理意见;没写意见的抄送算 skipped 不算失败
GET /task/processing/count 待办角标(?inbox=true 默认给统一待办的分档数 total/approval/cc_action/cc_read/unread/expired;inbox=false 退回只数 oa_task 的老口径,手机首页卡片与流程监控在用)
GET /task/completed 我的已办(按单折叠:一张单只摆最近那次,带 handle_count)
GET /task/{task_id} 任务详情
POST /task/{task_id}/view 标记已查看
POST /task/{task_id}/execute 办理(route, opinion, data?)
POST /task/{task_id}/goback 退回
POST /task/{task_id}/addtask 加签
POST /task/{task_id}/transfer 转办
POST /task/{task_id}/press 催办
GET /task/{task_id}/goback-targets
GET /read/processing 还在待阅档的抄送(界面上已并入统一待办,这一句留给代理与排查)
GET /read/completed
POST /read/{read_id}/view 标记已读
POST /read/{read_id}/handle 抄送需处理:处理意见 + 可选 attachments,登记进已阅
POST /read/view 点开整件单据:把它上面本人的待阅一并登记(需处理的那几条不动)
POST /read/view/batch 批量登记待阅:ids + 可选 opinion/handling/attachments,逐条成事、上限 50,回条数与逐条原因
POST /work/{work_id}/forward 已办结的单子由发起人转发给若干人:只认归档件 + 发起人/管理员,落待阅(来源仍是 cc),可勾要求处理;一次上限 50 人,超了整批挡下
GET /worklog 流转轨迹
POST /taskcompleted/{id}/reset 撤销转办 / 已办回滚
GET /admin/task/processing 流程监控:数据范围内的全部在办待办
GET /admin/work/list 流程监控:数据范围内的全部流程(在途 + 归档;旧地址 /admin/work/processing 同口径)
POST /admin/work/{job}/terminate
POST /admin/task/{task_id}/press
support
POST /attachment multipart 上传,按 YYYYMM 归档
GET /attachment GET /attachment/{id}/download DELETE /attachment/{id}
GET/POST/PUT/DELETE /draft[/{id}] 草稿箱;POST 的 process 认 id/名称/别名/「分类/流程名」/关键词,带 dryRun 只体检
GET /draft/types 能建草稿的流程类型与各自的参数清单(字段、必填、可选值)
GET /notification POST /notification/{id}/read POST /notification/read/all
GET /notification/unread/count
GET /statistics/workbench 工作台卡片与最近待办
GET /statistics/overview 管理端总览
GET /statistics/process/{id} 单流程统计
GET /settings/public 免鉴权:站点名与 logo(同一份也注进 index.html,见 app/web_shell.py)
GET /config 全部 6 组运行配置:值 + 中文说明 + 范围 + 来源
GET /config/{group} 读一组 PUT /config/{group} 保存一组(存库即生效)
POST /config/reload 丢掉进程内快照立刻重读
GET /settings PUT /settings/{key} 老接口,读写的是同一批 config:* 行
GET /system/info 配置在哪张表、revision、缓存秒数、生效的环境变量、每组存了几项
GET /system/storage 存储落点、探活与密钥掩码
POST /system/storage/test 探一个后端,可带未保存的 MinIO 参数
POST /system/storage/reload 按当前配置重建存储客户端
GET /operation-logs 操作日志
除 /settings/public 外都要登录,读写配置要 system:setting
portal(首页门户)
GET /portal/home?size=6 首页一次拉齐:counts + 各面板默认页 + 可发起流程
GET/POST/PUT/DELETE /cms/channels[/{id}] 栏目(写操作需 admin)
GET /cms/documents channel / keyword / is_hot / mine / status / 分页
GET /cms/documents/{id}?view=1 view=1 时自增浏览量;0 用于编辑回显
POST/PUT/DELETE /cms/documents[/{id}] 发布 / 草稿 / 撤回(需 admin)
POST /cms/documents/{id}/cover GET /cms/documents/{id}/cover
POST /cms/covers 先上传后保存;DELETE /cms/covers?cover= 放掉没保存成的那张
换图 / 删资讯 / 放弃编辑都会回收上一个对象
三条封面接口共用 app.storage 的 portal 用途,
cover 列存 uri(默认 minio://…),
cover_url 是后端拼好的鉴权代理地址
GET /meetings scope=mine|all
GET /meetings/coming?days=31 未来一个月内我参与的会议
GET /meetings/invited?status= 会议邀请(空串=全部状态)
POST /meetings PUT /meetings/{id} DELETE /meetings/{id}(取消)
POST /meetings/{id}/answer {status: accepted|rejected, opinion}
GET /schedules?start=&end= GET /schedules/month?month=YYYY-MM(含 counts)
GET /schedules/day?date=YYYY-MM-DD
POST/PUT/DELETE /schedules[/{id}]
GET /files scope=mine|shared|mine_only
POST /files multipart:file / folder / shared(人员选择器,逗号或分号分隔)
GET /files/{id}/download PUT /files/{id} DELETE /files/{id}
上传固定落本地磁盘(网盘暂不接对象存储),
下载走存储层流式回传并透传 Range,
可见性只认归属人与 shared_identities
组织者建会时会自动写入一条 role=organizer、status=accepted 的参与人,因此新建会议
的 accepted_count 起步为 1;“取消会议”是软删(status=cancelled),
/meetings/coming 会自动过滤。
9. 前端结构
router/index.ts 采用父路由挂 AppLayout(渲染 <RouterView />)+ 子路由的结构,
beforeEach 负责登录拦截、meta.permission 拦截与已登录访问 /login 的回跳。
受控路由都带 meta.permission,无权限时按 FALLBACK_PATHS
(portal:home → work:workbench → work:todo → work:profile)落到第一个有权的页面,
一个都没有就停在 /login。侧栏 AppSidebar.vue 用同一套权限码过滤菜单项,整组都没权限时
连分组标题一起藏掉。
| 路径 | 名称 | 说明 |
|---|---|---|
/login |
login | 登录(meta.public) |
/ |
— | 重定向到 /home |
/home |
portal-home | 首页门户(O2OA 五块面板) |
/workbench |
workbench | 工作台 |
/content/documents |
portal-documents | 信息资讯列表 |
/content/documents/create |
portal-document-edit | 发布 / 编辑信息(portal:manage) |
/content/documents/:id |
portal-document-detail | 信息详情 |
/content/meetings |
portal-meetings | 我的会议 / 会议邀请 |
/content/schedules |
portal-schedules | 我的日程(月历 + 当日) |
/content/files |
portal-files | 网盘(上传记录 + 下载) |
/start |
start-process | 发起流程 |
/todo /todo/:id |
my-todo / todo-detail | 待办列表 / 任务处理页 |
/done |
my-done | 已办 |
/created |
my-created | 我发起的 |
/work/:job |
work-detail | 流程详情 |
/read /draft |
my-read / draft | 已阅件(2026-11 起只剩已阅一档,待阅在待办里)/ 草稿箱 |
/agent /handover /profile |
agent / handover / profile | 流程代理 / 待办交接 / 个人资料 |
/design/processes /design/processes/:id |
design-processes / design-process-editor | 流程列表 / 可视化设计器 |
/design/forms /design/categories |
design-forms / design-categories | 表单设计 / 流程分类 |
/org/tree /org/persons /org/roles /org/auth-roles |
org-* | 组织架构 / 人员 / 岗位角色 / 权限角色 |
/monitor /statistics |
monitor / statistics | 流程监控 / 统计分析 |
/settings /logs |
settings / operation-logs | 系统设置 / 操作日志 |
约定:
-
BaseDialog只接受:show+@close;ConfirmDialog为:show+@confirm/@cancel -
Icon的name是字面量联合类型,动态图标需type IconName = InstanceType<typeof Icon>['$props']['name'] -
列表页统一走
useOAList(内部复用 sub2api 的useTableLoader,含分页、防抖、请求取消与错误 toast) -
stores/app.ts提供showSuccess/showError/showInfo/showWarning/hideToast -
首页各面板共用
components/portal/PanelShell.vue(标题 + tab + 更多 + 翻页), 首屏由GET /portal/home一次喂饱,切 tab / 翻页才打各自的列表接口 -
网盘页是
oa_file的上传记录列表:上传固定落本地磁盘,下载走GET /files/{id}/download,可见性以后端返回的scope为准,前端不自建权限规则 -
三态筛选统一发送
1/0,后端query.tri_state也兼容true/false -
待办列表那一只「流程状态」筛的是所属单据(
work_status=running,paused,逗号分隔多选), 不是待办自己那份status——那一列只有pending一个值,说的是这条待办办没办完。 四个流程状态与流程监控、「我发起的」、明细导出同一套取值;paused另算一档,判据是oa_task.pause(挂起是运行中的冻住开关,不写进status),与行上那枚「已挂起」角标同一份。 条件只有一份(runtime._task_conditions,统一待办那一条是service/inbox.Filters): 列表、批量「全选这一片」、导出 CSV 三条路共用,筛出几条就批几条、导几条 -
待办是一张取件箱(2026-11):
GET /task/inbox把我自己的待办、抄送需处理、只需阅三档 并成一页,档位互斥、加起来就是整张列表;红点逐行吃出参上的unread(待办认view_time、 抄送认seen_time),已读不是已办——灭点之后行照旧在待办里,只有单条或批量处理才离开。 只需阅那一条看过即归进已阅。界面上不再单独有一张「待阅」。全部口径、PC 与手机的版式、 为什么选并页不选搬表,见 todo-inbox-unified-design.md; 守卫backend/scripts/check_inbox_read.py(33 项,三档的列表 / 筛选 / 计数一致、红点生命周期、 混批那一档 skipped)与frontend/src/views/oa/TodoListView.inbox.spec.ts(16 条) -
一次开几张单子靠
stores/tabs.ts+components/layout/TabBar.vue:页签的身份是路径, 不是完整地址(/read?tab=done与/read同一张,/work/A与/work/B各一张), 点页签回到离开时那个fullPath;不设上限、开多少张都留着(超上限自动关最早那张会把人 回得去的那一格吃掉),工作台钉住不给关,清单存sessionStorage,落到登录页与页签一起清空(tabs.reset()+clearAllPersistedTableStates(): 页签清了、上一个人筛的条件没清,等于换个人继续看上一趟那一屏)。关掉一张页签,它那份缓存 跟着作废(tabs.remove给那一格刷一个序号),否则关掉再点开复用的还是上一趟那个实例与 那套筛选,与「关掉这一页」正好相反;「关闭其它 / 关闭全部」同一条删除口径。要不要留活 只写在路由上:meta.cache: true的那些(工作台、各张列表页、门户那几张列表)过AppLayout.vue里那道KeepAlive(留活那档的max是CACHE_MAX = 32,按标了cache的 列表页数给足宽裕,不再照页签数算——页签本身不封顶:关掉一张或刷新一张都换钥匙,旧钥匙那份还 等 LRU 挤,写太小就会把还开着的页签的留活挤掉), 回来还是那份组件、那套筛选与那一格滚动位置;单据详情一律不标——它们读当前地址上的:job/:id,藏着的那一份会跟着别人的地址把自己的数据改掉。「刷新这一页」不要求页面 自己实现:进缓存那一档钥匙是「路径 + 刷新序号」(tabs.instanceKey),不进缓存那一档 只带刷新序号(tabs.nonce)——详情页是照「同一个实例换一张单」写的、自己watch着:job/:id重拉,路径进了 key 就等于每换一张整页重挂。页签条摆不摆与多高各只有一处: 摆不摆只看AppLayout的tabBarShown(TabBar 自己那句v-if去掉了),高度取stores/tabs.ts的常量TAB_BAR_HEIGHT,AppLayout拿它算--app-tabbar-h,不再在 两处各写一遍2.5rem/h-10。 页签上那句单据标题由composables/useTabTitle.ts从详情页回填,没回填前用路由自带的meta.titleKey(跟着语言翻,人写的标题不翻) 什么时候少一格只有两个入口:页签条自己那颗 ×(含「关闭其它 / 关闭全部」),以及 「这一屏用完就废、人离开它」——按下返回、待办办完跳去已办、发起成功或存稿成功用 replace 顶掉那张旧表单、设计器因为表单已删把自己弹回列表。判据与实现只在composables/useCloseTabOnLeave.ts:BackButton默认就带这一手(keep-tab是唯一的例外口, 目前一处不用),等导航真的落定才收,为的是跳转没走成时别把还站在这页的人那一格删掉、 也别在走之前先把整屏重挂一遍。逐页清单与「看着像离开、其实不许收」的三种(就地重取、 换地址不换屏、手机上那条通用返回)写在frontend/src/router/README.md列表页的筛选条件与页码存在这一趟会话里(
composables/usePersistedTableState.ts, 钥匙 = 路由路径):useTableLoader每次发请求记一笔,只按initialParams的形状取键 (撤掉的筛选条件不该从老键里自己长回来),宽屏连页码一起还原、窄屏只还原条件 (手机上列表是越拉越长的流水,见useMobileFeed),且挂载后那句reload()认还原出来的 那一页而不是打回第一页。useOAList里那把默认钥匙(route.path)只在这一屏标了meta.cache时才发——留不留条件与留不留活是同一件事,判据与KeepAlive共用一句, 不留两把尺子;消息渠道、操作日志、组织人员那三个管理页没标cache,本来每进一次 都是新的一屏,跟着带上次的条件是无端端变味(要换钥匙显式传persistKey,要从空白开始就传 空串,详情页那种「每次都要看最新的」就传空串)。流程监控是这一句显式声明的例外:它同样 不留活(监控摆旧数比重新拉一次更误事),但自己传一把persistKey只要条件那一半——管理员 筛一轮就要点开几十张单子逐个查,每退回来重筛一遍是白费劲;它的「全部流程 / 全部待办」档位 写进地址(?tab=task),跟条件一起回来,否则条件留住了人却被放回另一张表。切回缓存里的列表页会按当前条件与当前页 静默重拉一次 (onActivated,只管宽屏,走load({ silent: true }):不碰loading,否则DataTable会把真实那几十行换成骨架、刚恢复好的滚动位置又被压回顶上)——躺在缓存里那段时间 单子可能早被别人办掉了。还原出来的那一页按报文pages校一道,越界落到最后一页再补一发—— 这一发收在同一趟请求的生命周期里(最多两轮的循环),不另起一次load():另起会换上自己的AbortController,头一发收尾认不出自己那一发,骨架就一直挂着 -
权限判定集中在
stores/auth.ts:can(code)/canAny(...codes)/dataScope/roleNames,can('')视为放行(用于没声明权限码的页面);isAdmin认is_admin与遗留的role === 'admin'。 页面里要按权限显隐就computed(() => auth.can('…')),不要再判isAdmin -
权限码的中文名在
constants/permissions.ts,后端目录是权威来源:后端新增了码而本地没收录时 界面原样显示码值,不会空白;pnpm check:i18n会盯住已登记的labelKey -
权限码有三条一致性由
src/constants/__tests__/permissionCodes.spec.ts守住:菜单/路由/按钮里写的 码必须在目录里(写错一个字符入口就永远不显示)、前端文案表要等于后端app/permissions.py的目录、 每个码与数据范围的中文名在 zh/en 都要有(权限矩阵用t(动态 key),i18n 扫描器抓不到这种) -
表单一律由
components/oa/FormRenderer.vue渲染,设计器的「放置位置」画布也只是给它多传design+activeKey:设计态才把字段画成圆角卡片、给空位格子铺 45° 斜纹、标出类型标签与第 N 行 · 第 i/2 列角标(.chip-position)并允许点选,运行态 DOM 完全不变(装饰全在v-if="design"里),所以「设计时看到的位置」和「审批页渲染出的位置」不可能分叉 -
单个字段怎么填、只读时怎么显示,统一在
components/oa/FormFieldControl.vue:主表那一格和 明细表的一格都走它,所以主表加一类控件,明细列跟着就有,不必两处各写一遍。明细列可用的 类型清单是types/index.ts的TABLE_COLUMN_TYPES(= 主表能填的类型减去标题、系统带出、 嵌套明细、公式、分割线、说明文字、隐藏这七类不能在一行里当值用的),后端app/service/formruntime.py的TABLE_COLUMN_TYPES必须一起改,漏一侧的话 保存表单设计时就被design.py的validate_schema()拦下。列上绑字典走的是属性面板里的 「选项来源」下拉(和主表同一个Select,从listDictsCached()的目录里挑,不让人手打编码), 选中后把dictValues()取回的条目预览在卡片上;绑了字典就不再显示手填选项那一格, 切回「手填选项」只清dictCode,原先手写的options原样留着 -
明细表(
type=table)的编辑态是「勾选列 + 序号列 + 右上角加减行」:有几行就显示几行, 点一次+加一行,不在末尾补一行等着填的空行(那种占位行会让人以为一次加了两行)。−只删勾上的行,勾了就能删,minRows不在这儿拦人——它只让底栏在0 < 行数 < minRows时提示「至少要 N 行」,真越界是提交时由后端_row_problems()挡下;maxRows满了+灰掉, 底栏同样说一句「最多 N 行」。一行都没有时只显示空状态提示,不铺空行也不唠叨最少行数。 编辑期用trimRows(留着空行,只丢未知列、按maxRows截断),落库才用normaliseRows剔空行。口径由src/components/oa/__tests__/FormRendererTable.spec.ts守住 -
格子里的控件一律
min-h-9(36px):style.css的.cell-control是这一条口径的唯一出处, 主表和格子共用的FormFieldControl在compact下把输入框、下拉、多行文本、选人、附件都套上它,Select/TextArea/Input/CascaderField/PeoplePicker/OptionPicker也各有一个compact入参(主表不传,仍是 42px 的宽松版)。多行文本在格子里是单行等高、内容自己在里面滚, 不然一个min-h-[80px]就能把那行撑成锯齿;用min-height而不是写死height,选项多到换行、 选了几个人的格子该长还是让它长。手写签名是唯一不放画布的:格子里只留一条按 36px 的按钮, 点开BaseDialog才给画布(外层发起弹窗也开着,Esc会一次关掉两层,所以这个弹窗只给按钮收) -
部门下拉读的是组织树,不是名称序的一维清单:
/org/units/simple回的是按(order_number, name)平铺的部门,层级只在path里,直接铺进下拉就成了父部门排在自家 子部门后面、三级科夹在二级部中间。utils/deptOptions.ts的buildDeptOptions()按前序 重排并标出level,Select见到数字level才按它缩进(16px 一档)并画一条层级引导线, 根部门加粗;level不进label,选中态、只读回显、搜索匹配都还是干净的部门名。 中间层被停用或被关键字筛掉时接最近的祖先当父级,层级只增不减;搜索把父部门筛掉了就在 行尾补一段父路径。组织树属性面板的「上级部门」走同一套(它原先往label里塞全角空格)。 口径由src/utils/__tests__/deptOptions.spec.ts与src/components/common/__tests__/Select.spec.ts守住 -
字段落位(第几行、第几列、占几格、哪里被挤成空位)由
utils/formLayout.ts计算, 它按 CSS grid 自动排布的口算:放不下就换行并留出空位,改这里要同步改src/utils/__tests__/formLayout.spec.ts -
会话自愈在
utils/sessionRecovery.ts:访问令牌(security.access_token_minutes,默认 720 分钟)过期时,api/client.ts的 401 分支先叫启动时注册的回调去POST /auth/refresh换一张新令牌,换到就把原请求重发一次; 换不到才清掉会话并跳/login?redirect=当前页。一整屏请求同时撞 401 只续期一次(refresh_token 是一次性的),/auth/login、/auth/captcha、/auth/refresh自己回 401 属于业务结果,不算会话过期。缺这段时,标签页挂过 令牌有效期只会停在一张空列表上:路由守卫只看本地有没有令牌,401 又只清了 store,既不报错也不跳登录, 看着像数据丢了。口径由src/api/__tests__/sessionRecovery.spec.ts(重发一次 / 只续期一次 / 登录接口不触发) 与src/utils/__tests__/sessionRecovery.spec.ts(续上不打断、续不上带 redirect 回登录、已在登录页不再跳)守住 -
懒加载 chunk 加载失败(多见于刚部署完的旧标签页)由
router/chunkReload.ts兜底:router.onError里对未完成的那一次跳转整页重载一次,afterEach清标记; 判定口径与「同一目标只重试一次」由src/router/__tests__/chunkReload.spec.ts覆盖
10. 扩展指引
- 新增环节类型:在
engine/definition.py增加ACTIVITY_*常量并加入ACTIVITY_TYPES与校验规则,在engine/engine.py的_arrive分支里处理,最后在ProcessDesignerView.vue的调色板与属性面板补配置项 - 新增表单字段类型:
FormFieldControl.vue增加录入与只读分支 +oa_form.fields[].type, 并在design.py的表单校验里放行;想让明细表也能用这一类,再把它加进前端TABLE_COLUMN_TYPES与后端formruntime.TABLE_COLUMN_TYPES - 新增通知时机:调用
engine内的通知写入函数,避免在 api 层散落 - 新库首次启动会走
seed.run的全部分支(建组织、流程、门户内容与素材落盘),线上库因已有数据 不会再走这些分支,所以改seed.py后除了跑验收脚本,还要跑python3 scripts/check_globals.py app scripts tests,或用OA_DB_NAME=<临时库>起一次实例把冷启动种数据的路径真跑一遍。临时库得自己建 (CREATE DATABASE unis_oa_tmp DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci, 跑完DROP DATABASE):ensure_database只建[database] create_allowlist点名的库, 名字不在里面就直接启动失败,见app/db.py与tests/db_guard.py - 改
models.py后跑python3 backend/scripts/dump_schema.py重新导出sql/schema.sql,再用python3 scripts/check_schema_snapshot.py回归这一对(不连库)。测试库会被启动时的ensure_columns()悄悄补列,本机永远看不出快照落后;而生产是auto_create_schema=false+ DBA 按快照手工建库, 落后一列 = 新库第一次登录Unknown column(oa_refresh_token.last_used_at就这么炸过一次)。 快照只管新建的库:已经在跑的生产库不会回头读它,所以models.py每加一列还得往sql/upgrade/里补一份当天日期的增量 SQL(ALTER TABLE ... ADD COLUMN,幂等写法与核账查询照现有那几个文件抄),DBA 拿它改老库。少了这一步的症状不是新库炸,而是 生产日志每隔一个轮询周期刷一条Unknown column(oa_outbound_message.phase就这么炸过第二次) - 新增一个存储后端(如 OSS / S3 兼容网关):在
app/storage/加一个实现FileStore的模块(put/open_stream/delete三个方法),在storageconfig的后端枚举里登记, 再在storage.store_for的映射表里加一行即可;业务层只认 uri 与purpose, 不会感知具体后端。uri 的 scheme 必须唯一,否则历史数据会解析到错误的后端 - 改表单校验规则:
utils/formLayout.ts的validateFields(设计器即时提示)与app/api/design.py的form_problems(保存与POST /process/forms/validate)必须一起改, 否则会出现「预览说能存、保存被拒」;跑python3 tests/form_design.py回归 - 改门户后端后跑
python3 tests/portal_home.py --base http://127.0.0.1:8000/api/v1(73 项断言),流程引擎侧另有tests/e2e_flow.py(47 项),表单设计tests/form_design.py(59 项,含审批人解析预览),权限侧tests/permissions.py(72 项);前端侧守卫跑pnpm test:run - 新增一个权限点:
app/permissions.py的目录里加码 → 目标接口挂Depends(require_permission("…"))(需要按范围看数据再叠scoped())→ 前端router/index.ts给路由补meta.permission、AppSidebar.vue给菜单补permission→constants/permissions.ts加中文名 +locales/{zh,en}.ts补perm.*→ 需要的话调整内置角色的默认权限,最后跑tests/permissions.py回归 - 新增一个接口:至少挂
Depends(current_user);面向管理、设计、统计、日志的读接口再挂require_permission("…"),需要按范围看数据的再叠scoped();确实要匿名的写进scripts/check_route_guards.py的ANONYMOUS并注明理由,然后跑这个脚本回归 - 首页热点封面是随种子数据落盘的素材:
backend/assets/portal_covers/里的图由app.seed.stage_cover拷进storage/portal/cover/,GET /cms/documents/{id}/cover也只从这个目录读。换图跑python3 scripts/gen_portal_covers.py(素材比目标新会自动重拷), 已初始化过的库再跑一次python3 scripts/apply_portal_covers.py