连锁门店数据分析 Agent

1. 手册用途与麦舍首版交付目标

FDE 按本手册组织业务调研、核验数据、推进开发、协调验收和完成交接。每个阶段明确找谁、做什么、产出什么、由谁确认。

本文件记录已确认的建设方向和待执行方法，不证明服务已实现、已验收或已上线。当前能力检索未找到可用于证明该 Agent 已上线的有效能力档案。具体人员、日期和状态在项目执行记录中维护。

完成首版时应交付

• 经业务验收的企业客户端查询入口及首批场景。
• 与版本绑定的指标、权限、映射和执行定义，以及独立核对的验收案例。
• 业务使用说明、运行与恢复说明、明确的支持和维护责任。
• 首轮实施复盘与经验证的模板调整；验证不足的做法继续标注适用限制。

阅读顺序：先看客户范围和责任，再按阶段任务推进；填写材料时使用模板；进入试用前逐条检查验收用例。

2. 客户事实、场景与范围

首版场景边界

范围分层

• 首版：企业入口、双库受控查询、首批场景、权限、证据回执、回归、培训和交接。
• 按客户需要扩展：SaaS API、服务端 CLI、Excel／CSV及必要分析快照；本期记录接入方法，不承诺同时开发。
• 待真实需求再评估：多租户平台、通用配置后台、统一同步调度等产品化能力。

首版不包含新报表前端、现有 BI 平台依赖、任意 SQL／命令执行、外部业务数据自动写回或自动经营决策。

3. FDE 与各方责任

FDE 负责把项目推进到可使用、可验收、可维护；业务口径与数据访问范围由相应责任人确认。

以上是项目协作责任，不新增业务系统流程角色。人事、运营、财务按职责参与；最高管理层承担使用或项目决策责任。实际姓名在启动时落实。

项目推进只维护一份执行记录

• 每个任务有执行人、依赖、预计投入、目标日期、产出链接和确认人；区分 FDE 工作时间与等待业务配合时间。
• 启动时约定检查节奏；每次推进检查只更新已完成证据、下一任务、阻塞事项和需要谁决定。
• 场景、公式、数据源、权限、交付日期变化时，FDE 记录影响并推动相关责任人确认；未确认的变更不混入已发布版本。
• HTML 保存标准方法和样例。飞书保存项目实例的实际任务与状态，Git 保存服务、配置和方法版本；实际链接待启动时填写。

填写方式见任务与责任表及问题／变更记录。

4. 架构、口径治理与可信分析规则

首版保持一个服务端数据分析引擎，以模块化方式管理身份、语义、执行、数据源和结果。WorkBuddy 负责交互与调用；每次执行由服务端校验。

4.1 三类材料的职责

4.2 指标从候选到发布

flowchart LR
  A[候选指标
保留来源] --> B[业务口径核验
归口人确认]
  B --> C[大小店数据绑定
FDE与数据维护人核验]
  C --> D[黄金案例验证
独立期望结果]
  D --> E[试运行
权限与回执验证]
  E --> F[已发布
Data Engine可调用]
  B -.冲突或缺项.-> R[退回待确认]
  C -.字段或映射不足.-> R
  D -.结果不一致.-> R
  F --> G[版本变更或停用
保留追溯]

发布状态固定为“候选、待业务确认、待数据验证、试运行、已发布、已停用”。业务含义由人事／运营／财务对应归口人确认；跨部门冲突由项目决策人裁决；FDE 负责把确认结果转成受控执行定义，不得自行决定业务公式。

4.3 Agent允许与禁止行为

推荐执行链：用户说法 → 别名与指标ID → 参数补全或反问 → 权限与店型路由 → 已发布执行定义 → 数据结果与口径回执。任何必要环节缺失即停止执行或返回受限结果。

4.4 身份与权限

服务端验证调用身份并映射内部人员，取得授权的指标、店型、组织、门店和字段范围。可选指标和解释也应受授权范围限制；在数据查询前拦截越权。调岗、停用和临时授权到期的生效方式与时限在接入阶段实测并确认。

用户令牌的验证和业务授权分开处理；不能仅信任客户端传入的人员名称、角色或门店列表。数据库及其他数据源凭证放在服务端，文档与日志不保存凭证正文。

4.5 语义与固定执行

Agent 可解释问题并组织参数；服务端只执行已发布定义。不支持或不唯一的问题进入反问／未支持反馈，不现场生成任意 SQL、API 端点、Shell 命令或计算规则。客户扩展可使用固定 API 调用、非交互受控 CLI、受校验的文件计算定义。

4.6 大小店选择、比较与汇总

