# CodeSpectra

**Repository Path**: zzz701/code-spectra

## Basic Information

- **Project Name**: CodeSpectra
- **Description**: 一个适用于openharmony中多维度代码审查的webhook服务
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 6
- **Created**: 2025-07-26
- **Last Updated**: 2025-07-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

开源代码管控系统 (Python+MySQL版)
# 🌟 项目简介
基于Python Flask框架和MySQL数据库构建的轻量级代码管理系统，提供完整的代码版本控制、团队协作和项目管理功能。

# 📂 项目结构
```text
├── code_spectra/
│   ├── __init__.py
│   ├── code_spectra.py     # 事件处理
│   └── manifest.json       # hook事件及子事件配置文件
├── constants/              # 常量
├── db/
│   ├── database.py         # 数据库模型
│   └── utils.py            # 数据库操作常用函数
└── log/                    # 仅用于存放日志的目录
└── logger/                 # 日志模型
└── models/                 # 工具模型
│   ├── file_searcher.py    # 用于检查目录或文件是否属于给出的目录和文件当中
│   ├── gitee_clinet.py     # 用于与gitee进行交互，如检视/评论/获取评论/获取文件等等
│   ├── owner_config_mgr.py # 用于更新库上最新的owner_config.json文件到本地
│   └── webhook.py          # webhook模型
└── sub_events/             # 子事件，不一一介绍
│   └── __init__.py         # 遍历整个目录将所有的子事件注册到ALL_REGISTERED_EVENTS中
└── tests/                  # TDD
└── config.toml             # 配置文件
└── main.py                 # 代码入口
└── start.sh                # 启动脚本
```

# ✨ 核心功能
通过审查权力拆分，配置code_spectra/manifest.json，对各种webhook自定义子事件，完成个性化的代码合入前管控。

## 概念介绍
- 一个webhook称为一个事件，该事件可以配置多个子事件(sub_events)，对他的子事件而言，该hook事件为父事件。
- sub_events中定义了所有可配置的子事件。
- **审查权力拆分：**
原来给PR进行加分，只需要审查人的个人账号点击“审查通过”即可完成。
```mermaid
graph TD
    A[个人账号] --> B[点击审查通过]
    B --> C[审查通过]
```
现在，我们成立了多个逻辑上的小组，每个小组有一个独立的gitee账号，负责自己责任模块的代码文件，相应的，PR只允许组账号进行加分，而不是个人账号。

每个逻辑小组内配备负责该模块的组员。
```mermaid
graph TD
    A[个人账号] --> B[在PR下面评论pass]
    B --> C[触发gitee的webhook]
    C -->|在这里植入我们的管控| D{管控检查通过?}
    D --> E[使用这个人所属的小组账号进行审查]
    E -->|是| F[审查通过，成功加分]
    E -->|否| G[审查失败，不允许加分]
```
这样在个人加分转变成组加分的过程中，便可插入我们的管控事件，实现审查权力的拆分。

## 运行流程
每个子事件有三个阶段
- pre_execute：事件执行前的检查，是否满足执行条件，如果没有校验条件可不重写该函数，返回false则不执行execute/post_execute。
- execute：事件执行逻辑，每个子事件必须重写该函数，返回false则不执行post_execute。
- post_execute：对PR进行评论回复，一般来说不推荐子事件重写该函数，复用base_event即可。

# 🚀 快速开始
## 前置条件
### 成立小组
- 将自己域内的业务范围按模块划分，注册新的gitee账号，名称例如arkui_image。
- 请代码仓的管理员邀请这些小组账号加入组织。
- 使用gitee的codeowner能力，在/代码仓/.gitee/CODEOWNERS中将每个目录或文件划分到不同的小组下，这样提交PR就会自动分配小组账号为该笔PR的审查人了。
### 添加组员
- 在/代码仓/.gitee/下新建owner_config.json，层级如下
```json
{
    "groups": {
        "$小组账户1的gitee地址": [
            "$小组1成员1的gitee地址",
            "$小组1成员2的gitee地址"
        ],
        "$小组账户2的gitee地址": [
            "$小组2成员1的gitee地址",
            "$小组2成员2的gitee地址",
        ]
    },
    "userInfos": {
        "$成员1的gitee地址": {
            "info": "$ta的个人信息，可自行发挥，比如他负责的模块+姓名，如[图片类组件 zhangsan]",
            "group": "$成员1所属小组的gitee地址"
        },
        "$成员2的gitee地址": {
            "info": "$ta的个人信息",
            "group": "$成员2所属小组的gitee地址"
        }
    }
}
```

