airlabs-manage/项目总结文档.md

AirLabs Project 项目总结文档

内容组 · 项目制周期 / 成本 / 产出管理系统
更新日期：2026-02-14

---

1. 项目概述

1.1 定位

服务于以 AI 动画/视觉内容为核心产出的内容团队（约 30 人以内）的内部管理系统。

核心价值：以项目为核心，以内容提交为最小记录单位，自动汇总产出、进度、成本与损耗，支持项目完成后统一结算。

1.2 解决的核心问题

• 项目实际投入成本不可见
• 实际产出是否匹配项目目标
• 测试与损耗占比无法量化
• 项目超期难以追踪
• 项目结束后是否盈利

1.3 覆盖范围（V1）

• 内容组、内容类项目、动画/视觉内容生产
• PC 端 Web 应用（预留响应式，V2 适配移动端）
• 不包含：产品研发周期、精细工时、人事绩效、审批验收、移动端专属适配

---

2. 技术架构

层级	技术选型	说明
前端	Vue 3 + Element Plus + Vite	后台管理 UI
后端	Python FastAPI	高性能 API
数据库	MySQL 8.0（阿里云 RDS）	生产环境；本地开发可回退 SQLite
图表	ECharts	仪表盘可视化
认证	JWT Token	登录鉴权与权限控制

2.1 部署

• CI/CD：Gitea Actions 自动构建
• 镜像：Docker 构建，推送到华为云 SWR
• 运行：K3s 集群，通过 Ingress 暴露服务
• 前端：静态构建后由后端统一托管（/ 路径返回 index.html）

2.2 目录结构

AirLabs Project/
├── backend/              # FastAPI 后端
│   ├── main.py           # 入口、静态文件托管、角色初始化
│   ├── models.py         # ORM 模型、枚举、权限定义
│   ├── calculations.py   # 成本分摊、三阶段损耗、效率、结算计算引擎
│   ├── config.py         # 配置
│   ├── database.py       # SQLAlchemy 引擎与会话
│   ├── auth.py           # 密码哈希、JWT
│   ├── schemas.py        # Pydantic 模型
│   └── routers/          # API 路由
│       ├── auth.py       # 登录、me
│       ├── users.py      # 用户 CRUD
│       ├── projects.py   # 项目 CRUD、完成、结算、效率
│       ├── submissions.py# 内容提交 CRUD、历史
│       ├── costs.py      # AI 工具、外包、人力调整、固定开支
│       ├── dashboard.py  # 仪表盘
│       └── roles.py      # 角色、权限
├── frontend/             # Vue 3 前端
│   └── src/
│       ├── views/        # 页面：Dashboard, Projects, ProjectDetail, Submissions,
│       │                 # Costs, Users, MemberDetail, Roles, Settlement, Login
│       ├── api/index.js  # 接口封装
│       ├── stores/auth.js# 用户状态
│       └── router/       # 路由与权限守卫
├── k8s/                  # K8s  manifests
├── .gitea/workflows/     # 部署流程
└── 人员清单.md           # 团队成员与薪资

---

3. 核心数据模型

3.1 项目（Project）

字段	说明
name	项目名称
project_type	客户正式/客户测试/内部原创/内部测试
status	制作中 / 已完成 / 废弃
leader_id	负责人
current_phase	前期/制作/后期
episode_duration_minutes	单集正片时长（分钟）
episode_count	集数
target_total_seconds	目标总秒数（计算属性 = 单集×集数×60）
estimated_completion_date	预估完成日期
actual_completion_date	实际完成日期
contract_amount	回款金额（客户正式项目）

3.2 用户（User）

• 姓名、用户名、所属阶段组（前期/制作/后期）
• 角色、月薪、社保、奖金
• 日成本 = (月薪+奖金+社保) ÷ 22 个工作日

3.3 内容提交（Submission）

• 提交人、所属项目、项目阶段、工作类型（制作/测试/方案）
• 内容制作类型（11 种，按阶段分组）
  • 前期：策划案 / 剧本 / 分镜 / 人设图 / 场景图
  • 制作：动画制作
  • 后期：配音 / 音效 / 修补镜头 / 剪辑
  • 其他
• 产出时长（分钟/秒，换算为 total_seconds）
• 投入时长（小时，可选）
• 提交对象（组长/制片/内部/外部）
• 提交日期
• milestone_id（系统自动关联：根据内容类型匹配同名里程碑）
• delay_reason（延期原因：里程碑超期时必填）

