version: "1.0.0"

name: "soundscore-project-delivery" description: "用于静态交互型音乐产品网站的交付方法总结。适合在需要从设计稿、信息架构和多轮反馈中快速落地可演示、可维护、可发布项目时调用。"

Soundscore Project Delivery Skill

目的

本 Skill 用于指导“设计驱动、交互密集、静态可部署”的产品网站落地，尤其适合以下类型项目：

• 需要直接从设计参考图、功能说明文档和多轮需求反馈中推进实现
• 页面结构清晰，但交互状态较多，且演示体验要求高
• 需要以静态站点形式稳定交付，尽量降低运行环境要求
• 需要在持续迭代中兼顾视觉一致性、代码可维护性与最终可发布性

适用场景

当项目同时满足以下特征时，应优先套用本 Skill：

• 有明确的信息架构文档，页面边界和核心流程相对稳定
• 首页、工作台、项目页、个人中心、关于页等页面间存在统一导航与状态流转
• 存在上传、播放、导出、弹窗、权限拦截、分页、编辑等多状态交互
• 最终交付形式偏向静态网页、课程展示网站、作品集或离线演示包

核心原则

1. 以“文档 + 设计稿 + 反馈记录”作为共同规范

不要只依赖单次口头描述实现页面，而应把三类信息共同视为规格来源：

• 信息架构文档：定义页面职责、数据类型、路由关系、交互边界
• 视觉参考图：定义布局重心、风格基调、层级关系和第一视线焦点
• 多轮反馈记录：定义真实使用中的优先级调整与细节修正方向

实现时应先判断“这是结构性要求、体验性要求，还是展示性要求”，再决定改动层级，避免为了局部细节破坏整体架构。

2. 优先保证“可稳定打开、可稳定演示、可稳定交付”

对于此类项目，首要目标不是引入更多工程化能力，而是保证以下几点：

• 任意电脑上尽量低门槛打开
• 核心流程从进入首页到完成主要操作能够稳定跑通
• 在课程网站、静态托管或离线场景下尽量少出兼容性问题

因此，技术选型与文件结构都应服务于“稳定交付”，而不是追求过度复杂的工程堆叠。

3. 先建立页面骨架，再逐层补足状态与交互

建议采用以下实现顺序：

1. 先搭建全局布局、导航、页脚、主要页面容器
2. 再实现核心路由与全局状态
3. 再补齐关键业务流程
4. 最后处理细节动效、视觉强化和容错逻辑

这样可以避免项目早期就陷入细枝末节，导致整体流转不完整。

推荐工作流

一、先定义全局框架

优先统一以下内容：

• 页面划分：首页、工作台、我的项目、个人中心、关于页
• 全局组件：导航栏、登录弹窗、协议弹窗、升级弹窗、导出弹窗
• 全局状态：当前页面、当前用户、当前项目、当前音频、全局弹窗开关
• 视觉基线：主背景、品牌色、按钮风格、卡片风格、阴影与高亮规则

一旦这些基础抽象稳定，后续新增功能时才能保持一致性。

二、用“主流程视角”实现功能，而不是零散堆功能点

推荐围绕用户真实路径组织开发：

1. 进入首页
2. 完成上传或进入已有项目
3. 跳转工作台并看到清晰的处理中过渡
4. 在工作台执行核心编辑、播放、切换、导出操作
5. 返回项目页、个人页、关于页完成补充行为

每新增一个功能，都应回答它属于哪条主流程、是否会打断流程、是否需要过渡状态和反馈提示。

三、把“全局状态”和“页面局部状态”明确分层

建议遵循：

• 与跨页面流转有关的状态放入全局 store
• 与单页展示、临时开关、局部 UI 相关的状态放在页面内部

例如：

• 用户信息、登录状态、跨页待处理音频、权限状态属于全局状态
• 单个弹窗的局部切换、分页页码、某个工具栏局部菜单开关属于页面状态

这样能显著降低页面间耦合，并避免状态串扰。

