团队项目第一次作业

活动智囊：把校园活动策划从“拍脑袋”变成“可执行”

一次策划会，最贵的不是创意，而是那些没被写下来的细节。

项目 内容
这个作业属于哪个课程 https://edu.cnblogs.com/campus/gdgy/Class78-Grade2024-CS
这个作业要求在哪里 https://edu.cnblogs.com/campus/gdgy/Class78-Grade2024-CS/homework/16767
这个作业的目标 以团队形式完整走一遍软件工程项目流程：完成需求分析与规格说明，实现前端、后端与智能体的协同开发，完成测试排错与文档交付，掌握项目的工程化实现思路，积累团队协作与大模型应用开发经验，为课程后续综合性大项目做好技术储备
团队名称 远航小队
团队成员 3124004449 袁炜轩、3124004439 王安亮、3124004441 王俊霖、3124004451 张帅
项目代码仓库 https://github.com/zs666700/raungong2

一、团队展示

1. 队名

远航小队

“远航”取的是出发和抵达两层意思：一方面，我们做的是一个把活动从“一句想法”推进到“能照着执行”的方案系统，从策划到落地本身就是一段航程；另一方面，对小队四个人来说，前后端协同加智能体接入都是一次全新的技术探索，这次开发也是一次技术上的远航，希望大家一起稳步推进、把项目真正跑起来。

2. 团队项目的具体规划及描述

我们小组本次要开发的项目是校园活动智能策划平台「活动智囊」，接口契约与前端工程名为 activity-mind，代码托管在 GitHub：https://github.com/zs666700/raungong2。

2.1 要解决的问题

校园活动的策划几乎全靠“有经验的人 + 微信群 + 一张 Excel”：

  • 经验不可复制：做过三届迎新晚会的人心里有数，第一次接手的人只能到处问“去年怎么办的”。
  • 方案不完整：多数策划书只有流程和节目单，缺预算明细、物资采购渠道、风险预案、复盘模板；真到执行才发现“灯光没人负责、备用话筒没买、下雨没有 Plan B”。
  • 预算靠估：金额不加总、超支没人发现，报销时才暴露。
  • 一次性的：写完锁在某个人的电脑里，下一届从零开始。

2.2 产品定位与能力

面向高校学生组织（班级、社团、学生会）的在线活动策划工作台：输入 6 个核心参数，几十秒内产出一份结构化、可编辑、可导出、金额自洽的完整方案。它不替代人的判断，负责把“该想到的都摆出来”，把策划从“回忆式写作”变成“填空 + 修改”。

能力 说明
生成 主题 / 类型 / 人数 / 预算 / 时间 / 地点六参数 → 异步生成完整方案
编辑 六大章节按节编辑，乐观锁防并发覆盖
管理 列表、关键词搜索、分页、复制、软删除
交付 一键导出 Markdown，浏览器打印为 A4 PDF

2.3 交付的六大章节

章节 内容要点
策划案 plan 摘要、背景、目标、亮点、成功标准、阶段计划（起止日期）、当日流程 rundown、预算（含应急金与资金来源）
物资清单 materials 品类、规格、单价、数量、小计、采购渠道、负责人、到位时间
分工表 tasks 阶段、角色、负责人、协作人、开始 / 截止时间、优先级、依赖、验收口径
宣传文案 promotion Slogan、关键信息、推文标题正文话题标签、渠道排期、海报三行文案
风险清单 risks 类别、等级、发生概率、影响、触发信号、缓解措施、应急预案、责任人（≥6 条）
复盘模板 review KPI（指标 / 目标值 / 统计方式）、复盘问题、检查清单、可复用模板

2.4 技术方案