• 只查一种店型时，仅访问对应来源。需要两侧数据时分别执行并返回各自来源和状态。
• 跨店型比较先检查定义、时间、单位和统计范围。不能比较时，可分别展示获授权结果并解释差异。
• 汇总另外确认聚合方式、去重范围和适用维度。比例、平均值等不能默认相加；人数或对象数需要明确重复识别依据。
• 门店编码按数据源区分，不能直接用同号连接两个数据库。只有业务确有跨系统同一门店关系时，再确认映射依据及有效期间。

4.7 独立基准与版本

黄金集是“已经独立核对的测试案例集合”。每个案例包括原始问题、身份与范围、指标及参数、数据截面、期望结果、核对依据、核对人和允许差异。以源明细核对或已确认的独立方法作为依据，不用待测执行定义自身的输出充当正确答案。

对持续变化的数据库，测试需固定可重复的数据截面或可复核期间，并说明延迟与后补数据影响；这不等于首期必须建设快照平台。回归应记录服务、Skill、语义、权限和执行定义版本。

4.8 趋势、对比与原因线索

输出明确期间、基期、粒度、授权范围及变化计算。业务需确认周期对齐、空值、分母为零、历史组织变化和补录规则。观察到的变化与原因解释分开；只有数据支持的分解或对比可以作为线索，并能定位到证据。原因未知时明确说不足以判断，由管理者决定是否进一步调查。

4.9 结果回执与异常

内部审计记录使用者、查询范围、执行与配置版本、实际访问来源、完成状态和耗时；记录范围、保留期与访问权限在交接时明确。

5. 分阶段执行手册

阶段目标与完成条件固定；人数、工时、日期和具体指标由项目实际情况填写。代表场景验证通过后再扩大范围。

6. 验收、培训、上线与交接

验收案例须先补齐实际指标、样本、账号、数据期间和期望值，再执行并记录结果。下表是首版的最小覆盖要求，不代表已经通过。

6.1 可观察的验收结果

编号链接到相关规则或执行阶段。每条结果单独记录“通过／失败／未执行”，并附实际证据；同一条中的检查点分别记录结果，避免一个“通过”掩盖未检查项。

6.2 阈值如何确定

在试用前确认样本范围、计算公式、数据量、负载、统计窗口与责任人。授权拦截、口径追溯和回执完整性要求在约定用例中全部通过；性能、并发、可用性、数据延迟和稳定期长度由测量与业务要求确定，不凭经验填写承诺。

业务成效只衡量已选场景，例如同一任务能否独立完成、核对次数、完成时间；比较前后必须使用一致的方法。回答数量或使用次数不能单独证明业务收益。

6.3 上线与交接检查

• 发布范围与版本对应验收记录。
• 关键场景通过；延期项明确接受人与影响。
• 使用者完成实操，知道支持范围与求助入口。
• 部署、数据源访问及账号权限落实。
• 运行检查、故障分派及回退步骤经过验证。
• 维护接收人、支持时段和响应约定明确。
• 稳定期窗口与退出条件明确。
• 凭证通过受控方式交接，文档仅记录位置与责任。

需要交接的材料：使用说明、服务与配置版本、部署和检查步骤、故障定位与恢复步骤、回归入口、数据源与授权维护责任。详见交接与复盘模板。

7. 其他连锁客户的实施与复用

沿用相同的阶段方法，重新核验客户事实。麦舍的双库、门店类型、部门名称和指标公式不自动成为行业默认值。

7.1 先完成客户差异核验

7.2 选择接入方式

单店可使用单一门店范围并简化组织配置；没有跨店分析需求时省去对应步骤。流程复杂程度随客户实际需要调整，但口径、数据来源和结果验收仍需完成。

7.3 判定复用方式并估算差异

7.4 试点、扩展与方法更新

1. 复用阶段 1–4，先完成新客户目标、责任、数据与口径核验。
2. 选择新客户代表场景，采用其独立基准完成端到端试点。
3. 由该客户验收，再扩展到其确认的场景／门店，执行试用、上线与交接。
4. 按复盘规则更新模板或实现；记录适用条件、版本及验证项目。

8. 可复制模板、麦舍示例与来源

以下字段可复制到项目执行记录或客户交付材料中填写。本静态页面不保存填写内容；“待填写”是模板状态，不是已完成记录。

8.7 启动时仍需落实

8.8 原始指标体系的准入问题

原始BI指标体系是重要候选来源，但当前不能整份发布。首批指标核验时至少处理以下问题：

以上为准入检查项，不在本手册内替业务作出结论，也不直接改写原始工作稿。

8.9 来源与版本说明

V4 与指标准入模板进入产品设计方案目录；V3、历史 HTML、原始指标体系和既有图片保留。名称修正用于本方案当前展示内容，不改变历史来源文件名、数据库名或仓库路径。