结构与资源治理

1. 资源目录要尽早定型

建议在项目早期就统一资源结构，例如：

• public/images/avatars
• public/images/covers
• public/images/ui
• public/audios
• public/docs
• public/lib
• public/css
• src/pages
• src/components
• src/data

资源目录一旦混乱，后期路径修复、部署兼容和缓存排查都会放大成本。

2. 静态资源路径必须统一策略

对于静态可部署项目，应尽量避免混用多套路径写法。所有图片、音频、字体、文档路径都应遵循一致的引用规则，并在部署前做一次全量检查。

尤其要注意：

• 图片和音频引用路径是否统一
• 导出文档链接是否在浏览器中可直接访问
• 字体文件在目标环境下是否确实能加载
• 不同页面是否存在路径写死但目录已迁移的问题

3. 样式、逻辑、数据尽量分离

虽然这类项目可接受轻量实现，但仍应避免把大量静态样式和静态数据直接堆入页面脚本中。

建议遵循：

• 静态公共样式进入 global.css
• 可复用 UI 区块拆为组件
• 曲谱数据、预设数据、教学数据独立到 src/data
• 页面脚本只保留页面真正需要的状态、方法和模板

这会直接提升后期改版和排障效率。

交互设计落地经验

1. 对复杂交互优先追求“结果可信”

如果某个交互是产品可信度的关键，就不能只做视觉占位，而应确保其核心结果成立。

典型做法包括：

• 播放控制要能真实驱动时间、进度、轨道音量和界面联动
• 导出按钮要符合浏览器行为，不要造成页面被替换或流程中断
• 权限限制要在用户触发时给出明确、可理解的反馈

“像是真的”不等于“真的可用”，关键演示路径必须尽可能靠近真实使用体验。

2. 所有拦截动作都要给用户清晰反馈

对于登录拦截、权限拦截、删除确认、不可用功能提示、支付升级、导出限制等场景，不应只让按钮失效，而要明确告知：

• 为什么不能继续
• 当前处于什么状态
• 用户下一步应该做什么

清晰的反馈会显著提升产品成熟度。

3. 过渡状态不能缺席

上传后、跳转后、处理中、保存中、导出前后，都应有对应的中间状态。 这些状态的价值不只是“美观”，更是为了避免用户误解系统无响应或流程出错。

4. 复用弹窗而不是复制流程

类似登录、协议、升级、导出、删除确认这类高频交互，应该尽量做成可复用组件，并通过参数或状态控制内容与行为。 这样既能保持风格统一，也能降低多处同步修改的成本。

兼容性与稳健性经验

1. 把部署环境当成正式环境来适配

课程网站、静态托管平台、内嵌容器、离线拷贝环境，都可能改变浏览器行为。 因此需要提前考虑：

• 新窗口与下载行为是否会被限制
• 路径是否在二级路径部署下仍可访问
• 字体是否因系统差异导致显示异常
• 页面缩放、容器嵌套和 sticky/fixed 元素是否产生遮挡

不要假设“本机可用就等于上线可用”。

2. 关键字体与关键资源尽量本地化

对于会影响核心信息显示的字体、图标和样式资源，应优先本地化，避免依赖外部网络环境。 这类项目一旦缺少关键字体，排版、音符显示和界面可信度都会明显下降。

3. 对缓存和本地存储保持警惕

当页面表现“偶尔正确、偶尔错误”时，不要只怀疑代码本身，也要检查：

• 是否为旧路径残留在本地缓存
• 是否有旧用户数据未同步更新
• 是否存在资源迁移后本地状态未自愈的问题

对于关键用户信息，应在初始化阶段进行必要的修正与兜底。

多轮迭代中的方法论

1. 把需求分成三类处理

面对连续反馈时，先区分：

• 结构类：页面层次、组件职责、路由关系、资源组织
• 体验类：流程顺畅度、可理解性、反馈提示、交互连续性
• 展示类：字号、间距、层级、图标、文案、对齐方式

