---
name: fullstack-delivery-workflow
description: >-
  XENON 双轨交付工作流：Electron 客户端页+Mock（轨道 A）、FastAdmin 业务模块+联调（轨道 B）。
  含 progress 快照、模块签收表、四则固定提示词。配合 electron-vue2-architecture 与
  docs/api 契约使用。
---

# XENON 全栈开发工作流

## 与架构 Skill 分工

| Skill | 职责 |
|-------|------|
| electron-vue2-architecture | Electron 目录、HTTP、Mock、Sign、Vuex、域模块代码 |
| 本文 | 分批、自检、签收、progress 维护 |

执行顺序：读本文定轨道与批次 → 读 electron-vue2-architecture 写代码 → 批末门禁 → 只更新 progress 快照。

## 项目边界

| 项 | 路径 / 约定 |
|----|-------------|
| 后端 | `backend-xenon/`（FastAdmin · ThinkPHP） |
| 客户端 | Electron + Vue2 + Element UI（待建或 `client/` 目录） |
| API 契约 | `docs/api/客户端接口文档.md`、`docs/api/admin端接口文档.md`、`docs/api/数据库文档.md` |
| 总方案 | `docs/开发方案.md` |
| 本地联调 | `backend-xenon/scripts/start.bat` → Admin `8080`、MySQL `13306` |
| 同步 / 离线 | 非本工作流范围 |

接口 url「待复核」处：按业务语义找接口，**不擅自改**文档（见 `开发方案 §3.4`）。

## 双轨

| 轨道 | 单位 | Mock | 何时用 |
|------|------|------|--------|
| A | 1～3 页，同业务域 | `VUE_APP_USE_MOCK=true` | Electron UI + Mock、页契约 |
| B | 1 业务模块（该模块全部 path） | `hybrid` → `false` | 后端 Controller/Service/SQL + 客户端真服 + Admin |

推荐：轨道 A 阶段签收后再大规模 B；某模块 Mock 已稳可单模块直接 B。

## 模块 ID（P0 优先）

| ID | 名称 | 契约来源 |
|----|------|----------|
| M01 | 登录 / 鉴权 | 客户端 §1 + admin §1 |
| M02 | 权限中间件 | `开发方案 §6` |
| M03 | 行业 / 客户 / 工艺 / 产品类型 | admin 文档对应章节 |
| M04 | 产品 + 媒体 | admin + 客户端产品相关 |
| M05 | admin 用户与角色 | admin RBAC |
| M06 | 客户端用户 | admin 客户端用户 + 客户端登录 |
| M07 | 标题简介 | admin + 客户端 |
| M08 | 客户端列表 / 详情 | 客户端文档 |
| M09 | 浏览历史 / 缓存 | 客户端文档 |
| M10 | 导入 / 导出 | admin + 客户端 |

## Agent 执行协议

1. 读 `docs/progress.md`「进度快照」。
2. 「下一批」→ **原样复制**对应轨道「下一批提示词」；「自检」→ 复制「批次自检提示词」。
3. 禁止改写四则提示词正文（用户明确要求改版除外）。
4. 回复首段：`本批：…` 或 `自检：…`。
5. 先 todos → 执行 → 批末门禁 → **只改 progress 快照**（rollout 勾选除外）。
6. 冲突时：`docs/module-rollout.md` 优先，与快照「建议下一批」交叉核对。

## 轨道 A — 单批（7 步）

1. 从 `docs/api/客户端接口文档.md` 确认 path、method（禁止自造）。
2. `modules/<域>/types.ts`
3. `modules/<域>/api.ts` + `service.ts` + `mock.ts` + `index.ts`
4. `mock/v1/<资源>/<action>.json`
5. `views/<域>/<Page>.vue` + `composables/useXxx.ts`（仅 import service）
6. `router/modules/<域>.ts` 挂 `DefaultLayout` children
7. 批末：`npm run typecheck`；本批 path 已在 mock 覆盖

### 单页 DoD

- UI 可导航，主流程可点。
- 域五件套：types、api、service、mock、view。
- mock 响应 `{code,msg,data}` 与 FastAdmin 约定一致（成功 `code=1`）。
- 页面无 import api/mock、无 axios 裸调。

### 阶段 A 签收（切入 B 前置）

| # | 条件 |
|---|------|
| 1 | 计划内客户端页契约全覆盖 |
| 2 | 声明 path ⊆ mock/v1 或 service 覆盖 |
| 3 | `npm run typecheck` PASS |
| 4 | `npm run dev:web` 或 `dev:electron` 可启动 |
| 5 | 主流程手测 5～7 条（登录 → 列表 → 详情） |

## 轨道 B — M-Batch（5 步）

| 步 | 内容 | DoD |
|----|------|-----|
| ① 契约 | mock + types + `docs/api` 字段对照 | mock JSON ≡ types ≡ 将实现响应 |
| ② 后端 | `application/api`（客户端）+ `application/admin`（后台）薄 Controller + Service + 迁移/SQL | 本模块 path curl **0 fail**（Docker 8080） |
| ③ Admin | FastAdmin 菜单/权限 + CRUD 页；**复用** Service | 无需求标 N/A，rollout Admin 列写 — |
| ④ hybrid | `config/mock-routes.ts` REAL_ROUTES 登记 | 抽测 1～3 条主路径 |
| ⑤ 签收 | rollout 勾选 + 更新快照 | 本行 客户端/后端/manifest/抽测已勾 |

### 模块 DoD

- 五步完成；本模块 curl 0 fail；mock 与真服形状一致（差异记入 rollout 备注）。

## Mock 三档

| VUE_APP_USE_MOCK | 行为 |
|------------------|------|
| true | 全 mock |
| hybrid | REAL_ROUTES 命中 → 真 API；未命中 → mock |
| false | 全真服 |

