Phase 9: version message (FR-13)
- ใส่คำอธิบายแบบ commit message ได้ทุก flow ที่สร้าง version (Save & Version / Start Versioning / generate จากเว็บ) + แสดงใน version history ทุกหน้า - backend: DocumentVersion.Message (varchar 2048) + migration AddVersionMessage + BadRequest ตรวจความยาวก่อนแตะ MinIO (กัน 500 + orphan object) - add-in: ConfirmVersionDialog เพิ่ม textarea (Start Versioning ใช้ dialog ด้วย) + แสดง message ใน VersionHistoryPanel - web: ฟอร์มสร้างเอกสาร + หน้า detail แสดง message (desktop truncate + tooltip, mobile เต็มบรรทัด) - sync เอกสารทั้งหมด: spec v5 (FR-13/AC-16) + plan Phase 9 + acceptance-review 1–16 + README + CLAUDE.md + web/README - tests: backend 52 / addin 50 / web 36 — เขียวทั้งชุด Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Suphonchai Phoonsawat
parent
b47667f918
commit
7b20f12ede
28 changed files with 928 additions and 141 deletions
|
|
@ -32,6 +32,8 @@ export interface VersionRecord {
|
|||
/** SHA256 hex */
|
||||
contentHash: string;
|
||||
fields: FieldsSnapshot | null;
|
||||
/** คำอธิบาย version แบบ commit message ที่ผู้ใช้พิมพ์ตอนสร้าง (FR-13) — null ได้ */
|
||||
message: string | null;
|
||||
}
|
||||
|
||||
/** อ่านค่า + สถานะ missing ของ field หนึ่งจาก snapshot ไม่ว่าจะเก็บรูปแบบไหน — ไม่มี field นี้คืน null */
|
||||
|
|
|
|||
|
|
@ -117,6 +117,20 @@ describe("startVersioning (FR-1 / AC-5)", () => {
|
|||
const { form } = parseUploadCall(fetchMock.mock.calls[0] as [string, { body?: FormData }]);
|
||||
expect(String((form.get("file") as File).name)).toMatch(/\.docx$/);
|
||||
});
|
||||
|
||||
it("FR-13 — ส่ง message แนบไปกับ multipart form ของ v1", async () => {
|
||||
installWordMock({});
|
||||
installOfficeDocumentMock(undefined);
|
||||
const fetchMock = installFetchMock();
|
||||
fetchMock.mockImplementationOnce(async () =>
|
||||
mockResponse({ status: 201, body: { versionId: "v", versionNumber: 1 } })
|
||||
);
|
||||
|
||||
await startVersioning("เริ่มติดตามฉบับแรก");
|
||||
|
||||
const { form } = parseUploadCall(fetchMock.mock.calls[0] as [string, { body?: FormData }]);
|
||||
expect(String(form.get("message"))).toBe("เริ่มติดตามฉบับแรก");
|
||||
});
|
||||
});
|
||||
|
||||
describe("saveAndVersion (FR-2 / AC-7, 13)", () => {
|
||||
|
|
@ -213,4 +227,42 @@ describe("saveAndVersion (FR-2 / AC-7, 13)", () => {
|
|||
versionNumber: 2,
|
||||
});
|
||||
});
|
||||
|
||||
it("FR-13 — ส่ง message แนบไปกับ multipart form", async () => {
|
||||
installWordMock({
|
||||
properties: {
|
||||
SavedByAddIn: ADDIN_SIGNATURE_GUID,
|
||||
DocumentTrackingId: "11111111-1111-1111-1111-111111111111",
|
||||
},
|
||||
});
|
||||
installOfficeDocumentMock(undefined);
|
||||
const fetchMock = installFetchMock();
|
||||
fetchMock.mockImplementationOnce(async () =>
|
||||
mockResponse({ status: 201, body: { versionId: "backend-version-2", versionNumber: 2 } })
|
||||
);
|
||||
|
||||
await saveAndVersion("11111111-1111-1111-1111-111111111111", 1, "แก้ไขสัญญาข้อ 3");
|
||||
|
||||
const { form } = parseUploadCall(fetchMock.mock.calls[0] as [string, { body?: FormData }]);
|
||||
expect(String(form.get("message"))).toBe("แก้ไขสัญญาข้อ 3");
|
||||
});
|
||||
|
||||
it("FR-13 — message ว่าง/whitespace ล้วน → ไม่แนบฟิลด์ message เลย", async () => {
|
||||
installWordMock({
|
||||
properties: {
|
||||
SavedByAddIn: ADDIN_SIGNATURE_GUID,
|
||||
DocumentTrackingId: "11111111-1111-1111-1111-111111111111",
|
||||
},
|
||||
});
|
||||
installOfficeDocumentMock(undefined);
|
||||
const fetchMock = installFetchMock();
|
||||
fetchMock.mockImplementationOnce(async () =>
|
||||
mockResponse({ status: 201, body: { versionId: "backend-version-2", versionNumber: 2 } })
|
||||
);
|
||||
|
||||
await saveAndVersion("11111111-1111-1111-1111-111111111111", 1, " ");
|
||||
|
||||
const { form } = parseUploadCall(fetchMock.mock.calls[0] as [string, { body?: FormData }]);
|
||||
expect(form.get("message")).toBeNull();
|
||||
});
|
||||
});
|
||||
|
|
|
|||
|
|
@ -70,15 +70,18 @@ async function saveDocument(): Promise<void> {
|
|||
async function uploadCurrentFile(
|
||||
documentId: string,
|
||||
clientVersionId: string,
|
||||
fields: Record<string, string>
|
||||
fields: Record<string, string>,
|
||||
message?: string
|
||||
): Promise<{ versionId: string; versionNumber: number }> {
|
||||
const file = await getCurrentDocumentFile();
|
||||
return uploadVersion(documentId, file, clientVersionId, fields, guessDocumentFileName());
|
||||
return uploadVersion(documentId, file, clientVersionId, fields, guessDocumentFileName(), message);
|
||||
}
|
||||
|
||||
/** FR-1 — เริ่ม track เอกสารปัจจุบัน: stamp รอบแรก + upload เป็น version 1 */
|
||||
/** FR-1 — เริ่ม track เอกสารปัจจุบัน: stamp รอบแรก + upload เป็น version 1
|
||||
* (FR-13: message คือ commit message ทางเลือกจาก dialog ยืนยัน) */
|
||||
export async function startVersioning(
|
||||
onProgress?: (message: string) => void
|
||||
message?: string,
|
||||
onProgress?: (progress: string) => void
|
||||
): Promise<StartVersioningResult> {
|
||||
const documentId = generateGuid();
|
||||
const clientVersionId = generateGuid();
|
||||
|
|
@ -106,15 +109,17 @@ export async function startVersioning(
|
|||
|
||||
// 4) upload version แรก
|
||||
onProgress?.("กำลังอัปโหลด version 1…");
|
||||
const result = await uploadCurrentFile(documentId, clientVersionId, fields);
|
||||
const result = await uploadCurrentFile(documentId, clientVersionId, fields, message);
|
||||
return { documentId, ...result };
|
||||
}
|
||||
|
||||
/** FR-2 — Save & Version ของเอกสารที่ track อยู่แล้ว (เรียกหลังผู้ใช้กดยืนยันใน dialog แล้ว) */
|
||||
/** FR-2 — Save & Version ของเอกสารที่ track อยู่แล้ว (เรียกหลังผู้ใช้กดยืนยันใน dialog แล้ว)
|
||||
* (FR-13: message คือ commit message ทางเลือกจาก dialog ยืนยัน) */
|
||||
export async function saveAndVersion(
|
||||
documentId: string,
|
||||
latestVersionNumber: number,
|
||||
onProgress?: (message: string) => void
|
||||
message?: string,
|
||||
onProgress?: (progress: string) => void
|
||||
): Promise<SaveAndVersionResult> {
|
||||
const clientVersionId = generateGuid();
|
||||
const timestamp = new Date().toISOString();
|
||||
|
|
@ -142,7 +147,7 @@ export async function saveAndVersion(
|
|||
|
||||
// 4) upload
|
||||
onProgress?.("กำลังอัปโหลด version ใหม่…");
|
||||
const result = await uploadCurrentFile(documentId, clientVersionId, fields);
|
||||
const result = await uploadCurrentFile(documentId, clientVersionId, fields, message);
|
||||
|
||||
// 5) เลขจริงจาก backend ต่างจากที่เดา (มี client อื่นแทรก) → แก้ XML part ให้ตรง (best effort)
|
||||
if (result.versionNumber !== predictedNumber) {
|
||||
|
|
|
|||
|
|
@ -8,13 +8,15 @@ import { generateGuid } from "./metadataService";
|
|||
* `fields` = map จาก `readContentControlFields()` ตาม FR-11
|
||||
*/
|
||||
|
||||
/** FR-5 — อัปโหลดไฟล์ปัจจุบันเป็น version ใหม่ (แนบ fields map ถ้ามี) */
|
||||
/** FR-5 — อัปโหลดไฟล์ปัจจุบันเป็น version ใหม่ (แนบ fields map ถ้ามี)
|
||||
* + FR-13: แนบ commit message ทางเลือกของผู้ใช้ */
|
||||
export async function uploadVersion(
|
||||
documentId: string,
|
||||
file: Blob,
|
||||
clientVersionId: string,
|
||||
fields?: Record<string, string>,
|
||||
fileName?: string
|
||||
fileName?: string,
|
||||
message?: string
|
||||
): Promise<UploadVersionResult> {
|
||||
const form = new FormData();
|
||||
form.append("file", file, fileName || `${documentId}.docx`);
|
||||
|
|
@ -22,6 +24,10 @@ export async function uploadVersion(
|
|||
if (fields && Object.keys(fields).length > 0) {
|
||||
form.append("fields", JSON.stringify(fields));
|
||||
}
|
||||
const trimmedMessage = message?.trim();
|
||||
if (trimmedMessage) {
|
||||
form.append("message", trimmedMessage);
|
||||
}
|
||||
return apiSendExpectJson<UploadVersionResult>(
|
||||
`/api/documents/${documentId}/versions`,
|
||||
{ method: "POST", body: form },
|
||||
|
|
|
|||
|
|
@ -87,6 +87,7 @@ const App: React.FC = () => {
|
|||
const [saving, setSaving] = React.useState(false);
|
||||
const [progressMessage, setProgressMessage] = React.useState<string | null>(null);
|
||||
const [confirmOpen, setConfirmOpen] = React.useState(false);
|
||||
const [startConfirmOpen, setStartConfirmOpen] = React.useState(false);
|
||||
const [flowError, setFlowError] = React.useState<string | null>(null);
|
||||
const [flowSuccess, setFlowSuccess] = React.useState<string | null>(null);
|
||||
|
||||
|
|
@ -209,13 +210,13 @@ const App: React.FC = () => {
|
|||
setPhase("signed-out");
|
||||
};
|
||||
|
||||
/** Start Versioning — stamp รอบแรก + upload v1 (FR-1/AC-5) */
|
||||
const handleStartVersioning = async () => {
|
||||
/** Start Versioning — stamp รอบแรก + upload v1 (FR-1/AC-5) · message คือ commit message จาก dialog (FR-13) */
|
||||
const handleStartVersioning = async (message: string) => {
|
||||
setStarting(true);
|
||||
setFlowError(null);
|
||||
setFlowSuccess(null);
|
||||
try {
|
||||
const result = await startVersioning(setProgressMessage);
|
||||
const result = await startVersioning(message, setProgressMessage);
|
||||
setDocumentId(result.documentId);
|
||||
setPhase("tracking");
|
||||
setFlowSuccess(`เริ่มติดตามเอกสารนี้แล้ว — สร้างเป็น version 1`);
|
||||
|
|
@ -230,8 +231,9 @@ const App: React.FC = () => {
|
|||
}
|
||||
};
|
||||
|
||||
/** Save & Version (FR-2) — ตามลำดับ spec: confirm → stamp → XML → save → file+fields → upload */
|
||||
const handleSaveAndVersion = async () => {
|
||||
/** Save & Version (FR-2) — ตามลำดับ spec: confirm → stamp → XML → save → file+fields → upload
|
||||
* message คือ commit message จาก dialog (FR-13) */
|
||||
const handleSaveAndVersion = async (message: string) => {
|
||||
if (!documentId) {
|
||||
return;
|
||||
}
|
||||
|
|
@ -240,7 +242,7 @@ const App: React.FC = () => {
|
|||
setFlowSuccess(null);
|
||||
try {
|
||||
const latestVersionNumber = versions[0]?.versionNumber ?? 0;
|
||||
const result = await saveAndVersion(documentId, latestVersionNumber, setProgressMessage);
|
||||
const result = await saveAndVersion(documentId, latestVersionNumber, message, setProgressMessage);
|
||||
setFlowSuccess(`สร้าง version ${result.versionNumber} เรียบร้อย`);
|
||||
await refreshHistory(documentId);
|
||||
} catch (error) {
|
||||
|
|
@ -349,7 +351,7 @@ const App: React.FC = () => {
|
|||
appearance="primary"
|
||||
icon={<DocumentArrowUp24Regular />}
|
||||
disabled={starting}
|
||||
onClick={() => void handleStartVersioning()}
|
||||
onClick={() => setStartConfirmOpen(true)}
|
||||
>
|
||||
{starting ? "กำลังเริ่มติดตาม…" : "Start Versioning This Document"}
|
||||
</Button>
|
||||
|
|
@ -422,9 +424,20 @@ const App: React.FC = () => {
|
|||
<ConfirmVersionDialog
|
||||
open={confirmOpen}
|
||||
busy={saving}
|
||||
onConfirm={() => void handleSaveAndVersion()}
|
||||
onConfirm={(message) => void handleSaveAndVersion(message)}
|
||||
onDismiss={() => setConfirmOpen(false)}
|
||||
/>
|
||||
|
||||
{/* FR-13 — Start Versioning ใช้ dialog เดียวกัน: ยืนยัน + พิมพ์ commit message ของ v1 ก่อนเริ่ม track */}
|
||||
<ConfirmVersionDialog
|
||||
open={startConfirmOpen}
|
||||
busy={starting}
|
||||
title="เริ่มติดตามเอกสารนี้?"
|
||||
description="ระบบจะ stamp metadata ลงไฟล์และบันทึกไฟล์ปัจจุบันเป็น version 1 ของเอกสารนี้"
|
||||
confirmLabel="เริ่มติดตาม (version 1)"
|
||||
onConfirm={(message) => void handleStartVersioning(message)}
|
||||
onDismiss={() => setStartConfirmOpen(false)}
|
||||
/>
|
||||
</div>
|
||||
);
|
||||
};
|
||||
|
|
|
|||
|
|
@ -7,31 +7,68 @@ import {
|
|||
DialogContent,
|
||||
DialogSurface,
|
||||
DialogTitle,
|
||||
Field,
|
||||
Spinner,
|
||||
Textarea,
|
||||
} from "@fluentui/react-components";
|
||||
|
||||
interface ConfirmVersionDialogProps {
|
||||
open: boolean;
|
||||
/** กำลังอยู่ระหว่าง flow หลังกดยืนยันแล้ว — ปุ่นทั้งสอง disable + แสดง spinner */
|
||||
/** กำลังอยู่ระหว่าง flow หลังกดยืนยันแล้ว — ปุ่มทั้งสอง disable + แสดง spinner */
|
||||
busy: boolean;
|
||||
onConfirm: () => void;
|
||||
/** ปรับข้อความตอน reuse กับ flow อื่น (FR-13 — Start Versioning ใช้ dialog ตัวเดียวกัน) */
|
||||
title?: string;
|
||||
description?: React.ReactNode;
|
||||
confirmLabel?: string;
|
||||
/** ได้รับ commit message ที่ผู้ใช้พิมพ์ (FR-13) — ว่างได้ */
|
||||
onConfirm: (message: string) => void;
|
||||
onDismiss: () => void;
|
||||
}
|
||||
|
||||
/** FR-2 ขั้นตอนที่ 1 — dialog ยืนยัน "สร้าง version ใหม่ของเอกสารนี้หรือไม่?" */
|
||||
const DEFAULT_TITLE = "สร้าง version ใหม่?";
|
||||
const DEFAULT_DESCRIPTION = "ระบบจะบันทึกไฟล์ปัจจุบันและอัปโหลดเป็น version ถัดไปของเอกสารนี้";
|
||||
const DEFAULT_CONFIRM_LABEL = "สร้าง version";
|
||||
|
||||
/** FR-2 ขั้นตอนที่ 1 — dialog ยืนยัน "สร้าง version ใหม่ของเอกสารนี้หรือไม่?" พร้อมช่องคำอธิบาย version
|
||||
* แบบ commit message ทางเลือก (FR-13) — ใช้ร่วมกับทั้ง Save & Version และ Start Versioning */
|
||||
export const ConfirmVersionDialog: React.FC<ConfirmVersionDialogProps> = ({
|
||||
open,
|
||||
busy,
|
||||
title,
|
||||
description,
|
||||
confirmLabel,
|
||||
onConfirm,
|
||||
onDismiss,
|
||||
}) => {
|
||||
const [message, setMessage] = React.useState("");
|
||||
|
||||
// component ถูก mount ค้างไว้ตลอด (App render ไว้นอก phase branch) — ต้องเคลียร์ค่าตอนปิด
|
||||
// ไม่ใช่ตอน unmount ไม่งั้นข้อความรอบก่อนหลุดมารอบถัดไป
|
||||
React.useEffect(() => {
|
||||
if (!open) {
|
||||
setMessage("");
|
||||
}
|
||||
}, [open]);
|
||||
|
||||
return (
|
||||
<Dialog open={open} onOpenChange={(_event, data) => !data.open && !busy && onDismiss()} modalType="alert">
|
||||
<DialogSurface>
|
||||
<DialogBody>
|
||||
<DialogTitle>สร้าง version ใหม่?</DialogTitle>
|
||||
<DialogTitle>{title ?? DEFAULT_TITLE}</DialogTitle>
|
||||
<DialogContent>
|
||||
ระบบจะบันทึกไฟล์ปัจจุบันและอัปโหลดเป็น version ถัดไปของเอกสารนี้
|
||||
{description ?? DEFAULT_DESCRIPTION}
|
||||
<Field label="คำอธิบาย version (ไม่บังคับ)" style={{ marginTop: 12 }}>
|
||||
<Textarea
|
||||
value={message}
|
||||
onChange={(_event, data) => setMessage(data.value)}
|
||||
placeholder="เช่น แก้ไขข้อ 3 สัญญาจ้าง"
|
||||
maxLength={2048}
|
||||
resize="vertical"
|
||||
rows={3}
|
||||
disabled={busy}
|
||||
textarea={{ "aria-label": "คำอธิบาย version" }}
|
||||
/>
|
||||
</Field>
|
||||
{busy ? (
|
||||
<div style={{ display: "flex", alignItems: "center", gap: 8, marginTop: 12 }}>
|
||||
<Spinner size="tiny" /> กำลังดำเนินการ…
|
||||
|
|
@ -42,8 +79,8 @@ export const ConfirmVersionDialog: React.FC<ConfirmVersionDialogProps> = ({
|
|||
<Button appearance="secondary" disabled={busy} onClick={onDismiss}>
|
||||
ยกเลิก
|
||||
</Button>
|
||||
<Button appearance="primary" disabled={busy} onClick={onConfirm}>
|
||||
สร้าง version
|
||||
<Button appearance="primary" disabled={busy} onClick={() => onConfirm(message)}>
|
||||
{confirmLabel ?? DEFAULT_CONFIRM_LABEL}
|
||||
</Button>
|
||||
</DialogActions>
|
||||
</DialogBody>
|
||||
|
|
|
|||
|
|
@ -55,6 +55,12 @@ const useStyles = makeStyles({
|
|||
color: tokens.colorNeutralForeground3,
|
||||
fontSize: tokens.fontSizeBase200,
|
||||
},
|
||||
messageRow: {
|
||||
color: tokens.colorNeutralForeground2,
|
||||
fontSize: tokens.fontSizeBase200,
|
||||
whiteSpace: "pre-wrap",
|
||||
overflowWrap: "anywhere",
|
||||
},
|
||||
});
|
||||
|
||||
function formatTimestamp(iso: string): string {
|
||||
|
|
@ -109,6 +115,9 @@ export const VersionHistoryPanel: React.FC<VersionHistoryPanelProps> = ({
|
|||
</Badge>
|
||||
<span className={styles.metaRow}>{formatTimestamp(version.createdAt)}</span>
|
||||
<span className={styles.metaRow}>โดย {version.createdByUserId}</span>
|
||||
{version.message ? (
|
||||
<span className={styles.messageRow}>{version.message}</span>
|
||||
) : null}
|
||||
</div>
|
||||
<Button
|
||||
icon={<ArrowDownload24Regular />}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue