技术栈规范(fmode-ng 平台版本基线)

定位:锁定 FmodeStudio 平台项目的工程版本基线。复制到项目后,在 CLAUDE.md「项目补充信息」记录实际版本与基线的差异及原因;升级走大版本评估流程(规则 4)。

负面清单(Do Not)

层	技术	基线
包管理	pnpm workspace monorepo	pnpm 11,单一 pnpm-lock.yaml(apps/* + packages/*)
前端	Angular(Standalone + Signals + OnPush)	Angular 20.x;样式 Tailwind 3.x(勿混用 Tailwind 4 语法与 @tailwindcss/postcss)
数据	fmode-ng + Parse Server + PostgreSQL	fmode-ng 最新稳定版安装后锁版本;parse-server 8.x(模式 B 自建时);PG 16(平台托管,用户不直接接触)
文件存储	NovaStorage(fmode-ng/core)	仅凭 cid 上传,无需关心七牛/OBS/S3
服务端	两类云函数 + api/ 模块 + Express	Parse Cloud Code(cloud/main.js)+ 动态云函数(fmode-functions-api),见 07-后端规范.md;Express 4.x(模式 B server.ts)
测试	前端 jest-preset-angular;后端 jest + supertest	jest 30.x
部署	模式 A 平台托管 / 模式 B PM2 + Nginx	pm2 5.x / nginx stable
AI 能力	DeepSeek / DashScope / 讯飞等	经动态云函数或 api/ 模块封装,见 07-后端规范.md

[必须] 数据访问统一 fmode-ng 封装:前端与后端统一通过 fmode-ng 访问数据——FmodeParse.initialize({config, appId, serverURL}) 仅初始化一次,其余位置 FmodeParse.with('dev') 取实例;禁止绕过封装裸调官方 parse SDK、禁止引入任何第三方 Parse 封装库。
[必须] 新增依赖审批:新增依赖必须向用户说明理由(解决什么问题/替代方案),经确认后安装;禁止顺手装库。
[必须] 依赖按需引入:体积大的库只引入用到的子模块(如 lodash-es 按需、FontAwesome 图标白名单),禁止全量 import。
[必须] 版本锁定与升级留痕:安装后锁版本;修复性升级可随改随更;大版本升级必须走 PRD/ADR 评估并留痕,禁止无评估升级。
[必须] 环境一致:本地/测试/生产依赖版本一致(单锁文件),禁止"本地能跑、生产报错"。
[必须] 测试生态版本配套(jest 30 起):jsdom 不再内置,前端测试须显式安装 jest-environment-jsdom;jest-preset-angular 17 以 jest-preset-angular/setup-env/zone 的 setupZoneTestEnv() 初始化(无 setup-jest 入口);新项目按上述配套配置,禁止照搬旧项目(jest 29 时代)配置。
[必须] 强制依赖清单(项目依赖以本清单为准,缺一不可;完整版本与用途登记用 templates/dependency-manifest-template.md):

依赖	用途	约束
fmode-ng	平台数据封装(前端+后端统一入口)	强制安装:`pnpm add fmode-ng`,安装后锁版本;禁止绕过(规则 1)
@angular/core 等 Angular 20.x	前端框架	版本基线锁定
tailwindcss 3.x	样式	勿混用 Tailwind 4 语法
官方 UI 组件底座(ui-kit)	前端组件唯一来源	包内 ui-kit\ 目录(src/app/ui + styles token + tailwind.config 映射),整目录复制使用,非 npm 依赖;复制步骤/依赖清单见 ui-kit\README使用说明.md;规范见 18-UI设计规范.md
@fortawesome/fontawesome-free 7.x	图标	免费 solid 图标,经底座 Icon 组件或 fa-solid 类使用;新增图标登记白名单,禁止全量 import(规则 3)
express / parse-server / pg-promise / cors / dotenv	模式 B 服务端	仅 apps/server;parse-server 8.x
jest / jest-preset-angular / jest-environment-jsdom / supertest	测试	jest 30.x,见规则 6
tsx / typescript(dev)	模式 B 运行 TS 与类型	仅 devDependencies
官方 parse SDK	数据访问底层	仅经 fmode-ng 使用,禁止直接依赖调用