技术选型 & 工程规范

前端技术栈

项	选型	说明
框架	Vue 3 + TypeScript	官方推荐，生态成熟
构建工具	Vite	极速 HMR，秒级热更新
状态管理	Pinia	Vue 官方推荐，简洁类型安全
UI 组件库	Soybean Admin（后台）/ shadcn/vue（C端）	颜值高，TailwindCSS 驱动
样式	TailwindCSS v4	工具类优先
图表	ECharts	用量统计、趋势图
HTTP 请求	Axios + TanStack Query	请求 + 缓存
路由	Vue Router 4
表单校验	VeeValidate + Zod	类型安全

后端技术栈

项	选型	说明
语言	Go	高并发、编译型、单二进制部署
HTTP 框架	Gin	轻量高性能
ORM	GORM	Go 生态最成熟
主数据库	PostgreSQL	用户/实例/配额等结构化数据
审计日志	BigQuery	海量对话记录，低成本查询
缓存	Redis	Session、限流计数器
认证	GCP IAP JWT 验证	服务端校验 IAP 签发 JWT
消息队列	Google Pub/Sub	异步报警通知
API 规范	REST + OpenAPI 3.0	自动生成文档，前后端契约

基础设施

项	选型
云平台	GCP（Compute Engine + Cloud Run + IAP）
AI 节点	OpenClaw on GCP Japan（ai-jp-1 等）
API 代理	LiteLLM Proxy（Cloud Run 部署）
域名	sayclaw.ai（Cloudflare，Proxied CDN）
SSL	Let's Encrypt（certbot snap，自动续期）
CI/CD	GitHub Actions + Cloud Deploy

前端项目详细结构

C端（portal）

apps/portal/src/
├── pages/
│   ├── Dashboard.vue      # 我的 AI 助理列表
│   ├── Chat.vue           # 进入 OpenClaw WebChat
│   ├── Usage.vue          # 我的用量统计
│   └── History.vue        # 历史对话（只读）
├── components/
│   ├── InstanceCard.vue   # 小龙虾卡片
│   └── UsageBar.vue       # 用量进度条
└── stores/
    ├── auth.ts            # 用户 + JWT 状态
    └── usage.ts           # 用量数据

后台（admin）— 基于 Soybean Admin

apps/admin/src/
├── views/
│   ├── dashboard/         # 数据总览
│   ├── users/             # 员工管理（列表/详情/新增）
│   ├── instances/         # 实例管理
│   ├── usage/             # 用量报表（按人/按部门/趋势图）
│   ├── audit/             # 审计日志搜索
│   └── alerts/            # 报警规则配置
└── components/
    ├── UsageChart.vue     # ECharts 用量图
    └── StatusBadge.vue    # 状态标签

后端 API 路由

portal-api（C端，公网）

POST   /auth/verify              # 验证 IAP JWT
GET    /me/instances             # 我的 AI 实例列表
GET    /me/usage                 # 我的用量（今日/本月）
GET    /me/history               # 我的历史对话（分页）

admin-api（后台，内网）

GET    /users                    # 员工列表
POST   /users                    # 新增员工
PATCH  /users/:id                # 更新（含离职 revoke）
GET    /instances                # 实例列表
GET    /usage/user/:email        # 指定用户用量
GET    /usage/dept/:dept         # 部门汇总
GET    /audit/logs               # 审计日志（过滤/分页）
PUT    /alerts/rules/:id         # 更新报警规则

数据库设计（核心）

-- 员工表
CREATE TABLE users (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email           VARCHAR(255) UNIQUE NOT NULL,
    name            VARCHAR(100),
    department      VARCHAR(100),
    status          VARCHAR(20) DEFAULT 'active',
    quota_daily     BIGINT DEFAULT 100000,
    created_at      TIMESTAMPTZ DEFAULT NOW(),
    revoked_at      TIMESTAMPTZ
);

-- 实例绑定
CREATE TABLE user_instances (
    user_id         UUID REFERENCES users(id),
    instance_id     VARCHAR(100),
    PRIMARY KEY (user_id, instance_id)
);

-- 实例配置
CREATE TABLE instances (
    id              VARCHAR(100) PRIMARY KEY,
    name            VARCHAR(100),
    model           VARCHAR(100),
    endpoint        VARCHAR(255),
    department      VARCHAR(100),
    status          VARCHAR(20) DEFAULT 'active'
);