Neo
6f8f12314f
包含多个会话的累积代码变更： - backend: AI 聊天服务、触发器调度、认证增强、WebSocket、调度器最小间隔 - admin-web: ETL 状态页、任务管理、调度配置、登录优化 - miniprogram: 看板页面、聊天集成、UI 组件、导航更新 - etl: DWS 新任务（finance_area_daily/board_cache）、连接器增强 - tenant-admin: 项目初始化 - db: 19 个迁移脚本（etl_feiqiu 11 + zqyy_app 8） - packages/shared: 枚举和工具函数更新 - tools: 数据库工具、报表生成、健康检查 - docs: PRD/架构/部署/合约文档更新 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
289 lines
26 KiB
Markdown
289 lines
26 KiB
Markdown
# Spec 审查报告：Neo_Specs 遗漏需求细节
|
||
|
||
> 审查日期：2026-03-20
|
||
> 审查方法：以 `docs/prd/specs/` 中 P5.1、P6-P10 为标杆，逐项对照 `docs/prd/Neo_Specs/` 中 NS1/NS3/NS4/RNS1，识别 Neo_Specs 中遗漏的需求细节
|
||
> 审查范围：6 个标杆文件 × 对应 Neo_Specs 文件
|
||
> 规则：NS1/RNS1 中新增的需求（标杆文件没有的）不算遗漏，仅关注标杆文件中有但 Neo_Specs 中缺失的内容
|
||
|
||
---
|
||
|
||
## 一、总览汇总
|
||
|
||
| 标杆文件 | 对照文件 | 缺失项总数 | 🔴 高 | 🟠 中 | 🟡 低 |
|
||
|---------|---------|:----------:|:-----:|:-----:|:-----:|
|
||
| P5.1（MCP Server AI 扩展） | NS3 | 10 | 2 | 5 | 3 |
|
||
| P6（小程序前端-任务模块） | NS1 + RNS1 | 18 | 6 | 8 | 4 |
|
||
| P7（小程序前端-绩效模块） | NS1 + RNS1 | 12 | 3 | 5 | 4 |
|
||
| P8（小程序前端-看板模块） | NS1 + RNS1 | 14 | 4 | 5 | 5 |
|
||
| P9（小程序前端-详情模块） | NS1 + RNS1 | 23 | 4 | 10 | 9 |
|
||
| P10（租户管理后台） | NS4 | 9 | 0 | 4 | 5 |
|
||
| **合计** | | **86** | **19** | **37** | **30** |
|
||
|
||
---
|
||
|
||
## 二、高风险缺失项汇总（🔴 高，共 19 项）
|
||
|
||
以下缺失项可能导致功能不完整、联调失败或数据错误，建议优先补充。
|
||
|
||
### P5.1 → NS3（2 项）
|
||
|
||
| # | 缺失内容 | 影响 |
|
||
|---|---------|------|
|
||
| 1 | App1（智能任务生成）的完整 Prompt 工程规范：P5.1 定义了 system prompt 模板、few-shot 示例、输出 JSON schema 约束，NS3 仅提及"调用 LLM 生成任务"无 prompt 细节 | 生成质量不可控，无法验收 |
|
||
| 2 | App2（财务洞察）的指标计算口径：P5.1 明确了 6 个财务指标的计算公式（含 items_sum 口径、环比基准），NS3 仅列出"生成财务分析报告" | 财务数据可能计算错误 |
|
||
|
||
### P6 → NS1/RNS1（6 项）
|
||
|
||
| # | 缺失内容 | 影响 |
|
||
|---|---------|------|
|
||
| 1 | 任务卡片的视觉状态机：P6 定义了 5 种卡片状态（待处理/已置顶/已完成/已放弃/过期）的颜色、图标、交互差异，NS1/RNS1 仅按 status 分组返回数据 | 前端无法正确渲染状态差异 |
|
||
| 2 | 任务列表的空状态设计：P6 定义了 3 种空状态（无任务/筛选无结果/网络错误）的文案和插图，NS1/RNS1 未提及 | 空状态体验缺失 |
|
||
| 3 | 置顶任务的排序规则：P6 明确"置顶任务按置顶时间倒序，非置顶按优先级→创建时间排序"，NS1 TASK-1 未定义排序规则 | 列表排序可能不符合预期 |
|
||
| 4 | 任务操作的确认弹窗规范：P6 定义了放弃/取消放弃操作的二次确认弹窗文案和按钮样式，NS1/RNS1 未提及前端交互细节 | 误操作风险 |
|
||
| 5 | 下拉刷新与触底加载的动画规范：P6 定义了 loading 动画、skeleton 屏、错误重试的交互细节，NS1/RNS1 仅提及"分页"和"懒加载" | 加载体验不一致 |
|
||
| 6 | 任务详情页的 AI 分析展示规范：P6 定义了 AI 分析卡片的折叠/展开交互、"重新生成"按钮、加载状态，NS1 TASK-2 仅定义了 aiAnalysis 数据字段 | AI 功能交互不完整 |
|
||
|
||
### P7 → NS1/RNS1（3 项）
|
||
|
||
| # | 缺失内容 | 影响 |
|
||
|---|---------|------|
|
||
| 1 | 营业日分割点（08:00）的完整处理规范：P7 多次强调"营业日以 08:00 为分割点"并给出具体示例（"本月"= 当月1日 08:00 ~ 次月1日 08:00），NS1/RNS1 的 PERF-1/PERF-2 使用 `biz_date` 查询但未说明 biz_date 是否已按 08:00 分割 | 跨日数据归属可能错误（如凌晨 2 点的服务归属哪天） |
|
||
| 2 | "预估"标记的完整规范：P7 AC7 和 T7 明确要求"当月数据显示预估标记"，NS1 PERF-1 提到 `isEstimate` 字段但未定义判断逻辑（什么条件下标记为预估？当月所有数据都是预估？还是仅未结算的？） | 预估标记逻辑不明确 |
|
||
| 3 | 定档折算惩罚的展示格式：P7 AC6 明确要求"120分钟（定档折算30分钟）"格式，NS1 PERF-2 提到 `hoursRaw`（折算前）和 `hours`（折算后）但未定义前端展示格式 | 折算信息展示不一致 |
|
||
|
||
### P8 → NS1/RNS1（4 项）
|
||
|
||
| # | 缺失内容 | 影响 |
|
||
|---|---------|------|
|
||
| 1 | 看板页面的 Tab 切换交互：P8 定义了助教/客户/财务三个 Tab 的切换动画、缓存策略（切换回来保持筛选状态），NS1/RNS1 仅定义了 API 参数 | Tab 切换体验不完整 |
|
||
| 2 | 财务看板的数据加载策略：P8 定义了"首次加载经营一览，其他板块懒加载"的分段加载策略，NS1 BOARD-3 是单个 API 返回全部 6 板块数据 | 首屏加载慢（200+ 字段一次返回） |
|
||
| 3 | 客户看板卡片的点击跳转：P8 定义了"点击客户卡片跳转到 customer-detail 页面"的交互，NS1/RNS1 BOARD-2 未定义卡片点击行为和跳转参数 | 看板→详情的导航链路断裂 |
|
||
| 4 | 助教看板的"距升档"进度条：P8 定义了升档进度的可视化展示（进度条 + 百分比 + 差距小时数），NS1 BOARD-1 仅返回 `perfGap` 文本字段 | 进度可视化缺失 |
|
||
|
||
### P9 → NS1/RNS1（4 项）
|
||
|
||
| # | 缺失内容 | 影响 |
|
||
|---|---------|------|
|
||
| 1 | 客户详情页的数据加载顺序：P9 定义了"基本信息→消费汇总→AI 洞察→消费记录→备注"的分段加载策略和 skeleton 占位，NS1 CUST-1 是单个 API 返回全部数据 | 首屏加载慢 |
|
||
| 2 | 助教详情页的档位进度可视化：P9 定义了档位节点（tierNodes）的时间轴样式、当前档位高亮、升档动画，NS1 COACH-1 仅返回 tierNodes 数据 | 档位展示缺乏视觉引导 |
|
||
| 3 | 消费记录的类型图标映射：P9 定义了台桌消费/商城消费/充值 3 种类型的图标、颜色、标签样式，NS1 CUST-1 仅返回 `type` 字段 | 消费类型视觉区分不明确 |
|
||
| 4 | 备注的 AI 评分展示：P9 定义了备注卡片上 AI 评分的星级展示（1-5 星）和评分说明 tooltip，NS1 仅返回 `ai_score` 数值 | 评分展示不直观 |
|
||
|
||
---
|
||
|
||
## 三、各标杆文件详细对比
|
||
|
||
### 3.1 P5.1（MCP Server AI 扩展）vs NS3
|
||
|
||
P5.1 定义了 MCP Server 的 7 个 AI 应用（App1-App7）的完整规范，NS3 覆盖了整体架构但在以下细节上有遗漏。
|
||
|
||
|
||
| # | 风险 | 缺失内容 | P5.1 位置 | NS3 现状 | 补充建议 |
|
||
|---|:----:|---------|----------|---------|---------|
|
||
| 1 | 🔴 | App1 Prompt 工程规范（system prompt 模板、few-shot 示例、输出 JSON schema） | §App1 详细设计 | 仅提及"调用 LLM" | 补充完整 prompt 模板和输出约束 |
|
||
| 2 | 🔴 | App2 财务指标计算口径（6 个指标公式、items_sum 口径、环比基准） | §App2 详细设计 | 仅列出"生成财务分析" | 补充指标公式，引用 DWD-DOC 口径规范 |
|
||
| 3 | 🟠 | App3 维客线索生成的触发条件和频率（每日/每周/事件驱动） | §App3 调度策略 | 未定义触发机制 | 补充调度策略和去重逻辑 |
|
||
| 4 | 🟠 | App4-App7 的缓存策略（cache_type 枚举、过期时间、失效条件） | §缓存设计 | 提及 ai_cache 表但未定义策略 | 补充各 App 的缓存 TTL 和失效触发条件 |
|
||
| 5 | 🟠 | LLM 调用的错误处理和降级策略（超时/限流/模型不可用时的回退） | §异常处理 | 未提及 | 补充降级策略（如返回缓存结果或提示用户） |
|
||
| 6 | 🟠 | Token 用量监控和成本控制（单次调用上限、日/月预算、超限处理） | §成本控制 | 未提及 | 补充 token 预算和告警机制 |
|
||
| 7 | 🟠 | App5（话术生成）的话术模板分类和质量评估标准 | §App5 详细设计 | 仅提及"生成话术" | 补充话术分类（召回/维护/推荐）和评估维度 |
|
||
| 8 | 🟡 | 各 App 的单元测试用例设计（输入/输出示例、边界条件） | §测试策略 | 未提及 | 补充关键 App 的测试用例 |
|
||
| 9 | 🟡 | MCP Server 的健康检查端点和监控指标 | §运维 | 未提及 | 补充 /health 端点和关键指标（延迟/成功率/token 用量） |
|
||
| 10 | 🟡 | AI 生成内容的审计日志（谁在什么时候对哪个客户生成了什么） | §审计 | 未提及 | 补充审计日志表或字段 |
|
||
|
||
---
|
||
|
||
### 3.2 P6（小程序前端-任务模块）vs NS1/RNS1
|
||
|
||
P6 定义了任务列表和任务详情两个页面的完整前端规范，NS1/RNS1 主要关注后端 API 设计，以下前端交互细节有遗漏。
|
||
|
||
| # | 风险 | 缺失内容 | P6 位置 | NS1/RNS1 现状 | 补充建议 |
|
||
|---|:----:|---------|--------|--------------|---------|
|
||
| 1 | 🔴 | 任务卡片 5 种状态的视觉规范（颜色/图标/交互差异） | §任务卡片设计 | 仅按 status 分组返回 | 在契约或前端 spec 中补充状态→样式映射表 |
|
||
| 2 | 🔴 | 3 种空状态设计（无任务/筛选无结果/网络错误）的文案和插图 | §空状态 | 未提及 | 补充空状态 UI 规范 |
|
||
| 3 | 🔴 | 置顶任务排序规则（置顶按时间倒序，非置顶按优先级→创建时间） | §排序逻辑 | TASK-1 未定义排序 | 在 API 契约中明确 ORDER BY 规则 |
|
||
| 4 | 🔴 | 放弃/取消放弃的二次确认弹窗文案和按钮样式 | §操作确认 | 未提及交互细节 | 补充确认弹窗规范 |
|
||
| 5 | 🔴 | 下拉刷新/触底加载的动画规范（loading/skeleton/错误重试） | §加载状态 | 仅提及"分页""懒加载" | 补充加载状态 UI 规范 |
|
||
| 6 | 🔴 | AI 分析卡片的折叠/展开交互、"重新生成"按钮、加载状态 | §AI 分析展示 | TASK-2 仅定义数据字段 | 补充 AI 卡片交互规范 |
|
||
| 7 | 🟠 | 任务优先级的视觉标识（高/中/低优先级的颜色和图标） | §优先级展示 | 未提及优先级视觉 | 补充优先级→样式映射 |
|
||
| 8 | 🟠 | 任务到期倒计时的展示规则（距到期 N 天的颜色变化） | §到期提醒 | 未提及 | 补充倒计时展示规则 |
|
||
| 9 | 🟠 | 备注输入框的字数限制和实时计数 | §备注交互 | createNote 仅定义参数 | 补充输入限制（如 500 字） |
|
||
| 10 | 🟠 | 任务详情页各模块的折叠/展开默认状态 | §详情布局 | 未提及 | 补充各模块默认展开/折叠状态 |
|
||
| 11 | 🟠 | 维客线索的展示样式（tag 颜色映射、线索卡片布局） | §维客线索 | 定义了 tag 格式但未定义样式 | 补充 tag 颜色和卡片样式 |
|
||
| 12 | 🟠 | 任务列表页的搜索功能（按客户名/手机号搜索） | §搜索 | 未提及搜索功能 | 确认是否需要搜索，如需则补充 |
|
||
| 13 | 🟠 | 任务完成后的成功反馈动画 | §操作反馈 | 未提及 | 补充成功/失败的 toast 规范 |
|
||
| 14 | 🟠 | 网络异常时的离线提示和重试机制 | §异常处理 | 未提及 | 补充网络异常 UI 和重试策略 |
|
||
| 15 | 🟡 | 任务卡片的长按/滑动操作（如滑动删除、长按置顶） | §手势交互 | 未提及 | 确认是否需要手势操作 |
|
||
| 16 | 🟡 | 页面切换时的转场动画规范 | §转场 | 未提及 | 补充页面转场动画类型 |
|
||
| 17 | 🟡 | 任务列表的批量操作（如批量标记完成） | §批量操作 | 未提及 | 确认是否需要批量操作 |
|
||
| 18 | 🟡 | 无障碍适配（屏幕阅读器标签、焦点顺序） | §无障碍 | 未提及 | 补充关键元素的 aria 标签 |
|
||
|
||
---
|
||
|
||
### 3.3 P7（小程序前端-绩效模块）vs NS1/RNS1
|
||
|
||
P7 定义了绩效概览和绩效明细两个页面的完整规范，NS1 §3.3 和 RNS1 T1-3/T1-4 覆盖了 API 设计，但以下细节有遗漏。
|
||
|
||
| # | 风险 | 缺失内容 | P7 位置 | NS1/RNS1 现状 | 补充建议 |
|
||
|---|:----:|---------|--------|--------------|---------|
|
||
| 1 | 🔴 | 营业日 08:00 分割点的完整处理规范 | AC2、页面清单多处 | PERF-1/PERF-2 用 `biz_date` 查询但未说明 biz_date 是否已按 08:00 分割 | 在 API 契约中明确：biz_date 已由 ETL 层按 08:00 分割，后端直接按 biz_date 查询即可；或补充后端时间转换逻辑 |
|
||
| 2 | 🔴 | "预估"标记的判断逻辑 | AC7、T7 | PERF-1 有 `isEstimate` 字段但未定义判断条件 | 补充：当月所有数据标记为预估？还是仅未结算的？还是基于 ETL 数据更新时间？ |
|
||
| 3 | 🔴 | 定档折算惩罚的展示格式规范 | AC6 | PERF-2 返回 `hours`/`hoursRaw` 但未定义展示格式 | 补充：前端展示为"120分钟（定档折算30分钟）"格式，明确 hours 和 hoursRaw 的关系 |
|
||
| 4 | 🟠 | "我的新客"筛选逻辑的完整定义 | AC3 | NS1 §3.3 提及 `dws_assistant_customer_stats` 但未定义"首次服务 + 2月内 + 服务次数≤2"的 SQL 条件 | 补充新客筛选的 WHERE 条件 |
|
||
| 5 | 🟠 | "我的常客"的展示字段（次数、小时数、工资合计） | AC4 | NS1 §3.3 提及数据源但未定义响应字段 | 补充常客列表的响应 schema |
|
||
| 6 | 🟠 | 收入与业绩档位卡片的视觉设计 | §performance 页面 | RNS1 T1-3 定义了数据字段但未定义卡片布局 | 补充卡片 UI 规范（进度条、档位标签、收入数字样式） |
|
||
| 7 | 🟠 | 服务记录按天归总的展示格式 | §performance 页面 | RNS1 PERF-1 定义了 DateGroup 结构但未定义日期标签格式 | 补充：日期标签格式（如"3月15日 周五"）、每日汇总行样式 |
|
||
| 8 | 🟠 | 本月/上月切换的交互细节 | AC2 | RNS1 T1-6 提到 F8（月份切换）但未定义切换动画和数据刷新策略 | 补充切换交互规范 |
|
||
| 9 | 🟡 | 绩效页面的空状态（新助教无数据时的展示） | 隐含 | 未提及 | 补充空状态文案 |
|
||
| 10 | 🟡 | 业绩明细的导出功能（如导出 Excel） | 隐含 | 未提及 | 确认是否需要导出功能 |
|
||
| 11 | 🟡 | 绩效数据的刷新频率说明（实时/每日/每次 ETL 后） | 隐含 | 未提及 | 补充数据新鲜度说明 |
|
||
| 12 | 🟡 | 业绩明细页的口径选择交互（本月/上月/本周/上周等） | §performance-records | RNS1 L3 定义了月份切换但 P7 还提到"本周/上周"口径，NS1/RNS1 未覆盖周口径 | 确认是否需要周口径，如需则补充 API 参数 |
|
||
|
||
---
|
||
|
||
### 3.4 P8（小程序前端-看板模块）vs NS1/RNS1
|
||
|
||
P8 定义了三个看板页面（助教/客户/财务）的完整前端规范，NS1 八¾节和 RNS1 RNS1.3 覆盖了 API 和筛选矩阵，但以下前端细节有遗漏。
|
||
|
||
| # | 风险 | 缺失内容 | P8 位置 | NS1/RNS1 现状 | 补充建议 |
|
||
|---|:----:|---------|--------|--------------|---------|
|
||
| 1 | 🔴 | 三看板 Tab 切换的缓存策略（切换回来保持筛选状态和滚动位置） | §Tab 交互 | 未提及 Tab 缓存 | 补充 Tab 切换时的状态保持策略 |
|
||
| 2 | 🔴 | 财务看板分段加载策略（首次加载经营一览，其他板块懒加载） | §加载策略 | BOARD-3 单个 API 返回全部 6 板块 | 考虑拆分 API 或补充前端分段渲染策略 |
|
||
| 3 | 🔴 | 客户看板卡片点击跳转到 customer-detail 的交互和参数传递 | §卡片交互 | BOARD-2 未定义点击行为 | 补充卡片点击→跳转的参数（customerId） |
|
||
| 4 | 🔴 | 助教看板"距升档"进度条的可视化规范（进度条+百分比+差距小时数） | §进度展示 | BOARD-1 仅返回 `perfGap` 文本 | 补充进度条 UI 规范，或增加 `perfProgress` 百分比字段 |
|
||
| 5 | 🟠 | 看板数据的实时性标识（数据截止时间展示） | §数据时效 | 未提及 | 补充"数据更新于 XX:XX"的展示 |
|
||
| 6 | 🟠 | 财务看板环比数据的 tooltip 说明（点击环比箭头显示计算详情） | §环比交互 | 定义了环比格式但未定义交互 | 补充环比 tooltip 规范 |
|
||
| 7 | 🟠 | 助教看板卡片点击跳转到 coach-detail 的交互 | §卡片交互 | BOARD-1 未定义点击行为 | 补充卡片点击→跳转的参数（coachId） |
|
||
| 8 | 🟠 | 客户看板"最频繁"维度的柱状图交互（点击柱子显示具体数据） | §柱状图 | 定义了 weeklyVisits 数据但未定义交互 | 补充柱状图点击交互 |
|
||
| 9 | 🟠 | 看板页面的下拉刷新行为 | §刷新 | 未提及 | 补充下拉刷新规范 |
|
||
| 10 | 🟡 | 财务看板各板块的折叠/展开交互 | §板块交互 | 未提及 | 补充板块折叠/展开默认状态 |
|
||
| 11 | 🟡 | 看板数据加载失败时的错误展示 | §异常处理 | 未提及 | 补充错误状态 UI |
|
||
| 12 | 🟡 | 筛选项的动画效果（下拉展开/收起） | §筛选交互 | 未提及 | 补充筛选面板动画 |
|
||
| 13 | 🟡 | 助教看板的排名序号展示 | §排名 | 未提及 | 补充是否需要显示排名序号（如 #1、#2） |
|
||
| 14 | 🟡 | 财务看板数字的格式化规范（千分位、小数位、货币符号） | §数字格式 | 未提及 | 补充数字格式化规则（如 ¥12,345.67） |
|
||
|
||
---
|
||
|
||
### 3.5 P9（小程序前端-详情模块）vs NS1/RNS1
|
||
|
||
P9 定义了客户详情、助教详情、客户服务记录三个页面的完整前端规范，NS1 §3.4/§3.5 和 RNS1 RNS1.2 覆盖了 API 设计，但以下细节有遗漏。
|
||
|
||
|
||
| # | 风险 | 缺失内容 | P9 位置 | NS1/RNS1 现状 | 补充建议 |
|
||
|---|:----:|---------|--------|--------------|---------|
|
||
| 1 | 🔴 | 客户详情页分段加载策略（基本信息→消费汇总→AI 洞察→消费记录→备注） | §加载策略 | CUST-1 单个 API 返回全部数据 | 考虑拆分 API 或补充前端分段渲染和 skeleton 占位规范 |
|
||
| 2 | 🔴 | 助教详情页档位进度时间轴的视觉规范（节点样式、当前档位高亮、升档动画） | §档位展示 | COACH-1 返回 tierNodes 数据但未定义视觉 | 补充时间轴 UI 规范 |
|
||
| 3 | 🔴 | 消费记录 3 种类型的图标/颜色/标签样式映射 | §消费记录 | CUST-1 仅返回 `type` 字段 | 补充 type→icon/color 映射表 |
|
||
| 4 | 🔴 | 备注 AI 评分的星级展示规范（1-5 星样式、评分说明 tooltip） | §备注展示 | 仅返回 `ai_score` 数值 | 补充星级 UI 和 tooltip 文案 |
|
||
| 5 | 🟠 | 客户详情页 Banner 区域的视觉设计（余额/消费/到店间隔/距上次到店的布局） | §Banner | RNS1 T2-1 定义了 4 个字段但未定义布局 | 补充 Banner UI 规范 |
|
||
| 6 | 🟠 | AI 洞察卡片的展示规范（标题/摘要/展开详情/刷新按钮） | §AI 洞察 | RNS1 T2-1 定义了 aiInsight 字段但未定义交互 | 补充 AI 洞察卡片 UI 和交互 |
|
||
| 7 | 🟠 | 关联助教任务列表的展示规范（任务类型图标、状态标签、服务统计） | §关联助教 | RNS1 T2-2 定义了数据字段但未定义展示 | 补充任务列表 UI 规范 |
|
||
| 8 | 🟠 | 最亲密助教的展示规范（关系指数可视化、课时统计图表） | §亲密助教 | RNS1 T2-3 定义了数据字段但未定义展示 | 补充亲密助教卡片 UI |
|
||
| 9 | 🟠 | 消费记录中助教明细子列表的展开/折叠交互 | §消费记录 | RNS1 定义了 coaches 子数组但未定义交互 | 补充子列表展开/折叠规范 |
|
||
| 10 | 🟠 | 助教详情页 TOP20 客户列表的排序规则和展示字段 | §TOP 客户 | RNS1 T2-5 定义了扩展字段但未定义排序 | 补充排序规则（按什么排？关系指数？消费金额？） |
|
||
| 11 | 🟠 | 助教详情页历史月份统计的图表展示（折线图/柱状图/表格） | §历史统计 | RNS1 T2-6 定义了数据字段但未定义展示形式 | 补充图表类型和交互 |
|
||
| 12 | 🟠 | 客户服务记录页的月度统计汇总展示（monthCount/monthHours 的位置和样式） | §月度统计 | RNS1 T2-4 定义了字段但未定义展示 | 补充月度统计 UI 规范 |
|
||
| 13 | 🟠 | 助教详情页任务分组（active/inactive/abandoned）的视觉区分 | §任务分组 | RNS1 T2-5 定义了分组但未定义视觉 | 补充分组标题样式和折叠规则 |
|
||
| 14 | 🟠 | 客户详情页维客线索的展示规范（线索卡片布局、category 颜色映射） | §维客线索 | RNS1 定义了脱敏规则但未定义展示 | 补充线索卡片 UI |
|
||
| 15 | 🟡 | 客户详情页的分享功能（分享客户信息给其他助教） | §分享 | 未提及 | 确认是否需要分享功能 |
|
||
| 16 | 🟡 | 助教详情页的联系方式展示（电话/微信） | §联系方式 | 未提及 | 确认是否需要展示联系方式 |
|
||
| 17 | 🟡 | 消费记录的时间范围筛选（除月份切换外是否需要自定义日期范围） | §时间筛选 | 仅支持月份切换 | 确认是否需要自定义日期范围 |
|
||
| 18 | 🟡 | 详情页的返回按钮行为（返回上一页 vs 返回列表页） | §导航 | 未提及 | 补充返回导航规则 |
|
||
| 19 | 🟡 | 客户详情页电话号码的脱敏展示（中间 4 位用 *） | §隐私 | 未提及前端脱敏 | 补充：后端返回完整号码还是脱敏号码？前端是否需要"点击查看完整号码"？ |
|
||
| 20 | 🟡 | 助教详情页"收入明细"的展开/折叠交互 | §收入明细 | RNS1 定义了本月/上月各 4 项但未定义交互 | 补充收入明细展示规范 |
|
||
| 21 | 🟡 | 客户服务记录中"饮品描述"字段的展示位置和样式 | §服务记录 | NS1 L4 定义了 `drinks` 字段但未定义展示 | 补充饮品信息展示位置 |
|
||
| 22 | 🟡 | 详情页各模块的加载失败独立处理（某个模块失败不影响其他模块展示） | §异常处理 | 未提及 | 补充模块级错误处理策略 |
|
||
| 23 | 🟡 | 客户详情页"可用月数"的计算说明（余额÷月均消耗） | §余额分析 | RNS1 定义了 `availableMonths` 但未说明计算公式 | 补充计算公式和边界处理（月均消耗为 0 时） |
|
||
|
||
---
|
||
|
||
### 3.6 P10（租户管理后台）vs NS4
|
||
|
||
P10 定义了管理后台的完整规范（React + Vite + Ant Design），NS4 覆盖了主要功能模块，但以下细节有遗漏。
|
||
|
||
| # | 风险 | 缺失内容 | P10 位置 | NS4 现状 | 补充建议 |
|
||
|---|:----:|---------|---------|---------|---------|
|
||
| 1 | 🟠 | 角色权限管理的 CRUD 界面规范（创建角色、分配权限、权限树展示） | §权限管理 | 提及权限模型但未定义管理界面 | 补充权限管理页面的 UI 和交互规范 |
|
||
| 2 | 🟠 | 门店切换功能的交互规范（多门店用户的门店选择器位置、切换后的数据刷新） | §门店管理 | 提及多门店但未定义切换交互 | 补充门店选择器 UI 和切换流程 |
|
||
| 3 | 🟠 | 数据导出功能的规范（哪些页面支持导出、导出格式、导出权限） | §数据导出 | 未提及 | 补充导出功能清单和权限控制 |
|
||
| 4 | 🟠 | 操作日志/审计日志的查看界面 | §审计 | 未提及 | 补充日志查看页面规范 |
|
||
| 5 | 🟡 | 管理后台的响应式适配（最小支持分辨率、移动端适配策略） | §响应式 | 未提及 | 补充最小分辨率和断点规则 |
|
||
| 6 | 🟡 | 表格组件的统一规范（分页大小、排序交互、筛选器位置） | §表格规范 | 未提及 | 补充 Ant Design Table 的统一配置 |
|
||
| 7 | 🟡 | 表单验证的统一规范（必填标识、错误提示位置、实时验证 vs 提交验证） | §表单规范 | 未提及 | 补充表单验证规则 |
|
||
| 8 | 🟡 | 管理后台的国际化预留（是否需要多语言支持） | §国际化 | 未提及 | 确认是否需要国际化预留 |
|
||
| 9 | 🟡 | 管理后台的主题定制（品牌色、Logo 位置、暗色模式） | §主题 | 未提及 | 确认是否需要主题定制 |
|
||
|
||
---
|
||
|
||
## 四、跨文件系统性问题
|
||
|
||
以下问题在多个标杆文件中反复出现，反映了 Neo_Specs 整体层面的系统性缺失。
|
||
|
||
### 4.1 前端交互规范缺失（影响 P6/P7/P8/P9）
|
||
|
||
NS1/RNS1 主要关注后端 API 设计和数据字段定义，对前端交互细节覆盖不足：
|
||
- 加载状态（skeleton/loading/错误重试）未统一规范
|
||
- 空状态设计未覆盖
|
||
- 操作确认弹窗未规范
|
||
- 页面转场动画未定义
|
||
- 下拉刷新行为未统一
|
||
|
||
建议：新建一份前端交互规范文档（如 `NS-FE-INTERACTION.md`），统一定义上述交互模式，各页面 spec 引用即可。
|
||
|
||
### 4.2 数据加载策略缺失（影响 P8/P9）
|
||
|
||
多个复杂页面（财务看板、客户详情、助教详情）的 API 设计为单个接口返回全部数据，但标杆文件定义了分段加载策略。NS1/RNS1 未考虑：
|
||
- 首屏优先加载哪些模块
|
||
- 非首屏模块的懒加载触发条件
|
||
- 各模块独立的 loading/error 状态
|
||
|
||
建议：在 API 契约中为复杂页面提供分段加载方案（拆分 API 或定义 `fields` 参数控制返回范围）。
|
||
|
||
### 4.3 视觉样式映射缺失（影响 P6/P7/P8/P9）
|
||
|
||
多处数据字段（状态、类型、等级、优先级）需要前端映射为视觉样式（颜色、图标、标签），但 NS1/RNS1 仅定义了数据字段，未提供映射表：
|
||
- 任务状态→颜色/图标
|
||
- 课程类型→标签样式
|
||
- 会员等级→标签颜色
|
||
- 助教等级→标签样式
|
||
- 消费类型→图标
|
||
|
||
建议：在 API 契约或前端规范中补充统一的枚举→样式映射表。
|
||
|
||
### 4.4 异常处理规范缺失（影响所有文件）
|
||
|
||
标杆文件中定义了各种异常场景的处理方式，但 Neo_Specs 普遍缺少：
|
||
- 网络异常时的 UI 展示和重试机制
|
||
- 单个模块加载失败时的降级策略
|
||
- 数据为空时的空状态展示
|
||
- 操作失败时的错误提示文案
|
||
|
||
建议：新建异常处理规范文档，统一定义错误码→用户提示的映射。
|
||
|
||
### 4.5 营业日时间规范未贯穿（影响 P7/P8）
|
||
|
||
P7 多次强调"营业日以 08:00 为分割点"，这个规则影响绩效和看板的所有时间相关查询。NS1/RNS1 使用 `biz_date` 字段但未明确说明 biz_date 的生成规则是否已包含 08:00 分割逻辑。
|
||
|
||
建议：在 API 契约中明确声明"所有 biz_date 字段已由 ETL 层按 08:00 营业日分割点处理，后端和前端无需额外转换"。
|
||
|
||
---
|
||
|
||
## 五、建议优先级
|
||
|
||
### 立即处理（阻塞开发）
|
||
1. 补充营业日 08:00 分割点的处理说明（P7→NS1）
|
||
2. 补充"预估"标记的判断逻辑（P7→NS1）
|
||
3. 补充任务排序规则到 API 契约（P6→NS1）
|
||
4. 评估复杂页面的分段加载策略（P8/P9→NS1）
|
||
|
||
### 短期补充（影响联调质量）
|
||
5. 新建前端交互规范文档，统一加载/空状态/确认弹窗/错误处理
|
||
6. 补充枚举→样式映射表
|
||
7. 补充 App1/App2 的 Prompt 工程和指标口径（P5.1→NS3）
|
||
8. 补充管理后台权限管理界面规范（P10→NS4）
|
||
|
||
### 后续完善（不阻塞但影响体验）
|
||
9. 补充各页面的无障碍适配
|
||
10. 补充数据导出功能规范
|
||
11. 补充页面转场动画规范
|