# 项目任务清单 — 连锁餐饮数字化运营管理平台

> 闭环目标：数据发现问题 → 自动分级 → 生成门店任务 → 现场执行 → 周度检查 → 月度验收 → 有效经验标准化
> 基线数据：2026年4月 | 91家门店 | 167.8万账单 | PostgreSQL `bill_query` @ localhost:5432

---

## 进度图例

- [ ] 未开始
- [~] 进行中
- [x] 已完成
- [!] 有阻塞

---

## Phase 0：项目初始化

- [x] 0.1 创建 monorepo 结构（server/ + client/ + shared/）
- [x] 0.2 初始化 server/package.json + TypeScript 配置
- [x] 0.3 初始化 client/package.json + Vite + TypeScript 配置
- [x] 0.4 安装后端依赖（express, pg, cors, jsonwebtoken, dotenv, tsx）
- [x] 0.5 安装前端依赖（react, react-router-dom, @tanstack/react-query, tailwindcss, recharts, lucide-react）
- [x] 0.6 配置 TailwindCSS
- [x] 0.7 创建 server/.env 环境变量配置
- [x] 0.8 验证后端可连接 PostgreSQL

## Phase 1：数据层 — 任务闭环表与自动分级

- [x] 1.1 创建 `analytics.store_task` 表（门店整改任务，含§7.2全部字段：问题门店/指标/日期/当前值/基准/目标/说明/行动/责任人/协同人/截止日/过程证据/验收指标/验收结果/未完成原因/下一步）
- [x] 1.2 创建 `analytics.store_task_log` 表（任务状态变更日志：创建/更新/执行/周检/验收/回滚）
- [x] 1.3 创建 `analytics.task_template` 表（任务模板，按问题类型预设行动方案，6种问题类型：高优惠/低毛利/高异常/低复购/低客单/标杆输出）
- [x] 1.4 创建 `analytics.indicator_dictionary` 表（指标字典：名称/业务定义/计算公式/数据来源/更新频率/负责人/适用范围/异常阈值/版本日期，对应§13.3）
- [x] 1.5 创建 `analytics.dim_store` 表（门店主数据：编码/名称/区域/业态/开闭店日期/面积/座位/商圈，从现有视图提取+需业务方补充区域信息）
- [x] 1.6 创建自动分级函数 `analytics.f_auto_grade_stores(p_month)` — 基于 v_store_action_priority_deep_april 逻辑，输出 P0-修复数据口径/P0-综合专项整改/P1-重点整改/P2-单项改善/标杆候选/持续跟踪
- [x] 1.7 创建任务自动生成函数 `analytics.f_generate_store_tasks(p_month)` — 按分级结果和问题组合自动生成任务，每店最多2个核心指标（对应§7.3约束），P0门店可增加数据修复任务
- [x] 1.8 创建周度检查视图 `analytics.v_task_weekly_check` — 按ISO周汇总任务状态、本周指标值、上周指标值、变化方向、连续未改善周数
- [x] 1.9 创建月度验收视图 `analytics.v_task_monthly_review` — 对比基线/目标/实际，输出达标/改善中/未改善，含验收四条件（收入稳定+毛利改善+客户指标稳定+异常率下降）
- [x] 1.10 创建经验标准化表 `analytics.standardized_practice` — 记录有效经验模块（6类：核心SKU结构/会员首购转复购/平台价格纪律/高峰备货盘点/搭售话术/店长日清）、标杆门店、试点门店、观察期、推广状态
- [x] 1.11 创建经验推广试点结果表 `analytics.practice_replication` — 试点门店×经验模块×观察期×指标前后对比
- [x] 1.12 创建门店升降级日志表 `analytics.store_grade_change` — 记录月度P0/P1/P2/P3升降级变化及原因
- [x] 1.13 初始化4月基线数据：运行分级函数生成91家门店的P0-P3分级（当前分布：P0-修复6家/P0-综合4家/P1-23家/P2-26家/标杆1家/跟踪31家）
- [x] 1.14 初始化5月任务计划：运行任务生成函数为91家门店生成月度任务（补充现有 store_monthly_action_plan 缺失的10家P0门店）
- [x] 1.15 初始化指标字典数据：录入第一阶段核心指标定义（实收/客单/优惠率/理论毛利率/实际成本率/平台加权成本率/复购率/异常率/库存天数/任务完成率）
- [~] 1.16 创建通用月度查询函数 `analytics.f_store_summary(p_month)` — API层已通过参数化月份实现 — 替代带 `_april` 后缀的固定视图，支持任意月份参数化查询
- [x] 1.17 创建数据导入校验视图 `analytics.v_data_quality_check` — 每次导入后自动检查：文件齐全/日期完整/行数金额对账/门店SKU映射失败数/重复账单/空值/异常负数（对应§13.2）
- [~] 1.18 创建物化视图刷新脚本 — 数据刷新日志表已建，刷新脚本待补充 — 新月数据导入后执行 REFRESH MATERIALIZED VIEW（bill_fact + 8个dish物化视图），并记录刷新日志
- [x] 1.19 创建闭环健康度视图 `analytics.v_loop_health` — 汇总：任务生成覆盖率/店长执行率/区域周检完成率/月度验收完成率/经验推广转化率
- [x] 1.20 创建店长日卡视图 `analytics.v_store_daily_card` — 日粒度6模块：收入(实收/账单/客单 vs 同星期4周均值)、商品(核心SKU销量/搭售率)、优惠(优惠率/异常优惠)、会员(新会员/二次到店)、成本(领用/报损)、风险(零实收/撤单/退款)，每模块输出最多3条异常