结构类优先级最高，其次是体验类，最后再统一打磨展示类。 这样能避免在结构未稳时过早陷入微调。

2. 版本冻结后必须转入“增量维护模式”

一旦某个版本被冻结，应明确：

• 后续改动在哪个新目录或新版本继续
• 哪些历史版本只读、不再回写
• 最终交付目录是哪一个

否则容易出现“改对了文件但改错了版本”的问题。

3. 文档要随着实现演进

当项目结构、资源路径、关键功能或交付方式发生明显变化时，应同步更新说明文档与经验文档。 否则文档会迅速失真，后续接手者很难判断当前真实状态。

高频反复修改风险

以下问题在真实迭代中往往会被多次提及，且如果处理方式不当，容易出现“已经改了，但仍不满意”的情况。 因此应将它们视为高优先级设计风险，而不是普通样式微调。

1. 页面紧凑度容易在“过松”和“过紧”之间反复摆动

当用户反复提出“太松”“太紧”“太小”“再放大一点”时，通常说明问题不只是单个间距，而是以下几个因素没有一起平衡：

• 首屏可见范围内的信息密度
• 卡片尺寸、留白、标题区高度之间的比例关系
• 按钮是否在首屏直接可见
• 内容主次是否足够清楚

处理这类问题时，不应只改单个 margin、padding 或字号，而应以“首屏可视信息是否完整”“重点操作是否立即可见”为判断标准，整体联动调整容器高度、卡片尺寸、区块间距和文本密度。

2. 视觉可见不等于信息有效

有些元素虽然已经出现在页面上，但用户仍会感到“不对”，常见原因包括：

• 文本太小，虽未溢出但阅读负担大
• 按钮存在但不够显眼，无法形成明确操作引导
• 表格或卡片虽完整显示，但信息重心不明确

因此不能把“没有溢出、没有报错、元素能看到”视为完成，而要进一步检查用户是否能在数秒内理解信息结构并定位到目标操作。

3. 文案与源材料不一致会显著降低可接受度

当页面展示内容来自既有文档、分工说明或已确认文本时，应优先保证忠实呈现，而不是擅自优化措辞。 尤其在团队介绍、职责说明、协议条款、按钮文案等区域，用户往往对文本准确性比对视觉微调更敏感。

推荐原则：

• 若有明确来源文档，以来源文档为准
• 若需要压缩内容，应先保证原意完整
• 若用户多次修正文案，应把该处视为高敏感内容，不再自行改写

4. 伪可用设计会比“暂不可用”更容易引发不满

以下情况尤其要避免：

• 看起来像可以下载、导出、删除，但点击后无反应
• 看起来像可选择的轨道、按钮或入口，实际上没有后续行为
• 在当前页面触发操作后直接跳离原流程，破坏上下文

更稳妥的设计方式是：

• 能做，就保证结果可信
• 不能做，就明确提示限制原因
• 若只能部分完成，就让交互结果与用户预期尽量一致

“有按钮但没行为”通常比“明确告知暂不可用”更容易造成负面反馈。

5. 容器层级与滚动遮挡问题属于结构问题，不只是样式问题

当用户多次提到“重叠”“被挡住”“缩放后顶上去”“标题栏压不住内容”时，应优先检查：

• sticky / fixed 元素的层级关系
• 是否建立了正确的层叠上下文
• 滚动容器和内部绝对定位元素是否共用错误层级
• 在浏览器缩放和小窗口下是否仍保持稳定

这类问题不能只靠提高单个元素的层级数值反复碰运气，而应从容器结构、定位关系和滚动上下文统一处理。

6. 课程网站、嵌入环境与正式浏览器的体验差异要提前显式告知

如果项目部署在课程网站、嵌套展示页或受限制的容器中，很多“本地没问题”的交互在上线后会变形，例如：

• 下载行为受限
• 页面缩放导致布局拥挤
• 局部区域高度不足导致覆盖
• 某些操作更适合新窗口打开

