# 客户签约看板 · 标准项目提示词

项目代号：ZK-DASHBOARD-2.0 适用端：PC 2.0 / 移动端 / 南区专属看板 部署域名：zk1.zhengl.vip 提示词版本：V1.0 整理日期：2026-10-22 文档性质：唯一执行口径

0. 执行者须知

0.1 你将以「可直接上线的成品」为标准完成本项目，而不是输出示意页、静态样稿或伪代码。

0.2 本文件第 1–13 章为执行规范；第 14 章为历史指令冲突的裁决结论；第 15 章为仍需业务确认的事项；附录为术语、流程步骤与文案。发生冲突时，按「专项页面规范 > 通用规范」「后轮指令 > 前轮指令」「第 14 章裁决 > 原文」的顺序处理。

0.3 同目录下的《客户签约看板_修订指令归档_V1.md》只用于人工溯源，不作为并行需求重复执行；执行时只需本文件。

0.4 产出物必须纯净：页面正文、HTML 注释、CSS/JS 注释、控制台输出、接口返回中，不得出现本提示词内容、页面布局说明、字段映射说明、数据源说明、「MySQL 实时同步」「数据表」等元信息。

0.5 除用户明确要求外，不得在生成的新页面、新方案中书写「本版相对上版修改了什么」之类的版本对比；版本差异只写入 README / CHANGELOG。

0.6 不得用假数据、示例数据、随机数冒充实盘数据。接口失败时显示明确的错误态与重试入口，不得静默显示 0。

0.7 所有颜色、标签、文案、状态顺序必须来自统一字典与统一 CSS 变量，禁止 PC、移动端、南区看板各写一套。

0.8 每轮实现必须可验证：完成一个模块即自检数据、交互、响应式与深浅色，再进入下一个模块；单轮工作量控制在 60 分钟内，复杂任务拆分为「实现 → 校验 → 修复」的闭环。

0.9 遇到歧义不得自行猜测业务口径；先按第 15 章提问，确认后再实现。

1. 项目背景与目标

1.1 业务背景

本项目服务于「药店智能体」连锁客户的签约与交付跟进。客户从签约开始，依次经过开通、系统对接、系统测试、渠道费充值、使用培训、落地执行、落地跟进，最终流程完成。业务方需要在同一块看板中同时回答四个问题：

现在签约了多少客户、多少门店，距离年度任务还有多远。
每个区域、每种连锁类型、每位销售的签约结构如何。
每个流程阶段积压了多少客户，卡在谁手里。
某一家连锁客户当前处于什么状态、由谁负责、下一步做什么。

1.2 产品目标

一屏看清全局：核心指标、流程进度、结构分布、趋势、明细，按「总览 → 分组 → 单客户」三层下钻。
三端一致：PC 2.0、移动端、南区专属看板的统计口径、色彩语义、标签样式、状态顺序完全一致。
数据可信：所有数字来自同一份主数据与同一套聚合函数；筛选对全量数据生效，而不是只对当前页生效。
移动端好用：单列信息流、底部四大操作、无横向滚动、无嵌套滚动条、单手可操作。
页面干净：不出现数据源、同步方式、备案以外的无关说明，不出现重复计数与冗余标签。

1.3 成功标准

任一指标卡片上的数字，都能通过点击下钻到对应的客户清单，清单条数与卡片数字一致。
任一筛选条件变化后，相关区块在同一帧内更新，页面不整页刷新。
同一客户在 PC、移动端、南区看板中的区域、类型、状态、销售、客服、培训人完全一致。
移动端在 375×667、390×844、430×932 三种视口下无横向滚动、无文字截断、无按钮遮挡。
PC 端在 1440×900 与 1920×1080 下，首屏可见 5 个指标卡与流程导航图，第三排三卡不换行。
验收清单（第 13 章）全部通过。

2. 交付范围

2.1 页面与文件

页面	建议文件	设备	数据范围	说明
入口路由	`index.php`	全设备	—	按设备自动分流，支持 `?v=pc` / `?v=m` 强制指定
智能体客户看板 2.0	`pc.html`	PC	全部区域	主看板，功能最完整
移动端看板	`mobile.html`	手机/平板	全部区域	单列信息流 + 底部四按钮
南区专属看板	`south.html`	PC	仅南区	省份卡片 + 销售开发卡片
数据接口	`api.php`	—	—	只读，输出规范化客户数据与元信息
配置	`config.php`	—	—	数据库、字段设置口令、修正规则；禁止前端可见

配套文件：assets/css/tokens.css、assets/css/app.css、assets/js/dict.js、assets/js/aggregate.js、assets/js/api.js、assets/js/pc.js、assets/js/mobile.js、assets/js/south.js、assets/vendor/（图表库本地化）、README.md、CHANGELOG.md、backup/。

2.2 版本关系

现有 1.0 看板完整保留，不覆盖、不删除，作为口径与视觉的参照基线。
2.0 必须继承 1.0 的全部指标能力、筛选能力、字段设置能力与客户明细能力，并在此基础上增加本文件定义的内容。
南区专属看板是 2.0 的区域裁剪版，沿用同一数据接口与同一套聚合逻辑，不单独维护第二套口径。
移动端是 2.0 的移动重排版，指标不减少核心项，但按第 6 章的顺序与形态呈现。

2.3 非目标

不做用户注册、登录、角色权限体系；仅「字段设置」需要口令。
不做数据新增、编辑、删除；所有接口只读。
不做邮件、短信、企业微信推送。
不做 Excel/PDF 导出（除非后续单独提出）。
不引入需要联网鉴权的 CDN、字体、图表服务。

3. 数据源与数据字典

3.1 连接信息

项	值	说明
主机（公网）	`tx.zhengl.vip`	仅用于运维排查
主机（服务器本机）	`127.0.0.1`	生产接口必须走本机
端口	`3306`
数据库	`zkcrm`
用户	`zkcrm`
密码	不写入本文件、不写入前端、不写入日志	通过 `config.php` 或环境变量 `DB_PASS` 注入
字符集	`utf8mb4`	连接与表均为 utf8mb4
主表	`jdy_data_20`（默认） / `jdy_data_11`（字段结构参考）	见 3.2 与第 15 章

安全要求：数据库口令只能存在于服务器端配置文件或环境变量中；api.php 不得把连接信息、SQL 语句、原始异常返回给浏览器。

3.2 主表选择与过滤

线上 1.0 使用 jdy_data_20，截至整理日有 61 条有效客户记录；源提示词给出的 jdy_data_11 有 9 条记录。两张表字段结构一致。
默认以 jdy_data_20 作为生产主表，保证与 1.0 数据连续；表名放入 config.php 的 DB_TABLE，切换表不改代码。
所有查询必须带 WHERE _deleted = 0，忽略 deleteTime 非空的记录。
只读取业务需要的列，禁止 SELECT * 后把 _raw 整体返回前端。

3.3 字段字典

下表为业务字段与物理列的对应关系。物理列名去掉了前导下划线（例如 _widget_1791449342205 在表中为 widget_1791449342205）。

业务字段	字段 ID / 物理列	类型	说明
表单名称	`formName`	string	固定为「新增智能体签约」
数据 ID	`_id`	string	简道云数据唯一 ID
应用 ID	`appId`	string	应用唯一 ID
表单 ID	`entryId`	string	表单唯一 ID
提交人	`creator`	json	`status`：-1 离职、0 未加入、1 已加入
修改人	`updater`	json	同上
删除人	`deleter`	json	同上
提交时间	`createTime`	string	UTC 时间戳
更新时间	`updateTime`	string	UTC 时间戳；用于「最新数据同步时间」
删除时间	`deleteTime`	string	UTC 时间戳
流程状态（流程引擎）	`flowState`	number	2 手动结束、1 已完成、0 进行中
选择连锁	`widget_1791449342204`	json	形如 `{"id":"..."}`
连锁 ID	`widget_1791449342205`	string	业务主键，去重优先使用
销售	`widget_1791449342208`	json	人员对象，见 3.5
区域	`widget_1791449342211`	string	南区 / 北区
连锁名称	`widget_1791449342206`	string	展示名称
签约主体名称	`widget_1791449342209`	string	合同主体
门店数	`widget_1792048325259`	number	整数，单位「家」
连锁类型	`widget_1792048325267`	string	全国百强 / 区县百强 / 50+ / 50-
连锁业务对接人姓名	`widget_1791882979503`	string
连锁业务对接人联系电话	`widget_1791882979504`	json	`{"phone":"...","verified":false}`
连锁技术对接人姓名	`widget_1791882979505`	string
连锁技术对接人联系电话	`widget_1791882979506`	json	同上
签约时间	`widget_1791510326270`	string	UTC 时间戳；所有日期筛选以此为准
服务开始时间	`widget_1791449342217`	string	UTC 时间戳
服务结束时间	`widget_1791449342218`	string	UTC 时间戳
客服	`widget_1791509478932`	json	人员对象
培训人	`widget_1791509478935`	json	人员对象
基础资料	`widget_1791510696565`	array	数组，元素可能为字符串或对象
优惠券	`widget_1791510696561`	array	同上
对接结果	`widget_1792029306426`	string
对接备注	`widget_1791596350260`	string
渠道信息	`widget_1791509478941`	array	同上
已开通策略	`widget_1791964258708`	array	同上
未开通策略原因	`widget_1791964258722`	string
区域负责人手机号码	`widget_1791453695943`	string
流程状态（业务）	`widget_1791533061604`	string	见 4.2，业务展示以此为准
是否开通	`widget_1792072044675`	string	`"1"` 为已开通

