# material-ops-platform

**Repository Path**: weiliu66/material-ops-platform

## Basic Information

- **Project Name**: material-ops-platform
- **Description**: No description available
- **Primary Language**: Go
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-18
- **Last Updated**: 2026-05-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 快手自动采集发布中台

Go 云端服务骨架，当前已实现“低频实时通知 + 客户端拉取 + 原子认领”的核心后端能力。

## 架构总览

本项目按“一套 Go 后端 + 一个 Web 管控台 + 一个桌面端运行链路”组织，生产部署时由 Go 服务托管构建后的 `web-antd` 前端，实现一体化发布。

- 云端后端：`cmd/api` 启动 HTTP 服务，`internal/*` 按身份、账号、素材任务、实时通知、升级中心拆分业务模块。
- Web 管控台：`web/apps/web-antd` 基于 `vue-vben-admin`，当前保留部门管理、账号管理、用户权限、素材任务、升级中心等运营页面。
- 桌面 SDK：`desktop_client` 负责统一登录、心跳、任务拉取、任务认领、升级清单与升级上报。
- 桌面应用：`desktop_app` 承载 PyQt6 桌面界面和本地采集/处理/发布能力，通过桌面 SDK 与云端交互。
- 数据库迁移：`migrations` 维护 MySQL 表结构与默认数据。

详细架构、接口边界和扩展约定见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。

## 功能

- 批量提交采集素材：`POST /api/source-items/ingest`
- WebSocket 低频合并通知：`GET /api/desktop/events`
- 待处理素材摘要：`GET /api/materials/pending-summary`
- 待处理素材拉取：`GET /api/materials/pending`
- 任务原子认领：`POST /api/material-jobs/{id}/claim`
- 任务续约、释放、结果回传
- 后台登录与角色权限：管理员、运营、查看者
- 桌面端登录、心跳、启动配置拉取
- 账号管理
- 对标账号提交、审核通过、驳回、修改后重提
- 升级管理中心：组件、下载地址型版本发布、指定客户端灰度、回滚、升级日志
- 桌面端接入层：登录、心跳、WebSocket 事件、防抖拉取、任务认领、模块升级下载校验
- PyQt6 桌面端新项目骨架：远程登录与后台事件、模块化升级目录、采集/处理/发布/其他分区

云端只负责数据、通知和租约锁。类目、佣金、发布上限、账号状态等业务判断由桌面端本地完成。

## 本地运行

1. 创建 MySQL 数据库：

```sql
CREATE DATABASE IF NOT EXISTS material_ops CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;
```

2. 执行迁移：

```bash
mysql -u root -p material_ops < migrations/001_initial.sql
mysql -u root -p material_ops < migrations/002_identity_accounts_targets.sql
mysql -u root -p material_ops < migrations/003_upgrade_center.sql
mysql -u root -p material_ops < migrations/004_unify_auth.sql
mysql -u root -p material_ops < migrations/005_simplify_upgrade_components.sql
mysql -u root -p material_ops < migrations/006_departments.sql
mysql -u root -p material_ops < migrations/009_follow_accounts.sql
mysql -u root -p material_ops < migrations/010_follow_accounts_owner_department.sql
mysql -u root -p material_ops < migrations/011_target_accounts_profile_fields.sql
mysql -u root -p material_ops < migrations/012_materials_business_fields.sql
mysql -u root -p material_ops < migrations/013_collection_records_and_material_owners.sql
mysql -u root -p material_ops < migrations/014_app_configs.sql
mysql -u root -p material_ops < migrations/015_collection_records_parse_fields.sql
mysql -u root -p material_ops < migrations/016_department_db_configs_and_user_expiry.sql
mysql -u root -p material_ops < migrations/017_card_keys.sql
mysql -u root -p material_ops < migrations/018_log_cleanup_indexes.sql
```

3. 启动服务：

```bash
./scripts/dev-api.sh
```

默认监听 `:8080`。

如需临时覆盖数据库或端口：

```bash
MATERIAL_OPS_HTTP_ADDR=':8090' ./scripts/dev-api.sh
```

4. 前端开发：

```bash
cd web
corepack enable
pnpm install
pnpm dev:antd
```

5. 一体部署前构建前端：

```bash
cd web
corepack enable
pnpm install
pnpm build:antd
cd ..
go run ./cmd/api
```

`web/apps/web-antd/dist` 存在时，Go 服务会直接托管前端页面。

## 线上部署

部署模板集中在 `deploy/ops/`，服务端和桌面端已分开：

- 服务端：`deploy/ops/systemd/material-ops-api.service`
- 域名反代：`deploy/ops/nginx/ops.yunfei123.xin.conf`
- 环境变量：`deploy/ops/env/material-ops-api.env.example`
- 桌面端物料目录：`deploy/ops/desktop/`

## 环境变量

