这一页给你一份可以直接喂给 AI 编程助手的指令,复刻「巡检 → 整改 → 经营分」这条管理闭环。适合已经跑通 M1~M3、想把门店管理从"靠人盯"升级成"靠分数说话"的团队。
读完你会知道:
- 为什么巡检、整改、经营分必须做成一个闭环,而不是三个独立功能
- 模板快照和规则版本化这两件事,为什么在第一版就要做,补做代价极高
- 超期整改怎么接入订货锁框架,做到"自动锁、复核过、自动解"
- 一份可复算的经营分月报应该长什么样
把线下巡店这件事数字化成一条闭环:
- 巡检——督导按结构化模板到店检查,拍照、定位、逐项打分;
- 整改——不合格项自动变成带期限的整改任务,门店提交整改、督导复核;
- 约束——超期未整改的门店,自动接入订货锁框架(M3 里搭好的那套),整改复核通过自动解锁;
- 经营分——巡检得分和营业额达标等板块按可配置权重聚合成一个月度综合分,再按可配置的分界表落到档位(如 A/B/C/D),每月出一份构成明细可复算的月报。管理动作挂在档位上,不挂具体分值。
做完这一步,门店管理就从"督导嘴上说"变成了"系统里一个分数",而且这个分数有牙齿——不整改就订不了货。
开工前确认以下里程碑已完成,否则先回去补:
| 依赖 | 页面 | 为什么需要 |
|---|---|---|
| M2 核心域 | 01-core-domain.md | 门店、员工、角色权限是巡检工单和整改责任人的地基 |
| M3 订货商城(锁框架) | 02-ordering-mall.md | 超期整改要接入统一的订货锁框架,锁/解锁/豁免走同一个入口 |
| M4 营业额 | 05-turnover-dashboards.md | 营业额达标情况是经营分的一个板块,分数要从那边取数 |
背景与模式讲解见 巡检与经营分:把门店管理变成一个分数,建议先读一遍再动手。
把下面整块复制给你的 AI 编程助手。
请在现有 Django 项目上实现「巡检 + 整改 + 经营分」模块。遵守项目既有约定:
函数式视图、loads_data(req) 解析 POST JSON、to_resp() 返回、code 字符串 '0'
表示成功;鉴权沿用统一登录态与角色权限;路由挂在 /api/inspection/ 前缀下。
## 一、巡检模板(结构化检查项)
1. 建模板主表 InspectionTemplate:名称、适用场景说明、状态(启用/停用)、
创建人、创建时间。
2. 建检查项表 InspectionItem(FK → 模板):所属板块(如 卫生/出品/服务/陈列,
板块名可自由配置)、检查项名称、检查标准描述、分值、是否必须拍照、排序号。
3. 模板支持增删改检查项,但**历史工单绝不受影响**(见第二节的快照要求)。
4. 提供模板 CRUD 接口:列表 / 详情(含全部检查项)/ 新建 / 编辑 / 停用。
停用是软状态,不物理删除。
## 二、巡检工单(照片 + 定位 + 打分)
1. 建工单主表 InspectionOrder:门店 FK、巡检人 FK、使用的模板 FK、
巡检时间、提交时的定位经纬度、总分、状态(进行中/已提交)。
2. 建工单明细表 InspectionOrderItem:逐条记录每个检查项的
**快照字段**(检查项名称、所属板块、检查标准、满分分值——从模板复制,
不做 FK 依赖展示)+ 实际得分 + 照片列表 + 备注。
红线:工单一旦提交,展示与计算只读快照字段,绝不回查模板实时内容。
这样模板后续怎么增删改,历史工单都能原样还原当时检查了什么、扣了多少。
3. 打分规则:每项得分 ∈ [0, 满分];低于满分即视为"不合格项"
(阈值可先写死为"未满分即不合格",预留每项可配置合格线的字段)。
4. 接口:发起巡检(选门店+模板,生成工单和明细快照)/ 逐项保存打分 /
提交工单(校验必拍照项已传图、写入定位、算总分、状态置已提交)。
5. 照片存对象存储,库里只存 key/URL;定位存经纬度两个 Float 字段。
## 三、不合格项自动生成整改任务
1. 工单提交时,对每个不合格项自动创建整改任务 RectificationTask:
来源工单明细 FK、门店 FK、责任人(默认该店店长)、问题描述(取快照的
检查项名称+标准+巡检备注)、整改期限(默认提交时间 + N 天,N 可配置,
示例:3 天,示例数字,非真实数据)、状态机:
待整改 → 已提交待复核 → 复核通过 / 驳回(驳回退回待整改,期限不重置)。
2. 门店端接口:我的整改任务列表 / 提交整改(整改说明 + 整改后照片,必填)。
3. 督导端接口:待复核列表 / 复核通过 / 驳回(驳回必填理由)。
4. 复核人默认为原巡检人,允许有管理权限的角色代复核。
## 四、超期未整改接入订货锁框架
1. 复用项目已有的统一订货锁框架(锁记录表 + 单一豁免入口),新增一种
锁类型 rectification_overdue。不要在订货流程里另写 if 判断,
锁与解锁都通过锁框架的统一入口操作。
2. 定时任务(走项目统一的定时任务体系)每日扫描:存在"已超期且状态仍为
待整改/驳回"任务的门店 → 调锁框架加锁;该门店所有超期整改任务
都复核通过后 → 自动解锁。
3. 加锁/解锁动作要写操作日志(谁/何时/因哪条任务),锁提示文案里带上
具体超期任务,让店长知道该干什么才能解锁。
4. 豁免走锁框架已有的统一豁免入口,本模块不另造豁免逻辑。
## 五、经营分聚合(板块加权 + 档位映射,均可配置)
经营分是两层结构:第一层板块加权算出综合分,第二层把综合分映射到档位。
两层都要做,缺了档位层这套机制只剩一半。
1. 综合分 = Σ(板块得分 × 板块权重)。板块示例(示例数字,非真实数据,
与结构篇《巡检与经营分》的示例一致):巡检 40%、营业额 25%、
培训 15%、日常运营 20%。
2. 权重存配置表 ScoreWeightConfig,不写死在代码里:板块编码、板块名称、
权重、取数说明。提供管理接口可改。校验:同一版本内权重之和必须为 100%。
3. 每个板块的得分来源:
- 巡检板块:当月该店所有已提交工单的得分率(得分/满分)聚合,
当月整改任务的按期完成率并入本板块一起折算;
- 营业额板块:从营业额模块(TurnoverRecord 及其达标统计结果)
取当月达标情况折算;
- 培训、日常运营等其余板块先留扩展点,按板块编码注册取数函数。
4. 档位映射:综合分不直接使用,按可配置分界表落到档位。建配置表
ScoreGradeConfig:档位编码、档位名称、分数下界/上界、排序。
示例(示例数字,非真实数据):90 分以上 A 档、75~89 B 档、
60~74 C 档、60 以下 D 档。校验:各档位区间必须连续覆盖满分区间
且互不重叠。管理动作(激励、约谈、限制扩张等)一律挂在档位上,
不挂具体分值——这是消灭"差 1 分要不要处理"扯皮的关键。
5. 月度计算产出 ShopMonthlyScore:门店、月份、综合分、**档位**、
每个板块的原始得分/权重/加权得分(全部落库,这就是"构成明细")。
## 六、规则版本化(历史月按当时规则算)
1. 权重配置表和档位分界表都必须带生效日期 effective_date:改规则 =
插入一条新版本记录,旧记录不改不删。计算某月分数时,取"该月月初
时点生效"的那个版本。
2. 红线:任何时候重算历史月份,都必须按该月当时生效的规则版本算,
绝不允许用最新配置回填历史。已出月份的分数与档位,月中改权重或
改档位分界都不受影响。
3. 每条 ShopMonthlyScore 记录要存所引用的规则版本标识(权重版本 +
档位分界版本),做到从结果能反查当时用的是哪套规则。
## 七、月报生成任务
1. 定时任务:每月初生成上月全量门店的经营分月报(先算 ShopMonthlyScore,
再渲染月报)。任务要幂等:重复触发只覆盖同月数据,不产生重复记录。
2. 月报内容:门店排名、综合分与档位、各板块得分×权重的构成明细、
环比变化、当月不合格项 TOP 与整改完成情况。所有数字必须能从落库的明细复算出来,
月报本身不做任何"只存在于报表里"的二次加工。
3. 提供查询接口(按月/按店),并预留推送能力:把月报摘要推送到
管理群(推送渠道做成抽象接口,先实现你项目已接的 IM,如飞书/微信群)。
## 八、收尾要求
1. 更新你项目的 CLAUDE.md:巡检/整改/经营分的模型、路由前缀、
锁类型 rectification_overdue、定时任务挂在哪一套调度里。
2. 新建或更新口径文档(如 SCORE_RULES.md):板块构成、权重与档位分界
的版本化规则、合格线定义、整改期限与锁的触发口径。以后每次改规则,先改文档再改代码。
3. 迁移文件、接口冒烟(发起巡检→打分→提交→生成整改→超期锁→复核解锁
全链路)跑通后再交付。- 巡检工单提交后,不合格项自动生成整改任务,期限、责任人正确
- 整改超期后门店被自动加订货锁;全部超期任务复核通过后自动解锁;锁走统一锁框架,订货流程里没有散落的特判
- 驳回整改会退回待整改状态且不重置期限,继续超期继续锁
- 月中修改板块权重,已出月份的经营分不变;下月起按新权重计算;两个月的记录各自能反查到所用规则版本
- 月度结果同时落综合分与档位,档位与当月生效的分界表一致;月中修改档位分界,已出月份的档位不变
- 档位分界表保存时校验区间连续覆盖且互不重叠,不满足直接拒绝
- 任选一家店一个月,用落库的板块明细手工加权,能复算出月报上的综合分,分毫不差
- 修改巡检模板(增删检查项、改分值)后,历史工单的展示与得分完全不变(读的是快照)
- 权重配置保存时校验和为 100%,不满足直接拒绝
- 月报生成任务重复触发不产生重复数据(幂等)
- CLAUDE.md 与口径文档已同步更新,规则口径与代码一致
-
历史工单显示错乱 症状:模板删了一个检查项,老工单里那一项凭空消失,总分对不上。 根因:工单明细只存了检查项 FK,展示时回查模板实时内容。 铁律:工单提交即快照,历史展示与计算只读快照,永不回查模板。
-
改一次权重,历史排名全变 症状:月中调整板块权重,上个月已经公布的门店排名跟着变了,运营同学被质疑"分数造假"。 根因:权重只有一份"当前值",重算历史时用了最新配置。 铁律:规则带生效日期做版本化,历史月永远按当时生效的版本算。
-
锁逻辑长在订货代码里 症状:想给某店豁免整改锁,发现订货流程里还有第二处 if 在拦,豁免了也订不了货。 根因:没有复用统一锁框架,新锁类型自己在订货链路上加了特判。 铁律:所有订货锁(营业额、整改、欠费……)一律走同一个锁框架和同一个豁免入口。
- 巡检与经营分:把门店管理变成一个分数 —— 本 prompt 对应的模式讲解
- 订货商城:价格快照与订单一致性 —— 锁框架所在的模块;"快照"思想在那边也有一次完整演绎
- 营业额:录入、抓取与达标锁 —— 经营分的营业额板块取数来源
- 数据口径:最贵的一类坑 —— 为什么规则版本化和可复算月报值得第一版就做
- 定时任务:双系统并存的教训 —— 月报与超期扫描任务挂调度前先读