Skip to content

docs

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

docs

README.md

Sky-Server 设计文档

文档概述

本目录包含了Sky-Server项目的完整设计文档，涵盖了系统架构、数据库设计、API设计和开发计划等方面。

文档目录

01-系统架构设计.md

系统的整体架构设计文档，包括：

  • 项目概述: 项目背景、核心特性、技术选型
  • 系统架构: 整体架构图、分层设计
  • 项目目录结构: 详细的代码组织结构
  • 核心模块设计: 各个核心模块的职责和接口设计
    • 元数据服务
    • 通用CRUD服务
    • 权限服务
    • 动作执行服务
    • 单据编号服务
    • 数据字典服务
  • 数据流设计: 查询、创建、动作执行的流程
  • 安全设计: 认证、授权、数据隔离、SQL注入防护
  • 性能优化: 缓存、数据库优化、并发控制
  • 部署架构: 开发环境和生产环境部署方案

适合人群: 架构师、技术负责人、新加入的开发人员

02-数据库设计.md

数据库的详细设计文档，包括：

  • 数据库概述: 数据库选型、设计原则
  • 数据表分类: 元数据表、权限表、动作表、字典表等
  • 核心表详细设计: 每个核心表的字段说明、索引设计
    • sys_table: 表单定义
    • sys_column: 字段定义
    • sys_table_ref: 表关联关系
    • sys_action: 动作定义
    • sys_user: 用户表
    • sys_groups: 权限组
    • sys_seq: 单据编号生成器
    • sys_dict: 数据字典
  • 表关系图: 数据库ER图
  • 标准字段说明: 所有表的通用字段
  • 数据库优化建议: 索引策略、分区策略、查询优化
  • 安全建议: 密码存储、SQL注入防护、数据备份

适合人群: 数据库设计师、后端开发人员、DBA

03-API设计.md

RESTful API的详细设计文档，包括：

  • API设计原则: RESTful规范、统一响应格式、HTTP状态码
  • 认证与授权: 登录、Token刷新、登出
  • 通用CRUD API: 增删改查接口设计
    • 查询列表（支持过滤、排序、分页）
    • 查询单条
    • 创建记录
    • 更新记录
    • 删除记录（软删除）
    • 批量操作
  • 元数据API: 获取表元数据、刷新缓存
  • 数据字典API: 字典和字典项查询
  • 动作执行API: 执行自定义动作
  • 权限API: 权限检查、获取用户权限
  • 单据编号API: 生成编号、预览编号
  • 用户管理API: 用户信息、修改密码
  • 文件上传API: 文件上传下载
  • 导入导出API: Excel导入导出
  • 错误码定义: 统一的错误码体系
  • API安全: 请求签名、限流、CORS
  • API版本管理: 版本策略、废弃通知

适合人群: 后端开发人员、前端开发人员、测试人员

04-开发计划.md

详细的开发计划和实施路线图，包括：

  • 项目概述: 项目目标、项目周期
  • 开发阶段划分: 分为6个阶段
    • 第一阶段: 基础框架搭建
    • 第二阶段: 认证授权模块
    • 第三阶段: 元数据服务
    • 第四阶段: 通用CRUD引擎
    • 第五阶段: 高级功能
    • 第六阶段: 完善和优化
  • 技术规范: 代码规范、Git规范、测试规范、文档规范
  • 开发工具: 必备工具、推荐IDE、开发插件
  • 质量保证: 代码审查、自动化测试、性能基准
  • 风险管理: 技术风险、进度风险及缓解措施
  • 里程碑: 各阶段交付内容
  • 参考资料: 技术文档、设计模式、最佳实践

适合人群: 项目经理、技术负责人、开发团队

文档使用指南

新人入职

建议按以下顺序阅读文档：

  1. 01-系统架构设计.md - 了解整体架构和技术选型
  2. 02-数据库设计.md - 理解数据模型和业务逻辑
  3. 04-开发计划.md - 了解开发规范和工作流程
  4. 03-API设计.md - 熟悉API接口设计

开发新功能

  1. 先查看 01-系统架构设计.md 确定功能所属模块
  2. 参考 02-数据库设计.md 了解相关数据表
  3. 参考 03-API设计.md 设计API接口
  4. 遵循 04-开发计划.md 中的技术规范编码

问题排查

  1. 数据问题查看 02-数据库设计.md
  2. API问题查看 03-API设计.md
  3. 架构问题查看 01-系统架构设计.md

核心概念速查

元数据驱动

Sky-Server的核心理念是元数据驱动，即：

  • 表结构、字段、关系不在代码中硬编码
  • 所有定义存储在数据库的元数据表中（sys_table、sys_column等）
  • 运行时动态加载元数据并生成UI和执行CRUD操作
  • 通过配置而非编码来扩展系统功能

关键元数据表

表名 用途
sys_table 定义逻辑表/表单
sys_column 定义字段
sys_table_ref 定义表关联关系
sys_action 定义自定义动作
sys_table_cmd 定义表操作钩子

字段赋值策略

类型 说明
pk 主键自增
docno 单据编号（使用序号生成器）
createBy 创建人
operator 操作用户
sysdate 当前时间
byPage 用户输入
select 下拉选择（字典）
fk 外键关联

权限模型

用户(sys_user)
  → 权限组(sys_groups)
    → 目录权限(sys_group_prem)
      → 安全目录(sys_directory)
        → 表(sys_table)

权限值（位运算）：

  • 1: 读
  • 2: 写
  • 4: 提交
  • 3 = 1 + 2: 读写
  • 5 = 1 + 4: 读提交

项目关键特性

1. 多租户支持

  • 所有表包含 SYS_COMPANY_ID 字段
  • 自动添加公司ID过滤条件
  • 数据完全隔离

2. 软删除

  • 所有表包含 IS_ACTIVE 字段
  • 删除操作仅将其设为 'N'
  • 支持数据恢复

3. 审计追踪

  • 所有表包含创建和修改信息
  • CREATE_BY, CREATE_TIME
  • UPDATE_BY, UPDATE_TIME

4. 灵活的动作系统

支持多种动作类型：

  • URL: 跳转到指定URL
  • SP: 执行存储过程
  • JS: 执行JavaScript
  • Python: 执行Python脚本
  • Job: 执行后台任务

5. 单据编号生成

支持灵活的编号格式：

  • 格式：PO{YYYY}{MM}{DD}{0000}
  • 结果：PO202601110001
  • 支持日/月/年循环

技术栈

类别 技术
语言 Go 1.21+
Web框架 Gin
ORM GORM
数据库 MySQL 8.0+
缓存 Redis
配置 Viper
日志 Zap
文档 Swagger

开发环境要求

  • Go 1.21+
  • MySQL 8.0+
  • Redis 6.0+
  • Git
  • Make（可选）

快速开始

# 克隆项目（项目搭建后）
git clone https://github.com/sky-xhsoft/sky-server.git
cd sky-server

# 初始化数据库
mysql -u root -p < sqls/create_skyserver.sql

# 配置环境变量
cp configs/config.example.yaml configs/config.yaml
# 编辑 config.yaml 填入数据库等配置

# 安装依赖
go mod download

# 运行
go run cmd/server/main.go

文档更新

本文档随项目开发持续更新。如有问题或建议，请提交Issue。

相关链接

文档版本: v1.0.0 最后更新: 2026-01-11 维护者: Sky-XHSoft Team