24kycj
88c6ce8ccc
- 迁移为 frontend-web、frontend-electron、backend-web 与 docker 部署结构 - 网页端：订阅门禁二次弹窗、套餐/支付组件化、顶栏分组对齐 - 首页：最近文件与模板库布局优化，缩略图对齐，下载与删除操作 - 新增管理后台、支付与云端文件 API，更新 README 与项目规范 Co-authored-by: Cursor <cursoragent@cursor.com>
250 lines
9.5 KiB
Markdown
250 lines
9.5 KiB
Markdown
---
|
||
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：同上
|