@pisell/private-materials 6.3.220 → 6.3.222

package/lib/plus/panpacificTask/README.md

@@ -0,0 +1,114 @@
+# PanpacificTask
+
+替代 Panpacific 原型 `#task` 的完整工作台。低代码页面只放一个组件，不再维护页面 JS、表单节点、抽屉或弹窗节点。
+
+```tsx
+import { PanpacificTask } from '@pisell/private-materials';
+
+<PanpacificTask />;
+```
+
+低代码物料名称：`PanpacificTask`，面板标题：**Panpacific Job 工作台**。注册文件在 `lowcode/panpacific-task/meta.ts`。物料包更新后，可直接导入仓库 `panpacific files/component-v1/schema.json`，或从物料面板拖入组件。该示例页面不再调用旧 Page.jsx；旧 `jsx-v1` 文件保留供回退。
+
+这是 proCode 组件，内部使用受控 Ant Design Modal / Drawer；低代码编辑器不需要单独管理它们。组件自身负责打开、关闭、未保存内容确认及请求中的锁定，并用 ConfigProvider 设置 pisell-lowcode 前缀以接入物料样式。
+
+## 已实现
+
+- Calendar / Timeline / List 三个视图。日历按到期日显示，可切换完整周期；双击日期创建 Job。
+- 日历每天最多展示四个项目，更多项目可从 +N 面板查看、拖出。右侧卡片按原型显示整行状态标签、Job 编号、供应商名称、到期日；悬停卡片关联高亮对应日历项目。标签、日历项目、甘特条和图例共用六种背景与文字颜色；已开票显示票据图标，取消状态显示删除线。
+- Timeline 顶部按展示状态筛选（全部、Create、Collected、Invoice、Complete、Cancel、Delayed），按存储状态分组，可折叠分组。
+- List 的列顺序：Job code、Supplier、Schedule、Due date、Status、Items、Payment、Actions。Items 对应新版数据结构中的物料明细数量；产出产品独立展示在抽屉中。
+- 搜索覆盖编号、供应商名称 / 州 / 分公司或邮编、联系方式、来源、付款条款、物料和产品的名称及描述，不搜索软删除明细。输入状态即时更新，结果列表使用延迟渲染；搜索、到期日和展示状态采用 AND 组合，可清空、重置；变更筛选回到第一页。
+- 日历项目、右侧卡片、List 行 / View、甘特条 / 左侧名称都打开同一个详情抽屉。Edit 进入抽屉编辑；Create 打开完整表单。
+- 表单顺序：基础信息（任务分类、日期与物流）→ 供应商（含联络信息）→ 物料 → 产出产品 → 付款条款。使用真正的 `Form.List`；Select 保留 small API，表单 / 抽屉内按钮、单行输入、数字输入、日期选择，以及顶部筛选控件统一为 38px；多行备注保持自适应高度，浮层挂载到滚动容器。新建底部为 Cancel / Create，编辑底部为 Cancel / Save，操作文案使用独立翻译键。
+- 选择供应商填充快照字段，并按 `STATE_SUPPLIER_00001` 生成编号。手动编辑编号后停止覆盖，Reset 恢复自动生成。保存时若服务端返回编号重复，保留填写内容并提示“Job 编号已存在，请修改后重试”，不预查询编号、不自动换号或重发请求。
+- 详情抽屉宽 520px，按原型使用灰底白色分区、右上编辑 / 关闭、底部状态操作；编辑时扩展到 820px。展示供应商及其联络信息、排期、物流、付款条款、任务分类、提货照片、收付款记录。物料与产品独立分区，每区再按 Scheduled / Confirmed 分组；标签与其他详情字段字号一致，使用带圆点的单行列表，如 Battery Module ×40 @ 8.5/kg。
+- 状态主操作 Create → Collected → Invoice → Complete；More 支持其他状态、取消、复制和移除。复制打开新建草稿，清除父子 ID、发票日期和旧编号，不复制收付款 / 提货记录。
+- 记录付款 / 收款、金额、参考号、凭证图片；凭证入口位于金额、单据号同排最前端，上传后替换为缩略图，在预览中删除后恢复入口。提货照片同样可在预览中删除，删除失败保留原图。只记录业务数据，不发起实际付款。
+- Calendar 移动排期、Gantt 移动和两端调整会调用更新接口，成功后同步三个视图；失败不接受拖动结果。甘特条使用 60px 行高显示两行内容，两端提供可见拖动手柄。
+- 中、繁中、英、日、葡五种语言。业务加载失败只记录 console，不插入 `pp-job-warning`；保存错误保留输入并展示。
+
+## 数据规则
+
+以提供的 `job.txt` / 关联表 schema 为准。`delayed` 是展示状态，仅在 **due_date 早于今天** 且状态非 complete / cancel 时成立，不写入数据库。时间区间起点为 pickup_date（缺省为 due_date），终点为 due_date（含当天）；组件适配为 endExclusive。
+
+移动只平移 due_date 及已有的 pickup_date；缺省提货日期保持缺省。甘特图左端调整写入 pickup_date，右端调整写入 due_date。job_created_date 是创建日期，拖拽不会修改；与旧原型平移创建日期的行为有意区分。
+
+选择供应商后，按下表自动填写 Job 的供应商快照（包含联络信息），允许在当前 Job 内调整。切换供应商时，缺失字段置空，避免残留上一家供应商的信息；编辑和详情读取已保存的 Job 快照，供应商主数据后续变化不自动覆盖历史 Job。
+
+| Supplier     | Job               |
+| ------------ | ----------------- |
+| name         | supplier_name     |
+| state        | supplier_state    |
+| sub_name     | supplier_sub_name |
+| contact_name | company_contact   |
+| phone        | supplier_phone    |
+| email        | supplier_email    |
+| lead_source  | lead_source       |
+
+sub_name 的业务含义为“分公司/邮编”。创建、编辑表单及详情统一标为“分公司 / 邮编”（英文 Branch / Postcode），选择供应商后从 sub_name 自动填写 supplier_sub_name，可在当前 Job 中调整，并参与搜索。该字段使用普通文本输入，允许分公司名称或邮编，不做纯数字邮编校验，也不根据 State 推导。供应商摘要显示“名称 · 分公司/邮编”，为空时仅显示名称；历史 Job 使用已保存的快照。
+
+contact_method 已停用，不参与表单、详情、搜索、自动填充或提交；历史数据库值保留，不用它推断电话或邮箱。Supplier.memo 没有对应的 Job 字段，不映射到物流备注或付款备注。
+
+Status / Invoice date 不作为表单输入，也不随编辑保存覆盖。新建写入 create / null；首次流转到 invoice 时写入当前日期，后续流转保留原有开票日期。
+
+物料 / 产品明细暂不显示 description 输入，也不要求用户填写。数据库不允许 description 为 null，因此未填时统一提交空字符串，不以名称自动补齐；创建、复制及编辑明细共用此规则，已有描述保留。详情优先显示名称，旧记录没有名称时仍能以描述识别。物料关联和数量的必填校验保持与数据结构一致。
+
+原型 Remove 是本地永久删除。此实现按数据库的 `deleted_at` 软移除 Job，避免关联付款 / 照片被级联删除或成为孤儿。子明细删除只对编辑会话中已读取且属于当前 Job 的记录调用 destroy。
+
+主表写入字段在 `model.ts/jobFields` 白名单内。新建（包括复制）只调用一次 `/api/prs_job:create`，body 包含 `job_materials` 和 `job_items` 两个关联数组，由 NocoBase 建立子记录的 job_id；新明细不传 id、job_id 或表单 \_key。BIGINT 保持原值，金额和数量保留十进制字符串；不填写 operator / audit 字段。
+
+提交时从 `appHelper.utils.store.getState().core.core.tenant.id` 读取当前租户 ID。saas_shop 将第一次 `/tenant/core` 响应存入该 store；响应中的 `tenant.tenant_id` 是第二次查询 parentCore 时使用的上级租户 ID，不用于此处，也不作为回退值。创建 Job 主表及两类明细、编辑时新增明细均显式写入当前租户 ID；不沿用复制草稿或供应商记录中的租户值，也不修改已有记录的 tenant_id。创建任何新记录前若无法取得有效租户，保留草稿并提示刷新，不先写入部分数据。无需解析鉴权凭证；后端仍负责鉴权和关联记录的访问权限。
+
+新建使用 NocoBase 原生关联创建事务，成功后结束新建会话，不继续调用子表 create；需要再次编辑时重新加载详情。明确失败保留草稿，可重试整次请求；超时或未返回父记录 ID 时结果不确定，需关闭后刷新核实，不自动降级为分步创建。实际事务与关联权限需在部署环境验证。
+
+编辑继续先更新主表，再分别新增、修改或删除两类明细，不使用嵌套数组全量替换。编辑的多个请求不构成整体事务：已成功的明细记录 checkpoint，后续明确失败可重试剩余操作。编辑新增明细、付款 / 照片创建也不自动重试不明确的结果。
+
+## 多语言与宿主接入
+
+参照 `saasTeamMembers/locales.ts`，`locales.ts` 按 en / zh-CN / zh-HK / ja / pt 分组，使用 `pisell2.panpacific.task.*` 键。组件从 `useEngineContext()` 取得 `engine.props.locale`，通过 `@pisell/utils` 的 `locales.init(localeTexts, locale)` 初始化，使用同一 `locales.getText` 渲染视图、表单、抽屉和校验提示。语言格式兼容与英文回退沿用共享工具，不再维护独立 translator 或 locale prop。
+
+## 接口及扩展
+
+默认复用 `appHelper.utils.request`，缺省使用 private-materials 初始化的 request；没有独立 token、域名或 fetch。`serve.ts` 按 `systemSettings/registry/services.ts` 的方式导出业务函数，以宿主 request 为首个参数，通过 `request.get/post` 调用 `/api/prs_…:action`，配置 `isNocobase: true` 和 `x-data-source: pisell2`。查询参数由 URLSearchParams 编码到 URL，写入字段放在 POST body，保留完整响应以读取分页 meta。
+
+所需 collection 权限：
+
+| Collection                                                                        | Action                       |
+| --------------------------------------------------------------------------------- | ---------------------------- |
+| prs_job                                                                           | list / get / create / update |
+| prs_job_material、prs_job_item                                                    | create / update / destroy    |
+| prs_supplier、prs_material_item、prs_product、prs_payment_term、prs_task_category | list                         |
+| prs_job_payment                                                                   | list / create                |
+| prs_job_pickup_photo                                                              | list / create / update       |
+
+Job create 必须允许写入 `job_materials`、`job_items` 关联字段及相应子字段。Job list / get 的 `appends` 必须支持 `job_materials` 和 `job_items`。详情未返回完整关系时禁止进入编辑，防止误清空明细。列表分页每页 200，最多 100 页，超过上限不会展示部分结果为完整列表。
+
+附件上传参考 `BaseUpload` 的非 shop 分支，读取 `appHelper.constants.mediaUploadUrl` 和 `getHeaders()`，直接 POST multipart 表单（`file`、`group_id=0`）。媒体请求使用宿主给定的完整地址和最新鉴权头，不经业务客户端拼接前缀；Content-Type 的 boundary 交由浏览器生成。租户环境可配置 `/tenant/media/upload`，编辑器可配置 `/admin/media/upload`，组件不硬编码环境地址，也不请求商城的 `/shop/ali-upload/policy`。缺少上传地址时明确报错，不猜测备用端点。
+
+附件 JSON 写入 `{ ...上传结果, url, name }`；读取兼容 url 字符串、数组、对象及原型 dataUrl。提货照片 JSON 若包含多张图片，删除仅移除选中的附件；最后一张删除时更新该照片记录的 deleted_at，不删除媒体库文件。图片限制 10MB，HTTP / 业务失败或未返回有效 URL 时不保存附件记录。如已有不同协议，可传 `uploadPhoto(file): Promise<Attachment>`。
+
+可选 props：
+
+| Prop              | 默认 / 用途                                                   |
+| ----------------- | ------------------------------------------------------------- |
+| defaultTab        | calendar；可选 timeline / list                                |
+| uploadPhoto       | 自定义图片上传流程，返回持久化附件 JSON                       |
+| onJobChange       | 保存、状态、日期、付款 / 照片或移除成功后通知宿主，参数 jobId |
+| className / style | 外层样式                                                      |
+
+组件无需页面 dataSource 配置，也不接收 transport / dataSourceMap 适配。接口扩展在 serve.ts 中完成。
+
+编号是前端预览值，唯一性由数据库约束保证。识别 `prs_job_tenant_job_number_unique` 冲突后仅显示多语言提示，由用户修改编号后重新提交；明确的编号重复不会被当作创建结果不确定而锁住表单。
+
+## 维护与验证
+
+`PanpacificTask.tsx` 组织视图和状态；`JobForm.tsx` / `JobDrawer.tsx` 负责表单和详情；`model.ts` 管理业务规则；`serve.ts` 定义接口；`saveJob.ts` 管理父子记录保存与重试检查点，`tenant.ts` 读取当前 NocoBase 租户；`attachments.ts` 处理附件，`PhotoPreview.tsx` 提供预览及删除入口；样式和翻译各自独立。
+
+仓库根目录执行保存逻辑的回归测试：
+
+```sh
+pnpm --filter @pisell/private-materials exec vitest run --config vitest.panpacific.config.ts
+```
+
+`saveJob.test.ts` 使用内存 get/post 客户端，覆盖不同错误响应结构、重复时不自动换号或重发、用户修改后重新提交、其他错误提示，以及超时保护和五种语言的提示键。还验证父子新记录的租户一致性、缺少租户时停止写入、编辑不改写已有租户、空描述兼容，以及删除影响 0 行时保留检查点、重试不重复删除已成功的记录。`tenant.test.ts` 验证当前租户 id 为 20、上级 tenant_id 为 1 时的提交、store 更新及缺失或无效字段的处理。独立 Node 配置不加载通用 UI 测试 setup，不访问远端业务数据。

