panel-project-deploy/references/delivery-contract.md

# 软件改造部署外包交付规范

> 本文件是 `SKILL.md` 的强制配套规范。凡触发“初始化并部署项目”“面板风格 UI 改造”“项目外包交付”等请求，交付前必须逐条对照。

## 0. 三条红线

1. **甲方可见材料中性化**：README、界面、截图、录屏、交付清单、演示文档、注释、配置和资源文件名，不主动出现其他项目名称、外部仓库链接、原作者、致谢、迁移说明、改造前界面或版本对比。
2. **许可证合规边界**：MIT、Apache-2.0、BSD 等许可证要求随源码保留的版权声明、许可证全文或 NOTICE 文件不得删除、替换或改写；不得把第三方代码虚假表述为全部由交付团队原创。
3. **稳定交付**：部署可复现、功能可验证、截图录屏与最终版本一致、文档可落地；不得为了清理外观线索而破坏业务功能。

演示交付包可以不放入源码和 LICENSE；源码包必须按所适用许可证保留版权、许可和 NOTICE 材料。

## 1. 核心服务内容（6 项，必须全部完成）

| # | 服务 | 执行要点 |
|---:|---|---|
| 1 | 项目部署运行 | 完整获取源码、搭建环境、编译配置调试；核心功能正常，无报错、闪退、功能缺失 |
| 2 | 界面定制改造 | UI 风格、色彩、布局、导航和数据展示全面优化；需要大屏的项目必须建设概览大屏 |
| 3 | 标识规范与许可证核对 | 清理依法可移除的公司名、LOGO、商标、专属标识、联系方式和来源宣传线索；核对源码 LICENSE/NOTICE 完整性 |
| 4 | 素材录制归档 | 内部基线仅用于核对；对外只提供最终产品的全页面截图与全功能录屏，分类上传约定网盘 |
| 5 | 文档编制优化 | 按当前产品口径编写可直接交付的标准化 README（见第 3 节） |
| 6 | 售后答疑支撑 | 交付后配合部署、使用、报错排查等答疑；基础质保、响应时限以合同约定为准 |

### 1.1 素材采集时序

```text
获取项目(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 必须核对并完整保留；不得删除法律要求保留的许可文本。
- 资源文件：图片、视频、音频中嵌入的水印、商标和第三方商业标识。

验收前必须做全文检索（关键词按实际项目扩充）：

```bash
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 项，缺一不可）

1. 一句话项目简介。
2. 详细功能描述（逐条功能对应配套截图）。
3. 解决的行业痛点。
4. 核心技术优势。
5. 具体应用场景。
6. 适配目标行业与人群。
7. 商业应用价值。
8. 技术架构说明（含架构图或拓扑图）。
9. 环境前置依赖要求。
10. 详细快速开始指南。
11. 完整安装部署教程（优先 Docker 一键部署；不适配 Docker 的提供可复现的手动步骤）。
12. 版权与使用说明（当前产品口径，不作虚假权属表述）。

要求：图文结合、结构完整、内容详实、与项目实际一致；禁止出现未实现功能、虚构命令、无法访问链接、主动来源宣传及致谢表述。

## 4. 完整交付物清单（7 项，缺一即不合格）

1. 可稳定运行的完整项目源码。
2. 当前产品全页面高清界面截图（无初始界面对比、无 before/after）。
3. 项目全功能操作演示录屏（无卡顿、无黑屏，完整展示核心功能）。
4. 分类整理完毕的素材归档链接（长期有效，可正常访问下载）。
5. 标准化完整版 README（含架构图、部署教程、场景说明）。
6. Docker 一键部署脚本/部署包（不适配的提供书面说明）。
7. 项目环境依赖清单、部署注意事项说明文档。

### 4.1 交付包结构与交付清单（强制）

交付物分两部分：**一个给甲方/终端使用的交付压缩包** + **一份单独的交付清单**。

交付压缩包内部结构：

```text
README.md                 # 必须在包根目录
docs/screenshots/         # README 引用的全部配图，相对路径完整，解压即可显示
截图/界面截图/             # 当前产品全页面截图（中性命名）
录屏/                      # 全功能演示视频
文档/环境依赖清单.md
文档/部署注意事项.md
```

硬性规则：

1. README 只在包根出现一份；“文档”目录不得再放 README。
2. 打包必须把 README 引用图片一并拷入并保持相对路径；交付前解压验证图片可显示。
3. 《交付清单.md》不打入 zip，作为与 zip 并列的单独文件提供。
4. 包内不出现内部工具、执行过程、外部项目线索及版本对比信息，命名使用甲方可读的中性名称。
5. 交付清单列出每项交付物的包内路径/链接、默认账号、验收记录与售后说明。

