freedak/SBrainCO
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

重构智脑实施方法论：引入FDE模式，八步工作法，适配中国连锁经营企业国情

Browse Source
This commit is contained in:
freedakgmail
2026-08-12 11:32:51 +08:00
parent c2a9e27e49
commit 64d2cd8043
16 changed files with 5001 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/智脑实施方法论/01-总体框架与八步工作法.md
+311
View File
@@ -0,0 +1,311 @@
# 01 · 总体框架与八步工作法
## 1. 核心理念
玄谋智脑不是一套技术系统，而是一套**以经营战略为起点、以数据闭环为终点的企业管理方法论**。
### 1.1 借鉴FDE精神，适配中国国情
本框架借鉴 **FDE（Forward Deployed Engineer，前线部署工程）** 的核心理念，但并非照搬硅谷模式。中国连锁经营企业的现实是：预算有限（十万到百万级，非硅谷六七位数美元）、数字化基础薄弱、人员流动大、利润薄。需要做适配性改造。
> "中国FDE不是照搬硅谷岗位，而是企业在AI落地中，为模型能力与业务结果之间补上的一段责任。" —— 《FDE落地中国白皮书》
**借鉴什么**：
- 前线嵌入：深入业务现场，不闭门造车
- 先跑通再优化：两周交付最小可用，而非半年画大饼
- 双向沉淀：面向客户留能力，面向平台留模板
- 结果负责：对业务结果负责，而非对"系统上线"负责
**不照搬什么**：
- 硅谷高客单价人海模式（中国连锁经营企业支撑不起）
- 全能FDE单人角色（中国更现实的是"AI+业务人员"组合）
- 重型工程底座（中国连锁经营IT基础设施简单，不需要Kubernetes级部署）
- Palantir式政府/金融级合规要求
### 1.2 中国适配：AI作为"虚拟FDE"
中国连锁经营企业的现实解法——用AI替代部分FDE职能，降低对人力的依赖：
| FDE职能 | 硅谷做法 | 中国适配做法 |
|---------|---------|-------------|
| 场景发现（Echo） | 行业专家驻场数周 | 老板/中层访谈 + AI整理提纲和指标草案 |
| 快速原型（Delta） | 工程师现场写代码 | AI生成SQL/API/前端代码，人审查验证 |
| 数据对接 | FDE手动打通系统 | AI辅助编写导入脚本和映射逻辑 |
| 持续迭代 | FDE长期驻场 | AI协同月度诊断 + 远程迭代 |
| 知识沉淀 | FDE带回经验形成产品 | AI辅助沉淀为文档/模板/Checklist |
**核心思路**：AI承担Delta层80%的代码工作，人聚焦Echo层的业务判断和组织推动。这样即使预算有限，也能实现FDE式的深度交付。
### 1.3 Echo + Delta 双角色模型
借鉴Palantir的FDE实践，将部署团队分为两层角色，但在中国语境下重新定义：
| 角色 | 定位 | 硅谷原版 | 中国适配 |
|------|------|---------|---------|
| **Echo**（该做什么） | 场景发现者、需求翻译者 | 退役军官/行业专家全职驻场 | 老板+中层访谈，AI辅助整理，业务人员兼职 |
| **Delta**（怎么做出来） | 快速构建者、现场交付者 | 工程师现场写代码 | AI生成代码为主，技术人员审查验证为辅 |
**关键原则**：AI让Delta变便宜（代码生成、自动化测试），Echo更稀缺（识别高价值场景、理解行业、推动组织采纳）。在中国连锁经营企业，Echo层的核心是**老板本人的经营智慧和中层的管理经验**，而非外部专家。
### 1.4 总体循环
```
老板战略 → 指标体系 → 数据本体 → 执行闭环 → AI协同构建 → 持续优化
↑ |
└────────────────── 反馈与优化 ←──────────────────────────┘
FDE双向沉淀：
面向客户：业务经验 → AI知识库 → 工作流 → 应用能力
面向平台：行业场景 → 系统接口 → 测试方法 → 产品组件
↕ 共同载体：本体层（结构化业务知识图谱）
```
## 2. 八步工作法
> 每一步都标注FDE角色（Echo/Delta）和沉淀产出（面向客户/面向平台）。
### 步骤一：老板访谈与指挥层构建 `[Echo主导]`
> 从经营战略出发，定义"老板要看什么、管什么、决策什么"
- FDE嵌入现场，访谈老板近期经营战略和目标（带提纲和示例）
- 将模糊战略翻译为可量化指标（"我想看门店效率"→"日均产出/坪效/人效"）
- 形成智脑指标体系（指挥层）
- **面向客户沉淀**：指标体系文档、老板驾驶舱原型
- **面向平台沉淀**：行业指标模板（可复用于同类连锁经营企业）
### 步骤二：数据现状与本体层构建 `[Echo+Delta]`
> 摸清家底，建立从数据到指标的映射——本体层是FDE双向沉淀的核心载体
- FDE深入客户数据现场，了解现有系统和数据情况
- 针对指标体系的数据要求，盘点数据覆盖度
- 构建智脑本体层（数据模型、物化视图、映射关系）
- **面向客户沉淀**：数据溯源文档、物化视图体系、数据质量报告
- **面向平台沉淀**：本体设计模式（门店-账单-费用-考勤的通用关系模型）
### 步骤三：中层访谈与执行层准备 `[Echo主导]`
> 明确"谁来做、做到什么程度、如何考核"——FDE不只是技术交付，更是组织流程改造
- FDE嵌入中层（区域经理、店长）工作现场，明确职权范围
- 将指标体系拆解到岗位级执行动作
- 准备智脑执行层（任务模板、考核标准、预警规则）
- **面向客户沉淀**：岗位-指标矩阵、任务闭环规则
- **面向平台沉淀**：行业任务模板库（预警→任务→验收的标准流程）
### 步骤四：AI协同模型设计与逻辑闭环验证 `[Echo+Delta]`
> 在写代码前，先用AI验证业务逻辑的完整性——FDE的"先想清楚再动手"
- AI协同设计各层次的数据模型和业务逻辑
- 验证"指标→数据→分析→预警→任务→执行→反馈"闭环
- 发现逻辑断点并修复
- **面向客户沉淀**：模型设计文档、闭环验证报告
- **面向平台沉淀**：闭环验证Checklist（可复用于同类项目）
### 步骤五：AI协同本体层构建 `[Delta主导]`
> AI参与数据层代码编写和验证——Delta层成本被AI大幅压缩
- AI协同编写物化视图SQL
- AI协同编写数据导入脚本
- AI协同验证数据质量
- **面向客户沉淀**：可运行的数据层
- **面向平台沉淀**：物化视图SQL模板、数据校验脚本库
### 步骤六：AI协同后端API构建与验证 `[Delta主导]`
> AI参与API开发，逐个验证——快速交付能用的代码，不追求完美架构
- AI协同编写后端路由和SQL查询
- curl + psql 双向验证每个API
- 修复SQL陷阱（schema、列名、日期格式）
- **面向客户沉淀**：可运行的API层
- **面向平台沉淀**：API路由模板、SQL查询模式库
### 步骤七：AI协同前端UIUX设计与实现 `[Delta主导]`
> AI参与页面设计，参考典型页面模板——先交付能用的，再迭代好用的
- AI协同设计页面布局和交互
- 基于组件规范实现前端页面
- 联调API，处理空状态和加载状态
- **面向客户沉淀**：可用的前端界面
- **面向平台沉淀**：页面组件模板、行业Dashboard布局模板
### 步骤八：数据驱动闭环优化 `[Echo+Delta]`
> 上线不是终点，而是优化的起点——FDE持续驻场，把"不确定的机会"变成"可重复的流程"
```
数据采集 → 分析（基于模型）→ 发现问题 → 改进方案（AI协同）
→ 实施 → 反馈 → 检验 → 优化 → 再循环
```
- 基于模型分析数据，发现经营问题
- AI协同生成改进方案
- 落地实施，跟踪反馈
- 检验效果，优化模型和参数
- **面向客户沉淀**：持续运转的闭环机制、最佳实践库
- **面向平台沉淀**：行业诊断模型、参数调优经验、可复制的改进方案模板
## 3. 三层架构与FDE本体层
```
┌─────────────────────────────────────────┐
│ 指挥层（老板） │
│ - 战略目标 → 指标体系 │
│ - 老板驾驶舱、总部驾驶舱 │
│ - 关注：趋势、风险、机会 │
│ - FDE角色：Echo发现场景、翻译需求 │
├─────────────────────────────────────────┤
│ 本体层（数据+模型） │
│ - 原始数据 → 物化视图 → 指标计算 │
│ - 数据溯源、口径一致性 │
│ - 关注：数据质量、覆盖度、准确性 │
│ - FDE角色：双向沉淀的核心载体 │
│ - 本体 = 结构化业务知识图谱 │
│ 面向客户：业务经验→AI知识库→工作流 │
│ 面向平台：行业场景→产品组件→复用能力 │
├─────────────────────────────────────────┤
│ 执行层（中层+一线） │
│ - 指标 → 任务 → 执行 → 反馈 │
│ - 门店工作台、任务闭环 │
│ - 关注：可执行、可考核、可追踪 │
│ - FDE角色：嵌入现场、改造流程、推动采纳 │
└─────────────────────────────────────────┘
```
### 3.1 本体层的FDE价值
本体层不是简单的数据库设计，而是**从多个客户现场踩坑中提炼出来的通用业务知识结构**：
- 第一个客户：花大量时间理解"门店-账单-费用-考勤"的关系，成本高
- 第二个客户：本体层已稳定，只需适配新字段名和业务规则
- 第十个客户：本体层成为行业模板，交付成本显著下降
> **规模化的核心度量**：如果第一个客户需要10人月，第十个同类客户仍然需要10人月，模式就没有跑通。
### 3.2 中国连锁经营企业的本体层特点
与硅谷FDE面向政府/金融的本体层不同，中国连锁经营企业的本体层有其特殊性：
| 维度 | 硅谷FDE本体 | 中国连锁经营本体 |
|------|-----------|----------------|
| 数据源 | 多系统、高复杂度 | 收银+考勤+薪资+库存，3-5个Excel/CSV |
| 数据质量 | 有ETL管道，相对干净 | 原始数据脏，列名无含义（c001~c200） |
| 变更频率 | 低（制度稳定） | 高（门店开关、商品调整、人员流动） |
| 映射复杂度 | 系统间ID对接 | 门店名不一致（"双安店"vs"双安总店"） |
| 本体核心 | 权限+流程+合规 | 门店+账单+费用+考勤+库存的关系模型 |
**连锁经营本体的核心资产**（跨品类通用：餐饮/零售/服务/教培）：
1. 字段映射文档（c001=门店名，c114=实收...）——这是最宝贵的踩坑沉淀
2. 门店名映射表——每个新客户都要重新建，但模式可复用
3. 物化视图SQL模板——结构相同，表名和字段名适配即可
4. 异常判断规则——"有消费无实收"等行业特定规则
5. **门店-商品-供应链关系模型**——餐饮有BOM，零售有SKU，教培有课包，结构相似
## 4. AI协同模式与FDE角色分工
AI不是替代人，而是全程协同伙伴。FDE模式下，AI让Delta变便宜，Echo更稀缺：
| 阶段 | FDE角色 | AI角色（Delta增强） | 人的角色（Echo主导） | 双向沉淀 |
|------|---------|-------------------|-------------------|---------|
| 老板访谈 | Echo | 整理提纲、记录要点、生成指标体系草案 | 引导访谈、确认战略方向、翻译模糊需求 | 行业指标模板 |
| 数据调研 | Echo+Delta | 分析数据质量、生成溯源文档、编写SQL | 确认数据含义、验证业务逻辑 | 本体设计模式 |
| 中层访谈 | Echo | 设计岗位-指标矩阵、生成任务模板 | 确认职权范围、考核标准、推动组织采纳 | 行业任务模板库 |
| 模型设计 | Echo+Delta | 设计数据模型、验证逻辑闭环 | 审查业务合理性、决策取舍 | 闭环验证Checklist |
| 本体构建 | Delta | 编写SQL和脚本、验证数据 | 审查代码、验证结果 | 物化视图SQL模板 |
| API构建 | Delta | 编写路由和查询、排查错误 | 验证API返回、确认业务逻辑 | API路由模板 |
| 前端实现 | Delta | 编写页面代码、设计交互 | 审查UI/UX、验证用户体验 | 页面组件模板 |
| 闭环优化 | Echo+Delta | 分析数据、生成改进方案 | 决策方案、推动实施、验收结果 | 行业诊断模型 |
### 4.1 "先跑通再优化"原则
```
传统交付：需求分析(1月) → 架构设计(1月) → 开发(3月) → 测试(1月) → 上线
FDE交付：现场嵌入(1周) → 最小可用(2周) → 真实反馈(1周) → 快速迭代(持续)
关键差异：
- 传统：追求完美架构，上线时需求已变
- FDE：先交付能用的，在真实反馈中迭代
- AI加持：Delta层（代码编写）成本大幅压缩，原型可在数小时内生成
```
**中国连锁经营企业的特殊考量**：
- 老板耐心有限：两周看不到东西就会失去信任，所以第一版必须快速可见
- 数据基础差：不要等数据完美了再开始，用现有脏数据先跑通，边用边治
- 人员能力参差：第一版必须"傻瓜式"操作，不能要求店长学习复杂流程
- 利润薄：每一步都要能算清ROI，老板才会继续投入
### 4.2 "从最小痛点开始"原则
不要上来做"大一统"方案。选一个最小痛点，两周内跑通：
| 选择标准 | 示例 |
|---------|------|
| 业务痛点足够明确 | "13家门店亏损，不知道为什么亏" |
| 数据虽然不完美但够用 | bill_records有168万条，覆盖94家门店 |
| 效果可以量化 | 亏损门店数从13降到8 |
| 老板关心 | 直接关联L0战略指标 |
| 不依赖组织变革 | 不需要先改考核制度才能跑 |
**中国连锁经营企业的典型最小痛点**：
1. **门店亏损诊断**：数据现成（账单+费用），老板最关心，两周可见
2. **成本异动监控**：数据现成（账单+成本），痛点明确，容易量化
3. **异常交易监控**：数据现成（账单/订单），风险可控，见效快
4. **人效分析**：数据现成（考勤+营收），人力成本是连锁经营第二大成本
**不建议作为起点的场景**：
- 智能排班（需要考勤数据质量高+店长配合）
- 会员精准营销（需要会员数据积累+营销预算）
- 供应链优化（需要跨系统数据+供应商配合）
跑通一个场景后，再复制到下一个——先铺石子路，再修高速公路。
## 5. 文档体系导航
### 方法论主体（八步）
| 步骤 | 文件 | FDE角色 | 核心输出 | 平台沉淀 |
|------|------|---------|---------|---------|
| 一 | [02-步骤一-老板访谈与指挥层构建.md](02-步骤一-老板访谈与指挥层构建.md) | Echo | 指标体系、驾驶舱原型 | 行业指标模板 |
| 二 | [03-步骤二-数据现状与本体层构建.md](03-步骤二-数据现状与本体层构建.md) | Echo+Delta | 数据溯源、物化视图 | 本体设计模式 |
| 三 | [04-步骤三-中层访谈与执行层准备.md](04-步骤三-中层访谈与执行层准备.md) | Echo | 岗位-指标矩阵、任务模板 | 行业任务模板库 |
| 四 | [05-步骤四-AI协同模型设计与逻辑闭环.md](05-步骤四-AI协同模型设计与逻辑闭环.md) | Echo+Delta | 模型设计、闭环验证 | 闭环验证Checklist |
| 五 | [06-步骤五-AI协同本体层构建.md](06-步骤五-AI协同本体层构建.md) | Delta(AI为主) | 数据层代码 | 物化视图SQL模板 |
| 六 | [07-步骤六-AI协同后端API构建与验证.md](07-步骤六-AI协同后端API构建与验证.md) | Delta(AI为主) | API层代码 | API路由模板 |
| 七 | [08-步骤七-AI协同前端UIUX设计与实现.md](08-步骤七-AI协同前端UIUX设计与实现.md) | Delta(AI为主) | 前端界面 | 页面组件模板 |
| 八 | [09-步骤八-数据驱动闭环优化.md](09-步骤八-数据驱动闭环优化.md) | Echo+Delta | 优化闭环 | 行业诊断模型 |
### 技术参考
| 文件 | 内容 |
|------|------|
| [10-技术参考-项目概述与架构.md](10-技术参考-项目概述与架构.md) | 技术架构、数据流、部署拓扑 |
| [11-技术参考-部署与运维.md](11-技术参考-部署与运维.md) | 部署脚本、FRP隧道、PM2 |
| [12-技术参考-调试排查手册.md](12-技术参考-调试排查手册.md) | 问题分类、排查流程、案例 |
| [13-技术参考-通用方法论与避坑指南.md](13-技术参考-通用方法论与避坑指南.md) | 核心原则、风险清单、Checklist |
| [14-技术参考-数据溯源与API全量清单.md](14-技术参考-数据溯源与API全量清单.md) | 逐页面→API→SQL→字段映射 |
| [15-技术参考-指标口径一致性分析.md](15-技术参考-指标口径一致性分析.md) | 跨页面口径对比、问题清单 |
## 6. 规模化度量（中国适配版）
硅谷FDE用"人月成本递减"衡量规模化。中国连锁经营企业更现实的度量方式：
| 指标 | 定义 | 目标 | 中国适配说明 |
|------|------|------|-------------|
| 首次交付周期 | 从访谈到第一个可用版本 | <4周 | 老板耐心有限，超4周信任崩塌 |
| 同类客户交付周期 | 第二个同类客户 | <2周 | 本体层和模板复用后应大幅缩短 |
| AI代码占比 | AI生成的代码占总代码比例 | >70% | 降低对稀缺工程人才的依赖 |
| 客户自助率 | 客户独立完成的数据操作占比 | 逐月提升 | 中国连锁经营IT能力弱，需渐进式 |
| 闭环运转率 | 月度闭环实际执行率 | >80% | 闭环转起来才是真落地 |
| 沉淀复用率 | 可复用资产占项目总产出 | >40% | 没有沉淀就没有规模化 |
### 6.1 中国连锁经营企业的规模化路径
```
阶段一（单店验证）：1个客户，4周交付，大量踩坑
↓ 沉淀：字段映射、物化视图SQL、页面模板
阶段二（同品牌复制）：同品牌不同月份，1周交付，验证稳定性
↓ 沉淀：数据校验脚本、异常规则库
阶段三（同品类复制）：同品类不同品牌（如餐饮A→餐饮B），2周交付，适配字段名和业务规则
↓ 沉淀：品类本体模板、指标体系模板
阶段四（跨品类扩展）：不同品类（餐饮→零售→服务→教培），3周交付，适配本体层
↓ 沉淀：连锁经营通用本体设计模式
```
**关键**：每个阶段的沉淀质量决定下一阶段的速度。如果做完一个客户没有沉淀出可复用资产，下一个客户又从头开始，那就是传统外包，不是FDE。
docs/智脑实施方法论/02-步骤一-老板访谈与指挥层构建.md
+147
View File
@@ -0,0 +1,147 @@
# 02 · 步骤一：老板访谈与指挥层构建
> 目标：从老板的经营战略出发，定义智脑要呈现什么、预警什么、辅助决策什么。 `[Echo主导]`
>
> FDE角色：这一步是典型的Echo层工作——深入业务现场，把老板模糊的战略意图翻译为可量化的指标体系。AI辅助整理提纲和生成草案，但核心是人的业务判断。
## 1. 访谈准备
### 1.1 访谈提纲
```
一、战略方向
1. 今年最关注哪3个经营目标？（营收/利润/扩张/降本/品牌）
2. 当前最大的经营痛点是什么？
3. 觉得哪些决策缺乏数据支撑？
二、管理范围
4. 您平时看哪些报表？频率？哪些指标最关键？
5. 希望每天/每周/每月自动看到什么？
6. 哪些情况需要立即预警？（如某店连续3天营收下降）
三、组织架构
7. 下面管几层？（总部→区域→门店）
8. 区域经理和店长的核心考核指标是什么？
9. 哪些决策是您亲自做的？哪些授权下去了？
四、数据现状
10. 现在有哪些系统？（收银/考勤/薪资/供应链/会员）
11. 这些系统数据能打通吗？
12. 有没有以前想做但没做成的数据分析？
五、期望与边界
13. 希望智脑帮您做到什么程度？（看数据/给建议/自动执行）
14. 有哪些底线是不能碰的？（如不能自动调价）
15. 对数据安全有什么要求？
```
### 1.2 示例引导
老板可能说："我就是想看哪家店在亏钱，为什么亏，怎么改"
拆解为：
- **指标**：门店贡献利润、食材成本率、人工费率、费用率
- **预警**：连续亏损、成本率超标、费用率异常
- **决策**：关店/整改/换人/降本
- **执行**：任务派发给区域经理→店长→跟踪反馈
## 2. 指标体系构建
### 2.1 指标分层
```
L0: 战略指标（老板关注）
├── 营收总额、利润总额、门店数、客单价
├── 同比/环比趋势
└── 盈利/亏损门店数
L1: 经营指标（管理层关注）
├── 优惠率、毛利率、会员占比
├── 食材成本率、人工费率、房租费率、水电费率
├── 外卖佣金占比
└── 平台经济性（美团/饿了么/抖音成本率）
L2: 执行指标（门店关注）
├── 日均实收、账单数、客单价
├── 风险评级（红/黄/绿）
├── 异常账单数、零实收数
├── 客流-人力匹配度
└── 任务完成率
```
### 2.2 指标卡设计
基于访谈结果，设计老板驾驶舱的指标卡：
| 指标 | 数据来源 | 展示形式 | 预警阈值 |
|------|---------|---------|---------|
| 营业收入 | bill_fact.consumption | MetricCard (currency) | 环比下降>10% |
| 实收 | bill_fact.received_total | MetricCard (currency) | — |
| 门店贡献利润 | received - food_cost - operating_expense | MetricCard (currency) | <0 标红 |
| 贡献率 | profit / matched_received * 100 | MetricCard (percent) | <5% 标黄 |
| 盈利门店数 | count FILTER(contribution > 0) | MetricCard (number) | — |
| 亏损门店数 | count FILTER(contribution <= 0) | MetricCard (number) | >5 标红 |
| 食材成本率 | food_cost / received * 100 | MetricCard (percent) | >40% 标红 |
| 人工费率 | wage / received * 100 | MetricCard (percent) | >25% 标红 |
### 2.3 预警规则设计
| 预警类型 | 触发条件 | 级别 | 推送对象 |
|---------|---------|------|---------|
| 营收异动 | 日营收环比下降>20% | 红色 | 老板+区域经理 |
| 成本异动 | 食材成本率>45% | 红色 | 老板+区域经理 |
| 人力异动 | 人工费率>30%或客流-人力严重不匹配 | 橙色 | 区域经理 |
| 平台依赖 | 单平台占比>70%且成本率>25% | 橙色 | 老板 |
| 任务逾期 | 整改任务超7天未完成 | 橙色 | 区域经理 |
## 3. 指挥层原型
### 3.1 老板驾驶舱
```
┌─────────────────────────────────────────────────┐
│ 老板驾驶舱 [2026年4月] │
├─────────────────────────────────────────────────┤
│ [营收] [实收] [利润] [贡献率] [盈利/亏损] │
│ 6420万 6369万 698万 10.96% 78家/13家 │
├─────────────────────────────────────────────────┤
│ 📊 利润瀑布图 📊 日度实收趋势 │
│ (实收→食材→人工→房租 (折线图，环比标注) │
│ →水电→佣金→利润) │
├─────────────────────────────────────────────────┤
│ 📊 门店风险分布 📊 P0/P1重点门店 │
│ (红/黄/绿饼图) (表格，含问题组合) │
├─────────────────────────────────────────────────┤
│ 📊 平台成本率TOP15 📊 门店经营象限 │
│ (美团/饿了么/抖音) (散点图：日均实收vs毛利率) │
├─────────────────────────────────────────────────┤
│ 📋 利润机会池 📋 月度趋势 │
│ (可改善空间排序) (实收+账单数双轴) │
└─────────────────────────────────────────────────┘
```
### 3.2 总部驾驶舱
比老板驾驶舱更详细，增加：
- 态势感知预警卡片（5类预警合并）
- 闭环健康度（5项rate指标）
- 同比/环比对比
- 利润趋势（月度贡献利润走势）
## 4. 访谈输出物
| 输出物 | 说明 | 后续步骤使用 |
|--------|------|-------------|
| 战略目标清单 | 老板关注的3-5个核心目标 | 步骤四模型设计的输入 |
| 指标体系文档 | L0/L1/L2分层指标定义 | 步骤二数据覆盖度盘点 |
| 驾驶舱原型 | 页面布局和指标卡设计 | 步骤七前端实现 |
| 预警规则 | 触发条件、级别、推送对象 | 步骤四闭环验证 |
| 管理层级图 | 总部→区域→门店的决策权分布 | 步骤三中层访谈 |
## 5. 关键注意事项
1. **不要一上来谈技术**：先聊经营，再聊数据，最后才聊系统
2. **指标要可量化**：老板说"想看门店效率"，要追问"效率具体指什么？人均产出？坪效？"
3. **预警要可执行**：预警必须关联到具体动作，否则只是噪音
4. **分清"看的"和"管的"**：老板看趋势和异常，管理层管过程和整改
5. **留出迭代空间**：第一版不需要完美，先上线核心指标，后续根据反馈迭代
docs/智脑实施方法论/02-数据接入与治理.md → docs/智脑实施方法论/03-步骤二-数据现状与本体层构建.md
+3 -1
View File
@@ -1,4 +1,6 @@
# 02 · 数据接入与治理
# 03 · 步骤二：数据现状与本体层构建
> 目标：摸清数据家底，建立从原始数据到指标体系的映射——本体层是FDE双向沉淀的核心载体。 `[Echo+Delta]`
## 1. 原始数据导入
docs/智脑实施方法论/04-步骤三-中层访谈与执行层准备.md
+176
View File
@@ -0,0 +1,176 @@
# 04 · 步骤三：中层访谈与执行层准备
> 目标：将指标体系从"老板看的"落地为"中层和一线执行的"，明确谁来做、做到什么程度、如何考核。 `[Echo主导]`
>
> FDE角色：这一步是Echo层在组织中的延伸——不只是技术交付，更是流程改造。需要嵌入中层和一线的工作现场，理解真实痛点，才能设计出可执行的任务闭环。
## 1. 中层访谈准备
### 1.1 访谈对象
| 角色 | 人数 | 关注重点 |
|------|------|---------|
| 区域经理 | 3-5人 | 区域整体经营、门店评级、人员调配 |
| 店长代表 | 5-8人（红/黄/绿各选） | 门店日常运营、成本控制、任务执行 |
| 商品部/供应链 | 1-2人 | 菜品成本、BOM、采购、配送 |
| 财务 | 1人 | 费用归集、成本核算口径 |
### 1.2 访谈提纲
```
一、职权范围
1. 你日常负责哪些门店/区域？核心KPI是什么？
2. 哪些决策你能直接做？哪些需要上报？
3. 你希望看到哪些数据来辅助你的日常决策？
二、执行痛点
4. 总部下发的任务，你觉得哪些好执行、哪些难落地？
5. 你觉得目前哪些指标考核不合理？
6. 如果系统能自动帮你发现一个问题并派发任务，你最希望是什么？
三、数据使用习惯
7. 你现在每天/每周看什么报表？
8. 哪些数据你觉得不准或滞后？
9. 如果有一个"门店工作台"，你最希望它包含什么功能？
四、闭环反馈
10. 整改任务从下发到完成，通常需要多久？
11. 执行中最大的阻力是什么？
12. 如何验证整改效果？
```
### 1.3 典型回答与拆解
**区域经理说**："我最头疼的是有些店长不主动整改，等我去检查才发现问题"
拆解：
- 系统需求：自动预警→自动派发任务→跟踪完成率→逾期上报
- 指标关联：任务生成率、店长执行率、区域周检率
- 执行层设计：预警触发→任务模板→店长接收→限期完成→区域验收
**店长说**："我不知道自己店在区域排第几，也不知道哪里做得不好"
拆解：
- 系统需求：门店工作台→对标分析→偏差诊断→改进建议
- 指标关联：日均实收、客单价、成本率、风险评级
- 执行层设计：店长打开页面即可看到本店vs区域均值偏差
## 2. 岗位-指标矩阵
### 2.1 矩阵设计
| 指标 | 老板 | 区域经理 | 店长 | 商品部 |
|------|------|---------|------|--------|
| 营收总额 | 👁️ 看 | 👁️ 看 | — | — |
| 门店贡献利润 | 👁️ 看 | 👁️ 看 | 👁️ 看 | — |
| 食材成本率 | 👁️ 看 | 👁️ 看 | 👁️ 看 | 👁️ 看 |
| 人工费率 | — | 👁️ 看 | 👁️ 看 | — |
| 风险评级 | 👁️ 看 | 🔄 管 | 🔄 管 | — |
| 客流-人力匹配 | — | 👁️ 看 | 🔄 管 | — |
| 异常账单 | — | 🔄 管 | 🔄 管 | — |
| 菜品成本方差 | — | — | — | 🔄 管 |
| 任务完成率 | 👁️ 看 | 🔄 管 | 🔄 做 | — |
| BOM准确率 | — | — | — | 🔄 管 |
- 👁️ 看：只看数据，不直接操作
- 🔄 管：负责监督和整改
- 🔄 做：负责执行和反馈
### 2.2 数据权限设计
```typescript
// 后端 getDataScope 实现
interface DataScope {
role: 'hq' | 'regional' | 'store' | 'dept'
store_names: string[] | null // null = 全部门店
region?: string // 区域经理管辖区域
store_code?: string // 店长所属门店
}
```
| 角色 | 可见范围 | 可操作范围 |
|------|---------|-----------|
| 总部管理员 | 全部门店 | 全部 |
| 区域经理 | 本区域门店 | 本区域 |
| 店长 | 本店 | 本店 |
| 商品部 | 全部门店（只读） | 菜品/BOM相关 |
## 3. 执行层设计
### 3.1 任务闭环模型
```
预警触发 → 任务生成 → 店长接收 → 整改执行 →
区域验收 → 效果检验 → 经验沉淀 → 关闭/重开
```
### 3.2 任务模板
| 预警类型 | 任务标题 | 责任人 | 期限 | 验收标准 |
|---------|---------|--------|------|---------|
| 食材成本率>45% | "XX店食材成本率超标，请分析原因并提交整改方案" | 店长 | 7天 | 成本率降至40%以下 |
| 连续亏损 | "XX店连续2月亏损，请制定扭亏方案" | 店长+区域经理 | 14天 | 当月贡献利润转正 |
| 异常账单增多 | "XX店异常账单数异常，请核查收银流程" | 店长 | 3天 | 异常账单数下降50% |
| 客流-人力不匹配 | "XX店高峰人手不足，请调整排班" | 店长 | 3天 | 高峰时段人均产出<15单 |
| 任务逾期 | "XX店有N项整改任务逾期，请督促完成" | 区域经理 | 3天 | 逾期任务清零 |
### 3.3 闭环健康度指标
| 指标 | 计算方式 | 目标值 |
|------|---------|--------|
| 任务生成率 | 已生成任务数 / 应生成预警数 | >80% |
| 店长执行率 | 已完成任务数 / 已接收任务数 | >70% |
| 区域周检率 | 本周已检查门店数 / 本周应检查门店数 | >90% |
| 月度验收率 | 本月已验收任务数 / 本月已完成任务数 | >80% |
| 经验推广率 | 已推广最佳实践数 / 已沉淀最佳实践数 | >50% |
## 4. 门店工作台设计
### 4.1 页面结构
```
┌─────────────────────────────────────────────────┐
│ 门店工作台 - 潘家园店 [2026年4月] │
├─────────────────────────────────────────────────┤
│ [日均实收] [客单价] [优惠率] [毛利率] [风险等级] │
│ 20,144 36.8 20.5% 61.8% 🟢 绿色 │
│ (vs区域均值) (+5%) (-2%) (+1%) (持平) │
├─────────────────────────────────────────────────┤
│ Tab1: 日报卡 Tab2: 风险 Tab3: 成本 │
│ Tab4: 会员 Tab5: 排班 Tab6: 任务 │
├─────────────────────────────────────────────────┤
│ 📋 今日待办任务（3项） │
│ □ 食材成本率超标整改（还剩5天） │
│ □ 异常账单核查（还剩2天） │
│ □ 排班优化（今日截止） │
├─────────────────────────────────────────────────┤
│ 📊 餐段分析（早/午/晚各时段实收vs区域均值） │
│ 📊 品类结构（各品类销售占比） │
│ 📋 异常账单明细 │
└─────────────────────────────────────────────────┘
```
### 4.2 店长视角的核心需求
1. **对标定位**：本店 vs 区域均值，一眼看出哪里偏差大
2. **任务驱动**：打开就有待办，不用自己去翻报表找问题
3. **一键诊断**：点击偏差指标，自动展开原因分析
4. **整改跟踪**：任务有期限、有验收、有效果检验
## 5. 访谈输出物
| 输出物 | 说明 | 后续步骤使用 |
|--------|------|-------------|
| 岗位-指标矩阵 | 每个岗位看什么、管什么、做什么 | 步骤四模型设计、步骤七页面权限 |
| 任务模板库 | 预警→任务→验收的标准流程 | 步骤四闭环验证、步骤六API开发 |
| 门店工作台原型 | 店长页面的布局和功能 | 步骤七前端实现 |
| 数据权限规则 | 各角色的数据可见范围 | 步骤六API的getDataScope |
| 闭环健康度指标 | 5项rate指标定义和目标值 | 步骤六API、步骤七总部驾驶舱 |
## 6. 关键注意事项
1. **不要跳过中层直接到一线**：区域经理是承上启下的关键环节
2. **任务模板要具体**：不能是"请改进"，必须是"请将食材成本率从45%降至40%"
3. **考核要联动**：系统指标要与现有KPI考核挂钩，否则没人会用
4. **店长的声音很重要**：选红/黄/绿各色门店的店长，了解不同状态下的痛点
5. **执行层不是管控工具**：是帮中层和一线更好地工作的工具，定位要正确
docs/智脑实施方法论/05-步骤四-AI协同模型设计与逻辑闭环.md
+202
View File
@@ -0,0 +1,202 @@
# 05 · 步骤四：AI协同模型设计与逻辑闭环验证
> 目标：在写代码前，用AI验证从战略指标到数据执行的全链路逻辑完整性，发现并修复断点。 `[Echo+Delta]`
>
> FDE角色：这是"先想清楚再动手"的关键步骤。Echo层定义业务逻辑闭环，Delta层用AI验证技术可行性。逻辑断点在这一步修复，成本远低于编码后返工。
## 1. 模型设计框架
### 1.1 三层模型映射
```
指挥层模型（战略→指标）
战略目标 → 核心指标 → 展示形式 → 预警规则
↓
本体层模型（数据→指标）
原始表 → 物化视图 → API字段 → 前端变量
↓
执行层模型（指标→任务→闭环）
指标偏差 → 预警触发 → 任务生成 → 执行反馈 → 效果检验
```
### 1.2 AI协同设计流程
```
1. 输入：指标体系 + 数据现状 + 岗位矩阵
2. AI生成：完整的数据模型设计草案
- 每个指标的计算公式
- 数据源映射
- 物化视图设计
- API设计
- 预警规则
- 任务模板
3. 人工审查：业务逻辑是否正确
4. AI验证：逻辑闭环是否完整
5. 输出：可执行的技术方案
```
## 2. 指标计算模型
### 2.1 核心指标公式
| 指标 | 公式 | 数据源 | 注意事项 |
|------|------|--------|---------|
| 营业收入 | `sum(consumption)` | bill_fact.consumption | — |
| 优惠 | `sum(discount_total)` | bill_fact.discount_total | — |
| 实收 | `sum(received_total)` | bill_fact.received_total | — |
| 客单价 | `sum(received) / sum(bill_count)` | bill_fact | 注意：不是avg(received_total) |
| 优惠率 | `avg(discount_total / consumption * 100)` | bill_fact | 逐单计算再平均 |
| 理论毛利率 | `sum(theoretical_profit) / sum(received) * 100` | bill_fact | — |
| 会员占比 | `sum(received) FILTER(member_id非空) / sum(received) * 100` | bill_fact | — |
| 食材成本率 | `sum(actual_food_cost) / sum(matched_received) * 100` | mv_store_operating_expense_monthly | 分母必须用matched口径 |
| 人工费率 | `sum(wage_expense) / sum(matched_received) * 100` | 同上 | 同上 |
| 贡献利润 | `sum(received) FILTER(has_expense) - food_cost - operating_expense` | 多表JOIN | FILTER vs COALESCE口径要统一 |
### 2.2 口径一致性规则
**核心原则**：同一指标在多个页面展示时，必须使用同一数据源和同一计算方式。
```sql
-- 正确：费用率分母统一为matched_received
sum(operating_expense) / sum(received) FILTER(WHERE has_expense) * 100
-- 错误：分母包含无费用门店
sum(operating_expense) / sum(received) * 100
```
**FILTER vs COALESCE**：
- `sum(x) FILTER(WHERE has_expense)` — 排除无费用门店的整行
- `sum(COALESCE(x, 0))` — 无费用门店的x视为0，但received仍计入分母
- 两者在计算金额时结果相同，但在计算比率时分母不同
## 3. 物化视图模型
### 3.1 设计原则
1. **预聚合到月度+门店粒度**：原始表千万级，API不能直接查
2. **一个视图服务多个API**：避免为每个API建一个视图
3. **字段命名统一**：`received`、`consumption`、`bill_count`在各视图中保持一致
4. **刷新机制明确**：每个视图有对应的刷新脚本
### 3.2 核心视图清单
| 视图 | 粒度 | 用途 | 关键字段 |
|------|------|------|---------|
| mv_store_risk_rating_monthly | 月×门店 | 门店评级 | risk_level, received, bill_count |
| mv_store_operating_expense_monthly | 月×门店 | 费用分析 | food_cost, wage, rent, utility |
| mv_store_platform_economics_monthly | 月×门店 | 平台经济性 | meituan_received, eleme_cost_rate |
| mv_bill_hourly | 月×门店×小时 | 客流分析 | bills, avg_guests |
| mv_overview_daily | 日 | 日度概览 | received, bill_count |
| mv_overview_monthly | 月 | 月度概览 | received, bill_count, avg_bill_value |
| mv_risk_anomaly | 月×门店×账单 | 异常账单 | anomaly_reason, consumption |
| mv_risk_cashier | 月×门店×收银员 | 收银员风险 | bill_count, anomaly_bills |
### 3.3 AI协同验证
```
AI Prompt示例：
"请检查以下物化视图设计是否覆盖了指标体系中的所有L0和L1指标。
指标体系：[附上指标体系文档]
物化视图清单：[附上视图清单]
输出：覆盖度矩阵 + 缺失指标 + 建议"
```
## 4. 逻辑闭环验证
### 4.1 闭环图
```
数据采集 → 物化视图 → API查询 → 前端展示 → 人工决策
↑ ↓
效果检验 ← 任务关闭 ← 执行反馈 ← 任务接收 ← 预警触发
```
### 4.2 AI验证清单
| 验证项 | 检查内容 | 方法 |
|--------|---------|------|
| 数据覆盖度 | 每个指标是否有数据源 | 指标→视图→表→字段 逐项追溯 |
| 计算正确性 | 公式是否正确 | 用已知数据验证计算结果 |
| 口径一致性 | 跨页面同一指标是否一致 | 对比不同API的返回值 |
| 预警完整性 | 每个预警是否有触发条件和任务模板 | 逐条检查预警规则 |
| 任务闭环 | 任务从生成到关闭是否有完整流程 | 模拟走一遍流程 |
| 权限正确性 | 各角色是否只看到应有数据 | 模拟不同角色登录验证 |
| 空状态处理 | 无数据时是否优雅降级 | 测试新月份/新门店场景 |
### 4.3 逻辑断点示例
**断点1**：预警"食材成本率>45%"已配置，但没有对应的任务模板
```
修复：添加任务模板"食材成本率超标整改"
```
**断点2**：任务"排班优化"已配置，但系统没有客流-人力匹配数据
```
修复：补充attendance_records解析逻辑，生成客流-人力匹配指标
```
**断点3**：店长能看到本店数据，但无法看到区域均值对标
```
修复：在/stores/:code API中增加区域均值字段
```
**断点4**：利润瀑布图的received包含无费用门店，导致费率偏低
```
修复：received改为FILTER(WHERE has_expense)口径
```
## 5. AI协同设计输出
### 5.1 技术方案文档
```
1. 数据模型设计
- 原始表ER图
- 物化视图清单和SQL
- 门店名映射表
2. API设计
- 路由清单
- 每个API的SQL查询
- 请求参数和响应格式
- 数据权限规则
3. 前端设计
- 页面清单
- 每个页面的组件布局
- 指标卡配置
- 图表配置
4. 预警与任务设计
- 预警规则清单
- 任务模板库
- 闭环健康度指标
```
### 5.2 验证报告
```
1. 覆盖度报告
- 指标覆盖率：X/Y
- 数据覆盖率：哪些指标有数据，哪些缺数据
2. 口径一致性报告
- 跨页面指标对比表
- 不一致项及修复方案
3. 闭环验证报告
- 预警→任务→执行→反馈 全链路测试结果
- 发现的断点及修复方案
4. 性能预估
- 各API预估响应时间
- 物化视图刷新耗时
```
## 6. 关键注意事项
1. **先验证再编码**：这一步的目的是在写代码前发现逻辑问题，避免返工
2. **AI是协同不是替代**：AI生成方案，人审查业务合理性
3. **闭环比单点重要**：一个指标算错了是bug，一个闭环断了是系统失效
4. **口径要从一开始统一**：后期修复口径不一致的成本远高于初期统一
5. **留出迭代空间**：第一版不需要覆盖所有指标，先跑通核心闭环
docs/智脑实施方法论/06-步骤五-AI协同本体层构建.md
+192
View File
@@ -0,0 +1,192 @@
# 06 · 步骤五：AI协同本体层构建
> 目标：AI参与数据层代码编写——物化视图SQL、导入脚本、数据质量校验，并逐项验证。 `[Delta主导，AI为主]`
>
> FDE角色：这一步是Delta层的核心工作。AI承担80%的代码生成（SQL、脚本），人聚焦审查和验证。本体层的沉淀质量直接决定下一个同类客户的交付速度。
## 1. AI协同模式
### 1.1 工作流程
```
1. 人工提供：数据现状（表结构、样本数据、数据量）
2. AI生成：物化视图SQL草案
3. 人工审查：业务逻辑是否正确
4. AI执行：在数据库上创建视图 + 验证数据
5. 人工确认：抽查数据准确性
6. 迭代：发现问题→AI修复→再验证
```
### 1.2 AI Prompt模式
```
"请基于以下原始表设计物化视图：
- 原始表：bill_records（字段：c003门店, c009消费, c068优惠, c114实收, c175下单时间, c176结账时间, c191收银员）
- 需求：按月×门店×小时聚合账单数、消费、优惠、实收
- 注意：c114可能为空字符串，需COALESCE处理
输出：CREATE MATERIALIZED VIEW SQL + 索引SQL"
```
## 2. 物化视图构建
### 2.1 构建顺序
```
1. 基础视图（不依赖其他视图）
├── mv_bill_hourly（账单小时聚合）
├── mv_overview_daily（日度概览）
└── mv_overview_monthly（月度概览）
2. 门店评级视图（依赖基础视图）
├── mv_store_risk_rating_monthly（门店风险评级）
└── mv_store_benchmark_composite_monthly（门店对标）
3. 费用视图（依赖外部费用数据）
└── mv_store_operating_expense_monthly（门店费用）
4. 风险明细视图（依赖原始表）
├── mv_risk_anomaly（异常账单）
├── mv_risk_zero（零实收）
└── mv_risk_cashier（收银员风险）
5. 平台视图
└── mv_store_platform_economics_monthly（平台经济性）
```
### 2.2 AI协同编写物化视图
**典型交互**：
```
人：bill_records中c003是门店名，c114是实收金额，但有些是空字符串
AI：生成SQL：
CREATE MATERIALIZED VIEW mv_bill_hourly AS
SELECT
c003 AS store_name,
EXTRACT(HOUR FROM c176::timestamp) AS hour,
to_char(c176::timestamp, 'YYYY-MM') AS month,
count(*) AS bills,
sum(COALESCE(NULLIF(c009,'')::numeric, 0)) AS consumption,
sum(COALESCE(NULLIF(c114,'')::numeric, 0)) AS received
FROM bill_records
WHERE c176 IS NOT NULL
GROUP BY 1, 2, 3;
人：门店名需要和费用表对齐，有些名字不一样
AI：补充映射逻辑，使用store_name_mapping
```
### 2.3 异常账单视图设计
```sql
-- AI协同设计的异常判断逻辑
CASE
WHEN consumption > 0 AND received = 0 THEN '有消费无实收'
WHEN discount > consumption THEN '优惠大于消费'
WHEN abs(consumption - discount - received) > 1 THEN '消费-优惠与实收不平'
ELSE NULL
END
```
**关键教训**：阈值0.05元太严格，会将浮点舍入差异标为异常。AI建议初始阈值设为1元，后续根据数据分布调整。
## 3. 数据导入脚本
### 3.1 AI协同编写导入脚本
```
人：这是4月的薪资Excel，列名是中文，需要导入salary_detail_records
AI：生成Python/SQL导入脚本，包含：
- 列名映射（中文→英文字段名）
- 数据类型转换
- 空值处理
- 去重逻辑
- 进度输出
```
### 3.2 导入关键点
| 数据源 | 关键问题 | 解决方案 |
|--------|---------|---------|
| bill_records | c001~c200列名无含义 | 建立字段映射文档 |
| salary_detail_records | salary_period格式"2026年4月" | 查询时用to_char中文格式 |
| attendance_records | department是路径字符串 | extractStore从后往前找"店" |
| 费用数据 | 门店名与账单系统不一致 | store_name_mapping映射表 |
## 4. 数据质量校验
### 4.1 AI协同校验
```
AI Prompt：
"请对以下物化视图进行数据质量校验：
1. 记录数是否合理（与原始表对比）
2. 金额加总是否一致（物化视图 vs 原始表）
3. 是否有NULL或异常值
4. 门店数是否完整
输出：校验SQL + 预期结果 + 实际结果"
```
### 4.2 校验清单
| 校验项 | SQL | 预期 |
|--------|-----|------|
| 门店数 | `SELECT count(DISTINCT store_name) FROM mv_bill_hourly WHERE month='2026-04'` | ~94家 |
| 实收总额 | `SELECT sum(received) FROM mv_bill_hourly WHERE month='2026-04'` | ~6369万 |
| 账单总数 | `SELECT sum(bills) FROM mv_bill_hourly WHERE month='2026-04'` | ~168万 |
| 异常账单占比 | `SELECT count(*) FROM mv_risk_anomaly / SELECT count(*) FROM bill_records` | <5% |
| 物化视图新鲜度 | 对比物化视图和原始表的count | 一致 |
## 5. 门店名映射
### 5.1 映射表构建
```sql
CREATE TABLE public.store_name_mapping (
salary_name TEXT, -- 薪资/考勤系统中的名称
bill_name TEXT -- 账单系统中的名称
);
```
### 5.2 AI协同发现映射
```
AI Prompt：
"请对比以下两个数据源的门店名，找出不一致的：
- 账单系统：SELECT DISTINCT store_name FROM mv_bill_hourly
- 考勤系统：SELECT DISTINCT extractStore(department) FROM attendance_records
输出：需要映射的对照表"
```
### 5.3 代码中的映射查找模式
```typescript
// 构建查找表：同时用原名和映射名
const staffLookup: Record<string, any> = {}
for (const [store, data] of Object.entries(staffSummary)) {
staffLookup[store] = data // 原名
const mapped = nameMap[store]
if (mapped && mapped !== store) {
staffLookup[mapped] = data // 映射名
}
}
```
## 6. 输出物
| 输出物 | 说明 | 验证方式 |
|--------|------|---------|
| 物化视图SQL | 所有视图的CREATE语句 | psql执行成功 |
| 索引SQL | 每个视图的索引 | 查询性能达标 |
| 导入脚本 | 各数据源的导入脚本 | 导入后数据量正确 |
| 映射表 | store_name_mapping | 所有门店能匹配 |
| 数据质量报告 | 校验结果汇总 | 人工抽查确认 |
| 刷新脚本 | 物化视图刷新流程 | 执行后数据更新 |
## 7. 关键注意事项
1. **先查数据再写SQL**：AI生成SQL前，先让它查实际表结构和样本数据
2. **物化视图必须建索引**：无索引的物化视图查询比原始表还慢
3. **刷新脚本要完整**：遗漏任何一个视图的刷新都会导致数据不一致
4. **映射表要持续维护**：新开门店时需要补充映射
5. **AI生成的SQL必须人工审查**：AI可能忽略业务约束（如空值处理、日期格式）
docs/智脑实施方法论/03-指标体系与API开发.md → docs/智脑实施方法论/07-步骤六-AI协同后端API构建与验证.md
+30 -3
View File
@@ -1,4 +1,6 @@
# 03 · 指标体系与API开发
# 07 · 步骤六：AI协同后端API构建与验证
> 目标：AI参与API开发，逐个验证——快速交付能用的代码，不追求完美架构。 `[Delta主导，AI为主]`
## 1. 指标分层设计
@@ -12,9 +14,34 @@ L2: API层 (后端路由，SQL查询 + 业务逻辑)
L3: 展示层 (前端页面，图表 + 表格)
```
## 2. 后端API规范
## 2. 页面与API总览
### 2.1 路由组织
| 页面 | 文件 | 调用的 API |
|------|------|-----------|
| 总部驾驶舱 | DashboardPage.tsx | /overview, /overview/daily, /stores/risk, /stores/priority, /tasks/loop-health, /stores/quadrant, /platform/economics, /situational-awareness/alerts, /store-expense/overview, /overview/yoy, /overview/mom, /overview/trend, /overview/profit-trend |
| 老板驾驶舱 | BossPage.tsx | /overview, /overview/daily, /store-expense/overview, /overview/profit-waterfall, /stores/risk, /stores/priority, /cost-analysis/store-overview, /store-expense/expense-structure, /overview/store-profit-ranking, /overview/profit-opportunity |
| 门店工作台 | StorePage.tsx | /stores/risk, /stores/priority, /tasks/stores/:code/daily-card, /tasks, /stores/:code/daily, /tasks/followup, /sku/attach, /sku/abc, /stores/:code, /situational-awareness/health-score, /stores/:code/meal-period, /stores/:code/category-mix, /stores/:code/cost, /stores/:code/member, /stores/:code/anomalies, /stores/:code/staffing |
| 成本分析 | CostPage.tsx | /cost/comparison, /cost/inventory, /cost/category-benchmark |
| 成本分析(Tab) | cost-analysis/*.tsx | /cost-analysis/overview, /category-comparison, /margin-deviation, /variance-top, /menu-engineering, /profitability, /pricing, /store-overview, /store-ranking, /bom-*, /packaging-*, /material-*, /data-quality, /unmatched-* |
| 费用分析(Tab) | store-expense/*.tsx | /store-expense/overview, /expense-structure, /store-ranking, /store-contribution, /break-even, /loss-diagnosis, /delivery-commission, /rent-risk, /fixed-variable, /efficiency, /store-evaluation |
| 风险监控 | RiskPage.tsx | /risk/anomaly, /risk/zero-received, /risk/cashier |
| 态势感知 | SituationalAwarenessPage.tsx | /situational-awareness/health-score, /alerts, /correlation, /forecast |
| 会员复购 | MemberPage.tsx | /member/comparison, /member/repeat |
| SKU分析 | SKUPage.tsx | /sku/abc, /sku/category |
| 菜单工程 | MenuEngineeringPage.tsx | /analytics-enhanced/menu-engineering/actions |
| 产品生命周期 | ProductLifecyclePage.tsx | /product/products, /product/reviews/overview, /product/reviews |
| BOM穿透 | BomPenetrationPage.tsx | /central-kitchen/bom-penetration |
| 分销对账 | DistributionReconciliationPage.tsx | /distribution/reconciliation |
| 生产计划 | ProductionPlanPage.tsx | /sales-driven/production-plan |
| 任务闭环 | TasksPage.tsx | /tasks |
| 数据导入 | DataImportPage.tsx | /product/import-logs, /product/quality-rules |
| 本体浏览 | OntologyPage.tsx | /tasks/ontology/* |
> 详细的逐页面→API→SQL→数据源字段映射，见 [08-数据溯源与API全量清单.md](08-数据溯源与API全量清单.md)
## 3. 后端API规范
### 3.1 路由组织
```
server/src/routes/
docs/智脑实施方法论/04-前端页面开发.md → docs/智脑实施方法论/08-步骤七-AI协同前端UIUX设计与实现.md
+3 -1
View File
@@ -1,4 +1,6 @@
# 04 · 前端页面开发
# 08 · 步骤七：AI协同前端UIUX设计与实现
> 目标：AI参与页面设计，参考典型页面模板——先交付能用的，再迭代好用的。 `[Delta主导，AI为主]`
## 1. 技术栈
docs/智脑实施方法论/09-步骤八-数据驱动闭环优化.md
+230
View File
@@ -0,0 +1,230 @@
# 09 · 步骤八：数据驱动闭环优化
> 目标：上线不是终点，而是持续优化的起点。建立"数据→分析→问题→方案→实施→反馈→检验→优化"的循环。 `[Echo+Delta]`
>
> FDE角色：这一步体现FDE"把不确定的机会变成可重复的流程"的核心理念。Echo层判断改进方向，Delta层用AI生成方案。闭环转起来才是真落地，否则只是交付了一个系统。
## 1. 闭环模型
```
┌─────────────────────────────────────────────────────┐
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 数据采集 │───→│ 分析诊断 │───→│ 发现问题 │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ ↑ │ │
│ │ ↓ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 优化模型 │←──│ 检验效果 │←──│ 实施改进 │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ ↑ │ │
│ │ ↓ │
│ ┌──────────┐ ┌──────────┐ │
│ │ 参数调优 │←─────────────────│ AI协同方案 │ │
│ └──────────┘ └──────────┘ │
│ │
└─────────────────────────────────────────────────────┘
```
## 2. 各阶段详解
### 2.1 数据采集
| 数据源 | 频率 | 内容 | 质量要求 |
|--------|------|------|---------|
| 收银系统 | 日 | 账单明细 | 完整性>99% |
| 考勤系统 | 月 | 打卡记录 | 覆盖率>95% |
| 薪资系统 | 月 | 薪资明细 | 准确性100% |
| 费用系统 | 月 | 门店费用 | 及时性<5日 |
| 用户行为 | 实时 | 页面访问、任务执行 | — |
### 2.2 分析诊断
**AI协同分析模式**：
```
输入：本月数据 + 上月数据 + 同比数据
AI输出：
1. 整体经营诊断（营收/利润/成本趋势）
2. 异常门店清单（附原因分析）
3. 改善机会排序（按预期收益）
4. 风险预警（下月可能恶化的门店）
```
**分析维度**：
- 趋势分析：月度环比、同比、近6月走势
- 结构分析：品类占比、时段占比、平台占比
- 对标分析：门店vs区域均值、vs标杆店
- 归因分析：利润下降→成本率上升→食材成本上升→哪类菜品
### 2.3 发现问题
**问题分类**：
| 类别 | 典型问题 | 发现方式 | 严重度 |
|------|---------|---------|--------|
| 经营异常 | 门店连续亏损 | 月度贡献利润<0 | 高 |
| 成本失控 | 食材成本率>45% | 月度成本分析 | 高 |
| 人力浪费 | 低谷时段人员冗余 | 客流-人力匹配 | 中 |
| 风险事件 | 异常账单激增 | 异常账单监控 | 高 |
| 执行不力 | 整改任务逾期 | 任务闭环跟踪 | 中 |
| 数据质量 | 物化视图stale | 数据校验脚本 | 低 |
### 2.4 AI协同改进方案
**AI生成方案模板**：
```
问题：XX店食材成本率45%（超标5pp）
AI分析：
1. 原因诊断：
- 牛肉类菜品成本率58%（高于均值12pp）
- 损耗率8%（高于均值3pp）
- 采购单价上涨15%
2. 改进建议：
- 调整牛肉类菜品BOM（预计降本3pp）
- 加强损耗管理（预计降本1pp）
- 评估替代供应商（预计降本1pp）
3. 预期效果：成本率降至40%
4. 跟踪指标：下周成本率、损耗率
```
### 2.5 实施改进
| 改进类型 | 责任人 | 期限 | 跟踪方式 |
|---------|--------|------|---------|
| BOM调整 | 商品部+店长 | 7天 | 下月成本率 |
| 排班优化 | 店长 | 3天 | 客流-人力匹配度 |
| 收银规范 | 店长 | 3天 | 异常账单数 |
| 供应商切换 | 商品部 | 14天 | 采购单价 |
| 人员调整 | 区域经理 | 30天 | 人工费率 |
### 2.6 反馈与检验
**检验方式**：
1. **定量对比**：改进前后指标值对比
2. **趋势验证**：连续2-3周数据是否持续改善
3. **对标验证**：与区域均值/标杆店对比是否缩小差距
4. **副作用检查**：改进某指标是否导致其他指标恶化
**反馈机制**：
- 改进有效 → 沉淀为最佳实践 → 推广到其他门店
- 改进无效 → 重新分析原因 → 调整方案
- 改进有副作用 → 权衡取舍 → 优化方案
### 2.7 优化模型与参数
**需要持续优化的参数**：
| 参数 | 初始值 | 优化依据 | 影响范围 |
|------|--------|---------|---------|
| 异常账单阈值 | 1元 | 误报率<5% | 异常账单数 |
| 高峰人手不足阈值 | 15单/人 | 业务峰值评估 | 客流-人力匹配 |
| 低谷冗余阈值 | 3人 | 门店规模调整 | 客流-人力匹配 |
| 风险评级阈值 | 红/黄/绿规则 | 管理层确认 | 门店评级 |
| 预警触发条件 | 各类规则 | 误报率/漏报率 | 预警数量 |
| 任务期限 | 3/7/14天 | 历史完成率 | 任务逾期率 |
## 3. 闭环运转机制
### 3.1 日循环
```
每日：
- 收银数据自动入库
- 日度概览自动更新
- 营收异动预警检查
- 店长查看日报卡
- 当日任务执行与反馈
```
### 3.2 周循环
```
每周：
- 区域经理周检
- 周度趋势分析
- 任务完成率统计
- 预警处理情况汇总
- AI协同生成周报
```
### 3.3 月循环
```
每月：
- 月度数据导入（考勤/薪资/费用）
- 物化视图刷新
- 月度经营分析（老板驾驶舱）
- 门店评级更新
- 任务闭环健康度评估
- AI协同生成月度诊断报告
- 参数调优评审
- 最佳经验沉淀与推广
```
## 4. AI协同优化模式
### 4.1 AI角色
| 阶段 | AI能力 | 人的角色 |
|------|--------|---------|
| 分析诊断 | 自动生成诊断报告 | 审查判断 |
| 发现问题 | 异常检测、趋势预警 | 确认严重度 |
| 改进方案 | 生成方案草案 | 决策取舍 |
| 效果检验 | 对比分析、副作用检测 | 确认结论 |
| 经验沉淀 | 提炼最佳实践 | 确认可推广性 |
### 4.2 AI Prompt示例
```
"基于以下月度数据，请生成经营诊断报告：
- 本月营收6420万，环比下降3%
- 13家门店亏损，比上月增加2家
- 食材成本率35.3%，上升1.2pp
- 人工费率18.5%，上升0.5pp
- 异常账单3.2万笔，占比1.9%
请输出：
1. 整体诊断（3-5个关键发现）
2. 重点关注门店（附原因）
3. 改进建议（按预期收益排序）
4. 下月风险预警"
```
## 5. 持续优化的关键指标
### 5.1 系统健康度
| 指标 | 目标 | 监控频率 |
|------|------|---------|
| API平均响应时间 | <500ms | 实时 |
| 物化视图刷新耗时 | <5min | 月度 |
| 数据质量校验通过率 | >99% | 月度 |
| 页面加载时间 | <3s | 实时 |
### 5.2 业务价值度
| 指标 | 目标 | 监控频率 |
|------|------|---------|
| 老板驾驶舱月活 | >20次/月 | 月度 |
| 店长工作台日活 | >80%店长 | 日度 |
| 预警处理率 | >90% | 月度 |
| 任务完成率 | >70% | 月度 |
| 整改有效率 | >60% | 月度 |
### 5.3 闭环成熟度
| 等级 | 特征 | 目标 |
|------|------|------|
| L1 起步 | 有数据、无分析 | — |
| L2 可视 | 有Dashboard、无预警 | 本项目已达到 |
| L3 预警 | 有预警、有任务 | 目标状态 |
| L4 闭环 | 任务→执行→反馈→检验 | 持续优化中 |
| L5 智能 | AI自动诊断+推荐方案 | 长期目标 |
## 6. 关键注意事项
1. **闭环不是一次性项目**：是持续运转的管理机制，需要组织保障
2. **数据质量是生命线**：垃圾数据进→垃圾结论出→错误决策→失去信任
3. **不要追求完美模型**：先跑通闭环，再逐步优化参数
4. **人的参与不可少**：AI辅助决策，人做最终判断
5. **经验沉淀最重要**：每次改进的有效经验要沉淀为可复制的最佳实践
6. **定期回顾参数**：业务变化后，预警阈值和评级规则需要调整
docs/智脑实施方法论/01-项目概述与架构.md → docs/智脑实施方法论/10-技术参考-项目概述与架构.md
+2 -2
View File
@@ -1,8 +1,8 @@
# 01 · 项目概述与架构
# 10 · 技术参考：项目概述与架构
## 1. 项目背景
为连锁餐饮企业（西部马华，100+门店）构建数据分析智脑平台，覆盖：
为连锁经营企业（西部马华，100+门店）构建数据分析智脑平台，覆盖：
- **老板驾驶舱**：门店风险评级、营收概览、平台经济性
- **门店分级**：红/黄/绿三色风险评级与明细
- **态势感知**：健康度评分、自动化预警、跨模块关联分析、趋势预测
docs/智脑实施方法论/05-部署与运维.md → docs/智脑实施方法论/11-技术参考-部署与运维.md
+1 -1
View File
@@ -1,4 +1,4 @@
# 05 · 部署与运维
# 11 · 技术参考：部署与运维
## 1. 部署脚本
docs/智脑实施方法论/06-调试排查手册.md → docs/智脑实施方法论/12-技术参考-调试排查手册.md
+1 -1
View File
@@ -1,4 +1,4 @@
# 06 · 调试排查手册
# 12 · 技术参考：调试排查手册
## 1. 问题分类与排查流程
docs/智脑实施方法论/07-通用方法论.md → docs/智脑实施方法论/13-技术参考-通用方法论与避坑指南.md
+1 -1
View File
@@ -1,4 +1,4 @@
# 07 · 通用方法论
# 13 · 技术参考：通用方法论与避坑指南
> 从智脑项目实践中提炼的核心原则和可复制方法论，适用于类似的连锁企业数据产品建设。
docs/智脑实施方法论/14-技术参考-数据溯源与API全量清单.md
+3504
View File
File diff suppressed because it is too large Load Diff
docs/智脑实施方法论/15-技术参考-指标口径一致性分析.md
+154
View File
@@ -0,0 +1,154 @@
# 15 · 技术参考：指标口径一致性分析
> 从数据溯源审计中提取的跨页面重复指标口径对比，以及已发现和待修复的问题清单。
## 1. 跨页面核心指标口径对比
### 1.1 营业收入（消费金额）
| 页面 | 前端变量 | API | API字段 | 数据源表.字段 |
|------|---------|-----|---------|-------------|
| 总部驾驶舱 | `od?.consumption` | /overview | `consumption` | analytics.bill_fact.consumption |
| 老板驾驶舱 | `od?.consumption` | /overview | `consumption` | 同上 |
| 费用总览Tab | `ov.total_consumption` | /store-expense/overview | `total_consumption` | analytics.bill_fact.consumption |
**口径：一致 ✅**
### 1.2 优惠
| 页面 | 前端变量 | API | API字段 | 数据源表.字段 |
|------|---------|-----|---------|-------------|
| 总部驾驶舱 | `od?.discount` | /overview | `discount` | analytics.bill_fact.discount_total |
| 老板驾驶舱 | `od?.discount` | /overview | `discount` | 同上 |
| 费用总览Tab | `ov.total_discount` | /store-expense/overview | `total_discount` | 同上 |
**口径：一致 ✅**
### 1.3 实收
| 页面 | 前端变量 | API | API字段 | 数据源表.字段 |
|------|---------|-----|---------|-------------|
| 总部驾驶舱 | `od?.received` | /overview | `received` | analytics.bill_fact.received_total |
| 老板驾驶舱 | `od?.received` | /overview | `received` | 同上 |
| 费用总览Tab | `ov.total_received` | /store-expense/overview | `total_received` | analytics.mv_store_risk_rating_monthly.received |
| 利润瀑布 | `wf.received` | /overview/profit-waterfall | `received` | analytics.mv_store_risk_rating_monthly.received |
**口径：一致 ✅** — `bill_fact.received_total` 汇总和物化视图汇总结果相同。
### 1.4 账单数
| 页面 | 前端变量 | API | API字段 | 数据源表.字段 |
|------|---------|-----|---------|-------------|
| 总部驾驶舱 | `od?.bill_count` | /overview | `bill_count` | analytics.bill_fact (count(*)) |
| 老板驾驶舱 | `ex?.total_bills` | /store-expense/overview | `total_bills` | analytics.mv_store_risk_rating_monthly.bill_count |
**口径：一致 ✅**
### 1.5 客单价
| 页面 | 计算方式 | 值 |
|------|---------|-----|
| 总部驾驶舱 | `avg(received_total)` from bill_fact | 38.29 |
| 老板驾驶舱 | `sum(received)/sum(bill_count)` | 38.29 |
**口径：一致 ✅** — 数学结果相同。
### 1.6 门店贡献利润（实际）
| 页面 | API | 计算方式 | 值 |
|------|-----|---------|-----|
| 总部驾驶舱 | /store-expense/overview | `sum(received) FILTER(费用匹配) - food_cost - operating_expense` | 6,982,110.42 |
| 老板驾驶舱(指标卡) | 同上 | 同上 | 同上 |
| 老板驾驶舱(瀑布图) | /overview/profit-waterfall | `sum(received) FILTER(has_expense) - food_cost - operating_expense` | 同上 |
**口径：一致 ✅**（已修复）
### 1.7 食材成本
| 页面 | API | 计算方式 |
|------|-----|---------|
| 总部驾驶舱 | /store-expense/overview | `sum(actual_food_cost)` |
| 老板驾驶舱(瀑布图) | /overview/profit-waterfall | `sum(COALESCE(actual_food_cost,0))` |
| 费用总览Tab | /store-expense/overview | 同总部 |
**口径：一致 ✅** — `sum(NULL)` 忽略 vs `sum(COALESCE(NULL,0))` 加0，结果相同。
### 1.8 费用率
| 页面 | 计算方式 | 值 |
|------|---------|-----|
| 总部驾驶舱 | `sum(operating_expense)/matched_received*100` | 53.77% |
| 老板驾驶舱(瀑布图) | `wf.total_expense/wf.received*100`（matched口径） | 53.77% |
| 费用总览Tab | 同总部 | 53.77% |
**口径：一致 ✅**（已修复）
### 1.9 门店风险分布 / P0+P1门店 / 盈利亏损数
| 指标 | 页面 | API | 数据源 |
|------|------|-----|--------|
| 风险分布 | 总部/老板 | /stores/risk | mv_store_risk_rating_monthly.risk_level |
| P0/P1 | 总部/老板 | /stores/priority | mv_store_action_priority_deep_monthly |
| 盈利/亏损 | 总部/老板 | /store-expense/overview | count FILTER(actual_store_contribution > 0) |
**口径：一致 ✅**
## 2. 口径一致性保障原则
1. **同一指标多页面展示时，必须使用同一数据源**（物化视图或原始表，不能混用）
2. **分母口径必须一致**：如"费用率"分母必须统一为 matched_received（仅含费用匹配门店）
3. **FILTER vs COALESCE**：`sum(x) FILTER(WHERE has_expense)` 与 `sum(COALESCE(x,0))` 在无NULL行时结果相同，但语义不同——FILTER排除整行，COALESCE只替换NULL值
4. **物化视图 vs 原始表**：优先用物化视图，避免直接查原始表（性能差 + 可能stale不一致）
5. **新增页面时**：如果复用已有指标，必须检查数据源是否一致，避免口径分裂
## 3. 已发现问题清单
### 已修复 ✅
| # | 问题 | 位置 | 修复方式 |
|---|------|------|---------|
| 1 | 利润瀑布 store_contribution 口径不一致 | /overview/profit-waterfall | received等改为 `FILTER(WHERE has_expense)` |
| 2 | 瀑布图费率分母不一致 | 前端除法 | received改为matched口径后分母一致 |
| 3 | mv_overview_monthly 刷新缺失 | 刷新脚本 | 加入DELETE+INSERT步骤 |
| 4 | 优惠率/毛利率/会员占比硬编码为0 | /overview API | 修正SQL计算 |
| 5 | Schema前缀错误 | /channel API | 移除analytics.前缀 |
| 6 | 列名不存在 | /stores/risk等 | SELECT * 或0 AS替代 |
| 7 | 日期格式不匹配 | 考勤相关API | to_char改中文格式 |
| 8 | 客流-人力匹配在岗人数不合理 | /situational-awareness/correlation | 改用打卡数据解析 |
| 9 | 客流月度汇总vs日均未对齐 | 同上 | 客流除以30天 |
### 待确认 ⚠️
| # | 问题 | 位置 | 影响 | 建议 |
|---|------|------|------|------|
| 1 | KPI达成率利润口径不一致 | /analytics-enhanced/kpi | 利润率偏低~0.7pp | 分母改为matched_received |
| 2 | store-profit-ranking COALESCE导致无费用门店排名异常 | /overview/store-profit-ranking | 利润TOP5可能含无费用门店 | 加FILTER(has_expense) |
| 3 | StorePage公司均值硬编码 | StorePage.tsx:188 | 不随数据更新 | 改为API动态获取 |
| 4 | StorePage scorecard直接查bill_records | /stores/:code | 可能与物化视图不一致 | 改用物化视图 |
## 4. 口径检查方法论
### 4.1 新增指标时的检查流程
```
1. 该指标是否在其他页面已存在？
→ 是：检查数据源是否一致（表、字段、过滤条件）
→ 否：记录到溯源文档
2. 分子分母的过滤条件是否一致？
→ 如：费用率分母是否都用了matched_received
3. 是否用了物化视图？
→ 优先用物化视图，避免直接查原始表
4. 是否有NULL处理差异？
→ sum(x) vs sum(COALESCE(x,0)) 在有NULL行时结果不同
5. curl + psql 双向验证
→ API返回值与直查数据库一致
```
### 4.2 定期口径审计
```
1. 运行溯源文档中的"跨页面对比"部分
2. 对每个指标，在所有出现的页面验证值是否一致
3. 不一致的，定位差异原因（数据源、过滤条件、计算方式）
4. 修复并更新文档
```
docs/智脑实施方法论/README.md
+44 -10
View File
@@ -1,22 +1,56 @@
# 玄谋智脑 · 实施方法论与执行手册
> 本文档体系总结"连锁餐饮企业智脑"项目的全部工作步骤、关键决策点和通用方法论，目标是形成可复制的执行手册，对类似项目快速落地。
> 以经营战略为起点、以数据闭环为终点的企业管理方法论。借鉴FDE（前线部署工程）精神，适配中国连锁经营企业国情——用AI替代部分FDE职能，降低对人力的依赖。
## 文档结构
## 核心理念
玄谋智脑不是一套技术系统，而是**战略驱动→数据支撑→闭环执行→持续优化**的管理体系。
```
老板战略 → 指标体系 → 数据本体 → 执行闭环 → AI协同构建 → 持续优化
↑ |
└────────────────── 反馈与优化 ←──────────────────────────┘
```
## 八步工作法
| 步骤 | 文件 | 核心问题 | 输出 |
|------|------|---------|------|
| 一 | [02-步骤一-老板访谈与指挥层构建.md](02-步骤一-老板访谈与指挥层构建.md) | 老板要看什么、管什么、决策什么 | 指标体系、驾驶舱原型 |
| 二 | [03-步骤二-数据现状与本体层构建.md](03-步骤二-数据现状与本体层构建.md) | 现有数据能否支撑指标体系 | 数据溯源、物化视图 |
| 三 | [04-步骤三-中层访谈与执行层准备.md](04-步骤三-中层访谈与执行层准备.md) | 谁来做、做到什么程度、如何考核 | 岗位-指标矩阵、任务模板 |
| 四 | [05-步骤四-AI协同模型设计与逻辑闭环.md](05-步骤四-AI协同模型设计与逻辑闭环.md) | 业务逻辑闭环是否完整 | 模型设计、闭环验证 |
| 五 | [06-步骤五-AI协同本体层构建.md](06-步骤五-AI协同本体层构建.md) | 数据层代码和验证 | 物化视图、导入脚本 |
| 六 | [07-步骤六-AI协同后端API构建与验证.md](07-步骤六-AI协同后端API构建与验证.md) | API层代码和验证 | 可运行的API |
| 七 | [08-步骤七-AI协同前端UIUX设计与实现.md](08-步骤七-AI协同前端UIUX设计与实现.md) | 前端界面实现 | 可用的Dashboard |
| 八 | [09-步骤八-数据驱动闭环优化.md](09-步骤八-数据驱动闭环优化.md) | 持续优化循环 | 闭环运转机制 |
> 总览见 [01-总体框架与八步工作法.md](01-总体框架与八步工作法.md)
## 技术参考
| 文件 | 内容 |
|------|------|
| [01-项目概述与架构.md](01-项目概述与架构.md) | 项目背景、技术架构、数据流、部署拓扑 |
| [02-数据接入与治理.md](02-数据接入与治理.md) | 原始数据导入、物化视图体系、数据质量校验、映射表管理 |
| [03-指标体系与API开发.md](03-指标体系与API开发.md) | 指标分层设计、后端API规范、常见SQL陷阱与修复模式 |
| [04-前端页面开发.md](04-前端页面开发.md) | 页面模板、组件规范、月份参数管理、数据展示约定 |
| [05-部署与运维.md](05-部署与运维.md) | 部署脚本、数据库备份、FRP隧道、PM2进程管理 |
| [06-调试排查手册.md](06-调试排查手册.md) | 常见问题分类、排查流程、修复模式速查 |
| [07-通用方法论.md](07-通用方法论.md) | 可复制的核心原则、风险清单、快速复制Checklist |
| [10-技术参考-项目概述与架构.md](10-技术参考-项目概述与架构.md) | 技术架构、数据流、部署拓扑 |
| [11-技术参考-部署与运维.md](11-技术参考-部署与运维.md) | 部署脚本、FRP隧道、PM2 |
| [12-技术参考-调试排查手册.md](12-技术参考-调试排查手册.md) | 问题分类、排查流程、实际案例 |
| [13-技术参考-通用方法论与避坑指南.md](13-技术参考-通用方法论与避坑指南.md) | 核心原则、风险清单、Checklist |
| [14-技术参考-数据溯源与API全量清单.md](14-技术参考-数据溯源与API全量清单.md) | 逐页面→API→SQL→字段映射（3500行） |
| [15-技术参考-指标口径一致性分析.md](15-技术参考-指标口径一致性分析.md) | 跨页面口径对比、问题清单 |
## 阅读建议
- **新项目启动**：按 01→09 顺序阅读八步工作法
- **新成员上手**：先读 01 了解框架，再读 10 了解架构，最后查 14 了解API全量映射
- **排查问题**：直接查 12 调试排查手册
- **口径审计**：查 15 指标口径一致性分析
- **快速复制**：查 13 通用方法论中的 Checklist
## 适用场景
- 连锁餐饮/零售企业的数据分析平台建设
- 连锁经营企业（餐饮/零售/服务/教培）的数据分析平台建设
- 基于PostgreSQL物化视图的BI系统
- Express + React + Recharts 技术栈的Dashboard项目
- 多租户SaaS架构的垂直行业数据产品
- AI协同的企业数字化转型项目
- FDE模式在中国连锁经营行业的适配性落地