# Production One-Click Deploy Frontend Implementation Plan

> **For agentic workers:** REQUIRED: Use superpowers:executing-plans to implement this plan in this repository. Do not use subagents. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 在不修改 `ruoyi-ui` 源码的前提下，补齐生产一键部署脚本中的前端静态包替换、旧版 `dist` 备份、`dist.zip` 解压验证和实施留痕。

**Architecture:** 本次前端交付不涉及 Vue 页面、接口契约或构建配置，而是通过 [bin/prod/deploy_from_package.sh](/Users/wkc/Desktop/loan-pricing/loan-pricing/bin/prod/deploy_from_package.sh) 管理发布目录中的 `frontend/dist.zip` 和 `frontend/dist/`。因此前端计划的重点是约束脚本里的静态包部署链路，验证旧 `dist` 目录时间戳备份、新 `dist.zip` 落盘和解压结果，并明确 `ruoyi-ui` 在本次任务中保持不变。

**Tech Stack:** shell、ZIP 静态资源包、`unzip`、`find`、`rg`

---

### Task 1: 确认本次任务无 `ruoyi-ui` 源码改动范围

**Files:**
- Inspect: `docs/superpowers/specs/2026-04-01-production-one-click-deploy-design.md`
- Inspect: `ruoyi-ui/src`
- Inspect: `ruoyi-ui/package.json`

- [ ] **Step 1: 核对设计文档中的前端交付边界**

Run: `rg -n "frontend/dist|dist.zip|不修改|不接入 Nginx|不新增外部配置文件" docs/superpowers/specs/2026-04-01-production-one-click-deploy-design.md`
Expected: 能看到本次前端范围只包含发布目录中的静态包替换和解压，不涉及 `ruoyi-ui` 工程改造。

- [ ] **Step 2: 检查前端源码中不存在需要同步修改的实现点**

Run: `rg -n "deploy_from_package|dist.zip|frontend/dist|生产一键部署" ruoyi-ui/src ruoyi-ui/package.json`
Expected: 无输出，说明 `ruoyi-ui` 不依赖本次部署脚本实现。

- [ ] **Step 3: 明确执行阶段不得改动 `ruoyi-ui`**

在执行笔记中写入以下约束：

```markdown
- 本次前端交付物是发布目录中的静态包部署链路
- 不修改 `ruoyi-ui` 下任何页面、接口、构建配置或打包脚本
- 如后续出现页面需求，必须回到新需求重新设计和计划
```

- [ ] **Step 4: 提交本任务**

```bash
git add docs/superpowers/plans/2026-04-01-production-one-click-deploy-frontend-plan.md
git commit -m "新增生产一键部署前端计划"
```

### Task 2: 在部署脚本中实现前端静态包发现与备份

**Files:**
- Modify: `bin/prod/deploy_from_package.sh`

- [ ] **Step 1: 实现前端 `dist.zip` 唯一校验**

补齐函数：

```sh
assert_single_dist_zip() {
    search_dir="$1"
    count=$(find "$search_dir" -type f -name 'dist.zip' | wc -l | tr -d ' ')
    if [ "$count" -ne 1 ]; then
        log_error "前端 dist.zip 数量不正确，期望 1 个，实际 $count 个"
        exit 1
    fi
    find "$search_dir" -type f -name 'dist.zip' | head -n 1
}
```

- [ ] **Step 2: 实现旧版前端 `dist` 时间戳备份**

补齐函数：

```sh
backup_frontend_dist() {
    if [ -d "$FRONTEND_DIST_DIR" ]; then
        mv "$FRONTEND_DIST_DIR" "$FRONTEND_DIR/dist-$(timestamp)"
    fi
}
```

- [ ] **Step 3: 实现新前端压缩包替换**

补齐函数：

```sh
deploy_frontend_archive() {
    source_dist_zip="$1"
    rm -f "$FRONTEND_DIST_ARCHIVE"
    mv "$source_dist_zip" "$FRONTEND_DIST_ARCHIVE"
}
```

- [ ] **Step 4: 做语法校验**

Run: `sh -n bin/prod/deploy_from_package.sh`
Expected: 无输出，返回码为 0。

- [ ] **Step 5: 提交本任务**

```bash
git add bin/prod/deploy_from_package.sh
git commit -m "实现生产部署脚本前端备份替换逻辑"
```