层 选型 说明
前端 Vue 3 + Vite + TypeScript + Pinia + Vue Router + Element Plus 组合式 API；页面级状态与登录态分离
后端 FastAPI + SQLAlchemy Async + Pydantic v2 全异步，/docs 即接口文档
数据库 SQLite（开发）/ PostgreSQL（生产） 时间存 UTC、金额存“分”、ID 用 UUID 字符串
智能体 LangGraph 三节点 + DeepSeek + BM25 RAG 三节点分别产出“策划案 + 预算”“物资 + 分工”“宣传 + 风险 + 复盘”，上下文逐级传递
契约 OpenAPI + JSON Schema 前后端以 contracts/ 为准，改接口先改契约
鉴权 JWT（HS256）+ 密码哈希 只允许访问本人数据
导出 前端生成 Markdown，浏览器打印为 PDF 避免服务端中文字体依赖

智能体链路：

POST /plans/generate → 建 plan + task → 202
        ↓ 后台 run_generation()
BM25 检索 knowledge/campus_activity.md
        ↓
节点1 策划案+预算 → 节点2 物资+分工 → 节点3 宣传+风险+复盘
        ↓
content_validator：Schema 校验 + 单价×数量重算 + 预算超支告警
        ↓
plan.status = ready（超时/失败 → 重试 1 次 → 规则模板降级 degraded=true）

2.5 开发分五个阶段推进

阶段 内容 产出
第一阶段 需求梳理，统一对项目的理解，确定契约与验收标准 需求规格说明书、选题报告、OpenAPI、内容 Schema、DDL
第二阶段 优先做后端与智能体模块，单独调试模型链路与校验逻辑 后端骨架、认证、202 任务、Mock / 真实智能体
第三阶段 开发前端页面，完成布局与接口对接 登录、新建、生成中、列表、详情、打印六个页面
第四阶段 前后端联调，编写测试用例，反复测试修 bug 联调记录、接口端到端检查、缺陷修复
第五阶段 整理截图、撰写博客、汇总小组材料 博客、截图、演示数据与演示脚本

规划时刻意控制了功能范围，不去写很难实现的功能，保证文档里写的内容都能在截止时间前落地，不做脱离实际的规划。

3. 队员风采

学号 姓名 性格 擅长的技术 兴趣爱好 团队角色
3124004449 袁炜轩 细心稳重、做事有条理，遇到报错能沉下心一步步排查 Python、接口测试、SQLite 数据核对、日志与缺陷排查 骑行、翻看开源项目与技术文档 测试工程师（测试负责人）
3124004439 王安亮 动手能力强、不怕陌生技术，逻辑清晰，擅长复现问题 Python 基础、本地环境部署、命令行调试、文档与素材整理 研究数码硬件、学习计算机底层知识 博客与文档负责人
3124004441 王俊霖 开朗、擅长沟通，能把模糊想法整理成规范条目，责任心强 Python、FastAPI 接口开发、SQLAlchemy 数据模型、接口契约设计 打羽毛球、浏览技术博客与产品设计 后端开发负责人
3124004451 张帅 执行力强、上手快，能按约定效果完成页面并快速调整 前端页面开发、布局调整、交互效果实现 看影视、玩单机游戏、留意 UI 设计 前端开发

袁炜轩（3124004449）：性格细心稳重，做事有条理，面对报错可以沉下心一步步排查，耐心充足，擅长梳理接口之间的逻辑。熟悉 Python 与 FastAPI 接口结构，能读懂后端实现与接口契约，擅长接口测试、数据一致性与缺陷排查。平时喜欢骑行，也经常翻看各类开源项目和技术文档。在团队中担任测试工程师，负责编写测试用例、执行接口端到端检查、核对金额重算与章节完整性，复现缺陷并跟踪修复结果，按验收标准逐条自测留档。

王安亮（3124004439）：动手能力很强，遇到陌生技术不会畏难，愿意主动查阅资料动手试错，逻辑思路清晰，很擅长复现程序里出现的问题。熟悉 Python 基础、本地开发环境部署、命令行调试，也习惯把过程整理成可读的文字。爱好研究数码硬件，平时会主动学习计算机底层相关知识。在小组里承担博客与文档工作，负责团队博客撰写、需求文档成文与版本维护，汇总截图与演示材料，同时负责本地运行环境部署与演示脚本的准备，保证提交的材料前后一致、能照着操作复现。

