跳转至

L-20260822-02 DIP1 前端 monorepo 脚手架（5 端 + shared）

任务编号：L-20260822-02 / 执行人：听码 WDE / 日期：2026-08-22 任务来源：按 TND V2.0（D01 §二 C4 前端容器层）在 dip1/frontend/（空目录）全新搭建前端 monorepo

1. 任务起止与输入产物

  • 开始/完成：2026-08-22
  • 输入产物：
  • D01 系统总体架构设计 §二 C4 前端容器层（5 端划分）+ §四.1 端口分配
  • OpenAPI 契约：docs/技术文档/openapi/{qsv,cpt,mds,dis,ops}.yaml（类型对齐来源）
  • 约束：只写 dip1/frontend/；opr-admin 须 pnpm build 通过；KISS

2. 输出产物

2.1 workspace 根

  • pnpm-workspace.yaml（apps/ + packages/）、根 package.json、tsconfig.base.json、.gitignore、README.md

2.2 packages/shared（@dip1/shared）

  • client.ts：Dip1ApiClient（fetch 封装；baseURL env 注入；JWT bearer 自动携带；X-Internal-Secret 预留；ApiError 统一错误）
  • types/：5 服务核心类型 —— qsv（QuoteParams32/QuoteResult/Quote）、cpt（CptProject/ProjectStage 15 态/StageTransitionEvent/NpsFeedback/StageDistribution）、dis（DispatchOrder/DispatchAssignment/InsuranceClaim/ComboId）、mds（SclCategory/BplBuilding/WplWorker/CplCustomer/PplBrand）、ops（CockpitSummary/Campaign）
  • i18n/：zh-HK（默认）/ zh-CN / en 三语文案占位 + getMessages()

2.3 apps/opr-admin（Next.js 14.2 App Router，重点交付）

  • 登录页 /login：dev JWT 粘贴 → localStorage(dip1.jwt)，附 Keycloak dev token 获取说明
  • 驾驶舱 /dashboard：并行调 GET /api/v2/ops/cockpit/summary（COP1 8 指标卡）+ GET /api/v2/cpt/project/stats-8-stage-distribution（CPT20 8 阶段条形图）；含 loading / error（重试）/ 未登录（401/403 → 引导登录）三态降级
  • 侧边栏骨架布局：驾驶舱 / CPT / QSV / DIS / MDS / OPS 6 入口；后 5 个为占位页（标题 + 开发中 + 对应服务 OpenAPI 清单，统一 PlaceholderPage 组件）
  • 品牌样式：#004046 深青 + #D4AF78 金（globals.css）

2.4 其余 4 端骨架

  • apps/mfr-portal（Next.js 14，端口 3001）：首页 + 登录占位，声明对接 /api/v2/qsv/quote/mfr-open 等
  • apps/lgp-portal（Next.js 14，端口 3002）：首页 + 登录占位，声明对接 /api/v2/dis/lgp/*
  • apps/wkr-app（Expo SDK51 + RN 0.74，Metro 8081）：App.tsx 三屏占位（任务列表 WKR1 / L6 打卡 CPT8 / 拒单 WKR3）
  • apps/cst-app（Expo SDK51 + RN 0.74，Metro 8082）：App.tsx 两屏占位（项目进度 CPT2 / NPS 评价 COL8）

3. 验证结果

  • pnpm install：成功（web 三端 + shared，28 → 970 包两次安装）
  • pnpm --filter @dip1/opr-admin build：✅ 通过（Next.js 14.2.35，11 路由静态预渲染，dashboard 4.06 kB）
  • tsc --noEmit：shared / opr-admin / mfr-portal / lgp-portal 4 包全部通过
  • mfr/lgp 未跑 build（任务约定）；wkr/cst 未执行 install/build（任务约定）

4. 阻塞与决策点

  • .env.local.example 文件被敏感文件策略拦截 → 决策：不创建该文件，env 变量（NEXT_PUBLIC_API_BASE_URL）改写进 README「API 对接」节 + lib/api.ts 注释
  • tsconfig.base.json 初版带 declaration: true 导致门户 TS2742（跨包类型不可命名）→ 移除 declaration（脚手架无需产声明）
  • shared 以 TS 源码直出 + 各 Web 端 transpilePackages: ["@dip1/shared"]，免 shared 构建步骤（KISS）

5. 遗留事项

  1. Keycloak OIDC 正式登录流程（当前 dev token 手工粘贴）
  2. next-intl（Web）/ i18next（RN）正式接入，当前仅 shared/i18n 文案占位
  3. CPT/QSV/DIS/MDS/OPS 5 个占位页的实际业务页面开发
  4. RN 两端 install/build 与 expo-router 导航接入
  5. Sentry 前端错误采集（D01 ADR-014）未接入