@qfei-design/make-app-approval

Make App 审批公共 npm 包，统一审批相关 UI、交互和样式。源码由本独立项目维护；ExpensePoc 是首个接入应用。

本次准备版本为 0.2.11，尚未发布。 日期范围控件合同从 0.2.0 起相较 0.1.0 有不兼容调整，升级前请阅读 迁移说明。已有基于 CanvasTable 的桌面审批列表、流程状态组件和普通记录编辑限制。已提供按节点授权的办理详情与动作组件，以及手机列表模式 presentation="mobile" 和复用同一办理控制器的手机详情布局插槽；真实接口及移动详情真机联调、独立流程表尚未完成。接入先读 包与宿主职责及接入步骤，再读 公开 API。

0.2.9 新增随包交付的宿主字段适配标准示例，覆盖人员头像缓存、原文数值校验与精确范围比较、手机及桌面样式，并同步 TASK 节点字段元数据接入说明。示例由宿主合入字段适配层，不新增审批运行时导出。示例开发依赖仍为正式 [email protected]；选择器打开期间异步刷新已选头像的修复仍需移动包单独发布、升级依赖后生效，不能视为本次审批包已包含该修复。

0.2.10 更新手机数值字段的输入来源识别：指针聚焦不显示编辑描边，Tab/Shift+Tab 导航保留可见焦点；输入来源 helper 随字段适配示例交付，运行时公开入口及依赖版本不变。

0.2.11 待发布变更：getRecordApprovalWriteRestriction 对流程状态 APPROVED 返回 reason: "approved" 和“该数据审批已通过，不可编辑”，即使记录已解锁或对象已解绑流程仍然禁编。已发布 0.2.10 不包含此规则；宿主升级到包含该变更的新版本并验证前，保留现有统一适配器保护。穷举 reason 的消费方需补齐新分支，任务办理继续按节点授权。

当前提供

• 根入口：流程状态映射、bpmDefinitionKey 识别、系统只读字段识别、普通记录编辑限制。纯逻辑，不依赖 React 或请求，可供 UI 和 App Service 使用。
• /react：ApprovalStatus 状态组件。
• /list：MyApprovalsPage，包内统一页签、搜索筛选、CanvasTable 虚拟滚动、分批加载、加载/空/错误/重试；宿主提供基础组件 components、查询 provider 和详情回调。
• /detail：ApprovalTaskDetail，统一节点字段权限、授权操作、意见/退回校验、顶部直接提交和异常处理；宿主提供控件、字段渲染和任务 provider。退回仅校验审批意见，跳过业务字段校验；同意、拒绝及 SUBMIT 校验可编辑必填字段。通过 renderLayout 将按钮放在抽屉关闭 X 左侧，审批意见随正文滚动，退回/拒绝时必填、同意时选填。
• /styles.css：状态、列表与紧凑详情模板；详情使用固定浅色分隔线和文字色，控件与品牌色沿用宿主。模板尺寸和字段模式见 公开 API。
• ESM / CommonJS 双格式、TypeScript 声明、行为测试及实际构建产物检查。

本地开发

Node.js >=22.12.0，pnpm 10.20.0，与现有 make-app 公共包一致。

corepack pnpm install --frozen-lockfile
corepack pnpm run verify
corepack pnpm dev
corepack pnpm pack --pack-destination /tmp/make-app-approval

verify 依次执行 CI 配置检查、测试、类型检查、构建和公开入口产物检查。CanvasTable 所属的 @qfei-design 作用域从 npmjs 安装，锁文件中的 CanvasTable 下载地址也指向 npmjs。其他依赖沿用公司 npm-group；安装前需在当前环境中注入只读变量 NEXUS_NPM_READ_AUTH，.npmrc 只引用变量名，不保存凭据值。

dev 启动明确标注模拟数据的列表演示，build:demo 验证演示构建。宿主模板 examples/host-integration.tsx 参与类型检查并随 npm 包交付。列表使用可选 peer @qfei-design/canvas-table@^1.3.2；使用列表的 UI 必须安装，单独使用根入口的 Service 无需安装。

加载布局的浏览器回归：启动 dev 后访问同一地址的 /detail-loading-layout.html。页面自动检查普通页面、固定高度页面及自定义抽屉的占位高度、加载居中和后续内容遮挡，全部通过显示 PASS。可调整浏览器宽度后刷新重测；此检查使用真实布局尺寸，需单独执行，不包含在 jsdom 的 verify 中，也不随 npm 包发布。

