# uctoo

**Repository Path**: uctoo/uctoo

## Basic Information

- **Project Name**: uctoo
- **Description**: UCToo是一套AI驱动的全栈应用开发基础设施。采用开源、通用、厂商中立的技术选型。内置众多开发者效率工具，可快速进行全栈应用的开发和运营，适合作为CMS、APP、小程序等产品的起始项目。V3.0版支持多端一致的ORM模型及API代码生成。已支持鸿蒙原生应用等最新技术体系。
- **Primary Language**: PHP
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 479
- **Forks**: 176
- **Created**: 2014-09-23
- **Last Updated**: 2026-04-17

## Categories & Tags

**Categories**: lowcode

**Tags**: TypeScript, ArkTS, UMI

## README

# UCToo Web Admin

UCToo Web Admin 是 UCToo v4 管理后台的 PC 前端项目，基于 Vue 3 + TypeScript + OpenTiny Vue 构建。采用 UMI 全栈模型同构架构设计，实现了前后端数据模型同构、状态管理同构、API 调用同构。

## 项目简介

本项目采用monorepo项目结构，使用pnpm进行包管理，包含以下主要部分：
- 前端应用 (web-admin/web)
- 后端服务 (web-admin/nestJs)
- 核心组件库和工具包 (packages目录)

系统提供了CMS内容管理、用户权限管理、AI智能体应用等多个功能模块，适用于各类企业级应用场景。

## AI驱动的全栈开发框架最佳实践    
1. **统一技术栈原则**：优先采用可支持一致技术栈实现全平台应用开发的编程语言，便于应用统一的编程规范和降低AI学习成本。  
2. **Monorepo架构优化**：采用monorepo组织工程的代码管理方案，便于AI IDE及大模型全面获取工程信息，实现更精准的代码生成。 
3. **CLI友好设计**：开发框架功能均可通过CLI命令行工具实现，便于与AI IDE及大模型的集成和互操作，支持自动化工作流。  
4. **AI Native原则**：原生智能化、天生全场景、高性能、强安全，符合AI Native的发展趋势，内置AI增强功能。  
5. **模型同构规范**：遵循UMI全栈模型同构规范，为确定性代码生成和AI辅助代码生成提供良好基础设施。  
6. **AI生态集成**：支持MCP、AgentSkills、WebMCP等AI生态主流协议和开发范式，确保与主流AI工具链的兼容性。

``` markdown 
added by TRAE+SeepSeek R1
7. 建立AI代码生成质量评估体系，通过单元测试覆盖率（≥85%）和SonarQube静态扫描保障代码质量
8. 实现CI/CD全流程AI辅助，使用AI生成测试用例并自动执行流水线（如GitHub Actions/Jenkins）
9. 内置MLOps基础设施，支持模型版本管理（MLflow）和AI服务监控（Prometheus+Grafana）
10. 强化AI安全规范，遵循OWASP AI安全指南，实施RBAC权限控制和数据脱敏处理
11. 构建知识图谱驱动的开发文档体系，实现API文档与代码实时同步（Swagger/Redoc）
12. 采用微服务化AI能力部署，通过Service Mesh（Istio）实现AI服务动态编排
13. 建立多维度可观测体系，集成日志分析（ELK）、链路追踪（Jaeger）和异常检测（AIops）
14. 实施用户体验量化管理，通过AB测试平台（Optimizely）和埋点分析（Mixpanel）持续优化
15. 构建开发者社区生态，建立RFC提案机制和Contribution GPT代码审查助手
补充实践着重于：

- AI代码生成的质量保障体系
- 智能化运维监控能力
- 开发者体验持续优化机制
- 安全合规的AI服务部署
- 开放协同的社区生态建设
```