辅助列：_jdy_id（简道云记录 ID）、_deleted、_raw（原始 JSON，仅供排障，不返回前端）、_created_at、_updated_at。

3.4 物理列名规则

数据库列名去掉了源字段的前导下划线：_widget_1791449342205 → widget_1791449342205。
_id 在表中对应 _jdy_id，id 列为同步工具写入的另一列，不得混用。
除 widget_1792048325259（double）、flowState（double）外，其余业务字段均为文本或 JSON 文本，需要在服务端解析。

3.5 JSON 与数组解析

人员对象：{"_id":"...","name":"戴丽沙","status":1,"type":0,"username":"..."}。展示取 name；status = -1 时加「离职」灰色标记，status = 0 时加「未加入」标记；空值、[]、null、"" 一律显示 —。
联系电话对象：{"phone":"13800000000","verified":false}。展示 phone；verified = true 时可加已验证图标，默认不强调。
数组字段：元素可能是字符串，也可能是 {"name":"..."}。统一提取 name，多个用「、」连接；空数组显示 —。
选择连锁 只取 id，用于和 连锁ID 交叉校验；两者不一致时进入异常区。
所有解析必须容错：JSON 解析失败时按原始字符串处理，不得让整行数据消失。

3.6 日期与时区

源数据为 UTC ISO 字符串，例如 2026-10-14T16:00:00.000Z。
展示与筛选统一按 Asia/Shanghai（UTC+8）换算。上述时间对应本地 2026-10-15，不是 2026-10-14。
日期列展示 MM月DD日（如 10月15日）；悬停或详情中展示 YYYY-MM-DD；时间戳展示 YYYY-MM-DD HH:mm。
「最新数据同步时间」取全表 MAX(updateTime)，换算为本地时间后展示。
周口径：周一为每周第一天；「本周」为本周一至今日，「上周」为上周一至上周日；「本月」为本月 1 日至今日，「上月」为上月 1 日至月末。
趋势图的「工作日」指周一至周五，跳过周六、周日，不引入法定节假日表。

3.7 数据质量与异常

以下情况必须进入「差异与异常数据」区，并在页面最下方以表格呈现，不得静默丢弃：

异常类型	判定规则	处理
缺销售	销售为空或无法解析	保留记录，销售显示「未分配」
缺客服	客服为空	保留记录，客服显示「未分配」
缺培训人	培训人为空	保留记录，培训人显示「未分配」
缺签约时间	签约时间为空或非法	不参与日期筛选与趋势，标记「缺签约时间」
门店数异常	为空、非数字或 ≤ 0	按 0 统计，标记「门店数异常」
连锁类型异常	不在四类白名单	归入「未分类」，保留原文
区域异常	不是南区/北区	归入「未分配」，保留原文
流程状态异常	不在八阶段白名单	保留原文，归入「其他」
重复连锁	连锁 ID 重复，或名称归一化后重复	保留全部记录，标记「疑似重复」，统计时按连锁 ID 去重
服务已到期	服务结束时间早于今天	标记「服务已到期」，仍计入历史签约
开通状态矛盾	`是否开通=1` 但无已开通策略，或反之	标记「开通状态待核」

3.8 人工数据修正

「吉林省一笑堂大药房连锁有限公司」的连锁类型修正为 50-。
修正以配置映射实现（CORRECTIONS），不直接改数据库；页面「差异与异常」区展示「人工修正」记录及原值。
后续新增修正只改配置，不改聚合代码。

3.9 规范化后的客户对象

接口返回前，每条记录统一为以下结构（字段缺失用空字符串或 0，不返回 null）：

{
  "chainId": "15504",
  "chainName": "贵州一树药业股份有限公司",
  "subject": "贵州一树药业股份有限公司",
  "region": "南区",
  "sales": "戴丽沙",
  "service": "游颖怡",
  "trainer": "郭祥",
  "stores": 1230,
  "chainType": "全国百强",
  "flowStatus": "系统对接",
  "signDate": "2026-10-25",
  "serviceStart": "2026-10-26",
  "serviceEnd": "2027-10-25",
  "opened": true,
  "province": "贵州省",
  "serviceStep": 0,
  "serviceStepLabel": "未分配",
  "contacts": {
    "business": { "name": "", "phone": "" },
    "technical": { "name": "", "phone": "" }
  },
  "remark": "",
  "noOpenReason": "",
  "updatedAt": "2026-10-15 21:55"
}

样例中的姓名、电话为结构示意，实际以数据库为准；文档不复制真实个人联系方式。

4. 业务字典与统计口径

4.1 区域

值	语义	主色语义
南区	南方大区	蓝
北区	北方大区	绿

规则：区域只允许这两个值；其他值归入「未分配」，在异常区列出。

4.2 流程状态与导航阶段

业务状态共 8 个，顺序固定，不得调换、不得增删：

签约 → 开通 → 系统对接 → 系统测试 → 渠道费充值 → 使用培训 → 落地执行 → 落地跟进 → 流程完成

其中「系统测试」与「渠道费充值」在导航图中合并为一个节点「客服处理」，其下再展开客服的 11 个处理步骤（见附录 A）。合并后的导航节点为 8 个：

签约 → 开通 → 系统对接 → 客服处理 → 使用培训 → 落地执行 → 落地跟进 → 流程完成

口径要求：

「客服处理」的客户数 = 系统测试 + 渠道费充值。
「进行中」= 流程状态不等于「流程完成」的客户数。
「流程完成」= 流程状态等于「流程完成」的客户数。
导航图每个节点显示该阶段客户数；点击节点弹出该阶段的客户明细。
各阶段客户数之和必须等于签约客户总数（含未分类需单列提示）。

4.3 连锁类型

值	标签色	文字色	语义
全国百强	红	白	全国性百强连锁
区县百强	橙	白	区县级百强连锁
50+	蓝	白	门店数 50 家以上
50-	灰	黑（深色模式为浅灰白）	门店数 50 家以下

规则：

四个标签的高度、圆角、内边距、字号、字重完全一致，仅背景色与文字色不同；宽度随文字自适应，但最小宽度一致。
标签不得出现空缺、错位、换行、被截断。
标签在卡片、排行榜、明细表、移动端列表中必须同色同形。
数量用加粗字体，标签名用常规字重（用于销售排行榜内的组合标签）。
「全国连锁」是「全国百强」的旧称，页面、接口、筛选、导出统一使用「全国百强」。

4.4 指标准确性口径

指标	定义	去重键
签约客户数	客户记录条数（有效、未删除）	连锁 ID；无 ID 时用归一化名称
签约门店数	所有客户门店数求和	—
南区/北区客户数	按区域分组的客户数	连锁 ID
南区/北区门店数	按区域分组的门店数之和	—
连锁类型客户数	按类型分组的客户数	连锁 ID
连锁类型门店数	按类型分组的门店数之和	—
流程状态客户数	按业务状态分组的客户数	连锁 ID
销售客户数	按销售分组的客户数	连锁 ID
销售门店数	按销售分组的门店数之和	—
销售类型分布	每位销售下四种连锁类型各多少家	连锁 ID
任务完成进度	已签约客户数 ÷ 任务目标	—
任务目标	总数 500、南区 220、北区 280	配置项

禁止事项：

禁止在多个卡片重复显示同一个「共 N 家」汇总文案。
禁止同一客户在多个销售下重复计数。
禁止用「当前页数据」代替「全量数据」计算汇总。
禁止把门店数当成客户数展示，或反之。

4.5 数字与单位

数值 ≥ 10000 时使用「万」，保留 1 位小数，例如 12345 → 1.2万、156789 → 15.7万、10001 → 1.0万。
10000 以下显示原始整数，不加千分位分隔符，例如 8678。
百分比保留 1 位小数，例如 12.2%。
客户/门店单位统一为「家」；数字与单位之间不加空格。
图表坐标轴可使用「万」缩写，但 tooltip 必须显示精确值。
用户明确要求原始数字时，以用户要求为准。

4.6 日期口径

筛选项	范围
全部	不限（默认）
今日	本地当天 00:00:00 – 23:59:59
昨日	本地昨天全天
本周	本周一 00:00 – 现在
上周	上周一 00:00 – 上周日 23:59:59
本月	本月 1 日 00:00 – 现在
上月	上月 1 日 – 上月最后一天
自定义	用户选择的开始日期 00:00 – 结束日期 23:59:59，含首尾两天

