[!info] related notes

governance-go-react项目技术架构文档

DailyUse 技术栈与架构设计规范

1. 核心架构原则

本项目采用 Nx Monorepo 架构进行前后端统一管理。核心设计思想如下：

• 后端 (Go)： 遵循 领域驱动设计 (DDD) 与整洁架构 (Clean Architecture)。业务逻辑与外部框架严格解耦，依赖由外向内倒置。
• 前端 (React)： 遵循 按功能特征划分 (Feature-Based / FSD)。数据流转采用函数式编程 (FP) 范式，状态与交互基于纯结构化数据 (POJO) 和纯工具函数，摒弃传统的 OOP 类实例，以实现极致的序列化与渲染性能。
• 前后端契约： 建立统一的 contracts 库，作为前后端交互的唯一真理来源 (Single Source of Truth)，沉淀 DTO 与 API 接口规范。

2. 技术栈清单

2.1 前端生态 (Frontend Stack)

模块	技术选型	核心职责与选型理由
核心框架	React + TypeScript	提供类型安全的视图层，契合纯数据驱动模型。
构建工具	Vite	极速冷启动与 HMR，提升开发体验。
状态管理	Zustand	轻量、无样板代码，专注存储结构化的全局数据快照。
数据同步	TanStack Query + Axios	承担服务端状态缓存、轮询、Token 拦截与数据去重。
路由管理	React Router	处理页面跳转与权限守卫 (Auth Guard)。
UI 组件库	Tailwind CSS + shadcn/ui	提效样式开发，组件源码级接入，高度可定制。
图表可视化	Recharts / ECharts	用于 Governance 模块的数据看板与趋势渲染。

2.2 后端生态 (Backend Stack)

模块	技术选型	核心职责与选型理由
核心语言	Go 1.21+	高并发、强类型，原生适合微服务与后端基建。
Web 框架	Gin	轻量级路由，中间件生态完善。
数据库	PostgreSQL	关系型存储主力，出色的 JSONB 支持，适合复杂规则配置。
ORM 框架	GORM	提供快速的数据持久化与 Schema 迁移能力。
认证加密	golang-jwt/jwt/v5 + bcrypt	JWT 无状态认证与高强度密码哈希。
配置管理	Viper	多环境 (Dev/Prod) 配置文件读取。

2.3 基础设施 (Infrastructure)

• Monorepo 管理: Nx (搭配 pnpm)
• 容器化: Docker + Docker Compose (本地环境一键拉起 PGSQL/Redis)
• 代码规范: golangci-lint (Go), ESLint + Prettier (TS/React)

---

3. 目录架构设计

项目整体拓扑结构分为 apps (宿主应用) 和 libs (业务/通用模块)。

Plaintext

dailyuse/
├── apps/
│   ├── backend/         # Go 启动入口 (main.go, 组装并注册 libs 中的各模块路由)
│   └── web/             # React 主应用 (仅包含全局 Provider, 路由配置与页面骨架)
│
├── libs/
│   ├── account/         # 🟢 Go: 用户核心领域 (User Entity, Profile)
│   ├── authentication/  # 🟢 Go: 认证领域 (Login, JWT 签发, Auth Middleware)
│   ├── governance/      # 🟢 Go: 治理领域 (代码规范校验, Webhook 处理)
│   ├── contracts/       # 🟡 Go/TS: 前后端契约 (DTO 结构体, API 响应统一格式)
│   └── app-react/       # 🔵 React: 前端物料库 (UI组件, 业务 Features, Hooks)
│
├── docs/                # 架构与技术文档 (如本文件)
├── docker-compose.yml   # 本地依赖服务编排
└── package.json / go.work

3.1 后端 DDD 模块分层结构 (以 libs/account 为例)

后端每个业务模块严格按照整洁架构进行四层拆分：

Plaintext

libs/account/
├── domain/               # 1. 领域层: 纯 Go 逻辑，定义实体 (Entity)、值对象 (VO) 与仓储接口
├── application/          # 2. 应用层: 核心业务流程与用例 (Use Case) 的编排
├── infrastructure/       # 3. 基础设施层: 仓储接口的具体实现 (如 GORM 接入)
└── interfaces/           # 4. 接口层: 处理 HTTP 请求与响应 (Gin Handler)

3.2 前端 FSD 模块分层结构 (libs/app-react)

前端摈弃类与实例，采用高度内聚的 Feature 目录结构：

libs/app-react/src/
├── components/           # 全局无状态 UI 组件 (Button, Modal 等)
├── features/             # 按业务领域划分的核心逻辑 (与后端界限上下文对应)
│   ├── auth/             # (例) 包含登录表单, useAuthStore, 专属 api 请求工具函数
│   ├── account/          
│   └── governance/       
├── services/             # 全局网络层拦截器与基础配置 (Axios Client)
└── utils/                # 纯数据处理的全局工具函数 (Formatters 等)