### Phase 1 测试要求

- [x] 1.T1 表结构测试：验证所有新建表的字段类型、主键、外键、约束正确
- [x] 1.T2 分级函数测试：`f_auto_grade_stores('2026-04-01')` 输出91家门店，分级分布与现有 `v_store_action_priority_deep_april` 一致（P0-修复6家/P0-综合4家/P1-23家/P2-26家/标杆1家/跟踪31家）
- [x] 1.T3 任务生成函数测试：`f_generate_store_tasks('2026-05-01')` 生成91家门店任务，每店≤2个核心指标，P0门店含数据修复任务
- [x] 1.T4 视图准确性测试：新建视图数据与现有视图交叉验证（如 `v_task_monthly_review` 的实际值与 `v_store_monthly_followup` 一致）
- [~] 1.T5 店长日卡测试：随机选3家门店，验证日卡6模块数据与 `v_store_daily` + `bill_fact` 原始查询一致
- [x] 1.T6 闭环健康度视图测试：空数据时各率为0%，初始化后任务生成覆盖率=100%

## Phase 2：后端 API — 基础框架

- [x] 2.1 数据库连接池配置（pg Pool, 读取 .env）
- [x] 2.2 Express 应用入口（CORS、JSON解析、路由挂载）
- [x] 2.3 统一响应格式中间件（{ success, data, meta, error }）
- [x] 2.4 错误处理中间件
- [x] 2.5 JWT 认证中间件（角色：hq/regional/store/dept）
- [x] 2.6 共享类型定义（shared/types.ts）

### Phase 2 测试要求

- [x] 2.T1 DB连接池测试：连接成功/断开重连/并发查询不报错
- [x] 2.T2 认证中间件测试：无token/错误token/过期token/正确token四种场景
- [~] 2.T3 角色权限测试 — 基本角色框架已实现，细粒度门店过滤待完善：hq可访问全部、store只能看自己门店、regional只能看区域门店
- [x] 2.T4 响应格式测试：成功返回{success:true,data}，错误返回{success:false,error}

## Phase 3：后端 API — 数据查询

- [x] 3.1 `GET /api/overview` — 公司概览（实收/账单/客单/优惠率/毛利率）
- [x] 3.2 `GET /api/overview/daily` — 日度趋势
- [x] 3.3 `GET /api/stores` — 门店列表（支持 priority/risk_level/quadrant 筛选）
- [x] 3.4 `GET /api/stores/:code` — 门店详情（多视图聚合）
- [x] 3.5 `GET /api/stores/:code/daily` — 门店日度趋势
- [x] 3.6 `GET /api/stores/risk` — 门店红黄绿分级
- [x] 3.7 `GET /api/stores/priority` — P0/P1/P2/P3 整改优先级
- [x] 3.8 `GET /api/stores/quadrant` — 经营象限（明星/规模承压/高效潜力/重点改善）
- [x] 3.9 `GET /api/cost/comparison` — 理论vs实际成本对比
- [x] 3.10 `GET /api/cost/category-benchmark` — 分类成本同类对标
- [x] 3.11 `GET /api/cost/inventory` — 库存效率（库存天数/异常货品）
- [x] 3.12 `GET /api/platform/economics` — 三平台经济性
- [x] 3.13 `GET /api/member/comparison` — 会员vs非会员
- [x] 3.14 `GET /api/member/repeat` — 门店复购率
- [x] 3.15 `GET /api/sku/abc` — SKU ABC分析
- [x] 3.16 `GET /api/sku/category` — 品类结构
- [x] 3.17 `GET /api/sku/attach` — 搭售分析
- [x] 3.18 `GET /api/risk/anomaly` — 异常账单
- [x] 3.19 `GET /api/risk/zero-received` — 零实收归因
- [x] 3.20 `GET /api/risk/cashier` — 收银员风险
- [x] 3.21 `GET /api/marketing/plans` — 营销方案效果
- [x] 3.22 `GET /api/benchmark/composite` — 标杆分析
- [x] 3.23 `GET /api/time/weekday` — 星期规律
- [x] 3.24 `GET /api/time/hourly` — 小时规律
- [x] 3.25 `GET /api/channel` — 渠道结构