``` markdown 
added by CodeBuddy+GPT-5 
7. 人机协同开发流程
以“人设目标、AI产草稿、人做评审与合并”为主线，定义每次迭代的验收标准和回滚策略。
复杂任务拆小步，给AI明确上下文、边界条件与评估口径，避免一次性超大变更。
统一的代码与提示工程规范
8. 统一编码规范、提交规范(Commitlint)、分支策略、目录结构；在仓库中提供“提示词模板与负样例库”，约束AI生成风格与安全边界。
为常见任务（CRUD、表单校验、权限门禁、接口封装）提供可复用Prompt Snippet。
9. 可测试的AI产出
单测/集成测试/契约测试覆盖AI生成模块，优先对数据模型、API契约、权限与幂等性做测试。
引入快照测试防回归，针对AI易变区域（UI渲染、文案、多语言）设置基线。
10. 强化安全与合规
对AI生成代码做SAST/DAST/依赖漏洞扫描；引入Secrets扫描与生成阶段密钥屏蔽。
后端默认零信任：鉴权在网关/中间件层，最小权限访问；对AI调用外部包做来源校验与许可证合规检查。
11. 数据与隐私治理
敏感数据最小化出境：提示词脱敏与分级；训练或微调使用脱敏样本。
设计“数据可追溯”链路：从需求-提示-生成-上线全链路留痕，满足审计与复现。
12. 观测与可解释性
接入日志、指标、分布式追踪；对AI相关关键路径做埋点（提示长度、模型版本、延迟、错误率）。
对生成结果提供“决策依据”或“来源链接”，便于人工复核与故障排查。
13. 依赖与模型版本治理
明确模型与依赖的版本矩阵；设灰度/金丝雀发布策略，允许按项目/环境快速切换模型。
给AI工具链（代码生成器、Lint、格式化器）也做版本锁定与变更日志。
14. 领域模型优先与契约驱动
先固化Domain Model与API契约，再驱动AI生成实现与前后端类型；用OpenAPI/JSON Schema/Protobuf做单一事实源。
通过代码生成器在多端同步类型，减少手写与漂移。
15. Prompt 即基础设施
将高价值Prompt抽象为“可测试、可发布、可版本化”的资源（如以文件/配置管理），支持回滚与A/B。
为关键Prompt建立性能基准与质量门槛（正确率、覆盖率、延迟）。
16. 人工评审与自动质量闸
在CI中设质量闸：静态检查、测试覆盖、Bundle大小、性能阈值、可访问性分数。
关键变更（安全、支付、数据导出）必须双人评审；AI建议仅作参考，不可越权合并。
17. 开发者体验与脚手架
提供一键初始化脚手架：内置目录规范、环境变量模板、示例Prompt、测试与CI配置。
常见业务基元（列表-详情、搜索-分页、表单-校验、权限-菜单）沉淀为可复用蓝图供AI调用。
18. 渐进式引入与风险控制
从低风险区域开始引入AI（文档、测试、样式、重复性脚本），逐步扩展到核心业务。
为AI生成变更设置隔离分支与特性开关；关键路径保留人工Fallback。
19. 性能与成本优化
在前端采用增量编译、按需加载、边缘缓存；在后端引入连接池、批处理、幂等重试。
对AI调用做缓存与去重；统一计费与用量监控，设超额预警与熔断策略。
20. 多环境一致性与基础设施即代码
Dev/Staging/Prod 配置分离且可追溯；用IaC（如Terraform）管理云资源与权限。
数据库迁移（如Prisma/Knex/Flyway）与Seed数据自动化，确保环境可复现。

```

``` markdown 
added by Qoder
新增的9条最佳实践：
提示词工程化 - 内置结构化提示词模板，提高AI代码生成准确度
代码即文档 - 自描述的代码结构，便于AI理解和维护
渐进式AI增强 - 支持平滑过渡到AI辅助开发
智能依赖管理 - 自动优化依赖关系，减少冲突
上下文感知生成 - 基于项目上下文生成一致性代码
多模态支持 - 支持多种输入形式的AI交互
持续学习机制 - 建立项目级别的AI优化反馈循环
安全第一原则 - 内置安全代码模式和漏洞检测
可解释性设计 - AI生成代码包含决策路径，便于理解和维护
这15条最佳实践涵盖了：
技术架构层面：统一技术栈、Monorepo、CLI友好设计
AI集成层面：AI Native、生态集成、提示词工程
开发体验层面：渐进式增强、上下文感知、多模态支持
质量保障层面：持续学习、安全优先、可解释性
维护性层面：代码即文档、智能依赖管理

```

## 技术栈

- **前端框架**: Vue 3.5+ + TypeScript
- **UI组件库**: OpenTiny Vue 3.28+
- **状态管理**: Pinia 2.1.7 + Pinia ORM 1.10.2
- **HTTP 客户端**: Axios 1.7.9
- **构建工具**: Vite / Webpack / Rspack / Farm
- **路由**: Vue Router 4.4.5
- **国际化**: Vue I18n 11.0.0
- **AI 集成**: @opencangjie/skills SDK + WebMCP SDK
- **包管理器**: pnpm

