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 约束

-- 入库记录非负
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 校验函数

// 入库记录校验
validateInventoryRecord({ quantity, rolls, price_per_meter })

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

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

2.2 安全写入包装器

// 双重校验 + 写入后验证
await safeInsertInventoryRecord(record);
await safeInsertPayment(payment);

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

3.1 Edge Function 定期检查

文件: functions/data-integrity-check/index.ts

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

部署命令:

meoo-cli cloud deploy-function -n data-integrity-check

3.2 数据库视图实时监控

-- 计划数量一致性检查
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：执行数据库迁移

# 读取迁移脚本内容
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

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

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

步骤3：集成前端组件

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

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

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

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

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

// ❌ 旧方式
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. 立即定位

   -- 查找不一致的记录
   SELECT * FROM v_plan_quantity_check WHERE check_result = '✗ 不一致';
   

2. 分析原因

   -- 查看审计日志
   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
维护者: 技术团队