王俊霖（3124004441）：性格开朗，擅长沟通，很擅长把模糊零散的想法整理成清晰规范的条目，有不错的责任心，能够协调小组内部对齐口径。擅长 Python 开发、FastAPI 接口开发、SQLAlchemy 异步数据模型，能把需求梳理的功底用在接口契约设计上。课余喜欢打羽毛球，经常浏览技术博客，学习产品设计思路。在团队中是后端开发负责人，负责后端主体框架搭建、认证与方案 / 任务接口、智能体适配与内容校验（金额重算、超支告警）等核心逻辑，并对照 contracts/ 维护接口实现的一致性。

张帅（3124004451）：执行力强，学习新知识上手速度快，能够按照约定的效果完成页面开发，收到修改意见之后可以快速调整页面样式。擅长前端页面开发、页面布局调整、交互效果实现。平时喜欢看影视、玩单机游戏，也会留意各类软件 UI 设计。在项目中负责前端开发，完成登录页、新建方案页、生成中页、方案列表与详情页、打印页的开发与样式优化，并完成与后端接口的对接。

4. 团队的首次合照

eade074305e01ecfc217a422e16b1f6b

5. 团队愿景

我们希望「活动智囊」成为校园里最省事的那份策划书：任何一个第一次接手活动的同学，输入几个参数，就能拿到一份金额算得对、物资买得齐、风险想到了、宣传能直接发的方案；上一届的经验不再随着人毕业而消失，而是沉淀成可复用的模板。也希望通过这次“远航”，把四人协作与智能体开发真正跑通，让它成为我们后续项目的起点。

二、选题报告

1. 选题名称与基本信息

项目 内容
选题名称 活动智囊——校园活动智能策划平台
选题类型 智能体应用类（大模型 + 结构化内容生成）
团队名称 远航小队
团队成员 3124004449 袁炜轩（测试）、3124004439 王安亮（博客与文档）、3124004441 王俊霖（后端）、3124004451 张帅（前端）
开发周期 2026 年 10 月 28 日 — 2026 年 11 月 8 日

2. 选题背景与问题来源

选题来自我们自己在班里办活动的经历。一次班级迎新晚会、一次社团招新，真正耗时间的不是想节目，而是把方案写成别人能照着执行的东西：预算要一项项加、物资要一件件数、谁负责什么要说清楚、下雨了怎么办要提前想。这些活每一届都在重复，却每一届都从零开始。

我们把这个过程里反复出现的四个问题归了一下：

  • 经验停留在个人身上，换人接手就断档；
  • 方案结构不固定，缺预算、缺物资、缺风险预案，执行时才暴露；
  • 金额靠估，不加总、不核对，报销时才发现超支；
  • 写完就锁在本地文件里，第二年无法复用。

这些问题不是靠“写得更认真”能解决的，而是缺一套把结构固定下来、把核算交给程序的办法。这正是本项目要回答的问题。

3. 选题意义

对使用者：把一次活动的策划从“回忆式写作”变成“填表 + 修改”。参数只需要 6 个核心项，产出却是六节完整、金额自洽的方案，第一次接手活动的同学也能拿到有据可依的底稿。

对团队：这是一次完整的工程训练。四人分别在前后端、测试与文档上各担一段，用同一份接口契约把四段工作缝在一起，走完需求、开发、联调、验收的完整流程；同时第一次把大模型接进一个需要结构约束、需要失败兜底的真实系统，而不是停留在调用一次接口看输出的层面。

对课程：选题规模与技术栈都在一周内可完成的范围内，交付物可演示、可复现，适合作为课程综合性大项目之前的一次预演。

4. 选题目标

