J-GAAP 書類管理 (電子帳簿保存法)

概要

公開・確定した書類は消さず、電子帳簿保存法の保存期間と監査証跡を守ります。ロック・無効化・復元など、J-GAAP に沿った書類ライフサイクルの実装メモです。

本文は英語のエンジニア向け仕様です。 保存の考え方だけ知りたい方は、セキュリティ／コンプライアンスの概要から読んでください。

技術メモ: Key Principles

電子帳簿保存法 Compliance

Data Retention: All documents must be retained for 7-10 years
No Physical Deletion: Documents are never permanently deleted
Audit Trail: All operations are logged with timestamps and user information
Void Over Delete: Published/locked documents cannot be deleted, must be voided with documented reason

技術メモ: Features

1. ロック/ロック解除（Document Locking ）

Purpose: Prevent accidental edits on finalized documents.

UI Location: Document Viewer Header → More Actions (⋮) → ロック/ロック解除

Behavior:

Locked documents display a "ロック中" badge in the header
Edit mode toggle is hidden for locked documents
Lock status can be toggled via the dropdown menu
Toast notifications confirm lock/unlock actions

API:

PATCH /api/documents/{documentId}/lock
Body: { "isLocked": boolean }

Frontend Files:

src/features/document/components/document-viewer-header.tsx - Lock toggle UI
src/features/document/components/document-viewer.tsx - Lock mutation handler
src/features/document/apis.ts - toggleLock() API function
src/features/document/queries.ts - useToggleLockMutation() hook

2. 論理削除（Soft Delete ）

Purpose: Mark documents as deleted without removing data (電子帳簿保存法 compliance).

UI Location:

Document Viewer Header → More Actions (⋮) → 削除
Document List Modal → Individual delete button (trash icon)
Document List Modal → Bulk Actions Bar → 削除

Behavior:

Sets deleted_at and deleted_by fields
Document is hidden from normal lists
Can be restored at any time
Only available for non-locked documents

API:

DELETE /api/documents/{documentId}

Frontend Files:

src/features/document-list/components/document-list-modal.tsx - Delete button UI
src/features/document/apis.ts - softDelete() API function
src/features/document/queries.ts - useSoftDeleteMutation() hook

3. 復元（Restore ）

Purpose: Restore soft-deleted documents.

UI Location: Document List Modal → Restore button (on deleted documents)

Behavior:

Clears deleted_at and deleted_by fields
Document reappears in normal lists
Only visible when "Show Deleted" filter is enabled

API:

POST /api/documents/{documentId}/restore

Frontend Files:

src/features/document-list/components/document-list-modal.tsx - Restore button UI
src/features/document/apis.ts - restore() API function
src/features/document/queries.ts - useRestoreMutation() hook

4. 無効化（Document Void ）

Purpose: Void accounting documents with documented reason (required for J-GAAP compliance when deletion is not allowed).

UI Location: Document Viewer Header → More Actions (⋮) → 書類を無効化

Behavior:

Sets is_voided, voided_at, voided_by, void_reason fields
Required for published/locked documents that cannot be deleted
Void reason is mandatory for audit compliance
Document remains in system with void status visible

API:

POST /api/documents/{documentId}/void
Body: { "reason": "void reason (required)" }

Frontend Files:

src/features/document/components/document-viewer-header.tsx - Void button UI
src/features/document/components/document-viewer.tsx - Void mutation handler
src/features/document/apis.ts - voidDocument() API function
src/features/document/queries.ts - useVoidDocumentMutation() hook

5. テンプレート複製（Document Duplication ）

Purpose: Create draft copies from existing documents for templating.

UI Location: Document Viewer Header → More Actions (⋮) → テンプレート複製

Behavior:

Creates new document with status "DRAFT"
Copies all content from source document
New document has unique ID
Navigates to the new duplicated document

API:

POST /api/documents/{documentId}/duplicate

Frontend Files:

src/features/document/components/document-viewer-header.tsx - Duplicate button UI
src/features/document/components/document-viewer.tsx - Duplicate mutation handler
src/features/document/apis.ts - duplicateDocument() API function
src/features/document/queries.ts - useDuplicateDocumentMutation() hook

6. 変更履歴（Activity Log ）

Purpose: View complete audit trail for document operations.

UI Location: Document Viewer Header → More Actions (⋮) → 変更履歴

Behavior:

Opens side panel with chronological activity list
Shows action type, user, timestamp
Pulls from version_control table
Supports filtering by action type

API:

GET /api/documents/{documentId}/activities

Frontend Files:

src/features/document/components/document-activity-log-panel.tsx - Activity log panel UI
src/features/document/apis.ts - getActivities() API function
src/features/document/queries.ts - useGetDocumentActivitiesQuery() hook

7. 一括操作（Bulk Operations ）

Purpose: Perform operations on multiple documents at once.

UI Location: Document List Modal → Select documents → Bulk Actions Bar

Features:

Select All / Clear Selection: Quick selection toggles
Bulk Lock: Lock multiple documents at once
Bulk Unlock: Unlock multiple documents at once
Bulk Delete: Soft delete multiple documents

Behavior:

