PilotPilot AI 项目协作空间

基于提供的 demo-B-协作空间.html、技术架构、实施方案和 Excel 项目清单实现的本地项目管理应用。

启动

本机依赖已安装后，在项目目录运行：

.\start.ps1

打开 http://127.0.0.1:5173。脚本后台启动 Go 项目服务、Python AI 服务和 Vite 前端，日志位于 .logs/。 停止由此脚本启动的进程：.\stop.ps1。重新编译后启动：.\start.ps1 -Build（先停止旧服务）。

首次打开会进入管理员初始化页。请自行设置首个管理员账号和至少 8 位密码；系统不会内置默认密码。后续使用该账号登录，登录态保存在 HttpOnly Cookie 中。

首次在另一台 Windows 电脑安装：

# 安装 Node.js 22.12+ 或 24、Go 1.24+、Python 3.11+ 后：
npm --prefix frontend ci
python -m venv ai-service/.venv
.\ai-service\.venv\Scripts\python.exe -m pip install -r ai-service/requirements.txt
.\start.ps1

前端使用 React 18、TypeScript、Vite 和 Ant Design 弹窗组件；原型 CSS 完整提取到 frontend/src/demo.css。 其余新增页面状态、表单与窄屏适配放在 frontend/src/app.css，没有改动原始 demo。

可用功能

• 协作首页：实时项目统计、状态分布、项目元数据完整度矩阵、多维分组、状态清单跳转。
• 项目空间：27 条真实项目初始记录、卡片/列表、筛选搜索、项目新建编辑删除、收藏、CSV 导出。
• 项目详情：10 项 Excel 元数据及补充管理字段、WBS / 里程碑、交付物版本上传下载、任务、团队名单、评论、统计。
• WBS 与甘特图：支持管理员维护版本化里程碑模板，项目内可筛选模板、选择条目、映射负责人并按起始日期批量导入；同时支持里程碑下最多 6 层任务拆解、组合/WBS 列表/甘特专注视图、周月缩放、筛选、进度、今日线、FS 依赖、关键路径和计划基线。
• 任务大厅：创建任务、领取、提交验收、退回、验收通过、取消，支持列表/五列看板与我的任务。
• 用户与权限：管理员维护用户、角色和权限；admin 拥有最高权限，系统阻止删除或降级最后一名管理员。
• 项目负责人：内置 project_owner 角色；选择项目责任人时自动授予该角色，只能查看和操作 ownerId 指向自己的一个或多个项目，不能访问其他项目或自行创建项目。
• 人员分配：项目责任人、任务责任人和项目团队都从用户目录选择；一个用户可加入多个项目或复用团队。
• 我的任务：按当前登录账号的 assigneeId 返回任务，不依赖重名的显示名称。
• 智能检索：混合检索数据库记录和交付物正文向量，结果显示文件、版本、页码、Sheet、章节和分块等来源。
• 文件预览：同一交付物的向量片段聚合为一个文件结果；检索页和项目交付物页可直接预览 PDF、图片、文本及 Office 提取内容，并可定位到所属项目交付物。
• 时间排序：节点、里程碑和任务按开始时间升序展示；缺少开始时间时使用完成时间，无日期记录排在最后。
• AI 助手：项目周报、进展汇总、风险问答；明确显示模型生成或本地规则汇总。
• 工时页面：维护项目级投入人天台账。尚未提供按人员逐日填报。
• 动态页面：查看工作区变更记录。

数据规则

Excel AI立项项目清单 中第 2–28 行为 27 个项目，第 29 行是状态说明，不导入。 项目独立 ID 与原始序号分开，保留重复的 14、16。保留“推进中”“进行中”等原始状态。

仅去除文本首尾空白；文本字段的空单元格映射为空字符串。投入人天、拟批复激励保留数值、文本或 null， 不把“/”“1年”“3年”换算为数值。投入统计只累加实际数值。备注中的“已推广”不自动覆盖项目状态。 不虚构 Excel 中没有的负责人、部门、任务、节点或工期。

进度优先使用人工填写值，否则根据有效任务完成率计算；无任务的已完成/已推广项目显示 100%，其他项目保持未知。 WBS 汇总任务和里程碑按子任务工作日工期加权计算进度；旧任务未关联里程碑时保留在“待归类”层级。 “健康矩阵”的纵轴是负责人、部门、开始/结束日期、评审、创值方式、资源、备注 8 项字段完整度，不代表模型预测。 暂停和超过截止日期的未完结项目进入关注列表。源记录未提供业务创建日期，不伪造月度趋势。

本地数据存储在 backend/data/pilotpilot.db 和 backend/data/uploads/。 备份时先停止服务，再一起复制数据库与上传目录。原始附件不被应用修改。

架构与部署

配套文档：

• 技术架构
• 管理员操作手册
• 项目负责人操作手册
• Linux Docker 部署与更新

React + TypeScript (5173)
  /api → Go + Gin + GORM (8080) → SQLite 本地持久化 / 可配置 MySQL
                    ↓ 受保护的 AI 代理
              FastAPI (8081) → 本地向量索引 / 本地规则 / 可配置兼容模型接口

Linux 生产部署采用 Nginx + Go + FastAPI + MySQL 8。数据库、上传原文和向量索引分别使用持久卷。首次部署及从指定仓库 main 分支更新的完整步骤见 DEPLOYMENT.md。

cp deploy/.env.production.example .env
# 编辑 APP_ORIGIN 和 MySQL 密码
bash deploy/update.sh --initial

后续更新只需执行 bash deploy/update.sh；脚本先备份持久数据，再拉取 http://10.10.1.40:3000/xcy/AI_PMP.git 的最新 main、重建容器并检查健康状态。

模型配置使用 LLM_BASE_URL、LLM_MODEL、LLM_API_KEY 环境变量，详见 ai-service/README.md。 默认不会外发项目数据。附件中模型地址和密钥没有写进应用源码，是否连接由部署环境配置决定。

原始交付物保存在 backend/data/uploads/，提取后的正文分块、来源元数据和向量默认保存在 ai-service/data/vector-index.sqlite3。支持 TXT、Markdown、CSV、JSON、DOCX、PDF、XLSX/XLSM、PPTX、HTML 和 XML。扫描图片 PDF 在未配置 OCR 时只建立元数据索引，并明确标记正文不可用。

验证

npm --prefix frontend run build
npm --prefix frontend test
cd backend
go test ./...
cd ../ai-service
.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
.\.venv\Scripts\python.exe -m pytest -q
cd ../frontend
npx playwright test

源数据核对脚本：在安装 openpyxl 的 Python 环境执行 python scripts/audit-source.py，对运行中的 API 逐行核对 270 个字段。 浏览器测试创建独立临时项目并清理，不修改源 27 条记录。

当前交付边界

这是本地多用户可运行版本，已实现账号登录、RBAC 和项目级访问控制；尚未实现企业 SSO、组织租户隔离和外部身份目录同步。 文件按版本保留原文并建立正文分块和向量索引；PDF、图片和文本可直接预览，Office 文件展示索引提取后的结构化正文。扫描件 OCR、专用 reranker 和 pgvector 集群尚未实现。 未配置远程模型时的摘要是本地规则输出，不宣称已调用大模型。

技术方案中的 SSO、MinIO、Kafka、Redis、Kubernetes、监控告警、多租户和性能 SLO 属于后续服务化范围， 本次不把它们标记为已交付或已验收。当前服务仅在回环地址开放，适合本机使用和业务流程验收。

前端构建与入口使用方式参考 Vite 官方文档 和 React createRoot 文档。