90707005ed
- 项目详情页三阶段里程碑管理(前期/制作/后期) - 制作卡片改用180px ECharts圆环进度图+右侧数据列表 - 修复损耗率双重计算bug(测试秒数不再重复计入超产) - 新增飞书推送服务、豆包AI风险分析、APScheduler定时报告 - 项目列表页增强(筛选/排序/批量操作/废弃功能) - 成员详情页产出时间轴+效率对比 - 成本页固定开支管理 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
308 lines
11 KiB
Markdown
308 lines
11 KiB
Markdown
# AirLabs Project 项目总结文档
|
||
|
||
> 内容组 · 项目制周期 / 成本 / 产出管理系统
|
||
> 更新日期：2025-02-11
|
||
|
||
---
|
||
|
||
## 1. 项目概述
|
||
|
||
### 1.1 定位
|
||
|
||
服务于**以 AI 动画/视觉内容为核心产出的内容团队**（约 30 人以内）的内部管理系统。
|
||
|
||
**核心价值**：以项目为核心，以内容提交为最小记录单位，自动汇总产出、进度、成本与损耗，支持项目完成后统一结算。
|
||
|
||
### 1.2 解决的核心问题
|
||
|
||
- 项目**实际投入成本**不可见
|
||
- 实际产出是否匹配项目目标
|
||
- 测试与损耗占比无法量化
|
||
- 项目超期难以追踪
|
||
- 项目结束后是否盈利
|
||
|
||
### 1.3 覆盖范围（V1）
|
||
|
||
- 内容组、内容类项目、动画/视觉内容生产
|
||
- PC 端 Web 应用（预留响应式，V2 适配移动端）
|
||
- **不包含**：产品研发周期、精细工时、人事绩效、审批验收、移动端专属适配
|
||
|
||
---
|
||
|
||
## 2. 技术架构
|
||
|
||
| 层级 | 技术选型 | 说明 |
|
||
|------|----------|------|
|
||
| 前端 | Vue 3 + Element Plus + Vite | 后台管理 UI |
|
||
| 后端 | Python FastAPI | 高性能 API |
|
||
| 数据库 | SQLite | 零配置，MVP 适用 |
|
||
| 图表 | 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）
|
||
|
||
- 提交人、所属项目、项目阶段、工作类型（制作/测试/方案）
|
||
- 内容制作类型（内容制作/设定策划/剪辑后期/其他）
|
||
- 产出时长（分钟/秒，换算为 total_seconds）
|
||
- 投入时长（小时，可选）
|
||
- 提交对象（组长/制片/内部/外部）
|
||
- 提交日期
|
||
|
||
---
|
||
|
||
## 4. 业务逻辑
|
||
|
||
### 4.1 成本结构
|
||
|
||
| 成本类型 | 计算方式 |
|
||
|----------|----------|
|
||
| **人力成本** | 按提交自动分摊：有秒数按秒数比例，无秒数按条数比例；支持 CostOverride 手动调整 |
|
||
| **AI 工具成本** | 指定项目 / 内容组整体（按产出秒数分摊）/ 手动分摊 |
|
||
| **外包成本** | 按项目直接归属 |
|
||
| **固定开支** | 办公室租金、水电费，按项目产出秒数比例分摊 |
|
||
|
||
### 4.2 损耗（Waste）与亏损（Loss）
|
||
|
||
**概念区分：**
|
||
|
||
- **损耗**：生产效率指标（测试试错 + 超产废片），盈利项目也有
|
||
- **亏损**：财务结果（总成本 > 回款），仅客户正式项目
|
||
|
||
**损耗计算：**
|
||
|
||
- **测试损耗**：工作类型为「测试」的提交秒数
|
||
- **超产损耗**：累计提交秒数 − 目标秒数（>0 部分）
|
||
- **废弃项目**：全部产出直接记为损耗，损耗率 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 新增 |
|
||
|
||
---
|
||
|
||
## 12. 已知待办 / 待完善
|
||
|
||
- **历史修改记录**：后端已有 `SubmissionHistory`，前端完整展示与 diff 对比可完善
|
||
- **数据导出**：PRD 提到 V2 支持 Excel/PDF，当前未实现
|
||
- **移动端适配**：V2 计划
|
||
- **数据库升级**：若用户量增长，可迁移至 PostgreSQL
|
||
- **AI 智能问答**：V3 计划，前端聊天页面 + 自然语言查询
|
||
- **按权限分级推送**：V3 计划，不同角色收到不同报告内容
|
||
|
||
---
|
||
|
||
## 13. 默认账号
|
||
|
||
- 首次启动自动创建：`admin` / `admin123`（超级管理员）
|
||
|
||
---
|
||
|
||
*本文档用于项目交接、复盘与后续迭代参考。*
|