Checkboxes appear on each document row
Bulk actions bar appears when documents are selected
Shows count of selected documents
Operations apply to all selected documents

API:

PATCH /api/documents/bulk/lock
Body: { "documentIds": string[], "isLocked": boolean }

DELETE /api/documents/bulk
Body: { "documentIds": string[] }

Frontend Files:

src/features/document-list/components/document-list-modal.tsx - Bulk selection UI
src/features/document/apis.ts - bulkLock(), bulkDelete() API functions
src/features/document/queries.ts - useBulkLockMutation(), useBulkDeleteMutation() hooks

8. 削除済みを表示（Show Deleted Filter ）

Purpose: Toggle visibility of soft-deleted documents.

UI Location: Document List Modal → Stats bar → Toggle switch

Behavior:

When enabled, shows deleted documents with visual distinction
Deleted documents have strikethrough styling
Restore button appears on deleted documents
Count badge shows number of deleted documents

Frontend Implementation:

Uses include_deleted query parameter
State managed in modal component
Visual distinction with amber/gray styling

技術メモ: Database Schema

技術メモ: Documents Table Additions

-- Soft delete fields
deleted_at TIMESTAMPTZ,
deleted_by UUID REFERENCES auth.users(id),

-- Void fields (for J-GAAP compliance)
is_voided BOOLEAN DEFAULT FALSE,
voided_at TIMESTAMPTZ,
voided_by UUID REFERENCES auth.users(id),
void_reason TEXT,

-- Lock field
is_locked BOOLEAN DEFAULT FALSE,

-- Indexes
CREATE INDEX idx_documents_deleted ON documents(is_deleted);
CREATE INDEX idx_documents_voided ON documents(is_voided);
CREATE INDEX idx_documents_user_deleted ON documents(user_id, is_deleted);

技術メモ: API Query Parameters

エンドポイント GET /api/documents

Parameter	Type	Description
`type`	string	Filter by document type
`page`	number	Page number (default: 1)
`pageSize`	number	Items per page (default: 20)
`include_deleted`	boolean	Include soft-deleted documents

UI コンポーネント

技術メモ: Document Viewer Header

The header toolbar organizes actions logically:

Row 1: Breadcrumb navigation

Row 2 (Left to Right):

Document selector with prev/next navigation
Lock status badge (when locked)
Auto-save status indicator
AI Analysis button
Document Guidance button
More Actions dropdown (⋮)
- ロック/ロック解除
- テンプレート複製
- 変更履歴
- 書類を無効化
- 削除 (only when not locked)

技術メモ: Document List Modal

Enhanced with J-GAAP features:

Header:

Document count badges (Draft / Confirmed / Deleted)
"Show Deleted" toggle switch

Document Row:

Selection checkbox
Document info (name, status, date)
Individual action buttons (Delete / Restore)

Bulk Actions Bar (appears when documents selected):

Selection count
Select All / Clear Selection
Bulk Lock / Unlock
Bulk Delete

技術メモ: Error Handling

技術メモ: Toast Messages (Japanese)

Action	Success	Error
Lock	ドキュメントをロックしました	ロック状態の変更に失敗しました
Unlock	ドキュメントのロックを解除しました	ロック状態の変更に失敗しました
Delete	ドキュメントを削除しました	削除に失敗しました
Restore	ドキュメントを復元しました	復元に失敗しました
Void	ドキュメントを無効化しました	無効化に失敗しました
Duplicate	ドキュメントを複製しました	複製に失敗しました
Bulk Lock	X件のドキュメントをロックしました	一括ロックに失敗しました
Bulk Delete	X件のドキュメントを削除しました	一括削除に失敗しました

技術メモ: Security Considerations

Authorization: All operations verify user ownership/permissions
Audit Logging: All operations logged with user ID and timestamp
Void Reason Required: Cannot void without documented reason
Lock Protection: Locked documents cannot be deleted (must void)
Soft Delete Only: No permanent deletion endpoint exposed

技術メモ: Future Enhancements

Void Reason Modal: Add proper modal for entering void reason
Activity Log Filtering: Filter by action type, date range
Bulk Void: Void multiple documents at once
Export Activity Log: Download audit trail as CSV/PDF
Document Recovery Period: Auto-permanent delete after X years (with warning)

J-GAAP 書類管理 (電子帳簿保存法)

概要

技術メモ: Key Principles

電子帳簿保存法 Compliance

技術メモ: Features

1. ロック/ロック解除（Document Locking ）

2. 論理削除（Soft Delete ）

3. 復元（Restore ）

4. 無効化（Document Void ）

5. テンプレート複製（Document Duplication ）

6. 変更履歴（Activity Log ）

7. 一括操作（Bulk Operations ）

8. 削除済みを表示（Show Deleted Filter ）

技術メモ: Database Schema

技術メモ: Documents Table Additions

技術メモ: API Query Parameters

エンドポイント GET /api/documents

UI コンポーネント

技術メモ: Document Viewer Header

技術メモ: Document List Modal

技術メモ: Error Handling

技術メモ: Toast Messages (Japanese)

技術メモ: Security Considerations

技術メモ: Future Enhancements

関連ドキュメント