日期筛选一律作用于「签约时间」。

4.7 文案替换表

以下为历史版本中出现过、必须统一替换的文案。替换范围包括页面标题、表头、图例、tooltip、空态、导出文件名。

旧文案	新文案	说明
目标客户	当前合作客户	1.0 表头遗留
培育与落地中	培训与落地中	流程状态分组名
数据源 / MySQL 实时同步 / 数据表	删除，不出现	实现细节不外露
点击查看明细 / 点击阶段可筛选明细	删除	卡片本身可点，无需提示
共 N 家（在多个卡片重复）	仅保留一次	去重
手机版（页脚链接文字）	改为导航栏二维码按钮	不占页脚
备案信息（多条）	仅保留蜀ICP备19008580号	见 6.10

5. 全局设计规范

5.1 设计基调

关键词：克制、清晰、层次分明、极简直观、数据优先。
信息密度高但不拥挤：卡片之间留白统一，数据与标签对齐。
主色蓝 #1677FF；整体浅色调为默认。
全页配色严格控制在 5 种主色以内：亮橙、蓝、浅蓝、灰、白；功能色（红/绿）仅用于语义表达，不用于装饰。
禁止花哨渐变、荧光色、彩虹配色、无意义动效。

5.2 色彩令牌

令牌	浅色	深色	用途
`--brand`	`#1677FF`	`#3B8CFF`	主色、主按钮、链接、南区
`--brand-weak`	`#E8F1FF`	`#132844`	主色浅底
`--blue-soft`	`#7EB3FF`	`#5E9BEA`	浅蓝辅助、图表次级
`--green`	`#12B76A`	`#2ED47A`	北区、达成、正常
`--orange`	`#F79009`	`#FFA426`	区县百强、提醒
`--red`	`#E5484D`	`#FF5C61`	全国百强、异常、第一名
`--gray`	`#8A94A6`	`#9AA6B8`	50-、次要文字
`--ink`	`#101828`	`#EAF0F9`	主文字
`--ink-2`	`#475467`	`#A9B7CC`	次要文字
`--ink-3`	`#98A2B3`	`#6F7F96`	弱化文字、占位
`--line`	`#E4E9F2`	`#22304A`	分割线、边框
`--bg`	`#F4F7FC`	`#0B1220`	页面底色
`--panel`	`#FFFFFF`	`#131E33`	卡片底色
`--panel-2`	`#F8FAFD`	`#182642`	卡片内次级底色

配色硬性约束：

橙色与红色必须明显区分：橙偏黄（#F79009），红偏正红（#E5484D），不得使用同一色相的深浅色冒充两种颜色。
南区固定蓝、北区固定绿，全站不得互换。
排行榜名次色：第 1 红、第 2 橙、第 3 黄（#F5B400）、第 4–5 蓝、第 5 名以后黑（深色模式为浅灰）。
流程状态分布不使用花哨配色：统一主色蓝的深浅阶 + 完成态绿，禁止每个节点一种颜色。
页面主色相不超过蓝、绿、橙、红四类；黑白灰为中性色，不计入。

5.3 字体

中文："PingFang SC", "Microsoft YaHei", "Hiragino Sans GB", sans-serif。
数字与英文："DIN Alternate", "SF Pro Display", "Segoe UI", sans-serif，数字使用等宽数字特性 font-variant-numeric: tabular-nums。
字号阶：12 / 13 / 14 / 16 / 18 / 22 / 28 / 34 px；行高 1.4–1.6。
指标卡数值 28–34 px、字重 700；卡片标题 14 px、字重 600；辅助文字 12 px。
不使用艺术字、描边字、投影字。

5.4 空间与栅格

PC 内容最大宽度 1720 px，两侧最小留白 24 px。
栅格 12 列，列间距 16 px；卡片圆角 14 px，内边距 18–20 px。
卡片阴影只用一级：0 1px 2px rgba(16,24,40,.04), 0 4px 12px rgba(16,24,40,.05)；悬停可加深一级，不做位移动画。
分区之间垂直间距 16 px；标题与内容间距 12 px。
移动端左右安全边距 16 px，卡片圆角 12 px，底部操作栏固定高度 56 px + 安全区。

5.5 图标与插画

全站 LOGO 统一使用 https://wenjian.zhengl.vip/zkkj/logof.png，PC 导航栏与移动端标题栏同源，不得各用一张；加载失败时以文字「客户签约看板」兜底。
统一使用线性图标，线宽 1.5–1.75 px，尺寸 16/18/20 px。
同一语义只用一个图标；流程节点图标与移动端流程条图标必须一致。
不使用 emoji 作为功能图标。

5.6 语言与文案

全中文，专有名词保持业务原词（连锁、门店、客服、培训人、落地跟进）。
「培育与落地中」统一改为「培训与落地中」。
「目标客户」统一改为「当前合作客户」，表头、图例、tooltip、导出文案全部替换。
不出现「数据源」「MySQL」「实时同步」「数据表」「接口」等实现词汇。
不出现「点击查看明细」「点击阶段可筛选明细」这类提示语（卡片本身可点即可）。
不出现「共 N 家」在多个区块重复。
英文副标题统一为「最新数据同步时间」。

6. PC 端规范（智能体客户看板 2.0）

6.1 页面骨架

自上而下：

顶部导航栏（固定吸顶）。
第一排指标区：签约客户、门店总数、任务完成进度、进行中、流程完成（5 张卡）。
第二排流程区：横向流程导航图（8 个节点）。
第三排分析区：连锁类型分布（约 25%）、销售排行榜（约 25%）、签约趋势（约 50%）。
第四排明细区：搜索 + 表格 + 分页。
最底部：差异与异常数据（可折叠）+ 页脚（备案号）。
弹窗层：客户明细、销售完整榜单、字段设置、日期选择。

6.2 顶部导航栏

内容从左到右：

LOGO：https://wenjian.zhengl.vip/zkkj/logof.png，高度 32–36 px，等比缩放，不拉伸，加载失败时用文字「客户签约看板」兜底。
主标题「客户签约看板」，副标题「最新数据同步时间 · YYYY-MM-DD HH:mm」。
中部：筛选按钮组（日期、区域），按钮放在导航栏内，不占用导航栏下方空间。
右侧：连锁搜索框（仅作用于明细）、「字段设置」图标按钮、颜色切换按钮、手机版二维码按钮。

交互要求：

筛选按钮点击展开下拉面板，面板为浮层，不推挤页面。
已生效筛选在按钮上显示选中值，并提供单条清除。
颜色切换在浅色/深色之间切换，记住用户选择；首次访问跟随系统。
导航栏在滚动时保持吸顶，高度 60–64 px。

6.3 第一排：指标卡

五张卡等宽等高，内容顶部与底部对齐，不允许出现大面积空白。

卡 1 签约客户

中心为半圆进度环（或圆环）显示签约客户总数，环心为大号数字。
环左右分别标注北区客户数、南区客户数；北区绿、南区蓝。
下方一行小字：任务目标 500 家。
点击卡片弹出全部客户明细。

说明：源需求中「中间为汇总数，左右为北区数；南区用蓝色，北区绿色」与「半圆图」并存，本规范统一为「半圆环 + 中心总数 + 左北右南」。

卡 2 门店总数

主数字为门店总数（万单位规则见 4.5）。
下方两个并排小项：南区门店数（蓝）、北区门店数（绿）。
点击弹出客户明细并按门店数展示。

卡 3 任务完成进度

半圆进度图为主视觉，中心显示完成百分比。
下方显示「已签约 61 / 目标 500」。
再下方两条细进度条：南区 28/220、北区 33/280，颜色分别为蓝、绿。
不使用普通直线进度条作为主视觉。

卡 4 进行中

主数字为流程状态 ≠ 流程完成的客户数。
左侧四行明细，每行「状态名 + 数量」： - 策略处理中 = 流程状态为「开通」的客户数 - 实施处理中 = 流程状态为「系统对接」的客户数 - 客服处理中 = 流程状态为「系统测试」或「渠道费充值」的客户数 - 培训与落地中 = 流程状态为「使用培训」「落地执行」「落地跟进」的客户数
四行数值之和必须等于主数字；不相等说明有未分类状态，需在异常区提示。
每行可点击，弹出对应客户明细。

卡 5 流程完成

主数字为流程状态 = 流程完成的客户数。
下方显示占总签约数的百分比。
点击弹出客户明细。

统一要求：卡片右上角不显示「点击查看明细」等说明文字；整卡可点击并有 hover 反馈；卡片内部数字与标签基线对齐。

6.4 第二排：流程状态导航图

