# 文件管理系統實作計劃

## 🎯 目標
實作 ISO 27001 文件管理系統，支援政策文件的建立、審核、發布、簽署和版本管理。

## 📅 實作時間：3-4 天

---

## 🏗️ 架構設計

### 後端模型 (Django Models)

#### 1. DocumentCategory (文件分類)
```python
- id: UUID
- name: 政策/程序/指引/表單
- order: 排序
- icon: 圖示
- description: 說明
```

#### 2. Document (文件主表)
```python
- id: UUID
- organization_id: 組織
- document_number: 文件編號 (唯一)
- title: 標題
- category: 分類 FK
- version: 版本號
- status: 狀態 (draft/review/approved/published/archived)
- content: 內容 (富文本)
- template_variables: JSON 範本變數
- created_by: 建立者
- reviewed_by: 審查者
- approved_by: 核准者
- published_at: 發布時間
- review_cycle_months: 審查週期 (月)
- next_review_date: 下次審查日期
- related_controls: M2M 關聯控制措施
- created_at, updated_at
```

#### 3. DocumentVersion (文件版本歷史)
```python
- id: UUID
- document_id: FK
- version: 版本號
- content: 內容快照
- change_summary: 變更摘要
- created_by: 建立者
- created_at: 建立時間
```

#### 4. DocumentAcknowledgment (文件簽署記錄)
```python
- id: UUID
- document_id: FK
- user_id: FK
- acknowledged_at: 簽署時間
- ip_address: IP
- signature_data: 電子簽章
- UNIQUE(document_id, user_id)
```

#### 5. DocumentTemplate (文件範本)
```python
- id: UUID
- name: 範本名稱
- category: 分類
- template_content: 範本內容
- variables: JSON 可用變數
- is_active: 是否啟用
```

---

## 📁 檔案結構

```
backend/
├── documents/
│   ├── models.py          # 文件模型
│   ├── serializers.py     # API 序列化器
│   ├── views.py           # ViewSet (CRUD + 工作流)
│   ├── urls.py            # URL 路由
│   ├── permissions.py     # 權限檢查
│   ├── utils.py           # 工具函式 (範本引擎)
│   └── migrations/
│
frontend/src/
├── types/
│   └── document.ts        # TypeScript 型別
├── api/
│   └── documents.ts       # API 呼叫
├── pages/
│   ├── DocumentList.tsx   # 文件列表
│   ├── DocumentForm.tsx   # 新增/編輯文件
│   ├── DocumentView.tsx   # 文件查看
│   └── DocumentTemplates.tsx  # 範本管理
└── components/
    ├── DocumentStatus.tsx     # 狀態標籤
    ├── DocumentWorkflow.tsx   # 工作流按鈕
    └── SignatureModal.tsx     # 簽署對話框
```

---

## 🔄 工作流設計

### 文件生命週期
```
草稿 (draft)
  ↓ submit_for_review
審查中 (review)
  ↓ approve
已核准 (approved)
  ↓ publish
已發布 (published)
  ↓ archive (可選)
已歸檔 (archived)
```

### API 端點

**基本 CRUD**
- `GET /api/documents/` - 列表
- `GET /api/documents/{id}/` - 詳情
- `POST /api/documents/` - 新增
- `PUT /api/documents/{id}/` - 更新
- `DELETE /api/documents/{id}/` - 刪除

**工作流操作**
- `POST /api/documents/{id}/submit_for_review/` - 提交審查
- `POST /api/documents/{id}/approve/` - 核准
- `POST /api/documents/{id}/publish/` - 發布
- `POST /api/documents/{id}/acknowledge/` - 簽署
- `POST /api/documents/{id}/archive/` - 歸檔

**查詢端點**
- `GET /api/documents/pending_acknowledgment/` - 待簽署清單
- `GET /api/documents/review_due/` - 待審查清單
- `GET /api/documents/statistics/` - 統計資料

