unis-oa/docs/architecture.md

71 KiB
Raw Permalink Blame History

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'] / 裸字段名 → 沙箱取值, or and not is not None → JS 写法,A if C else B → 三元, float int round len sum total count rows get money_cn days_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(办结)、或没有可用出线。

关键点:

  1. token 记账。oa_work.tokens 保存并行分支状态(engine/tickets.py), parallel 出网关时为每条出线复制 token,merge 入网关按前序计数聚合, 计数未满则本轮不产生待办。退回与撤销通过 tickets 的 reset/prefix 收敛, 避免“半个分支还活着”。
  2. 表单作用域。oa_task.form 决定该环节可见与可写的表单;取值为 activity.form or work.form,因此环节未单独绑定时沿用流程的 latest_form, 设计器里表现为“使用表单:无 · 沿用流程默认表单”。
  3. 同代人合并。processingTaskOnceUnderSamePerson 打开时,若下一环节处理人与 刚办理的人是同一个账号,则自动以 auto 类型办结并继续流转(自己审批自己)。
  4. 空处理人兜底。emptyToCreator=true 时若解析不出处理人,交回发起人; 否则按流程异常终止并写 oa_work_log。
  5. 留痕。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。
  6. 编号。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