Mock / hybrid-mock **不发送**签名 Header。

## 批末命令（项目现状）

| 轨道 | 每批 | 里程碑 |
|------|------|--------|
| A | `npm run typecheck` | + `dev:electron` 冒烟 |
| B | 本模块 curl 清单 0 fail | + hybrid 抽测 + `typecheck` |

后端抽测示例：`curl -X POST http://127.0.0.1:8080/api/...`（带 Bearer / Sign 按 `.env`）。

## 模块签收表（rollout）

| 列 | 含义 |
|----|------|
| 模块 ID | M01…M10 |
| 名称 | 业务模块 |
| API 数 | 本模块 path 数 |
| 客户端 | Electron 页/service 已实现 |
| 后端 | api/admin Controller 已实现 |
| Admin | FastAdmin 后台（— 表示 N/A） |
| manifest | REAL_ROUTES 已登记 |
| 抽测 | hybrid 主路径通过 |
| 签收日期 | |

首个未签收：客户端 / 后端 / manifest / 抽测 任一未勾。

## 自检 vs 下一批

| | 自检 | 下一批 |
|---|------|--------|
| 目的 | 验 DoD | 实现新一批 |
| 首段 | `自检：…` | `本批：…` |
| 写代码 | 否（补漏除外） | 是 |
| 改 progress | 仅快照 | 快照 + rollout |

## 禁止

- 改 progress 内四则提示词（用户明确要求除外）
- 自检重复实现整批
- 无模块 ID / 无域边界空回归
- 未登记 REAL_ROUTES 即宣称模块完成
- api Controller 与 admin Controller 各写一套重复业务逻辑
- 未读 `docs/api` 猜字段
- 跨域同批大改
- 页内 mock 数据或散落 HTTP
- 擅自修改 API 文档「待复核」url

---

## progress.md 模板（`docs/progress.md`）

```markdown
# progress.md

> Agent 只改「进度快照」；勿改下方四则提示词。

## 进度快照

| 项 | 填写 |
|----|------|
| 更新日期 | |
| 当前轨道 | A / B |
| 当前模块/域 | |
| 建议下一批 | |
| 本批已完成 | |

## 轨道A — 批次自检提示词
（粘贴 SKILL 对应代码块全文）

## 轨道A — 下一批提示词
（粘贴 SKILL 对应代码块全文）

## 轨道B — 批次自检提示词
（粘贴 SKILL 对应代码块全文）

## 轨道B — 下一批提示词
（粘贴 SKILL 对应代码块全文）
```

## module-rollout.md 模板（`docs/module-rollout.md`）

```markdown
# module-rollout.md

| ID | 名称 | API数 | 客户端 | 后端 | Admin | manifest | 抽测 | 签收日期 | 备注 |
|----|------|-------|--------|------|-------|----------|------|----------|------|
| M01 | 登录鉴权 | | | | | | | | |
```

---

## 四则提示词（固定正文，写入 progress.md）

### 轨道A — 下一批提示词

```text
执行轨道A下一批（Electron 页+Mock）。先建 todos。须配合 electron-vue2-architecture。自判：读 progress「建议下一批」；无则从 docs/api/客户端接口文档.md 取同域未实现页，每批 1～3 页。首段「本批：轨道A <域> <页名>」。① docs/api 定 path ② modules/<域>/{types,api,service,mock,index} ③ mock/v1/*.json ④ views/<域>/*.vue + composable ⑤ router/modules/<域>.ts。批末 npm run typecheck。禁跨域同批、禁页内 axios/mock、禁自造 API。只改 progress 快照。
```

### 轨道A — 批次自检提示词

```text
轨道A自检本批。先建 todos。自判：本对话刚完成页优先，否则读快照「当前模块/域」。首段「自检：轨道A <域> <页名>」。核对：域五件套齐全；本批 path mock 已覆盖；页面仅 import service；主路径 mock 可点。批末 npm run typecheck。只改 progress 快照。
```

### 轨道B — 下一批提示词

```text
执行轨道B M-Batch。先建 todos。须配合 electron-vue2-architecture + backend-xenon。自判：读 progress + module-rollout + docs/api；按 M01→M10 取首个未签收（客户端/后端/manifest/抽测未全勾）。首段「本批：Mxx <名>」。① 契约：mock+types 对照 docs/api ② backend-xenon Controller+Service+SQL，本模块 curl 0 fail ③ FastAdmin Admin（N/A 写 —）④ config/mock-routes REAL_ROUTES + hybrid 抽测 1～3 条 ⑤ rollout 勾选+快照。禁无模块 ID、禁未 manifest 即完成、禁重复 Service 逻辑。只改 progress 快照。
```

### 轨道B — 批次自检提示词

```text
轨道B M-Batch 自检。先建 todos。自判：本对话模块优先，否则读快照+rollout 对应行+docs/api。首段「自检：Mxx <名>」。核对：mock/types 与 Service 响应一致；本模块 curl 0 fail；Admin 复用 Service 或 N/A；REAL_ROUTES 已登记；rollout 本行已勾。只改 progress 快照。
```

---

## 初始化 Checklist

```text
[ ] docs/progress.md（快照 + 四则提示词）
[ ] docs/module-rollout.md（M01～M10 空表）
[ ] 客户端工程按 electron-vue2-architecture 初始化
[ ] backend-xenon/scripts/start.bat 可启动
[ ] .env：VUE_APP_API_BASE=http://127.0.0.1:8080
[ ] 首批：M01 或轨道 A 登录页，更新 progress 快照
```

## 非琐碎开发勾选

- 轨道 A：`electron-vue2-architecture` + `fullstack-delivery-workflow`
- 轨道 B：同上