接入示例

Make App 的 UI 和 Service 固定使用相同的已发布版本。升级到 0.2.0 时移除旧版审批包的 pnpm 补丁；远端依赖安装直接从 npmjs 获取发布产物。

import {
  APPROVAL_STATUS_FIELD,
  getRecordApprovalWriteRestriction,
  hasApprovalDefinition,
} from "@qfei-design/make-app-approval";
import { ApprovalStatus } from "@qfei-design/make-app-approval/react";
import "@qfei-design/make-app-approval/styles.css";

const approvalEnabled = hasApprovalDefinition(entity);
const restriction = getRecordApprovalWriteRestriction(record, { approvalEnabled });
const status = <ApprovalStatus value={record[APPROVAL_STATUS_FIELD]} />;

restriction 非空时，宿主隐藏普通编辑按钮/菜单，并在表格进入编辑和提交时检查最新行数据；不能仅将按钮置灰。restriction 为空时仍须检查原有操作、字段和行级权限。业务记录状态缺失时展示 -，未知非空状态展示“状态未知”；不要把加载失败当作未发起。已打开的表单在保存前仍需检查最新状态，后端写接口负责最终校验。完整接线范围见普通记录已通过只读。

包与宿主的分工

• 包目前统一列表、任务详情内容、节点字段权限和审批操作；宿主提供抽屉/页面容器及业务字段控件。
• 宿主处理导航、路由、应用上下文、登录及 App Service 请求。包处理列表刷新；宿主用 refreshKey 通知办理成功并刷新其他业务页面。包不读取 Token，不直接访问 Make 后端。
• 已接入审批的宿主保留“我的审批”入口和路由，流程停用后仍可访问历史任务；不按当前 bpmDefinitionKey 或任务数量隐藏入口，无任务时展示空态。历史数据权限由后端校验。
• components 必传：Input、Select、DateRangePicker、Button、Tabs。包固定查询/重置/日期校验/刷新功能，宿主适配控件事件和主题；没有原生控件兜底，也不要求宿主安装 Antd。Antd 宿主可复制 适配示例，继承既有 ConfigProvider。
• 后端决定“待处理 / 已完成”的归类、筛选、总数、排序和分页。2026-10-19 已确认 Make Workflow 接入参数：Service 固定 viewType: MY，待处理传 taskStatus: PENDING，已完成传 taskStatus: COMPLETED；前端直接展示返回行，不合并 CLOSED 查询、不去重、不按流程状态过滤。
• 申请单ID使用后端 recordId 原字符串。筛选仅有申请单ID、申请时间、申请人：keyword 映射为 recordId 完整编号精确查询；申请人单选默认“全部申请人”，候选来自宿主 users 接口，applicantId 映射为 starterId，清空时省略。人员 ID 全程保留精度。
• 新建审批字段按 bpm-start-config.fields 接入 UI 和 Service，不能与普通 IAM 字段再取交集。已确认上游为网关 origin + /make/workflow/v1/bpm-start-config，字段元数据完整、与 Schema 一致；ExpensePoc 新建表单已完成代码接入、尚待真实字段和发起联调；该新建表单不属于包组件。全部 Workflow 资源共用 /make/workflow/v1/ 前缀，网络适配仍由宿主提供。
• 普通业务入口禁编与任务内审批/退回修改是不同入口；包不会通过解锁业务记录来办理审批。

完整公开 API 见 PUBLIC_API.md。自动接入工具先读 package.ai.json。

发布

采用与 make-app-observability 一致的 @qfei/component-release-tools 和 GitLab CI 流程。alpha/beta 由 dev/test 手动流水线触发，只发布内部 Nexus；latest 由受保护的 vX.Y.Z 标签手动任务触发，将同一份产物发布到内部 Nexus 和 npmjs。分支验证同时覆盖 React 19 和 React 18。

完整的分支流程、初始化命令、CI 变量和失败重试说明见 发布规范。远端仓库为 make-app-approval，本地通过 origin 关联。本次 0.2.11 的发布状态以 GitLab 任务和 registry 查询为准。本地只运行验证和打包，不运行发布命令。不要仅凭本地版本号认定 registry 已有对应版本。