> **注：** web-admin 目录中的 nestJs 后端服务仅用于 start-installer.bat 快捷安装过程，实际支撑 web 端业务的服务器端 API 均由 agentskills-runtime 提供。

## 项目结构

```
uctoo-admin/
├── apps/
│   ├── web-admin/           # Web管理后台
│   │   ├── nestJs/          # NestJS 后端服务
│   │   ├── web/             # Vue 前端项目
│   │   │   └── node_modules/@opencangjie/skills/dist/runtime/win-x64/release  # Agent Skills Runtime 发布包（通过SDK安装）
│   │   └── start-installer.bat # 一键安装启动脚本
│   ├── agentskills-runtime/ # Agent Skills 运行时 （开发环境）
│   ├── miniapp/             # 小程序端
├── scripts/                 # 脚本
├── .gitignore
├── package.json
├── pnpm-lock.yaml
├── pnpm-workspace.yaml
└── README.md
```

### 目录说明

- **apps/web-admin/web/node_modules/@opencangjie/skills/dist/runtime/win-x64/release**：Agent Skills Runtime JavaScript SDK 安装的运行时发布包，包含编译后的可执行文件和依赖，用于生产环境运行。
- **apps/agentskills-runtime**：Agent Skills 运行时的开发环境，包含源代码和开发配置。

## 安装使用

### 方式一：一键安装（推荐）

Windows 用户可直接运行安装脚本：

```bash
# 克隆项目
git clone https://gitee.com/uctoo/uctoo.git
cd uctoo/apps/web-admin

# 运行安装助手
start-installer.bat
```

安装助手会自动：
1. 检查 Node.js 环境
2. 安装前后端依赖
3. 启动后端服务（端口 3000）
4. 启动前端服务（端口 3031）
5. 打开浏览器进入安装向导

### 方式二：手动安装

#### 环境要求

- Node.js >= 14.0.0
- pnpm 或 npm

#### 安装步骤

1. **安装后端依赖**
```bash
cd apps/web-admin/nestJs
pnpm install
```

2. **安装前端依赖**
```bash
cd apps/web-admin/web
pnpm install
```

3. **配置环境变量**

复制 `.env.example` 为 `.env`，并根据实际情况修改：

```env
# 应用上下文
VITE_CONTEXT=/vue-pro/

# API 基础路径
VITE_BASE_API=/api

# 后端服务地址
VITE_SERVER_HOST=https://javatoarktsapi.uctoo.com
VITE_BACKEND_URL=https://javatoarktsapi.uctoo.com

# 构建输出目录
VITE_OUT_DIR=../dist
```

4. **启动后端服务**
```bash
cd apps/web-admin/nestJs
pnpm run start:dev
```

5. **启动前端服务**
```bash
cd apps/web-admin/web
pnpm run dev
```

6. **访问应用**

打开浏览器访问 http://localhost:3031

## 核心特性

### 1. UMI 全栈模型同构

数据模型定义在 `apps/web-admin/web/src/store/models/uctoo/` 目录下，每个模型同时定义数据结构和 API 调用方法：

```typescript
// src/store/models/uctoo/uctoo_user.ts
import { Model } from 'pinia-orm';
import { useAxiosRepo } from '@pinia-orm/axios';

export class uctoo_user extends Model {
  static override entity = 'uctoo_user'

  @Uid() declare id: string
  @Str('') declare email: string
  @Str('') declare name: string
  // ... 其他字段

  static override config = {
    axiosApi: {
      actions: {
        // 列表查询
        getUctooUserList(page: number, pageSize: number, searchParams?: any) {
          return useAxiosRepo(uctoo_user).api().get(
            `/api/v1/uctoo/uctoo_user/${pageSize}/${page}`, {
              params: searchParams,
              dataKey: 'uctoo_users'  // 分页数据键名
            }
          )
        },
        // 单条查询
        getUctooUser(id: string) {
          return useAxiosRepo(uctoo_user).api().get(`/api/v1/uctoo/uctoo_user/${id}`)
        },
        // 新增
        addUctooUser(data: any) {
          return useAxiosRepo(uctoo_user).api().post('/api/v1/uctoo/uctoo_user/add', data)
        },
        // 编辑
        editUctooUser(data: any) {
          return useAxiosRepo(uctoo_user).api().post('/api/v1/uctoo/uctoo_user/edit', data)
        },
        // 删除
        deleteUctooUser(data: any) {
          return useAxiosRepo(uctoo_user).api().post('/api/v1/uctoo/uctoo_user/del', data)
        },
        // 登录
        login(data: { email?: string; username?: string; password: string }) {
          return useAxiosRepo(uctoo_user).api().post('/api/v1/uctoo/uctoo_user/signin', data)
        }
      }
    }
  }
}
```

