admin/momentry_core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: unify file_uuid/identity_uuid naming in FILE_LIFECYCLE design doc

Browse Source
This commit is contained in:
Accusys
2026-05-15 13:30:43 +08:00
parent 5d899b7ada
commit 79265dfb86
1 changed files with 10 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
docs_v1.0/DESIGN/FILE_LIFECYCLE_V1.0.md
View File

@@ -24,7 +24,7 @@ status: "draft"
``` ```
SHA256 = DNA or fingerprint (immutable biometric identity) SHA256 = DNA or fingerprint (immutable biometric identity)
file mtime = birth moment (preserved by rsync across systems) file mtime = birth moment (preserved by rsync across systems)
birthday (UUID anchor) = mtime timestamp birthday (file_uuid anchor) = mtime timestamp
.pre.json = birth certificate .pre.json = birth certificate
POST /api/v1/files/register = civil registration POST /api/v1/files/register = civil registration
status = registered = citizenship completed status = registered = citizenship completed
@@ -36,7 +36,7 @@ A file enters the system in two distinct phases:
| Phase | Action | Analogy | Automatic? | Status | | 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` | | **Citizenship** | Register: INSERT into DB | 戶政事務所登記 | ❌ User API | `registered` |
## Phase 1: Pre-Processing (Birth) ## 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 birthday = 2026-05-15T02:15:00Z ← file birth time, never changes
↓ ↓
file_uuid = SHA256(mac | birthday | path | filename) file_uuid = SHA256(mac | birthday | path | filename)
↓ ↓
Same file: same path + filename → same UUID, regardless of registration count Same file: same path + filename → same file_uuid, regardless of registration count
Different files: different content_hash → different UUID (even if same name) Different files: different content_hash → different file_uuid (even if same name)
``` ```
## Phase 2: Registration (Citizenship) ## Phase 2: Registration (Citizenship)
@@ -160,7 +160,7 @@ File detected by watcher (detection only, no modification)
[Pre-Processor] [Pre-Processor]
├─ SHA256 (DNA / fingerprint) ├─ SHA256 (DNA / fingerprint)
├─ ffprobe (metadata extraction) ├─ ffprobe (metadata extraction)
└─ UUID (birth certificate ID) └─ file_uuid (birth certificate ID)
│ │
▼ ▼
{file_uuid}.pre.json {file_uuid}.pre.json
@@ -183,9 +183,9 @@ registration_time = NOW()
| # | Task | File | | # | 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` | | 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` | | 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.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.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 |