docs: API验证分工表+北极星四层地图（项目Bot产出）

2026-08-31 07:44:27 +08:00
parent 136fe3811f
commit df93b635b3
6 changed files with 712 additions and 0 deletions
@@ -0,0 +1,41 @@
+# 北极星① 数据接入 — 一页纸逻辑地图
+
+> 定位：让数据进得来、进得对、进得全。任总10分钟消化层。
+
+## 数据流（箭头图）
+```
+财务软件(用友/金蝶/管家婆) ──R3调研中──┐
+Excel/手工录入 ──import-excel-smart──┤
+Bot写入 ──bot/kpi-value-with-check───┼─→ 数据源登记(value-sources)
+网银流水 ──cash/import/vouchers──────┤      ↓
+                                  数据质量检查(data-quality)
+                                      ↓
+                               KPI实际值归集(value-collect)
+                                      ↓
+                             进入CMA可分析数据池（KPI/预算/现金流）
+```
+
+## 关键API（核心5个）
+| 核心 | API | 作用 |
+|:--|:--|:--|
+| ⭐1 | `POST /data/import-excel-smart` | 智能导入Excel（含科目映射） |
+| ⭐2 | `POST /budget/value-collect/run` | 实际值自动归集 |
+| ⭐3 | `GET /data-quality/governance-check` | 数据治理检查（财务七规则） |
+| ⭐4 | `POST /cash/import/vouchers` | 凭证/流水导入 |
+| ⭐5 | `POST /bot/kpi-value-with-check` | Bot带校验写入KPI值 |
+
+## 决策点（需任总拍板 1-3个）
+1. 财务软件接口选型：接哪个软件（用友/金蝶/管家婆）→ R3调研后定
+2. 数据质量标准：治理检查评分阈值定多少（当前error-10/warning-5）
+3. 历史数据导入范围：导入多少个月的流水/凭证
+
+## 验证点
+- ✅ L1自动：data-quality/governance-check（脚本/cron每日）
+- ✅ L1自动：value-collect 归集正确性（幂等验证）
+- 🟡 L2 Bot验证：import-excel-smart 导入闭环（QA Bot造数验证）
+- 🔴 L3任总抽验：登录/切换企业/智能导入/治理检查 4项核心
+
+## 当前状态
+- ✅ 手工/Excel/Bot写入 已落地（2026-08-30）
+- ✅ 数据质量检查 已落地（财务七规则）
+- ⏳ 财务软件接口 调研中（R3，zhixiangtong适配器方案已出）