3.4 项目里程碑（ProjectMilestone）

• 所属项目、名称、所属阶段（前期/后期）
• is_completed（是否完成）、completed_at（完成日期）
• estimated_days（预估工作日）
• start_date（开始日期）
• actual_days（计算值 = 开始到完成/今天的工作日数，排除周末）
• is_overdue（计算值 = 实际 > 预估）
• 默认里程碑：前期 5 个（策划案/剧本/分镜/人设图/场景图）+ 后期 5 个（配音/音效/修补镜头/剪辑/杂项）

---

4. 业务逻辑

4.1 成本结构

成本类型	计算方式
人力成本	按提交自动分摊：有秒数按秒数比例，无秒数按条数比例；支持 CostOverride 手动调整
AI 工具成本	指定项目 / 内容组整体（按产出秒数分摊）/ 手动分摊
外包成本	按项目直接归属
固定开支	办公室租金、水电费，按项目产出秒数比例分摊

4.2 损耗（Waste）与亏损（Loss）

概念区分：

• 损耗：生产效率指标，盈利项目也有
• 亏损：财务结果（总成本 > 回款），仅客户正式项目

三阶段损耗计算体系：

阶段	计算方式	损耗指标
前期	工时制	里程碑超期天数 × 8h
制作	秒数制	测试损耗 + 超产损耗
后期	工时制	里程碑超期天数 × 8h

• 前期损耗：遍历前期里程碑（策划案/剧本/分镜/人设图/场景图），有预估工期且已完成/超期的，超出天数 × 8h = 损耗工时
• 制作损耗：测试损耗（work_type=测试且phase=制作的秒数）+ 超产损耗（制作产出+修补镜头 − 目标秒数的超出部分）
• 后期损耗：剪辑等里程碑按工时计算；修补镜头秒数已计入制作损耗；配音/音效不计损耗
• 废弃项目：全部产出直接记为损耗，损耗率 100%

秒数损耗率 = (测试损耗 + 超产损耗) ÷ 目标秒数 × 100% 工时损耗 = 前期超期工时 + 后期超期工时

4.3 团队效率（人均基准对比法）

• 人均基准 = 目标秒数 ÷ 参与制作人数
• 超出比例 = (个人提交 − 人均基准) ÷ 人均基准 × 100%

4.4 进度计算

• 完成百分比 = 当前有秒数提交的累计秒数 ÷ 目标总秒数 × 100%
• 仅统计有产出秒数的提交（制作组 + 后期补拍）

---

5. 权限体系

角色	可见范围	典型权限
超级管理员	全量	全部
主管	所有项目	dashboard, project CRUD+complete, submission, cost, settlement, efficiency
组长	所负责项目	project view+create, submission, cost, efficiency
成员	本人提交、项目公开信息	project view, submission

权限标识：dashboard:view, project:view/create/edit/delete/complete, submission:view/create, cost:view/create/delete, user:view/manage, role:manage, settlement:view, efficiency:view

---

6. 前端页面与路由

路径	页面	权限
/login	登录	公开
/dashboard	仪表盘	dashboard:view
/projects	项目列表	project:view
/projects/:id	项目详情、提交、损耗、进度	project:view
/submissions	提交记录	submission:view
/costs	成本管理（AI/外包/固定开支/人力调整）	cost:view
/users	用户管理	user:manage
/users/:id/detail	成员详情	user:view
/roles	角色管理	role:manage
/settlement/:id	项目结算	settlement:view

项目详情页操作：编辑、确认完成（制作中→已完成）、标记废弃（制作中→废弃）、查看结算（已完成）

---

7. 废弃项目特性（近期新增）

• 状态：ProjectStatus.ABANDONED = "废弃"
• 含义：项目中途停止，不再继续制作
• 损耗：全部产出记为损耗，损耗率 100%
• 操作：
  • 项目详情页「标记废弃」按钮（仅制作中可见）
  • 编辑表单中状态下拉增加「废弃」选项
• 仪表盘：废弃项目纳入总损耗统计、成本构成统计、损耗排行

---

8. 人员与团队（来自 人员清单.md）

• 22 人：主管 3、组长 4、组员 15、Owner 2
• 职位涵盖：总导演、AI 导演、制片、动画制作、剪辑、编剧等
• 薪资与社保已录入，用于人力成本计算

