# 00 · 交接导览（先读我）

LLMS 索引： [llms.txt](/llms.txt)

---

> 本目录是 QMTV 项目开发文档集，面向开发/运维的同事。建议按顺序阅读，全程约 30 分钟即可建立完整认知并跑起项目。

## 项目速览卡

| 项 | 值 |
|---|---|
| 项目名 | QMTV — AI 短剧智能生产线 |
| 位置 | `D:\WORK\GAE\qmtv`（本目录） |
| 技术栈 | Node.js 22 + Express 5 + better-sqlite3（后端）；Vue 3 + Vue Router 4 + Vite 8（前端）；无 UI 框架，自研主题 |
| 启动 | `npm install` → `npm start`（后端 :3300 并托管前端 dist）→ `npm run build`（构建前端） |
| 数据库 | `data/qmtv.db`（SQLite WAL，49 张表，免安装） |
| 规模 | 后端 24 个模块 / 5436 行，239 个 API；前端 24 个页面 / 约 9000 行 |
| 设计文档（历史全量） | `D:\WORK\GAE\QMTV网站设计文档.md`（22 节，按 v1→v22 版本演进记录每一步设计决策与实测结论） |

## 文档地图

| 文档 | 内容 | 什么时候读 |
|---|---|---|
| **01-系统设计方案.md** | 产品定位、功能全景、各模块设计方案、数据模型、计费模型、AI 链路设计、视觉体系 | 想理解"为什么这样设计" |
| **02-系统架构介绍.md** | 技术栈、目录结构、后端模块职责、前端结构、49 张表清单、关键机制（SSE/供应商适配/启动恢复）、构建部署 | 想理解"代码怎么组织的" |
| **03-系统开发说明.md** | 环境准备、启动步骤、账号、日常开发操作指南（加页面/加接口/加表）、验证方法、踩坑清单、运维注意 | 动手开发前必读 |
| **04-待开发功能与规划.md** | 真实模型接入清单、已知欠账与改进项、建议优先级 | 排后续开发计划 |
| **05-API接口速查手册.md** | 全部 239 个 API 按模块分组 | 写代码时当字典查 |

## 30 分钟上手路径

1. （5 分钟）读本文档 + `02-系统架构介绍.md` 的目录结构一节
2. （5 分钟）`npm install`，两个终端分别 `npm start` 和 `npm run dev`（前端热更 :5173，代理到 :3300）
3. （5 分钟）用制片账号登录 `producer@xingmang.cn / demo123456`，把主导航每一页点一遍；再用管理员 `admin@qmtv.com / admin123456` 看管理后台
4. （10 分钟）读 `03-系统交接说明.md` 的「常见开发任务怎么做」与「踩坑清单」
5. （5 分钟）浏览 `04-待开发功能与规划.md`，确定你的第一个任务

## 三条最重要的经验（先记住再说）

1. **发中文请求调试一律写 Node 脚本**（仓库里有大量 `verify_*.js` 可参照），不要用 curl/heredoc——Git Bash 下中文会 GBK 损坏，曾数次被误判为 bug。
2. **数据库是SQLite 单文件**，改表结构统一走 `server/db.js` 的 migrations 数组（`ALTER TABLE ... ADD COLUMN`，try/catch 幂等），**不要**手改已有 CREATE TABLE。
3. **所有生成动作都走积分**：先 `tryDeduct` 再调 `providers.imageSmart/videoSmart`，失败退款由 providers 内部统一负责，调用方不要重复退款。生成类入口只此一个约定，接手时务必遵守。

---

反链：

- [产品](/qmtv/product/)