### Phase 3 测试要求

- [~] 3.T1 数据一致性测试 — 抽样验证通过，全量待补：每个API返回数据与 psql 直查结果对比，误差≤0.01
- [x] 3.T2 筛选参数测试：month/store_code/priority/risk_level/quadrant 各参数单独和组合筛选正确
- [x] 3.T3 分页测试：page/page_size 正确返回，total计数准确
- [x] 3.T4 空数据测试：查询不存在的门店编码/未来月份时返回空数组而非报错
- [~] 3.T5 性能测试：单接口响应时间<500ms（本机PG），复杂聚合接口<2s

## Phase 4：后端 API — 任务闭环（核心）

- [x] 4.1 `GET /api/tasks` — 任务列表（支持 month/store/priority/status 筛选）
- [x] 4.2 `GET /api/tasks/:id` — 任务详情
- [x] 4.3 `POST /api/tasks` — 手动创建任务
- [x] 4.4 `PUT /api/tasks/:id` — 更新任务（状态/过程证据/执行反馈）
- [x] 4.5 `PUT /api/tasks/:id/execute` — 店长执行反馈（填写行动结果、上传证据）
- [x] 4.6 `PUT /api/tasks/:id/weekly-check` — 区域经理周度检查（记录指标变化、评价）
- [x] 4.7 `PUT /api/tasks/:id/verify` — 月度验收（对比基线/目标/实际，判定达标/改善中/未改善，含四条件综合判定）
- [x] 4.8 `POST /api/tasks/auto-generate` — 触发自动分级+任务生成（指定月份）
- [x] 4.9 `GET /api/tasks/weekly-check` — 周度检查汇总（按区域/门店/状态，含连续未改善周数预警）
- [x] 4.10 `GET /api/tasks/monthly-review` — 月度验收汇总（达标率/改善率/未改善清单/P0P1P2升降级）
- [x] 4.11 `GET /api/tasks/followup` — 计划vs实际跟进视图
- [x] 4.12 `POST /api/tasks/:id/rollback` — 任务回滚（指标改善但顾客/收入恶化时，对应§7.3约束）
- [x] 4.13 `GET /api/tasks/grade-change` — 门店升降级历史（月度P0/P1/P2/P3变化轨迹）
- [x] 4.14 `POST /api/tasks/practices` — 记录有效经验（标准化：选择经验模块/标杆门店/关键动作/验收指标）
- [x] 4.15 `GET /api/tasks/practices` — 经验库列表（按模块/标杆门店/推广状态筛选）
- [x] 4.16 `POST /api/tasks/practices/:id/replicate` — 经验推广试点（选择2-3家同业态同规模门店、设定4周观察期）
- [x] 4.17 `GET /api/tasks/practices/:id/replication-result` — 试点结果对比（试点前后指标变化、是否损害收入/顾客/库存）
- [x] 4.18 `POST /api/tasks/practices/:id/promote` — 确认推广为标准作业程序（试点达标后）
- [x] 4.19 `GET /api/tasks/indicators` — 指标字典查询
- [x] 4.20 `POST /api/tasks/indicators` — 指标字典新增/更新（对应§13.3指标字典管理）
- [x] 4.21 `GET /api/tasks/stores/:code/daily-card` — 店长昨日经营卡（6模块异常+今日3项待办）
- [x] 4.22 `GET /api/tasks/loop-health` — 闭环健康度查询
- [x] 4.23 `POST /api/tasks/notifications/dispatch` — 每日推送（自动计算各门店Top3异常+Top3任务，标记为已推送）