**範本相關**
- `GET /api/document-templates/` - 範本列表
- `POST /api/documents/from_template/` - 從範本建立

**版本相關**
- `GET /api/documents/{id}/versions/` - 版本歷史
- `GET /api/documents/{id}/compare/{v1}/{v2}/` - 版本比較

**匯出**
- `GET /api/documents/{id}/export/pdf/` - PDF 匯出
- `GET /api/documents/{id}/export/word/` - Word 匯出

---

## 🎨 前端頁面設計

### 1. DocumentList.tsx (文件列表)
**功能：**
- 分類篩選 (政策/程序/指引/表單)
- 狀態篩選
- 搜尋
- 統計卡片：總數、待簽署、待審查
- 批次操作
- 匯出

**UI 元素：**
```tsx
<PageHeader title="文件管理" />
<Statistics cards={[total, pending, reviewDue]} />
<Filters />
<Table columns={[number, title, category, status, version, publishedDate]} />
<Pagination />
```

### 2. DocumentView.tsx (文件查看)
**功能：**
- 顯示文件內容 (富文本)
- 文件資訊區塊
- 版本歷史
- 簽署狀態與進度
- 關聯控制措施
- 版本比較

**UI 元素：**
```tsx
<DocumentHeader info={doc} actions={[edit, download, print]} />
<DocumentInfo metadata={doc} />
<Tabs>
  <TabPane key="content" tab="內容">
    <RichTextDisplay content={doc.content} />
  </TabPane>
  <TabPane key="versions" tab="版本歷史">
    <VersionHistory versions={versions} />
  </TabPane>
  <TabPane key="signatures" tab="簽署記錄">
    <SignatureList signatures={signatures} />
  </TabPane>
  <TabPane key="controls" tab="控制措施">
    <ControlList controls={doc.related_controls} />
  </TabPane>
</Tabs>
{!signed && <SignButton onClick={showSignModal} />}
```

### 3. DocumentForm.tsx (新增/編輯)
**功能：**
- 基本資訊輸入
- 富文本編輯器
- 關聯控制措施選擇
- 範本變數替換
- 草稿儲存

**表單欄位：**
- 文件編號 (自動生成)
- 標題 *
- 分類 * (下拉)
- 內容 * (富文本編輯器)
- 審查週期 (月)
- 關聯控制措施 (多選)

### 4. DocumentTemplates.tsx (範本管理)
**功能：**
- 預設範本列表
- 從範本建立文件
- 自訂範本 (管理員)
- 範本預覽

---

## 🔧 技術實作細節

### 1. 範本引擎 (Jinja2)

**backend/documents/utils.py**
```python
from jinja2 import Template

class DocumentTemplateEngine:
    def __init__(self, organization):
        self.org = organization
    
    def get_context(self):
        return {
            'company_name': self.org.name,
            'company_address': self.org.address,
            'current_date': datetime.now().strftime('%Y-%m-%d'),
            'current_year': datetime.now().year,
        }
    
    def render(self, template_content, custom_vars=None):
        context = self.get_context()
        if custom_vars:
            context.update(custom_vars)
        template = Template(template_content)
        return template.render(**context)
```

### 2. 文件編號自動生成

**格式：** `DOC-{CATEGORY}-{SEQUENCE}`
- 政策: `DOC-POL-001`
- 程序: `DOC-PRO-001`
- 指引: `DOC-GUI-001`
- 表單: `DOC-FRM-001`

```python
def generate_document_number(category):
    prefix_map = {
        'policy': 'POL',
        'procedure': 'PRO',
        'instruction': 'GUI',
        'form': 'FRM',
    }
    prefix = prefix_map.get(category, 'DOC')
    
    last_doc = Document.objects.filter(
        document_number__startswith=f'DOC-{prefix}-'
    ).order_by('-document_number').first()
    
    if last_doc:
        last_num = int(last_doc.document_number.split('-')[-1])
        new_num = last_num + 1
    else:
        new_num = 1
    
    return f'DOC-{prefix}-{new_num:03d}'
```

