Peiqi Standards
绿色主题的软件工程系统抽象视觉

Modern Engineering Playbook

应用开发与设计规范

面向一系列业务应用的统一工程底座、设计语言与交付秩序。以绿色为主色， 追求清晰、克制、可靠和长期可维护。

TypeScript First API Contract Design Tokens Secure Delivery

Principles

先建立共同语言，再扩展应用矩阵

01

一致性优先

统一技术栈、目录结构、接口契约、设计令牌和发布流程，让每个应用像来自同一个产品体系。

02

可演进架构

从模块化单体起步，边界清晰后再拆分服务；避免为了“先进”而过早引入复杂度。

03

体验克制

界面以任务效率为核心，绿色表达品牌气质，布局、动效和文案都服务于可读性与信任感。

Technology Route

前后端技术路线

Frontend

Next.js + React + TypeScript

使用 Next.js App Router 承载门户、后台、轻应用与文档站。页面以服务端渲染优先， 交互复杂区块使用客户端组件。

  • UI：Tailwind CSS + Headless UI 或 Radix UI
  • 状态：TanStack Query 处理服务端状态，Zustand 处理局部客户端状态
  • 表单：React Hook Form + Zod
  • 图表：ECharts 或 Recharts，按业务复杂度选择
Backend

NestJS + Fastify + TypeScript

后端采用模块化架构，业务边界按领域拆分。默认 REST API，跨系统集成再引入事件和队列。

  • 接口：OpenAPI 生成契约与客户端类型
  • 数据：PostgreSQL + Prisma 或 Drizzle ORM
  • 缓存：Redis，用于会话、限流、热点数据
  • 任务：BullMQ 处理异步任务与重试
Platform

Docker + Nginx + CI/CD

所有应用容器化部署，Nginx 负责入口、HTTPS、压缩和静态资源缓存。CI 统一执行质量门禁。

  • 仓库：pnpm workspace + Turborepo 管理多应用
  • 质量：ESLint、Prettier、Stylelint、TypeScript strict
  • 测试：Vitest、Playwright、API contract tests
  • 监控：结构化日志、错误追踪、健康检查

Engineering Standard

开发规范

代码组织

推荐一个仓库承载多个应用和共享包，形成稳定的开发节奏： apps/web、apps/admin、apps/api、 packages/ui、packages/config、 packages/contracts。

业务模块按领域命名，例如 users、orders、 assets。模块内部保留 controller、service、repository、schema、 test 的固定结构。

接口契约

所有接口必须有 OpenAPI 或 Zod schema，前端类型由契约生成，禁止手写猜测响应结构。

错误模型

统一返回 code、message、details、requestId。

配置管理

环境变量集中校验，密钥不入库，不出现在前端构建产物与日志中。

数据迁移

数据库变更必须提交 migration，线上迁移先备份、后执行、可回滚。

类型检查 100% 关键路径测试 提交前格式化 主分支受保护 发布可回滚

Design System

绿色主题设计规范

颜色令牌

Forest 900#064E3B
Emerald 700#047857
Primary 500#10B981
Mint 300#6EE7B7
Paper#F6FBF8
Ink#17211D

字体与排版

中文优先使用系统黑体栈：PingFang SC、Microsoft YaHei、Noto Sans CJK SC。 英文与数字使用 Inter、SF Pro 或 Segoe UI。正文行高保持 1.7，标题行高保持 1.12。

Display / 56
Title / 32
Body / 16

界面组件

  • 圆角：按钮 8px，卡片 8px，输入框 8px，弹窗 12px
  • 阴影：只用于浮层和关键卡片，避免重阴影制造噪声
  • 按钮：主按钮绿色实底，次按钮白底绿边，危险操作使用红色独立语义
  • 表格：紧凑行高、固定表头、悬停行提示，批量操作靠近选择状态
  • 表单：标签左上，错误信息就近展示，必填项用文本标注而非只靠颜色

动效与状态

动效时长控制在 120ms 到 220ms，使用 ease-out。加载、空状态、成功、失败都要有明确反馈； 避免大面积闪烁、循环装饰动画和无意义的悬浮效果。

Success Warning Danger

Delivery Governance

交付与运维规范

Plan

需求进入前

明确目标、用户、边界、成功指标和风险；超过一周的功能拆成可独立上线的小交付。

Build

开发过程中

分支小步提交，PR 描述包含变更范围、截图、测试结果和回滚方式。

Release

发布上线时

使用灰度或低峰发布；上线后检查健康接口、错误日志、核心业务链路和资源占用。

Learn

迭代复盘后

沉淀组件、接口、脚本和经验，能复用的进入共享包，不能复用的写清楚边界。