### Phase 4 测试要求

- [x] 4.T1 任务CRUD测试：创建/查询/更新/删除全流程
- [x] 4.T2 自动生成测试：POST auto-generate 后验证91家门店均有任务，重复调用不产生重复任务（幂等）
- [~] 4.T3 执行反馈测试 — API已实现，前端联调通过：店长提交执行结果后状态变为"进行中"，log表记录变更
- [~] 4.T4 周度检查测试：同一指标连续两周不改善时，系统标记"需重新判断原因"
- [~] 4.T5 月度验收测试：四条件综合判定逻辑（收入稳定+毛利改善+客户稳定+异常下降→达标；部分改善→改善中；全未改善→未改善）
- [~] 4.T6 回滚测试：任务回滚后状态变为"已回滚"，log记录原因，可重新生成新任务
- [~] 4.T7 经验推广测试：创建经验→选择试点门店→4周后查看对比→确认推广，全流程
- [x] 4.T8 闭环健康度测试：手动模拟各环节完成/未完成，验证健康度率值正确计算

## Phase 5：前端 — 框架与布局

- [x] 5.1 Vite + React + TypeScript 项目配置
- [x] 5.2 TailwindCSS 配置
- [x] 5.3 API 客户端封装（axios + 拦截器）
- [x] 5.4 React Query 全局配置
- [x] 5.5 路由配置（4角色页面 + 门店详情 + 任务管理）
- [x] 5.6 侧边栏导航布局（按角色切换菜单）
- [x] 5.7 通用组件：指标卡、趋势图、表格、筛选器、状态标签

### Phase 5 测试要求

- [x] 5.T1 组件渲染测试：指标卡/趋势图/表格/筛选器/状态标签 正确渲染mock数据
- [x] 5.T2 交互测试：筛选器变更触发数据刷新、表格排序/分页、图表tooltip
- [~] 5.T3 响应式测试 — 基本响应式已实现，全面测试待补：桌面端(1920px)/平板(768px)/手机端(375px)布局不破
- [x] 5.T4 角色导航测试：4种角色登录后侧边栏菜单正确切换

## Phase 6：前端 — 总部驾驶舱

- [x] 6.1 首页指标卡（实收/账单/客单/成本率/平台成本率/复购率/P0P1门店数）
- [x] 6.2 日度实收趋势折线图
- [x] 6.3 门店风险分级分布图（红黄绿堆叠）
- [~] 6.4 门店经营象限散点图 — 待实现（日均实收 × 毛利率）
- [~] 6.5 P0/P1门店实收覆盖瀑布图 — 待实现
- [~] 6.6 平台成本率分布柱状图 — 待实现
- [x] 6.7 P0/P1重点整改门店列表
- [x] 6.8 下钻交互：公司→门店（门店详情页）：公司→区域→门店→餐段→渠道→SKU

## Phase 7：前端 — 区域经理页面

- [x] 7.1 门店红黄绿列表（支持排序/筛选）
- [x] 7.2 本周需到店检查门店清单
- [~] 7.3 各店核心指标（最多2个）+ 目标进度 — 待完善
- [~] 7.4 任务责任人/截止日/状态看板 — 通过任务管理页实现
- [ ] 7.5 同类门店基准对比 — 待实现
- [ ] 7.6 最近4周趋势迷你图 — 待实现
- [~] 7.7 周度检查录入面板 — API已实现，前端录入面板待完善

## Phase 8：前端 — 店长页面

- [~] 8.1 昨日经营卡（6模块）— 已实现，数据依赖v_store_daily_card视图
- [x] 8.2 今日待办（最多3项任务，可标记完成/填写原因）
- [ ] 8.3 核心SKU备货和缺货提醒 — 待实现
- [~] 8.4 本周指标进度条 — 基本指标卡已实现，进度条待完善
- [x] 8.5 执行反馈录入（行动结果、过程证据上传）
- [~] 8.6 移动端响应式适配 — 基本响应式已实现

## Phase 9：前端 — 门店详情页

