Imported from qilirampart/DramaTV-community (
AGENTS.md). Install upstream withnpx skills add qilirampart/DramaTV-community. Copyright stays with the author.
DramaTV 社区项目规则
适用目录：E:\点众\DramaTV社区搭建
项目定位：AI 视频生成社区，后续与画布软件联动，支持作品发布、工作流发布、作者主页、讨论互动和内容派生。
1. 项目目标
这个项目不是普通短视频 feed，也不是单纯官网。
当前目标是构建一个社区产品骨架，覆盖以下核心能力：
- 视频作品浏览
- 工作流浏览
- 作者主页展示
- 评论与互动
- 发布入口
- 与画布软件联动的预留边界
长期目标：
- 作品和工作流双内容体系
- 社区发现、讨论、收藏、关注
- 工作流复制、派生、在画布中打开
- 精选、活动、榜单等运营层
2. 当前阶段判断
当前阶段固定判断为：PGC 冷启动阶段。
当前主线不是深挖画布 runtime，也不是先做复杂 UGC 机制，而是先把社区闭环跑通。
一句话约束：
- 先把社区做成社区
- 再把社区和画布接得更强
3. 当前范围与优先级
3.1 P0 主线
第一阶段只关注 5 个核心页面：
- 社区首页
- 视频详情页
- 工作流详情页
- 作者主页
- 发布页
第一阶段必须优先打通的闭环：
- 首页分发作品与工作流
- 用户进入视频详情页
- 用户从视频详情回到工作流详情
- 用户进入作者主页继续浏览
- 创作者能够发布视频并绑定工作流
- 评论能力至少具备最小闭环
3.2 P1 补强层
- 点赞
- 收藏
- 关注
- 草稿与基础审核
- 工作流发布入口补强
- 作者页聚合优化
3.3 P2 二级增强
- 复制到画布
- 画布 runtime 渐进加载
- 工作流派生链路
- 高级榜单、搜索、推荐
- 复杂通知与大型运营系统
规则：
P2能力可以预留接口位和产品位- 但不能抢占
P0主线排期
4. 当前仓库现状
当前仓库现实状态必须明确：
- 当前正式前端主线已经是
apps/web下的Next.js + React + TypeScript - 当前正式后端主线已经是
apps/server下的Spring Boot - 根目录旧的
React + Vite页面原型已归档到archive/legacy-react-vite-prototype - AI、媒体、工作流相关异步处理继续由
Python Worker / FastAPI承担
规则：
- 正式开发、联调、验收统一以
apps/web+apps/server这套全链路工程为准 - 旧原型只作为早期页面探索归档，不再承接新需求和新接口联调
- 所有新增数据契约、接口命名、模块边界都要直接贴近当前全栈实现
5. 会话恢复入口
每次新会话开始时，按顺序读取：
AGENTS.md.codex/progress.mdmemory/MEMORY.mddocs/README.mddocs/01_总览/社区全栈项目总览与推进路线.mddocs/01_总览/PGC阶段社区主线闭环与优先级.mddocs/02_研究/视频社区竞品研究简表.md中与当前任务相关部分docs/03_架构/社区全栈业务流程.mddocs/03_架构/候选技术栈分析.mddocs/03_架构/社区第一阶段领域模型与服务拆分.mddocs/03_架构/工作流存储与复制机制设计.mddocs/04_实施设计/数据库初版表设计.mddocs/04_实施设计/第一阶段 API 清单.mddocs/04_实施设计/Next.js 页面数据契约.md
如果文档与代码不一致：
- 以代码现状为准
- 在
.codex/progress.md中补记差异
6. 技术栈基线
当前统一基线为：
- 前端：
Next.js + React + TypeScript - 平台后端：
Spring Boot - AI / 媒体 / 工作流处理：
Python Worker / FastAPI - 数据层：
PostgreSQL - 缓存与短状态：
Redis - 异步任务：
Queue - 媒体存储：
Object Storage - 媒体处理：
FFmpeg - 边缘与入口：
Nginx + CDN
规则：
- 页面契约、API 契约、表结构命名都要尽量兼容这套基线
QL / QC等老板口径未确认前，不进入正式代码常量或 API 字段
7. 页面规则
7.1 社区首页
必须解决：
- 用户快速发现作品
- 用户快速发现工作流
- 用户快速进入创作入口
默认包含：
- 推荐流
- 热门内容
- 工作流入口
- 创作入口
- 作者或专题入口
7.2 视频详情页
必须解决：
- 看视频
- 看简介和标签
- 看作者
- 看关联工作流
- 参与评论
7.3 工作流详情页
必须解决：
- 看工作流说明
- 看适用场景
- 看关联作品
- 看作者
- 保留复制或在画布中打开的入口
7.4 作者主页
至少分两个内容区：
- 作品
- 工作流
7.5 发布页
第一阶段必须覆盖：
- 上传视频
- 填写标题和简介
- 绑定工作流
- 添加标签
- 选择分区
- 区分草稿、待审核、已发布等状态
8. 数据模型规则
前期统一围绕这 5 类实体开发：
UserVideoWorkflowFeedItemComment
推荐最小结构：
type User = {
id: string
name: string
avatar: string
bio?: string
}
type Video = {
id: string
title: string
summary?: string
cover: string
videoUrl: string
duration?: number
tags: string[]
authorId: string
workflowId?: string
visibility?: 'public' | 'link' | 'private'
}
type Workflow = {
id: string
title: string
summary?: string
cover?: string
authorId: string
visibility?: 'public' | 'link' | 'private'
allowFork?: boolean
}
type FeedItem = {
id: string
type: 'video' | 'workflow'
targetId: string
}
type Comment = {
id: string
content: string
authorId: string
targetId: string
createdAt: string
}规则：
- 页面实现前先确认依赖哪些实体
- 假数据字段名尽量贴近未来接口
- 同一类信息不允许出现多套命名
9. 服务边界规则
9.1 Spring Boot 负责
- 社区读写 API
- 发布链路与草稿状态
- 评论、关注、收藏、点赞等关系
- 审核状态流转
- 画布联动入口编排
9.2 Python Worker / FastAPI 负责
- 视频预处理
- 封面抽帧
- 预览生成
- AI 相关任务
- 重媒体异步流程
9.3 基础设施侧负责
- 对象存储
- CDN 分发
- 队列削峰
- Redis 短状态
- Nginx 入口转发
规则：
- 不要把重媒体处理塞进主同步请求
- 不要把发布链路和异步处理状态混成一个黑盒接口
10. 安全与负载基线
当前阶段虽然是第一阶段，也必须提前考虑以下基础约束：
10.1 安全
- 上传入口必须预留文件类型校验和大小限制
- 发布链路必须预留审核状态
- 评论内容必须预留风控与敏感内容处理边界
- 鉴权相关能力必须明确游客、登录用户、创作者、运营角色差异
- 不在前端暴露内部对象存储直链策略细节
10.2 负载
- 首页列表默认不全量自动播放
- 资源区分封面、poster、preview、source
- 读多写少页面优先考虑 CDN 与缓存
- 重任务走异步队列，不阻塞主请求
- 发布与复制类链路预留状态查询接口，避免前端长时间阻塞等待
11. 组件规则
优先建立可复用卡片系统，不先堆大页面。
第一批基础组件建议：
VideoCardWorkflowCardCreatorHeaderCommentItemCommentThreadTagSectionHeaderPublishFormSection
规则：
- 展示组件与数据组装逻辑分开
- 同类卡片统一信息层级
- 单页特殊视觉不能破坏组件体系
- 页面由模块组合，不把所有逻辑塞进一个文件
12. 媒体资源规则
社区项目默认把视频视为高风险资源。
规则：
- 首页列表默认不全量自动播放
- 优先使用封面图、poster、短预览
- 区分原视频、预览视频、封面图
- 列表流避免同时加载过多视频
- 正式资源优先走 CDN
- 不把大视频长期混在源码仓库里
推荐媒体结构：
type MediaAsset = {
cover: string
poster?: string
preview?: string
source?: string
}13. 交互状态规则
以下交互必须明确标记状态：
- 登录
- 注册
- 点赞
- 收藏
- 评论
- 关注
- 发布
- 复制工作流
- 在画布中打开
每个交互都必须属于以下三类之一：
- 前端占位
- 已接接口但未完整联调
- 已可用
未接接口的交互，不允许伪装成已完成能力。
14. 画布软件联动规则
这个项目后续会与画布软件联动，当前阶段必须提前预留联动边界。
至少考虑以下能力：
- 从工作流详情页进入画布
- 复制工作流到自己的画布空间
- 作品发布时绑定工作流
- 作品详情页展示来源工作流
规则：
- 当前只保留产品位、接口位和演示链路
- 画布联动不能压过
P0社区主线
15. 进度记录规则
进度统一记录到 .codex/progress.md。
结构固定为：
- 当前快照
- 当前看板
- 追加日志
规则：
- 日志 append-only
- 方向变化时先更新快照
- 中断前必须写明“做到哪一步、卡在哪里、下次先做什么”
16. 经验沉淀规则
经验统一记录到 memory/MEMORY.md。
只记录：
- 已验证有效的方法
- 已确认重复出现的问题
优先沉淀的经验类型：
- 卡片信息密度
- 视频加载策略
- 评论区性能
- 工作流与视频绑定方式
- 移动端社区阅读体验
17. 质量门槛
任何页面进入完成态前，至少检查：
- 主路径是否可用
- 桌面端是否可读
- 移动端是否可读
- 卡片信息层级是否清楚
- 假数据或占位是否明确标注
- 资源体积是否明显失控
- 是否为下一步留出清晰入口
18. 当前产品方向约束
基于竞品研究，当前方向固定为：
- 首页像内容社区，不像官网
- 工作流是一级内容，不是附件
- 作者主页同时展示作品和工作流
- 社区不只展示结果，也展示方法
- 当前先建立
PGC闭环，再扩展到PUGC / UGC - 后续允许复制、派生、联动画布
不做以下错误方向：
- 做成普通短视频平台
- 工作流只做下载附件
- 首页做成大而全工具导航站
- 过早做复杂交易和审核体系
- 让二级增强功能持续抢占
P0主线排期
19. 当前核心文档清单
本项目当前核心文档：
docs/README.mddocs/01_总览/社区全栈项目总览与推进路线.mddocs/01_总览/PGC阶段社区主线闭环与优先级.mddocs/02_研究/视频社区竞品研究简表.mddocs/03_架构/社区全栈业务流程.mddocs/03_架构/候选技术栈分析.mddocs/03_架构/社区第一阶段领域模型与服务拆分.mddocs/03_架构/工作流存储与复制机制设计.mddocs/04_实施设计/数据库初版表设计.mddocs/04_实施设计/第一阶段 API 清单.mddocs/04_实施设计/Next.js 页面数据契约.mdAGENTS.md.codex/progress.mdmemory/MEMORY.md
20. 可观测性与链路追踪规则
进入全链路开发阶段后，排障能力必须和功能开发一起建设，不能等出问题后再补。
20.1 requestId 贯穿规则
- 所有前端到后端的业务请求都应带
X-Request-Id - 后端必须把同一个
requestId写入响应和日志 - 前端报错提示、控制台报错、联调截图里优先保留
requestId - 没有
requestId的问题，默认视为排障信息不完整
20.2 关键业务标识透传规则
以下链路的日志和错误上下文，至少应补齐业务标识中的相关字段：
userIdvideoIdworkflowIddraftIdcommentIdruntimeIdcopyTaskIdmoderationTaskId
规则：
- 业务标识优先以后端真实解析结果为准，不盲信前端透传
- 发布、复制、审核、上传、评论、联动画布这几条链路，日志里不能只有一句“失败了”
- 轮询、健康检查、心跳类请求要控制日志噪音，不能淹没主业务日志
21. 错误码与日志规则
21.1 错误码映射规则
- 上传、画布联动、审核、第三方媒体服务等链路，必须先映射为项目内部错误码，再返回前端
- 前端拿到的应是“可显示文案 + 错误码 + requestId”，不是第三方原始报错
- 未知异常也必须落到统一兜底错误码，不能把堆栈或原始异常文案直接透出
- 不允许长期使用裸
IllegalArgumentException文案充当正式业务契约
21.2 日志落地规则
- 本地和测试环境都要使用固定日志路径与稳定文件名
- 日志至少区分访问日志、应用日志、错误日志，避免所有内容混到一个输出文件
- 日志必须可滚动切分，不能长期依赖单个控制台输出或
nohup.out风格文件 - 新增后台脚本、异步任务、Worker 任务时，同步考虑日志文件归档与定位方式
21.3 敏感信息保护规则
- 禁止把
Authorization、登录态 token、上传 token、对象存储签名、第三方密钥直接打进日志 - 禁止把超大 prompt、原始工作流 JSON、完整请求体默认整包写日志
- 第三方返回的原始错误、堆栈、HTML 响应体不直接透给前端
22. Bug 反馈与复现信息规则
任何进入排查队列的问题，至少补齐以下信息：
- 发生时间
- 环境信息：本地 / 测试 / 线上
- 账号标识或用户备注
- 设备、系统、浏览器
- 访问页面与路由
- 操作步骤
- 实际结果与预期结果
- 截图或录屏
requestId
如果问题涉及具体业务对象，还应补充相关 ID：
videoIdworkflowIddraftIdcommentIdruntimeIdcopyTaskId
规则：
- 没有时间、路由、步骤、
requestId的问题，不应直接进入“后端先查一下” - 前端后续要为关键失败态预留“复制错误信息 / requestId”入口，降低沟通成本
- 团队内部讨论问题时，优先贴结构化信息，不只贴一张局部截图