### 3. 版本控制

**版本號規則：** `major.minor`
- major: 重大變更 (需重新簽署)
- minor: 小修正

```python
def create_version(document, change_summary, is_major=False):
    current_version = document.version  # e.g., "1.2"
    major, minor = map(int, current_version.split('.'))
    
    if is_major:
        new_version = f"{major + 1}.0"
    else:
        new_version = f"{major}.{minor + 1}"
    
    # 建立版本記錄
    DocumentVersion.objects.create(
        document=document,
        version=current_version,
        content=document.content,
        change_summary=change_summary,
        created_by=request.user
    )
    
    # 更新文件版本
    document.version = new_version
    document.save()
    
    return new_version
```

### 4. 電子簽章 (簡化版)

```python
# 簽署時記錄
def acknowledge_document(document, user, request):
    signature = DocumentAcknowledgment.objects.create(
        document=document,
        user=user,
        ip_address=get_client_ip(request),
        signature_data=f"{user.get_full_name()} - {datetime.now()}"
    )
    return signature
```

### 5. 權限設計

**權限矩陣：**
```
角色            | 查看 | 新增 | 編輯 | 審查 | 核准 | 發布 | 刪除 |
---------------|-----|-----|-----|-----|-----|-----|-----|
SuperAdmin     |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |
SecurityOfficer|  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |
Auditor        |  ✓  |  ✓  |  ✓  |  ✓  |  ✗  |  ✗  |  ✗  |
Employee       |  ✓  |  ✗  |  ✗  |  ✗  |  ✗  |  ✗  |  ✗  |
```

---

## 📦 預設範本

### 範本 1: 資訊安全政策
```markdown
# {{company_name}} 資訊安全政策

**版本：** 1.0
**發布日期：** {{current_date}}
**核准者：** 總經理

## 一、目的
本政策旨在保護 {{company_name}} 之資訊資產，確保資訊的機密性、完整性及可用性。

## 二、適用範圍
本政策適用於 {{company_name}} 全體員工及承包商。

## 三、資訊安全目標
1. 保護客戶資料，防止未經授權之存取
2. 確保關鍵業務系統可用性達 99.5% 以上
3. 符合個資法及相關法規要求

## 四、資訊安全原則

### 4.1 機密性 (Confidentiality)
- 資訊僅限授權人員存取
- 依資料敏感度分級管理
- 傳輸及儲存時採用加密保護

### 4.2 完整性 (Integrity)
- 防止資料遭未經授權之竄改
- 建立變更控制機制
- 定期驗證資料正確性

### 4.3 可用性 (Availability)
- 確保授權使用者可及時存取資訊
- 建立備份及災難復原機制
- 監控系統效能

## 五、角色與責任

### 5.1 最高管理階層
- 核准資訊安全政策
- 提供資源支持

### 5.2 資訊安全委員會
- 定期檢討資安執行狀況

### 5.3 資訊安全主管
- 統籌資安管理制度
- 處理資安事件

### 5.4 全體員工
- 遵守資訊安全政策
- 通報可疑事件

## 六、違反政策之處置
依情節輕重：警告、記過、停職、解僱、法律追訴

## 七、政策審查
本政策每年至少審查一次

---
核准簽章：_______________
日期：_______________
```

### 範本 2: 存取控制程序
```markdown
# {{company_name}} 存取控制程序

**版本：** 1.0
**發布日期：** {{current_date}}

## 一、目的
確保只有授權人員可存取資訊系統及資料

## 二、帳號管理

### 2.1 帳號申請
1. 填寫「帳號申請表」
2. 部門主管核准
3. IT 部門開通
4. 記錄開通日期

### 2.2 帳號變更
職務調動時重新審核權限

### 2.3 帳號停用
離職當天立即停用

## 三、權限管理

### 3.1 最小權限原則
僅給予業務所需的最小權限

### 3.2 權限分級
- Level 1: 一般使用者
- Level 2: 部門管理者
- Level 3: 系統管理員

## 四、密碼政策
- 最小長度：12 字元
- 複雜度：大小寫+數字+特殊符號
- 定期更換：每 90 天

## 五、審查
每半年審查一次所有帳號權限
```

