# zhiyancloud

**Repository Path**: dingn/zhiyancloud

## Basic Information

- **Project Name**: zhiyancloud
- **Description**: 一个基于本体建模思想构建的研发项目管理软件，含AI知识库和低码工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-28
- **Last Updated**: 2026-05-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 知研云 (ZhiYanCloud)

> 面向研发管理的**元数据驱动平台** —— 类似 ServiceNow / Salesforce Platform 的形态。

知研云**不是一个项目管理软件**,而是一个可以"用元数据搭出业务"的平台。产品线管理、项目管理、知识库管理这三大业务域,只是平台预置的**开箱即用案例**,而非写死的功能模块。业务表在**运行时由元数据驱动生成**(通过 DDL 引擎 `ALTER TABLE`),用户可以为每个业务域实例配置不同的字段、视图与状态机。

**核心设计哲学:**

> 业务上随便玩,底层我守着。
>
> —— 业务层最大化灵活,底层最大化严谨。

---

## ✨ 核心特性

- **元数据驱动**:对象(表)、字段(列)、视图、状态机全部由元数据描述,运行时生成与渲染。
- **一对象一物理表**:每个 `meta_object` 对应唯一一张物理表,字段累积进字段库,通过启用清单决定实例使用哪些字段。
- **DDL 引擎托管结构变更**:所有 `ALTER TABLE` 必须经过 DDL 引擎,与元数据写入在同一事务内完成(PostgreSQL 支持事务 DDL)。
- **MetaRepository 统一查询**:业务表的 CRUD 一律走元数据驱动的 Repository,杜绝手拼动态 SQL。
- **状态机驱动流转**:状态变更只能通过状态机的合法转换,禁止直接 `UPDATE status_id`。
- **细粒度权限模型**:状态机可见性 > 超管 > 创建人 > 业务域对象权限,层层叠加。
- **审计只追加**:`audit_log` 只增不改不删。

---

## 🧱 技术栈

| 层 | 选型 |
|---|---|
| 语言 | Go 1.26 |
| Web 框架 | Gin |
| ORM | GORM (PostgreSQL 驱动) |
| 数据库 | PostgreSQL |
| 缓存 | Redis |
| 迁移 | golang-migrate |
| CLI | Cobra |
| 配置 | Viper(支持 `ZYC_` 前缀环境变量覆盖) |
| 日志 | Zap + lumberjack |
| 前端 | Vue 3 + Vite + TypeScript + Element Plus + Pinia + Vue Router |

---

## 🗂️ 目录结构

```
zhiyancloud/
├── cmd/zhiyancloud/        # 应用入口(serve / migrate / cache-warm 子命令)
├── internal/
│   ├── transport/          # HTTP 层(router、handler、dto)
│   ├── admin/              # 管理后台(dashboard / metaadmin / backup / system …)
│   ├── domain/             # 业务域(productline / project / knowledgebase / workitem)
│   ├── core/               # 核心服务(auth / user / org / role / permission / menu / tag …)
│   ├── platform/           # 平台基石(meta / view / statemachine / codegen / audit / eventbus)
│   └── ...
├── pkg/                    # 通用基础库(database / cache / logger / config / errcode / id / utils)
├── migrations/             # 固定结构表迁移 SQL(*.up.sql / *.down.sql)
├── web/                    # 前端工程(Vue 3 + Vite)
├── prototype/             # 交互原型(静态页面)
├── docs/                   # 设计文档(见下方索引)
├── deploy/                 # 部署相关
├── config.yaml(.example)   # 配置文件
├── .env.example            # 环境变量示例
└── Makefile                # 常用命令
```

### 架构分层(强约束)

```
transport (HTTP)
    ↓
admin | domain
    ↓
core (auth/user/org/role/permission)
    ↓
platform (meta/view/statemachine/codegen/audit/eventbus)
    ↓
pkg (database/cache/logger/config/errcode/id/utils)
```

依赖方向严格单向,禁止反向或跨层耦合:

- ❌ `platform` 不得依赖 `core / domain / admin`
- ❌ `core` 不得依赖 `domain / admin`
- ❌ `domain` 之间不得互相直接依赖(通过 eventbus 或 core 协调)
- ❌ `admin` 与 `domain` 不得互相依赖
- ❌ `pkg` 不得依赖任何 `internal/` 内的包

---

## 🚀 快速开始

### 1. 前置依赖

- Go 1.26+
- PostgreSQL(默认 `localhost:5432`,库名 `zhiyancloud`)
- Redis(默认 `localhost:6379`)
- Node.js(仅在需要构建前端时)

### 2. 准备配置

```bash
cp config.yaml.example config.yaml
# 按需修改数据库 / Redis / JWT 等配置
# 也可通过 ZYC_ 前缀环境变量覆盖,例如:
#   export ZYC_DATABASE_PASSWORD=yourpassword
```