### 4.2 交付树仓库双存档（授权推送时，强制）

用户明确授权推送到交付树仓库（默认 `https://code.xinmi.cloud/depei/panel-delivery-tree`）时，必须做到：

1. **压缩包 + 解压内容双存档**：`交付包/<key>-delivery-<YYYYMMDD>.zip` 与同名解压目录
   `交付包/<key>-delivery-<YYYYMMDD>/`（README、`docs/screenshots/`、`截图/界面截图/`、`录屏/*.mp4`、`文档/`）同时入库；
   前者用于整包下载，后者用于在 Gitea 网页直接浏览，内容必须与 zip 一致。
2. 真实源码以 git submodule 挂到 `项目源码/<key>` 并固定到交付提交；登记 Git 主地址、上游来源、分支与锁定 commit。
3. 录屏等被全局 `.gitignore` 忽略的二进制，须在 `交付包/**` 下显式取反放行（`!交付包/**/*.mp4` 等），
   并用 `git check-ignore -v` 确认实际命中取反规则；`交付包模板/` 仍不入库二进制。
4. 机器与人工登记一致：sidecar JSON 与 `registry.json` 记录 `package`、字节数、`sha256`、
   `git`、`deploy`、`extractedDir`、`extractedFileCount`、`extractedSizeBytes/MB`、`archiveForm`；
   `交付登记.md`、`交付包/README.md`、根 `README.md` 同步链接 zip 与解压目录。文件数、体积、SHA256 必须实测，禁止照抄。
5. 推送后双重验证：`git rev-parse HEAD` 与 `git ls-remote origin refs/heads/main` 一致；
   用 Gitea Contents API 分段编码中文路径（保留 `/`）确认解压目录与录屏 mp4 已在远程。
6. 含中文路径的批量复制/删除优先用 Python `shutil`，避免 PowerShell 管道中文乱码与删除策略拦截。
7. 未获推送授权时不推送任何仓库，只在项目内 `.Codex/delivery` 本地留档，沿用“不推送代码”约束。

## 5. 验收标准（7 条，全部达标方可验收）

1. **运行**：正常启动、稳定运行；所有功能可正常操作，无报错、失效、页面错乱或接口异常。
2. **界面**：布局、风格、导航全面优化，概览大屏美观、数据正常、适配主流分辨率。
3. **标识**：甲方可见页面、注释、配置和文档无第三方商业标识、主动来源宣传及版本对比。
4. **素材**：产品截图清晰、页面全覆盖；录屏流畅、完整演示核心功能；归档分类规整可下载。
5. **文档**：README 覆盖第 3 节全部模块，图文结合、架构图准确、教程可落地、版权说明不作虚假表述。
6. **部署**：Docker 一键部署无故障；不支持 Docker 的手动步骤可复现。
7. **合规**：不侵犯第三方知识产权，源码许可证和 NOTICE 材料按要求保留。

## 6. 验收与整改流程

1. 提交完整交付物、归档链接与文档资料。
2. 甲方按合同约定完成核验。
3. 合格后进入验收/结算流程。
4. 不合格时列明问题，在约定时限内整改并重新交付；每次整改必须更新审计和核查记录，形成闭环。

## 7. 售后与响应 SLA

- 质保范围、响应时限和质保期以合同正文为准。
- 通常包括：功能缺陷、部署问题、文档答疑、使用指导和基础技术咨询。
- 新增功能、深度定制、第三方平台变更或超出原需求的工作，可另行协商。

## 8. 保密与知识产权

- 交付成果的使用权、商用权及知识产权归属以合同和授权文件为准。
- 不得未经授权私自转发、售卖、复用、转让或二次分发甲方成果。
- 对商业信息、项目需求、交付资料、客户资源和技术方案承担保密义务。

## 9. 交付前自检顺序（强制）

```text
1. 全功能走查              → 无报错、无功能缺失
2. panel_ui_audit.py       → 0 violations
3. 标识/版本对比检索        → 甲方可见材料无残留
4. README 12 项对照        → 图文齐全、链接可达、无主动来源表述
5. 截图/录屏覆盖度核对      → 页面全覆盖、功能全演示
6. deliverables_check.py   → 7 项交付物齐备
```

第 6 步脚本退出码非 0 时，禁止声明“已交付”。