---

## 🧪 測試計劃

### 單元測試
```python
# tests/test_document_models.py
def test_document_number_generation()
def test_version_increment()
def test_workflow_transitions()
def test_acknowledgment_uniqueness()
```

### API 測試
```bash
# 建立文件
POST /api/documents/
{
  "title": "資訊安全政策",
  "category": "policy",
  "content": "..."
}

# 提交審查
POST /api/documents/1/submit_for_review/

# 核准
POST /api/documents/1/approve/

# 發布
POST /api/documents/1/publish/

# 簽署
POST /api/documents/1/acknowledge/
```

### E2E 測試
```javascript
// 使用 Playwright
test('完整文件工作流', async ({ page }) => {
  // 登入
  await login(page, 'admin')
  
  // 新增文件
  await page.goto('/documents/new')
  await page.fill('[name="title"]', '測試政策')
  await page.click('button:has-text("儲存草稿")')
  
  // 提交審查
  await page.click('button:has-text("提交審查")')
  
  // 核准
  await page.click('button:has-text("核准")')
  
  // 發布
  await page.click('button:has-text("發布")')
  
  // 驗證
  await expect(page.locator('.status-badge')).toContainText('已發布')
})
```

---

## 📊 驗收標準

### 功能性
- [x] 可新增文件
- [x] 可編輯文件
- [x] 可查看文件
- [x] 可刪除文件
- [x] 支援工作流 (草稿→審查→核准→發布)
- [x] 支援版本控制
- [x] 支援電子簽署
- [x] 支援範本
- [x] 支援搜尋篩選
- [x] 支援匯出 PDF

### 非功能性
- [x] API 回應時間 < 500ms
- [x] 支援 100+ 文件
- [x] 支援富文本編輯
- [x] 行動裝置友善
- [x] 權限控制正確

### UI/UX
- [x] 介面直覺易用
- [x] 載入狀態明確
- [x] 錯誤訊息清楚
- [x] 操作有回饋

---

## 📅 實作排程

### Day 1: 後端基礎
- [ ] 建立 models (Document, DocumentVersion, DocumentAcknowledgment)
- [ ] 建立 serializers
- [ ] 建立基本 ViewSet
- [ ] 建立 migrations
- [ ] 建立測試資料 seed

### Day 2: 後端工作流
- [ ] 實作工作流 actions
- [ ] 實作權限檢查
- [ ] 實作範本引擎
- [ ] 實作統計 API
- [ ] 單元測試

### Day 3: 前端列表與查看
- [ ] 建立 TypeScript types
- [ ] 建立 API 介面
- [ ] 實作 DocumentList 頁面
- [ ] 實作 DocumentView 頁面
- [ ] 實作狀態標籤元件

### Day 4: 前端表單與整合
- [ ] 實作 DocumentForm 頁面
- [ ] 實作富文本編輯器
- [ ] 實作簽署對話框
- [ ] 實作範本選擇器
- [ ] 整合測試

---

## 🚀 部署檢查清單

- [ ] migrations 已執行
- [ ] 預設範本已匯入
- [ ] 預設分類已建立
- [ ] 權限設定正確
- [ ] API 文件已更新
- [ ] 使用者手冊已更新

---

## 📚 參考資料

- ISO 27001:2022 Annex A.5.1 資訊安全政策
- Django 文件管理最佳實踐
- Jinja2 範本引擎文件
- React Rich Text Editor 整合

---

**預估完成時間：** 3-4 個工作天
**優先級：** 高 ⭐⭐⭐
**複雜度：** 中等
**依賴：** 認證系統、組織管理