# GitCandy 需求文档 > 版本：v1.0 | 日期：2026-07-20 | 来源：代码扫描反推 本文档描述 GitCandy 的愿景、核心目标和功能方向。完成状态在[功能清单](/NewLife/GitCandy/Blob/master/Doc/功能清单.md)中追踪，详细设计在[架构设计](/NewLife/GitCandy/Blob/master/Doc/架构设计.md)中展开。 --- ## 1. 背景与愿景 ### 1.1 系统定位 GitCandy 是一个基于 .NET 的 Git 分布式版本控制平台（Git Hosting Service），支持公有和私有代码库。用户可不受限制地创建代码库，随时随地与团队协作。 | 产品/工程 | 定位 | |-----------|------| | `GitCandy`（数据层） | XCode 数据层，定义实体模型与数据库操作 | | `GitCandy.Web`（Web层） | ASP.NET Core MVC + NewLife.Cube 魔方框架，提供 Web 界面与 Git HTTP 协议服务 | | `Test`（测试） | 控制台测试项目 | ### 1.2 愿景 打造一个免部署、开箱即用的私有 Git 代码托管平台，支持团队与个人下属源码库两级管理，提供完整的代码浏览、协作与审计能力。 --- ## 2. 核心目标 | 编号 | 目标 | 所属层级 | 一句话描述 | |------|------|----------|------------| | SYS | 系统基础 | 基础层 | 系统配置管理、认证桥接、用户自动同步与首页导航 | | USER | 用户管理 | 核心层 | 用户注册、认证登录、账号信息查看与搜索 | | TEAM | 团队管理 | 核心层 | 团队创建、成员管理、角色分配 | | REPO | 仓库管理 | 核心层 | 仓库创建/配置/删除、协作权限管理、仓库列表浏览 | | GIT | Git核心服务 | 业务层 | Git Smart HTTP 协议、代码树浏览、提交历史、分支/标签、归档、Blame、统计分析 | | HIST | 操作历史 | 辅助层 | Git 操作日志记录与审计查看 | --- ## 3. 功能需求 ### 3.1 SYS — 系统基础 - **SYS-1 系统配置管理**：通过魔方 ConfigController 管理 GitCandy 全局配置（服务开放、注册开关、仓库路径、缓存路径、Git-Core路径、每页条数等）。 - **SYS-2 用户自动同步**：Cube 认证后自动在 GitCandy 本地用户表创建/关联用户记录。 - **SYS-3 首页与语言切换**：提供首页重定向、关于页面、中英文语言切换。 ### 3.2 USER — 用户管理 - **USER-1 用户后台管理**：管理员通过魔方后台管理所有用户，支持按条件搜索、查看成员列表、关联分组、仓库列表等。 - **USER-2 用户账号页面**：查看用户详情（昵称、邮箱、所属团队、代码库列表），支持用户名搜索。 - **USER-3 Web用户认证**：集成 Cube 管理提供者，支持 Cookie 认证，自动关联 GitCandy 本地用户。 - **USER-4 用户注册与创建**：支持通过 Biz 层创建新用户（指定名称、昵称、密码、邮箱、描述）。 ### 3.3 TEAM — 团队管理 - **TEAM-1 团队管理**：创建/编辑/删除团队，查看团队详情与成员列表。 - **TEAM-2 用户团队关联管理**：通过魔方后台管理用户与团队的关联关系，支持设置团队管理员。 - **TEAM-3 团队成员选择**：在团队页面中选择添加/移除成员。 ### 3.4 REPO — 仓库管理 - **REPO-1 仓库后台管理**：管理员通过魔方后台管理所有仓库，支持按拥有者/用户/可见性搜索。 - **REPO-2 仓库浏览与管理**：创建仓库（指定拥有者、私有/公开、匿名读写权限），编辑仓库设置，删除仓库。 - **REPO-3 用户仓库关联管理**：通过魔方后台管理用户与仓库的读写权限关联。 - **REPO-4 仓库协作管理**：仓库拥有者可添加协作者（用户/团队），设置读写权限。 - **REPO-5 仓库列表浏览**：分页浏览自己有权限的仓库列表，区分公开/私有。 ### 3.5 GIT — Git核心服务 - **GIT-1 Git Smart HTTP传输**：实现 Git 智能 HTTP 协议（info/refs、git-upload-pack、git-receive-pack），支持 git clone/push/pull 操作。 - **GIT-2 代码树浏览**：按路径浏览仓库目录结构和文件列表，支持分支/标签切换。 - **GIT-3 文件内容查看**：查看文件原始内容（Blob/Raw），支持语法高亮。 - **GIT-4 提交历史浏览**：查看仓库提交历史列表和单次提交详情（变更文件、差异对比）。 - **GIT-5 分支管理**：查看仓库所有分支列表，按分支浏览代码。 - **GIT-6 标签管理**：查看仓库所有标签列表，按标签浏览代码。 - **GIT-7 代码归档下载**：按分支/标签/提交打包下载源码（zip 格式）。 - **GIT-8 Blame代码审阅**：逐行查看文件的修改历史和责任人。 - **GIT-9 贡献者统计**：查看仓库贡献者列表及提交统计。 - **GIT-10 分支差异比较**：比较两个分支/提交之间的代码差异。 - **GIT-11 仓库统计信息**：自动计算仓库提交数、分支数、贡献者数、文件数、源码大小。 ### 3.6 HIST — 操作历史 - **HIST-1 Git操作日志**：记录每次 Git 操作（push/pull/clone）的用户、仓库、操作类型、成功/失败、客户端信息等，支持魔方后台查看。 --- ## 4. 🧊 暂缓清单 | 功能 | 暂缓理由 | 解冻前提 | |------|----------|----------| | SSH密钥管理 | `SshKey` 实体已从编译排除，模型定义存在但未启用 | 需要SSH协议支持时恢复 | | 认证日志管理 | `AuthorizationLog` 实体已从编译排除，旧的 Token 认证体系已废弃 | 需要独立的授权码认证时恢复 | ## 5. 不做什么 - ❌ 不提供 WebHook/CI-CD 集成（当前版本） - ❌ 不提供 Pull Request / Merge Request 工作流 - ❌ 不提供 Issue 追踪 - ❌ 不提供 Wiki 文档 - ❌ 不提供代码搜索（全文检索） - ❌ 不提供 SSH 协议支持（仅 HTTP）