采用从左至右的一条导航图，8 个节点横向排列，节点之间用箭头连接。
节点结构：序号/图标 + 阶段名 + 客户数；当前筛选项下无客户的节点置灰但不隐藏。
箭头要「高一些、大气一些」：箭头高度不小于 28 px，使用实心三角或粗线箭头，与节点垂直居中，不得错位、不得压住文字。
节点使用统一主色阶：已完成阶段深蓝、进行中阶段中蓝、未开始阶段浅灰蓝；完成态可用绿色描边。
点击任一节点弹出该阶段客户明细；「客服处理」节点弹窗内再按 11 个客服步骤分组展示。
导航图整体高度不超过 120 px，避免占用首屏。
移动端使用同一套节点与图标，但改为两行排列（见 7.5）。

6.5 第三排左：连锁类型分布

四张等大小卡片，2×2 或 1×4 排列（视宽度），分别对应全国百强、区县百强、50+、50-。
每张卡片内容：类型标签、客户数（大号）、门店数（小号）、南区/北区拆分（小号，蓝/绿）。
四张卡片高度一致，内容顶部对齐、底部对齐，卡片下方不得出现大片空白。
标签颜色严格按 4.3；四个标签的长宽高一致。
卡片可点击，弹出该类型客户明细。
不再显示「共 N 家」之外的重复汇总文案。

6.6 第三排中：销售排行榜

默认显示前 5 名；卡片底部提供「展示全部」入口，点击弹出完整榜单弹窗。
首页不显示「按门店数 / 按客户数」切换按钮；该切换只在弹窗内出现。
排序规则：默认按客户数降序；客户数相同按门店数降序；再相同按姓名拼音升序。
每行结构：名次徽标（圆角矩形，数字水平垂直居中）+ 姓名 + 类型标签组 + 客户数/门店数。
名次徽标颜色按 5.2：1 红、2 橙、3 黄、4–5 蓝、5 以后黑。
姓名后不再重复「N 家客户」文字；客户数只在最右侧出现一次。
类型标签最多显示 3 个，出现第 4 个时隐藏「50-」；标签内「类型名 + 数量」，名称常规字重、数量加粗。
每行高度一致，标签不换行、不溢出。
弹窗榜单支持按客户数、按门店数切换，展示全部销售及其类型分布。

6.7 第三排右：签约趋势

展示最近 7 个工作日（跳过周六日）的签约趋势。
指标 1：签约客户数，堆叠柱形图，南区蓝、北区绿。
指标 2：签约门店数，曲线图，与柱形图共用 X 轴，使用独立 Y 轴或双轴标注。
图例可点击开关单个指标；关闭后图表自适应。
图表必须「好看」：柱宽适中、圆角 2–4 px、网格线仅横向浅色、坐标轴无边框、tooltip 显示日期与精确值。
空数据日期显示为 0，不跳过；不得出现折线断裂。
图表高度 220–260 px，与左侧两卡等高对齐。

6.8 第四排：明细表

标题栏

左侧标题「签约明细」。
右侧搜索框：按连锁名称模糊搜索，仅作用于明细表。
搜索框右侧为「每页条数」下拉框（20 / 50），不使用分段按钮。
不显示「数据源」字样。

列

默认显示：连锁 ID、连锁名称、连锁类型、门店数、销售、客服、培训人、当前状态、当前处理人、签约时间。

签约时间格式 MM月DD日，并作为默认排序字段（最新在前）。
连锁类型使用 4.3 标签。
当前状态使用流程状态文案。
当前处理人取该阶段责任人：签约/开通/系统对接=销售；系统测试/渠道费充值=客服；使用培训=培训人；落地执行/落地跟进=客服或培训人（取有值者）；流程完成显示「—」。
门店数右对齐，使用等宽数字。
其余字段默认隐藏，可在字段设置中开启：签约主体、区域、服务开始时间、服务结束时间、业务对接人、业务对接电话、技术对接人、技术对接电话、对接结果、对接备注、未开通策略原因、是否开通、已开通策略、渠道信息。

表头筛选

可筛选列仅限：连锁类型、销售、客服、培训人、当前状态、区域、签约时间。
其他列不出现筛选图标。
筛选作用于全量数据，不是当前页。
筛选后回到第 1 页，并显示已生效条件标签。
表头筛选与顶部导航筛选互不覆盖：顶部筛选是全局，表头筛选是明细局部；两者同时生效时取交集，并在明细标题旁提示「已应用 N 个明细筛选」。

排序

支持按列排序：连锁名称、门店数、签约时间、当前状态。
默认按签约时间降序。
排序作用于全量数据。

分页

默认每页 20 条，可切换 20 / 50。
页码切换只刷新表格区域，不整页刷新、不跳动滚动位置。
显示总条数与当前区间，例如「共 61 条 · 1–20」。
页码过多时使用省略号，当前页高亮。
表格内部不出现纵向滚动条；页面整体滚动。

行交互

点击行弹出客户详细信息。
客户详情包含：连锁名称、连锁 ID、签约主体、区域、连锁类型、门店数、销售、客服、培训人、当前状态、当前处理人、签约时间、服务起止、业务/技术对接人及电话、对接结果、对接备注、未开通原因、是否开通、已开通策略、渠道信息。
详情弹窗为右侧抽屉或居中弹窗，宽 560–720 px，内部可滚动，底部有关闭按钮。
明细点击必须能弹出详情；这是 1.0 的缺陷，必须修复并纳入验收。

6.9 差异与异常数据

位于页面最下方，默认折叠，标题显示异常总数与分级（高/中/低）。
表格列：连锁名称、异常类型、异常说明、原值、建议处理。
支持按异常类型筛选。
「人工修正」记录单独一组，标明修正前后值。

6.10 页脚

左侧显示「蜀ICP备19008580号」，链接到 https://beian.miit.gov.cn/，新窗口打开，rel="noopener noreferrer"。
右侧显示「最新数据同步时间：YYYY-MM-DD HH:mm」。
不显示数据源、不同步方式、不显示手机版链接文字（手机版入口在导航栏二维码按钮）。
不再显示其他备案信息。

6.11 弹窗与浮层

客户明细弹窗：标题为连锁名称，右上角关闭，内容分组展示。
销售完整榜单弹窗：顶部有「按客户数 / 按门店数」切换，列表可滚动，最大高度 70vh。
字段设置弹窗：需要口令才能打开（见 9.6）。
日期选择弹窗：见 9.2。
所有弹窗：遮罩 rgba(16,24,40,.45)，出现动画 160 ms 淡入 + 8 px 上移，关闭支持 ESC 与点击遮罩。
弹窗打开时锁定背景滚动；关闭后恢复原滚动位置。

7. 移动端规范

7.1 设计目标

单列信息流，自上而下阅读，不横向滚动。
首屏必须看到「签约客户」「签约门店数」两张卡与任务进度。
所有筛选集中到底部，不在顶部或导航栏下方放筛选条。
所有区块不折叠（连锁类型、流程状态、销售汇总均直接展开）。
页面只使用蓝、绿、橙、红与黑白灰；连锁类型标签严格按 4.3。

7.2 顶部标题栏

吸顶，高度 56 px + 状态栏安全区；背景与页面内容必须有明显区隔（使用 --panel 实底 + 底部 1px 分隔线 + 轻微阴影），不得与内容同色连成一片。
左侧 LOGO：高 28 px，左边距 16 px，垂直居中；不得贴边、不得偏上。
LOGO 右侧为标题「客户签约看板」，字号 16 px、字重 700；下方小字「最新数据同步时间 · MM-DD HH:mm」，字号 11 px。
右侧只保留一个「颜色切换」按钮（浅色/深色/跟随系统三态或两态切换），右边距 16 px，垂直居中。
不显示「电脑版」按钮、不显示连锁类型筛选按钮、不显示其他入口。
默认跟随手机系统的深色/浅色设置；用户手动切换后记住选择。
历史指令中的「LOGO 右移 20px、下移 15px、颜色按钮左移 20px」属于对早期版本贴边问题的临时修补，最终以实现「安全区 + 16px 内边距 + 垂直居中」为准，不再叠加固定像素偏移。

7.3 内容顺序

第一排：签约客户、签约门店数（2 张卡，等宽并排）。
任务完成进度（半圆进度图）。
流程状态分布（2 行 × 4 节点）。
连锁类型分布（4 张卡，2×2）。
区域概览（南区/北区客户数、门店数、各类型家数、各状态家数）。
销售排名（按客户数/按门店数切换）。
签约趋势（最近 7 个工作日）。
签约明细（列表 + 搜索 + 分页）。
页脚（最新数据同步时间）。
底部固定操作栏（4 个按钮）。

7.4 第一排卡片

签约客户卡

主数字为签约客户总数。
右侧或下方显示南区、北区客户数，蓝/绿。
不再显示「共 N 家」重复文案。

签约门店数卡

主数字为门店总数（万单位规则）。
下方显示南区、北区门店数，蓝/绿。

两张卡等高，数字与标签顶部/底部对齐，无大面积空白。