---

9. PRD 与实现对照

PRD 要求	实现情况
项目管理（创建/编辑/状态/目标）	✅
内容提交表单	✅
项目详情（进度、提交、损耗）	✅
人力/AI/外包/固定开支成本	✅
仪表盘	✅
项目结算、盈亏	✅
废弃项目	✅（PRD 未写，实际补充）
登录与 4 级权限	✅
历史修改记录（版本追溯、修改原因）	⚠️ 部分（有 SubmissionHistory 表与 history 接口，前端展示待完善）
用户管理（新增/编辑/薪资）	✅

---

10. AI 能力模块（V2 新增）

10.1 技术架构

FastAPI 后端
  ├── services/ai_service.py        # 豆包模型调用（OpenAI 兼容协议）
  ├── services/report_service.py    # 报告数据汇总 + AI 摘要
  ├── services/feishu_service.py    # 飞书自建应用消息推送
  ├── services/scheduler_service.py # APScheduler 定时任务
  └── routers/reports.py            # 手动触发报告 API
          ↓                    ↓
    豆包 AI (ARK)         飞书开放平台
    生成报告摘要           私聊推送给管理员

10.2 功能清单

功能	说明
自动日报	每天 20:00，今日提交、项目进展、风险提醒
自动周报	每周五 20:00，项目进展、团队产出、成本概览
自动月报	每月1日 10:00，上月完整数据、成本明细、盈亏
项目风险预警	仪表盘展示，规则引擎检测超期/进度/损耗/停滞
手动触发	POST /api/reports/{daily,weekly,monthly}，调试用
报告预览	POST /api/reports/preview/{type}，不推送仅预览

10.3 新增依赖

包	用途
openai	豆包 AI 调用（兼容协议）
httpx	飞书 API 异步请求
apscheduler	定时任务调度
python-dotenv	.env 配置文件

10.4 配置项

通过 backend/.env 配置：

• ARK_API_KEY — 豆包 API Key
• ARK_MODEL — 模型名称
• FEISHU_APP_ID / FEISHU_APP_SECRET — 飞书应用凭证
• REPORT_RECEIVERS — 接收人手机号（逗号分隔）

---

11. PRD 与实现对照（更新）

PRD 要求	实现情况
项目管理（创建/编辑/状态/目标）	✅
内容提交表单	✅
项目详情（进度、提交、损耗）	✅
人力/AI/外包/固定开支成本	✅
仪表盘	✅
项目结算、盈亏	✅
废弃项目	✅（PRD 未写，实际补充）
登录与 4 级权限	✅
历史修改记录	⚠️ 部分
用户管理	✅
AI 自动报告 + 飞书推送	✅ V2 新增
项目风险预警	✅ V2 新增
三阶段损耗计算（前期工时/制作秒数/后期工时）	✅ V1.1 新增
内容类型细化（4→11 种）	✅ V1.1 新增
里程碑管理（预估/实际天数、超期检测）	✅ V1.1 新增
提交自动关联里程碑 + 超期延期原因	✅ V1.1 新增
仪表盘双色进度条（超产可视化）	✅ V2.1 新增
工时损耗展示（仪表盘+项目进度+tooltip）	✅ V2.1 新增
提交页延期原因条件显示修复	✅ V2.1 修复
后端 SPA 路由与 API 路由冲突修复	✅ V2.1 修复

---

12. V1.1 三阶段损耗计算体系（近期新增）

12.1 背景

V1 损耗计算仅用「产出秒数 vs 目标秒数」一种方式，无法覆盖前期（策划/人设等）和后期（剪辑等）无法用秒数衡量的工作，导致这些阶段的损耗无法量化。

12.2 改动概要

改动项	说明
内容类型扩展	从 4 种（内容制作/设定策划/剪辑后期/其他）扩展为 11 种，按前期/制作/后期分组
里程碑增强	新增 estimated_days（预估天数）、start_date（开始日期），系统自动计算 actual_days 和 is_overdue
三阶段损耗	前期/后期按工时（天数超期 × 8h），制作保持秒数制（测试 + 超产）
提交关联里程碑	提交时根据 content_type 自动匹配同名里程碑，超期时必须填写延期原因
数据库迁移	启动时幂等 ALTER TABLE 添加 4 个新字段 + 旧 content_type 值映射