## 克隆仓库
git clone https://gitee.com/liyujie43/code-spectra.git

## 创建数据库

- 建议安装mysql 8.0+
- 数据库配置也在config.toml中，详情见下文

mysql -u root -p -e "CREATE DATABASE pr_management"

## **配置说明**

### **config.toml**
打开config.toml修改以下**必填配置**：
```
[database]
user = "你的mysql用户"
password = "你的mysql密码"
host = "localhost"
db_name = "你的mysql数据库名称"

[accounts.groups]
# 填写你的组账号信息，如
# "https://gitee.com/xxx" = "xxx的token"

[accounts.admin_user]
# 填写仓库管理员信息，如
# "https://gitee.com/xxx" = "xxx的token"

[accounts.notifier]
# 填写特性管理员账号，用来推送评论，如
# "https://gitee.com/xxx" = "xxx的token"

```
其他配置可自行添加和修改:

- check_tdd.force_accounts则是可以强制通过测试用例检查的人员名单

- check_mod.force_accounts是可以强制通过侵入式修改检查的的人员名单

详情可以查看config.toml配置文件

### **manifest.json**
打开code_spectra/manifest.json，进行个性化配置

如果hook_name是note_hooks，action是comment，层级如下：
```json
{
    "note_hooks": {
        "comment": {
            "events": {
                "$评论关键字": {
                    "event_name_zh": "$事件中文名",
                    "event_name_en": "$事件英文名",
                    "sub_events": []
                }
            }
        }
    }
}
```
如果hook_name不是note_hooks，层级如下：
```json
{
    "$hook_name": {
        "$hook的action": {
            "event_name_zh": "$事件中文名",
            "event_name_en": "$事件英文名",
            "sub_events": []
        }
    }
}
```
sub_events内部配置字段如下：
```json5
"sub_events": [
    {
        "enable": true,                 # true为启用，false为禁用
        "event_class": "$sub_events目录下某个event的类名",
        "use_parent_event_name": true,  # true表示此事件进行post_execute时，会以父事件的名称组装评论，而不是本子事件自己的名称，不填默认为false
        "show_table": true,             # true表示此事件进行post_execute时，是否需要组装html表格，不填默认为false
        "post_on_fail_only": true,      # true表示是否仅在execute失败场景下进行post_execute，不填默认为false
        "continue_on_fail": true,       # true表示就算该子事件失败，也会继续执行后面的子事件，不填默认为false
        "branches": [
            "$该子事件生效的代码分支"
        ]                               # 不填默认对所有分支生效
    }
]
```
## 运行
sudo ./start.sh

# 📜 开发新的子事件
**每个event必须重写以下字段**：
- event_name_zh：事件中文名（在基类的generate_statement时用到）
- event_name_en：事件英文名（在基类的generate_statement时用到）

**必须重写以下函数**：
- def execute：具体执行事件逻辑，若执行完需要评论回复则返回True，否则返回False，需要在逻辑内对failed进行赋值，表示执行成功或者失败

**可选重写以下函数**：
- def suggestion【需携带装饰器@property】：失败建议，写好中英文，在基类默认post_execute中组装评论使用
- def pre_execute：校验事件是否应该执行，不重写默认为True
- def post_execute：对PR进行评论回复，默认组装评论分为三个部分
    · 表格：通过generate_table组装html表格，由show_table开关控制
    · 陈述句：通过generate_statement生成默认组装event_name+结果，如“TDD检查成功”/“review failed”之类的格式
    · 失败建议：self.suggestion，需要event自行定义
    对上述每个部分都会调用一遍，然后组装到一起。
- def generate_statement：生成陈述句，可自定义陈述句，中英文组装好进行返回
- def generate_table：生成表格，默认为check type（event_name_en）/result（failed）/report（-）三列，可按需配置字段

# **📧 联系方式**
项目维护者:
- liyujie43@huawei.com
- lusong11@huawei.com

# 🙏 致谢
Flask开发团队

MySQL社区

所有贡献者