类别 目标
功能目标 完成“登录 → 创建方案 → 异步生成 → 查看详情 → 按节编辑 → 复制 / 删除 → 导出”的主链路
内容目标 单次生成交付六个内容节：策划案（含预算）、物资清单、分工表、宣传文案、风险清单（≥6 条）、复盘模板
质量目标 金额由后端按单价 × 数量重算，误差为 0；章节缺失判失败；超预算写入告警
容错目标 模型不可用时降级生成并标记，演示流程不依赖外网与密钥
工程目标 接口以 OpenAPI 契约为准，前端类型检查通过，仓库不含密钥与数据库文件
学习目标 掌握智能体三节点编排、结构约束与降级兜底的做法，理解契约优先的前后端协作方式

5. 选题内容与范围

本期确定要做的是：单用户账号体系；方案六节生成与分节编辑；异步任务与进度轮询；列表搜索分页、复制、软删除；Markdown 导出与打印视图；模型供应商可切换（Mock / Dify / Coze / LangGraph）与规则降级；健康检查与统一错误码。

本期明确不做的是：方案版本历史与回滚、单节重新生成、模板库复用与共享、多人协同编辑与评论、服务端 PDF 渲染、第三方登录与消息通知、在线支付与场地真实预订。这些要么涉及额外的数据同步机制，要么超出课程周期，宁可写清楚不做，也不在文档里留空头承诺。

6. 技术路线与关键难点

技术路线：前端 Vue 3 + Vite + TypeScript + Element Plus 负责交互与展示；后端 FastAPI + SQLAlchemy 异步 + Pydantic v2 负责接口、任务与数据；智能体用 LangGraph 编排三个节点，接入 DeepSeek，配合 BM25 在本地知识库检索片段；接口契约用 OpenAPI，内容结构用 JSON Schema，数据库用 db-schema.sql 固化。

四个关键难点及我们的处理办法：

难点 具体表现 处理办法
输出结构不稳 模型偶发少字段、包一层说明文字、数字写成字符串 提示词固定字段与示例；写库前按 Schema 校验；非法 JSON 先做修复抽取，仍失败重试 1 次
金额必须算对 单价 × 数量与合计不一致，超预算无人发现 后端重算金额，覆盖模型给出的数字；超预算只写入 warnings，不改用户输入
长请求会超时 一次生成几十秒，直接同步返回易被网关断开 生成接口立即 202，落库任务记录后后台执行，前端按 poll_after_ms 轮询进度
没有网络也要能演示 演示现场断网或额度用尽 适配器模式隔离供应商；失败两次后走规则模板降级，标记 degraded=true 并在页面提示

7. 可行性分析

技术上可行：所用技术栈都是课程内已接触或可在一周内上手的开源方案，DeepSeek 接口按 token 计费、成本低；LangGraph 的节点编排只需三个节点，链路短、易调试。时间上可行：需求与契约在第一个迭代冻结，后端与智能体、前端各占一个迭代，留一个迭代专门联调与修缺陷。资源上可行：四人各自有明确的一段工作，互不空等；开发期用 SQLite 单文件，不需要额外服务器。

风险也如实列出：最大的不确定性是模型输出结构与耗时波动，因此我们把“校验 + 重试 + 降级”写进了需求，而不是等出问题再补；其次是四人课表不同步，靠接口契约和每日一次进度同步来降低等待成本。

8. 进度安排

阶段 时间 主要工作 阶段产物
第一阶段 10.28–10.31 选题确认、需求梳理、契约与验收标准定稿 选题报告、需求规格说明书、OpenAPI、内容 Schema、DDL
第二阶段 11.01–11.03 工程骨架、认证、方案与任务接口、智能体三节点与校验 可跑的后端与 Mock 智能体
第三阶段 11.03–11.05 六个页面开发与接口对接 登录、新建、生成中、列表、详情、打印页
第四阶段 11.05–11.07 前后端联调、用例执行、缺陷修复 接口端到端检查记录、修复清单
第五阶段 11.07–11.08 材料整理与提交 截图、演示数据、团队博客与文档