> 配置默认监听 `0.0.0.0:9000`,日志输出至 `./logs/zhiyancloud.log`。

### 3. 执行数据库迁移

```bash
make migrate-up        # 应用所有未执行的迁移
make migrate-version   # 查看当前迁移版本
```

### 4. 构建并运行

```bash
make build             # 构建前后端(前端缺失则自动跳过)
make run               # 启动应用(默认读取 config.yaml)
```

后端二进制产物位于 `bin/zhiyancloud`,也可直接运行:

```bash
./bin/zhiyancloud --config config.yaml serve
```

### 5. 前端开发(可选)

```bash
cd web
npm install
npm run dev            # 本地开发
npm run build          # 生产构建
```

---

## 🛠️ 常用命令

```bash
make build         # 一键构建前后端
make build-backend # 仅构建后端
make run           # 启动应用 (CONFIG=config.yaml)
make test          # 跑单元测试 (go test ./...)
make lint          # 代码检查 (go vet ./...)
make tidy          # 整理 go.mod
make clean         # 清理构建产物
make migrate-up    # 执行所有未应用的迁移
make migrate-down  # 回滚 N 步迁移 (N=1 默认)
make migrate-version            # 显示当前迁移版本
make db-reset CONFIRM=yes       # ⚠️ DROP 所有数据 + 重新迁移(仅限开发环境)
```

---

## 📦 预置业务域

平台预置了三大业务域作为**开箱即用案例**,它们本质上都是元数据配置的产物,可被复制、改造或新增:

| 业务域 | 说明 |
|---|---|
| 产品线管理 (productline) | 管理产品线及其层级关系 |
| 项目管理 (project) | 项目实体、编号规则、状态字典、标签机制 |
| 知识库管理 (knowledgebase) | 知识库与文档组织 |
| 工作项 (workitem) | 需求 / 缺陷 / 任务等工作项实体 |

---

## 🔒 关键约束与不变量

以下规则贯穿整个项目生命周期,违反即视为 bug:

1. **一对象一物理表**:每个 `meta_object` 对应唯一一张物理表。
2. **字段库累积**:同一对象的字段累积进字段库,启用清单决定实例使用哪些字段。
3. **字段永不物理删除**:停用 = 标记 `is_deprecated`,物理列保留。
4. **系统对象保护**:`is_system=true` 的对象不可删除、不可改物理表名。
5. **状态变更走状态机**:不允许直接 `UPDATE status_id`。
6. **创建人读权限不可剥夺**:任何配置都不能让创建人看不到自己创建的数据。
7. **删除权限受限**:仅超管 + 创建人可删除,项目经理也不行。
8. **离职用状态字段**:`employment_status='left'`,不删用户。
9. **审计永不删除**:`audit_log` 只追加。
10. **DDL 通过引擎**:严禁绕开 DDL 引擎直接执行 `ALTER`。

### 命名约定(摘要)

- 表名:小写下划线,如 `meta_object`、`work_item_requirement`
- 主键:统一 `id`,类型 UUID
- 自定义字段列名:`cf_{snake_case_name}_{short_uuid}`,如 `cf_customer_industry_a1b2`
- 审计字段:`created_at` / `updated_at` / `is_deleted` / `deleted_at`

> 详见 `docs/NAMING.md`、`docs/METAREPO.md`。

---

## 📚 设计文档索引

建议按以下顺序阅读(`04` 为优先级最高的平台基石,与其他文档冲突时以它为准):

| 顺序 | 文档 | 角色 |
|---|---|---|
| 1 | [`docs/00_技术选型与项目骨架.md`](docs/00_技术选型与项目骨架.md) | 技术栈、目录结构、部署方式 |
| 2 | [`docs/04_元数据架构设计.md`](docs/04_元数据架构设计.md) | ⭐ 平台基石 |
| 3 | [`docs/05_状态机设计.md`](docs/05_状态机设计.md) | 行为维度元数据 |
| 4 | [`docs/03_权限模型设计.md`](docs/03_权限模型设计.md) | 权限、用户、审计 |
| 5 | [`docs/02_工作项实体设计.md`](docs/02_工作项实体设计.md) | 工作项的具体实现 |
| 6 | [`docs/01_项目实体设计.md`](docs/01_项目实体设计.md) | 编号规则、状态字典、标签机制 |
| 7 | [`docs/06_产品界面设计规范.md`](docs/06_产品界面设计规范.md) | 前端界面与设计器交互规范 |

---

## 📈 开发状态

**当前阶段:Stage 1 —— 元数据引擎核心**

具体目标见 [`docs/第一周里程碑清单.md`](docs/第一周里程碑清单.md)。权限、状态机、审计等功能虽已在设计文档中定义,但暂未纳入当前阶段实现范围。

---

## 📄 许可证

私有项目,暂未公开授权。