### 2. 同构状态管理使用示例

```vue
<script setup>
import { useAxiosRepo } from '@pinia-orm/axios'
import { uctoo_user } from '@/store/models/uctoo/uctoo_user'

// 获取用户列表
const fetchUsers = async () => {
  const res = await useAxiosRepo(uctoo_user).api().getUctooUserList(1, 10)
  // 数据自动存入 Pinia ORM store
  const users = useAxiosRepo(uctoo_user).all()
}

// 登录
const handleLogin = async (formData) => {
  const res = await useAxiosRepo(uctoo_user).api().login(formData)
  if (res.data.errno === '0') {
    // 登录成功
  }
}
</script>
```

### 3. AI 智能体集成

项目内置 AgentSkills Runtime JavaScript SDK，支持 AI 智能体功能：

- 自然语言数据库查询
- AI 辅助表单填写
- 智能数据分析

## 开发规范

### UMI 同构模型开发规范

1. **模型定义位置**：所有数据模型定义在 `src/store/models/uctoo/` 目录
2. **模型命名**：使用小写下划线命名，如 `uctoo_user`、`sys_config`
3. **API 方法命名**：采用 `动作+模型名` 格式，如 `getUctooUserList`、`addUctooUser`
4. **dataKey 配置**：
   - 分页接口：使用实体复数形式，如 `uctoo_users`、`uctoo_roles`
   - 非分页接口：使用 `data`
5. **Human-Code Preservation**：自定义代码写在 `//#region Human-Code Preservation` 区域内，避免被生成器覆盖

### 页面开发规范

1. **使用组合式 API**：`<script setup lang="ts">`
2. **状态管理**：优先使用 Pinia ORM 模型，而非传统 Pinia store
3. **API 调用**：通过模型层的 `useAxiosRepo(Model).api().方法名()` 方式调用
4. **类型定义**：所有数据类型使用 TypeScript 严格定义

## 构建部署

### 开发构建

```bash
cd apps/web-admin/web

# Vite 开发服务器
pnpm run dev

# 或指定端口
pnpm run start
```

### 生产构建

```bash
cd apps/web-admin/web

# Vite 生产构建
pnpm run build

# Webpack 构建
pnpm run build:wp

# Rspack 构建
pnpm run build:rp

# Farm 构建
pnpm run build:fr
```

### 构建输出

构建后的文件位于 `apps/web-admin/web/dist` 目录，可部署到任意静态服务器。

## Git 贡献提交规范

- `feat` 增加新功能
- `fix` 修复问题/BUG
- `style` 代码风格相关无影响运行结果的
- `perf` 优化/性能提升
- `refactor` 重构
- `revert` 撤销修改
- `test` 测试相关
- `docs` 文档/注释
- `chore` 依赖更新/脚手架配置修改等
- `ci` 持续集成
- `types` 类型定义文件更改
- `wip` 开发中

## 浏览器支持

本地开发推荐使用`Chrome 80+` 浏览器

支持现代浏览器, 不支持 IE

| [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/edge/edge_48x48.png" alt=" Edge" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)</br>IE | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/edge/edge_48x48.png" alt=" Edge" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)</br>Edge | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/firefox/firefox_48x48.png" alt="Firefox" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)</br>Firefox | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/chrome/chrome_48x48.png" alt="Chrome" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)</br>Chrome | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/safari/safari_48x48.png" alt="Safari" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)</br>Safari |
| :-: | :-: | :-: | :-: | :-: |
| not support | last 2 versions | last 2 versions | last 2 versions | last 2 versions |

## 相关项目

- [agentskills-runtime](https://gitee.com/UCT/agentskills-runtime) - Agent Skills 运行时内核
- [uctoo-app-client-pc](https://gitee.com/UCT/uctoo-app-client-pc) - UCToo 应用开发管理后台

## 许可证

MIT License

Copyright (c) 2026 UCToo