这种情况下，经验不是“默认相信环境一致”，而是：

• 优先让主流程在受限环境下仍可跑通
• 对明显受宿主环境影响的体验提前提示
• 把“最佳体验入口”明确传达给用户

7. 首页展示图和装饰视觉是高感知区域，轻微失衡也会被反复指出

像首页实机展示、屏幕截图裁切、白边、缩放、浮动装饰、图标方向这类内容，虽然看似只是细节，但会直接影响用户对整体完成度的判断。 这些区域应优先关注：

• 是否完整展示核心画面
• 是否存在白边、裁切失衡、重心偏移
• 图标语义是否与操作含义一致
• 装饰效果是否服务于主视觉，而不是喧宾夺主

高感知视觉区应采用“小步验证、及时回看”的方式迭代，而不是一次性大改。

8. 关于页、团队页、说明页的难点不在“做出来”，而在“信息可信 + 阅读顺畅”

这类页面很容易被误认为是低优先级静态页，但实际上用户会特别关注：

• 团队信息是否完整、可信
• 排版是否一眼能读懂
• 按钮是否在首屏可见
• 弹窗表格是否规整、对齐、易读

因此，静态说明页不应只满足“有内容”，而应满足“内容可信、信息层级清楚、阅读成本低”。

高敏感设计项的处理策略

如果某个设计点在同一项目中被连续多次修正，应将其视为高敏感设计项，并按以下方式处理：

1. 优先回到用户真正不满意的层面

不要把连续反馈机械理解为“再调一点样式”，而应先判断用户真正不满意的是：

• 信息看不全
• 操作不够明显
• 结构不够紧凑
• 文案不够准确
• 交互结果不符合预期

只有找准层面，后续修改才不会反复摇摆。

2. 不要用局部数值微调替代整体判断

如果一个区域已经经历多轮反馈，后续修改不应再只围绕单个数值，而应整体检查：

• 首屏可见内容
• 重点按钮是否可达
• 内容是否一眼可读
• 页面是否在不同缩放下仍稳定

3. 对高敏感区域建立“完成标准”

建议把用户高频反馈区域转化为明确标准，例如：

• 首屏必须直接看到完整卡片和关键按钮
• 关键操作不能造成页面跳离当前任务流
• 表格内容必须忠实于来源文本并保持对齐一致
• 标题栏在滚动和缩放下不能被任何内容覆盖

只有把主观不满转成客观标准，后续迭代才会越来越稳定。

交付前检查清单

在最终发布前，至少完成以下检查：

• 所有关键页面能正常进入
• 主要交互流程从首页到工作台能完整跑通
• 全局弹窗均可打开、关闭、复用
• 导航、返回、跳转逻辑一致
• 资源路径全部可访问
• 关键字体、图标、图片、音频、导出文档加载正常
• 本地存储不会导致明显的错误状态残留
• 样式未被大面积内联到脚本中
• 最终版本号、目录名、交付目录彼此一致
• 仓库状态清晰，可直接打包、部署或托管
• 高敏感区域已经过首屏可见性、缩放稳定性、文案准确性和交互可信度复查

不应沉淀为长期经验的做法

以下内容不应被误总结为通用方法论：

• 仅为当前环境临时适配的应急处理
• 只针对单次展示场景的特殊绕行
• 过度依赖某一环境、某一浏览器、某一宿主网站的行为假设
• 只解决局部表象、没有解释根因的“碰巧可用”式改法

沉淀经验时，应保留那些能跨项目复用、能解释为什么有效、并且能指导后续类似项目落地的做法。

最终产出标准

一个合格的此类项目交付结果，应同时满足：

• 设计风格统一
• 页面结构清晰
• 主流程完整可演示
• 核心交互可信
• 资源组织规范
• 维护成本可控
• 静态部署友好

若只能做到“能展示页面”，但无法保证流程顺畅、资源稳定、结构清楚、后续可维护，则不算高质量交付。