# Phoenix品牌插件示例

**Repository Path**: phoenixwing/phoenix-branding

## Basic Information

- **Project Name**: Phoenix品牌插件示例
- **Description**: Phoenix Admin 品牌插件开发示例，演示通过独立插件自定义登录页、默认启动页、Logo、应用名称、favicon 和页面标题，不修改 Host 认证逻辑与 tracked 源码。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-11
- **Last Updated**: 2026-09-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Phoenix Branding

Phoenix Branding（`phoenix.admin.branding`）是 Phoenix Admin 的品牌与启动页扩展参考实现，
用于通过受控插件声明替换登录页呈现、工作台标识、应用名称、页面标题、favicon 和默认
欢迎页。

当前版本为 **0.1.1**。仓库同时提供源码开发挂载，以及可由 Phoenix Admin 受控安装的
`.phoenix.cool` 声明式正式制品。

## 核心能力

| 能力 | 实现 | 安全边界 |
| --- | --- | --- |
| 登录页品牌 | 由 Host 在 Vue 挂载前读取活动品牌快照，首个可见帧直接显示品牌 | 只接受安全文本、Host 布局预设和已校验包内资源 |
| 工作台品牌 | v2 完整声明 Acme 固定标题、副标题和明暗 Logo | Host 只在完整插件与完整 Host 品牌之间选择，不逐页查库 |
| 默认首页 | 提供独立欢迎页，并在已登录工作台内从 `/` 跳转 | 登录页、错误页、无权限页仍由 Host 管理 |
| 后端入口 | 提供最小 Midway 模块入口 | 不声明接口、实体、DDL、数据库表或远程 API |

默认的 Acme 品牌内容是可替换示例。正式公开登录声明位于
`packages/admin-plugin/manifest.json`；欢迎页与兼容固定文案位于 `site-profile.json`，并由验证
脚本保证两者一致。Logo 与 favicon 位于插件 `assets/` 目录，每项资源都声明 SHA-256、字节数
和 MIME 类型。

## 登录首屏快照

Public Login Branding Snapshot 负责登录前公开界面和工作台品牌投影，不包含登录后首页、菜单、
权限、capability 或业务数据。选择或启用品牌后先进入待重启；Host 在受控 API 重启时从已验证
manifest 与包内资源生成完整只读快照并原子切换。停用或取消选择并重启后恢复最近一次已验证
Host 默认品牌。

浏览器在应用挂载前同步读取该快照，因此不会先显示一个品牌来源再切换成另一个，也不需要
插入中性过渡提示。认证表单、验证码、OAuth、Token、提交事件和路由守卫始终由 Host 实现，
插件不能提供 HTML、JavaScript、任意 CSS、外链资源或远程依赖。

## 品牌有效来源

当前 manifest 使用 `uiContributions.contractVersion=2` 完整声明 Acme 固定品牌。Acme 当前
生效时，登录页、document title/favicon 和工作台左上角全部使用同一个插件 revision，不与
Host 标题、说明或 Logo 按字段混合。

插件活动期间，管理员仍可把 Host 默认品牌保存为备用配置；该保存不修改当前 Acme revision。
停用或取消选择 Acme 并重启 Admin API 后，Host 才发布最新备用品牌。切回 Host 不要求卸载
插件。Host 当前生效时，Host 保存后原子发布，无需重启；新开、刷新或重登页面使用新 revision。

字段契约、品牌覆盖优先级、原子快照生成和停用/卸载回退见
[《工作台品牌静态快照契约》](docs/工作台品牌静态快照契约.md)。

## 快速验证

环境要求：Node.js 20.11 或更高版本。

```bash
npm run verify
```

