iloom-flatten/docs/DATA_INTEGRITY_GUIDE.md

# 数据完整性保障方案 - 万分之一错误率目标

## 📊 质量目标

- **系统错误率**: ≤ 0.01% (万分之一)
- **财务数据准确率**: 100%
- **核心业务数据一致性**: 100%

## 🏗️ 四层防护体系

### 第一层：数据库强约束（最后一道防线）

**文件**: `migrations/20260604_200000_data_integrity_constraints.sql`

#### 1.1 触发器校验
- ✅ 计划数量一致性验证 (`validate_plan_quantity_consistency`)
- ✅ 入库记录正数验证 (`validate_inventory_record_positive`)
- ✅ 付款金额一致性验证 (`validate_payment_amount`)
- ✅ 应付账款汇总验证 (`validate_accounts_payable_totals`)

#### 1.2 CHECK 约束
```sql
-- 入库记录非负
CHECK (quantity >= 0 AND rolls >= 0 AND price_per_meter >= 0)

-- 付款金额非负
CHECK (amount >= 0 AND quantity >= 0 AND price_per_meter >= 0)

-- 应付账款逻辑约束
CHECK (paid_amount <= total_amount AND unpaid_amount <= total_amount)
```

#### 1.3 审计日志
所有关键表的数据变更自动记录到 `data_audit_logs` 表，包含：
- 变更前后的值
- 操作人
- 操作时间
- 验证是否通过

### 第二层：前端预检校验（写入前拦截）

**文件**: `src/utils/dataValidation.ts`

#### 2.1 校验函数
```typescript
// 入库记录校验
validateInventoryRecord({ quantity, rolls, price_per_meter })

// 付款记录校验
validatePayment({ amount, quantity, price_per_meter })

// 计划完成数量校验
validatePlanCompletion({ target_quantity, completed_quantity })
```

#### 2.2 安全写入包装器
```typescript
// 双重校验 + 写入后验证
await safeInsertInventoryRecord(record);
await safeInsertPayment(payment);
```

### 第三层：自动化监控（持续检测）

#### 3.1 Edge Function 定期检查
**文件**: `functions/data-integrity-check/index.ts`

- ⏰ 建议每小时执行一次
- 🔍 检查所有核心表的数据一致性
- 📊 计算错误率并与阈值对比
- 🚨 超标时生成告警

**部署命令**:
```bash
meoo-cli cloud deploy-function -n data-integrity-check
```

#### 3.2 数据库视图实时监控
```sql
-- 计划数量一致性检查
SELECT * FROM v_plan_quantity_check WHERE check_result = '✗ 不一致';

-- 付款金额检查
SELECT * FROM v_payment_check WHERE check_result = '✗ 不一致';

-- 应付账款检查
SELECT * FROM v_accounts_payable_check WHERE check_result = '✗ 不一致';

-- 错误率监控
SELECT * FROM v_error_rate_monitor WHERE error_rate_per_10k > 1;
```

### 第四层：可视化监控面板

**文件**: `src/components/DataIntegrityDashboard.tsx`

功能：
- 📈 实时显示系统数据质量状态
- 🎯 错误率趋势图（近7天）
- ⚠️ 异常项目高亮显示
- 📋 最近失败记录列表
- 🔄 支持手动触发检查

## 🚀 实施步骤

### 步骤1：执行数据库迁移

```bash
# 读取迁移脚本内容
cat migrations/20260604_200000_data_integrity_constraints.sql

# 分批执行（避免单次SQL过长）
meoo-cli cloud migrate --name "data_integrity_constraints" \
  --changes "添加数据完整性强约束、触发器、审计日志和监控视图" \
  --sql "$(cat migrations/20260604_200000_data_integrity_constraints.sql)"
```

### 步骤2：部署 Edge Function

```bash
# 部署数据完整性检查函数
meoo-cli cloud deploy-function -n data-integrity-check

# 配置定时任务（在 Supabase Dashboard 中设置）
# 建议：每小时执行一次
```

### 步骤3：集成前端组件

在管理后台或系统设置页面添加监控面板：