7.5 任务完成进度

使用半圆进度图，中心显示完成百分比，下方显示「已签约 61 / 目标 500」。
半圆轨道使用浅蓝，进度使用主蓝；完成态可用绿色。
下方并排两条细进度：南区 28/220、北区 33/280，颜色蓝/绿。
不使用直线进度条作为主视觉。

7.6 流程状态分布

采用与 PC 完全一致的 8 个导航节点、图标、色彩语义。
移动端改为 2 行显示，每行 4 个节点；节点之间用短箭头连接，箭头不得错位、不得指向空白。
每个节点显示图标、阶段名、客户数；客服处理节点显示合并数。
点击节点弹出该阶段客户列表；客服处理节点弹窗内按 11 个步骤分组。
不使用花哨配色，仅主蓝阶 + 完成态绿。
不再单独放「流程完成」卡片；流程完成数量在本区块的最后一个节点体现。

7.7 连锁类型分布

4 张卡 2×2 排列，内容：类型标签、客户数、门店数、南区/北区拆分。
标签颜色与 PC 一致：全国百强红、区县百强橙、50+ 蓝、50- 灰。
四张卡等高，内容顶底对齐。
点击卡片弹出该类型客户列表。

7.8 区域概览

不显示「区域数」「销售人数」这类汇总统计。
用两张卡分别呈现南区、北区：客户数、门店数、四种连锁类型各多少家、各流程状态多少家。
卡片内部使用紧凑的两列小表；数字右对齐。
点击任一类型或状态行，弹出对应客户列表。
南北区颜色固定蓝/绿。

7.9 销售排名

标题右侧提供「按客户数 / 按门店数」切换。
默认按客户数降序，客户数相同按门店数降序。
每位销售显示：名次、姓名、客户数、门店数、类型标签组。
类型标签：最多一行 3 个，出现第 4 个时隐藏「50-」；标签名常规字重、数量加粗。
名次徽标圆角矩形，数字水平垂直居中；颜色按 5.2。
姓名后不重复「N 家客户」。
展示全部销售，不折叠；列表较长时随页面滚动，不做内部滚动。
标签计数以当前筛选后的明细集合为准，不包含被筛掉的数据；分页不影响统计。

7.10 签约趋势

最近 7 个工作日，跳过周六日。
签约客户数为堆叠柱（南区蓝、北区绿），签约门店数为曲线。
图例可点击开关；移动端图表高度 180–200 px。
X 轴标签使用 MM-DD，数量过多时隔位显示。

7.11 签约明细

列表式，一行一条记录，不使用横向表格。
每行结构： - 第一行：连锁名称（主文字，最多两行省略）+ 连锁类型标签。 - 第二行：销售、客服、培训人（销售 · 客服 · 培训人，缺失显示 —）。 - 第三行：当前状态徽标 + 签约时间（MM月DD日）+ 门店数（N 家）。
默认按签约时间降序，最新在前；支持按门店数、连锁名称排序。
默认每页 20 条，可切换 20 / 50；分页在列表底部，页面整体滚动，列表内部不出现滚动条。
点击行进入客户详情页/抽屉，内容与 PC 详情一致。
明细标题右侧不放筛选；搜索框放在明细列表下方（列表之后），按连锁名称模糊搜索，输入即筛选，清除按钮恢复。
字段设置决定显示哪些字段；默认显示连锁 ID、连锁名称、连锁类型、门店数、销售、客服、培训人、当前状态、当前处理人、签约时间。
不显示「数据源」「同步方式」。

7.12 底部固定操作栏

四个按钮等宽，固定底部，含安全区内边距，背景实底 + 上边框 + 阴影：

顺序	按钮	行为
1	日期	打开日期快捷面板：全部、今日、昨日、本周、本月、上周、上月、自定义
2	筛选	打开筛选面板，项目顺序固定为：区域 → 连锁类型 → 流程状态 → 销售人 → 日期
3	字段	打开字段设置，勾选明细显示字段（需口令，与 PC 同一口令）
4	刷新	静默重新拉取数据；按钮图标旋转，禁止弹窗或 Toast「正在刷新」

要求：

不把区域、类型、状态、销售、日期拆成单独按钮放在页面上。
筛选面板为底部抽屉，支持「重置」「确定」，显示已选数量角标。
筛选生效后不在卡片下方添加「当前筛选结果」描述。
底部栏不得遮挡最后一条明细，列表底部预留 72 px + 安全区。

7.13 提示与反馈

Toast 为深色底白字，居中偏下，1.8 秒自动消失，不阻塞操作；修复「不会自动消失」的问题。
加载态使用骨架屏或局部 spinner，不遮罩整页。
刷新成功不弹窗，仅在同步时间更新时给出轻微高亮。
空状态：图标 + 一句说明 + 「清除筛选」按钮。
错误态：说明 + 「重试」按钮，保留上次成功数据并标注「数据可能不是最新」。

7.14 移动端适配

视口 320–430 px 均可用；360 px 为基准设计。
字号不小于 11 px；点击区域不小于 44×44 px。
不使用 hover 作为唯一反馈。
支持 iOS 安全区 env(safe-area-inset-*)。
横屏时内容居中，最大宽度 560 px。
不出现横向滚动条；长名称使用省略号并提供详情查看。

8. 南区专属看板规范

8.1 定位

仅 PC 端，仅统计南区客户。
继承 1.0 看板的全部指标卡、图表与筛选能力，并在其上增加省份与销售开发视图。
使用与 2.0 相同的数据接口、同一套聚合函数、同一套色彩与标签规范。
页面不出现「北区」相关指标；若数据中出现北区记录，直接过滤，不计入任何数字。

8.2 页面骨架

顶部导航栏：LOGO、标题「南区客户看板」、副标题同步时间、日期筛选、区域锁定为南区（不显示区域切换）、颜色切换。
第一排指标卡：沿用 1.0 指标卡布局，包含签约客户、门店总数、任务完成进度、进行中、流程完成；任务进度使用半圆图。
第二排：南区整体进度（半圆图）+ 连锁类型进度条（全国百强、区县百强、50+、50-）。
第三排：省份卡片区，每行 5 张。
第四排：销售开发进度卡片区，结构与省份卡片一致。
第五排：流程状态导航图 + 客服处理 11 步骤。
第六排：差异与异常数据（最下方，可折叠）。
页脚：备案号 + 最新同步时间。

不出现「南区 · 各省 × 连锁类型明细」这一区块及类似标题。

8.3 省份卡片

每行 5 张，等宽等高；窄屏按 4/3 列自适应，但不得少于 3 列。
卡片标题为省份名；标题栏右侧放该省销售标签（一个或多个），标签使用中性浅底，不使用连锁类型色。
卡片正文： - 「已签约 X 家」：该省签约客户数。 - 「已合作 X 家」：该省流程状态为「流程完成」的客户数。 - 「门店 X 家」：该省门店数。 - 四种连锁类型的小标签 + 数量。 - 一条细进度条：已合作 / 已签约。
不显示客服信息、不显示客服姓名。
卡片内容顶部与底部对齐，禁止下方大片空白。
点击卡片进入该省客户明细。
省份来源：优先取补充表中的省份字段；缺失时按连锁名称中的省市关键词推断；仍无法判断时归入「未分配省份」。

8.4 销售开发进度卡片

与省份卡片同结构、同尺寸、同排列（每行 5 张）。
标题为销售姓名；标题栏放其负责省份标签（多个用「、」或独立小标签）。
正文： - 「已签约 X 家」「已合作 X 家」「门店 X 家」。 - 四种连锁类型小标签 + 数量。 - 一条细进度条：已签约 / 负责省份目标（若配置了目标）；无目标时显示已签约数并隐藏百分比。
不显示客服信息。
点击卡片进入该销售客户明细。
排序默认按已签约客户数降序，相同按门店数降序。

8.5 整体进度与类型进度

南区整体任务完成进度使用半圆图：已签约 28 / 目标 220，中心显示 12.7%。
连锁类型使用横向进度条，四条并列或两列两行： - 全国百强、区县百强、50+、50-。 - 每条显示类型标签、客户数、门店数、占南区客户比例。 - 进度条颜色与类型标签一致。
进度条高度 6–8 px，圆角，轨道浅灰。

8.6 流程状态导航与客服步骤

采用与 1.0 一致的从左至右导航图，8 个节点。
「系统测试」与「渠道费充值」合并为「客服处理」。
导航图下方展开「客服处理 11 步」： - 11 个步骤横向或网格排列，每步显示序号、步骤名、客户数。 - 客户按 serviceStep 分配；未匹配的归入「未分配步骤」。 - 点击任一步骤弹出该步骤客户明细。
步骤 1–10 继承旧看板「系统测试」「渠道费充值」的跟进状态；步骤 11 为「已在 CRM 提交确认」。
导航图与 11 步区域合计高度不超过 260 px。

