From 79265dfb86ffb4bca815a878ac8f7e42a6eb640a Mon Sep 17 00:00:00 2001 From: Accusys Date: Fri, 15 May 2026 13:30:43 +0800 Subject: [PATCH] docs: unify file_uuid/identity_uuid naming in FILE_LIFECYCLE design doc --- docs_v1.0/DESIGN/FILE_LIFECYCLE_V1.0.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs_v1.0/DESIGN/FILE_LIFECYCLE_V1.0.md b/docs_v1.0/DESIGN/FILE_LIFECYCLE_V1.0.md index 9e87817..f92c14a 100644 --- a/docs_v1.0/DESIGN/FILE_LIFECYCLE_V1.0.md +++ b/docs_v1.0/DESIGN/FILE_LIFECYCLE_V1.0.md @@ -24,7 +24,7 @@ status: "draft" ``` SHA256 = DNA or fingerprint (immutable biometric identity) file mtime = birth moment (preserved by rsync across systems) -birthday (UUID anchor) = mtime timestamp +birthday (file_uuid anchor) = mtime timestamp .pre.json = birth certificate POST /api/v1/files/register = civil registration status = registered = citizenship completed @@ -36,7 +36,7 @@ A file enters the system in two distinct phases: | Phase | Action | Analogy | Automatic? | Status | |-------|--------|---------|:----------:|:------:| -| **Birth** | Pre-process: SHA256 + probe + UUID | 出生 + 醫院開出生證明 | ✅ Watcher | `unregistered` | +| **Birth** | Pre-process: SHA256 + probe + file_uuid | 出生 + 醫院開出生證明 | ✅ Watcher | `unregistered` | | **Citizenship** | Register: INSERT into DB | 戶政事務所登記 | ❌ User API | `registered` | ## Phase 1: Pre-Processing (Birth) @@ -92,17 +92,17 @@ Stored alongside other processor outputs: } ``` -### Key Design: UUID = f(mac, birthday, path, filename) +### Key Design: file_uuid = f(mac, birthday, path, filename) -The `birthday` is `file modification time` (mtime) — obtained from `fs::metadata().modified()`. Using mtime instead of birthtime ensures UUID stability when files are transferred between systems via rsync (which preserves mtime but not birthtime on macOS). +The `birthday` is `file modification time` (mtime) — obtained from `fs::metadata().modified()`. Using mtime instead of birthtime ensures file_uuid stability when files are transferred between systems via rsync (which preserves mtime but not birthtime on macOS). ``` birthday = 2026-05-15T02:15:00Z ← file birth time, never changes ↓ file_uuid = SHA256(mac | birthday | path | filename) ↓ -Same file: same path + filename → same UUID, regardless of registration count -Different files: different content_hash → different UUID (even if same name) +Same file: same path + filename → same file_uuid, regardless of registration count +Different files: different content_hash → different file_uuid (even if same name) ``` ## Phase 2: Registration (Citizenship) @@ -160,7 +160,7 @@ File detected by watcher (detection only, no modification) [Pre-Processor] ├─ SHA256 (DNA / fingerprint) ├─ ffprobe (metadata extraction) - └─ UUID (birth certificate ID) + └─ file_uuid (birth certificate ID) │ ▼ {file_uuid}.pre.json @@ -183,9 +183,9 @@ registration_time = NOW() | # | Task | File | |---|------|------| -| 1 | Expose `pre_process_file()` as public function (SHA256 + probe + UUID → `.pre.json`) | `src/watcher/watcher.rs` | +| 1 | Expose `pre_process_file()` as public function (SHA256 + probe + file_uuid → `.pre.json`) | `src/watcher/watcher.rs` | | 2 | Register: read `.pre.json`, skip SHA256/probe if cached | `src/api/server.rs` → `register_single_file` | -| 3 | UUID: use `birthday` from `.pre.json` (or `fs::metadata().created()` fallback) | `src/api/server.rs` | +| 3 | file_uuid: use `birthday` from `.pre.json` (or `fs::metadata().modified()` fallback) | `src/api/server.rs` | | 4 | INSERT status: `registered`, registration_time: `NOW()` | `src/api/server.rs` | @@ -195,4 +195,4 @@ registration_time = NOW() |---------|------|---------| | V1.0 | 2026-05-15 | Initial design — birth certificate (pre-process) + civil registration two-phase flow | | V1.1 | 2026-05-15 | Reclassified from DESIGN to STANDARDS as design standard | -| V1.2 | 2026-05-15 | mtime replaces birthtime for UUID stability across rsync; watcher is detection-only | +| V1.2 | 2026-05-15 | mtime replaces birthtime for file_uuid stability across rsync; watcher is detection-only |