10 KiB
10 KiB
软件改造部署外包交付规范
本文件是
SKILL.md的强制配套规范。凡触发“初始化并部署项目”“面板风格 UI 改造”“项目外包交付”等请求，交付前必须逐条对照。
0. 三条红线
- 甲方可见材料中性化：README、界面、截图、录屏、交付清单、演示文档、注释、配置和资源文件名，不主动出现其他项目名称、外部仓库链接、原作者、致谢、迁移说明、改造前界面或版本对比。
- 许可证合规边界：MIT、Apache-2.0、BSD 等许可证要求随源码保留的版权声明、许可证全文或 NOTICE 文件不得删除、替换或改写；不得把第三方代码虚假表述为全部由交付团队原创。
- 稳定交付：部署可复现、功能可验证、截图录屏与最终版本一致、文档可落地；不得为了清理外观线索而破坏业务功能。
演示交付包可以不放入源码和 LICENSE；源码包必须按所适用许可证保留版权、许可和 NOTICE 材料。
1. 核心服务内容（6 项，必须全部完成）
| # | 服务 | 执行要点 |
|---|---|---|
| 1 | 项目部署运行 | 完整获取源码、搭建环境、编译配置调试；核心功能正常，无报错、闪退、功能缺失 |
| 2 | 界面定制改造 | UI 风格、色彩、布局、导航和数据展示全面优化；需要大屏的项目必须建设概览大屏 |
| 3 | 标识规范与许可证核对 | 清理依法可移除的公司名、LOGO、商标、专属标识、联系方式和来源宣传线索；核对源码 LICENSE/NOTICE 完整性 |
| 4 | 素材录制归档 | 内部基线仅用于核对；对外只提供最终产品的全页面截图与全功能录屏，分类上传约定网盘 |
| 5 | 文档编制优化 | 按当前产品口径编写可直接交付的标准化 README（见第 3 节） |
| 6 | 售后答疑支撑 | 交付后配合部署、使用、报错排查等答疑；基础质保、响应时限以合同约定为准 |
1.1 素材采集时序
获取项目(0) → 完整度/项目分析(1-2)
→ 初始版本启动(3，内部) → 初始界面截图(4，仅内部)
→ [此后才允许改代码] 品牌/界面/AI/标识规范(6-11)
→ 产品构建启动(15) → 健康验证(16)
→ 产品界面截图 + 全功能录屏(17)
→ README/版本归档(18) → 交付核查(19) → 交付树双存档(20，授权推送时)
- 内部基线截图必须是代码零改动状态下的真实画面，仅用于内部核对，任何情况下不进入交付物。
- 对外截图与录屏必须来自最终构建部署并健康通过的版本，禁止使用半成品。
- 对外截图页面全覆盖、文件名中性，不出现 before/after、改造前、原版等字样。
2. 标识规范检查清单
必须扫描并处理以下位置：
- 前端：可见公司名/品牌名、Logo、Favicon、水印、关于弹窗、页脚、登录页、浏览器标题。
- 代码注释：文件头中的公司名称、作者 ID、外部链接与联系方式。
- 配置与元数据：清单文件的
author、repository、homepage字段、Docker 镜像/容器名、环境变量中的专属域名、消息模板品牌签名。 - 文档：README 及 docs 内的公司宣传内容、二维码、购买链接、商务联系方式、主动来源说明和致谢表述。
- 许可证：源码包中的 LICENSE/NOTICE 必须核对并完整保留；不得删除法律要求保留的许可文本。
- 资源文件：图片、视频、音频中嵌入的水印、商标和第三方商业标识。
验收前必须做全文检索（关键词按实际项目扩充）：
grep -rniE "原公司名|原域名|原品牌|原作者ID|原仓库|致谢|qq群|微信|商务合作|before|after|改造前|原版" . \
--include="*.{ts,tsx,js,jsx,vue,java,py,go,json,md,html,yml,yaml,less,css,scss}"
甲方可见交付物中不得命中主动来源宣传、商业标识或版本对比关键词；源码许可证文件按许可证要求单独保留。
3. 标准化 README 必备内容（12 项，缺一不可）
- 一句话项目简介。
- 详细功能描述（逐条功能对应配套截图）。
- 解决的行业痛点。
- 核心技术优势。
- 具体应用场景。
- 适配目标行业与人群。
- 商业应用价值。
- 技术架构说明（含架构图或拓扑图）。
- 环境前置依赖要求。
- 详细快速开始指南。
- 完整安装部署教程（优先 Docker 一键部署；不适配 Docker 的提供可复现的手动步骤）。
- 版权与使用说明（当前产品口径，不作虚假权属表述）。
要求：图文结合、结构完整、内容详实、与项目实际一致；禁止出现未实现功能、虚构命令、无法访问链接、主动来源宣传及致谢表述。
4. 完整交付物清单（7 项，缺一即不合格）
- 可稳定运行的完整项目源码。
- 当前产品全页面高清界面截图（无初始界面对比、无 before/after）。
- 项目全功能操作演示录屏（无卡顿、无黑屏，完整展示核心功能）。
- 分类整理完毕的素材归档链接（长期有效，可正常访问下载）。
- 标准化完整版 README（含架构图、部署教程、场景说明）。
- Docker 一键部署脚本/部署包（不适配的提供书面说明）。
- 项目环境依赖清单、部署注意事项说明文档。
4.1 交付包结构与交付清单（强制）
交付物分两部分：一个给甲方/终端使用的交付压缩包 + 一份单独的交付清单。
交付压缩包内部结构：
README.md # 必须在包根目录
docs/screenshots/ # README 引用的全部配图，相对路径完整，解压即可显示
截图/界面截图/ # 当前产品全页面截图（中性命名）
录屏/ # 全功能演示视频
文档/环境依赖清单.md
文档/部署注意事项.md
硬性规则：
- README 只在包根出现一份；“文档”目录不得再放 README。
- 打包必须把 README 引用图片一并拷入并保持相对路径；交付前解压验证图片可显示。
- 《交付清单.md》不打入 zip，作为与 zip 并列的单独文件提供。
- 包内不出现内部工具、执行过程、外部项目线索及版本对比信息，命名使用甲方可读的中性名称。
- 交付清单列出每项交付物的包内路径/链接、默认账号、验收记录与售后说明。
4.2 交付树仓库双存档（授权推送时，强制）
用户明确授权推送到交付树仓库（默认 https://code.xinmi.cloud/depei/panel-delivery-tree）时，必须做到：
- 压缩包 + 解压内容双存档：
交付包/<key>-delivery-<YYYYMMDD>.zip与同名解压目录交付包/<key>-delivery-<YYYYMMDD>/（README、docs/screenshots/、截图/界面截图/、录屏/*.mp4、文档/）同时入库； 前者用于整包下载，后者用于在 Gitea 网页直接浏览，内容必须与 zip 一致。 - 真实源码以 git submodule 挂到
项目源码/<key>并固定到交付提交；登记 Git 主地址、上游来源、分支与锁定 commit。 - 录屏等被全局
.gitignore忽略的二进制，须在交付包/**下显式取反放行（!交付包/**/*.mp4等）， 并用git check-ignore -v确认实际命中取反规则；交付包模板/仍不入库二进制。 - 机器与人工登记一致：sidecar JSON 与
registry.json记录package、字节数、sha256、git、deploy、extractedDir、extractedFileCount、extractedSizeBytes/MB、archiveForm；交付登记.md、交付包/README.md、根README.md同步链接 zip 与解压目录。文件数、体积、SHA256 必须实测，禁止照抄。 - 推送后双重验证：
git rev-parse HEAD与git ls-remote origin refs/heads/main一致； 用 Gitea Contents API 分段编码中文路径（保留/）确认解压目录与录屏 mp4 已在远程。 - 含中文路径的批量复制/删除优先用 Python
shutil，避免 PowerShell 管道中文乱码与删除策略拦截。 - 未获推送授权时不推送任何仓库，只在项目内
.Codex/delivery本地留档，沿用“不推送代码”约束。
5. 验收标准（7 条，全部达标方可验收）
- 运行：正常启动、稳定运行；所有功能可正常操作，无报错、失效、页面错乱或接口异常。
- 界面：布局、风格、导航全面优化，概览大屏美观、数据正常、适配主流分辨率。
- 标识：甲方可见页面、注释、配置和文档无第三方商业标识、主动来源宣传及版本对比。
- 素材：产品截图清晰、页面全覆盖；录屏流畅、完整演示核心功能；归档分类规整可下载。
- 文档：README 覆盖第 3 节全部模块，图文结合、架构图准确、教程可落地、版权说明不作虚假表述。
- 部署：Docker 一键部署无故障；不支持 Docker 的手动步骤可复现。
- 合规：不侵犯第三方知识产权，源码许可证和 NOTICE 材料按要求保留。
6. 验收与整改流程
- 提交完整交付物、归档链接与文档资料。
- 甲方按合同约定完成核验。
- 合格后进入验收/结算流程。
- 不合格时列明问题，在约定时限内整改并重新交付；每次整改必须更新审计和核查记录，形成闭环。
7. 售后与响应 SLA
- 质保范围、响应时限和质保期以合同正文为准。
- 通常包括：功能缺陷、部署问题、文档答疑、使用指导和基础技术咨询。
- 新增功能、深度定制、第三方平台变更或超出原需求的工作，可另行协商。
8. 保密与知识产权
- 交付成果的使用权、商用权及知识产权归属以合同和授权文件为准。
- 不得未经授权私自转发、售卖、复用、转让或二次分发甲方成果。
- 对商业信息、项目需求、交付资料、客户资源和技术方案承担保密义务。
9. 交付前自检顺序（强制）
1. 全功能走查 → 无报错、无功能缺失
2. panel_ui_audit.py → 0 violations
3. 标识/版本对比检索 → 甲方可见材料无残留
4. README 12 项对照 → 图文齐全、链接可达、无主动来源表述
5. 截图/录屏覆盖度核对 → 页面全覆盖、功能全演示
6. deliverables_check.py → 7 项交付物齐备
第 6 步脚本退出码非 0 时，禁止声明“已交付”。