9. 成员分工

成员 角色 主要职责
王俊霖（3124004441） 后端开发负责人 后端框架与数据模型、认证与方案 / 任务接口、智能体适配与内容校验、接口契约维护
张帅（3124004451） 前端开发 六个页面与组件开发、分节编辑交互、导出与打印排版、接口对接
袁炜轩（3124004449） 测试工程师 测试用例编写、接口端到端检查、金额与章节一致性核对、缺陷复现与回归
王安亮（3124004439） 博客与文档负责人 选题报告与需求文档成文、博客撰写、截图与材料汇总、本地环境部署与演示脚本

10. 预期成果

一份可运行的平台代码（前端、后端、Mock 服务与契约文件）；一份需求规格说明书与一份选题报告；一份团队博客；一组演示数据与截图；一份可照着操作的演示脚本。验收时以需求文档中的验收标准逐条对照，未实现项已在范围边界中列明。

三、需求分析文档

本文参考《软件需求规格说明规范》的组织方式，按目标与范围、总体描述、功能与数据需求、接口需求、非功能需求、验收标准的顺序编写，内容与仓库 contracts/ 目录下的 openapi.json、plan-content.schema.json、db-schema.sql 保持一致。

3.1 迭代记录表

迭代 时间 目标 交付物 状态 遗留问题 / 下一步
迭代一·需求与契约 10.28–10.31 需求梳理、范围冻结、确定接口与内容契约 需求规格说明书、选题报告、OpenAPI、内容 Schema、DDL、示例方案 JSON 已完成 风险条目下限（≥6 条）与预算字段口径在评审中定稿
迭代二·后端骨架与认证 11.01–11.03 工程骨架、建库、注册登录 /healthz、/docs、三张核心表、JWT 认证 已完成 用户名重复等错误码统一为 {code,message} 结构
迭代三·生成主流程 11.03–11.05 202 异步任务、轮询、智能体与校验降级 Mock / 真实智能体、任务状态机、金额重算 已完成 真实模型输出格式不稳，补 JSON 修复重试
迭代四·编辑与交付 11.05–11.07 按节编辑、列表搜索分页、复制删除、导出 编辑接口 + 409、列表接口、Markdown 导出 已完成 列表接口确认不返回大 JSON，只返回摘要
迭代五·联调测试与材料 11.07–11.08 前后端联调、用例执行、缺陷修复、材料整理 接口端到端检查、演示数据、博客与截图 进行中 按验收标准逐条自测并截图留档

3.2 项目标志

image

设计说明：绿色底板取“可用、稳妥”，白色方案卡片代表一份被结构化下来的策划书，卡片内的对勾代表“条目可执行、可验收”，右上角暖色四角星是“智囊的灵感”。整体无文字，缩到 32px 仍可辨认，可直接用作站点图标。

3.3 思维导图

mindmap root((活动智囊)) M1[用户与权限] M1a[注册] M1b[登录 JWT] M1c[当前用户] M1d[数据隔离 仅本人] M2[方案生成] M2a[参数表单] M2a1[主题 类型 人数 预算] M2a2[时间 时长 地点] M2a3[受众 目标 语气 约束] M2b[异步任务] M2b1[202 受理] M2b2[任务轮询] M2b3[进度与阶段] M2c[智能体] M2c1[LangGraph 三节点] M2c2[DeepSeek] M2c3[BM25 知识库] M2c4[超时重试 1 次] M2c5[规则降级] M3[内容产物] M3a[策划案 含预算] M3b[物资清单] M3c[分工表] M3d[宣传文案] M3e[风险清单 至少六条] M3f[复盘模板] M4[编辑与交付] M4a[按节编辑] M4b[乐观锁 409] M4c[Markdown 导出] M4d[浏览器打印 PDF] M5[方案管理] M5a[列表] M5b[关键词搜索] M5c[分页] M5d[复制] M5e[软删除] M6[系统能力] M6a[枚举字典] M6b[健康检查 智能体状态] M6c[统一错误码] M6d[演示资料 无后端可跑]