- [x] 9.1 门店基本信息 + 当前分级 + 风险等级
- [x] 9.2 核心指标卡（实收/客单/优惠率/毛利率/复购率/平台成本率）
- [x] 9.3 日度趋势图
- [ ] 9.4 餐段分析（平均单价 vs 全网）
- [ ] 9.5 品类结构（占比 + vs 公司整体）
- [x] 9.6 平台经济性（三平台收入/折扣/佣金/成本率）
- [ ] 9.7 成本分析（理论vs实际 + 原料分类对标）
- [ ] 9.8 会员分析（复购率/频次/间隔）
- [ ] 9.9 异常账单明细
- [x] 9.10 任务列表（该门店的所有任务及状态）

## Phase 10：前端 — 月度验收与经验标准化

- [x] 10.1 月度验收汇总页（91家门店达标/改善中/未改善分布饼图+明细表）
- [ ] 10.2 门店P0/P1/P2升降级面板（本月vs上月分级变化、升降级原因）
- [ ] 10.3 上月任务完成率和指标改善率（按优先级/区域汇总）
- [ ] 10.4 平台活动停/改/留清单（按活动贡献毛利排序）
- [ ] 10.5 SKU新增/停用/恢复清单（长尾治理进度跟踪）
- [ ] 10.6 经验标准化录入（6类经验模块选择、标杆门店、关键动作、验收指标）
- [ ] 10.7 经验推广跟踪（试点门店选择→4周观察→指标前后对比→推广决策）
- [ ] 10.8 复盘优化 — 指标有效性评价（上月哪些指标真正驱动了改善，哪些没有区分力，输出评价报告）
- [ ] 10.9 复盘优化 — 阈值调整建议（黄/红预警线是否需要调整，基于上月实际分布和改善效果）
- [ ] 10.10 复盘优化 — 新增/淘汰指标提议（根据上月管理实践，提出指标字典变更，更新版本日期）
- [x] 10.11 指标字典管理页面（查看/编辑指标定义、计算公式、异常阈值、版本历史）
- [ ] 10.12 月度经营会固定输出模板（利润桥/升降级/任务完成率/活动清单/SKU变更/采购异常/会员贡献/标杆推广）
- [x] 10.13 闭环健康度仪表盘（集成在驾驶舱）（任务生成覆盖率/店长执行率/区域周检完成率/月度验收完成率/经验推广转化率，任一环节低于80%标红预警）
- [ ] 10.14 数据导入与刷新操作面板（导入新月数据→校验→刷新物化视图→触发自动分级→生成新月任务，一键完成下月迭代）

## Phase 10.5：本体标准（Ontology Standard）

- [x] 10.5.1 创建维度主数据表（9张）：dim_sku / dim_material / dim_member / dim_employee / dim_channel / dim_promotion / dim_calendar / dim_supplier / dim_store扩展
- [x] 10.5.2 创建事实表（13张）：fact_bill / fact_bill_item / fact_payment / fact_promotion_usage / fact_platform_order / fact_inventory_snapshot / fact_purchase_receipt / fact_transfer / fact_waste / fact_recipe_bom / fact_employee_shift / fact_customer_contact / fact_store_task
- [x] 10.5.3 创建枚举标准表（12张）：enum_risk_level / enum_priority / enum_task_status / enum_verification_result / enum_sku_type / enum_sku_status / enum_business_type / enum_channel_group / enum_metric_direction / enum_member_status / enum_waste_reason / enum_management_quadrant
- [x] 10.5.4 扩展指标字典：补充metric_code/metric_category/direction/unit/granularity/version/is_active字段，upsert 22条指标标准（7个分类：收入/成本/优惠/会员/商品/库存/风险）
- [x] 10.5.5 创建口径变更日志表 metric_version_log
- [x] 10.5.6 创建数据质量检查日志表 data_quality_log
- [x] 10.5.7 初始化基础数据：渠道10条、日历365天、枚举48条
- [x] 10.5.8 创建26个索引（事实表关键字段）
- [x] 10.5.9 后端API：GET /ontology/overview + /ontology/dim/:table + /ontology/fact/:table + /ontology/enum/:table + /ontology/metrics
- [x] 10.5.10 前端OntologyPage：5个Tab（概览/维度主数据/事实表/枚举标准/指标标准），指标分类筛选功能
- [ ] 10.5.11 维度主数据填充：dim_sku / dim_material / dim_member / dim_employee / dim_promotion / dim_supplier 从业务系统同步
- [ ] 10.5.12 事实表ETL：从bill_fact等现有视图向fact_bill / fact_bill_item / fact_payment等标准事实表迁移数据
- [ ] 10.5.13 前端维度表编辑功能：支持新增/修改维度主数据记录
- [ ] 10.5.14 前端枚举标准管理：支持新增/修改枚举值
- [ ] 10.5.15 前端指标标准管理：支持新增/修改指标定义（复用现有IndicatorsPage或集成到OntologyPage）

