fmode-app/templates/monorepo-scaffold-template.md

Monorepo 一键启动骨架模板(fmode 平台版)

用途:新建 FmodeStudio 平台项目时复制本骨架(pnpm workspace monorepo + 根脚本一键启动 + dev/prod 双环境 + 模式 A/B 目录统一)。目录职责与完整规则见 rules/03-项目架构与目录.md;两模式部署见 rules/10-安全与环境部署.md;平台铁律见 CLAUDE.md 黄金规则 5/6。 填写说明:<...> 为必填项,按项目实际情况替换后删除本行。

一、目录骨架

<project-root>/
├── pnpm-workspace.yaml
├── package.json                 # 根脚本(一键启动,见第三节)
├── .npmrc
├── .gitignore                   # node_modules/ dist/ config.json .env 等
├── .claude/                     # 项目规则与 hooks(复制 CLAUDE.md + rules/)
├── apps/
│   ├── web/                     # Angular 前端(见 rules/03 标准目录)
│   │   ├── src/app/
│   │   │   ├── app.routes.ts  app.config.ts  app.ts
│   │   │   ├── core/           # 单例服务/守卫/前端私有类型(FmodeParse 初始化唯一入口)
│   │   │   ├── shared/  layouts/  pages/<feature>/
│   │   ├── src/assets/data/     # Mock 数据 JSON(按实体命名)
│   │   ├── angular.json
│   │   ├── proxy.conf.json      # /parse /api → http://127.0.0.1:<server port>
│   │   └── package.json         # dependencies: fmode-ng(锁版本)
│   └── server/                  # 服务端(两模式目录统一:模式 A 上传此目录,模式 B 运行此目录)
│       ├── config.json          # Parse Server 配置(含 masterKey,**不入 git**,规则 10 第 1 条)
│       ├── server.ts            # 模式 B 入口(Express + Parse Server)
│       ├── api/
│       │   ├── routes.ts        # 桶文件
│       │   └── module/<feature>/routes.ts   # → /api/<feature>
│       ├── cloud/
│       │   ├── main.js          # Parse.Cloud.define / beforeSave / afterSave
│       │   └── providers/       # (可选)拆分模块
│       └── package.json         # dependencies: express parse parse-server pg-promise cors dotenv;dev: tsx
├── packages/
│   └── shared/                  # 前后端共享:类型/常量/枚举(workspace 协议引用)
│       └── src/models/  src/constants/
├── modules/                     # (可选)CDN 模块本地副本(如 fmode-functions-api)
└── docs/                        # 文档体系 + schema/ PlantUML 范式(rules/11、05)

二、工作区与配置

pnpm-workspace.yaml

packages:
  - apps/*
  - packages/*

根 package.json(一键启动核心)

{
  "name": "<project-name>",
  "private": true,
  "packageManager": "pnpm@11",
  "scripts": {
    "dev": "concurrently -n web,server -c cyan,green \"pnpm -F web dev\" \"pnpm -F server dev\"",
    "dev:web": "pnpm -F web dev",
    "dev:server": "pnpm -F server dev",
    "build": "pnpm -F web build",
    "start:prod": "pm2 start apps/server/ecosystem.config.js",
    "test": "pnpm -r test",
    "lint": "pnpm -r lint"
  },
  "devDependencies": {
    "concurrently": "^9"
  }
}

子包脚本约定

• apps/web:dev: ng serve --proxy-config proxy.conf.json;build: ng build --configuration production;test: jest;
• apps/server:dev: tsx watch server.ts;test: jest --runInBand。

三、开发模式与生产环境对照

维度	开发模式(pnpm dev)	生产环境
启动方式	concurrently 并行:web dev server + server 热重载(tsx watch)	模式 A:平台托管(fmode server start --config apps/server/config.json);模式 B:pnpm build + pnpm start:prod(PM2 + Nginx)
serverURL	指向本地 server(经 proxy.conf.json 代理)或平台测试实例	指向平台返回/生产 Parse Server 地址(仅初始化处一处)
Mock 开关	可开(rules/06 Mock 规范:一行开关切换)	必须关闭(发布前检查清单项)
鉴权	允许 dev-login(双重校验保证仅非 production 生效)	必须真实鉴权(rules/10 第 5 条双重校验)
构建	免构建,dev server 即时编译	ng build --configuration production(无 sourcemap、hash 文件名)
上传内容(模式 A)	—	apps/server(config.json/api/cloud)+ apps/web/dist

四、一键启动使用步骤

1. 复制本骨架到新项目根目录,执行 pnpm install(自动装 workspace 全部依赖,生成单一 pnpm-lock.yaml);
2. 删除子包遗留的 package-lock.json / yarn.lock;
3. 填 apps/server/config.json(appId/masterKey/databaseURI/serverURL/port/cloud),确认 .gitignore 已排除;
4. 开发:pnpm dev(一条命令起前后端);只起一端用 pnpm dev:web / pnpm dev:server;
5. 生产:模式 A 上传部署(规则 10 第 6 条);模式 B pnpm build → pnpm start:prod,Nginx 配置见规则 10 第 9 条;
6. 依赖管理:新依赖 pnpm -F <pkg> add <dep>(根依赖加 -w),fmode-ng 安装后锁版本(规则 04 第 4 条)。

五、验证清单(骨架落地后自检)

• pnpm install 一次成功,仅一个 pnpm-lock.yaml,无其他 lock 文件;
• pnpm dev 一条命令同时起前端与后端,页面能开、FmodeParse.initialize 生效;
• pnpm build 产物在 apps/web/dist 且无 .map 文件;
• pnpm test 递归跑通全部 workspace 测试;
• 前端无 masterKey;config.json 仅 apps/server/ 一份且未入 git;
• serverURL 仅在前端初始化处出现一次;建表由 FmodeSchema 完成,无手工建表要求(平台铁律)。