# video

**Repository Path**: gitmc/video

## Basic Information

- **Project Name**: video
- **Description**: 灵境工坊，主要自己用来创建audio的
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-30
- **Last Updated**: 2026-05-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 灵镜工坊 — 项目说明与开发规则

**副标：** 音视频创作与分发工作台  

面向本仓库协作与 Cursor / Agent 的约定。修改代码前请先通读 **Rules** 小节。

## 概览

单体仓库，主要包含：

| 目录 | 说明 |
| --- | --- |
| `client/` | Vue 3 + TypeScript + Vite 前端；Ant Design Vue；`pnpm` |
| `server/` | Egg.js（tegg，`@HTTPController`）后端；`npm`；默认 `http://localhost:7001` |
| `docs/` | VitePress 文档站（可选） |

业务域：视频发现（Top10）、内容分析、运营素材、渲染任务、账号会话与上传任务；另有 `transcribe` 模块（视频链转写字幕）。

---

## Rules（必须遵守）

### 仓库与包管理

- **前端** `client/`：使用 **pnpm**（见该目录 `packageManager` 字段）。脚本：`pnpm dev` / `pnpm build`。
- **后端** `server/`：使用 **npm**。脚本：`npm run dev`（开发）、`npm run lint`、`npm run typecheck`、`npm run build`。
- **Node**：后端 `package.json` 要求 `>=22.18.0`；本地开发以该版本为准。
- 根目录无统一 `package.json`；前后端分别在各自目录安装依赖。

### 联调与配置

- 前端默认请求基址 **`http://localhost:7001`**，与 `client/src/shared/utils/http.ts` 中 `getBaseUrl()` 一致。
- 覆盖方式：在 `client/` 下复制 `.env.example` 为 `.env`，设置 `VITE_API_BASE_URL`（见 `client/README.md`）。
- 后端 MySQL：`config.default` 下需 `MYSQL_HOST` 等环境变量才启用；若存在 **`.runtime/mysql.local.json`**（见 `server/config/config.local.ts`），本地会合并 `egg-mysql`。**注意：`egg-mysql` 启动时会连库自检，连不上会导致进程直接退出**。依赖 **`@eggjs/rds`** 时，默认 **`connectTimeout` / `poolWaitTimeout` 仅约 500ms**，远程 RDS 易出现 `PoolWaitTimeoutError`；仓库已把默认提高到 **20s**，也可用环境变量覆盖：`MYSQL_CONNECT_TIMEOUT_MS`、`MYSQL_POOL_WAIT_TIMEOUT_MS`。排查：把 `host` 改为可达地址、检查安全组/VPN；临时只想起服务可设 **`MYSQL_DISABLE_PLUGIN=true`**（依赖库的 Studio 接口会不可用）。可选：`MYSQL_REQUIRE=true` 影响 `app.ts` 自测是否因连库失败而抛错。
- 转写相关：`VOSK_MODEL_DIR`、`TRANSCRIBE_SCRIPT_PATH`、`PYTHON_BIN` 等见 `server/config/config.default.ts` 中 `bizConfig.transcribe`。

### API 与安全约定

- 对外 HTTP API 统一前缀 **`/api`**（例如 `/api/video/top10`、`/api/video/analyze`）。新增接口保持该前缀。
- 当前 `config.default.ts` 对 **`/api/*` 忽略 CSRF**，并启用 **CORS** 中间件，适用于本地联调。**对外部署前**应收紧跨域、CSRF 与鉴权策略；勿把本地联调配置直接当生产方案。
- 错误响应：后端控制器使用 `toHttpErrorPayload` 等统一形态；前端 `httpGet` / `httpPost` 解析 `{ error?, code? }` 并抛出 `HttpError`。

### 后端代码结构（Egg / tegg）

- 模块在 `server/app/module/` 下注册，`server/config/module.json` 列出路径（当前含 `transcribe`、`foo`）。
- **控制器**：`@HTTPController({ path: '/api' })` + `@HTTPMethod`；注入 Service；入参校验使用 `shared/validators.ts`；错误映射使用 `shared/errors.ts`。
- **服务**：`app/module/foo/service/*.ts`；从 `index.ts` 导出供控制器与其它层引用。
- 导入路径示例：项目内使用带 `.ts` 后缀的路径（与现有文件一致），不要随意改为无后缀除非全仓统一变更。

### 前端代码结构（Vue 3）

- **路由**：`client/src/app/router.ts`。Studio 模式下包含 `/projects`、`/tasks/...`、鉴权页等；关闭 Studio（`VITE_STUDIO_ENABLED=false`）时 legacy 路由仍以 `/discover` 等为入口。
- **功能按域分目录**：`src/features/<feature>/`（`pages/`、`components/`、`api/`、`model/`、`types.ts` 等）。新增页面优先放入对应 feature，不要堆在根 `components/`。
- **共享代码**：`src/shared/`（`utils/`、`constants/`、`model/`）。
- **UI**：全局已注册 **Ant Design Vue**；布局与导航参考 `src/app/AppLayout.vue`。
- **HTTP**：统一使用 `src/shared/utils/http.ts` 的 `httpGet` / `httpPost`，避免散落裸 `fetch` 且不写基址。
- 构建：`pnpm build` 会跑 `vue-tsc -b` 再 `vite build`，新增代码需通过类型检查。

### Git 与大文件

- `.gitignore` 忽略 `node_modules/`、常见音视频与转写产出、`vosk-model-*` 等大资源；大模型路径优先用环境变量，勿提交仓库。

### 文档

- 除非任务要求，**不必**为每次小改动新增或扩建 README；接口清单以 `server/README.md` 与地面真实路由为准，变更时同步该文件中的 API 说明。

---

## 常用命令速查

```bash
# 前端（client）
cd client && pnpm install && pnpm dev

# 后端（server）
cd server && npm install && npm run dev

# 文档（docs）
cd docs && pnpm install && pnpm dev
```

---

## 扩展时的检查清单

1. 新 API：是否挂在 `/api` 下、错误格式是否与前端 `HttpError` 一致？
2. 前端：是否复用 `http.ts`、类型与路由 meta 是否更新？
3. 后端：是否在 `module.json` 注册新模块（若新增模块目录）？
4. 环境变量与安全：生产场景是否收紧 CSRF/CORS 与鉴权？
5. 提交前：对应子项目能否通过 `pnpm build` / `npm run lint`（及 `typecheck`）？