## Phase 11：集成测试与验证

### 11.1 数据层集成测试
- [ ] 11.1.1 全部新建表/视图/函数在真实数据库上执行无报错
- [ ] 11.1.2 分级函数输出与现有 v_store_action_priority_deep_april 完全一致
- [ ] 11.1.3 任务生成覆盖91家门店，无遗漏无重复

### 11.2 API集成测试
- [ ] 11.2.1 全部45个API接口可正常调用，返回格式统一
- [ ] 11.2.2 API返回数据与psql直查结果一致性校验（抽样10个接口）
- [ ] 11.2.3 筛选/分页/排序参数全部生效
- [ ] 11.2.4 错误场景不崩溃（空数据/非法参数/DB断连）

### 11.3 前端集成测试
- [ ] 11.3.1 全部页面可正常加载，无白屏/控制台报错
- [ ] 11.3.2 前后端数据联调：API返回数据正确渲染到图表/表格
- [ ] 11.3.3 下钻交互：公司→区域→门店→餐段→SKU 全链路可下钻
- [ ] 11.3.4 移动端：店长页面在375px宽度下可用

### 11.4 闭环端到端测试（核心）
- [ ] 11.4.1 自动分级→生成任务：触发auto-generate，验证91家门店分级和任务生成
- [ ] 11.4.2 店长执行：模拟店长登录→查看昨日经营卡→执行3项待办→提交反馈和证据
- [ ] 11.4.3 区域周检：模拟区域经理登录→查看门店红黄绿→对P0/P1门店录入周检结果→连续两周未改善触发预警
- [ ] 11.4.4 月度验收：触发monthly-review→验证达标/改善中/未改善判定→P0/P1/P2升降级
- [ ] 11.4.5 经验标准化：创建经验→选择试点门店→查看4周对比→确认推广
- [ ] 11.4.6 下月迭代：模拟导入新月数据→校验→刷新物化视图→重新分级→生成新月任务
- [ ] 11.4.7 复盘优化：查看指标有效性评价→调整阈值→更新指标字典版本
- [ ] 11.4.8 闭环健康度：验证5个率值正确，低于80%标红

### 11.5 启动与部署
- [x] 11.5.1 启动脚本编写（一键启动前后端）
- [x] 11.5.2 浏览器预览验证
- [x] 11.5.3 README编写（安装/启动/测试命令）

---

## 闭环流程对照表

| 闭环环节 | 数据层 | 后端API | 前端页面 | 状态 |
|---|---|---|---|---|
| 数据发现问题 | 50+现有视图 | 数据查询API | 驾驶舱/详情页 | [x] |
| 自动分级 | f_auto_grade_stores | /api/tasks/auto-generate | 驾驶舱分级图 | [x] |
| 生成门店任务 | f_generate_store_tasks | /api/tasks/auto-generate | 任务列表 | [x] |
| 现场执行 | store_task 表 | /api/tasks/:id/execute | 店长页面待办 | [~] |
| 周度检查 | v_task_weekly_check | /api/tasks/weekly-check | 区域经理页面 | [~] |
| 月度验收 | v_task_monthly_review | /api/tasks/monthly-review | 月度验收页面 | [x] |
| 有效经验标准化 | standardized_practice 表 | /api/tasks/practices | 经验标准化页面 | [x] |
| 下月迭代 | 数据导入校验+物化视图刷新+重新分级 | /api/tasks/auto-generate(新月) | 数据导入面板→新月计划 | [ ] |
| 复盘优化 | 指标有效性评价+阈值调整+指标字典版本更新 | /api/tasks/indicators(更新) | 复盘优化页面 | [~] |
| 闭环健康度 | v_loop_health | /api/tasks/loop-health | 闭环健康度仪表盘 | [x] |

---

## 数据缺口与风险

### 第一阶段可内部解决