8.7 指标与图表继承

1.0 已有的指标卡、图表、筛选、明细能力全部保留，不得删减。
新增内容只能追加，不得替换 1.0 的核心指标。
1.0 与 2.0 的同名指标必须同口径、同格式、同颜色。
差异与异常数据固定放在页面最下方。

9. 全局交互规范

9.1 筛选体系

作用域

层级	入口	作用范围
全局筛选	PC 导航栏按钮 / 移动端底部「日期」「筛选」	所有卡片、图表、榜单、明细
明细筛选	PC 明细表头	仅明细表与其计数
明细搜索	PC 明细标题右侧 / 移动端明细下方	仅明细表

PC 全局筛选项

日期：全部（默认）、今日、昨日、本周、本月、上周、上月、自定义。
区域：全部、南区、北区。
连锁类型：全部、全国百强、区县百强、50+、50-。
销售：全部 + 销售名单（按拼音排序）。
流程状态：全部 + 8 个状态。

移动端筛选面板顺序

区域 → 连锁类型 → 流程状态 → 销售人 → 日期。该顺序为固定顺序，不得调整。

规则

多选还是单选：区域、连锁类型、流程状态、销售人均为多选（默认全选），日期为单选。
已选项以标签形式展示在按钮下方或面板顶部，可单个移除。
点击「重置」恢复默认（全部）。
筛选变化后所有区块同步更新，URL 记录筛选状态（可分享、可刷新保留）。
筛选后各卡片数字与明细条数必须一致。
明细表头筛选与全局筛选取交集；清除表头筛选不影响全局筛选。
筛选不得导致整页刷新、白屏或滚动位置跳回顶部（明细分页除外）。

9.2 日期选择器

PC 使用双月日历浮层，一次选择开始与结束日期：第一次点击为开始，第二次点击为结束；再次点击重新开始。
自定义区间输入框点击即弹出日历，不需要先点「自定义」再点输入框。
日历显示月份切换、星期表头、今天标记、选中区间高亮、起止端点圆角。
提供「今天」「本月」「清除」快捷操作与「确定」「取消」。
设计要大气：单元格 36–40 px，月份标题 15 px，留白充足，不使用拥挤小日历。
移动端使用底部抽屉日历，单月显示，支持左右滑动切月。
选择结束后立即生效，不需要二次确认（移动端可保留「确定」）。

9.3 排序

明细默认按签约时间降序。
可排序列：连锁名称、门店数、签约时间、当前状态。
点击表头切换升序/降序，显示箭头状态；第三次点击恢复默认。
排序对全量筛选结果生效，不只对当前页。

9.4 分页

默认每页 20 条；可选 20、50。
页码切换只更新表格 DOM，不刷新整页、不重新请求全量接口（可请求分页参数）。
显示「共 N 条 · 当前 1–20」。
页码超过 7 页时使用「1 … 4 5 6 … 20」形式。
切换每页条数后回到第 1 页。

9.5 刷新

PC 导航栏提供刷新按钮；移动端为底部第 4 个按钮。
点击后按钮图标旋转（至少 600 ms），静默请求，不弹「正在刷新」。
成功后更新「最新数据同步时间」，不整页重绘。
失败时保留旧数据并提示「刷新失败，请稍后重试」。
不自动轮询，避免无意义请求。

9.6 字段设置与口令

入口：PC 导航栏「字段设置」、移动端底部「字段」。
打开前要求输入口令；口令只存在服务端（password_hash），前端不包含明文、不包含哈希。
校验通过后服务端签发短期会话（30 分钟），期间再次打开不重复输入。
连续失败 5 次锁定 1 分钟；失败提示不透露正确性细节。
字段设置面板： - 分「默认显示」与「可选字段」两组，勾选即生效。 - 至少保留连锁名称与当前状态两列，不允许全部取消。 - 提供「恢复默认」。 - 设置保存在浏览器本地，换设备不继承。
移动端与 PC 使用同一口令，避免绕过。

9.7 颜色切换

支持浅色/深色；首次访问跟随系统 prefers-color-scheme。
手动切换后写入本地存储，优先级高于系统。
切换不闪烁：在 <head> 内联脚本中尽早设置 data-theme。
深色模式下所有文字对比度 ≥ 4.5:1，图表颜色同步适配。
打印时强制浅色。

9.8 二维码

PC 导航栏提供「手机版」按钮，点击弹出二维码，不直接跳转。
二维码内容为移动端完整 URL（含当前筛选参数可选，默认不带参数）。
弹窗内提供「复制链接」与「在新窗口打开」。
二维码使用本地生成库，不依赖外部图片接口。

9.9 客户详情

PC 为右侧抽屉（宽 640 px）或居中弹窗；移动端为全屏页。
顶部：连锁名称 + 类型标签 + 关闭按钮。
分组： - 基础信息：连锁 ID、签约主体、区域、门店数、省份。 - 签约信息：签约时间、服务开始、服务结束、销售。 - 交付信息：客服、培训人、当前状态、当前处理人、客服步骤。 - 对接信息：业务对接人/电话、技术对接人/电话、对接结果、对接备注。 - 策略信息：是否开通、已开通策略、未开通原因、渠道信息。
电话可点击拨号（移动端 tel:）。
底部显示该客户最近更新时间。

9.10 加载、空态与错误

首屏使用骨架屏，区块级 loading，不整页转圈。
空态文案：「当前筛选条件下没有客户」+「清除筛选」。
接口错误：显示错误码与重试，不显示 SQL、堆栈、服务器路径。
数据为空但接口成功：显示 0 与空态，不显示「—」代替全部数字。

10. 技术实现约束

10.1 技术栈

前端：原生 HTML + CSS + 原生 JS（ES2019+），不引入构建步骤，确保可直接部署到静态站点。
图表：本地化的轻量图表库（如 ECharts 定制包），不得引用公网 CDN。
后端：PHP 8.x（宝塔环境），PDO + 预处理语句，utf8mb4。
无框架依赖、无 Node 运行时依赖。
所有静态资源使用相对路径，站点可挂在任意子目录。

10.2 性能

首屏接口响应 < 800 ms（61 条数据规模）。
首屏可交互 < 2 s（本地网络）。
单页静态资源总大小 < 1.2 MB（含图表库）。
图片使用 SVG 或 WebP；LOGO 设置宽高避免布局抖动。
接口开启 gzip；静态资源设置缓存头（HTML 不缓存，JS/CSS 带版本号）。
不在前端重复请求同一接口；筛选在前端内存中计算，必要时才回源。

10.3 兼容性

Chrome / Edge 最近两个大版本。
Safari 15+（含 iOS）。
微信内置浏览器（iOS/Android）。
不支持 IE。

10.4 可访问性

所有按钮有可读文本或 aria-label。
弹窗有焦点陷阱与 ESC 关闭。
颜色不是唯一信息载体：状态同时有文字，类型同时有标签文字。
键盘可完成筛选、翻页、打开详情。

10.5 安全

所有 SQL 使用预处理；排序字段使用白名单映射。
输出到 HTML 的内容做转义，防止 XSS。
接口只读，拒绝非 GET 请求。
不返回 _raw、数据库结构、服务器路径。
口令使用 password_hash / password_verify，失败限流。
响应头设置 X-Content-Type-Options: nosniff、Referrer-Policy: strict-origin-when-cross-origin。
不记录含个人电话的日志。

11. 数据接口约定

11.1 端点

GET api.php?action=bootstrap 返回一次性引导数据：元信息、字典、全量客户（已规范化）、聚合结果。

可选参数：dateFrom、dateTo、region、chainType、sales、flowStatus（逗号分隔多值）。服务端过滤与前端过滤结果必须一致。

11.2 响应结构

{
  "meta": {
    "generatedAt": "2026-10-22 17:30",
    "lastSyncAt": "2026-10-22 16:37",
    "total": 61,
    "source": "primary"
  },
  "dict": {
    "regions": ["南区", "北区"],
    "chainTypes": ["全国百强", "区县百强", "50+", "50-"],
    "flowOrder": ["签约", "开通", "系统对接", "系统测试", "渠道费充值", "使用培训", "落地执行", "落地跟进", "流程完成"],
    "flowNav": ["签约", "开通", "系统对接", "客服处理", "使用培训", "落地执行", "落地跟进", "流程完成"],
    "serviceSteps": ["1 客户未确定时间", "…", "11 已在CRM提交确认"]
  },
  "kpi": {
    "signedTotal": 61,
    "stores": 8678,
    "south": { "customers": 28, "stores": 4895 },
    "north": { "customers": 33, "stores": 3783 },
    "progress": { "target": 500, "done": 61, "pct": 12.2, "southTarget": 220, "northTarget": 280 },
    "inProgress": 60,
    "completed": 1
  },
  "customers": [],
  "aggregates": {
    "byRegion": [],
    "byChainType": [],
    "byFlow": [],
    "bySales": [],
    "byProvince": [],
    "trend": []
  },
  "anomalies": []
}