主要分支：

  • 用户与权限：注册、登录、JWT、当前用户、数据隔离
  • 方案生成：参数表单（主题 / 类型 / 人数 / 预算 / 时间 / 时长 / 地点 / 受众 / 目标 / 语气 / 约束）、异步任务（202 + 轮询）、智能体（三节点 + RAG + 超时重试 + 降级）
  • 内容产物：策划案（含预算）、物资、分工、宣传、风险、复盘
  • 编辑与交付：按节编辑、乐观锁冲突、Markdown 导出、打印 PDF
  • 方案管理：列表、搜索、分页、复制、软删除
  • 系统能力：枚举字典、健康检查、统一错误码、Mock 演示

3.4 类图（数据模型）

classDiagram class User { +String id +String username +String passwordHash +String displayName +String role +DateTime createdAt +DateTime updatedAt } class Plan { +String id +String userId +String title +String status +int version +String theme +String activityType +int participants +int budgetFen +DateTime startsAt +int durationMinutes +String location +JSON input +JSON content +String summary +bool degraded +String agentProvider +DateTime deletedAt } class GenerationTask { +String id +String planId +String userId +String type +String sectionKey +String status +String stage +int progress +String idempotencyKey +int attempt +String errorCode +DateTime startedAt +DateTime finishedAt } class AgentAdapter { <<interface>> +generate(request) AgentResult } class MockAgent class LangGraphAgent class DifyAgent class CozeAgent class ContentValidator { +validate(content) +recalcAmounts(content) +budgetWarnings(content) } class ExportService { +toMarkdown(plan) } class SectionKeys { <<enumeration>> plan materials tasks promotion risks review } User "1" --> "0..*" Plan : 拥有 Plan "1" --> "0..*" GenerationTask : 触发 GenerationTask ..> AgentAdapter : 调用 AgentAdapter <|.. MockAgent AgentAdapter <|.. LangGraphAgent AgentAdapter <|.. DifyAgent AgentAdapter <|.. CozeAgent Plan ..> ContentValidator : 生成后校验 Plan ..> ExportService : 导出 Plan ..> SectionKeys : 按节编辑

实体与关键约束（依据 contracts/db-schema.sql）：

实体 关键字段 约束
users id、username、password_hash、display_name、role username 唯一；role ∈ user/admin
plans user_id、title、status、version、budget_fen、input_json、content_json、degraded、deleted_at version ≥ 1 用于乐观锁；软删除；金额存“分”
generation_tasks plan_id、user_id、type、section_key、status、progress、idempotency_key、attempt progress 0–100；idempotency_key 唯一防重复生成
plan_versions plan_id、version、content_json、editor_id (plan_id, version) 唯一
templates user_id、name、input_json、content_json、use_count 用户内未删除方案名唯一
export_records plan_id、format、file_size format ∈ markdown/pdf
agent_calls task_id、provider、latency_ms、tokens_in/out、error_code 用于统计成功率与耗时

本期使用 users、plans、generation_tasks 三张表，其余四张是后续版本要用的扩展表。

3.5 功能描述

3.5.1 前端需求