### Task 3: 在部署脚本中实现前端解压与结果校验

**Files:**
- Modify: `bin/prod/deploy_from_package.sh`

- [ ] **Step 1: 实现前端解压函数**

补齐函数：

```sh
deploy_frontend_dist() {
    dist_unpack_dir="$WORK_DIR/frontend"
    mkdir -p "$dist_unpack_dir"
    unzip -oq "$FRONTEND_DIST_ARCHIVE" -d "$dist_unpack_dir"
    rm -rf "$FRONTEND_DIST_DIR"
    mkdir -p "$FRONTEND_DIST_DIR"
    cp -a "$(resolve_frontend_source_dir "$dist_unpack_dir")"/. "$FRONTEND_DIST_DIR"/
}
```

要求同时实现 `resolve_frontend_source_dir()`，至少支持：

- 解压根目录直接包含 `index.html`
- 解压后为 `dist/index.html`
- 其他情况下用 `find` 定位第一个 `index.html`

- [ ] **Step 2: 将前端流程接入主执行顺序**

主流程至少补齐：

```sh
frontend_dist_source=$(assert_single_dist_zip "$WORK_DIR/package")
backup_frontend_dist
deploy_frontend_archive "$frontend_dist_source"
deploy_frontend_dist
```

- [ ] **Step 3: 检查脚本中已包含前端关键链路**

Run: `rg -n "assert_single_dist_zip|backup_frontend_dist|deploy_frontend_archive|deploy_frontend_dist|resolve_frontend_source_dir|frontend/dist.zip|frontend/dist" bin/prod/deploy_from_package.sh`
Expected: 能看到前端校验、备份、替换和解压函数都已落位。

- [ ] **Step 4: 做语法校验**

Run: `sh -n bin/prod/deploy_from_package.sh`
Expected: 无输出，返回码为 0。

- [ ] **Step 5: 提交本任务**

```bash
git add bin/prod/deploy_from_package.sh
git commit -m "实现生产部署脚本前端解压逻辑"
```

### Task 4: 用临时发布目录验证前端部署结果并留痕

**Files:**
- Modify: `bin/prod/deploy_from_package.sh`
- Create: `doc/implementation-report-2026-04-01-production-one-click-deploy-frontend.md`

- [ ] **Step 1: 构造临时前端发布目录做解压验证**

Run:

```bash
tmpdir=$(mktemp -d)
mkdir -p "$tmpdir/input/dist"
printf '<html>ok</html>\n' > "$tmpdir/input/dist/index.html"
(cd "$tmpdir/input" && zip -qr "$tmpdir/dist.zip" dist)
unzip -oq "$tmpdir/dist.zip" -d "$tmpdir/unpacked"
test -f "$tmpdir/unpacked/dist/index.html"
rm -rf "$tmpdir"
```

Expected: 命令执行成功，说明计划中的 `dist.zip -> frontend/dist` 解压链路可被临时目录复现。

- [ ] **Step 2: 再次确认 `ruoyi-ui` 未被纳入改动范围**

Run: `git status --short ruoyi-ui`
Expected: 无本次任务新增或修改的前端源码文件；如果有输出，必须先判断是否为历史遗留改动，不得误提交。

- [ ] **Step 3: 编写前端实施记录**

在 [doc/implementation-report-2026-04-01-production-one-click-deploy-frontend.md](/Users/wkc/Desktop/loan-pricing/loan-pricing/doc/implementation-report-2026-04-01-production-one-click-deploy-frontend.md) 至少记录：

```markdown
- 部署脚本中新增前端 dist.zip 唯一校验
- 旧版 frontend/dist 时间戳备份规则
- 新版 frontend/dist.zip 替换规则
- 前端静态资源解压到 frontend/dist 的实现方式
- 已确认 `ruoyi-ui` 本次无源码改动
- 执行的验证命令与结果
```

- [ ] **Step 4: 核对实施记录路径**

Run: `ls doc/implementation-report-2026-04-01-production-one-click-deploy-frontend.md`
Expected: 文件存在于仓库 `doc/` 目录。

- [ ] **Step 5: 提交本任务**

```bash
git add bin/prod/deploy_from_package.sh doc/implementation-report-2026-04-01-production-one-click-deploy-frontend.md
git commit -m "完成生产一键部署前端实现"
```