11.3 契约要求

字段名固定，前端不猜测、不兼容多套命名。
空值统一为空字符串或 0，不返回 null。
数字字段为 number 类型，不返回字符串。
聚合结果由服务端计算，前端只做展示与二次筛选；同一口径不得前后端各算一遍。
接口版本写入 meta.version，结构变更时递增。

12. 版本、备份与部署

12.1 文件版本

所有交付文件使用版本后缀：pc_V1.html、pc_V2.html；线上入口通过复制为 pc.html 生效。
每次修改生成新文件，禁止覆盖历史版本。
HTML/CSS/JS 内不写版本对比说明；版本差异只写 CHANGELOG.md。
CHANGELOG.md 每次记录：版本号、日期、变更点、影响文件、验证结果。

12.2 本机留存（强制）

所有生成的文件必须在本机保留一份，路径：C:\Users\zhenglei\brainyaiclaw\project\20261022_客户看板提示词整理\。
每个版本在 backup\V1\、backup\V2\ 下完整留存，不得只留 diff。
本机与服务器文件保持一致；部署前先本机归档，再上传。
交付时在 README 中列出本机路径与服务器路径的对应关系。

12.3 项目文档

根目录 README.md：项目概况、目录结构、页面清单、数据口径、部署方式、账号口令的管理方式（不写明文）。
CHANGELOG.md：迭代历程。
docs/data-dictionary.md：字段字典与解析规则。
docs/design-tokens.md：颜色、字号、间距、组件规范。
目的是让后续接手的 AI 或开发者能快速理解背景、结构与历史变更。

12.4 部署

通过 baota-mcp 部署到云服务器。
站点目录：/www/wwwroot/zk1.zhengl.vip。
域名：zk1.zhengl.vip，绑定 80/443，申请并启用 SSL。
根入口 index.php 按设备分流；?v=pc / ?v=m 可强制。
部署后验证：首页 200、接口 200、PC/移动端自动分流、静态资源无 404、HTTPS 无混合内容。
部署前备份旧站点目录；部署失败可回滚。
不修改服务器上其他站点与面板配置。

12.5 环境配置

config.php 不入库、不公开、不被 Web 直接下载（放在站点根目录外或加访问限制）。
数据库口令、字段设置口令通过环境变量或配置文件注入。
提供 config.example.php，只含键名与说明。

12.6 通用项目规范（适用于所有交付）

以下规则来自项目级提示词，适用于本项目及后续所有衍生交付。

版本管理

所有文件采用版本后缀迭代：V1、V2，以此类推。
每次修改生成新文件，严禁覆盖旧版本。
版本差异写入 CHANGELOG.md，不在页面内容中书写版本对比（见 0.5）。

项目文档

项目根目录必须有 README.md 或 MANIFEST.md，记录项目概况与迭代历程。
目标是让后续接手的 AI 或开发者快速理解背景、结构与历史变更。

任务目录

每次新建空白对话开始新任务时，在对应项目文件夹下新建一个子目录，存放本次对话生成的文件与处理记录。
目录命名：YYYYMMDD_任务简称。
例外：用户明确约定其他位置时，优先按用户约定执行。

部署

部署属于需要用户确认的动作：用户确认终稿并给出上传指令后再执行。
使用 baota-mcp 部署到云服务器。
为项目分配访问域名或端口；本项目固定为 zk1.zhengl.vip。

页面布局（文档类页面）

左侧配置可折叠/收起的二级目录，支持点击跳转，提升阅读时的空间利用率。
完美适配移动端，PC 与手机端均应清晰一致。
主色调统一 #1677FF；层次分明、极简直观；全页配色不超过 5 种。

复杂任务

任务过复杂时拆分为多个步骤：完成上一步并校验成功后，再进入下一步。
某步失败时循环执行「修复 → 校验」，直至解决。
输入存在歧义或包含多个不明确意图时，先询问确认再处理。
单轮执行控制在 60 分钟内，避免超时失败；必要时拆分为多轮或后台任务。

数字显示

数值超过 10000 时使用「万」，保留 1 位小数。
用户明确要求原始数字或其他单位时，按用户约定执行。

13. 验收清单

13.1 数据一致性

签约客户数 = 明细总条数（去重后）。
南区 + 北区客户数 = 总客户数（无未分配时）。
四种连锁类型客户数之和 = 总客户数。
八个流程状态客户数之和 = 总客户数。
销售客户数之和 = 总客户数。
各卡片门店数之和 = 门店总数。
「进行中」+「流程完成」= 总客户数。
进行中卡片四行之和 = 进行中总数。
任务进度百分比 = 已签约 ÷ 500，保留 1 位小数。
同一客户在 PC、移动端、南区看板的字段完全一致。

13.2 PC 端

点击明细行能弹出客户详细信息。
点击明细页码不整页刷新，滚动位置保持。
明细表头筛选对全量数据生效，不只对当前页。
表头筛选只出现在指定 7 列。
筛选后上方卡片数字不变（明细筛选仅作用于明细）。
搜索框可按连锁名称过滤明细。
每页条数使用下拉框，切换后回到第 1 页。
连锁类型四个标签长宽高一致，50+ 有颜色和标签。
第一排五卡内容顶底对齐，无大片空白。
流程箭头高度足够、垂直居中、不压文字。
销售排行榜前 5 名，数字徽标居中，标签最多 3 个，姓名后不重复客户数。
销售排行榜「展示全部」打开完整榜单，切换按钮只在弹窗内。
趋势图跳过周末，双指标可开关，视觉整洁。
日期选择一次完成起止选择。
字段设置需要口令。
手机版按钮显示二维码，不直接跳转。
页脚显示备案号与最新同步时间，不显示数据源与手机版链接。
深浅色切换正常，刷新后保持。

13.3 移动端

顶部标题栏有独立背景，与内容有明确区隔。
LOGO 与颜色按钮不贴边、不偏上。
首屏两卡并排，数字完整。
任务进度为半圆图。
流程状态两行显示，箭头不错位，颜色与 PC 一致。
底部四个按钮：日期、筛选、字段、刷新。
筛选面板顺序为区域、连锁类型、流程状态、销售人、日期。
筛选生效后卡片下方无结果描述文字。
明细默认 20 条，可切 50，列表无内部滚动条。
明细按签约时间倒序，时间格式 MM月DD日。
搜索框位于明细下方且可用。
销售排名类型标签最多 3 个，计数随筛选变化。
刷新按钮旋转，无「正在刷新」弹窗。
Toast 1.8 秒自动消失。
底部栏不遮挡最后一条内容。
深色模式跟随系统，手动切换后记住。
无横向滚动，320 px 宽度可用。

13.4 南区看板

仅显示南区数据，无北区指标。
省份卡片每行 5 张，标题为省份，标题栏有销售标签。
省份卡片显示已签约、已合作、门店数、四类型数量，不显示客服。
省份卡片下方无大片空白。
销售开发卡片与省份卡片结构一致，负责省份以标签展示。
整体进度为半圆图，类型分布为进度条。
流程导航为 8 节点，客服处理展开 11 步并分配客户。
不出现「各省 × 连锁类型明细」区块。
差异与异常在页面最下方。
1.0 的指标与筛选能力全部保留。

13.5 部署

https://zk1.zhengl.vip 可访问，证书有效。
手机访问自动进入移动端，PC 自动进入 PC 端。
强制参数 ?v=pc / ?v=m 生效。
接口无报错，页面无控制台错误。
本机备份完整，版本目录齐全。

14. 历史指令裁决表

多轮修改中存在互相覆盖、表述冲突或前后不一致的地方。下表给出唯一执行结论；「来源轮次」对应《修订指令归档_V1.md》的 R1–R15，同一事项在多轮出现时列出主要来源；未列入的事项按「后轮覆盖前轮」处理。