编号 页面 / 模块 功能点 交互与状态
F-01 登录 LoginView 注册与登录切换、表单校验、错误提示、来源回跳 未登录访问受保护路由 → 重定向登录；Token 存本地并注入请求头
F-02 新建 PlanCreateView 主题、活动类型（枚举下拉）、人数、预算、开始时间、时长、地点；进阶：受众、目标（≤5 条）、语气、约束 前端做与后端一致的字段校验；提交成功跳转生成中页并携带 task_id
F-03 生成中 GeneratingView 轮询任务、阶段文案、进度条、失败原因、超时提示、可离开 轮询间隔按返回值 poll_after_ms；成功跳详情，失败可重试
F-04 列表 PlanListView 卡片列表、关键词搜索（防抖）、分页、状态标签、空态、骨架屏 搜索与翻页只更新查询参数；异常统一走错误提示
F-05 详情 PlanDetailView 六大章节分区渲染、按节编辑弹窗、保存 / 取消、版本冲突提示 保存携带 version；返回 409 时提示“内容已被更新”，要求刷新后再改
F-06 分节编辑组件 预算行增删改与实时合计、物资表格、分工表、宣传卡片、风险表、复盘清单 编辑区与展示区同源数据，金额前端即时预览、后端最终重算
F-07 方案操作 复制方案、软删除、导出 Markdown、打印 删除需二次确认；导出用 Blob 下载并复用后端文件名
F-08 打印 PrintView 打印版式、分页控制、隐藏按钮 通过 @media print 与独立打印页保证 A4 排版
F-09 全局 登录态、服务状态徽标（/healthz 判断智能体是否就绪）、统一错误码文案、加载与空态 Pinia 管理登录态；错误码 → 中文提示映射
F-10 演示 Mock 无后端时可跑通全流程 devmock/ 提供同契约的假接口，只需改 VITE_API_BASE_URL

3.5.2 后端需求（接口清单）

方法 路径 说明 关键约束
GET /healthz 健康检查，含智能体 provider 与是否已配置 生产部署探活使用
POST /api/v1/auth/register 注册 用户名重复 → 409 USERNAME_TAKEN
POST /api/v1/auth/login 登录，返回 JWT 密码错误 → 401
GET /api/v1/auth/me 当前用户 需 Bearer Token
GET /api/v1/meta/enums 活动类型、状态、章节、风险等级、优先级、语气字典 前端不硬编码枚举
POST /api/v1/plans/generate 创建生成任务 立即 202；返回 task_id、plan_id、poll_url、poll_after_ms；同参数可复用未完成任务
GET /api/v1/tasks/{task_id} 轮询任务 返回 status、stage、progress、error_code/message
GET /api/v1/plans 方案列表 只返回摘要字段，不返回 content_json；分页 + 关键词
GET /api/v1/plans/{plan_id} 方案详情 含 latest_task、degraded、meta.agent
PATCH /api/v1/plans/{plan_id}/sections/{section_key} 按节编辑 必须带 version；版本不一致 → 409；成功后 version+1
POST /api/v1/plans/{plan_id}/duplicate 复制方案 生成新 plan，内容同源、状态 ready
DELETE /api/v1/plans/{plan_id} 删除方案 软删除，仅本人
GET /api/v1/plans/{plan_id}/export?format=markdown 导出 Content-Disposition 文件名中文正确；CORS 已暴露该头

统一错误结构：

{ "detail": { "code": "USERNAME_TAKEN", "message": "用户名已存在" } }

生成请求字段约束（schemas/plan.py）：

字段 类型 约束
theme str 2–60 字
activity_type str 必须在枚举内
participants int 10–2000
budget_yuan float 0–1,000,000
starts_at datetime ISO 8601
duration_minutes int 30–480，默认 120
location str 1–120 字
target_audience / constraints / extra_notes str 分别不超过 120 / 500 / 500 字
goals list ≤5 条
tone str lively / warm / formal / creative

3.5.3 智能体与内容校验

  1. 异步：接口不等待模型返回，后台任务执行、前端轮询，避免网关超时。
  2. 三节点：策划案 + 预算 → 物资 + 分工 → 宣传 + 风险 + 复盘；后一节点入参携带前一节点 JSON 与 BM25 检索片段（top-k=4）。
  3. 超时与重试：AGENT_TIMEOUT_SECONDS=120，失败重试 1 次；仍失败且 ENABLE_FALLBACK=true 时用知识库规则模板生成，标记 degraded=true、meta.agent.provider=fallback，前端提示“方案为降级生成”。
  4. 校验：非 JSON 可修复抽取；缺章节判失败；单价 × 数量、物资小计、预算合计由后端重算，误差为 0；超预算写入 warnings，不改用户输入。

