# frontendbackend **Repository Path**: BenKids/frontendbackend ## Basic Information - **Project Name**: frontendbackend - **Description**: Frontend and Backend Project - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2026-04-03 - **Last Updated**: 2026-11-05 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # frontendBackend 项目说明 多端协同的管理系统:**后端 + Web 前端 + 微信小程序 + 支付宝小程序**。 ## 项目概述 | 端 | 目录 | 技术栈 | |---|---|---| | 后端 | `project_backend` | 若依 RuoYi 基座 / Spring Boot / MyBatis / MySQL / Redis | | Web 前端 | `project_frontend` | Vue 3 + Vite + TypeScript / Element Plus / Pinia / Alova | | 微信小程序 | `project_wechat` | 原生小程序工程,无构建步骤 | | 支付宝小程序 | `project_alipay` | 原生小程序工程,无构建步骤 | 接口契约由后端 SpringDoc 自动生成,快照入库 `.agents/snapshot/openapi/`,由根目录 `alova.config.ts` 读取生成前端请求封装与类型,日常无需启动后端。 ## 环境要求 - JDK 25 - Maven 3.9+ - Node.js 20+(推荐 22 LTS) - MySQL 8.0+ - Redis 5.0+ - uv(提供 `uvx`,AI IDE 的 MySQL MCP 依赖)与 Node 自带的 `npx` ### IDE 扩展安装清单 | 扩展 | 说明 | |---|---| | Alova | 提供 Alova 请求库的语法提示与配置文件支持 | | Oxc | 基于 Oxlint / Oxfmt 的高速代码检查与格式化 | | Vitest | 运行与调试 Vitest 单元测试的集成面板 | | Auto Rename Tag | 同步修改成对 HTML / Vue 标签的开闭名称 | | Vue (Official) | Vue 3 的官方语言支持(类型检查、补全、调试) | | Language Support for Java(TM) by Red Hat | 提供 Java 代码的补全、导航、重构等语言能力 | | Debugger for Java | 在 IDE 中调试运行 Java 程序 | | Maven for Java | 浏览与执行 Maven 项目目标和依赖管理 | | Project Manager for Java | 管理 Java 工程的导入、构建与运行环境 | 可选扩展: | 扩展 | 说明 | |---|---| | Mermaid/Mermaid Viewer | 在 IDE 内实时预览 Mermaid 图表 | | Real Intellij Light | 提供接近 IntelliJ IDEA 的浅色主题 | | Playwright Test for VSCode | 网页自动化测试 | ## 目录结构 ``` frontendBackend/ ├── project_backend/ # 后端 Maven 多模块工程(启动模块 ruoyi-admin) ├── project_frontend/ # Web 前端工程 ├── project_wechat/ # 微信小程序(微信开发者工具导入) ├── project_alipay/ # 支付宝小程序(支付宝开发者工具打开) ├── sql/ # 数据库初始化脚本 ├── uploadPath/initial/ # 后端静态资源初始文件(登录背景 / 头像 / LOGO / 3D 模型) ├── docs/ # 项目认知图(mermaid)、编码现状(reference)、接口契约快照(openapi) ├── alova.config.ts # 接口与类型自动生成配置 ├── .agents/ # 多 IDE 统一的 AI 协作配置(rules / skills / agents / memory / scripts / plans) └── README.md ``` ## 项目初始化配置 首次拉起项目按下列顺序执行:AI IDE 配置 → 测试配置 → 数据库 → 后端 → 前端 → 小程序端 → 契约同步。 ### 1. AI IDE 配置 #### 1.1 CodeBuddy / Qoder MCP 配置 将仓库根目录下的 `.mcp.Example.json` 重命名为 `.mcp.json`,修改其中 `MySQL` 的 `MYSQL_HOST` / `MYSQL_PORT` / `MYSQL_USER` / `MYSQL_PASSWORD` / `MYSQL_DATABASE` 为本机数据库连接,并在 `Gitee` 的 `GITEE_ACCESS_TOKEN` 填入自己的 Gitee 访问令牌(CodeBuddy 与 Qoder 共用该文件)。`.mcp.json` 已被 `.gitignore` 忽略,只对本机生效。 #### 1.2 Trae MCP 配置 将 `.trae/mcp.Example.json` 重命名为 `.trae/mcp.json`,改动项与 1.1 相同(同样是本机文件,不入库)。 #### 1.3 规则与技能目录联接 三侧 IDE 的 `rules` / `skills` 是指向 `.agents/` 的目录联接(不入库),新环境需自行建立: | 联接路径 | 目标 | |---|---| | `.codebuddy/rules` | `.agents/rules` | | `.codebuddy/skills` | `.agents/skills` | | `.trae/rules` | `.agents/rules` | | `.qoder/rules` | `.agents/rules` | Windows 下用 `mklink /J <联接路径> <目标路径>` 建立(目录联接无需管理员权限)。Qoder 直接识别 `.agents/skills`(无需联接)。 三侧 agent 文件 `.codebuddy/agents/`、`.trae/agents/` 与 `.qoder/agents/` 已入库且为生成物:内容统一维护在 `.agents/agents/`(角色正文在 `agent-*.md`,公共节在 `_shared.md`,各侧 frontmatter 配置在同名 `agent-*.md` 的 `ides` 段);改完执行 `python .agents/scripts/common/gen_agents.py` 重建,`--check` 校验产物与源一致,产物不手改。三侧 hook 脚本共用 `.agents/scripts/**`,注册文件路径见 `.agents/hooks/hook-fields.md` 的「注册现状」节。 ### 2. 测试配置文件 把测试账号 `E2E_USERNAME` 与密码 `E2E_PASSWORD` 写入 `project_test/.env.e2e`(本地私有,不入库,优先于入库模板 `project_test/.env.e2e.example`;键集合与含义照抄模板)。`E2E_BASE_URL` 默认指向 `http://localhost:2333`,后端端口不同时一并修改。装载优先级与 SSO 免登凭据的就绪方式见 `.agents/snapshot/frontend/frontend-test-domain.md`。 ### 3. 数据库 1. 创建数据库 `ry-vue`(字符集 `utf8mb4`)。 2. 导入 `sql/ry-vue.sql`:含全部表结构与初始数据(菜单、字典、系统配置、默认账号等)。 3. 启动 Redis:登录验证码与令牌存储依赖 Redis,缺失时后端启动即报错。 ### 4. 后端 1. 修改 `project_backend/ruoyi-admin/src/main/resources/application-druid.yml` 中 `master` 数据源的 `url` / `username` / `password`,库名与第 3 步一致。 2. 修改 `project_backend/ruoyi-admin/src/main/resources/application.yml` 中的 Redis 连接与 `ruoyi.profile`(文件上传根目录)。 3. 准备静态资源:把仓库 `uploadPath/initial/` 整体放到 `ruoyi.profile` 指向的目录下(`/profile/**` 由该目录对外提供服务)。库内 `system_config` / `system_file` / `system_user` 按 `/profile/initial/...` 引用登录页背景、默认头像、IP 人物、LOGO 与 3D 模型,缺失时这些资源返回 404。 4. 首次启动前构建: ```bash cd project_backend mvn clean install -DskipTests ``` 5. 启动: ```bash mvn spring-boot:run -pl ruoyi-admin ``` 生产打包:`mvn clean package -DskipTests` 后 `java -jar ruoyi-admin/target/ruoyi-admin.jar`。 ### 5. 前端 1. 前端工程装依赖 ```bash cd project_frontend npm install ``` 2. 仓库根也需装一次依赖,E2E、契约与 lint / format 工具链来自根 `package.json`: ```bash cd .. npm install ``` 3. 可选测试:单元测试 `npm test`、组件测试 `npm run test:component`(首次需在 `project_frontend/` 下执行 `npx playwright install chromium`);E2E 在仓库根执行 `npm run test:e2e`(首次需执行 `npx playwright install`),有头可视化运行用 `npm run test:e2e:ui:headed`。 ### 6. 小程序端 - `project_wechat` / `project_alipay` 用各自开发者工具打开即可,无需安装依赖与构建。 - 将 `project_wechat/utils/config.js` 与 `project_alipay/utils/config.js` 中的 `baseUrl` 改为可访问的后端地址。 - 请求后端时配置合法域名,或在开发者工具中开启「不校验合法域名」。 - 使用自有小程序账号时,替换 `project_wechat/project.config.json` 的 `appid`;支付宝端在开发者工具中设置。 ### 7. 接口契约与类型重新生成 后端接口变更后,在仓库根目录执行 `python .agents/scripts/common/openapi_pull.py --auto`:脚本复用已在运行的后端,未运行时自动构建并启停,抓取并写入 `.agents/snapshot/openapi/` 契约快照(`openapi.json`、`groups.json`、`meta.json`)后重生成前端请求类型,输出「前端接口类型已同步」即完成。加 `--no-types` 时只刷新契约快照,不重生成类型。生成的文件在 `project_frontend/src/request`,请勿手改;业务二次封装写在 `project_frontend/src/assets/api`。 ## AI 工作流 本仓库采用「主 Agent 编排 + subagent 执行」的协作方式:主 Agent 只做需求澄清、规格落盘与任务转发,全部文件写入由对应 subagent 或编排层完成。 流程主干为 7 步 / 3 阶段: - **规格**:S1 需求澄清 → S2 规格落盘(加载 `req-prd` 一次产出 `.agents/plans/{模块标识}.md`,派发规格写在文件内 `dispatch` 段) - **执行**:S3 派发(随 prompt 只下发 `relevant_mermaid` 图路径清单)→ S4 并行产出(6 个 subagent 按写入范围各自产出代码 / 测试并回传 `*Changes`) - **收尾**:S5 派生刷新(契约快照 + 前端类型 + MSW 夹具 + 新鲜度自证)→ S6 事实层同步(`agent-fact-maintain` 统一更新 `.agents/snapshot/`)→ S7 收尾(`Stop` hook 聚合门禁 + 按模板汇报) 相关入口: - 协作约束、subagent 表与各自写入范围:`AGENTS.md` - 规则与技能:`.agents/rules/`、`.agents/skills/` - 各步职责与回退:[`AGENTS.md`](AGENTS.md) 的「执行流程(S1–S7)」;流程描述与资产归属规范:[`.agents/rules/AI工作流.md`](.agents/rules/AI工作流.md)、[`.agents/COLLABORATION.md`](.agents/COLLABORATION.md) - hook 事件与退出码:[`.agents/hooks/hook-fields.md`](.agents/hooks/hook-fields.md);门禁校验项与认知图维护:[`.agents/snapshot/SNAPSHOT.md`](.agents/snapshot/SNAPSHOT.md) ## E2E 测试工程(project_test) 根级独立工程,承载 web 端端到端测试(Playwright)。与 `project_frontend` 的 vitest 三层(纯逻辑 / 请求契约 / 组件行为)互不交叉:本工程只跑真实后端与真实浏览器关键用户路径(`ui` 工程)。 依赖统一由仓库根 `node_modules` 提供(无需在本目录安装),命令一律在**仓库根**执行。 ### 目录结构 ``` project_test/ ├─ playwright.config.mts # 工程配置(ES 模块制式,勿改回 .ts) ├─ package.json # 声明 ES 模块域(type: module;依赖由仓库根 node_modules 提供) ├─ e2e-run.ps1 # 编排脚本:日志汇总 / 失败明细 / 错误上下文 / 失败摘要自动生成 ├─ .env.e2e.example # 入库凭据模板(最低优先级) ├─ .env.e2e # 本地私有凭据(不入库,优先级高于模板;可选) ├─ fixtures/ │ ├─ env.ts # 环境与凭据装载 + 前端路由常量 │ ├─ auth/session.ts # 唯一 token 入口:快照读取 / 受控重建 / 浏览器会话注入 │ ├─ auth/ledger.ts # 跨进程会话台账(登记待登出的自建会话) │ ├─ auth/cleanup.ts # 枚举在线会话并强退、台账登出、会话基线 │ ├─ backend/client.ts # 后端请求封装(令牌 / 请求 / 登出 / 日志清理) │ ├─ backend/seed.ts # 岗位 / 用户 / 文件造数与按前缀清理 │ ├─ backend/sso.ts # 入站免登取票:服务间签名(HMAC-SHA256)调用 POST /sso/ticket │ ├─ ui/{auth,nav,collect,api-errors,console-errors}.ts # 登录登出、菜单导航与表格、瞬态提示采集、接口错误采集、控制台报错采集 │ ├─ globalSetup.ts # 先清账 → 建唯一主会话 → 预热前端 │ └─ globalTeardown.ts # 台账登出 + 枚举强退兜底 + 基线结论 ├─ ui/ # 真实浏览器关键用户路径(序号标定执行顺序,会话销毁型固定末位) ├─ data/ # 静态夹具(用户列表导入模板 xlsx) ├─ tools/cleanup.py # 独立清账入口(只清在线会话,不跑用例) ├─ tools/run-e2e.py # 仓库根 npm 跑测入口包装器:跑 Playwright + 自动生成失败摘要(退出码透传) ├─ tools/filter-failures.py # JSON 报告 → 失败用例极简 markdown 摘要(避免直读原始测试输出) └─ artifacts/ # report / results / trace(不入库) ``` ### 命令(仓库根) | 命令 | 说明 | | :------------------------------------------------------------------------ | :-------------------------------------------------- | | `npm run test:e2e` | 全量 E2E(ui),跑完自动生成失败摘要 | | `npm run test:e2e:ui` / `npm run test:e2e:ui:headed` | 仅 ui 工程(无头 / 有头),跑完同样自动生成失败摘要 | | `npm run test:e2e:cleanup` | 只清理 E2E 账号在线会话,不跑用例 | | `npm run test:e2e:summary` | 手动生成失败用例极简摘要(见下方「失败摘要」) | | `npm run typecheck:e2e` / `npm run lint:e2e` / `npm run format:e2e:check` | 工具链自证 | 三个跑测入口(`test:e2e` / `test:e2e:ui` / `test:e2e:ui:headed`)均经 `tools/run-e2e.py` 包装器执行:内部以 `npx playwright test --config=project_test/playwright.config.mts` 起测,Playwright 退出后(无论成败)自动调用 `filter-failures.py` 生成失败摘要,最终进程**以 Playwright 的退出码退出**(摘要生成异常仅打印一行告警,不改写退出码)。入口参数经 `npm run