- `MATERIAL_OPS_MYSQL_DSN`：MySQL DSN。
- `MATERIAL_OPS_HTTP_ADDR`：HTTP 监听地址，默认 `:8080`。
- `MATERIAL_OPS_NOTIFY_WINDOW`：通知合并窗口，默认 `5s`。
- `MATERIAL_OPS_NOTIFY_MAX_INTERVAL`：高峰期最大通知间隔，默认 `10s`。
- `MATERIAL_OPS_LEASE_TTL`：任务认领租约时长，默认 `10m`。
- `MATERIAL_OPS_LOG_CLEANUP_INTERVAL`：日志自动清理执行间隔，默认 `6h`。
- `MATERIAL_OPS_LOG_CLEANUP_BATCH_SIZE`：单次分批删除条数，默认 `1000`。
- `MATERIAL_OPS_COLLECTION_LOG_RETENTION_DAYS`：采集日志保留天数，默认 `30`，设为 `0` 可关闭自动清理。
- `MATERIAL_OPS_CARD_KEY_API_LOG_RETENTION_DAYS`：卡密调用日志保留天数，默认 `30`，设为 `0` 可关闭自动清理。
- `MATERIAL_OPS_JWT_SECRET`：JWT 签名密钥。
- `MATERIAL_OPS_BOOTSTRAP_PASSWORD`：首次启动自动创建 `admin` 用户的密码，默认 `Admin@123`。

说明：

- 上述日志清理环境变量现在作为默认值兜底。
- 管理员可在 Web 管控台“中台管理 -> 日志清理”中在线修改总开关、执行间隔、批次大小和各日志类型保留天数。
- 后续新增日志类型时，可沿用同一配置页扩展，不必再单独做一套开关。

## 默认账号

首次启动且用户表为空时，会创建：

- 后台管理员：`admin` / `Admin@123`
- 默认绑定桌面客户端：`desktop-demo`（归属 `admin`）

生产环境务必修改默认账号密码，并配置客户端绑定关系。

## 主要接口

- `POST /api/auth/login`
- `GET /api/me`
- `GET/POST /api/users`
- `GET/POST /api/departments`
- `GET /api/accounts`
- `GET/POST/PATCH /api/target-accounts`
- `POST /api/target-accounts/{id}/approve`
- `POST /api/target-accounts/{id}/reject`
- `GET /api/desktop/bootstrap`
- `POST /api/desktop/heartbeat`
- `POST /api/source-items/ingest`
- `GET /api/materials/pending-summary`
- `GET /api/materials/pending`
- `POST /api/material-jobs/{id}/claim`
- `GET/POST /api/admin/upgrade/components`
- `GET/POST /api/admin/upgrade/releases`
- `POST /api/admin/upgrade/releases/{id}/rollback`
- `GET /api/admin/upgrade/logs`
- `POST /api/open/card-keys/unbind`
- `POST /api/desktop/upgrade/manifest`
- `POST /api/desktop/upgrade/report`

## Web 控台接口返回规范（统一）

为适配 `vue-vben-admin`，Web 控台接口统一返回以下结构：

```json
{
  "code": 0,
  "data": {},
  "error": null,
  "message": "ok"
}
```

- 成功：`code = 0`，业务数据放在 `data`。
- 失败：`code = -1`，错误信息放在 `error` 和 `message`。
- 前端 `requestClient` 统一按 `code/data` 解包，不再使用 `responseReturn: body` 绕过解析。

说明：

- 当前统一范围为 Web 与桌面共享的 `/api/**` 接口（如 auth、user、menu、账号池、升级中心、素材任务等）。
- 桌面端调用 `/api/desktop/**`、`/api/materials/**`、`/api/material-jobs/**` 也统一使用该返回壳。

统一登录说明：

- 登录入口仅保留：`POST /api/auth/login`。
- Web 登录：`username/password`（`loginType` 为空或 `web`）。
- 桌面登录：`username/password + loginType=desktop + clientId`。
- 桌面登录仅允许 `admin`、`operator` 角色，且 `clientId` 必须绑定到当前账号。

桌面 SDK 环境变量：

- `MATERIAL_OPS_DESKTOP_USERNAME`：桌面端登录用户名，默认 `admin`。
- `MATERIAL_OPS_DESKTOP_PASSWORD`：桌面端登录密码，默认 `Admin@123`。
- `MATERIAL_OPS_CLIENT_ID`：桌面客户端 ID，默认 `desktop-demo`。

新增页面/菜单开发约定：

- 新增 Web 菜单对应的后端接口，必须复用同一返回壳（`code/data/error/message`）。
- 列表接口建议放入 `data.items`，与现有页面保持一致，便于通用表格组件复用。
- 所有页面按钮必须使用中文，包括新增、编辑、删除、保存、取消、查询、重置、回滚、发布等操作，不允许直接出现英文按钮文案。
- 表格操作、弹窗标题、表单占位、状态标签、确认提示也应保持中文，避免同一页面中英文混用。

## 桌面端

- `desktop_client/`：可复用云端 SDK 和任务运行骨架。
- `desktop_app/`：从旧 PyQt6 项目复制后独立改造的新桌面端。

桌面端升级支持“整体包 + 最多 3 个拆分模块”。当基础客户端、处理核心、采集发布适配包一起变化时发布 `full-client` 整体升级包；只改局部时发布 `core-client`、`processor-core`、`ops-adapter-pack` 对应模块，桌面端会后台下载并校验对应升级包。