migrate to new git
This commit is contained in:
191
data/memo/DRAFT_FIELD_IMPROVEMENT.md
Normal file
191
data/memo/DRAFT_FIELD_IMPROVEMENT.md
Normal file
@@ -0,0 +1,191 @@
|
||||
# Draft 欄位改進方案
|
||||
|
||||
## 問題描述
|
||||
|
||||
原本的 `draft` 欄位被用於兩種不同目的，導致資料結構混亂：
|
||||
|
||||
1. **暫存沖帳分配** - 在個人沖帳流程中暫存使用者的沖帳金額分配
|
||||
2. **歷史沖帳記錄** - 記錄已完成的沖帳明細
|
||||
|
||||
這導致兩種不同用途的資料互相覆蓋，造成資料不一致的問題。
|
||||
|
||||
## 改進方案
|
||||
|
||||
將原本的純陣列格式改為物件格式，包含兩個子陣列：
|
||||
|
||||
### 新的 draft 欄位格式
|
||||
```json
|
||||
{
|
||||
"transfer_draft": [
|
||||
{
|
||||
"pro_order_detail_num": "訂單明細編號",
|
||||
"reconcile": "沖帳金額"
|
||||
}
|
||||
],
|
||||
"pro_order_detail_items": [
|
||||
{
|
||||
"pro_order_detail_num": "訂單明細編號",
|
||||
"reconcile": "沖帳金額",
|
||||
"activity_name": "活動名稱",
|
||||
"actitem_name": "項目名稱",
|
||||
"price": "原始金額",
|
||||
"register_date": "報名日期",
|
||||
"order_no": "訂單編號"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 1. `transfer_draft` - 暫存沖帳分配
|
||||
**用途：**
|
||||
- 在 `personal_reconcile.aspx` 中暫存使用者的沖帳金額分配
|
||||
- 顯示 📝 圖示表示有暫存資料
|
||||
- 支援「暫存」和「重新分配」功能
|
||||
|
||||
### 2. `pro_order_detail_items` - 沖帳明細記錄
|
||||
**用途：**
|
||||
- 在 `balance_reconcile.aspx` 中顯示歷史沖帳記錄
|
||||
- 在 `balance_reconcile_query.aspx` 中顯示選取項目
|
||||
- 包含完整的活動和項目資訊
|
||||
|
||||
## 向後相容性
|
||||
|
||||
程式碼會自動檢測格式並處理：
|
||||
|
||||
### 新格式（物件）
|
||||
```json
|
||||
{
|
||||
"transfer_draft": [...],
|
||||
"pro_order_detail_items": [...]
|
||||
}
|
||||
```
|
||||
|
||||
### 舊格式（陣列）
|
||||
```json
|
||||
[
|
||||
{
|
||||
"pro_order_detail_num": "12345",
|
||||
"reconcile": 5000
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## 修改的檔案
|
||||
|
||||
### personal_reconcile.aspx
|
||||
- 更新 `loadFromDraftOrAutoDistribute()` 方法支援新舊格式
|
||||
- 更新 `saveDraft()` 方法使用新格式
|
||||
- 新增 `hasTransferDraft()` 方法檢查暫存資料
|
||||
- 更新顯示邏輯使用新格式
|
||||
|
||||
### balance_reconcile.aspx
|
||||
- 更新歷史記錄載入邏輯支援新格式
|
||||
- 更新詳細資訊顯示邏輯支援新格式
|
||||
- 保持向後相容性
|
||||
|
||||
### balance_reconcile_query.aspx
|
||||
- 更新 `getDraftItems()` 方法支援新舊格式
|
||||
- 更新項目顯示邏輯
|
||||
|
||||
## 資料安全保護機制
|
||||
|
||||
為了確保 `transfer_draft` 和 `pro_order_detail_items` 的操作互不影響，實作了以下保護機制：
|
||||
|
||||
### 1. 統一工具函數
|
||||
所有頁面都使用統一的 `draft-utils.js` 工具函數：
|
||||
- `window.DraftUtils.getDraftObject(draft)` - 安全解析 draft 欄位
|
||||
- `window.DraftUtils.getDraftField(draft, fieldName)` - 安全取得特定欄位
|
||||
- `window.DraftUtils.updateDraftField(draft, fieldName, newValue)` - 安全更新特定欄位
|
||||
- `window.DraftUtils.hasTransferDraft(draft)` - 檢查是否有暫存資料
|
||||
- `window.DraftUtils.hasProOrderDetailItems(draft)` - 檢查是否有歷史記錄
|
||||
|
||||
### 2. 操作範例
|
||||
|
||||
**更新 transfer_draft（不會影響 pro_order_detail_items）：**
|
||||
```javascript
|
||||
const currentDraft = this.dialog.selected.draft || '';
|
||||
const newTransferDraft = this.dialog.items
|
||||
.filter(item => Number(item.reconcile) > 0)
|
||||
.map(item => ({
|
||||
pro_order_detail_num: item.num,
|
||||
reconcile: Number(item.reconcile)
|
||||
}));
|
||||
|
||||
const newDraftObj = window.DraftUtils.updateDraftField(currentDraft, 'transfer_draft', newTransferDraft);
|
||||
```
|
||||
|
||||
**更新 pro_order_detail_items（不會影響 transfer_draft）：**
|
||||
```javascript
|
||||
const currentDraft = item.draft || '';
|
||||
const newDetailItems = [
|
||||
{
|
||||
pro_order_detail_num: "123",
|
||||
reconcile: 5000,
|
||||
activity_name: "法會",
|
||||
actitem_name: "護持金"
|
||||
}
|
||||
];
|
||||
|
||||
const newDraftObj = window.DraftUtils.updateDraftField(currentDraft, 'pro_order_detail_items', newDetailItems);
|
||||
```
|
||||
|
||||
**檢查是否有暫存資料：**
|
||||
```javascript
|
||||
if (window.DraftUtils.hasTransferDraft(item.draft)) {
|
||||
console.log('有暫存資料');
|
||||
}
|
||||
```
|
||||
|
||||
**取得特定欄位：**
|
||||
```javascript
|
||||
const transferDraft = window.DraftUtils.getDraftField(item.draft, 'transfer_draft');
|
||||
const detailItems = window.DraftUtils.getDraftField(item.draft, 'pro_order_detail_items');
|
||||
```
|
||||
|
||||
### 3. 統一工具檔案
|
||||
建立了 `draft-utils.js` 統一工具檔案，所有頁面都引用此檔案：
|
||||
- 所有 draft 操作函數統一管理
|
||||
- 格式驗證功能
|
||||
- 向後相容性處理
|
||||
- 詳細的使用範例
|
||||
- 避免程式碼重複，提升維護性
|
||||
|
||||
### 4. 頁面引用方式
|
||||
每個 `.aspx` 頁面都在 `<script>` 標籤前加入：
|
||||
```html
|
||||
<script src="draft-utils.js"></script>
|
||||
```
|
||||
|
||||
然後使用 `window.DraftUtils` 來呼叫工具函數，確保所有頁面使用相同的邏輯。
|
||||
|
||||
### 5. 完整工具函數清單
|
||||
`draft-utils.js` 提供以下工具函數：
|
||||
|
||||
**基本操作：**
|
||||
- `getDraftObject(draft)` - 解析 draft 欄位，返回標準化物件
|
||||
- `getDraftField(draft, fieldName)` - 安全取得特定欄位
|
||||
- `updateDraftField(draft, fieldName, newValue)` - 安全更新特定欄位
|
||||
- `clearDraftField(draft, fieldName)` - 清除特定欄位
|
||||
|
||||
**檢查函數：**
|
||||
- `hasTransferDraft(draft)` - 檢查是否有暫存資料
|
||||
- `hasProOrderDetailItems(draft)` - 檢查是否有歷史記錄
|
||||
|
||||
**工具函數：**
|
||||
- `mergeDraftObjects(draft1, draft2)` - 合併兩個 draft 物件
|
||||
- `validateDraftFormat(draft)` - 驗證 draft 格式
|
||||
- `getDraftSummary(draft)` - 取得 draft 摘要資訊
|
||||
- `migrateLegacyFormat(draft)` - 將舊格式轉換為新格式
|
||||
- `cleanEmptyDraft(draft)` - 清理空的 draft 欄位
|
||||
- `formatDraftJson(draft)` - 格式化 draft JSON 為可讀字串
|
||||
|
||||
## 優點
|
||||
|
||||
1. **職責分離** - 每個子陣列有明確的用途
|
||||
2. **資料一致性** - 避免不同用途的資料互相覆蓋
|
||||
3. **向後相容** - 支援舊格式，無需資料庫變更
|
||||
4. **易於維護** - 程式碼邏輯更清晰
|
||||
5. **擴展性** - 未來可以添加更多子陣列
|
||||
6. **資料安全** - 確保各欄位操作互不影響
|
||||
7. **程式碼統一** - 所有頁面使用相同的工具函數
|
||||
8. **功能完整** - 提供豐富的工具函數支援各種操作需求
|
||||
Reference in New Issue
Block a user