SoonDesign/.cursor/skills/fullstack-delivery-workflow/SKILL.md

name, description

name	description
fullstack-delivery-workflow	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）

# progress.md

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

## 进度快照

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

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

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

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

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

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

# module-rollout.md

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

---

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

轨道A — 下一批提示词

执行轨道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 — 批次自检提示词

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

轨道B — 下一批提示词

执行轨道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 — 批次自检提示词

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

---

初始化 Checklist

[ ] 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：同上