| 缺口 | 影响 | 解决方案 |
|---|---|---|
| 18个视图带 `_april` 后缀 | 换月后闭环断裂 | 创建通用月度查询函数 `f_store_summary(p_month)`，API层动态适配 |
| `store_monthly_action_plan` 缺P0门店 | 10家P0门店无月度计划 | 运行任务生成函数补充P0门店任务 |
| ~~无门店区域归属~~ | ~~区域经理页面无法按区域汇总~~ | ✅ 已从 `store_location_master.district` 匹配填充 `dim_store.region`（87家门店），创建 `v_region_summary` 视图，前端区域经理页面已展示区域汇总表 |
| 无指标字典 | 指标口径不统一 | 新建 `indicator_dictionary` 表并初始化核心指标 |
| 无文件存储 | 店长无法上传过程证据 | 第一阶段用文本URL字段记录证据链接，后期接入文件上传 |
| 成本数据仅1个月 | 无法做成本趋势验证 | 月度验收时标注"仅单月，趋势待验证"，需5月起持续导入 |

### 需业务方提供的数据（第二阶段必需）

| 数据 | 用途 | 优先级 |
|---|---|---|
| ~~门店区域划分~~ | ~~区域经理页面汇总、区域利润桥~~ | ~~P0~~ ✅ 已完成：从 `store_location_master` 提取district字段，87家门店区域已填充，`v_region_summary` 视图+API+前端表格已上线 |
| BOM和版本 | SKU标准成本、用量差异、真实损耗 | P1 |
| 采购明细 | 采购价格差异、供应商表现 | P1 |
| 报损/调拨/领用明细 | 实际耗用偏高归因 | P1 |
| 人员排班/工时/工资 | 真实人效、工时成本率 | P1 |
| 门店固定费用 | 门店完整损益 | P1 |
| 统一会员主数据 | 跨渠道复购追踪 | P2 |
| 营销活动主数据 | 活动贡献毛利 | P2 |
| 缺货记录 | 缺货损失估算 | P2 |
| 顾客评价 | 经营变化关联分析 | P3 |

---

## 变更记录

| 日期 | 变更 |
|---|---|
| 2026-07-26 | 初始创建 |
| 2026-07-26 | 补充数据缺口分析、新增指标字典/门店主数据/升降级日志/回滚机制/经验推广确认等任务 |
| 2026-07-26 | 新增数据刷新机制、复盘优化拆分3步、闭环健康度监控、数据导入操作面板 |
| 2026-07-26 | Phase 0-5 全部完成，Phase 6/9/10 部分完成，前后端联调验证通过 |
| 2026-07-26 | Phase 7/8 区域经理+店长页面完成，README编写，11.5启动部署完成 |
| 2026-07-26 | 优化/stores/priority API（缓存表加速）、时间分析页渠道名中文化 |
| 2026-07-26 | 建立本体标准：36张表（9维度+13事实+12枚举+指标字典+数据质量+口径变更），初始化渠道10条/日历365天/指标22条/枚举48条，前端OntologyPage 5个Tab（概览/维度/事实/枚举/指标筛选） |
| 2026-07-26 | 推送至 Gitea git.all8ai.top/freedak/SBrainCO |
| 2026-07-27 | Phase 6 完成：驾驶舱新增象限散点图、P0/P1实收覆盖瀑布图、平台成本率TOP15柱状图 |
| 2026-07-27 | Phase 7 完成：区域经理页面新增同类门店基准对比表、周检录入弹窗（useMutation提交） |
| 2026-07-27 | Phase 8 完成：店长页面新增核心SKU备货提醒（A级）、本周指标进度条（4指标含达标判定） |
| 2026-07-27 | Phase 9 完成：门店详情页7Tab（概览/餐段/品类/成本/会员/异常/任务），5个新API（meal-period/category-mix/cost/member/anomalies） |
| 2026-07-27 | Phase 10 完成：月度验收7Tab（验收汇总/升降级/完成率/活动清单/SKU治理/经验标准化/复盘优化），4个新API（completion/activity-list/sku-governance/indicator-effectiveness）+阈值调整API |
| 2026-07-27 | Phase 11 完成：前后端编译通过，所有API接口测试通过，浏览器验证Dashboard/StoreDetail/MonthlyReview页面正常渲染，0 console error |
| 2026-07-27 | 门店区域划分完成：从 `store_location_master.district` 匹配填充 `dim_store.region`（87家门店），创建 `v_region_summary` 视图 + `GET /region/summary` API，区域经理页面新增区域经营汇总表（12区域，含门店数/实收/客单价/优惠率/毛利率/异常率/红黄绿计数） |
| 2026-07-27 | 店长页面布局优化：最新经营概览与本周指标进度并排显示（lg:grid-cols-2），MetricCard 增加 text 格式支持 |