```tsx
import { DataIntegrityDashboard } from './components/DataIntegrityDashboard';

// 在路由中添加
<Route path="/admin/data-integrity" element={<DataIntegrityDashboard />} />
```

### 步骤4：替换现有写入操作

将现有的直接写入替换为安全写入：

```typescript
// ❌ 旧方式
await supabase.from('inventory_records').insert(record);

// ✅ 新方式
import { safeInsertInventoryRecord } from '../utils/dataValidation';
await safeInsertInventoryRecord(record);
```

需要替换的文件：
- `src/pages/textile/FabricWarehouse.tsx` - 坯布入库
- `src/pages/textile/PlanOverview.tsx` - 流程确认
- `src/pages/purchaser/WarehouseManage.tsx` - 产品入库
- `src/pages/*/PaymentPending.tsx` - 付款操作

### 步骤5：配置告警通知（可选）

在 Edge Function 中集成告警渠道：
- 📧 邮件通知
- 💬 钉钉/企业微信
- 📱 短信告警

## 📋 日常运维检查清单

### 每日检查
- [ ] 查看数据完整性监控面板
- [ ] 确认错误率 ≤ 1/万
- [ ] 检查是否有新的失败记录

### 每周检查
- [ ] 分析错误率趋势
- [ ] 审查审计日志中的异常操作
- [ ] 验证备份数据完整性

### 每月检查
- [ ] 运行全量数据一致性检查
- [ ] 评估是否需要调整阈值
- [ ] 更新数据质量报告

## 🔧 故障处理流程

### 发现数据不一致

1. **立即定位**
   ```sql
   -- 查找不一致的记录
   SELECT * FROM v_plan_quantity_check WHERE check_result = '✗ 不一致';
   ```

2. **分析原因**
   ```sql
   -- 查看审计日志
   SELECT * FROM data_audit_logs 
   WHERE record_id = '{问题记录ID}'
   ORDER BY changed_at DESC;
   ```

3. **修复数据**
   - 优先使用事务保证原子性
   - 修复后重新运行一致性检查
   - 记录修复过程到审计日志

4. **根因分析**
   - 是代码bug？→ 修复代码并添加测试
   - 是并发问题？→ 添加锁机制或使用事务
   - 是用户误操作？→ 加强前端校验和提示

### 错误率突然升高

1. 检查最近的代码部署
2. 查看审计日志中的失败模式
3. 检查数据库负载和性能
4. 必要时回滚最近的变更

## 📊 监控指标定义

| 指标 | 计算公式 | 目标值 | 告警阈值 |
|------|---------|--------|---------|
| 系统错误率 | (不一致记录数 / 总记录数) × 10000 | ≤ 1/万 | > 1/万 |
| 计划数量一致率 | 一致的计划数 / 总计划数 | 100% | < 99.99% |
| 付款金额准确率 | 准确的付款数 / 总付款数 | 100% | < 99.99% |
| 应付账款准确率 | 准确的账款数 / 总账款数 | 100% | < 99.99% |

## 🎯 持续改进

### 短期优化（1-2周）
- [ ] 完成数据库约束部署
- [ ] 集成前端校验工具
- [ ] 部署 Edge Function
- [ ] 添加监控面板

### 中期优化（1-2月）
- [ ] 建立自动化测试覆盖
- [ ] 实现数据修复工具
- [ ] 完善告警通知机制
- [ ] 培训运维人员

### 长期优化（3-6月）
- [ ] 引入机器学习异常检测
- [ ] 建立数据质量评分体系
- [ ] 实现自动修复机制
- [ ] 定期第三方审计

## 📞 技术支持

如遇数据完整性问题，请按以下优先级处理：

1. **P0 - 财务数据错误**: 立即停止相关操作，联系技术负责人
2. **P1 - 核心业务数据不一致**: 1小时内响应，4小时内修复
3. **P2 - 非关键数据异常**: 24小时内处理
4. **P3 - 监控告警**: 按日常运维流程处理

---

**最后更新**: 2026-06-04  
**版本**: v1.0  
**维护者**: 技术团队