编号	冲突或歧义	涉及轮次	最终裁决
C01	移动端 LOGO 与颜色按钮多次按像素微调（右移 20px、下移 15px、左移 20px）	R3、R4	不再叠加固定偏移；统一为左右 16px 安全边距 + 垂直居中
C02	移动端底部按钮有「日期/筛选/字段/刷新」与「明细/筛选/字段/刷新」两种版本	R8、R12	采用「日期、筛选、字段、刷新」四按钮，「明细」不作为按钮
C03	移动端筛选顺序出现「区域→连锁类型→流程状态→销售人→日期」与「日期→区域→销售人→流程状态→连锁类型」两种	R8、R14	采用「区域→连锁类型→流程状态→销售人→日期」
C04	移动端销售排行的类型标签计数，一说只统计当前已显示明细，一说分页不应影响统计	R14	筛选影响统计，分页不影响统计
C05	PC 销售排行榜默认条数有 10 与 5 两种	R13、R15	首页 5 条，完整榜单在弹窗内
C06	每页条数出现 10/20/50 与 20/50 两种	R9、R15	统一 20 / 50，默认 20
C07	任务完成进度先要求直线进度条，后要求半圆进度图	R10、R12、R13	采用半圆进度图
C08	签约客户卡形容为「中间汇总、左右北区数」，方位不明确	R15	半圆环 + 中心总数 + 左北区（绿）右南区（蓝）
C09	移动端是否需要「流程完成」卡片	R13	不需要独立卡片；数量在流程导航末节点体现
C10	是否统计区域数与销售人数	R14、R15	不统计这两个汇总；改用南/北区卡片呈现客户、门店、类型、状态
C11	底部备案信息：先要求取消，后要求显示蜀ICP备19008580号	R2、R12	只显示蜀ICP备19008580号及工信部链接，其他备案信息不显示
C12	页脚是否显示同步时间：前两轮说移到标题栏后底部不需要，后一轮又要求底部显示	R4、R8、R14	底部显示「最新数据同步时间」；标题栏同时保留副标题
C13	明细表头是否「每列都可筛选」与「仅 7 列可筛选」	R4、R15	仅连锁类型、销售、客服、培训人、当前状态、区域、签约时间 7 列可筛选
C14	签约趋势是「最近 7 日」还是「最近 7 个工作日」	R13、R15	最近 7 个工作日，跳过周六日
C15	手机版搜索框位置：明细标题右方 / 明细下方	R3、R14	移动端放明细下方；PC 放明细标题右方
C16	南区省份卡片「上方标注销售」与「销售作为标签放标题栏」	R5、R6	销售以标签形式放卡片标题栏右侧
C17	「总进去采用半圆图表」表述不清	R5	理解为南区整体任务进度采用半圆图
C18	「南北区的配送、连锁类型的配送」	R12	「配送」为「配色」误写；执行时按配色全局一致处理
C19	主数据表 `jdy_data_11` 与线上 `jdy_data_20` 不一致	源需求	默认 `jdy_data_20`，表名配置化；见第 15 章待确认项
C20	页面数量：一说 2 个页面（手机/PC），实际还有南区看板	源需求、R6	设备分流 2 个入口 + 南区专属 1 个页面，共 3 个业务页面
C21	「培育与落地中」与「培训与落地中」	R9	统一为「培训与落地中」
C22	销售排行榜第 5 名颜色：4–5 名蓝色与 5 名以后黑色重叠	R11	第 4–5 名蓝，第 6 名起黑
C23	连锁类型 50- 的文字色：灰底白字 / 灰底黑字	R11、R14	灰底黑字（深色模式用浅灰底 + 深色字，保证对比度）
C24	首页是否显示「按门店数/按客户数」切换	R13	首页不显示，仅完整榜单弹窗内显示
C25	手机端是否保留顶部连锁类型筛选按钮	R14	不保留，全部筛选集中到底部
C26	卡片下方是否显示「当前筛选结果」描述	R14	不显示
C27	「不要再每个标签上方都重复显示 43 家」	R14、R15	任一区块只出现一次汇总数，标签上方不重复计数
C28	明细是否允许内部滚动条	R9	不允许；页面整体滚动
C29	字段设置是否需要密码	R4	需要；PC 与移动端同一口令
C30	手机版按钮显示二维码还是直接跳转	R15	显示二维码，不直接跳转
C31	客服处理是否包含「系统测试 + 渠道费充值」	R5	是；合并为一个导航节点，下展 11 步
C32	南区看板是否保留 1.0 全部功能	R5、R6	全部保留，只做增量，不替换
C33	「点击每个列表头都能筛选」是否包含非业务列	R15	仅业务列，且限定 7 列
C34	移动端首屏卡片数量	R13	2 张：签约客户、签约门店数
C35	通用规则要求「文件内容中标注版本修改记录」，而新增要求禁止在方案中做版本对比	源需求、本次要求	页面、HTML、CSS/JS、接口中一律不做版本对比；版本差异只写入 README / CHANGELOG
C36	通用规则要求把页面布局要求写清楚，而新增要求禁止把系统提示词内容写进产出物	源需求、本次要求	布局规范只作为生成依据；页面正文、注释、接口、控制台不得出现本提示词内容或布局说明
C37	「任务完成进度的主数据使用进度图」表述不清	R13	理解为任务完成进度以进度图（半圆图）为主视觉，数字为辅

15. 待业务确认事项

以下事项无法从历史指令中唯一确定。实现时先按「默认方案」执行，并在交付说明中标注；收到确认后只改配置或局部逻辑。

编号	事项	默认方案	影响
Q01	生产主表用 `jdy_data_20`（61 条）还是 `jdy_data_11`（9 条）	`jdy_data_20`，与 1.0 连续	全站数字
Q02	任务目标 500/220/280 的适用年度与是否可配置	作为配置项，默认 2026 年度	进度百分比
Q03	省份字段来源：补充表、名称推断还是人工维护	补充表优先 → 名称推断 → 未分配	南区省份卡片
Q04	客服 11 步与「系统测试/渠道费充值」的精确对应关系	1–10 步继承旧看板跟进状态，11 步为 CRM 确认	客服处理区块
Q05	「已合作」是否等同于「流程完成」	等同	南区卡片
Q06	字段设置口令由谁设定、是否按人分发	单一运维口令，`password_hash` 存储	字段设置
Q07	数据刷新频率与是否允许直连生产库	手动刷新 + 页面加载拉取，只读账号	性能与安全
Q08	是否需要导出 Excel/PDF	暂不做	范围
Q09	1.0 旧入口是否继续保留、是否加版本切换	保留 1.0，不加入口	版本管理
Q10	移动端是否需要离线缓存	不做	范围

附录 A　客服处理 11 步

步骤	文案	归属
1	客户未确定时间	客服处理
2	已预约，时间未到	客服处理
3	已培训，策略开启跟进中	客服处理
4	已短信报备/资料提供中	客服处理
5	已培训，策略未开启	客服处理
6	待进一步解决方案	客服处理
7	待价值报告	客服处理
8	待资料补充	客服处理
9	销售反馈晚点推进	客服处理
10	以上已跟进完	客服处理
11	已在 CRM 提交确认	客服处理

规则：

步骤 1–10 继承旧看板「系统测试」「渠道费充值」两个状态的跟进结果。
步骤 11 表示客服侧处理完毕，进入使用培训前的确认节点。
未识别的步骤值归入「未分配步骤」，在异常区列出。
步骤名称中的数字与文案之间保留一个空格，例如「1 客户未确定时间」。

附录 B　术语表

术语	含义
连锁	一个签约客户实体，以连锁 ID 唯一标识
门店	连锁下属门店，门店数为整数
签约客户数	有效客户记录数，按连锁 ID 去重
已合作	流程状态为「流程完成」的客户
南区 / 北区	业务大区，固定蓝/绿
全国百强 / 区县百强 / 50+ / 50-	连锁类型，固定红/橙/蓝/灰
流程状态	8 个业务阶段，见 4.2
导航阶段	8 个展示节点，含合并后的「客服处理」
客服步骤	客服处理节点下的 11 个跟进步骤
进行中	流程状态 ≠ 流程完成
当前处理人	当前阶段的责任人，见 6.8
最新数据同步时间	全表 `MAX(updateTime)` 的本地时间
本机备份	`C:\Users\zhenglei\brainyaiclaw\project\20261022_客户看板提示词整理\` 下的完整副本

附录 C　修订指令归档

同目录文件《客户签约看板_修订指令归档_V1.md》按轮次完整记录了用户原始指令，用于溯源与复核。

使用规则：

该归档不作为并行需求重复执行。
归档与本文件冲突时，以本文件第 14 章裁决为准。
新增需求先更新本文件与归档，再实施。

附录 D　交付物清单

交付物	路径	说明
标准提示词	`客户签约看板_标准提示词_V1.md`	本文件，唯一执行口径
修订指令归档	`客户签约看板_修订指令归档_V1.md`	原始指令溯源
项目说明	`README.md`	目录、口径、部署、备份
变更记录	`CHANGELOG.md`	版本历史
本机备份	`backup\V1\`	全量文件副本
在线文档	`https://zk1.zhengl.vip`	可查阅版本

附录 E　执行顺序建议

读取本文件第 3–5 章，建立数据字典与设计令牌。
实现 api.php，用 61 条真实数据验证字段解析、时区、去重、异常规则。
实现 assets/js/aggregate.js，用第 13.1 节的 10 条等式做单元自检。
实现 PC 2.0，按「指标卡 → 流程导航 → 三卡 → 明细 → 异常」顺序，每完成一块自检。
实现移动端，复用同一数据层，按第 7 章顺序重排。
实现南区看板，复用聚合函数，仅做区域过滤与省份维度。
按第 13 章逐项验收，记录未通过项并修复。
本机归档 → 上传服务器 → 绑定域名 → 启用 SSL → 线上复验。

文档结束