3.5.4 非功能需求

类别 要求
性能 列表接口本地 ≤300ms；单次生成 60s 内完成（真实模型实测约 48s）；前端首屏 ≤3s
可用性 智能体不可用时仍能降级出方案；任务失败有可读错误码，不白屏
安全 密码哈希存储；JWT 鉴权且只能访问本人数据；.env 与 Key 不入库不入日志；列表不返回大 JSON
一致性 契约优先：接口变更先改 OpenAPI，再改实现与文档
兼容 Chrome/Edge 最新两个版本；最小宽度 1280px 桌面优先，移动端仅保证可读
可维护 前端页面 / 组件 / 工具分层；后端 api / services / agent / models 分层；统一错误码

3.6 验收标准

编号 场景 验收标准（可演示、可复现）
A-01 健康检查 GET /healthz 返回 200，且 agent.provider 与 agent.configured 正确反映当前配置
A-02 注册登录 注册 → 登录 → 带 Token 访问 /auth/me 成功；重复用户名 409 USERNAME_TAKEN；密码错误 401
A-03 权限隔离 未带 Token 访问受保护接口 401；用户 A 无法读取 / 修改用户 B 的方案
A-04 生成主流程 输入“迎新晚会 / 100 人 / 2000 元 / 一周后 / 学校礼堂 / 120 分钟”，5–60 秒内状态变为 ready，返回六个章节
A-05 任务轮询 提交返回 202 与 poll_url；轮询可见 queued→running→succeeded；失败任务带 error_code 与可读 message
A-06 金额自洽 任一物资 amount = quantity × unit_price，小计与合计由后端重算且误差为 0；超预算时 warnings 非空
A-07 风险完整 风险清单 ≥6 条，每条含等级、触发信号、缓解措施、责任人
A-08 按节编辑 修改任一章节保存成功，刷新后仍在；用旧 version 再提交返回 409
A-09 列表能力 列表只返回摘要字段；关键词搜索命中主题；分页正确；删除的方案不再出现
A-10 复制与导出 复制生成新方案内容一致；导出 Markdown 中文不乱码、含六章节、文件名为中文方案名
A-11 降级可用 不配置 API Key 时，ENABLE_FALLBACK=true 仍能产出方案，且 degraded=true、前端有降级提示
A-12 工程质量 pnpm typecheck 通过；接口与 contracts/openapi.json 一致；仓库无 .env、*.db、.venv、node_modules
A-13 无后端演示 仅启动 devmock + 前端，可独立走完“登录 → 新建 → 生成中 → 详情 → 编辑 → 导出”全流程

A-01 至 A-10 为验收必过项，A-11 至 A-13 为容错与演示项。

3.7 范围边界

  • 版本历史与恢复、单节重新生成、模板复用；
  • 服务端 PDF 生成，改用浏览器打印；
  • 多用户协同编辑、方案分享与团队共享；
  • 在线支付、场地真实预订、外部供应商对接；
  • 移动 App、消息推送。

3.8 已知风险与应对

风险 影响 应对
模型输出格式不稳（缺字段、非法 JSON） 方案生成失败或前端渲染异常 Schema 校验 + JSON 修复重试 + 规则降级兜底
真实生成耗时波动（实测约 48s） 演示时等待过长或被网关超时 一律异步 202 + 轮询；演示前预热或准备现成方案
公网免费实例不能持久化 SQLite 重启后数据丢失 生产切 PostgreSQL；演示用本地库
联调时间紧 功能不完整 保核心链路，其余按余力补齐

注：想使用请联系管理员张帅3124004451开启服务器。

posted @ 2026-11-07 18:28  Wh1teFe  阅读(57)  评论(0)    收藏  举报