验证命令先使用 Phoenix Admin Node/Vue 的实际 ESLint 配置检查两端插件运行时，再检查
manifest、前后端入口、v2 完整静态品牌、资源字节/SHA/MIME、品牌配置一致性、首页路由、
静态 SVG、数据所有权，以及正式包的确定性与原子不覆盖行为。默认从相邻的
`../phoenix-admin-node` 与 `../phoenix-admin-vue` 读取 Host；CI 可通过
`PHOENIX_ADMIN_NODE_ROOT`、`PHOENIX_ADMIN_VUE_ROOT` 锁定其他 clean Host 根目录。

## 正式打包与安装

正式打包要求 Git 工作树 clean，并把 40 位源码 commit、Node/Vue payload、全文件大小与
SHA-256 一并写入不可变制品：

```bash
npm run package:build
npm run package:verify
```

默认输出：

```text
dist/admin-plugin/phoenix-branding-0.1.1.phoenix.cool
```

同一输入会生成相同包 SHA。构建器使用与目标同目录的临时文件和 hard link 原子发布；同名
目标或发布边界并发占用时安全失败，不覆盖既有字节。生产包不含测试、工具、`node_modules`
或 COOL Hook，只能交给 Phoenix Admin 的 Pah 声明式安装器。

在 `/phoenix/plugins` 选择该包后，按页面顺序完成校验装配、零 DDL dry-run、安装和启用，再
显式选择品牌并按提示受控重启 API。验证结束时先停用或取消选择并重启，确认 Host 备用品牌
恢复；是否卸载是独立验证动作。当前版本无业务表、实体、字典或迁移。

完整步骤与验收边界见[《正式制品与生命周期验收》](docs/正式制品与生命周期验收.md)。

## 开发挂载

1. 打开 Phoenix Hub 的“Admin 插件”。
2. 添加本仓库根目录，例如 Windows 下的 `E:\phoenix\phoenix-branding`。
3. 执行“开发挂载”，再启动 Phoenix Admin Vue 与 Node Host。
4. 按验证计划检查独立欢迎页、Host 品牌 DOM 未被插件运行时改写，以及宽窄屏和 console。

开发挂载只会在 Host 中创建被 Git 忽略的模块链接，不会选择正式品牌或用运行时伪造品牌
预览；登录页与工作台品牌必须由 Host 从已验证 contribution 生成快照。插件源码始终由本仓库
维护。详细的加载目录、装配边界与卸载恢复要求见下方文档。

## 项目结构

```text
phoenix-branding/
├── docs/                       # 装配说明与验证记录
├── packages/admin-plugin/
│   ├── manifest.json           # Phoenix Admin 插件清单
│   ├── midway/                 # 最小 Node 入口
│   └── vue/                    # 品牌运行时、欢迎页与静态资源
├── scripts/
│   ├── verify.mjs              # 清单与目录约束检查
│   └── lib/plugin-package.mjs  # 确定性打包与独立验包
└── test/                       # 品牌与正式包契约测试
```

## 兼容性

- Phoenix Admin Host：`>=0.2.2 <0.3.0`
- Phoenix Wing：`>=0.6.4 <0.7.0 || 0.7.2`
- 插件激活方式：重启后生效

其中 `0.7.2` 已通过 Phoenix Admin Host 的品牌健康检查，以及 Acme 登录页与工作台实际联调；
本范围不声明尚未验证的 Wing `0.8.x` 或其他版本。

## 文档

- [插件结构与装配点检](docs/插件结构与装配点检.md)
- [工作台品牌静态快照契约](docs/工作台品牌静态快照契约.md)
- [正式制品与生命周期验收](docs/正式制品与生命周期验收.md)
- [本地开发挂载验证计划](docs/本地开发挂载验证计划.md)
- [本地开发挂载验证记录](docs/本地开发挂载验证记录.md)

## 仓库与许可

正式仓库：[Gitee / phoenixwing / phoenix-branding](https://gitee.com/phoenixwing/phoenix-branding)

Copyright © 2024–2026 凤凰之翼（PhoenixWing）贡献者。项目使用
[Apache License 2.0](LICENSE) 开源。