package/lib/plus/panpacificTask/attachments.js

@@ -0,0 +1,66 @@
+const require_objectSpread2 = require("../../_virtual/_@oxc-project_runtime@0.122.0/helpers/objectSpread2.js");
+const require_asyncToGenerator = require("../../_virtual/_@oxc-project_runtime@0.122.0/helpers/asyncToGenerator.js");
+//#region src/plus/panpacificTask/attachments.ts
+function attachments(value) {
+	if (!value) return [];
+	if (Array.isArray(value)) return value.flatMap(attachments);
+	if (typeof value === "string") try {
+		return attachments(JSON.parse(value));
+	} catch (_unused) {
+		return /^(https?:\/\/|\/|data:image\/)/i.test(value) ? [{ url: value }] : [];
+	}
+	if (typeof value === "object") {
+		const url = value.url || value.dataUrl;
+		if (typeof url === "string" && /^(https?:\/\/|\/|data:image\/)/i.test(url)) return [require_objectSpread2._objectSpread2(require_objectSpread2._objectSpread2({}, value), {}, { url })];
+		if (value.data) return attachments(value.data);
+	}
+	return [];
+}
+function preparePhoto(file) {
+	var _file$name$split$pop;
+	if (file.size > 10 * 1024 * 1024) throw new Error("pisell2.panpacific.task.imageOnly");
+	if (file.type.startsWith("image/")) return file;
+	const type = {
+		png: "image/png",
+		jpg: "image/jpeg",
+		jpeg: "image/jpeg",
+		webp: "image/webp",
+		gif: "image/gif"
+	}[((_file$name$split$pop = file.name.split(".").pop()) === null || _file$name$split$pop === void 0 ? void 0 : _file$name$split$pop.toLowerCase()) || ""];
+	if (!file.type && type) return new File([file], file.name, {
+		type,
+		lastModified: file.lastModified
+	});
+	throw new Error("pisell2.panpacific.task.imageOnly");
+}
+function defaultPhotoUploader({ mediaUploadUrl, getHeaders } = {}) {
+	return function() {
+		var _ref = require_asyncToGenerator._asyncToGenerator(function* (file) {
+			var _result$errors;
+			file = preparePhoto(file);
+			if (!mediaUploadUrl) throw new Error("pisell2.panpacific.task.uploadFailed");
+			const body = new FormData();
+			body.append("file", file);
+			body.append("group_id", "0");
+			const headers = new Headers(getHeaders === null || getHeaders === void 0 ? void 0 : getHeaders());
+			headers.delete("Content-Type");
+			const response = yield fetch(mediaUploadUrl, {
+				method: "POST",
+				body,
+				headers
+			});
+			const result = yield response.json().catch(() => null);
+			if (!response.ok || (result === null || result === void 0 ? void 0 : result.status) === false || (result === null || result === void 0 || (_result$errors = result.errors) === null || _result$errors === void 0 ? void 0 : _result$errors.length)) throw new Error("pisell2.panpacific.task.uploadFailed");
+			const image = attachments(result)[0];
+			if (!image) throw new Error("pisell2.panpacific.task.uploadFailed");
+			return require_objectSpread2._objectSpread2(require_objectSpread2._objectSpread2({}, image), {}, { name: file.name });
+		});
+		return function(_x) {
+			return _ref.apply(this, arguments);
+		};
+	}();
+}
+//#endregion
+exports.attachments = attachments;
+exports.defaultPhotoUploader = defaultPhotoUploader;
+exports.preparePhoto = preparePhoto;

package/lib/plus/panpacificTask/index.d.ts

@@ -0,0 +1,2 @@
+import { Attachment, PanpacificTaskProps } from "./types.js";
+import { PanpacificTask } from "./PanpacificTask.js";