12.3 涉及文件

后端：

• models.py — ContentType 枚举扩展、ProjectMilestone 新字段、Submission 新字段、CONTENT_PHASE_MAP
• schemas.py — MilestoneOut/Create/Update、SubmissionCreate/Out 新字段、ProjectOut 新增 waste_hours
• calculations.py — 重写 calc_waste_for_project() 三阶段逻辑，新增 _working_days_between()
• routers/projects.py — enrich_project() 用集中损耗函数、_build_milestone_out()、PUT /milestones/{id}
• routers/submissions.py — 自动关联里程碑、超期校验 delay_reason
• routers/dashboard.py — 损耗汇总兼容 waste_hours
• main.py — 启动迁移（ALTER TABLE + ENUM 扩展 + 旧值映射）

前端：

• views/Submissions.vue — 内容类型分组下拉、自动设置阶段、延期原因字段
• views/ProjectDetail.vue — 里程碑显示预估/实际天数和超期标记、编辑弹窗、损耗拆分展示
• views/Settlement.vue — 损耗分析改为三列分阶段展示
• api/index.js — 新增 updateMilestone 方法

12.4 旧数据兼容

• 旧 content_type 自动迁移：内容制作→动画制作、设定策划→策划案、剪辑后期→剪辑
• 已有项目自动补充"剪辑"里程碑
• 无 estimated_days 的里程碑不参与损耗计算

---

13. V2.1 前端增强与路由修复（2026-02-14）

13.1 仪表盘双色进度条

进度超过 100% 的项目（如品牌方 TVC 258.3%），进度条分为蓝色（目标内）和红色（超出部分），直观反映超产程度。百分比数字在超 100% 时变为红色。

13.2 工时损耗展示

• 总损耗卡片：在总损耗率下方显示工时损耗（如 工时损耗 192h）
• 项目进度条下方：每个项目显示损耗率 + 工时损耗（如 损耗 158.3% · 工时48h）
• 损耗排行图表 tooltip：鼠标悬浮显示秒数损耗和工时损耗

13.3 提交页延期原因修复

修复 Submissions.vue 中延期原因字段始终显示的 Bug（原条件 !== undefined 恒为 true）。改为根据所选项目+内容类型匹配里程碑，仅在里程碑超期时显示红色标签 + 警告 + 必填延期原因。

13.4 后端路由修复

• catch-all SPA 路由拦截 API 请求：main.py 的 /{full_path:path} 会匹配 /api/* 路径（因 API 路由注册时带尾部斜杠 /api/projects/，而请求不带斜杠 /api/projects）。修复：catch-all 对 api/ 开头路径返回 404 + 所有路由改为无尾部斜杠（@router.get("")）+ 前端 API 调用同步去掉尾部斜杠。

13.5 演示数据（seed_demo.py）

重写种子数据，覆盖 5 个项目、4 种类型、32 个里程碑、124 条提交。所有 created_at 设为过去日期，前期结束后才有制作提交，owners/制片不提交，生产速率参照真实情况（60-120s/人/天）。

13.6 涉及文件

后端：

• main.py — 导入 HTTPException，catch-all 增加 API 路径判断
• routers/projects.py — @router.get("") 去尾部斜杠
• routers/users.py — 同上
• routers/submissions.py — 同上
• routers/roles.py — 同上
• routers/dashboard.py — project_summaries 补充 waste_hours 字段
• seed_demo.py — 全面重写

前端：

• api/index.js — 所有 list/create 请求去尾部斜杠
• views/Dashboard.vue — 双色进度条、工时损耗展示、chart tooltip 增强
• views/Submissions.vue — 延期原因计算属性 + 前端校验

---

14. 已知待办 / 待完善

• 历史修改记录：后端已有 SubmissionHistory，前端完整展示与 diff 对比可完善
• 数据导出：PRD 提到 V2 支持 Excel/PDF，当前未实现
• 移动端适配：V2 计划
• 数据库迁移工具：当前用 main.py startup 里的幂等 ALTER TABLE，大规模重构时建议引入 Alembic
• AI 智能问答：V3 计划，前端聊天页面 + 自然语言查询
• 按权限分级推送：V3 计划，不同角色收到不同报告内容

---

15. 默认账号

• 首次启动自动创建：admin / admin123（超级管理员）

---

本文档用于项目交接、复盘与后续迭代参考。