# 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**
```yaml
packages:
  - apps/*
  - packages/*
```

**根 package.json(一键启动核心)**
```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 完成,无手工建表要求(平台铁律)。