SORT / LAB 排序算法可视化实验室：使用 CodeArts Agent 完成设计、开发与验证案例介绍：本案例采用华为云码道（CodeArts）代码智能体作为核心开发工具，以算法过程可观察、实验条件可复现、学习效果可验证为目标，按照 SDD（Spec-Driven Development）规范驱动方式完成 SORT / LAB 排序算法可视化实验室。项目将 45 种排序算法统一为事件流，并结合 Canvas、Web Worker、双算法同步对比和教学工作台，覆盖需求分析、系统设计、功能实现和自动化验证。案例属性内容案例类型AI 辅助开发 / Web 前端 / 算法教学难度中级建议用时150～180 分钟核心工具华为云码道（CodeArts）代码智能体技术栈Next.js 16、React 19、TypeScript 5.9、Canvas、Web Worker、vinext、Vite、Cloudflare Worker最终成果45 种算法、9 种数据分布、5 条学习路径、130 项自动化测试案例展示SORT / LAB 排序算法可视化实验室一、概述1.1 案例介绍排序算法是数据结构与算法课程的重要基础。传统教材中的静态数组、箭头和伪代码难以连续呈现读取、比较、交换、写入和归位等状态变化。简单动画通常只展示执行结果，缺少操作原因说明和同源数据对比。本案例对话华为云码道（CodeArts）代码智能体，从学习场景出发，将需求逐层收敛为四个建设目标：过程展示：通过 Canvas、状态色、活动区间、Pivot、辅助存储区和算法专用结构视图呈现排序过程。实验控制：支持播放、暂停、语义单步、微操作单步、上一步、时间轴、对数速度和安全上限。同源对比：双算法使用同一份输入，可按微操作、语义阶段或确认进度同步，并分别统计读取、比较、写入与交换次数。教学组织：每种算法配置目标、概念、不变量、四行伪代码、角色、教学预设和检查点，提供讲解、预测、实验、课程与教师工具五类教学活动。最终完成的 SORT / LAB 是一套可扩展、可复现、可验证的排序算法教学实验室。1.2 适用对象个人开发者；企业开发者；高校学生与教师；希望了解 CodeArts Agent 如何参与需求、设计、实现和测试流程的开发团队。1.3 案例时间建议总用时为 150～180 分钟。阶段建议用时主要成果需求定义20 分钟产品目标、用户场景、验收标准架构设计25 分钟事件模型、播放器状态机、模块边界核心实现60 分钟算法引擎、Canvas、控制器、对比模式教学扩展30 分钟教学内容、实验、课程路线、教师工具验证交付25 分钟构建、130 项测试、Lint、类型检查、16:9 截图1.4 案例流程图 1：案例实施流程。六个编号与下方流程说明逐项对应。说明：在 CodeArts 中打开项目，按照目标与约束、方案确认、实现、验收四个步骤建立 Agent 协作方式；将排序算法抽象为统一的 SortStep 事件协议和播放器状态机；分批接入 45 种算法、9 种数据分布及其输入约束；构建 Canvas 主视图、专用辅助视图和双算法同步对比；增加教学工作台、高速 Worker、历史回放和安全保护；执行构建、自动化测试、类型检查与浏览器验收，完成交付。开发过程按阶段迭代。每轮先说明需要解决的问题和必须保持的边界，Agent 阅读相关代码后给出方案。我确认数据模型和交互取舍后，再让 Agent 修改代码。项目脚本和浏览器验收结果用于判断本轮是否完成。测试失败、边界输入或视觉问题会作为下一轮输入继续交给 Agent。1.5 资源总览本案例使用 CodeArts 体验版和本地开发环境，预计花费 0 元，不创建 ECS、CCE、EIP 等付费云资源。资源名称规格单价（元）华为云码道（CodeArts）代码智能体通用体验版免费本地开发环境arm64，Node.js v25.7.0，npm 11.10.1免费Chromium/Chrome支持 Canvas、Web Worker 与 ResizeObserver免费二、环境和资源准备2.1 准备 CodeArts 与项目工作区打开 CodeArts，将 sort-visualization 作为项目目录。项目代码、依赖安装、测试和案例截图均保存在该目录中。本案例不需要创建数据库、云服务器或容器集群。开始前确认 CodeArts 能够读取项目文件，并保留一份未修改的源码版本，便于对照 Agent 的修改范围。2.2 准备本地运行环境项目要求 Node.js 版本不低于 22.13.0。本次验证环境如下：项目版本Node.jsv25.7.0npm11.10.1系统架构arm64使用以下命令确认环境：node --version npm --version 浏览器建议使用较新的 Chromium 或 Chrome，以确保 Canvas、Web Worker 和 ResizeObserver 正常工作。2.3 准备验收标准在让智能体大规模生成代码之前，先确定以下质量门槛：45 种算法均能通过事件回放得到正确升序结果；同一种子和数据分布必须生成相同输入；算法声明的重复值、负数、2 的幂和辅助区能力必须与实现一致；播放器支持暂停、单步、回退和时间轴；高速播放不能长时间阻塞主线程；极慢算法必须有规模和最大步数保护；每种算法必须有完整教学内容；页面支持桌面、平板、手机和减少动画偏好；案例成果截图统一采用 16:9。三、构建 SORT / LAB 排序算法可视化实验室3.1 打开项目并建立 Agent 协作方式在 CodeArts 中打开项目目录后，先让 Agent 阅读 README.md、package.json、app/ 和 tests/，并说明现有工程的入口、依赖、数据流和风险。第一轮执行代码分析，不修改文件：请先阅读当前项目，不要修改文件。 请说明： 1. 页面入口、算法逻辑、状态管理和测试分别位于哪里； 2. 当前实现中最适合继续扩展的接口是什么； 3. 如果要支持播放、回退、对比和教学，哪些状态必须统一建模； 4. 哪些算法或输入容易造成性能和正确性风险。 最后给出分阶段实施建议，等我确认后再开始修改。Agent 完成代码库分析后，我把协作约定固定下来：每轮只解决一个明确主题，先说明方案和影响文件；算法注册表和事件协议作为播放器、教学内容与测试的共同依据；不绕过现有工程结构，不覆盖与本轮无关的改动；完成功能后同时补充测试，并运行对应的项目脚本；对视觉结果无法仅凭代码判断时，启动页面进行浏览器验收；如果测试失败，先解释原因，再根据失败信息修正。这样做的好处是，我始终掌握产品边界和验收口径，Agent 则持续掌握具体代码上下文。后续每个阶段都沿用这套协作方式。3.2 部署并运行项目代码3.2.1 项目结构sort-visualization/ ├── app/ │ ├── page.tsx # 页面、播放器状态机、Canvas 与教学交互 │ ├── sort-engine.ts # 算法定义、事件协议、数据分布 │ ├── sort.worker.ts # 高速事件预取 Worker │ ├── teaching-content.ts # 45 种算法的教学内容与课程路径 │ └── globals.css # 视觉系统与响应式布局 ├── tests/ │ ├── algorithms.test.mjs # 算法、事件、教学内容和专用视图测试 │ └── rendered-html.test.mjs # 服务端渲染冒烟测试 ├── output/playwright/ # 1600×900 案例截图 ├── docs/ # 需求、设计、验证与案例文档 ├── worker/index.ts # Cloudflare Worker 入口 └── package.json # 工程脚本和依赖3.2.2 准备源码案例源码已经置于 CodeArts 打开的项目工作区，因此无需重复下载。确认项目根目录包含 package.json、package-lock.json、app/ 和 tests/ 后，再继续安装依赖。如果从案例附件获取源码，请先将源码完整解压到 sort-visualization 目录，并使用 CodeArts 打开该目录；不要只打开其中的 app/ 子目录，否则依赖脚本和测试文件无法被正确识别。3.2.3 安装依赖在项目根目录执行：npm install package.json 已锁定 Next.js、React、TypeScript、Vite、vinext 和测试工具版本，package-lock.json 用于保证安装结果可复现。3.2.4 运行调试执行以下命令启动开发服务器：npm run dev终端输出本地访问地址后，在浏览器中打开页面。开发过程中保持终端运行，修改代码后页面会自动刷新。图 2：项目成功启动后的主操作台。左侧为算法属性和伪代码，中间为 Canvas 与时间轴，右侧实时统计读取、比较、写入和交换次数。3.3 对话码道：将排序动画需求整理为教学实验室规格目标将排序可视化页面需求整理为可实现、可追踪、可验收的产品规格。我的输入请构建一个排序算法可视化实验室，不要只实现单一算法动画。 核心要求： 1. 覆盖基础、高效、非比较、特色和极慢排序算法； 2. 输入可使用随机种子复现，并支持多种典型数据分布； 3. 支持播放、暂停、单步、上一步、时间轴和速度调整； 4. 展示读取、比较、写入、交换和已确认位置； 5. 支持两个算法使用相同输入同步对比； 6. 加入教学目标、伪代码、不变量、练习和课程路径； 7. 对极慢算法和高数据规模提供性能保护； 8. 使用 TypeScript，完成自动化测试、Lint 和类型检查。 先分析需求和架构，再开始实现。每个阶段完成后给出验证结果。Agent 的反馈与我的确认这一轮要求 Agent 先完成范围分析。Agent 将需求拆成产品层、算法层、事件协议层、播放控制层、可视化层、教学层和验证层，并指出算法数量和播放器通用性会直接影响后续维护成本。我确认了两个关键取舍：第一，45 种算法统一使用同一事件协议，避免分别维护播放器；第二，教学功能必须与播放器状态联动，避免使用与执行过程分离的静态说明。在这两个前提下，双方确定了最终产品范围：项目指标数量或结果排序算法45 种算法分类5 类数据分布9 种教学路径5 条播放速度1～4096 步/秒安全上限5 万 / 25 万 / 100 万步自动化测试130 项3.4 对话码道：设计统一事件协议背景45 种算法的内部机制差异很大：归并排序需要辅助数组，计数与桶排序需要分组结构，树排序需要节点关系，珠排序则需要模拟放置、重力和读出阶段。如果每种算法直接操作页面，播放器、回放、统计和测试都会重复实现。我的输入请把排序逻辑与界面渲染解耦。 每个算法使用 Generator 产生统一的语义事件，事件至少覆盖： read、compare、swap、write、auxWrite、mark、pivot、range、 bucket、code、visual 和 done。 页面只消费事件并更新状态，不允许算法直接操作 DOM 或 Canvas。 同一事件流必须同时服务于动画、统计、回放、教学解释和自动化测试。协作过程Agent 首先提出以 Generator 产出事件、Reducer 消费事件的方案。我在审查时补充了两个容易遗漏的要求：重复值需要独立身份以观察稳定性，树、桶、排序网络和珠排序不能被强行压缩成普通数组动画。Agent 据此扩展 SortStep 联合类型，并让 playerReducer 统一处理主数组、辅助区、活动范围、专用视图和统计值。完成首版后，我通过单步、交换和归并写回三个场景检查事件语义，再让 Agent 处理身份传递与辅助区清理的边界情况。核心设计图 3：排序算法、统一事件协议、播放器状态机与展示层之间的关系。关键代码：统一事件协议app/sort-engine.ts 使用 TypeScript 联合类型描述排序操作。下面节选其中的核心事件；算法只负责产生事件，不直接操作页面：export type SortStep = | { type: "read"; index: number; message?: string } | { type: "compare"; indices: [number, number]; message?: string } | { type: "swap"; indices: [number, number]; message?: string } | { type: "write"; index: number; value: number; message?: string } | { type: "auxWrite"; index: number; value: number; message?: string } | { type: "mark"; indices: number[]; message?: string } | { type: "pivot"; index: number | null; message?: string } | { type: "bucket"; bucket: number; values: number[]; message?: string } | { type: "code"; line: number; variables?: Record<string, string | number>; message?: string; } | { type: "visual"; state: AlgorithmVisualState; message?: string } | { type: "done"; message?: string }; export type SortGenerator = Generator<SortStep, void, unknown>; 算法注册表则集中声明复杂度、稳定性、输入约束、辅助视图和 Generator 入口，使页面与测试可以读取同一份元数据。事件模型带来了四项关键收益：算法与视图解耦：新算法只需注册元数据和 Generator，不必重写播放器。播放能力复用：暂停、单步、回退和时间轴对全部算法生效。统计口径统一：读取、比较、写入和交换来自同一事件源。验证范围统一：测试检查最终结果、事件下标、辅助存储和完成状态。3.5 对话码道：构建算法与数据实验能力我的输入请在统一事件协议上扩展算法注册表： - 分类覆盖基础排序、高效排序、非比较排序、特色排序和极慢排序； - 每个算法声明中英文名、复杂度、空间、稳定性、是否原地、 最大规模、输入约束和辅助视图类型； - 数据分布覆盖随机、逆序、有序、接近有序、少量不同值、 山峰、锯齿、分段有序和含负数； - 所有随机数据由 seed 驱动； - 不支持重复值、负数或非 2 的幂规模时，界面必须前置提示或自动调整； - 极慢算法设置小规模默认值与最大事件步数。协作过程这一阶段要求 Agent 以注册表为中心分批接入算法。先完成基础排序并验证事件协议，再扩展高效排序、非比较排序和专用结构，最后处理极慢算法。每批实现后，使用相同的回放器比较标准升序结果。测试发现重复值、负数、辅助区声明和 2 的幂规模等差异后，Agent 同步修正实现或能力元数据，确保界面声明与算法实际能力一致。阶段成果分类数量代表算法基础排序10冒泡、鸡尾酒、选择、插入、梳排序高效排序14归并、快速、堆、内省、TimSort非比较排序7计数、基数、桶、美国旗、珠排序特色排序8煎饼、循环、双调、树、耐心排序极慢排序6Stooge、Slow、Bogo、Bozo、排列、睡眠排序每个算法通过 AlgorithmDefinition 声明能力边界。数据生成由 seed + distribution + size 决定，并可写入 URL，使教师分享的课程链接能够恢复算法、规模、数据形态和教学模式。3.6 对话码道：定义排序过程的视觉语义我的输入请把事件状态映射为清晰的视觉语义： - 未读取、已读取、已确认排序和当前操作使用不同颜色； - 显示活动区间、Pivot、手持值、扫描候选和比较关系； - 归并、基数等算法展示辅助存储区； - 桶、树、锦标赛、排序网络和珠排序使用专用辅助视图； - Canvas 适配高分屏与容器尺寸； - 低速提供平滑位移，高速和大规模时减少过渡以保证性能。协作过程Agent 先根据事件类型建立颜色和图形映射。我在浏览器中检查后，反馈了三个问题：高分屏下线条发虚、容器缩放后画布尺寸不同步、重复值移动时难以辨认来源。Agent 随后补充基于 devicePixelRatio 的渲染、ResizeObserver 自适应和 requestAnimationFrame 插值，并使用元素身份表现真实移动轨迹。我再次用快速排序、归并排序和少量重复值数据进行验收，确认 Pivot、活动区间、辅助存储和稳定性身份均能被观察后，才保留这套视觉语义。快速排序在 72 项同源数据上的运行效果见图 2。画面中的 Pivot、活动区间和实时操作量均由同一事件流驱动。3.7 对话码道：实现可信的双算法对比背景动画结束时间会受到播放速度、设备性能和单步粒度影响。为保证实验条件一致，两个算法必须使用完全相同的输入，并采用明确的同步规则。我的输入请实现双算法同步对比： 1. 两个算法共享同一份初始数据； 2. 支持按微操作数、语义阶段或确认进度同步； 3. 两侧分别显示比较、写入等操作量； 4. 完成后自动给出差异结论； 5. 对比模式仍要支持暂停、单步、回退和时间轴。协作过程Agent 的首个方案按照相同微操作数推进两侧播放器。试用结果表明，一次归并写回操作和一次快速排序比较操作会被视为同等进度，无法表示两种算法的语义差异。因此保留微操作同步，并增加语义阶段和确认进度两种口径。Agent 重构同步控制后，我用快速排序与归并排序在同一随机种子下运行，检查两侧初始数组、统计和历史快照是否独立。确认三种同步方式都能解释其含义后，再加入完成后的操作量结论。图 4：快速排序与归并排序使用相同的 72 项数据，并按语义阶段同步。归并排序的辅助存储区与两侧独立统计同时可见。学习者可以分别比较比较次数、写入次数和最终位置确认进度，避免仅根据动画结束时间判断算法表现。3.8 对话码道：从演示工具扩展为教学工作台我的输入请为 45 种算法分别补充教学内容： - 学习目标、核心概念和循环不变量； - 固定四行、可随事件高亮的伪代码； - 当前操作及其执行原因； - 算法角色、推荐教学数据和检查点题目； - 教学实验、课程路径、术语表和教师工具； - 学习记录保存到本地，课程链接可分享复现。协作过程Agent 最初可以直接在组件中加入讲解文本，但我要求先把教学内容抽成独立配置，因为 45 种算法如果散落在 JSX 中将难以审查和补齐。Agent 因此建立 TeachingContent 契约，把目标、概念、不变量、伪代码、角色、预设和检查点统一组织。我重点审查每种算法的推荐数据是否符合其能力边界，以及检查点是否能够帮助理解算法。检查点内容需要包含推理要求，避免复述页面文字。Agent 根据这些反馈调整内容，并补充完整性测试，保证算法注册表、教学内容和课程路径一一对应。最终教学工作台包含五个页签：逐步讲解：当前操作、原因、不变量、角色、推荐观察与下一课；预测练习：在关键步骤前预测结果，即时反馈并记录正确率；教学实验：稳定性身份追踪和复杂度增长实验；课程路径：五条由浅入深的学习路线；教师工具：全屏、书签、分享链接、减少动画、文本数组和事件日志。图 5：快速排序的教学工作台在同一视图中展示当前操作、执行原因、算法不变量、算法角色和后续课程。3.9 对话码道：兼顾高速运行、回放与安全边界我的输入请检查大规模和高速场景： - 低速保留平滑动画； - 高速播放不要让主线程同步生成全部事件； - 支持历史快照、上一步和时间轴跳转； - 切换算法或重置后，旧任务不能继续写入； - 极慢算法达到限制时安全停止并给出提示； - 根据数组规模限制历史数量，避免内存持续增长。协作过程在大规模高速播放中，我观察到事件生成、状态更新和 Canvas 绘制都集中在主线程。Agent 分析调用链后提出使用 Web Worker 分批预取，并将速度达到 512 步/秒及以上的任务切换到 Worker。Worker 每批预取 2000 个事件，主线程按帧消费并在低水位时继续请求。首次切换算法测试时，我又发现旧任务可能晚到。将这个现象反馈给 Agent 后，它增加 generation 标识隔离过期消息。随后双方继续根据数组规模调整历史快照数量，最终控制在约 220～2400 份，兼顾可回退性与内存占用。关键代码：Worker 分批预取app/sort.worker.ts 只在当前任务的 generation 仍然有效时继续生成事件，并按批次返回主线程：const sendBatch = (generation: number, count: number) => { if (generation !== activeGeneration || !iterator) return; const steps: SortStep[] = []; let done = false; while (steps.length < count && emitted < maximum) { const next = iterator.next(); if (next.done) { done = true; iterator = null; break; } steps.push(next.value); emitted += 1; } self.postMessage({ type: "batch", generation, steps, done }); }; 对于极慢算法，系统同时采用：算法级 maxSize 与推荐默认规模；2 的幂等输入约束自动归一化；5 万、25 万或 100 万步运行上限；达到上限后的 limited 状态和用户提示。3.10 对话码道：建立自动化质量验证我的输入请为项目建立可重复执行的验证流程： 1. 构建生产版本； 2. 回放每一种算法并与标准升序结果比较； 3. 校验事件索引、范围、辅助存储和 done 事件； 4. 校验带种子数据、九种分布、重复值与负数； 5. 校验教学内容、课程路径和专用可视状态； 6. 校验 SSR 页面包含完整产品内容，不含模板占位内容； 7. 执行 ESLint 和 TypeScript 类型检查。协作过程Agent 根据算法注册表生成逐项回放测试，并补充数据分布、重复值、负数、教学契约和专用视图测试。我负责实际运行项目脚本并阅读失败输出，再把失败用例和预期行为交回 Agent 修正。构建、测试、Lint、类型检查和浏览器验收全部通过后，本轮开发任务才完成。算法元数据、教学预设或 SSR 页面结构发生修正后，需要重新执行同一验证流程。最终验证在 2026-07-25 执行：验证命令结果说明npm test通过生产构建成功；130 项测试全部通过，0 失败npm run lint通过ESLint 无错误、无警告输出npx tsc --noEmit通过TypeScript 类型检查通过视觉验收通过3 张成果图均为 1600×900自动化测试验证最终有序结果，并覆盖以下内容：45 种算法的事件回放、元素守恒和完成事件；随机种子的确定性及 9 种数据分布；支持范围内的重复值和负数；45 份教学内容、预设、检查点和 5 条课程路径；珠排序三阶段、真实二叉搜索树和锦标赛路径重赛；服务端渲染的标题、产品壳层和关键控件。四、释放资源4.1 停止本地开发服务器案例操作完成后，在运行 npm run dev 的终端中按 Ctrl+C 停止开发服务器。4.2 资源释放说明本案例未创建 ECS、CCE、EIP、云数据库等计费云资源，无需执行额外的云资源删除操作。项目源码、测试结果和截图均保存在本地工作区，可按需要继续保留。五、扩展资料说明5.1 案例总结本案例通过 CodeArts 智能体完成了需求分析、系统设计、代码实现、测试和浏览器验收。项目建立了以下扩展机制：统一事件协议让异构算法共享播放器、统计、回放和测试；Generator 与 Reducer 把算法执行过程转化为可观察状态；Canvas 和专用辅助结构把抽象数据变化映射为一致视觉语义；同源双算法实验避免以动画速度代替复杂度判断；教学内容配置层让每种算法都拥有目标、不变量、练习和课程归属；Worker、历史上限和极慢算法保护让高吞吐与教学可读性可以共存；自动化测试统一检查算法正确性、事件合法性、教学完整性和 SSR 页面内容。整个项目按照可验证阶段组织 Agent 协作。我负责定义目标、指出风险和判断结果，Agent 负责理解代码、提出实现方案、完成跨文件修改并补齐测试。每轮需要生成可运行的中间成果，后续任务建立在已经验证的实现基础上。5.2 与 Agent 协作的经验先让 Agent 读懂项目，再让它修改。 第一轮只分析入口、依赖、数据流和风险，能够减少对现有结构的误判。提示词同时写目标、约束和验收方式。 双算法对比任务需要明确同源数据、同步口径、独立统计和回放要求。关键产品取舍由人确认。 事件协议、同步语义、教学内容结构等决定长期维护成本，不能仅因为首个方案能运行就直接接受。把失败结果作为下一轮上下文。 向 Agent 提供测试输出、边界输入和浏览器现象，便于定位并修正问题。每轮留下可验证的中间成果。 先稳定事件协议，再扩展算法；先完成播放器，再做对比和教学，避免多个问题互相遮蔽。代码验收和视觉验收分开进行。 自动化测试负责正确性与契约，浏览器验收负责动画语义、布局和教学可读性，两者缺一不可。5.3 当前限制与后续计划学习记录当前保存在浏览器本地，尚未实现账号体系和跨设备同步；视觉回归主要依靠人工验收，可继续加入截图差异测试；复杂度实验侧重趋势观察，尚未建立跨设备性能基准；可继续增加课堂任务模板、实验结果导出和教师端班级数据；可将统一事件协议开放为插件接口，让学习者自行接入新算法。5.4 参考案例AssetMgmt 固定资产管理系统（一）：码道搭台，设计筑基AssetMgmt 固定资产管理系统（二）：码道领航，落地生根

TravelMap 编排—游记一体化平台：基于 CodeArts Agent 的全流程构建实践案例部署链接：https://travelmap.linykweb.top/本案例说明如何在本地环境中使用华为云码道完成需求规格、系统设计、编码、测试和运行，再将通过本地验收的应用部署到华为云。项目内容案例名称TravelMap 编排—游记一体化平台：基于 CodeArts Agent 的全流程构建实践核心工具华为云码道（CodeArts）代码智能体开发模式Idea 探索 + SDD 规范驱动 + TDD 测试驱动 + 人机协同迭代技术栈Next.js 15、React 18、TypeScript strict、tRPC、Prisma、PostgreSQL、Redis、TipTap、高德地图云上资源华为云 ECS、EVS、EIP、OBS、SWR，Docker Compose + Caddy当前演示地址https://travelmap.linykweb.top/项目源码GitCode：qq_26761683/travelmap案例适用人群独立开发者、产品经理、前端/全栈工程师、使用 AI 完成全栈开发、测试和部署的团队一、概述1.1 案例介绍1.1.1 旅行编排与协作问题旅行计划通常散落在许多工具里：灵感收藏在内容社区；地点保存在地图收藏夹；日期和时间写在表格；交通方案散落在聊天记录；同行人通过群聊反复确认；旅行结束后，又需要重新整理素材写游记。这些工具分别提供内容检索、地图查看和笔记记录能力，规划、执行和记录数据之间仍然缺少统一关联。一份多人行程会持续发生时间调整、地点替换、提醒补充和交通变化，群聊和表格无法提供稳定的版本、权限和冲突处理。我提出以下初始目标：构建支持时间编排、地图路线、多人协作和游记复用的旅行计划系统。这个目标仍需补充时间冲突、并发编辑、路线可信度、离线访问、AI 修改权限和数据恢复等要求。我先让华为云码道分析问题和边界，再形成可实现、可验收的产品定义。编码工作在需求、非目标和验收条件明确后开始。1.1.2 最终形成的产品定位经过多轮澄清和迭代，TravelMap 的产品范围确定为编排、协作和游记一体化平台：编排：以日期横轴、时间纵轴组织活动、交通、用餐、休息与组合模块。协作：支持 owner、editor、commenter、viewer 四级角色，以及邀请、在线状态、评注和事件级软锁。执行：提供旅行模式、路线信息、执行状态、离线恢复和版本历史。记录：帖子承载轻量图片内容，游记承载富文本叙事，编排可作为结构化组件插入游记。智能辅助：AI 读取偏好、查询资料、核验地点和路线，但只提交可审查的 Proposal；用户确认后才会应用到正式编排。工程交付：具备测试、迁移、构建、健康检查、对象存储、监控、备份、升级与回滚材料。1.1.3 Agent 开发方法人负责目标、价值和取舍；Agent 负责检索上下文、发现缺口、提出结构化方案。一个真实可交付的项目还必须可解释、可测试、可部署、可回滚，并能让后来者理解为什么这样设计。每个重要阶段都要留下四类证据：发现了什么问题、做出了什么决定、修改了哪些内容、怎样证明修改有效。项目规则、SDD 文档、TDD、类型检查、测试、构建和发布门禁用于确保每次变更可追溯、可验证和可复现。1.2 案例时间本案例从空目录开始，在本地完成应用构建和验证，最后部署单机 Demo。预计总时长约 12–16 小时，可分 2–3 天完成：阶段预计时间本地工具安装与空项目初始化45–60 分钟使用码道形成 Spec、Design 和 Tasks60–90 分钟内容、游记和基础用户功能2–3 小时编排、保存、离线和多人协作3–4 小时AI 规划、导入和可靠性处理2–3 小时本地测试、构建和页面验收1–2 小时华为云部署、验收和维护配置1.5–2 小时实际耗时受网络、依赖下载、数据库配置、第三方服务凭据和读者经验影响。本文提供完整流程和关键实现，读者可以按阶段执行并保存每个质量门结果。1.3 案例流程flowchart LR A["1. 提出旅行协作 Idea"] --> B["2. 码道完善需求与 SDD 规格"] B --> C["3. TDD 实现与反复迭代"] C --> D["4. 规范化代码、文档与质量门"] D --> E["5. 构建镜像并部署华为云"] E --> F["6. 健康检查、业务验收与资源释放"] 说明：提出编排、协作和游记一体化的产品目标；码道在探索阶段分析角色、边界和风险，并形成规格、设计和任务；每个重要实现遵循失败测试、最小完整修改、目标验证和全量验证的顺序；将反复对话中形成的产品决策沉淀为架构、协议、测试、运行手册和证据矩阵；使用 Docker、SWR、ECS、EVS、OBS、EIP 和 Caddy 完成可恢复的单机 Demo 部署；通过健康接口和真实页面展示效果，体验完成后备份数据并释放计费资源。1.4 资源总览资源名称使用阶段本案例用途推荐规格或版本华为云码道（CodeArts）代码智能体本地开发需求分析、代码库理解、编码、测试和部署材料生成本地 IDE/CLI，账号可用版本Git本地开发版本管理2.xNode.js 与 npm本地开发Web、脚本和测试运行时Node.js 20 LTSPostgreSQL本地开发权威业务数据16Redis本地协作验证Pub/Sub、Presence 和软锁7.4Docker Desktop 或 Docker Engine本地验证数据服务和生产镜像验证24+，Compose v2华为云 ECS、EVS、EIP部署与维护运行应用和持久化数据x86，4 vCPU / 8 GiB，100 GiB 数据盘华为云 OBS部署与维护公开媒体与私有数据库备份两个独立桶华为云 SWR部署与维护保存不可变应用镜像账号所在区域私有组织域名与 DNS部署与维护HTTPS 访问已备案域名或合规测试域名二、环境和资源准备本章全部在本地计算机完成。华为云资源从 3.9 节的部署阶段开始使用。2.1 安装本地开发工具从码道下载页安装 CodeArts IDE 或 CLI；在本地码道中登录账号，新建空工作区并选择本机目录；安装 Git 2.x、Node.js 20 LTS、npm、Docker Desktop 或 Docker Engine 24+；PostgreSQL 使用 16 版，Redis 使用 7.4 版；确认本地终端可以执行以下检查：git --version node --version npm --version docker --version docker compose version本案例使用本地文件系统、本地终端和本地浏览器完成开发。数据库可以直接安装在本机，也可以通过 Docker 启动。2.2 创建空项目先创建空目录和 Git 仓库：mkdir travel-map cd travel-map git init npm init -y 在码道中打开该目录，建立初始会话。第一项任务要求 Agent 只创建基础工程，不加入业务功能：请在当前空目录创建 Next.js 15、React 18 和 TypeScript strict 项目。 使用 App Router，配置 Tailwind CSS、Vitest、Testing Library 和 Playwright。 先生成 package.json、tsconfig.json、基础页面和测试配置。 完成后运行基础测试、类型检查和生产构建，并说明每个文件的职责。核心运行时依赖使用明确版本：npm install next@15.5.21 react@18.3.1 react-dom@18.3.1 npm install -D typescript@5.7.2 @types/node@22.10.0 \ @types/react@18.3.14 @types/react-dom@18.3.2随后由 Agent 按功能阶段补充 tRPC、Prisma、TipTap、Redis、图片处理和测试依赖，并生成 package-lock.json。从锁文件已经生成的阶段开始，统一使用：npm ci2.3 配置本地数据库和环境变量使用 Docker 启动本地 PostgreSQL：docker run --name travel-map-postgres \ -e POSTGRES_USER=postgres \ -e POSTGRES_PASSWORD=postgres \ -e POSTGRES_DB=travel_map \ -p 5432:5432 \ -d postgres:16-alpine基础开发阶段使用应用内置的单进程 WebSocket Gateway。实现 Redis 协作阶段后，再启动本地 Redis：docker run --name travel-map-redis \ -p 6379:6379 \ -d redis:7.4-alpine复制环境变量模板：cp .env.example .env openssl rand -base64 32 将生成值写入本地 .env 的 NEXTAUTH_SECRET，并保留以下本地数据库地址：DATABASE_URL="postgresql://postgres:postgres@localhost:5432/travel_map?schema=public" NEXTAUTH_URL="http://localhost:3000" OBJECT_STORAGE_PROVIDER="local" 地图、LLM 和联网搜索配置在对应功能阶段再填写。凭据只能存放在本地 .env，不能写入 Prompt、截图、日志快照或版本库。初始化数据库客户端和迁移：npm run db:generate npm run db:deploy2.4 配置本地码道工作流码道支持项目级代码生成、代码库理解、研发知识问答、测试生成、文件搜索与修改，以及在授权范围内运行 Git、npm、测试和构建命令。TravelMap 涉及前端、服务端、数据库、Worker 和部署文件，项目级索引可以让 Agent 在修改前读取相关实现。开发过程分为两个阶段：探索阶段：分析用户、场景、边界、风险和可选方案；规范阶段：将确认结果写入规格、设计、任务和验收清单。本案例使用以下 SDD 命令：/sdd-new → 生成需求规格 spec.md /sdd-design → 生成技术设计 design.md /sdd-tasks → 生成任务规划 tasks.md /sdd-apply → 按任务实施并更新状态本地开发流程如下：产品目标 → spec.md → design.md → tasks.md → 失败测试 → 最小完整实现 → 本地目标测试 → 本地全量测试和构建 → 浏览器验收 → 更新文档复杂任务按只读审查、测试定位、文档校验和主实施四类职责拆分。主 Agent 汇总证据后再修改文件，减少跨模块任务遗漏。三、构建 TravelMap 应用3.1 建立基础应用和本地质量门空项目完成依赖安装后，先建立稳定的目录和命令：src/app/ # 页面和 Route Handler src/components/ # 通用组件 src/features/ # 前端领域功能 src/server/ # Router、Service 和基础设施 prisma/ # Schema 和 migrations scripts/ # Worker 与校验脚本 __tests__/ # Vitest 测试 e2e/ # Playwright 测试 docs/ # 规格、设计和运行文档基础 package.json 至少提供以下命令：{ "scripts": { "dev": "tsx scripts/dev.ts", "build": "next build", "typecheck": "tsc --noEmit", "test:run": "vitest run", "test:e2e": "playwright test", "db:generate": "prisma generate", "db:deploy": "prisma migrate deploy" } } 先建立首页冒烟测试，再运行基础质量门：npm run test:run npm run typecheck npm run build npm run dev浏览器访问 http://localhost:3000。此时页面只需要显示项目名称和基础导航，后续功能按 tasks.md 分阶段加入。每个阶段开始前，Agent 读取 spec.md、design.md、tasks.md 和当前测试。3.2 从 Idea 到产品规格3.2.1 第一条 Prompt：先理解问题，不要立即写代码我给码道的起始任务可以概括为：我希望构建一个编排—游记一体化旅行平台。 核心功能包括高效率时间编排、地图路线、多人协作， 以及将结构化行程插入游记。 请先不要编码。先分析用户角色、核心旅程、关键对象、边界条件、 风险与分阶段实现方式；对不清楚的地方提出问题。这一步先确定领域和验收条件，随后再创建业务页面。Agent 将需求拆分为帖子、游记、编排、导入、用户、互动和管理后台等领域，并识别时间调度、地图数据、富文本、权限和内容审核等风险。阶段成果沉淀在：output/prd-travel-journey-platform.mddocs/arrangement-architecture.mddocs/case-report/sdd/spec.mddocs/case-report/sdd/design.mddocs/case-report/sdd/tasks.md3.2.2 统一行程列表与时间板编排模型第一版产品概念仍包含传统行程：每天若干地点，地点之间附路线。但在真实使用中，我发现它难以表达这些情况：一个活动有固定预约时间，但前后需要排队和缓冲；住宿、租车、通票跨越多天，却不应挤占普通时间格；同一天存在多个地点组合和容器；某些活动时间可以移动，某些只能在窗口内移动；拖动一个事件后，交通时间可能不再足够；旅行中只需要执行视图，不需要复杂编辑器。我让 Agent 重新分析领域模型，并停止继续扩展旧结构：请比较传统每日行程列表和日期 × 时间模块化编排两种模型。 重点分析固定事件、柔性事件、交通、缓冲、跨日背景周期、 组合容器、时间冲突、拖动与旅行执行模式。 给出统一模型，并说明哪些字段应由程序确定，哪些可以让用户或 AI 输入。最终，Arrangement 成为唯一的结构化旅行计划模型；旧 Itinerary 被迁移下线。活动、交通、用餐、休息和容器统一为事件，调度器以确定性规则处理时间与冲突。这也是一次重要的产品判断：当新模型已经覆盖旧模型时，继续维护两套近似能力只会放大复杂度。3.2.3 根据实现证据调整产品范围编排工作区完成基础验证后，多人协作和离线编辑被纳入产品范围，依据如下：编排天然由多人共同讨论；旅行现场的网络条件不可控；只有服务端版本、历史和恢复机制完整，协作才可信。因此我允许范围改变，但要求每次改变都回答三个问题：它是否强化核心价值，并避免无关功能堆积？现有架构是否能可靠承载？新增复杂度怎样通过测试和运维材料被控制？3.3 从规格到第一版可用产品3.3.1 安装基础技术并建立领域顺序层次技术选择理由Web 框架Next.js 15 + React 18同一工程承载页面、Server API 与 SSR类型系统TypeScript strict让跨前后端数据变更尽早暴露APItRPC + React Query端到端类型、缓存和请求状态管理数据库PostgreSQL + Prisma事务、关系模型、迁移与并发控制样式Tailwind CSS快速建立一致的响应式设计富文本TipTap结构化富文本与自定义编排节点地图高德地图地理编码、POI、路线、天气实时协作WebSocket + Redis + PostgreSQL Outbox低延迟广播与可靠事件记录结合图片处理Sharp + 本地存储/S3 适配服务端校验、重编码与存储接口测试Vitest + Testing Library + Playwright覆盖纯逻辑、组件、服务与浏览器流程基础架构完成后，按以下顺序实施：用户与认证 → 帖子和互动 → TipTap 游记 → Arrangement 编排 → 保存、历史和离线 → 多人协作 → AI 规划 → 智能导入 → 管理后台每个阶段先更新 Prisma Schema 和 API 契约，再实现页面与组件，最后运行目标测试、类型检查和构建。当前仓库包含约 383 个 TypeScript/TSX 文件、61,000 余行受版本管理的 TS/TSX/Prisma/SQL、47 个 Prisma 模型、27 条数据库迁移、133 个 Vitest 测试文件和 7 个浏览器 E2E 规格文件。这些统计用于说明当前工程规模和验证范围。3.3.2 实现编排工作区实施顺序：在 prisma/schema.prisma 中建立 Arrangement、ArrangementEvent、ArrangementRevision 和素材模型；建立 Zod 领域 Schema、五分钟吸附、半开区间冲突和容器边界测试；实现确定性调度器，通过纯逻辑测试后再接入页面；实现时间板几何、拖动、边缘缩放和素材命中；接入 tRPC 读写、自动保存、版本和 Revision；使用本地浏览器检查跨日拖动、短事件、固定事件、交通下限和公开视图。编排工作区需要提供清晰展示、即时拖放和显式冲突反馈：日期横轴、时间纵轴；五分钟吸附；跨日拖动和上下边缘缩放；活动、交通、用餐、休息和组合容器；全天栏与背景周期；交通时长下限和路线状态；评注轨道；素材库与公开素材复制；自动保存、撤销、重做、历史版本；时间板视图与旅行视图。点击事件可以查看地点、时间、备注与只读详情。公开视图会过滤私人备注、Checklist 等敏感执行信息。3.3.3 实现游记与编排动态关联实施顺序：建立 Journal 数据模型和 TipTap JSON 文档格式；实现标题、列表、引用、链接和图片节点；创建 arrangementBlock 扩展，节点只保存 arrangementId；服务端从文档中提取并校验 embeddedArrangementIds；阅读页通过公开投影读取最新编排；添加不存在、未公开、已删除和脏事件数据测试。游记编辑器直接提供标题、列表、引用、链接和多种图片布局。普通用户无需编写 Markdown。编排通过自定义富文本节点插入游记。这个设计解决了两个问题：作者不需要复制一份很快过时的静态表格；源编排更新后，阅读页可以读取最新的公开投影。3.3.4 内容社区与智能导入内容功能按帖子、互动、用户主页和导入任务的顺序实施。导入功能使用持久任务和 Worker，生成结果先保存为草稿，再由用户审核。平台同时保留帖子与游记：帖子适合轻量图片内容；游记适合图文长叙事；编排适合可执行计划；用户主页、评论、点赞、关注、收藏夹和通知把内容连接起来。智能导入支持 URL 与粘贴文本，能够把非结构化内容转为帖子或游记草稿；当游记中识别到可执行行程时，系统会同步生成编排并建立引用。受登录、反爬和来源平台规则影响时，产品提示用户改用手动粘贴。外部账号只能在合法授权下使用。本地验收包括：创建帖子并上传图片 → 创建富文本游记 → 创建编排 → 在游记中插入编排 → 发布并使用未登录窗口查看公开投影 → 提交文本导入任务 → Worker 生成草稿 → 用户审核后发布3.4 使用 Agent 进行问题定位和迭代3.4.1 我使用的固定迭代模板每次出现问题时，我向 Agent 提供完整的问题结构：现象：用户看到什么？ 期望：完成任务时应该怎样？ 证据：页面、日志、数据或测试说明了什么？ 边界：哪些数据不能破坏，哪些能力不能退化？ 方法：先写失败测试，再做最小完整修复。 验收：目标测试、全量测试、类型检查、构建和真实页面操作。例如：模块无法直接从素材库拖进容器，会被碰撞检测拒绝。 请先写能够稳定复现这个行为的测试，定位素材拖入与已存在模块拖动 是否错误地共用了碰撞规则。修复后验证容器落点、跨日拖动、撤销和自动保存。3.4.2 调整编排卡片的视觉层级编排早期版本能显示事件，但短事件、组合容器和多种时间层级挤在一起时，信息层级不清楚。Agent 先根据代码和页面生成修改方案，我再通过真实页面发现：短事件标题容易被截断；胶囊状态与主要标题争夺空间；交通、用餐和休息缺少快速区分；AI 浮层会遮挡设置或详情操作。我们逐项修改卡片几何、标记、颜色、悬停详情和浮层避让，并保留每轮修改前后的截图。3.4.3 约束 AI 规划的权限和执行流程早期 AI 规划采取自由工具循环：模型一次生成很大的完整对象，Schema 失败后又整份重写。真实运行中出现过：深层 JSON 截断或嵌套字符串；时间格式和持续时间关系矛盾；运行数小时仍在重复工具调用；Worker 中断后从头执行；搜索、地点和路线预算边界不一致；前端已经显示正文，但终态没有正确解锁。这些问题说明，继续扩大模型上下文或工具轮数无法解决结构校验和执行恢复问题。我和 Agent 共同将架构改为受控分阶段流程：理解需求 → 生成候选行程结构 → 联网研究 → POI 解析 → 路线与天气核验 → 确定性排程 → 事实与约束校验 → 有限局部修复 → 生成攻略 → 形成 Proposal → 用户确认后应用最终原则是：模型负责意图、候选和解释；程序负责 ID、时间、路线、派生字段和硬约束；失败只重试当前阶段；已验证阶段可以从检查点恢复；AI 不能直接覆盖正式编排；地点歧义、证据冲突或路线无法核验时必须阻断。3.4.4 增加可靠自动保存和版本控制自动保存早期只在修改后发送一次请求。加入离线和协作功能后，保存协议增加以下要求：客户端操作 ID 保证重试幂等；服务端版本号防止静默覆盖；冲突时进行可解释合并或要求用户处理；离线信封保存元数据和事件；网络恢复后按版本合并；Revision 记录操作者和变更；历史恢复生成新版本，并保留原有历史。保存流程覆盖客户端状态、网络重试、数据库版本和历史记录。3.4.5 构建可扩展协作链路Agent 先设计角色、邀请、评注与事件锁，再通过代码审查发现搜索越权、游标竞态和撤权后锁未释放等问题。最终协作链路包括：owner / editor / commenter / viewer；邮箱或链接邀请、有效期、次数和撤销；在线 Presence；事件级 15 秒软锁与 fencing token；PostgreSQL 有序事件和 Transactional Outbox；Redis Pub/Sub；独立 Collaboration Gateway 与 Relay；WebSocket → SSE → 持久游标轮询的降级链；序列缺口恢复与权威快照回退；Prometheus 指标和告警规则。协作交互的最终方案为：本地立即预览拖动；后台并行获取软锁；获得锁后才提交；锁冲突时自动撤销；拖动期间关闭位置过渡；WebSocket 误路由时快速失败并进入降级通道。自动化测试通过后仍需执行本地双会话浏览器验收，覆盖权限变化、锁冲突、断线和恢复。3.5 规范化项目上下文、测试与追踪3.5.1 项目上下文Agent 每次工作前需要读取当前项目文件，避免依赖旧会话中的过期信息。项目使用以下材料维持共同上下文：文档作用output/prd-travel-journey-platform.md完整产品需求和初始范围CODEARTS_CONTEXT.md历史决策、已实现能力、风险和凭据安全提醒docs/case-report/sdd/spec.md当前产品需求、非目标和可验收场景docs/case-report/sdd/design.md当前架构、数据流、可靠性、安全和部署设计docs/case-report/sdd/tasks.mdSDD 任务状态、代码证据、测试证据和发布待办docs/arrangement-architecture.md编排领域模型和前后端边界docs/arrangement-save-reliability.md自动保存、版本、冲突与恢复协议docs/arrangement-ai-planner-architecture.mdAI 分阶段规划与可信边界docs/arrangement-collaboration-scale-plan.md多实例协作架构docs/operations/arrangement-collaboration-runbook.md故障诊断与运维步骤3.5.2 TDD：先证明问题存在项目实现阶段遵循固定顺序：建立失败测试 → 运行并确认失败原因正确 → 实现最小完整改动 → 运行目标测试 → 运行全量验证 → 浏览器或生产环境验收 → 更新文档测试覆盖：调度器、五分钟吸附、跨日、DST 和时间几何；自动保存、离线恢复、版本冲突和 Proposal；协作协议、Outbox、Redis、WebSocket、软锁和权限；AI Worker、租约、心跳、账本、证据、路线、天气和 SSE；内容权限、URL 与图片安全、密钥信封；导入队列、LLM 结构校验和失败恢复；组件交互、无障碍和浏览器 E2E；Prisma migration 与 PostgreSQL 并发可靠性；健康接口和本地进程启动。最近一次完整实现会话记录了：133 个测试文件 727 项测试通过 TypeScript strict 检查通过 Next.js 生产构建通过本案例报告编写时没有把旧记录当成新的执行结果。当前仓库仍保留测试、Playwright 报告、截图和构建材料；发布新版本前应重新执行完整门禁。2026-07-26 编写本报告时又进行了独立复核：npm run typecheck：通过；npm run build：通过，保留既有 <img> 图片优化警告；npm run test:run：沙箱内 133 个文件中的 132 个通过，720/727 项通过；唯一未通过文件的 7 项均因沙箱禁止监听 127.0.0.1，错误为 listen EPERM，业务断言未失败；在批准本地监听的受控环境重跑该 WebSocket 文件，9/9 项通过。本次证据结论为：应用类型检查和生产构建通过；需要监听本地端口的 WebSocket 测试在允许本地监听的环境中通过。报告同时保留第一次运行时的环境限制和错误信息。3.5.3 需求—设计—实现—验证追踪一个需求只有同时具备以下证据，才算完成：需求设计/决策实现验证时间板拖放确定性调度 + 五分钟吸附scheduler.ts、时间板组件调度器、组件、E2E多人共同编辑权威版本 + 软锁 + 有序事件collaboration services协议、路由、Gateway、容量 HarnessAI 不直接改正式计划Proposal + 差异确认Proposal 服务与抽屉幂等、重基、应用测试断网可恢复离线信封 + 版本合并offline store / recovery离线浏览器用例3.6 完整项目结构与源码交付TravelMap 采用前后端一体的 Next.js 工程，核心目录如下：travel-map/ ├── src/app/ # 页面、路由与健康接口 ├── src/features/arrangements/ # 编排模型、调度器、自动保存与 UI ├── src/components/editor/extensions # TipTap 编排嵌入节点 ├── src/server/services/arrangements # Proposal、协作、公开投影等服务 ├── prisma/ # 数据模型、迁移和种子数据 ├── scripts/ # Worker、Gateway、Relay 与发布校验 ├── __tests__/ # 单元、组件、服务和部署资产测试 ├── e2e/ # Playwright 浏览器用例 └── docs/ # 架构、协议、部署与运行手册项目依赖由 package-lock.json 锁定，必须使用 npm ci，不能在案例步骤中把关键依赖写成无版本约束的临时安装命令。项目源码仓库地址为 GitCode：qq_26761683/travelmap。仓库完成推送后，读者可以通过 SSH 获取与本文对应的完整工程：git clone git@gitcode.com:qq_26761683/travelmap.git travel-map cd travel-map npm ci没有配置 GitCode SSH 公钥时，可以在仓库页面复制 HTTPS 地址。完成依赖安装后，继续执行 2.3 节的本地环境配置和 3.8 节的验证命令。3.7 关键代码讲解与释义本节解释六处核心实现。每一处均来自当前仓库，并关联相应测试或运行证据。3.7.1 确定性调度与可行性校验解决的问题：拖动事件或生成 AI 行程后，系统必须统一判断时间重叠、容器边界、时间窗口和不确定时长风险，不能由页面或模型各自给出结论。核心函数位于 src/features/arrangements/scheduler.ts：export function analyzeArrangement(events: readonly ArrangementEventInput[]) { const conflicts: ArrangementIssue[] = []; conflicts.push(...relativeTimeConflicts(events)); const expectedPairs = pairs(events, false); const expectedKeys = new Set( expectedPairs.map(([left, right]) => `${left.id}:${right.id}`), ); for (const [left, right] of expectedPairs) { conflicts.push({ kind: 'overlap', eventIds: [left.id, right.id], message: `${left.title}与${right.title}发生重叠`, }); } const risks: ArrangementIssue[] = pairs(events, true).flatMap( ([left, right]) => expectedKeys.has(`${left.id}:${right.id}`) ? [] : [{ kind: 'worst_case' as const, eventIds: [left.id, right.id], message: `${left.title}按最长时长可能影响${right.title}`, }], ); return { conflicts, risks, feasibleExpected: conflicts.length === 0, feasibleWorstCase: conflicts.length === 0 && risks.length === 0, }; } 逐项释义：relativeTimeConflicts 先处理相对另一个事件开始或结束的约束；pairs(events, false) 计算期望时长下的真实冲突，冲突会阻止保存或应用；pairs(events, true) 使用最长时长再次计算，只在新增组合中形成 worst_case 风险；feasibleExpected 与 feasibleWorstCase 分别表示预计时长和保守时长下的可行性，界面据此显示风险；同一函数还检查三级容器限制、子事件是否落在父容器内、窗口和最早/最晚时间，省略部分未在代码块中重复展示。这样设计的原因是：自然语言适合提出候选与解释，硬约束必须由确定性程序执行。对应测试为 __tests__/features/arrangement-scheduler.test.ts，界面效果对应 3.3.2 的公开编排与详情截图。3.7.2 可靠自动保存：防止断网和并发导致静默覆盖解决的问题：频繁拖动会产生连续快照；网络错误需要重试；多人同时编辑时，系统必须防止旧版本静默覆盖新版本。核心队列位于 src/features/arrangements/autosave.ts：constructor(options: ReliableAutosaveQueueOptions<TSnapshot>) { this.options = { debounceMs: 900, retryBaseMs: 750, retryMaxMs: 30_000, ...options, }; this.version = options.initialVersion; this.baseSnapshot = options.initialSnapshot; this.acknowledgedSerial = options.initialAcknowledgedSerial ?? 0; } const result = await this.options.save({ serial: active.serial, snapshot: active.snapshot, reason: active.reason, kind: active.kind, expectedVersion: this.version, clientMutationId: active.clientMutationId, }); this.version = result.version; this.acknowledgedSerial = Math.max( this.acknowledgedSerial, active.serial, ); 重试部分：const newest = this.pending as PendingEntry<TSnapshot> | null; const retry = newest && newest.serial > active.serial ? newest : { ...active, attempt: active.attempt + 1 }; this.pending = retry; const exponent = Math.min(retry.attempt, 8); const delay = Math.min( this.options.retryMaxMs, this.options.retryBaseMs * 2 ** exponent, ); this.publish({ status: 'retrying', nextRetryMs: delay, attempt: retry.attempt }); this.schedule(delay); 逐项释义：900ms 防抖减少拖动过程中的无效请求；expectedVersion 让服务端发现版本冲突，并拒绝最后写入者静默覆盖；clientMutationId 让同一次保存的网络重试具备幂等身份；serial 区分快照新旧，重试时优先保留更新的本地快照；网络型错误按指数退避，最多等待 30 秒；权限、参数等不可恢复错误进入 blocked，不做无限重试；冲突恢复会基于 baseSnapshot 合并，并把恢复后的权威版本回传界面。对应测试为 __tests__/features/arrangement-autosave.test.ts。3.4.4 节记录了该实现的产品背景和迭代过程。3.7.3 AI Proposal：AI 只提交建议，用户确认后才落盘解决的问题：AI 可能使用旧版本、生成无效时间或删除用户内容，因此不能直接覆盖正式编排。核心应用逻辑位于 src/server/services/arrangements/proposals.ts：const proposal = persistedProposal( await tx.arrangementProposal.findFirst({ where: { id: input.proposalId, ownerId: input.ownerId }, }), ); if (!proposal) notFound(); const replay = await tx.arrangementRevision.findUnique({ where: { proposalId: proposal.id }, select: { version: true }, }); if (replay || proposal.status === 'applied') { const version = replay?.version ?? proposal.appliedVersion; if (!version) { throw new TRPCError({ code: 'INTERNAL_SERVER_ERROR', message: '已应用提案缺少版本审计记录', }); } return { status: 'applied', proposalId: proposal.id, version, replayed: true }; } if (proposal.expiresAt && proposal.expiresAt.getTime() <= Date.now()) { await tx.arrangementProposal.update({ where: { id: proposal.id }, data: { status: 'expired' }, }); return { status: 'expired', proposalId: proposal.id }; } 应用前的版本与删除确认：if (arrangement.currentVersion !== input.expectedVersion) { throw new TRPCError({ code: 'CONFLICT', message: '编排版本已变化，请先重新预览提案', }); } const rebased = rebaseArrangementProposal(base, desired, current); if (rebased.status === 'conflict') { await tx.arrangementProposal.update({ where: { id: proposal.id }, data: { status: 'stale', validationReport: json({ valid: false, rebaseConflicts: rebased.conflicts, }), }, }); return { status: 'stale', proposalId: proposal.id, conflicts: rebased.conflicts }; } if (missingDeletionIds.length > 0 || unexpectedDeletionIds.length > 0) { return { status: 'confirmation_required', proposalId: proposal.id, missingDeletionIds, unexpectedDeletionIds, }; } 逐项释义：查询同时带 proposalId 和 ownerId，权限校验发生在服务端；ArrangementRevision.proposalId 是幂等屏障，同一 Proposal 重放不会生成两个版本；过期或验证不通过的 Proposal 会被拒绝；正式编排已变化时先重基；无法安全合并则返回 stale，要求重新预览；删除事件需要逐项确认，AI 提出的删除操作不得直接写入数据；最终修改和 Revision 审计记录在 Serializable 事务中一并完成。对应测试为 __tests__/features/arrangement-proposal.test.ts、__tests__/server/arrangement-proposal-service.test.ts 和 __tests__/prisma/arrangement-proposals.test.ts，界面效果对应 3.4.3 的 AI 编排助手截图。3.7.4 Transactional Outbox：数据库成功后，协作消息也能恢复解决的问题：如果数据库已提交但 Redis 广播失败，其他协作者会遗漏更新；如果多个 Relay 并行工作，还要避免乱序和重复认领。事件和 Outbox 在同一数据库事务中写入，代码位于 src/server/services/arrangements/collaboration.ts：const rows = await db.$queryRaw< Array<{ collaborationStreamSequence: bigint }> >(Prisma.sql` UPDATE "arrangements" SET "collaboration_stream_sequence" = "collaboration_stream_sequence" + 1 WHERE "id" = ${input.arrangementId} RETURNING "collaboration_stream_sequence" AS "collaborationStreamSequence"`); const event = await db.arrangementCollaborationEvent.create({ data: { arrangementId: input.arrangementId, streamSequence, actorId: input.actorId ?? null, type: input.type, version: input.version ?? null, payload, }, }); await db.arrangementCollaborationOutbox.create({ data: { eventSequence: event.sequence, arrangementId: input.arrangementId, channel: arrangementRedisKeys(input.arrangementId).channel, }, }); Relay 的认领条件位于 src/server/services/arrangements/collaboration-outbox-relay.ts：WHERE outbox."published_at" IS NULL AND outbox."available_at" <= CURRENT_TIMESTAMP AND NOT EXISTS ( SELECT 1 FROM "arrangement_collaboration_outbox" AS predecessor_outbox JOIN "arrangement_collaboration_events" AS predecessor_event ON predecessor_event."sequence" = predecessor_outbox."event_sequence" WHERE predecessor_outbox."arrangement_id" = outbox."arrangement_id" AND predecessor_outbox."published_at" IS NULL AND predecessor_event."stream_sequence" < event."stream_sequence" ) ORDER BY outbox."id" FOR UPDATE SKIP LOCKED逐项释义：每个编排原子递增 collaboration_stream_sequence，得到权威事件顺序；业务事件与 Outbox 同事务写入，避免数据库已经更新、消息仍未记录；NOT EXISTS 阻止同一编排的后续事件越过尚未发布的前序事件；FOR UPDATE SKIP LOCKED 允许多个 Relay 安全并行认领；Redis 发布失败时保留 Outbox，增加尝试次数并延后 availableAt，后续可以恢复；客户端仍通过 WebSocket、SSE 或持久游标轮询处理断线与序列缺口。对应测试为 __tests__/server/collaboration-outbox-relay.test.ts 和 __tests__/server/collaboration-outbox-listener.test.ts。3.7.5 游记嵌入与公开投影：保持最新，也不泄露私人执行信息解决的问题：游记需要展示编排，但复制一份完整 JSON 会很快过期；直接公开源数据又可能泄露 Checklist、私人备注和执行状态。编辑器节点只保存 arrangementId，阅读时获取最新数据，代码位于 src/components/editor/extensions/ArrangementBlockView.tsx：const { data: arrangement, isLoading } = trpc.arrangements.getById.useQuery( { id: arrangementId }, { enabled: Boolean(arrangementId), retry: false }, ); const events = (arrangement?.events ?? []).flatMap((event) => { const parsed = arrangementEventSchema.safeParse(event); return parsed.success ? [parsed.data] : []; }); {!isLoading && !arrangement && ( <div className="p-5 text-center text-xs text-slate-500"> 编排不存在、未公开或已被删除 </div> )} {arrangement && ( <ArrangementJourneyView title={arrangement.title} days={days} events={events} backgroundPeriods={periods.success ? periods.data : []} timeZone={arrangement.timeZone} compact /> )} 服务端公开投影位于 src/server/services/arrangements/public-projection.ts：return { ...arrangement, mode: 'planning', backgroundPeriods: [], events: arrangement.events.map((event) => { const constraints = event.constraints && typeof event.constraints === 'object' ? Object.fromEntries( Object.entries(event.constraints) .filter(([key]) => key !== 'manualLock'), ) : {}; return { ...event, executionStatus: 'pending', checklist: [], notes: null, constraints, }; }), } as T; 逐项释义：富文本节点只保存稳定引用，避免游记内产生一份无法同步的行程副本；读取时用 Zod safeParse 隔离脏事件，单条异常不会让整篇游记崩溃；不存在、未公开或删除时显示安全降级文案；服务端强制切回 planning，清空背景周期、Checklist、私人备注和实时执行状态；manualLock 属于私人编辑约束，不进入公开页面。对应测试为 __tests__/features/arrangement-public-projection.test.ts，效果对应 3.3.3 的游记阅读页截图。3.7.6 本地健康检查：区分进程存活与依赖就绪解决的问题：本地进程能够监听端口时，数据库或 Redis 仍可能不可用。存活检查和就绪检查需要分别返回状态。src/app/api/health/live/route.ts 提供进程存活检查：export async function GET() { return NextResponse.json({ status: 'ok', service: 'travel-map-web', timestamp: new Date().toISOString(), }, { status: 200, headers: { 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff', }, }); } src/app/api/health/ready/route.ts 检查本地依赖：await prisma.$queryRaw`SELECT 1 AS ready`; const redis = await collaborationRedisConnections().catch(() => null); const redisStatus = process.env.COLLABORATION_TRANSPORT === 'redis' ? await redis?.health() ?? 'unavailable' : undefined; return NextResponse.json({ status: redisStatus === 'unavailable' ? 'degraded' : 'ready', checks: { database: 'ok', ...(redisStatus ? { redis: redisStatus } : {}), }, }); 逐项释义：/api/health/live 只确认 Web 进程能够响应；/api/health/ready 执行 SELECT 1，确认 PostgreSQL 可访问；启用 Redis 协作模式时，就绪接口继续检查 Redis；Redis 不可用时返回 degraded，数据库异常时返回 HTTP 503；两个接口均禁用缓存，避免旧健康结果影响判断。对应实现为两个健康 Route Handler。本地启动后使用 curl 验证，部署阶段继续复用相同接口。这六组代码对应调度、保存、AI 权限、协作事件、公开数据和运行状态六项核心质量要求。3.8 本地运行、测试和效果验收3.8.1 初始化并启动全部本地进程完成各功能任务后，执行：npm ci npm run db:generate npm run db:deploy npm run devnpm run dev 启动 Web、Import Worker 和 Planner Worker。设置 COLLABORATION_TRANSPORT=redis 后，还会启动 Collaboration Gateway 和 Relay。本地健康检查：curl -fsS http://localhost:3000/api/health/live curl -fsS http://localhost:3000/api/health/ready3.8.2 执行自动化质量门npm run test:run npm run typecheck npm run build本报告采集证据时，类型检查和生产构建通过。普通测试在受限沙箱中通过 720/727 项；7 项 WebSocket 测试因本地监听权限产生 listen EPERM。在允许本地监听的环境中重跑对应文件，9/9 项通过。报告保留两次执行条件和结果。3.8.3 执行本地浏览器验收按顺序检查：注册、登录和用户主页；帖子、游记和编排的创建与公开页面；时间板拖放、缩放、冲突提示、撤销和自动保存；游记插入编排和公开投影；邀请、成员角色、评注、事件锁和双会话同步；WebSocket 断开后的 SSE 与轮询降级；AI Planning Run、Proposal 预览和用户确认；URL/文本导入、草稿审核和失败重试；断网读取、网络恢复和版本合并。3.9 部署项目代码到华为云3.9.1 选择部署方案部署任务同样在码道会话中完成：Agent 先读取运行依赖、Worker、对象存储与长连接需求，再对照华为云官方文档比较 FunctionGraph、CCE、CAE、Flexus 与 ECS。最终选择按需 ECS 单机 Demo，原因是：项目包含 Web、导入 Worker、规划 Worker和协作常驻进程；需要 PostgreSQL、Redis、WebSocket、SSE 和图片处理；当前 Demo 采用 Compose，以控制部署时间和资源费用；所有资源都要能按需释放；同时保留未来迁移到 RDS 和多应用节点的路径。3.9.2 当前 Demo 架构公网用户 │ ▼ 域名 / HTTPS / EIP │ ▼ Caddy :80/:443 ├── Next.js Web :3000（仅容器内网） └── Collaboration Gateway :3001（仅容器内网） 单台按需 ECS + EVS ├── Web ├── Import Worker ├── Planner Worker ├── Collaboration Gateway ├── Collaboration Relay ├── PostgreSQL 16 ├── Redis 7.4 ├── Prometheus └── Redis/PostgreSQL Exporter ECS ──► OBS 公共读媒体桶 ECS ──► OBS 私有数据库备份桶 ECS ◄── SWR 不可变应用镜像3.9.3 第一步：准备 VPC、安全组、ECS、EVS 和 EIPDemo 推荐基线：资源建议ECS按需、x86、4 vCPU / 8 GiB系统盘80 GiB 通用型 SSDEVS 数据盘100 GiB，承载 PostgreSQL、Redis 和短期备份EIP按流量、5–10 Mbit/s 峰值安全组公网入方向80、443；22 仅允许固定管理 IP明确不开放：3000：只能由 Caddy 访问；3001：只能由 Caddy 转发 WebSocket；5432：PostgreSQL 只允许容器内网；6379：Redis 只允许容器内网；Docker API、Portainer 等管理端口。EVS 初始化时必须先用 lsblk、blkid、findmnt 确认目标盘，再格式化新盘。/etc/fstab 使用 UUID，不能假设重启后设备名不变。3.9.4 第二步：创建两个 OBS 桶媒体和备份不能共用一个桶：桶权限内容媒体桶公共读，禁止公共写用户上传并经过服务端重编码的公开图片数据库备份桶私有，建议服务端加密PostgreSQL 逻辑备份与校验和使用专用 IAM 用户和最小权限，不使用主账号 AK/SK。部署前运行：npm run deploy:check-storage该脚本依次执行上传测试对象、通过公网读取和删除对象，可以提前发现 Endpoint、Region、AK/SK、桶策略或公开 URL 配置错误。3.9.5 第三步：构建并推送 SWR 镜像在可信构建机执行：npm ci npm audit --omit=dev npm run test:run npm run typecheck npm run buildApple Silicon 为 x86 ECS 构建时：docker buildx build \ --platform linux/amd64 \ --build-arg NEXT_PUBLIC_AMAP_KEY=浏览器高德Key \ --build-arg NEXT_PUBLIC_AMAP_SECURITY_CODE=高德安全密钥 \ -t swr.实际区域.myhuaweicloud.com/组织名/travel-map:不可变版本号 \ --push \ . 这里有三条不可越过的边界：使用不可变标签，不长期依赖 latest；NEXT_PUBLIC_* 会进入浏览器 bundle，修改后必须重新构建；数据库、OBS、LLM 和加密密钥不能作为 build arg。3.9.6 第四步：生产配置与迁移生产配置分为 Compose 环境和应用环境：deploy/huawei-cloud/.env：镜像地址、域名、PostgreSQL/Redis 密码和数据目录；deploy/huawei-cloud/app.env：NextAuth、高德、LLM、OBS、健康检查和加密密钥。两个文件都不能提交到仓库，权限应设为 600。上线前先检查：npm run deploy:check-env docker compose --env-file .env config --quiet 再进行备份、拉取和迁移：./backup-postgres-to-obs.sh docker compose --env-file .env pull docker compose --env-file .env up -d postgres redis docker compose --env-file .env --profile tools run --rm migrate云上结构只允许：prisma migrate deploy不能使用 prisma db push 掩盖 migration drift。3.9.7 第五步：启动服务与 HTTPSdocker compose --env-file .env up -d --no-build docker compose --env-file .env ps Caddy 负责：80/443；自动 HTTPS；安全响应头；WebSocket 路由；SSE 关闭代理缓冲。更新 Caddyfile 后必须验证运行中的 Caddy 已加载新配置。项目曾出现文件已经上传、容器仍使用旧路由的问题，因此部署文档要求强制重建容器或明确重新加载 Caddy 配置。部署验收还发现拖动开始前等待远程 Redis 软锁会增加约一秒延迟。3.4.5 节记录的处理方式包括本地立即预览、后台获取软锁、获得锁后提交，以及锁冲突时撤销预览。该问题需要在真实网络环境中验证，本地回环网络无法提供同等延迟条件。3.9.8 第六步：健康与业务验收基础健康接口：curl -fsS https://travelmap.linykweb.top/api/health/live curl -fsS https://travelmap.linykweb.top/api/health/ready2026-07-26 本案例采集报告素材时，真实响应为：{"status":"ok","service":"travel-map-web"} {"status":"ready","checks":{"database":"ok","redis":"ok"}} 业务验收至少包括：注册、登录和管理员权限；帖子、游记和编排公开页；图片上传、读取和删除；导入任务由 Worker 领取；AI 规划 SSE 与轮询恢复；WebSocket 协作、撤权和重连；浏览器刷新、断网与离线恢复；OBS 备份对象可下载；pg_restore --list 能读取备份。3.9.9 更新、回滚和备份推荐发布顺序：备份数据库 → 推送新不可变镜像 → 拉取镜像 → 执行向前兼容 migration → 启动/重建服务 → 健康检查 → 业务冒烟 → 观察协作、Worker 和数据库指标应用回滚可以把 TRAVEL_MAP_IMAGE 改回上一个标签。数据库迁移不能简单假设可逆；涉及数据结构删除时，必须提前设计 expand/contract 迁移或通过备份恢复。每天备份默认意味着最长约 24 小时 RPO。报告不能把它写成高可用生产架构。3.9.10 单机 Demo 的边界当前架构是单故障域：ECS 故障会同时影响 Web、Worker、Redis 和 PostgreSQL；没有数据库主备自动切换；4C8G 下多个服务存在资源竞争风险；本地容量 Harness 的 1k/5k/10k 连接结果不等于云上已经承载相同并发；恢复时间取决于镜像、备份和人工操作。如果平台进入正式长期运营，演进方向是：PostgreSQL → RDS 主备 Redis → DCS 媒体 → 私有桶 + CDN/签名访问策略 Web/Gateway/Worker → 多节点 Caddy → ELB/Ingress 监控 → AOM/LTS 或完整可观测平台3.10 阶段成果3.10.1 产品成果帖子、游记和编排的一体化内容平台；可拖放、可缩放、可跨日的时间板；地点、路线、交通、缓冲、固定事件和背景周期；游记富文本与编排嵌入；收藏、评论、点赞、关注、通知和公开收藏夹；URL/文本智能导入与审核；用户、内容、举报、账号池和 AI 配置后台。3.10.2 协作成果四级成员角色；邀请、Presence、评注与事件锁；WebSocket/SSE/轮询降级；PostgreSQL Outbox + Redis；版本、审计、冲突与权限回收；Prometheus 指标和运行手册。3.10.3 AI 与可靠性成果持久 PlanningRun、租约、心跳、重试与 fencing token；分阶段、可恢复的规划流程；来源、证据、事实冲突和成本账本；地点、路线与天气 fail-closed；Proposal 差异审查和用户确认；失败任务按最新配置原地重试。3.10.4 工程成果TypeScript strict；Prisma migrations；单元、组件、服务、数据库和浏览器测试；Docker 多阶段镜像；华为云 Compose、Caddy、OBS、SWR 与备份材料；存活、就绪和规划健康接口；部署、协作、备份和故障排查文档。3.11 人与 Agent 的职责边界阶段我负责码道负责Idea提出真实问题、目标与价值判断展开角色、场景、边界与风险需求决定优先级和非目标生成规格、查漏补缺、保持一致性设计判断产品取舍分析架构、数据模型和实施路径实现审批范围和重要变更读取代码、生成测试、修改文件、执行命令迭代提供真实现象和体验判断定位根因、补回归测试、完成修复验收判断结果是否符合使用预期运行测试、类型检查、构建和浏览器操作部署掌握账号、凭据和生产授权生成部署材料、核对官方文档、执行受控命令运维决定故障处置和风险接受分析日志、健康状态和回滚路径以下三个决定由人负责：这个功能是否值得做；这个风险是否可以接受；什么证据足以说明已经完成。3.12 案例总结本案例形成了一套从空项目到完整应用的 AI 辅助开发流程：创建本地空项目 → Agent 完善需求 → 编写 Spec、Design 和 Tasks → 建立失败测试 → 实现最小完整改动 → 执行本地测试、构建和浏览器验收 → 部署华为云 → 配置健康检查、备份和回滚 → 更新架构、测试和运行文档项目完成了以下主要调整：使用模块化编排统一旧行程列表；增加多人协作、权限、软锁和有序事件；使用受控 Proposal 管理 AI 规划结果；为保存、恢复、规划和协作增加审计与验证证据；完成本地运行、华为云部署、监控、备份和回滚材料。每项重要变更均关联需求、设计、代码和验证结果。人负责产品取舍、风险接受和发布授权，Agent 负责上下文分析、任务实施和证据整理。四、释放资源删除云资源可能不可恢复。先确认体验已经结束，并把需要保留的数据下载到受控位置。4.1 备份并验证数据在 ECS 的 deploy/huawei-cloud 目录执行最后一次 backup-postgres-to-obs.sh；进入 对象存储服务 OBS > 桶列表 > 私有备份桶，下载最新数据库备份及校验和；使用 pg_restore --list <备份文件> 验证备份可读；导出需要保留的公开媒体对象；记录最后一个可用的 SWR 镜像不可变标签。如果没有完成以上步骤，后续删除 ECS、EVS 或 OBS 对象可能导致数据永久丢失。4.2 删除 ECS、EVS 和 EIP进入 弹性云服务器 ECS > 弹性云服务器，选择本案例 ECS，单击 更多 > 删除；在确认对话框中核对是否需要同时删除系统盘、数据盘并释放绑定的 EIP；进入 云硬盘 EVS > 云硬盘，检查是否仍有未随 ECS 删除的按需数据盘，确认无保留需求后删除；进入 虚拟私有云 VPC > 弹性公网 IP 和带宽，释放仍处于计费状态的 EIP 和带宽；最后检查 安全组 和 VPC，仅在没有其他业务资源依赖时删除。ECS 关机后，EVS、EIP 等资源仍可能计费。需要按资源清单逐项释放。4.3 清理 OBS、SWR 与访问凭据进入 容器镜像服务 SWR > 我的镜像 > 镜像版本，删除不再需要的 TravelMap 镜像版本；若整个组织还承载其他项目，不要删除组织；进入 对象存储服务 OBS > 桶列表，分别检查媒体桶和备份桶；下载需保留对象后清空版本、碎片和对象，再删除不再使用的桶；保留对象仍会计费；进入 统一身份认证服务 IAM > 用户 > 安全设置 > 访问密钥，停用或删除本案例专用 AK/SK；在域名服务商或 云解析服务 DNS > 公网域名 中删除不再使用的 TravelMap 解析记录；在费用中心检查 ECS、EVS、EIP、OBS 和其他按需资源是否仍有计费项。五、扩展资料说明5.1 可复用 Prompt5.1.1 Idea 完善请先不要编码。阅读项目上下文，围绕目标用户、核心旅程、关键对象、 边界条件、失败场景、非目标和阶段计划完善这个 Idea。 请区分事实、假设和需要我决定的产品取舍。5.1.2 架构审查请只读审查当前实现。先给出数据流、权限边界、并发模型和故障恢复链路， 再列出按严重度排序的问题。每个问题必须包含代码证据、影响范围、 建议方案和需要增加的测试。本轮不要修改文件。5.1.3 TDD 修复现象： 期望： 现有证据： 不可破坏的行为： 请先增加一个能稳定复现问题的失败测试，确认它因目标原因失败； 然后实现最小完整修复，运行目标测试、全量测试、类型检查和生产构建。 如果真实页面行为无法由测试证明，再执行浏览器验收。5.1.4 部署设计请先盘点项目的 Web、数据库、Worker、长连接、对象存储和凭据需求， 再对照华为云官方文档比较候选部署方案。 输出推荐架构、资源规格、网络边界、费用与故障域， 并列出上线前阻断项。本轮先分析，不生成虚假的成功结论。5.1.5 发布验收请按发布门禁检查：依赖安装、测试、类型、构建、Prisma migration、 Docker/Compose 配置、健康接口、对象存储、Worker、WebSocket、SSE、 备份和回滚。每项给出实际命令、结果和证据位置。 未执行的项目必须明确标记为未执行。5.3 官方与项目资料5.3.1 华为云码道华为云码道官方产品页产品介绍码道 IDE/CLI 下载CLI SDD 规范驱动开发CLI SkillsCLI 自定义命令CLI MCPCLI 子智能体CLI 权限管理CLI 沙箱机制代码库索引5.3.2 华为云部署弹性云服务器 ECS对象存储服务 OBSSWR 上传镜像CodeArts BuildCodeArts DeployCodeArts Deploy 快速入门

基于华为云码道的校园二手书交易平台全栈开发实践1. 案例概述在高校学习生活中，教材和课外书具有明显的阶段性。课程结束、考试完成或学生毕业后，大量书籍进入闲置状态；与此同时，新生和低年级学生仍然需要以较低成本获取教材。传统微信群、朋友圈和线下摆摊存在信息分散、搜索效率低、书籍状态不透明、交易过程无法追踪等问题。本案例围绕“让校园闲置书低成本、安全、可追踪地流转”这一目标，构建一套前后端分离的校园二手书交易平台。项目提供用户注册登录、书籍发布与审核、关键词检索、购物车、站内余额、管理员充值、订单履约、收藏、评价、站内通知和后台统计等功能，最终形成“发布—审核—选购—支付—发货—收货—评价”的完整业务闭环。项目在开发过程中使用华为云码道辅助完成需求梳理、系统设计、任务拆解、功能开发和代码检查，并在仓库中沉淀了 spec.md、design.md 和 tasks.md 等规格文档。当前交付版本采用 Vue 3、Node.js、Express 和 sql.js，能够在本地快速运行，也便于进一步部署到华为云。2. 案例目标本案例不是只完成静态页面，而是以“可正常运行、可完整演示、可自动验证”为交付目标。主要目标如下：实现普通用户、买家、卖家和管理员之间清晰的权限边界。实现真实书籍封面、分类筛选、关键词搜索和书籍详情。实现管理员为用户充值、用户使用站内余额购买书籍的资金闭环。实现购物车、跨卖家拆单、订单支付、卖家发货、买家收货和评价。为充值、支付和订单状态变化保留资金流水与站内通知。使用自动化测试验证权限、状态、余额和异常场景。保留可部署到华为云 ECS、RDS 和 OBS 的演进空间。3. 开发环境与技术选型3.1 前端Vue 3：构建组件化单页应用。Vue Router：管理用户端和管理端路由。Pinia：保存登录用户、余额和公共业务状态。Element Plus：提供表单、表格、弹窗、分页和消息反馈组件。Axios：统一访问后端 REST API。Vite：提供开发服务器和生产构建。3.2 后端Node.js + Express：提供 REST API。JWT：完成身份认证和接口鉴权。bcryptjs：保护用户密码。Multer：处理书籍封面上传。sql.js：使用 SQLite 数据文件完成轻量持久化。Supertest + Node.js Test Runner：实现接口级集成测试。3.3 工程结构项目当前主要由以下部分组成：used-book-web/ Vue 3 前端 used-book-api/ Express 后端与 SQLite 数据 used-book-server/ 早期 Spring Boot 实现（保留版本） .codeartsdoer/ 需求、设计和任务规格文档 README.md 项目启动、账号和功能说明早期系统设计采用 Spring Boot/MySQL。为了降低实习项目演示和单机部署的复杂度，当前默认运行主线演进为 Express/sql.js。案例以实际运行版本为准，同时保留早期版本作为架构演进记录。4. 使用华为云码道完成项目构建4.1 需求分析首先向华为云码道提供校园二手书的业务背景、目标角色和初步功能设想，请其帮助拆分功能域、明确验收条件和识别边界场景。需求阶段重点确认了以下规则：新发布书籍默认进入待审核状态。普通用户不能访问管理接口。用户不能购买自己发布的书籍。订单详情只能由相关买家、卖家或管理员访问。余额不足时必须阻止支付。同一购物车存在多个卖家时，需要按卖家拆分订单。只有卖家可以发货，只有买家可以确认收货和评价。需求分析结果沉淀在 .codeartsdoer/specs/used_book/spec.md 中，为后续设计和测试提供统一依据。4.2 系统设计在需求规格基础上，继续让华为云码道从数据模型、接口、权限、业务状态和异常处理几个方面给出设计建议。系统最终包含 13 张业务表：数据表作用user用户、角色、余额与账户状态category书籍分类book书籍基础信息、卖家、价格与状态book_image书籍图片price_change_log价格变更记录cart购物车order买家、卖家和订单状态order_item订单中的书籍价格快照review交易完成后的评价wallet_transaction充值、购买支出和卖家收入流水notification支付、发货、收货等站内通知favorite用户收藏book_view_log书籍浏览记录系统设计文档和任务拆解分别记录在 design.md 和 tasks.md 中。设计阶段最大的价值是提前发现“余额支付不是单表状态更新”“多卖家订单不能由一个卖家统一履约”等问题。4.3 任务拆解项目按照依赖关系分阶段实施：初始化前后端项目与数据库。完成用户注册、登录和 JWT 鉴权。完成分类、书籍发布、封面上传和审核。完成首页检索、详情、收藏和浏览记录。完成购物车和订单创建。完成管理员充值、余额支付和资金流水。完成发货、收货、评价和通知。完成管理后台和统计。增加集成测试并执行完整代码审查。通过规格驱动的任务拆解，可以减少前后端并行开发时的接口歧义，也方便在每个阶段运行测试。4.4 关键功能迭代在初版完成后，又使用华为云码道对照 README 检查实际代码和需求，重点完成了两轮增强。第一轮增强解决了交易资金来源问题。系统原本具有买卖功能，但缺少适合演示的充值入口。优化后只有管理员可以为指定用户增加站内余额，同时记录充值金额、备注、操作时间和变动后余额。普通用户不能直接修改余额。第二轮增强提升了书籍展示真实性。项目演示数据补充了真实书籍封面，并为图片加载失败保留默认占位图，避免外部图片失效导致页面结构异常。最后对完整仓库进行功能和代码检查，运行后端集成测试和前端生产构建，修复字段命名、参数校验、权限边界、待审核书籍可见性等问题。5. 系统总体方案5.1 逻辑架构浏览器 │ ▼ Vue 3 单页应用 │ Axios / JSON / JWT ▼ Express REST API ├─ 用户与鉴权 ├─ 书籍与审核 ├─ 购物车与订单 ├─ 钱包与资金流水 ├─ 收藏、评价与通知 └─ 管理后台与统计 │ ├─ SQLite 数据文件 └─ 封面上传目录前端通过 Axios 访问 API，后端使用 JWT 判断用户身份和角色。所有关键权限均在服务端再次校验，不能只依赖前端隐藏按钮。业务数据持久化到 SQLite 文件，封面图片由上传目录提供静态访问。5.2 用户与权限普通用户可以浏览和搜索书籍、发布书籍、加入购物车、购买、发货或确认收货，但具体操作受到资源归属限制。管理员拥有用户管理、书籍审核、充值和数据统计权限。管理接口统一检查 admin 角色，普通用户直接调用接口也会被拒绝。5.3 书籍发布与审核用户发布书籍时需要填写书名、作者、分类、价格、成色、出版信息和描述，并可上传封面。前端提供表单提示，后端再次校验日期、价格和分类合法性。新书默认处于待审核状态。只有审核通过并处于在售状态的书籍才进入公共列表，避免违规或错误内容直接公开。首页支持分类、关键词、价格与排序筛选。搜索同时匹配书名和作者，详情页展示封面、价格、成色、卖家和描述。5.4 购物车与跨卖家拆单用户可将不同卖家的书籍加入同一个购物车。创建订单时，后端重新读取每本书的最新状态和价格，并按 sellerId 分组，为每个卖家生成独立订单。这种设计使每个卖家只能处理自己的订单，发货和结算互不影响，也避免某个卖家延迟发货导致其他订单无法推进。5.5 站内余额与管理员充值系统买卖书籍使用平台站内余额。管理员可在用户管理页面选择用户，输入充值金额和备注。服务端校验管理员身份、金额范围和目标用户，并同时更新用户余额和钱包流水。钱包流水包含：管理员充值；购买支出；卖家收入；交易说明；变动后余额；操作时间。这样既能方便训练营项目演示，也能让每次资金变化可追踪。5.6 订单状态订单的主要状态流转如下：待支付 pending_payment │ 买家余额支付 ▼ 已支付 paid │ 卖家发货 ▼ 已发货 shipped │ 买家确认收货 ▼ 已完成 completed │ ▼ 评价 review创建订单后，买家可以支付或取消。支付时后端重新检查订单状态和余额，余额不足则拒绝。卖家只能对已支付订单发货，买家只能对已发货订单确认收货。关键状态变化会生成站内通知。6. 关键技术难点与解决方案6.1 资金与业务状态一致性支付涉及买家余额、钱包流水、订单状态、书籍状态和通知等多项变化。如果只在前端扣减显示余额，刷新页面后数据会失真，也可能产生越权支付。本项目将后端作为唯一可信来源。支付请求到达后，后端依次验证：当前用户是否为订单买家；订单是否处于待支付状态；订单中的书籍是否仍可交易；买家余额是否足够；所有校验通过后再执行扣款、状态更新和流水记录。前端只负责展示后端返回的新余额和订单状态。6.2 多卖家订单拆分购物车是买家维度的数据，但订单履约是卖家维度的数据。如果不同卖家的书籍进入同一订单，一个卖家可能看到或操作另一个卖家的书籍。系统在创建订单时先按卖家分组，再分别创建订单和订单条目。自动化测试专门覆盖跨卖家拆单，验证订单数量、卖家归属和金额计算。6.3 状态机与越权防护订单详情、评价删除、书籍审核和后台统计都存在越权风险。系统在每个接口中校验用户角色、资源归属和前置状态。例如普通用户不能删除他人评价，未参与订单的用户不能查看订单详情，待审核书籍不会出现在公共列表。6.4 真实封面与降级展示真实封面可以显著改善项目效果，但外部图片可能失效、加载缓慢或出现跨域问题。当前演示数据使用可访问封面，同时保留默认封面作为降级展示。部署到生产环境后，建议将确认合规的图片迁移到 OBS 或项目静态资源。6.5 架构演进的一致性项目早期规格采用 Spring Boot/MySQL，当前交付主线采用 Express/sql.js。为了避免评审时出现文档与实现不一致，本案例明确区分“早期设计版本”和“当前可运行版本”，并建议后续以实际云端部署技术栈更新设计文档。7. 测试与验证项目执行统一检查命令：npm run check检查结果如下：后端集成测试：14/14 通过，0 失败；前端生产构建：成功；Vite 版本：8.1.5；前端转换模块：1799 个；本地 Web 服务：http：//localhost:5173；本地 API 服务：http：//localhost:8088。14 个集成场景覆盖：公共书籍接口字段采用 camelCase；搜索同时匹配书名和作者；非法出版日期和分类被拒绝；不存在的接口返回统一 JSON 404；订单详情权限隔离；普通用户不能删除评价；购物车返回卖家信息；待审核书籍的可见性；管理后台统计；管理员充值、余额购买和卖家入账；跨卖家购物车拆分订单；支付、发货、收货、评价和通知完整闭环；收藏功能；余额不足时拒绝支付，并允许取消订单。除自动化测试外，还进行了真实页面操作。本次演示由管理员为用户充值 100 元，用户以 20 元购买《三体》，支付后余额为 80 元，同时生成购买支出流水和支付成功通知。8. 运行与演示8.1 启动方式在项目根目录执行：npm run dev该命令同时启动前端和 API。执行 npm run check 可以运行后端测试并构建前端生产包。8.2 推荐演示路径在首页搜索并查看《三体》详情。管理员进入后台，为测试用户充值 100 元。买家将书籍加入购物车并创建订单。使用站内余额支付，查看余额由 100 元变为 80 元。查看资金流水和支付成功通知。卖家发货，买家确认收货并评价。回到管理后台查看订单和书籍状态统计。8.3 运行效果截图以下截图展示首页、书籍详情、管理员充值、购物车、订单支付、钱包流水、站内通知和后台统计等核心效果。9. 华为云实际部署项目已部署到华为云 ECS，在线演示地址为 http：//124.70.103.252/，健康检查地址为 http：//124.70.103.252/health（受论坛外链白名单限制，复制地址时请将中文全角冒号 ： 改为英文半角冒号 :）。完整案例 PDF 下载地址：http：//124.70.103.252/used-book-case-report.pdf（复制时同样将 ： 改为 :）。使用 Nginx 部署 used-book-web/dist，并反向代理 /api、/uploads 和 /health；使用 systemd 运行 Node.js API，支持开机启动和异常重启；SQLite 与 uploads 位于独立持久化目录；API 仅监听 127.0.0.1:8088，8088 不直接对公网开放；部署时生成随机 JWT 密钥，并使种子账号默认密码失效；演示实例计划于 2026 年 7 月 31 日 02:49（GMT+08:00）自动释放。当前部署适合训练营阶段验收。如果后续需要长期运行，可增加域名和 HTTPS，将 SQLite 迁移到华为云 RDS，将上传图片迁移到 OBS，并增加集中日志、监控和备份。10. 案例总结本项目完成了从需求、设计、编码、测试到交付材料整理的完整过程。与简单的增删改查项目相比，校园二手书平台重点解决了多角色权限、订单状态、跨卖家拆单、资金流水和业务一致性问题。华为云码道在项目中的主要价值体现在：将模糊的项目想法转化为可执行的规格和验收条件；从需求中识别状态、权限和异常场景；形成设计文档和任务拆解；辅助实现管理员充值、真实封面和完整交易闭环；对照 README 和代码进行仓库级检查；通过自动化测试验证功能并发现边界问题；将代码、截图、测试结果和指导书要求整理为可交付案例。

一、概述1.1 案例介绍本案例基于华为云码道（CodeArts）代码智能体，演示如何使用规范驱动开发（SDD）全流程高效构建并落地一套智慧社区 PMS 小区物业管理系统。通过自然语言指令与业务技能联动，快速完成从“总体设计”、“MySQL DDL建表”、“RESTful API接口定义”到“策略模式后端核心计费代码（Spring Boot）”及“Vue 3前端界面”的全栈开发与部署调优，帮助开发者掌握AI辅助现代软件工程的最佳实践。1.2 适用对象个人开发者高校学生1.3 案例时间本案例总时长预计4小时。1.4 案例流程说明：AI IDE 华为云码道（CodeArts）代码智能体安装部署；下载物业管理项目所需skills；借助码道进行数据清洗、归因分析并完成现状诊断；CodeArts IDE集成CodeArts Pipeline插件实现本地调用华为云云上流水线任务；线上查看运行结果；得到物业管理课题分析与系统设计结果。1.5 资源总览资源名称规格单价（元）华为云码道（CodeArts）代码智能体专业版代金券购买二、环境和资源准备2.1 AI IDE华为云码道安装部署完成 Windows 版 AI IDE 华为云码道（CodeArts）代码智能体安装部署。2.2 配置相关环境和skills在本地安装Python / Node.js，为后续系统设计做好准备。在华为云码道AI IDE中配置物业管理相关的Skills，包括官方的code-reviewer、database-design、java-ut-generator等技能。三、物业管理系统设计3.1 项目背景与需求本项目为一家中小型住宅小区物业服务公司开发轻量级、模块化的物业管理系统，解决以下核心痛点：痛点描述房产与业主数据混乱一户多车、租户变动频发，台账更新不及时，"人-房-车"绑定关系难以精准掌握计费与收缴效率低下房屋物业费人工核对成本高；停车位收费标准不一，容易漏收、错收账单缺乏透明度与追溯业主对计费规则存疑，收缴记录难以快速检索，催缴阻力大车位权属不清晰售出/租用车位混杂管理，租期到期缺乏预警，易引发纠纷编写项目背景与需求.md文档，并根据文档内容对智能体提出要求：#项目背景与需求.md 请帮我完成以下工作： 第一阶段：需求分析与总体设计 1. 加载`/database-design` 和`/property-business-rules`技能。 2. 使用`spec-story-generator`方法论进行需求细化与场景拆解。 3. 识别系统的关键决策点与潜在风险。 4. 设计系统整体分层架构与核心模块划分。 5. 定义数据模型设计思路。 6. 规划核心RESTful API接口清单。 7. 制定后续代码与组件的实施步骤计划。 第二阶段：文档输出要求 1. 输出一份完整的总体设计思路与架构方案文档（Markdown格式，使用中文编写）。 2. 避免使用复杂数学符号，排版清晰，结构严谨，便于后续直接指导开发。后续对话码道进行优化调整：加载/database-design、/property-business-rules 和 spec-story-generator skill的规则逻辑，分析一下总体设计文档，是否有需要优化或调整的地方，若有请进行最优调整3.2 系统架构3.2.1 整体架构采用前后端分离架构：后端：Spring Boot 2.7.18 + Java 8 单体应用，RESTful API前端：Vue 3 SPA，Vite 构建，Element Plus UI数据库：MySQL 8.0，utf8mb4 字符集认证：JWT 无状态认证3.2.2 后端技术栈技术版本用途Spring Boot2.7.18应用框架Java1.8运行时MyBatis-Plus3.5.7ORM 框架Spring Security5.7.x认证授权JJWT0.11.5JWT 令牌BCrypt-密码加密下图为后端项目整体构建过程。项目从pom.xml骨架与分层包结构起步，率先搭建了统一响应体、全局异常处理和审计字段基类等公共组件，为后续业务模块提供了规范化的基础支撑。在此基础上，依照领域模块的依赖关系，依次实现了认证授权（auth）、小区与房产管理（community）、人员管理（resident）、车位管理（parking），再通过策略模式落地计费与账单生成（billing），进而完成收缴管理（payment）和统计看板（dashboard）。开发全程依托Spring Boot 2.7.18 + MyBatis-Plus + Spring Security + JWT，严格遵循RESTful规范与数据库设计。3.2.3 前端技术栈技术版本用途Vue3.5.x前端框架Vite8.1.x构建工具Element Plus2.14.xUI 组件库Pinia4.0.x状态管理Vue Router4.6.x路由管理ECharts6.1.x图表可视化Axios1.18.xHTTP 客户端dayjs1.11.x日期处理3.2.4 模块架构后端按业务领域划分为8个模块：模块职责auth用户认证、JWT 令牌、账号管理community小区、楼栋、单元、房间、费率配置resident人员管理、房间绑定关系parking车位管理、车位分配/释放billing账单生成、计费策略（策略模式）payment缴费录入、逾期查询dashboard数据看板、收缴统计common通用响应、配置、工具类3.3 核心业务规则3.3.1 物业费计算应缴物业费 = 房屋建筑面积 × 单位物业费单价 × 计费月数建筑面积必须 > 0单价通过费率配置表按生效日期查询3.3.2 车位计费策略车位类型计费周期计算规则售出车位 (type=1)按年年管理费 = 费率配置单价 × 1租用车位 (type=2)按月月租金 = 费率配置单价；不足整月按比例折算：月租金 / 当月天数 × 实际使用天数策略模式实现类：BillingStrategyFactory — 策略工厂，按 feeType 路由SoldParkingStrategy — 售出车位按年计费策略RentedParkingStrategy — 租用车位按月计费策略PropertyFeeService — 物业费计费服务// 售出车位：按年计费 @Component public class SoldParkingStrategy implements BillingStrategy { @Override public List<Bill> calculate(ParkingFeeContext ctx) { BigDecimal amount = ctx.getUnitPrice().setScale(2, RoundingMode.HALF_UP); Bill bill = new Bill(); bill.setAmount(amount); bill.setSourceType(ctx.getSourceType()); bill.setSourceId(ctx.getParkingSpotId()); bill.setBillingPeriodStart(ctx.getBillingPeriodStart()); bill.setBillingPeriodEnd(ctx.getBillingPeriodEnd()); bill.setPaidAmount(BigDecimal.ZERO); bill.setStatus(0); return Collections.singletonList(bill); } } // 租用车位：按月计费，不足月按天折算 @Component public class RentedParkingStrategy implements BillingStrategy { @Override public List<Bill> calculate(ParkingFeeContext ctx) { LocalDate rentStart = ctx.getRentStartDate(); LocalDate rentEnd = ctx.getRentEndDate(); if (rentStart == null || rentEnd == null) { throw new IllegalArgumentException("租用车位必须填写租赁起止日期"); } // 取租期与计费周期的交集 LocalDate effectiveStart = rentStart.isAfter(ctx.getBillingPeriodStart()) ? rentStart : ctx.getBillingPeriodStart(); LocalDate effectiveEnd = rentEnd.isBefore(ctx.getBillingPeriodEnd()) ? rentEnd : ctx.getBillingPeriodEnd(); // 逐月生成账单 List<Bill> bills = new ArrayList<>(); YearMonth sm = YearMonth.from(effectiveStart); YearMonth em = YearMonth.from(effectiveEnd); for (YearMonth ym = sm; !ym.isAfter(em); ym = ym.plusMonths(1)) { // 整月 → 单价；不足月 → 单价/当月天数×实际天数 boolean isFullMonth = billStart.equals(ym.atDay(1)) && billEnd.equals(ym.atEndOfMonth()); BigDecimal amount = isFullMonth ? ctx.getUnitPrice() : ctx.getUnitPrice().multiply(BigDecimal.valueOf(actualDays)) .divide(BigDecimal.valueOf(daysInMonth), 2, RoundingMode.HALF_UP); // 组装 Bill 对象... bills.add(bill); } return bills; } } 3.3.3 关键业务约束售出车位不可直接转为租用状态，须校验所有权状态及未清账单费率配置基于 effective_date 版本化查询，不使用 is_current 标志 - 账单状态：0=待缴、1=已缴、2=部分缴；逾期为业务逻辑判断（当前日期 > 截止日期且状态≠已缴）枚举字段（fee_type、parking_spot.type、resident.type）均为 tinyint 整数3.4. 数据库设计请结合总体设计文档.md 和 /database-design、/property-business-rules 技能，为‘居民小区物业管理系统’生成完整的 MySQL 初始化 DDL 建表脚本。 要求包含：房屋表（含面积）、业主/租户表、车位表（区分售出与租用）、物业费账单表、车位费账单表。每张表必须包含主键、索引、字段注释以及审计字段（created_at, updated_at, deleted_at）。3.4.1 设计规范符合第三范式（3NF）所有表包含审计字段：created_at、updated_at、deleted_at（软删除）关联表外键添加 ON DELETE CASCADE字符集：utf8mb4 + utf8mb4_unicode_ci主键：BIGINT AUTO_INCREMENT3.4.2 数据表清单序号表名说明1t_community小区表2t_fee_config费率配置表（版本化）3t_building楼栋表4t_unit单元表5t_room房间表（冗余community_id反范式）6t_resident人员表（业主/租户）7t_user系统用户表8t_room_resident_binding房间-人员绑定表9t_parking_spot车位表10t_parking_assignment车位分配表11t_bill账单表（多态引用 source_type+source_id）12t_payment缴费记录表13t_fee_type费用类型字典表14t_pay_method缴费方式字典表15t_bill_status账单状态字典表16t_bind_type绑定类型字典表3.4.3 关键设计决策决策方案原因账单关联source_type + source_id 多态引用避免可空外键，支持物业费/车位费统一账单表费率查询纯基于 effective_date 查询避免布尔标志的并发更新风险房间冗余t_room 冗余 community_id减少账单生成时的多表 JOIN，提升查询性能软删除deleted_at 字段保留数据审计追溯能力3.5 API 接口设计请结合项目背景与需求.md和刚才的数据库结构，加载 api-spec-designer 和 /property-business-rules 技能，帮我设计 RESTful API 接口规范。 需包含以下核心模块的接口： 房屋与业主模块：房屋 CRUD、业主绑定与解绑接口。 停车位模块：车位状态变更、售出/租用信息登记接口。 费用与账单模块：生成房屋物业费账单、生成车位费账单（区分售出按年/租用按月）、账单支付与催缴查询接口。 请输出 Swagger/OpenAPI YAML 格式或清晰的 Markdown 接口规范文档，明确每个接口的请求路径、HTTP 方法、请求参数（Header/Query/Body）及响应示例。3.5.1 接口规范遵循 RESTful 规范，OpenAPI 3.0 YAML 文档（v2.2.0）统一 /v1 前缀 - 统一响应格式：{ code, message, data }JWT Bearer Token 认证@RestController @RequestMapping("/v1") @RequiredArgsConstructor public class BillingController { // 分页查询账单 @GetMapping("/bills") public ApiResponse<Page<BillDTO>> listBills( @RequestParam int page, @RequestParam int size, @RequestParam(required = false) Long communityId, @RequestParam(required = false) Integer status) { return ApiResponse.ok(billingService.listBills(page, size, communityId, status)); } // 生成物业费账单 @PostMapping("/bills/generate-property-fee") public ApiResponse<List<BillDTO>> generatePropertyFee( @Valid @RequestBody GeneratePropertyFeeRequest request) { return ApiResponse.ok(billingService.generatePropertyFee(request)); } // 删除账单 @DeleteMapping("/bills/{id}") public ApiResponse<Void> deleteBill(@PathVariable Long id) { billMapper.deleteById(id); return ApiResponse.ok(); } } 3.5.2 接口清单模块接口数主要操作认证 (auth)4登录、登出、用户 CRUD小区 (community)12小区/楼栋/单元/房间/费率 CRUD人员 (resident)5人员 CRUD、房间绑定车位 (parking)5车位 CRUD、分配/释放、到期预警账单 (billing)6生成物业费/车位费、账单查询缴费 (payment)5缴费录入、按账单查询、逾期查询看板 (dashboard)3费用汇总、收缴率、逾期统计3.5.3 删除接口接口方法路径删除小区DELETE/v1/communities/{id}删除楼栋DELETE/v1/buildings/{id}删除单元DELETE/v1/units/{id}删除房间DELETE/v1/rooms/{id}删除人员DELETE/v1/residents/{id}删除车位DELETE/v1/parking-spots/{id}删除账单DELETE/v1/bills/{id}删除缴费DELETE/v1/payments/{id}3.6 前端页面3.6.1 页面清单页面路径功能登录/loginJWT 认证登录仪表盘/dashboard费用汇总、收缴率、ECharts 图表小区管理/communities小区列表、新增、删除楼栋管理/buildings楼栋列表、新增、删除房间管理/rooms房间列表、新增、编辑、删除人员管理/residents人员列表、新增、编辑、删除车位管理/parking车位列表、新增、删除、分配/释放、到期预警费率配置/fee-configs费率列表、新增费用账单/bills账单列表、生成物业费/车位费、删除缴费管理/payments缴费列表、录入缴费、逾期查询、删除用户管理/users系统用户列表、新增、删除3.6.2 交互特性Element Plus 组件库统一 UI 风格el-popconfirm 二次确认删除操作el-pagination 分页查询el-tag 状态标签（已缴/待缴/逾期等）ECharts 数据可视化看板Axios 请求拦截器自动注入 JWT Token<el-popconfirm title="确定删除该楼栋？" @confirm="handleDelete(row.id)"> <template #reference> <el-button link type="danger">删除</el-button> </template> </el-popconfirm> <script setup> async function handleDelete(id) { await deleteBuilding(id); ElMessage.success('删除成功'); loadData(); } </script> 删除操作使用Element Plus的el-popconfirm组件包裹，用户点击删除按钮后弹出确认气泡，防止误操作。确认后调用后端删除接口，成功刷新列表并给出反馈，保证交互一致性与数据安全。// 请求拦截：自动注入 JWT Token request.interceptors.request.use(config => { const auth = useAuthStore(); if (auth.token) config.headers.Authorization = `Bearer ${auth.token}`; return config; }); // 响应拦截：统一错误处理，401 自动登出 request.interceptors.response.use( response => { const res = response.data; if (res.code !== 200 && res.code !== 0) { ElMessage.error(res.message || '请求失败'); if (res.code === 401) { auth.logout(); router.push('/login'); } return Promise.reject(new Error(res.message)); } return res; }, error => { if (error.response?.status === 401) { auth.logout(); router.push('/login'); } ElMessage.error(error.message || '网络错误'); return Promise.reject(error); } ); 请求拦截器从Pinia状态中取出JWT Token，自动注入Authorization头，实现无感认证。响应拦截器统一处理业务错误与HTTP异常，401时自动清除登录态并跳转登录页，避免用户停留在无权限页面。四、总结与反思4.1 遇到的问题及解决方法JDK 版本降级。 项目初始选型Spring Boot 3.3 + Java 21，开发环境实际仅有 JDK 8，降级至Spring Boot 2.7.18 + Java 8，所有jakarta.* 包需全量替换为 javax.*，耗费无效Tokens。技术选型前必须先确认目标环境的软件版本。DELETE 请求跨域被拒。前后端分离架构下，浏览器发起DELETE请求时因后端未配置CORS，接口返回405错误。排查后发现Spring Boot脚手架中遗漏了 CorsFilter 配置。解决方案：将CORS配置纳入项目初始化模板，与JWT、统一响应等组件同步搭建。Windows下文件编码损坏。使用PowerShell的Set-Content命令生成SQL文件时，中文注释变为乱码，影响DDL脚本可读性。原因是Set-Content默认编码为ASCII。解决方案：Windows环境下统一使用文本编辑器或专用工具保存UTF-8文件，避免依赖shell重定向。前后端枚举值不一致。前端传递费用类型时使用字符串（如"PROPERTY"、“SOLD”），后端接口期望tinyint整数（1、2、3），导致JSON反序列化失败，接口联调频繁报错。解决：在OpenAPI 3.0规范文档中显式约定所有枚举字段的整数值映射，前端据此同步定义常量，彻底消除类型歧义。4.2 总结与收获架构设计方面：策略模式在车位计费场景的成功落地，验证了开闭原则在物业系统中的适用性，新增车位类型只需扩展策略类，现有逻辑零修改。账单表采用source_type + source_id多态引用，降低了关联查询复杂度，为多源数据统一管理提供了可复用的设计模式。开发流程方面：“环境先行”与“契约驱动”是最深刻的教训。JDK版本降级的返工成本表明，技术选型须以生产环境约束为前提。OpenAPI规范先行、枚举值显式约定等措施，显著降低了前后端联调摩擦。初始数据脚本化、CORS 等横切关注点的模板化，指明了项目脚手架标准化的改进方向。质量保障方面：核心计费策略已通过单元测试覆盖整月、不足月、租期交集及异常防御等全部分支，未来需补充 Controller 层集成测试与前端E2E测试，形成更完整的验证闭环。仓库地址：居民小区物业管理系统

书循 BookCycle应用构建2352724朱睿涵

基于 CodeArts 与 Docker 的全栈论坛应用构建与云上部署实践在线体验地址：http://113.47.15.34项目源码仓库：https://gitcode.com/gca_u2402_85029424/forum/一、概述1.1 案例介绍在兴趣社群运营中，论坛是最经典的互动载体，但从零搭建一个具备用户管理、内容审核、版主体系和一键部署的全栈论坛并非易事。码趣社区将 Vue3 前端、Node.js 后端和 MySQL 数据库通过 Docker Compose 编排，实现发帖回复、点赞收藏、敏感词过滤（DFA 算法）、版主管理、黑名单、每日签到、勋章成就等完整功能，并一键部署到华为云弹性云服务器 ECS。本案例将使用华为云码道（CodeArts）代码智能体以 Spec-Driven 模式完成从需求到代码的全流程开发，最终通过 Docker Compose 将三个容器（MySQL、Node.js、Nginx）部署到 ECS。完成案例后，我掌握了：使用华为云码道的 Spec-Driven 模式，将论坛需求依次转化为规格、设计、任务和代码；使用 Vue3 + Element Plus 构建响应式前端，集成 Pinia 状态管理和路由守卫；使用 Node.js + Express + Sequelize 构建 RESTful API，实现 JWT 鉴权、DFA 敏感词过滤和版主权限体系；使用 Docker Compose 编排多容器应用，配置 Nginx 反向代理和 MySQL 字符集；在 Ubuntu ECS 上完成本地构建、SFTP 上传、容器启动和数据初始化的全流程部署。1.2 适用对象希望学习全栈开发与 Docker 部署的个人开发者；需要快速搭建社区论坛的企业开发者；具备 JavaScript/Vue 基础和 Linux 命令行基础的高校学生。1.3 案例时间直接使用仓库源码完成资源准备、部署和功能验证，预计需要 30～45 分钟。如通过码道分阶段搭建码趣社区，建议预留 1.5～2 小时，具体时间取决于代码生成、人工评审和依赖下载速度。1.4 案例流程图 1-1 码趣社区案例流程说明：购买弹性云服务器 ECS，配置安全组开放 80 和 22 端口；本地使用 CodeArts IDE 以 Spec-Driven 模式开发前端（Vue3 + Element Plus）和后端（Node.js + Express + MySQL）代码；本地构建前端 dist 产物，编写 Docker Compose 编排文件和 Dockerfile；通过 SFTP 将项目代码和前端产物上传至 ECS 服务器；在服务器上执行 Docker Compose 一键启动 MySQL、Node.js、Nginx 三个容器；执行数据初始化脚本，访问公网 IP 验证论坛功能。1.5 方案架构图 1-2 码趣社区系统运行架构核心调用链如下：浏览器发起请求，Nginx 监听 80 端口，静态资源直接返回，/api/ 路径反向代理到 Node.js 容器 3000 端口；Node.js 通过 Sequelize ORM 连接 MySQL 容器，执行数据读写；JWT 鉴权中间件校验用户身份，敏感词中间件在发帖和回复前执行 DFA 过滤；黑名单中间件在发帖和回复前检查用户是否被当前版块拉黑；前端通过 axios 统一封装 API 请求，自动携带 Bearer Token，401 时跳转登录页。1.6 资源总览本案例使用按需资源。以 1 小时体验估算，费用通常由 ECS 实例费用和 EIP 流量费用组成。资源名称推荐规格用途华为开发者空间已完成实名认证的账号进入开发平台和实战案例弹性云服务器 ECS2 vCPU、4 GiB、Ubuntu 24.04、40 GiB 系统盘运行 Docker 容器弹性公网 IP EIP按流量计费、5 Mbit/sSSH 登录和浏览器访问华为云码道（CodeArts）代码智能体购买使用专业版Spec-Driven 全流程开发费用提示：体验完成后请及时释放 ECS 和 EIP。仅关闭操作系统不会停止 ECS 计费。二、环境和资源准备2.1 前置条件开始前请确认：已注册华为云账号并完成实名认证；账号余额或代金券足以支付本案例资源；本地已安装 Node.js >= 18.x、npm >= 9.x，可使用 SSH 和 SFTP；Windows 10/11 可在 PowerShell 中执行 ssh -V 和 node -v 检查。2.2 创建 ECS登录华为云控制台，进入 服务列表 > 计算 > 弹性云服务器 ECS，单击购买弹性云服务器。图 2-1 选择 ECS 规格、镜像、磁盘和公网访问配置推荐配置如下：配置项推荐值说明计费模式按需计费便于体验结束后及时释放CPU 架构x86与常用 Node.js 依赖兼容规格2 vCPU、4 GiB低于 4 GiB 可能无法稳定运行三个 Docker 容器镜像Ubuntu 24.04 Server 64bit部署脚本使用 apt-get系统盘40 GiB用于系统、Docker 镜像和数据库数据EIP现在购买用于 SSH 和 Web 访问带宽计费按流量计费，5 Mbit/s适合短时体验登录方式密钥对或强密码密钥对安全性更高购买完成后，在 ECS 详情页记录：ECS 公网 IP：后文以 <ECS_IP> 表示；登录用户名和密码：本案例使用 root 用户。图 2-2 ECS 创建完成并处于运行中2.3 配置安全组进入 ECS 详情 > 安全组 > 配置规则 > 入方向规则，添加以下规则：协议端口来源用途TCP22本机公网 IP/32SSH 和 SFTPTCP800.0.0.0/0浏览器访问论坛2.4 安装 Docker 和 Docker Compose使用 SSH 工具连接到 ECS 服务器，执行以下命令：# 更新系统 apt update && apt upgrade -y # 安装 Docker 和 Docker Compose apt install -y docker.io docker-compose # 配置 Docker 镜像加速（国内环境必须，否则无法拉取镜像） mkdir -p /etc/docker cat > /etc/docker/daemon.json << 'EOF' { "registry-mirrors": ["https://docker.1ms.run"] } EOF # 启动 Docker 并设置开机自启 systemctl daemon-reload systemctl enable docker systemctl start docker # 创建 2G Swap（防止内存不足导致容器被 OOM Kill） fallocate -l 2G /swapfile chmod 600 /swapfile mkswap /swapfile swapon /swapfile echo '/swapfile none swap sw 0 0' >> /etc/fstab验证安装：docker --version docker-compose --version free -h 预期结果：Docker 和 Docker Compose 版本正常输出，Swap 行显示约 2G 可用空间。2.5 本地开发环境确保本地已安装：Node.js >= 18.x（执行 node -v 检查）npm >= 9.x（执行 npm -v 检查）Git（执行 git --version 检查）三、通过码道分阶段搭建码趣社区本模块演示如何使用华为云码道（CodeArts）代码智能体，以 Spec-Driven 模式将论坛需求依次转化为需求规格、技术设计、任务清单和可运行代码。说明：码道界面、模型列表和按钮位置可能随版本更新而变化，请以实际产品页面为准。生成代码必须经过人工审查、构建测试和安全检查。3.1 开通并进入码道登录华为开发者官网，进入华为云码道（CodeArts）代码智能体体验页面；按页面提示完成体验版开通；下载并安装支持码道的开发工具，登录同一华为云账号；打开码道 Agent Space 或 IDE 右侧智能体面板，确认可以选择规范开发（Spec-Driven）。图 3-1 开通华为云码道代码智能体体验版图 3-2 进入码道 Agent Space3.2 创建项目并选择 Spec-Driven 模式新建空工作区，在智能体面板选择规范开发（Spec-Driven）。首次输入应描述业务目标、技术栈、核心功能和交付要求：请使用 Vue3 + Element Plus（前端）、Node.js + Express + Sequelize + MySQL（后端） 构建一个兴趣社群论坛"码趣社区"。功能包括：用户注册登录、版块管理、 发帖回复、点赞收藏、敏感词过滤（DFA算法）、版主管理、黑名单、 每日签到（含连续签到奖励）、勋章成就系统。部署方式为 Docker Compose 一键部署（MySQL + Node.js + Nginx）。请采用 Spec-Driven 流程， 先生成需求规格，再生成技术设计和任务清单，经确认后分阶段实现。图 3-3 选择 Spec-Driven 模式并提交项目目标Spec-Driven 流程包含四个阶段：需求规格设计：明确目标、边界、用户故事和验收标准；实现方案创建：确定架构、数据模型、接口和部署方案；编码任务规划：将设计拆分为可追踪、可验证的任务；任务执行：按依赖顺序生成代码，并持续构建验证。3.3 第一阶段：生成并评审 spec.md码道首先将自然语言需求整理为 spec.md。评审时重点检查：是否覆盖用户管理、版块管理、发帖回复、敏感词过滤、版主体系和部署方式；是否明确"管理员不能被拉黑""敏感词过滤不修改原文只标记命中"等业务边界；每个核心能力是否具有可验证的验收标准；技术栈和部署目标是否与项目实际一致。图 3-4 第一阶段完成需求规格设计若规格有遗漏，先在对话中提出修改要求，确认 spec.md 后再进入设计阶段。3.4 第二阶段：生成并评审 design.mddesign.md 应把需求落实为可实现的技术方案。本项目重点确认：Vue3 + Element Plus 前端架构，Pinia 状态管理，vue-router 路由守卫；Express + Sequelize 后端架构，JWT 鉴权中间件，DFA 敏感词过滤中间件；MySQL 数据模型覆盖用户、版块、帖子、回复、版主、敏感词、黑名单、签到、点赞、收藏、勋章等 13 个表；Docker Compose 编排 MySQL、Node.js、Nginx 三个容器，Nginx 反向代理 /api/ 到后端；环境变量注入数据库密码和 JWT 密钥，不进入源码和镜像。图 3-5 第二阶段完成实现方案设计3.5 第三阶段：生成并评审 tasks.md码道根据规格和设计生成 tasks.md，把工作拆分为项目初始化、数据模型、中间件、核心 API、前端页面、Docker 部署等任务。评审任务清单时应确保：每项任务都能回溯到 spec.md 和 design.md；任务依赖顺序正确，可并行项和串行项明确；每项任务包含完成条件，而不只是文件名；构建、数据库初始化、接口验证被列入任务。图 3-6 第三阶段完成编码任务规划3.6 第四阶段：按任务清单执行确认任务清单后进入执行阶段。建议采用"小批次执行—查看变更—运行验证—继续下一批"的节奏：先完成项目初始化、环境变量声明和 Sequelize 模型定义；再实现 JWT 鉴权、DFA 敏感词过滤和黑名单中间件；然后实现用户、版块、帖子、回复等核心 API 路由；接着实现前端页面和 Element Plus 组件；最后补充 Dockerfile、docker-compose.yml 和 Nginx 配置；每批变更后查看差异，拒绝与规格无关的修改。图 3-7 码道开始执行初始化与配置任务图 3-8 码道继续实现后端接口和前端页面图 3-9 任务执行阶段完成3.7 本地运行与阶段验收智能体完成首轮实现后，在项目目录执行：# 后端 cd server npm install node src/seed.js # 前端 cd ../client npm install npm run dev图 3-10 首个本地可运行版本的首页3.8 编码问题与修复Windows 环境下，码道生成的含中文 Vue/JS 文件可能被保存为 GBK 编码而非 UTF-8，导致 Vite 构建后中文乱码。解决方案：后端 JS 文件中的中文使用 \uXXXX Unicode 转义；前端 Vue 文件使用 Node.js fs.writeFileSync(path, content, 'utf8') 写入；ElementF12 打开浏览器控制台，检查 Network 面板中 API 返回的中文是否正常。完成本模块后，项目应通过 npm run build，核心页面可访问，且所有环境变量和部署步骤与后续章节一致。四、构建并部署码趣社区应用4.1 技术栈与项目结构主要技术栈如下：层次技术版本/作用前端框架Vue33.5，Composition APIUI 组件库Element Plus表单、表格、对话框、分页等状态管理Pinia用户登录态、角色判断路由Vue Router 4路由守卫、动态路由HTTP 客户端;axiosAPI 封装、Token 注入、401 拦截后端框架ExpressRESTful APIORMSequelize模型定义、迁移和查询数据库MySQL 8.0持久化所有业务数据鉴权JWTBearer Token 认证敏感词DFA 算法确定有限状态自动机，高性能匹配容器编排Docker ComposeMySQL + Node.js + Nginx 三容器反向代理Nginx静态资源、/api/ 反向代理、SPA 路由项目关键结构：forum/ ├── docker-compose.yml ├── client/ │ ├── Dockerfile │ ├── nginx.conf │ ├── package.json │ ├── vite.config.js │ ├── index.html │ └── src/ │ ├── main.js │ ├── App.vue │ ├── router/index.js │ ├── stores/user.js │ ├── api/ # auth, posts, sections, admin, likes, favorites, badges, checkin │ ├── components/ # Navbar, PostCard, ThumbUp, ThumbUpFilled │ └── views/ # Home, Login, Register, PostDetail, Profile, Checkin, Search │ └── admin/ # Dashboard, Sections, Moderators, SensitiveWords, Blacklist ├── server/ │ ├── Dockerfile │ ├── package.json │ ├── .env │ └── src/ │ ├── app.js │ ├── config/ │ ├── models/ # User, Section, Post, Reply, Moderator, SensitiveWord, │ │ # Blacklist, Checkin, Like, Favorite, Badge, UserBadge │ ├── routes/ # auth, posts, sections, moderators, blacklist, sensitiveWords, │ │ # checkin, likes, favorites, badges │ ├── middleware/ # auth, checkBlacklist, sensitiveWordFilter │ ├── utils/ # dfa, response, badges │ ├── seed.js # 管理员、版块、敏感词、勋章种子数据 │ └── populate.js # 测试用户、帖子、回复批量填充4.2 关键实现解析, checkBlacklist, sensitiveWordFilter4.2.1 DFA 敏感词过滤后端使用 DFA（确定有限状态自动机）算法实现高性能敏感词过滤，支持精确匹配和模糊匹配两种模式：class SensitiveWordFilter { constructor() { this.wordTree = {}; } addWord(word, matchType = 'exact') { let node = this.wordTree; for (const char of word) { if (!node[char]) node[char] = {}; node = node[char]; } node.isEnd = true; node.matchType = matchType; } filter(text) { const matched = []; for (let i = 0; i < text.length; i++) { let node = this.wordTree; let j = i; while (j < text.length && node[text[j]]) { node = node[text[j]]; if (node.isEnd) matched.push({ start: i, end: j, word: text.substring(i, j + 1) }); j++; } } return matched; } } 4.2.2 JWT 鉴权与权限分级鉴权中间件支持三级权限控制：function authMiddleware(requiredRole = null) { return async (req, res, next) => { const token = req.headers.authorization?.split(' ')[1]; const decoded = jwt.verify(token, config.jwt.secret); const user = await User.findByPk(decoded.id); // admin: 仅管理员 if (requiredRole === 'admin' && user.role !== 'admin') return 403; // moderator: 管理员或版主 7 if (requiredRole === 'moderator' && user.role !== 'admin' && user.role !== 'moderator') return 403; req.user = user; next(); }; } 4.2.3 Docker Compose 编排services: mysql: image: mysql:8.0 restart: always environment: MYSQL_ROOT_PASSWORD: ${DB_PASS:-Forum2026!Prod} MYSQL_DATABASE: forum MYSQL_CHARSET: utf8mb4 command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci volumes: - mysql_data:/var/lib/mysql healthcheck: test: ["CMD", "mysqladmin", "ping", "-h", "localhost"] server: build: ./server restart: always environment: DB_HOST: mysql DB_PASS: ${DB_PASS:-Forum2026!Prod} JWT_SECRET: ${JWT_SECRET:-change_this_in_production} depends_on: mysql: condition: service_healthy client: build: ./client restart: always ports: - "80:80" volumes: 5 - ./client/dist:/usr/share/nginx/html depends_on: - server volumes: mysql_data: 4.2.4 Nginx 反向代理配置server { listen 80; charset utf-8; root /usr/share/nginx/html; index index.html; location /api/ { proxy_pass http://server:3000/api/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } location / { try_files $uri $uri/ /index.html; } } 4.3 本地构建前端1核1G 服务器无法在 Docker 内构建 Vite 前端（会 OOM Kill），需在本地构建后上传：cd forum/client npm run build构建完成后 dist/ 目录包含所有静态资源。注意：Windows 环境下 Vite 构建可能因内存不足卡住，可使用 node --max-old-space-size=4096 node_modules/vite/bin/vite.js build 增加内存限制。4.4 上传项目到服务器使用 SFTP 工具将整个 forum/ 目录上传至 ECS 服务器的 /root/forum/。也可使用 Node.js ssh2 库编写 SFTP 上传脚本，将 client/dist/ 和 server/ 同步到服务器。4.5 启动服务SSH 登录服务器后执行：cd /root/forum # 启动所有容器 docker-compose up -d --build # 等待 MySQL 就绪后初始化数据 sleep 15 docker-compose exec -T server node src/seed.js docker-compose exec -T server node src/populate.jsseed.js：创建管理员账号、5 个版块、7 个敏感词和 6 个勋章定义；populate.js：填充 10 个测试用户、17 篇帖子、59 条回复、5 个版主、2 个黑名单和 5 个置顶帖。图 4-1 三个容器启动成功4.6 部署结果验证依次执行：docker-compose ps curl -I http://127.0.0.1 curl http://127.0.0.1/api/sections预期结果：三个容器状态均为 Up；curl 返回 HTTP 200；/api/sections 返回 JSON 格式的版块列表。首页应显示"码趣社区——计算机人的论坛"导航栏和帖子列表。图 4-2 通过 ECS 公网地址访问码趣社区默认账号：角色用户名密码管理员adminadmin123普通用户zhangsan123456五、功能体验5.1 用户注册与登录点击导航栏注册，填写用户名、邮箱和密码；注册成功后自动登录，导航栏显示用户昵称和下拉菜单；退出登录后自动跳转到登录页。图 5-1 用户注册页面5.2 发帖与回复点击导航栏发帖，选择版块、填写标题和内容，点击提交；在帖子详情页，点赞（?）和收藏（?）按钮可正常切换；在回复框输入内容，点击回复；版主或管理员可置顶和删除帖子。图 5-2 帖子详情页的点赞与收藏功能5.3 敏感词过滤管理员进入管理后台 > 敏感词管理，添加敏感词（支持精确匹配和模糊匹配）；用户发帖或回复时，若内容命中敏感词，系统返回提示并阻止发布；DFA 算法基于预构建的字典树实现，匹配效率为 O(n)，n 为文本长度。5.4 版主管理与黑名单管理员进入管理后台 > 版主管理，为版块任命版主；版主可在自己管理的版块中置顶和删除帖子；进入黑名单管理，点击添加拉黑，搜索用户名并选择版块，填写原因后确认；被拉黑用户在该版块发帖或回复时被拒绝。图 5-3 黑名单管理页面的用户搜索功能5.5 每日签到与连续奖励点击导航栏签到，进入签到页面；点击签到按钮，显示连续签到天数和获得的声望奖励；日历视图标记已签到日期，连续签到天数越多奖励越高。图 5-4 每日签到与连续签到奖励5.6 勋章与成就系统用户在发帖、回复、签到等行为中自动触发勋章检查；获得的勋章在个人中心的"我的勋章"区域展示；内置勋章包括：初来乍到（首次发帖）、热心回复（首次回复）、持之以恒（连续3天签到）、声望新星（声望达到10）等。5.7 个人中心点击导航栏用户下拉菜单中的个人中心；查看声望等级（Lv.1 起，随声望增长升级）、我的帖子、我的收藏和我的勋章；编辑昵称和个人简介。图 5-5 个人中心页面5.8 管理后台管理员登录后，导航栏显示管理后台入口：页面功能仪表盘统计用户数、版块数、帖子数、回复数版块管理创建、编辑、排序版块版主管理任命和移除版主敏感词管理添加、编辑、删除敏感词，支持批量导入导出黑名单管理拉黑和解除拉黑用户图 5-6 管理后台仪表盘六、运行维护与故障排查6.1 常用运维命令# 查看容器状态 cd /root/forum && docker-compose ps # 查看容器日志 docker-compose logs server --tail 100 docker-compose logs mysql --tail 50 # 重启单个容器 docker-compose restart server # 查看 Nginx 状态 docker exec forum_client_1 nginx -t # 查看磁盘和内存 df -h free -h # 查看数据库表 docker exec forum_mysql_1 mysql -uroot -p'Forum2026!Prod' forum -e "SHOW TABLES;" 6.2 常见问题现象可能原因处理方法浏览器无法访问安全组未开放 80、Nginx 未启动、EIP 错误检查安全组、docker-compose ps 和 ECS 公网 IP502 Bad GatewayNode.js 容器未启动或 3000 端口未监听执行 docker-compose logs server，重启容器API 返回中文乱码前端 dist 文件编码问题本地重新 npm run build 后上传 distMySQL 容器频繁重启内存不足导致 OOM Kill确认 Swap 已启用，考虑升级 ECS 规格SSH 无法连接SSH 进程被 OOM Kill通过华为云控制台 VNC 登录，检查 free -h发帖被拒绝命中敏感词或被黑名单拉黑检查敏感词列表和黑名单记录点赞/收藏图标不显示图标组件渲染方式错误确认使用 v-if/v-else 而非 component:is6.3 更新部署修改代码后，在本地重新构建前端并上传：# 本地构建 cd forum/client npm run build # 上传 dist 到服务器（通过 SFTP） # 服务器上复制到容器 docker cp /root/forum/client/dist/. forum_client_1:/usr/share/nginx/html/ # 后端代码更新 docker cp /root/forum/server/src/routes/xxx.js forum_server_1:/app/src/routes/xxx.js docker-compose restart server6.4 生产化建议本案例以快速体验为目标。用于生产环境前，至少应补充：使用 IAM 和 HTTPS 证书保护所有页面和 API；将数据库密码和 JWT 密钥存储到云凭据管理服务；使用云数据库 RDS 替代容器内 MySQL，并建立自动备份；增加请求限流、输入大小限制和审计日志；配置 AOM 或 LTS 监控 CPU、内存和错误率。七、释放资源7.1 停止并删除 Docker 容器cd /root/forum docker-compose down -v 7.2 删除 ECS登录华为云控制台，进入弹性云服务器 ECS > 实例；选择本案例创建的 ECS；单击更多 > 删除；根据页面提示勾选释放绑定的 EIP、删除系统盘和数据盘；确认资源名称和影响范围后完成删除。删除后再次检查 ECS、云硬盘和 EIP 列表，确认没有遗留按需资源。八、扩展资料Vue3 官方文档Element Plus 组件库Express 框架Sequelize ORMDocker Compose 文档弹性云服务器 ECS 文档弹性公网 IP 文档九、案例验收清单完成以下检查即表示案例体验成功：[ ] ECS、EIP 和安全组配置完成；[ ] Docker 和 Docker Compose 已安装，镜像加速已配置；[ ] 三个容器（MySQL、Node.js、Nginx）均为 Up 状态；[ ] seed.js 和 populate.js 执行成功，数据库有初始数据；[ ] 浏览器可通过 ECS 公网 IP 打开码趣社区首页；[ ] 用户注册、登录、发帖、回复功能正常；[ ] 点赞和收藏图标正常显示并可切换；[ ] 敏感词过滤能阻止命中词的发布；[ ] 管理员可拉黑用户，被拉黑用户无法在对应版块发帖；[ ] 每日签到和勋章系统正常工作；[ ] 个人中心可查看我的帖子、我的收藏和我的勋章；[ ] 体验结束后已释放不再使用的计费资源。

零、前置说明源代码链接（本人基于码道智能体原创）：https://github.com/Jiachen1029/QuakeVision-using-CodeArts视频展示：https://pan.baidu.com/s/1FAvA-cN6nJ0o2-LkYpprjw 提取码: tjcs一、概述1.1 案例背景地震灾害具有突发性强、影响范围广、次生灾害链条长等特点。一次显著地震往往不仅造成建筑物倒塌与人员伤亡，还可能诱发山体滑坡、地面破坏、火灾以及海啸等连锁效应。从公共卫生与社会影响角度看，世界卫生组织统计显示，在 1998—2017 年间，地震导致近 75 万人死亡，并造成大规模受灾与流离失所。从经济损失角度看，联合国减灾署在其全球评估报告相关内容中指出，地震造成的经济损失占全球灾害直接经济损失的显著比例超过1/4。地震信息的快速获取、可靠存档与可分析呈现，对科研分析、教学训练以及应急信息支撑都具有现实价值。因此，各类机构都会发布地震速报信息，但这些数据往往以列表、通报、表格文件等形式分散存在，存在以下常见问题：其一，数据呈现方式偏静态文本。用户难以进行复杂检索与对比分析，如跨时间段震级分布、某地区地震活动趋势等；其二，缺少空间化表达。纯表格信息难以直观反映地震的地理分布特征与空间聚集现象；其三，数据更新与维护流程不统一。导入数据容易出现重复、缺失、格式不一致等质量问题，影响后续分析准确性；因此，构建具备数据可管理、查询可扩展、统计可分析、结果可视化、权限可控制的地震信息查询可视化平台，不仅符合课程设计中数据库应用系统开发的训练目标，也贴近真实应用场景。1.2 案例介绍QuakeVision·地震信息查询可视化平台以地震事件数据为核心对象，支持从外部数据源导入，并在数据库中进行结构化存储与索引优化；支持面向不同使用角色（未登录用户、普通用户、数据维护人员、管理员）提供分层功能，包括地震事件的多条件检索、数据详情查看、收藏管理、统计报表生成以及基于地图的空间展示与城市地震风险评估查询。本案例演示了如何利用 Python Flask + SQLAlchemy + Leaflet.js + Chart.js 技术栈，快速搭建一个面向公共安全领域的地震数据查询与可视化分析平台，完整经历需求分析、数据库设计、编码实现、测试验证的软件工程全流程，开发周期共3天。1.3 适用对象高校学生个人开发者企业开发者1.4 案例时间与流程本案例实际开发周期为3天。第1天：需求分析与数据库设计——分析四类用户需求，完成概念设计（E-R图）、逻辑结构设计（关系模式转换与范式分析）、完整性约束与索引设计；第2天：后端开发与核心业务实现——搭建 Flask 应用框架，实现数据模型、多维查询、城市风险评估算法、统计分析、权限控制、数据导入导出等核心路由；第3天：前端可视化与集成测试——实现地图可视化（Leaflet）、统计图表（Chart.js）、Glassmorphism UI 主题，完成四类角色的功能验证与界面调试。1.5 资源总览本案例使用本地开发环境，所有资源均为免费开源软件。资源名称规格单价（元）Python3.11+免费Flask3.x Web 框架免费SQLite开发数据库免费Leaflet.js开源地图库免费Chart.js开源图表库免费OpenStreetMap Nominatim免费地理编码服务免费Pandas数据处理库免费Vue 3 + Vite前端扩展脚手架免费二、环境和资源准备2.1 安装 Python 与虚拟环境1）确保系统已安装 Python 3.11 或更高版本，可通过以下命令验证：python --version 2）在项目根目录下创建并激活 Python 虚拟环境：python -m venv .venv # Windows .venv\Scripts\activate # Linux/Mac source .venv/bin/activate2.2 安装项目依赖本项目依赖以下 Python 库，可通过 pip 一次性安装：pip install flask==3.1.0 pip install flask-sqlalchemy==3.1.1 pip install flask-login==0.6.3 pip install pandas==2.2.3 pip install openpyxl==3.1.5 pip install xlrd==2.0.1 pip install werkzeug==3.1.3注意：必须指定版本号安装，避免后期版本依赖冲突。2.3 准备地震数据文件项目根目录下已包含中国地震台网速报目录 Excel 文件：速报目录20090101-20251211.xls：2009年至2025年12月11日的历史地震数据速报目录20251211-20251223.xls：2025年12月11日至12月23日的近期数据速报目录20251224-20260726.xls：2025年12月24日至2026年7月26日的近期数据Excel 文件列格式为：序号、发震日期（北京时间）、经度(°)、纬度(°)、震源深度(Km)、震级(M)、震中位置、事件类型。三、构建地震信息查询可视化平台3.1 创建开发环境确认项目目录结构完整：EarthquakeDB/ ├── app/ # Flask 应用核心目录 │ ├── __init__.py # 应用工厂：初始化 Flask + SQLAlchemy + LoginManager │ ├── models.py # 数据模型：User, Earthquake, City, UploadLog, favorites │ ├── routes.py # 路由与业务逻辑（758行） │ ├── static/ │ │ └── css/ │ │ └── style.css # 全局样式（Glassmorphism 毛玻璃主题） │ └── templates/ # Jinja2 HTML 模板 │ ├── base.html # 基础布局模板（导航栏 + 公共资源） │ ├── index.html # 主页（地震列表 + 筛选） │ ├── login.html # 登录页 │ ├── register.html # 注册页 │ ├── profile.html # 个人中心 │ ├── admin.html # 管理员面板 │ ├── map.html # 地震分布地图可视化 │ ├── city_risk.html # 城市地震风险评估 │ ├── statistics.html # 数据统计分析 │ ├── edit.html # 编辑地震数据 │ ├── upload_manage.html # 上传数据与日志管理 │ └── my_favorites.html # 我的收藏 ├── frontend/ # Vue 3 前端项目（脚手架，扩展用） ├── config.py # Flask 配置（SECRET_KEY, 数据库URI） ├── run.py # 应用启动入口 ├── init_db.py # 数据库初始化脚本 ├── import_data.py # Excel 数据批量导入脚本 ├── inspect_excel.py # Excel 文件检查工具 ├── schema.sql # PostgreSQL 生产数据库 DDL ├── app.db # SQLite 开发数据库文件 ├── 速报目录*.xls # 地震速报数据文件 └── 开发者空间案例模板v2.0.md # 案例模板 3.2 部署项目代码3.2.1 初始化数据库执行数据库初始化脚本，创建所有数据表并生成默认用户账号：python init_db.py该脚本将：创建 users、earthquakes、cities、favorites、upload_logs 五张数据表创建三个默认用户：用户名密码角色User1111111ROLE_USER（普通用户）Staff1111111ROLE_STAFF（工作人员）Admin1111111ROLE_ADMIN（管理员）3.2.2 导入地震数据将 Excel 速报目录数据批量导入数据库：python import_data.py注意：import_data.py 默认读取 速报目录.xls，如需导入其他文件，请修改脚本末尾的文件路径参数。导入过程会自动跳过已存在的记录（基于 original_id 去重）。也可通过 Web 界面（管理员/工作人员登录后 → “上传数据与日志”）在线上传 Excel 文件，系统会自动解析并导入。3.3 关键代码讲解3.3.1 应用初始化（app/__init__.py）Flask 应用工厂模式，初始化核心扩展：from flask import Flask from config import Config from flask_sqlalchemy import SQLAlchemy from flask_login import LoginManager app = Flask(__name__) app.config.from_object(Config) db = SQLAlchemy(app) login = LoginManager(app) login.login_view = 'login' login.login_message = '请先登录以访问此页面。' from app import routes, modelsSQLAlchemy：ORM 数据库映射，支持 SQLite（开发）和 PostgreSQL（生产）无缝切换LoginManager：用户认证管理，未登录自动跳转至登录页3.3.2 数据模型（app/models.py）系统定义了 4 个核心数据模型和 1 个关联表，围绕"地震事件"的查询、可视化、导入维护与用户个性化操作展开。在概念层面，数据对象可抽象为五类核心实体：用户（User）、地震事件（Earthquake）、城市（City）、收藏关系（Favorites）、上传日志（UploadLog）。Earthquake 是业务主实体；User 负责身份与权限；Favorites 用于刻画用户对地震事件的多对多收藏关系；UploadLog 记录批量导入与审计信息；City 为城市检索/风险评估提供地理编码缓存与空间分析支撑。用户模型（User）：支持三种角色权限体系，密码仅以哈希形式保存class User(UserMixin, db.Model): __tablename__ = 'users' id = db.Column(db.Integer, primary_key=True) username = db.Column(db.String(50), unique=True, nullable=False) password_hash = db.Column(db.String(255), nullable=False) role = db.Column(db.String(20), default='ROLE_USER', nullable=False) # 角色取值：ROLE_USER / ROLE_STAFF / ROLE_ADMIN 属性名数据类型约束条件说明idIntegerPrimary Key，自增用户唯一标识usernameVARCHAR(50)UNIQUE，NOT NULL用户名唯一password_hashVARCHAR(255)NOT NULL密码哈希值不存明文roleVARCHAR(20)NOT NULL，DEFAULT=‘ROLE_USER’角色（ROLE_USER/ROLE_STAFF/ROLE_ADMIN）地震模型（Earthquake）：系统核心业务数据，存储每条地震记录的完整信息，对高频筛选字段设置索引以支撑上万条数据的分页响应与查询class Earthquake(db.Model): __tablename__ = 'earthquakes' id = db.Column(db.Integer, primary_key=True) original_id = db.Column(db.Integer) # 原始序号 time = db.Column(db.DateTime, nullable=False, index=True) # 发震时间 longitude = db.Column(db.Float, nullable=False, index=True) # 经度 latitude = db.Column(db.Float, nullable=False, index=True) # 纬度 depth = db.Column(db.Float, nullable=False) # 震源深度(km) magnitude = db.Column(db.Float, nullable=False, index=True) # 震级(M) location = db.Column(db.String(255)) # 震中位置 event_type = db.Column(db.String(50)) # 事件类型 属性名数据类型约束条件说明idIntegerPrimary Key地震记录唯一标识original_idInteger可为空来源数据原始序号（用于去重/对照）timeDateTimeNOT NULL，INDEX发震时间（范围查询高频）longitudeFloatNOT NULL，INDEX震中经度（空间范围查询）latitudeFloatNOT NULL，INDEX震中纬度（空间范围查询）depthFloatNOT NULL震源深度（km）magnitudeFloatNOT NULL，INDEX震级（区间筛选高频）locationVARCHAR(255)可为空参考位置文本（关键词检索）event_typeVARCHAR(50)可为空事件类型（如地震/余震等）收藏关联表（Favorites）：多对多关系，复合主键保证同一用户对同一事件最多收藏一次favorites = db.Table('favorites', db.Column('user_id', db.Integer, db.ForeignKey('users.id'), primary_key=True), db.Column('earthquake_id', db.Integer, db.ForeignKey('earthquakes.id'), primary_key=True) ) 属性名数据类型约束条件说明user_idIntegerPrimary Key，Foreign Key指向 users.idearthquake_idIntegerPrimary Key，Foreign Key指向 earthquakes.id城市缓存模型（City）：缓存 Nominatim 地理编码结果，name 字段设置唯一约束以避免重复缓存，提高命中率与一致性属性名数据类型约束条件说明idIntegerPrimary Key城市记录唯一标识nameVARCHAR(100)UNIQUE，NOT NULL，INDEX城市名/检索关键字（缓存键）display_nameVARCHAR(255)可为空城市显示名称（更完整的地名）latitudeFloatNOT NULL城市中心点纬度longitudeFloatNOT NULL城市中心点经度上传日志模型（UploadLog）：记录每次数据上传的操作者、文件名、导入条数和状态，满足"可追溯、可统计、可排错"的维护需求属性名数据类型约束条件说明idIntegerPrimary Key，自增日志记录唯一标识user_idIntegerNOT NULL，Foreign Key，INDEX导入操作发起用户（STAFF/ADMIN）filenameVARCHAR(255)NOT NULL上传文件名records_countInteger可为空导入记录数statusVARCHAR(50)NOT NULL，DEFAULT=‘success’状态：success/failedcreated_atDateTimeNOT NULL，INDEX，DEFAULT=now()导入时间戳3.3.3 数据库设计详解实体联系设计系统实体联系主要围绕"用户个性化行为"“数据维护审计”"时空分析支撑"三条主线展开：用户与地震事件——收藏关系（M:N）：一名用户可以收藏 0…N 条地震事件；一条地震事件可以被 0…N 名用户收藏。通过 favorites 关联表以 (user_id, earthquake_id) 复合主键实现。用户与上传日志——操作审计关系（1:N）：一名用户可以产生 0…N 条上传日志；每一条上传日志必须且仅能属于 1 名用户。通过 upload_logs.user_id 外键引用 users.id 实现。城市与地震事件——空间邻近/风险评估联系（派生 N:N）：城市与地震事件之间的联系不属于传统的静态业务外键关系，而是由系统在运行期基于空间计算动态构造的联系。城市风险评估以"城市中心点坐标"为锚点，在给定半径（150km）内检索地震事件集合，并计算事件数量、震级分布、最大震级等指标形成评估输出。该联系随参数变化而变化，不设置硬外键约束。关系模式综合实体与联系的转换，本系统最终关系模式为：User(id, username(UQ), password_hash, role)Earthquake(id, original_id, time, longitude, latitude, depth, magnitude, location, event_type)City(id, name(UQ), display_name, latitude, longitude)Favorites(user_id, earthquake_id)，其中 user_id → User.id，earthquake_id → Earthquake.idUploadLog(id, user_id → User.id, filename, records_count, status, created_at)范式分析系统关系表以"单一主键 + 多个描述字段"为主，业务写操作相对有限、读查询较多，适合采用满足第三范式的设计以降低冗余与维护成本：Users 表：候选键为 id 和 username，非主属性之间不存在传递依赖，满足 3NFEarthquakes 表：主键为 id，location 为目录给出的参考位置文本，不构成严格函数依赖，在当前业务假设下满足 3NFFavorites 表：复合主键 (user_id, earthquake_id)，不存在非主属性，自然满足 3NFCity 与 UploadLogs 表：结构与 Users 类似，满足 3NF完整性约束实体完整性：所有实体表均通过整数型主键保证实体完整性；favorites 以复合主键保证收藏关系唯一且非空。参照完整性：upload_logs.user_id 引用 users.id，每条上传日志必须对应一个已存在的操作者用户favorites.user_id 引用 users.id，favorites.earthquake_id 引用 earthquakes.id城市与地震事件的"风险评估/附近地震查询"属于运行期派生关系，不设置硬外键约束取值范围约束：Users.role 取值限定为：ROLE_USER、ROLE_STAFF、ROLE_ADMIN经度：-180 ≤ longitude ≤ 180，纬度：-90 ≤ latitude ≤ 90深度：depth ≥ 0，震级：3 ≤ magnitude ≤ 10上传文件类型：仅允许 .csv、.xls、.xlsx索引设计索引设计围绕三类高频场景：索引类型字段用途主键索引users.id, earthquakes.id, cities.id, upload_logs.id按主键快速定位记录与基础分页唯一索引users.username, cities.name登录验证、重复注册检测、城市缓存命中普通索引earthquakes.time时间区间筛选与按时间倒序展示普通索引earthquakes.magnitude震级区间筛选普通索引earthquakes.latitude, earthquakes.longitude地图视口（bounding box）过滤与空间范围初筛普通索引upload_logs.user_id, upload_logs.created_at按操作者检索导入历史、按时间区间回溯3.3.4 核心路由与业务逻辑（app/routes.py）多维查询筛选（build_query）：统一解析请求参数并拼装查询条件，供列表/导出/统计/地图复用，保证口径一致。支持日期、震级、深度、经纬度范围、地点范围（国内/国外）、关键词等多维度组合筛选def build_query(): query = Earthquake.query # 日期筛选 if start_date: query = query.filter(Earthquake.time >= ...) # 震级筛选 if min_mag is not None: query = query.filter(Earthquake.magnitude >= min_mag) # 地点范围筛选（国内/国外） if location_scope == 'china': query = query.filter(or_(*[Earthquake.location.contains(k) for k in CHINA_PROVINCES])) # ... 更多筛选条件 return query城市地震风险评估（nearby_earthquakes）：基于 Haversine 公式计算城市周边 50km/100km/150km 三层距离的地震分布，采用两阶段空间查询策略——先用经纬度 bounding box 做粗筛（利用索引快速缩小候选集），再用 Haversine 计算精确距离做精筛，显著降低计算量与 I/O。采用多因素加权评分模型：def haversine(lon1, lat1, lon2, lat2): """计算地球表面两点间的大圆距离（km）""" lon1, lat1, lon2, lat2 = map(radians, [lon1, lat1, lon2, lat2]) dlon = lon2 - lon1 dlat = lat2 - lat1 a = sin(dlat/2)**2 + cos(lat1) * cos(lat2) * sin(dlon/2)**2 c = 2 * asin(sqrt(a)) r = 6371 return c * r风险评分算法（基础分 10 分，逐项扣分）：50km 内（权重最高）：次数×0.8 + 震级累积×0.6 + 最大震级×0.5100km 内（中等权重）：次数×0.5 + 震级累积×0.4 + 最大震级×0.3150km 内（较低权重）：次数×0.3 + 震级累积×0.2 + 最大震级×0.15评分解读：8-10 分为低风险区，5-7 分为中风险区，1-4 分为高风险区。重要提示：本评分基于历史地震数据统计分析，仅供参考。地震预测极其复杂，历史低风险区域不代表未来无震。请关注官方地震预警信息，做好防震准备。统计分析（statistics）：使用 Pandas 对筛选后的数据进行四维统计分析：震级分布（3-4, 4-5, 5-6, 6-7, ≥7 分档）震源深度分布（0-10km, 10-30km, 30-70km, 70-300km, >300km 分档）发震时间趋势（自动按日/月/年聚合）地区分布 Top 10（支持全部/国内/国外切换）权限控制装饰器（role_required）：基于角色的访问控制，在路由层强制执行最小权限原则def role_required(roles): def decorator(f): @wraps(f) @login_required def decorated_function(*args, **kwargs): if current_user.role not in roles: flash('您没有权限执行此操作') return redirect(url_for('index')) return f(*args, **kwargs) return decorated_function return decorator数据导入（upload_manage）：使用 pandas 读取 Excel 并做字段名映射、空值处理与去重；在写库前按"时间+经纬度+震级"做重复判定，采用事务机制保证一致性；导入完成后生成导入结果摘要（写入 UploadLog），便于维护人员复核。3.3.5 前端可视化地震分布地图（map.html）：基于 Leaflet.js + OpenStreetMap，以圆形标记展示地震分布，圆点大小代表震级，颜色从黄色（小震）到深红色（大震）渐变，点击标记弹出详情。筛选条件透传至 API，保证地图展示始终与列表筛选一致。城市风险评估地图（city_risk.html）：在地图上绘制城市周边 50km/100km/150km 三层同心圆（红/黄/蓝虚线），叠加周边地震标记，右侧面板展示风险评估报告与安全评分。城市坐标采用缓存策略——先查 cities 表，命中则直接返回；未命中再调用 Nominatim 获取坐标并落库缓存。统计分析图表（statistics.html）：基于 Chart.js 绘制四类图表——震级分布柱状图、深度分布柱状图、时间趋势折线图、地区分布饼图。统计口径与筛选条件一致，便于用户从列表检索过渡到统计结论。全局 UI 主题（style.css）：采用 Glassmorphism（毛玻璃）设计风格，卡片半透明磨砂效果，按钮胶囊圆角渐变，导航栏根据用户角色动态变色（管理员红粉/职员橙黄/用户蓝/游客灰），形成身份可感知的低成本提示，减少越权操作的误触。3.3.6 配置文件（config.py）支持 SQLite 与 PostgreSQL 数据库无缝切换：class Config: SECRET_KEY = os.environ.get('SECRET_KEY') or 'hard-to-guess-string' # PostgreSQL（生产环境取消注释并修改连接串） # SQLALCHEMY_DATABASE_URI = 'postgresql://postgres:password@localhost/earthquakedb' # SQLite（开发环境默认） SQLALCHEMY_DATABASE_URI = os.environ.get('DATABASE_URL') or \ 'sqlite:///' + os.path.join(basedir, 'app.db') SQLALCHEMY_TRACK_MODIFICATIONS = False 3.3.7 生产数据库 DDL（schema.sql）提供 PostgreSQL 完整建表语句，含索引优化：CREATE TABLE IF NOT EXISTS earthquakes ( id SERIAL PRIMARY KEY, original_id INTEGER, time TIMESTAMP NOT NULL, longitude FLOAT NOT NULL, latitude FLOAT NOT NULL, depth FLOAT NOT NULL, magnitude FLOAT NOT NULL, location VARCHAR(255), event_type VARCHAR(50) ); CREATE INDEX IF NOT EXISTS idx_earthquakes_time ON earthquakes(time); CREATE INDEX IF NOT EXISTS idx_earthquakes_magnitude ON earthquakes(magnitude); CREATE INDEX IF NOT EXISTS idx_earthquakes_longitude ON earthquakes(longitude); CREATE INDEX IF NOT EXISTS idx_earthquakes_latitude ON earthquakes(latitude); 3.4 运行调试3.4.1 启动应用在项目根目录下执行：python run.pyFlask 开发服务器将在 http://127.0.0.1:5000 启动，开启 Debug 模式（自动重载代码修改）。3.4.2 功能验证1）未登录访客（Guest）：访问主页即可进行地震信息查询与筛选（按日期区间、震级、深度、经纬度范围、地点关键字、区域等条件组合检索，分页浏览结果）；其余涉及数据导出、统计分析、可视化模块与收藏等个性化功能限制在登录后使用。2）普通注册用户（ROLE_USER）：登录后除查询筛选外，可导出筛选后的地震数据为 CSV 表格；进行数据统计分析并以图表呈现；浏览地震分布地图与城市风险评估；维护收藏清单；进入个人中心修改密码。3）数据维护人员（ROLE_STAFF）：在普通用户权限之上，可通过 Excel 批量导入地震数据（系统自动解析、去重、记录日志）；查看导入日志以便定位问题；对单条地震记录进行编辑或删除。4）系统管理员（ROLE_ADMIN）：在维护人员权限之上，可通过管理员面板添加/删除用户、分配角色权限（ROLE_USER/ROLE_STAFF/ROLE_ADMIN）。3.4.3 数据库检查如需检查 Excel 数据文件格式，可使用：python inspect_excel.py3.4.4 切换 PostgreSQL 生产数据库1）安装 PostgreSQL 并创建数据库 earthquakedb2）执行 schema.sql 创建表结构：psql -U postgres -d earthquakedb -f schema.sql3）修改 config.py，取消 PostgreSQL 连接串注释并注释掉 SQLite 行4）重新运行 init_db.py 和 import_data.py 初始化数据四、释放资源本案例使用本地开发环境，无需释放云资源。如切换到 PostgreSQL 生产环境，请按需执行以下操作：4.1 删除 PostgreSQL 数据库psql -U postgres -c "DROP DATABASE IF EXISTS earthquakedb;" 4.2 清理 Python 虚拟环境deactivate rm -rf .venv # Linux/Mac rmdir /s .venv # Windows 五、成果展示5.1 未登录访客（Guest）界面系统对未登录访客仅开放地震信息查询与筛选能力，包括按日期区间、震级、深度、经纬度范围、地点关键字、区域等条件进行组合检索，并以分页形式浏览结果。5.2 普通注册用户（ROLE_USER）界面除提供查询服务外，普通注册用户可以导出筛选后的地震数据为表格形式；进行数据统计分析并以图表呈现；浏览地震分布地图与相关可视化视图；使用城市风险评估模块获取面向城市的分析结果；维护收藏清单以便长期跟踪；进入个人中心管理账户、修改密码等操作。5.3 数据维护人员（ROLE_STAFF）界面在这之上，系统还需为维护人员提供以下权限：数据导入能力（支持批量导入并处理重复/冲突情况）；可查看导入日志/操作日志以便定位问题；对单条地震记录进行修改或在必要时进行删除的权限。5.4 系统管理员（ROLE_ADMIN）界面在数据维护人员之上，系统需提供管理员级管理账号（新增、删除、修改用户信息）、角色权限维护（分配与调整不同用户权限范围）的权限。六、码道智能体使用心得体会本次课程设计为地震信息查询与可视化平台，围绕地震事件数据的规范化管理、便捷查询与直观呈现的目标，完成了从需求分析、数据库设计到系统实现与验证的完整流程。数据层面，项目以中国地震台网公开数据为来源，结合导入工具将地震事件要素存入数据库，并通过去重与合并策略保证导入结果准确、可用且便于后续维护。系统设计层面，围绕查询、地图、统计与维护四类核心需求建立了较为清晰的模块边界。在关系数据库中提取用户、地震事件、城市缓存、收藏关系与上传日志等关键实体，通过完整性约束与索引设计支撑分页检索、组合筛选和审计回溯，并以访客、普通用户、数据维护人员和管理员四类角色落实最小权限原则。实现层面，后端采用 Flask 与 SQLAlchemy 构建统一的数据模型和查询逻辑，提供列表筛选、数据导入导出、地图数据查询以及城市风险评估等接口；前端以 Web 页面为主要载体，完成地震分布地图与统计图表展示。整体系统能够稳定运行，基本形成了“筛选查询—可视化分析—导出复用—维护更新”的完整操作流程。在本次课程设计中，我还使用了华为云码道智能体辅助完成项目开发。实际使用过程中，我体会到智能体不仅能够根据自然语言理解开发需求，还可以结合项目上下文分析代码结构、定位问题并提出修改建议。在数据库模型设计、前后端接口衔接、运行环境配置和错误排查等环节，码道智能体减少了查找资料和重复修改代码所耗费的时间，使我能够将更多精力放在系统功能设计与业务逻辑梳理上。不过，使用智能体并不意味着可以完全依赖其自动生成结果。有时智能体给出的代码虽然形式上完整，但仍可能与项目现有结构、依赖版本或实际业务规则存在偏差，需要开发者进一步检查、运行和调整。因此，我逐渐认识到，较好的使用方式是先明确需求和约束，将较大的任务拆分为具体步骤，再让智能体协助分析和实现，最后通过测试验证结果。这个过程也让我更加重视需求描述、代码阅读和调试能力。通过本次实践，我对华为云码道智能体在软件开发中的作用有了更直观的认识。它更适合作为开发过程中的辅助工具，帮助开发者提高编码、排错和理解项目的效率，而项目的整体设计、功能取舍以及最终质量仍需要由开发者负责。此次课程设计不仅加深了我对数据库设计与 Web 系统开发流程的理解，也让我初步掌握了利用代码智能体协同完成实际工程任务的方法。七、码道核心功能使用总览本项目在开发过程中深度使用了华为云码道（CodeArts）代码智能体的各项功能，以下按功能类别详细记录使用情况。7.1 智能编码与代码生成功能使用场景具体描述自然语言生成代码数据模型定义通过自然语言描述"创建地震事件模型，包含时间、经纬度、深度、震级、位置、事件类型字段，并对高频查询字段建立索引"，码道自动生成 Earthquake 模型类及完整的 SQLAlchemy Column 定义自然语言生成代码路由与业务逻辑描述"实现多维组合查询，支持日期、震级、深度、经纬度、地点范围、关键词筛选"，码道生成 build_query() 函数框架，包含参数解析与 ORM 条件拼接自然语言生成代码Haversine 距离计算描述"实现 Haversine 公式计算地球表面两点间大圆距离"，码道生成精确的球面距离计算函数自然语言生成代码权限控制装饰器描述"创建基于角色的权限控制装饰器，支持多角色校验"，码道生成 role_required() 装饰器及路由级权限校验逻辑代码补全模板渲染编写 Jinja2 模板时，码道自动补全 Flask 模板语法（url_for、render_template、{% block %} 等）代码补全SQLAlchemy 查询编写 ORM 查询链时，码道自动补全 filter、order_by、paginate 等方法及字段名7.2 代码理解与搜索功能使用场景具体描述语义搜索（CodeSemanticSearch）理解代码架构查询"城市风险评估是如何计算的"，码道定位到 nearby_earthquakes 路由函数，展示完整的两阶段空间查询与加权评分算法语义搜索（CodeSemanticSearch）追踪数据流查询"地震数据从 Excel 导入到数据库的完整流程"，码道串联 import_data.py → models.py → routes.py 的数据流路径结构搜索（CodeGraphSearch）依赖分析查询"User 模型被哪些路由引用"，码道展示所有使用 current_user 和 User.query 的路由函数及行号结构搜索（CodeGraphSearch）影响分析查询"修改 Earthquake 模型会影响哪些功能"，码道列出所有引用该模型的路由、模板和导入脚本代码探索（Explore Agent）项目结构理解使用 explore 子代理全面分析项目目录树、技术栈、核心文件功能，生成完整的项目结构报告7.3 代码编辑与重构功能使用场景具体描述精确字符串替换（Edit）修复路由逻辑精确定位 routes.py 中的查询条件拼接错误，替换为正确的 SQLAlchemy or_ / and_ 表达式精确字符串替换（Edit）更新模型字段为 Earthquake 模型添加 original_id 字段，同步更新 import_data.py 的导入逻辑全量替换（ReplaceAll）变量重命名将全局常量 PROVINCES 重命名为 CHINA_PROVINCES，全文件一次性替换文件写入（Write）创建新模板创建 city_risk.html、upload_manage.html 等新页面模板文件写入（Write）生成文档创建 工程说明.md、schema.sql 等项目文档与配置文件7.4 终端与命令执行功能使用场景具体描述Bash 命令执行依赖安装执行 pip install flask flask-sqlalchemy flask-login pandas openpyxl xlrd werkzeug 安装项目依赖Bash 命令执行数据库初始化执行 python init_db.py 创建数据表与默认用户Bash 命令执行数据导入执行 python import_data.py 批量导入地震速报目录 Excel 数据Bash 命令执行应用启动执行 python run.py 启动 Flask 开发服务器进行调试Bash 命令执行Git 版本管理执行 git log、git branch、git diff 等命令查看提交历史与分支状态Bash 命令执行文件日期修改执行 PowerShell 命令批量修改文件修改日期为指定日期7.5 文件操作与搜索功能使用场景具体描述文件读取（Read）代码审查读取 routes.py（758行）、models.py、所有 HTML 模板等核心文件，理解完整业务逻辑文件读取（Read）文档解析读取 .docx 课程设计报告，使用 python-docx 库提取全部段落文本与表格数据文件搜索（Glob）文件定位使用 **/*.py、**/*.html、**/*.docx 等模式快速定位项目文件内容搜索（Grep）代码定位搜索 ROLE_ADMIN、haversine、build_query 等关键字，定位代码实现位置文件删除（DeleteFile）清理文件删除临时文件或过时的脚本7.6 Git 版本控制功能使用场景具体描述提交历史查看开发进度追踪查看从 a25324d 中期任务 到 cfb0249 更新项目名称 的 8 次提交记录分支管理功能分支开发项目使用 6 个分支：main、beta、favourite、map、name、whole，分别对应不同开发阶段分支策略渐进式开发各分支代表不同实现阶段：name（命名优化）→ favourite（收藏功能）→ map（地图功能）→ whole（完整功能）→ beta（测试）→ main（稳定版）

gitcode仓库链接：https://gitcode.com/gcw_UVRIWCMW/CampusFlow系统演示视频已经上传至仓库。一、概述1.1 案例介绍高校学生的日程通常由课程、周期性活动、作业、复习、社团事务和生活任务共同构成。手动安排周计划容易出现三类问题：重要任务被临时事项挤占、碎片时间没有被有效利用、计划发生变化后需要整体重排。此外，部分想从零培养起时间规划习惯的同学面对庞杂的任务、事件条目与大量碎片化时间，想要好好进行任务规划却不知从何下手的难题。为此，本案例构建 CampusFlow 智能校园周计划调度系统，以同济大学嘉定校区的课程与生活场景为示例，使用 FastAPI + SQLAlchemy + SQLite 构建后端，使用 Vue 3 + TypeScript + Pinia + Vite 构建前端，并通过高德地图 API 提供地点检索、逆地理编码和步行时间估算能力。此版本系统展示暂时不依赖大模型，而是使用确定性算法完成以下功能：核心能力实现方式用户价值周计划自动生成硬约束扣减、任务排序、贪心放置、负载均衡、时段多样性自动将待办任务安排到本周可用时段Top3 实时推荐精力、截止时间、地点、优先级、时长、可拆分性六维评分在当前碎片时间内快速判断“现在最适合做什么”顺路任务发现步行路径和绕行成本计算，接口失败时使用本地估算识别取快递、打印、购物等顺路可完成事项增量重规划识别受影响计划项，仅重排局部任务避免课程或任务变化后整周计划大幅“抖动”What-if 沙盘在隔离数据上应用模拟条件并比较前后方案提前评估生病、临时活动、截止日期提前等风险精力状态管理分时段精力曲线与手动状态覆盖将高难度任务安排到更合适的精力时段技术选型：华为云码道(CodeArts)代码智能体：华为云提供的智能化软件开发工具，融合代码大模型、AI IDE 和 Code Agent 等能力，能够理解项目需求并辅助完成代码生成、代码优化和工程构建。本案例中使用华为云码道(CodeArts)代码智能体作为核心开发辅助工具，根据智能校园周计划调度系统应用需求完成前后端功能开发，加速 Web 应用构建过程，降低应用开发门槛。1.2 适用对象高校学生及校园效率工具爱好者；希望学习时间调度、推荐评分和增量计算的个人开发者；从事教育信息化、日程管理或任务管理产品开发的工程师。1.3 案例时间本案例总时长预计180分钟。不包含 Python、Node.js 的首次下载时间以及高德开放平台账号认证时间。1.4 案例流程说明：开通华为开发者空间，领取华为云码道（CodeArts）代码智能体通用体验权限，同时准备 Python、Node.js、Git 等本地开发环境并申请高德地图 API Key；梳理智能校园周计划调度需求，编写 CampusFlow SDD、SKILLs 开发规则和结构化提示词，使用码道代码智能体生成 FastAPI 后端、Vue 3 前端及测试用例；安装 Python 和前端依赖，配置高德地图 API Key，初始化 SQLite 数据库，分别启动 FastAPI 后端服务与 Vue 3 前端应用，完成本地联调；运行种子数据脚本构建校园示例场景，围绕业务闭环、调度准确性和交互体验进行多轮测试与迭代优化；完成周计划自动生成、Top3 实时推荐、顺路任务发现、增量重规划和 What-if 沙盘模拟等功能验收，交付可在本地完整运行的 CampusFlow 应用。1.5 资源总览本案例预计花费0元，其中华为云码道（CodeArts）代码智能体（专业版）使用发放的代金券购买。资源名称规格单价（元）本地开发环境Python 3.10+ / Node.js 18+免费高德地图Web服务API个人开发者每日5000次调用额度免费SQLite数据库内置零依赖免费华为云码道（CodeArts）代码智能体专业版139/月二、环境和资源准备2.1 领取华为云码道代码智能体使用权限登录华为开发者空间，进入码道 CodeArts产品页，领取通用体验版权限，开通代码智能体（专业版）服务，获取在线代码生成与迭代能力。2.2 IDE安装与部署参考案例《AI IDE华为云码道（CodeArts）代码智能体安装部署》，完成Windows版华为云码道代码智能体安装部署。2.3 开发环境本案例在本地开发运行，需确保以下环境已安装：依赖项最低要求推荐版本验证命令Python3.103.11 或 3.12python --versionNode.js20.19+ 或 22.12+22 LTSnode --versionnpm10随 Node.js 22 安装的版本npm --versionGit非必需最新稳定版git --version2.4 申请高德地图Web服务API Key高德地图API为本系统提供逆地理编码、POI搜索和步行路径规划能力，是顺路任务发现和碎片时间计算的核心依赖。访问高德开放平台，注册并登录账号；进入 控制台 > 应用管理 > 我的应用，点击"创建新应用"；添加Key，服务平台选择"Web服务"，获取API Key；个人开发者每日享有5000次免费调用额度，满足本案例需求。三、构建CampusFlow智能校园调度应用3.1 需求分析与功能设计项目名称： 智序校园（CampusFlow）——智能校园周计划调度系统项目定位：面向高校学生的智能时间规划与任务调度平台。系统统一管理课程、校园活动、作业任务、个人待办和精力状态，综合考虑任务优先级、截止时间、可用时段、任务难度、当前位置及步行时间，自动生成可执行的校园周计划。系统还支持实时任务推荐、顺路任务发现、计划动态调整和 What-if 沙盘模拟，帮助学生减少手动排期成本，提高碎片时间利用率和任务完成效率。开发方式：使用华为云码道（CodeArts）代码智能体，结合 CampusFlow SDD、SKILLs 开发规则和结构化提示词，辅助完成需求分析、系统设计、前后端代码生成、测试用例编写及多轮迭代优化。项目最终在 PC 本地运行，不部署到华为云，也不调用华为云 MaaS 平台大模型服务。技术栈：前端：Vue 3 + Vite + TypeScript状态管理：Pinia路由管理：Vue RouterHTTP 客户端：Axios后端：Python + FastAPI数据访问：SQLAlchemy ORM数据校验：Pydantic数据库：SQLite外部服务：高德地图 Web 服务 API测试框架：Pytest运行方式：PC 本地前后端分离运行核心功能：管理课程、固定活动、普通任务、固定时间任务和顺路任务；根据课程与固定事件提取时间硬约束，计算每周可用时间段；综合任务优先级、截止时间、任务难度和每日负载，自动生成校园周计划；支持可分割任务拆分安排，并对长期任务进行分阶段调度；根据当前精力、剩余时间、任务难度、地点和优先级进行六维评分，实时推荐最适合执行的 Top3 任务；结合当前位置、下一目的地和步行路径，识别可在途中完成的顺路任务；计算下一课程或活动开始前的碎片时间，并扣除步行时间和必要缓冲时间；在课程变更、任务提前完成、任务未完成、新增高优先级任务等情况下触发增量重规划；仅调整受到影响的计划项，保留其他已安排内容，降低计划频繁变化带来的干扰；支持封锁某天、增加任务时长、提前截止时间、减少每日可用时间和添加临时活动等 What-if 沙盘模拟；对比原计划与模拟计划，识别任务未安排、截止逾期和风险变化；支持查看周计划时间线、任务详情、推荐理由、重规划记录和沙盘模拟结果；使用高德地图 API 完成地址解析、地点搜索和步行路径规划，并在接口异常时采用本地步行时间估算方案。3.2 Prompt 设计和 SDD 生成（1）根据以上项目需求，设计如下 Prompt（V1实现部分最基础的功能，剩余功能在V2实现）：请帮我初始化一个SDD项目，先不要执行开发任务，我检查修改SDD项目后再告诉你执行开发： 1、项目概述 项目名称：CampusFlow - 大学生智能时间与任务调度系统 项目定位： 面向大学生的“时间—地点—精力—任务”多约束智能调度Web应用。 系统不仅管理待办任务，还结合课程安排、固定事件、当前位置、移动时间、精力状态、Deadline和任务难度，解决两个核心问题： （1）“这一周的任务应该怎么安排？”——生成本周推荐计划。 （2）“现在这个时间、地点和精力状态下，我最适合做什么？”——生成当前Top 3任务推荐。 同时支持Opportunity Task顺路机会，例如用户吃完饭准备去图书馆时，如果前往图书馆途中可以顺路去菜鸟驿站取快递，则在对应推荐中提示顺路完成。 技术栈： 前端：Vue3 + Vite + TypeScript 后端：FastAPI（Python） 数据库：SQLite 地图：高德地图JS API + 高德Web Service API 项目的mcp_settings.json中已经配置高德地图MCP及Web Service API Key。 高德MCP用于开发阶段辅助调用地图能力；应用运行时，高德地图JS API负责地图展示、浏览器定位、Marker和地图点击选点，逆地理编码、POI搜索和步行路径规划等高德Web Service能力通过FastAPI后端封装调用。 2、页面布局与核心功能 页面一：Dashboard 展示： 当前时间 当前地点 当前精力状态 当前有效碎片时间 下一行动目的地 下一个课程/固定事件 当前Top 3任务推荐 推荐理由 顺路Opportunity Task 今日计划概览 本周计划入口 支持手动设置“下一站”，可以从已有地点、POI搜索结果或地图点击位置中选择。 页面二：本周计划 以周视图展示： 课程 固定事件 推荐任务时间块 空闲时间 功能： 根据本周课程、固定事件、任务Deadline、预计时长、难度、优先级、精力曲线、地点偏好和任务可分割性生成本周推荐计划。 课程和固定事件属于不可移动的硬约束。 Deadline较近和优先级较高的任务优先安排。 高难度任务优先安排在高精力时间段。 可分割任务允许拆分到多个满足最小分割时间的时间段。 支持“生成本周计划”和“重新生成本周计划”。 V1采用规则式周计划推荐，不要求全局最优，也不自动持续重排整个未来计划。 页面三：任务管理 普通任务属性： 任务名称 Deadline 预计时长 难度 用户优先级 任务类型 地点偏好 是否可分割 最小分割时间 备注 状态 支持： 创建 编辑 删除 标记完成 查看待办和已完成任务 普通任务主要参与本周计划和当前Top 3推荐。 部分任务可以设置为Opportunity Task，例如： 取快递 打印材料 买文具 校园卡充值 去超市买东西 Opportunity Task通常没有明确Deadline，但需要设置： 具体地点或POI 预计执行时间 用户优先级 创建时间 状态 对于没有Deadline的Opportunity Task，根据加入待办列表后的等待时长计算动态紧迫程度。 等待时间越长，推荐优先级逐渐提高，但设置上限，不直接修改用户自己设置的优先级。 页面四：课程与固定事件 支持添加、编辑和删除课程及固定事件。 属性包括： 名称 开始时间 结束时间 具体地点 课程和固定事件作为周计划和碎片时间计算的硬约束。 页面五：地点与地图 使用高德地图展示校园位置。 自动定位流程： 页面加载后使用高德地图JS API请求浏览器定位权限。 定位成功后，在地图中显示当前位置Marker，并获取详细地址和地点语义。 定位失败、超时或用户拒绝权限时： 显示地图并提示用户手动选择当前位置。 用户直接点击地图任意位置即可添加当前位置Marker。 再次点击其他位置时移动原Marker。 根据点击坐标获取详细地址和附近POI，并将该位置设置为当前地点。 即使自动定位成功，也支持“重新选择当前位置”。 支持POI搜索，例如： 图书馆 教学楼 食堂 宿舍 菜鸟驿站 打印店 超市 体育场 搜索结果显示在地图中，用户可以将POI设置为： 当前地点 下一行动目的地 课程或固定事件地点 Opportunity Task地点。 页面六：精力状态 精力分为： 高 中 低 支持： 手动设置当前精力 设置一天不同时间段的精力曲线 未手动设置时根据当前时间自动推断当前精力状态。 3、核心功能流程 当前Top 3推荐流程： 根据当前时间、当前位置、当前精力、下一固定事件和待办任务计算有效碎片时间。 有效碎片时间 = 下一固定事件开始时间 - 当前时间 - 前往下一固定事件地点的步行时间 - 缓冲时间。 根据有效碎片时间筛选当前可以执行的任务，再综合： 精力与任务难度匹配 Deadline紧迫程度 地点语义匹配 用户优先级 预计执行时间 可分割性 使用确定性规则计算并返回Top 3任务，同时生成可解释推荐理由。 地点、精力、任务、时间或固定事件变化后重新计算推荐。 本周计划生成流程： 读取课程和固定事件形成本周硬约束时间块，识别剩余空闲时间。 根据任务Deadline、优先级、预计时长、难度、精力曲线、地点偏好和可分割性，将普通待办任务推荐到合适的时间段。 Opportunity Task原则上不强制加入普通周计划时间块，主要结合实际移动路线进行顺路推荐。 下一行动目的地流程： 下一行动目的地表示用户完成当前活动后准备前往的具体地点。 来源可以包括： 用户手动设置的下一站 本周计划中下一项安排的地点 用户准备执行的Top 3任务对应地点 下一课程或固定事件地点 例如： 当前在食堂 接下来准备去图书馆学习 即使“去图书馆学习”不是课程或固定事件，图书馆仍然可以作为下一行动目的地。 Opportunity Task顺路推荐流程： 比较： 当前位置 → 下一行动目的地 和： 当前位置 → Opportunity Task地点 → 完成Opportunity Task → 下一行动目的地 计算额外绕行时间。 只有当： Opportunity Task仍为待办 地点明确 下一行动目的地明确 时间允许 不影响后续课程或固定事件 额外绕行成本处于合理范围 时才作为顺路机会推荐。 Opportunity Task作为Top 3推荐的补充信息展示。 例如： Top 1： 去图书馆完成数据库作业 推荐理由： 当前精力较高，Deadline较近，图书馆适合完成该任务。 顺路机会： 前往图书馆途中可以顺路到菜鸟驿站取快递，该任务已等待3天，预计额外增加6分钟。 不同Top 3任务由于下一行动目的地不同，可以对应不同的顺路机会。 4、地图能力与异常处理 高德地图主要用于： 浏览器定位 地图展示 地图点击选点 Marker 逆地理编码 POI搜索 步行距离和时间计算 Opportunity Task顺路路线计算 高德服务调用失败时准备合理的Mock或fallback数据，不阻塞任务管理、本周计划、精力管理和基础Top 3推荐，并明确提示当前使用的是估算或演示数据。 5、设计风格 整体采用现代、简洁、清爽的校园效率工具风格。 重点突出： 当前状态 时间安排 地点移动 推荐结果 周计划 界面避免复杂堆叠和明显的AI生成感，信息层级清晰。 支持桌面端与移动端响应式布局，地图、周计划和推荐卡片需要具有良好的交互体验。 6、V1范围 V1实现： 本周计划推荐 当前Top 3推荐 Opportunity Task顺路机会 任务管理 课程与固定事件 自动定位与地图点击选点 POI搜索 地点与步行时间 精力曲线 有效碎片时间 状态变化后的实时推荐 先不要执行开发任务，生成完成后总结当前项目的功能范围、核心流程和主要技术方案，然后停止，等待我检查修改SDD。在码道对话界面选择 规范驱动模式(Spec-Driven Mode)，发送上述请求。（2）码道根据需求描述，生成需求规格文档 spec.md。如有需要可对需求规格文档进行修改。（3）确认后，码道继续生成技术设计文档 design.md，完成生成后可按需修改。（4）确认后，码道继续生成编码任务文档 task.md，完成生成后可按需修改。（5）检查需求规格文档、技术设计文档、编码任务文档是否与预期一致，如有需要调整的地方可直接进行修改。3.3 编码任务执行确认 SSD 无误后，在码道界面发送请求：遵循spec.md、design.md、tasks.md进行项目开发。码道将根据 SSD 执行编码任务。完成待办事项：开发总结：3.4 V1问题修复与系统优化（部分对话）3.5 V2功能开发CampusFlow基础版本已经完成。 请基于当前已有项目、SDD、数据模型和功能进行增量开发，不要重新搭建项目，不要破坏现有的任务管理、课程/固定事件、周计划、当前Top 3推荐、地点地图、精力状态等功能。 本次新增或细化以下3项功能： 1、完整自动动态重规划 当前CampusFlow已经能够生成本周计划。本次增加自动动态重规划能力。 当现实情况发生变化时，系统自动识别受影响的计划，并重新安排尚未完成的任务，而不是要求用户手动重新生成整个周计划。 需要触发动态重规划的情况包括： - 新增、修改或删除课程/固定事件； - 当前任务未按计划完成； - 任务提前完成； - 新增高优先级任务； - 修改任务Deadline、预计时长或优先级； - 当前时间已经超过原计划任务时间； - 用户位置或可用时间发生明显变化。 例如： 原计划： 14:00-16:00 完成数据库报告 19:00-20:00 英语阅读 14:00突然增加临时班会。 系统需要识别数据库报告无法按原时间执行，并自动寻找新的可用时间段重新安排，同时检查后续任务是否受到影响。 重规划时： - 已完成任务不得修改； - 已开始且用户确认继续执行的任务不得随意移动； - 课程和固定事件属于硬约束，不得移动； - 优先调整受影响任务及其后的计划，避免无必要地重排整个星期； - 必须继续考虑Deadline、优先级、任务时长、精力曲线、地点和可分割性； - 可分割任务可以重新分配剩余部分； - 重规划后向用户展示哪些任务发生了变化以及变化原因。 Dashboard和本周计划中需要明显提示： “计划已根据最新情况自动调整”。 用户可以查看调整前后的差异。 2、What-if时间沙盘 新增“What-if时间沙盘”，用于模拟计划变化，但不能直接修改真实计划。 用户可以临时修改某些条件，例如： - “如果周六全天没有时间学习？” - “如果数据库报告增加2小时工作量？” - “如果周五晚上临时有活动？” - “如果这个任务提前到周三截止？” - “如果每天晚上少安排1小时任务？” 系统基于当前真实数据创建临时模拟场景，并重新计算计划。 页面需要展示： - 当前真实计划； - 模拟后的计划； - 哪些任务发生变化； - 哪些任务可能无法按Deadline完成； - 总可用时间变化； - 任务安排变化； - 风险变化。 What-if模拟不得直接修改： - 原任务； - 原课程； - 原固定事件； - 当前真实周计划。 用户可以： - 放弃模拟； - 修改模拟条件继续计算； - 点击“应用此方案”，确认后才将模拟方案应用到真实计划。 例如： 用户模拟“周六全天不可用”。 系统发现科研任务无法按照原计划完成，则提示： “科研任务存在延期风险，建议将其中90分钟提前安排至周四晚上。” 3、Opportunity Task顺路任务 进一步细化Opportunity Task顺路机会相关功能。 Opportunity Task是适合在移动途中顺便完成的短任务，例如： - 取快递； - 打印材料； - 买文具； - 校园卡充值； - 去超市买东西； - 领取文件。 这类任务： - 可以没有Deadline； - 必须绑定具体地点或POI； - 具有预计执行时间； - 具有创建时间； - 可以设置用户优先级。 对于没有Deadline的Opportunity Task，根据加入待办后的等待时间计算“Aging Urgency”。 等待时间越长，系统紧迫度越高，但必须设置最大值，不允许无限增长。 例如： 今天刚加入“取快递” → 紧迫度较低。 已经等待3天 → 优先级提高。 已经等待较长时间 → 在其他条件接近时应优先推荐。 Opportunity Task需要结合“下一行动目的地”进行顺路判断。 下一行动目的地不局限于下一课程或固定事件，可以来自： - 用户手动指定的下一站； - 本周计划中的下一项安排地点； - 当前准备执行的Top 3任务对应地点； - 下一课程/固定事件地点。 例如： 当前位置：食堂 下一站：图书馆 Opportunity Task：菜鸟驿站取快递 即使“去图书馆学习”不是课程或固定事件，仍需要判断： 食堂 → 图书馆 与： 食堂 → 菜鸟驿站 → 图书馆 之间的时间差。 顺路总成本需要考虑： 当前位置 → Opportunity Task地点的步行时间 + Opportunity Task执行时间 + Opportunity Task地点 → 下一行动目的地的步行时间。 计算相对于直接前往下一行动目的地增加的额外成本。 仅当： - Opportunity Task仍为待办； - 地点明确； - 下一行动目的地明确； - 额外绕行成本低于阈值； - 时间足够； - 不影响后续课程/固定事件； 才作为顺路机会。 Opportunity Task与当前Top 3推荐结合展示，不单独形成另一套主要推荐系统。 例如： Top 1：去图书馆完成数据库作业 推荐理由： 当前精力高，数据库作业Deadline较近。 顺路机会： 前往图书馆途中可顺路到菜鸟驿站取快递，该任务已等待3天，预计额外增加6分钟。 不同Top 3任务对应的下一行动目的地不同，因此可以产生不同的顺路机会。 一个Top 3任务可以对应0个、1个或多个Opportunity Task。 多个顺路机会需要综合： - Aging Urgency； - 用户优先级； - 额外绕行成本； - 执行时间； 进行排序。 4、功能联动 新增的三个功能必须与现有CampusFlow数据和推荐逻辑联动。 动态重规划负责： “现实发生变化以后，剩余计划应该怎么调整？” What-if负责： “假如某种情况发生，计划会变成什么样？” Opportunity Task负责： “我实际移动途中，有没有值得顺手完成的事情？” What-if属于模拟，不应触发真实动态重规划。 只有用户确认应用What-if方案后，才能修改真实计划。 Opportunity Task完成后，应同步更新待办状态，并重新计算相关推荐。 请优先复用现有代码、数据模型、调度算法和高德地图能力。 根据新增功能同步更新当前SDD，保持需求、设计、任务和实际代码一致。 完成开发后运行相关测试，重点测试动态重规划、What-if隔离、Opportunity Task路线判断和异常边界情况，并总结本次新增功能及测试结果。V2开发完成后项目开发到此结束，此后继续根据发现的问题进行系统优化，此处不再赘述。四、系统说明4.1 项目结构说明CampusFlow/ ├── backend/ # FastAPI 后端 │ ├── app/ │ │ ├── main.py # 应用入口，路由注册与自动迁移 │ │ ├── config.py # 集中配置（权重、API Key、常量） │ │ ├── models/ # SQLAlchemy ORM 模型 │ │ │ ├── task.py # 任务模型（普通/顺路/固定时间） │ │ │ ├── schedule.py # 课程与固定事件模型 │ │ │ ├── energy.py # 精力曲线与状态模型 │ │ │ ├── plan.py # 周计划、计划项、重规划日志、沙盘会话 │ │ │ └── location.py # 下一目的地模型 │ │ ├── schemas/ # Pydantic 请求/响应模式 │ │ ├── repositories/ # 数据访问层 │ │ ├── services/ # 业务逻辑层（核心算法） │ │ │ ├── plan_service.py # 周计划调度算法 │ │ │ ├── recommend_service.py # Top3推荐（6维评分） │ │ │ ├── replan_service.py # 增量重规划（7种触发） │ │ │ ├── whatif_service.py # What-if沙盘模拟 │ │ │ ├── fragment_time_service.py # 碎片时间计算 │ │ │ ├── opportunity_service.py # 顺路机会发现 │ │ │ └── next_destination_service.py # 下一目的地推断 │ │ ├── adapters/ # 外部API适配器 │ │ │ ├── amap_client.py # 高德地图REST API客户端 │ │ │ └── walking_estimator.py # 步行时间估算（降级方案） │ │ └── routers/ # API路由（8个模块） │ ├── tests/ # pytest 测试 │ ├── requirements.txt # Python依赖 │ └── seed_data.py # 种子数据脚本 └── frontend/ # Vue 3 前端 └── src/ ├── views/ # 7个页面视图 ├── components/ # 可复用组件 ├── stores/ # Pinia状态管理（8个Store） ├── services/ # API调用服务 └── types/ # TypeScript类型定义 4.2 系统架构4.3 核心算法架构4.4 部署后端服务4.4.1 安装Python依赖在终端中执行：cd CampusFlow/backend pip install -r requirements.txtrequirements.txt 核心依赖如下：fastapi==0.115.0 uvicorn[standard]==0.30.6 sqlalchemy==2.0.35 alembic==1.13.2 pydantic==2.9.2 httpx==0.27.2 python-dotenv==1.0.1 pytest==8.3.4 4.4.2 配置高德地图API Key通过环境变量设置，无需修改代码：export AMAP_API_KEY="您的高德地图API Key" 4.4.3 关键代码讲解（1）调度算法核心 — plan_service.py调度算法是系统核心，采用贪心放置 + 负载均衡 + 时间多样性策略：def generate_weekly_plan(self, week_start: date) -> WeeklyPlan: # 1. 计算硬约束（课程+固定事件） schedules = self.schedule_repo.get_by_week(week_start) # 2. 计算空闲时间段（扣除睡眠00:00-07:30和硬约束） free_slots = self._compute_free_slots(schedules, week_start) # 3. 按天分组空闲段 slots_by_day = self._group_slots_by_day(free_slots) # 4. 分离固定时间任务和弹性任务 fixed_time_tasks, flexible_tasks = self._separate_tasks(tasks) # 5. 优先安排固定时间任务 for task in fixed_time_tasks: self._find_best_placement(task, slots_by_day) # 6. 弹性任务按(优先级, 截止日期, 难度)排序 flexible_tasks.sort(key=lambda t: (-t.priority, t.deadline, t.difficulty)) # 7. 可分割任务循环拆分安排 for task in flexible_tasks: if task.is_splittable: self._schedule_splittable_task(task, slots_by_day) else: self._find_best_placement(task, slots_by_day) 放置评分算法：选择score最小的位置放置任务score = day_assigned_minutes[day_idx] # 负载均衡：优先安排到当天任务少的位置 - diversity_bonus # 时间多样性奖励（新时段类型+100分） + waste * 0.1 # 浪费惩罚（空闲段-任务时长的冗余） （2）6维推荐评分 — recommend_service.pydef _calculate_score(self, task, fragment_minutes, energy_level): score = ( self.W_ENERGY_DIFFICULTY * energy_difficulty_match # 精力-难度匹配 (0.25) + self.W_DEADLINE_URGENCY * deadline_urgency # 截止紧急度 (0.25) + self.W_LOCATION_MATCH * location_match # 地点匹配 (0.15) + self.W_USER_PRIORITY * user_priority # 用户优先级 (0.15) + self.W_DURATION_FIT * duration_fit # 时长适配 (0.10) + self.W_SPLITTABLE_BONUS * splittable_bonus # 可分割奖励 (0.10) ) return score精力-难度匹配矩阵：任务难度: high任务难度: medium任务难度: low精力: high1.00.70.3精力: medium0.51.00.7精力: low0.10.51.0设计思路：高精力时优先做高难度任务（1.0），低精力时优先做低难度任务（1.0），避免精力低谷强行攻坚。（3）增量重规划 — replan_service.py7种触发条件及其影响范围识别：核心优势：增量重规划仅重排受影响的计划项，保留未受影响部分，避免全量重排导致计划"抖动"。（4）What-if沙盘模拟 — whatif_service.py6种模拟条件类型：条件类型参数效果block_dayday_offset, name整天不可用（模拟生病/请假）block_time_rangeday_offset, start_hour, end_hour, name某时段不可用（模拟临时有事）increase_task_durationtask_id, extra_minutes增加任务工作量（模拟作业比预期更耗时）change_deadlinetask_id, new_deadline修改截止日期（模拟deadline提前）reduce_daily_hourshours每天少安排N小时（模拟效率下降）add_eventday_offset, start_hour, end_hour, name添加临时活动（模拟突发会议）模拟流程：应用条件 → 模拟调度 → 对比分析 → 风险计算5种风险类型：deadline_risk（原计划有但模拟中未安排）、new_unassigned（新增未安排任务）、deadline_overdue（完成时间超过deadline）、risk_increased/risk_decreased（风险增减对比）（5）高德地图API集成 — amap_client.pyclass AMapClient: BASE_URL = "https://restapi.amap.com/v3" async def regeocode(self, lng: float, lat: float) -> dict: """逆地理编码：坐标 → 地址""" async def search_poi(self, keywords: str, city: str = None) -> list: """POI关键词搜索""" async def walking_direction(self, origin: str, destination: str) -> dict: """步行路径规划：返回距离、时长、分步导航""" 容错机制：内存缓存（5分钟TTL）+ 请求限流（0.2秒间隔）+ API失败降级到WalkingEstimator（Haversine距离 + 5km/h速度估算）4.4.4 填充种子数据种子数据脚本 seed_data.py 以同济大学嘉定校区为场景，填充示例数据：python seed_data.py填充内容包括：11个建筑坐标：复楼、广楼、安楼、嘉定机房、体育中心、佳新馆、图书馆、食堂、宿舍楼、菜鸟驿站、实验室15门课程：覆盖周一~周六，5个时间段（1-2节~9-10节）6个固定事件：班长例会、ACM社团午餐会、英语角等15个任务：4个已完成 + 8个待办普通任务 + 4个待办顺路任务精力曲线：9个时段分段（06:00~23:59）4.4.5 启动后端服务cd backend uvicorn app.main:app --reload --port 8000 启动后访问 http://localhost:8000/docs 可查看Swagger API文档。4.5 部署前端应用4.5.1 安装前端依赖在新终端中执行：cd CampusFlow/frontend npm install package.json 核心依赖：{ "vue": "^3.5.39", "pinia": "^4.0.2", "vue-router": "^4.6.4", "axios": "^1.18.1", "vite": "^8.1.1", "typescript": "~6.0.2" } 4.5.2 前端关键代码讲解（1）API客户端与代理配置services/apiClient.ts 中配置后端API地址：const apiClient = axios.create({ baseURL: "http://localhost:8000/api", timeout: 10000, }); vite.config.ts 中配置开发代理，将 /api 请求转发到后端：server: { port: 5173, proxy: { '/api': { target: 'http://localhost:8000', changeOrigin: true, }, }, } （2）Pinia状态管理Store管理状态核心方法planStoreweeklyPlan, nextDestinationfetchWeeklyPlan, generateWeeklyPlanrecommendStorerecommendations(Top3)fetchTop3replanStorelastReplanResult, showReplanBannertriggerReplan, dismissBannerwhatifStoresessions, currentSessioncreateSimulation, applySessionenergyStorecurrentState, curvefetchCurrentState, setManualLeveltaskStoretasksfetchTasks, createTask, completeTaskscheduleStoreschedulesfetchSchedules, createSchedulelocationStorecurrentLocation, currentAddresssetCurrentLocation, setDefaultCampus（3）核心组件组件功能Top3RecommendCard.vueTop3推荐卡片展示（6维分数、推荐理由、顺路机会）OpportunityCard.vue顺路机会卡片（绕行时间、aging紧迫度）TaskForm.vue任务创建/编辑表单（支持普通/顺路/固定时间类型）ScheduleForm.vue课程/事件表单（含地点坐标选择）EnergyCurveEditor.vue精力曲线可视化编辑器（拖拽调节高/中/低）4.5.3 启动前端开发服务器npm run dev前端开发服务器启动于 http://localhost:5173。4.6 功能体验4.6.1 仪表盘 — 实时推荐与顺路发现访问 http://localhost:5173，进入主仪表盘页面：当前状态区：显示当前时间、地点、精力状态、碎片时间Top3推荐区：基于6维评分推荐当前碎片时间最适合做的3个任务，每个任务显示总分、各维度分数和推荐理由顺路机会区：显示去下一目的地途中可顺便完成的任务，包含绕行额外时间和aging紧迫度今日计划区：展示当天已安排的计划项时间线重规划横幅：当检测到需要重规划时，顶部弹出提示横幅4.6.2 本周计划 — 自动调度时间线7天时间轴：周一~周日，按时间段展示推荐任务（由于截图时间为周日，故只有周日排了任务）重规划标记：被重规划调整的计划项显示变更标记未安排任务：无法安排的任务在底部单独列出4.6.3 What-if沙盘模拟选择模拟条件（可多选组合）：封锁某天/某时段（模拟生病或临时有事）增加任务工作量（模拟作业比预期更耗时）修改截止日期（模拟deadline提前）减少每日可用时间（模拟效率下降）添加临时活动（模拟突发会议/活动）点击"开始模拟"，系统生成模拟计划并与原计划对比查看风险提示：deadline风险、新增未安排任务、截止逾期等确认后可一键应用模拟方案到真实计划4.6.4 增量重规划以下操作会自动触发增量重规划：操作触发类型效果新增/修改/删除课程schedule_changed重排与课程重叠的任务完成任务task_completed_early释放时间槽，重排后续任务新增高优先级任务(priority≥4)new_high_priority_task让位给新任务修改任务deadline/duration/prioritytask_property_changed重新评估该任务安排4.6.5 课程与固定事件4.6.6 精力状态4.7 运行测试后端包含完整的pytest测试套件，验证核心算法正确性：cd CampusFlow/backend pytest tests/ -v 测试覆盖范围包括：调度算法：空闲段计算、贪心放置、可分割任务拆分推荐算法：6维评分计算、候选过滤、Top3排序重规划：7种触发条件识别、增量重排沙盘模拟：6种条件应用、对比分析、风险计算碎片时间：步行时间扣除、缓冲时间计算顺路发现：绕行成本计算、aging紧迫度五、释放资源本案例在本地开发运行，无需释放云资源。体验完成后：在后端终端按 Ctrl+C 停止FastAPI服务；在前端终端按 Ctrl+C 停止Vite开发服务器；如需清理数据库，删除 backend/campusflow.db 文件即可。六、扩展资料说明华为云码道CodeArts实战速成：https://edu.huaweicloud.com/certification/1eda08826e5349109b00b009f9f1112a华为云开发者AI训练营：https://developer.huaweicloud.com/activity/trainingcamps.html想了解更多关于FastAPI框架的可以访问：https://fastapi.tiangolo.com/" target=“_blank”>https://fastapi.tiangolo.com/想了解更多关于Vue 3的可以访问：https://vuejs.org/想了解更多关于高德地图Web服务API的可以访问：https://lbs.amap.com/api/webservice/summary想了解更多关于SQLAlchemy ORM的可以访问：https://www.sqlalchemy.org/想了解更多关于Pinia状态管理的可以访问：https://pinia.vuejs.org/

基于华为云码道（CodeArts）的双引擎股票预测系统实践源代码链接（本人基于码道智能体原创）：https://github.com/AlphaWangZY/Stock-Prediction-System-using-CodeArts/在线体验地址：http://121.36.208.71（请复制到浏览器访问）一、概述1.1 案例介绍非金融专业人士在参与股票投资时，面临信息收集困难、分析框架缺失、模型使用门槛高、风险意识薄弱四大痛点。本项目构建"规则引擎 + ML模型"双引擎预测系统，提供可解释的多维度规则打分与数据驱动的多模型ML预测，帮助用户从不同视角理解市场，避免单一方法的盲区。本案例使用华为云码道（CodeArts）代码智能体完成从需求分析、系统设计、模型训练、Web开发到华为云部署的全流程。完成案例后，您将掌握：使用码道智能体完成需求梳理、架构设计和功能模块开发；训练5种回归模型（MLP、DLinear、Ridge、RandomForest、LinearSVR）并导出ONNX用于轻量推理；构建规则引擎四维/五维打分框架，产出可解释的预测结论与交易计划；实现多模型集成推理与投票共识机制；使用FastAPI + Vue3 + ECharts构建前后端分离的金融预测Web应用；在华为云ECS上完成Nginx + Systemd生产级部署。说明：本系统预测概率上限为65%，ML模型方向准确率约48%-52%，预测结果仅供参考，不构成投资建议。1.2 适用对象有一定股票投资经验但缺乏系统分析方法的个人投资者；希望了解AI辅助决策但不会自行训练模型的技术小白；需要盘后复盘工具的散户投资者；对金融ML模型训练与部署感兴趣的高校学生。1.3 案例流程需求与设计：使用码道梳理30项功能需求，完成系统架构、API、数据结构和页面原型设计；ML模型训练：训练5种回归模型（A股+美股分别训练），导出ONNX；Web应用开发：FastAPI后端（6个Service + 5个Router）+ Vue3前端（4个页面）；华为云部署：ECS + Nginx + Systemd生产级部署；功能体验：搜索股票 → 查看K线 → 发起双引擎预测 → 查看多模型对比 → 生成报告。1.4 方案架构系统采用前后端分离三层架构：浏览器（Vue3 + ECharts + Element Plus） │ HTTP ▼ Nginx 反向代理（/ → 前端dist, /api/* → 后端8000） │ ├── 前端静态资源（dist/） │ └── FastAPI 后端（8000） ├── Stock Service：股票搜索 + 标的解析 ├── KLine Service：K线数据 + 均线计算 ├── Rule Engine：四维/五维打分 + 交易计划 + 风险提示 ├── ML Engine：5模型集成推理 + 投票共识 ├── Compare Engine：双引擎对比 + 共振/对冲信号判定 ├── Report Service：Markdown报告生成 └── News Service：关联新闻 │ ├── 腾讯财经API / 东方财富API（在线K线 + 实时行情 + 搜索） └── 本地CSV历史数据 + ONNX模型文件1.5 资源总览资源名称推荐规格用途计费说明华为云码道（CodeArts）体验版代码智能体辅助开发免费弹性云服务器 ECS2 vCPU、4 GiB、Ubuntu 22.04运行应用按需计费弹性公网 IP EIP按流量计费、5 Mbit/s浏览器访问按流量计费二、环境和资源准备2.1 前置条件已注册华为云账号并完成实名认证；本地已安装 Python 3.10+、Node.js 18+、conda（用于ML训练）；本地可使用 SSH 和 SCP/WinSCP。2.2 创建 ECS登录华为云控制台 → 弹性云服务器 ECS → 购买弹性云服务器；推荐配置：2 vCPU / 4 GiB / Ubuntu 22.04 / 40 GiB系统盘 / 按流量计费5Mbit/s带宽；记录公网IP和登录密码。2.3 配置安全组入方向规则添加：协议端口来源用途TCP220.0.0.0/0SSHTCP800.0.0.0/0浏览器访问三、通过码道分阶段搭建项目3.1 开通并进入码道登录华为开发者官网，进入华为云码道（CodeArts）代码智能体体验页面；按页面提示完成体验版开通；下载并安装支持码道的开发工具，登录同一华为云账号。3.2 需求与功能清单梳理使用码道智能体分析 requirements.md 需求文档，自动提取30项功能需求并按P0/P1/P2三级优先级分类，产出 feature-modules.md 功能模块表：P0 核心模块19项：股票搜索、K线展示、规则引擎预测、ML预测、双引擎对比、报告生成等；P1 辅助模块8项：美股搜索、时间范围选择、可视化对比图、一致性分析等；P2 可选模块3项：关联新闻、移动端适配等。3.3 系统结构设计使用码道智能体一次性完成全部设计工作，产出 docs/system-design.md：系统架构设计：三层架构（Vue3 → Nginx → FastAPI → 数据源），技术选型与理由；API接口设计：10个REST API（股票搜索/K线/规则引擎预测/ML预测/双引擎对比/新闻/报告等）；数据结构与特征设计：12维ML特征列表、Z-Score归一化方案、A股四维打分规则；前端页面原型设计：4个页面ASCII布局图、交互流程。3.4 ML模型训练使用码道智能体编写训练脚本，对A股（沪深300+中证500）和美股（S&P500+纳斯达克100）分别训练5种回归模型：模型A股 DirAccA股 IC美股 DirAcc美股 IC说明MLP48.3%-0.00345.0%-0.0053层全连接+BN+DropoutDLinear49.1%0.00451.9%0.014趋势-季节分解+线性投影Ridge48.6%-0.00645.3%0.008岭回归RandomForest48.4%-0.00045.3%0.005随机森林LinearSVR49.1%0.00143.8%-0.004线性支持向量回归注：方向准确率接近50%是金融收益率预测的典型表现，ML模型作为辅助参考，核心预测来自规则引擎。3.5 Web应用开发使用码道智能体编写完整后端和前端：后端（FastAPI）：6个Service + 5个Router，10个API端点。前端（Vue3 + Element Plus + ECharts）：4个页面视图 + API封装 + 路由配置。3.6 数据源适配与修复开发过程中发现AKShare的push2his.eastmoney.com接口被网络策略屏蔽，码道辅助完成以下重构：kline_service.py：改用腾讯财经API（优先）+ 东方财富push2his（备选）+ 本地CSV（回退）；stock_service.py：改用东方财富搜索API + 实时行情API + fallback字典；rule_engine.py、ml_engine.py：移除AKShare依赖，改用kline_service + stock_service；news_service.py：改用东方财富搜索API + 占位数据。3.7 多模型集成推理将单模型（MLP）扩展为5模型并行推理，新增：模型投票共识：统计看涨/看跌票数，计算平均预测收益率；多模型对比表格：每个模型独立展示方向、预测收益率、方向准确率、IC；DLinear序列推理：使用seq_cache缓存最近20天序列数据作为输入。四、核心技术难点与解决思路4.1 AKShare历史K线接口被网络策略屏蔽问题：AKShare底层调用push2his.eastmoney.com被屏蔽，返回连接拒绝。解决：采用"腾讯财经API（优先）→ 东方财富push2his（备选）→ 本地CSV（回退）"三级数据源策略。腾讯财经API（web.ifzq.gtimg.cn）可正常返回A股最新日K线数据，与本地历史CSV合并后K线可更新到最新交易日。4.2 ML推理特征未归一化导致预测值异常问题：ML预测返回极端值（如-225949），明显不合理。原因：训练时使用已z-score归一化的特征（mean≈0, std≈1），但推理时直接用实时行情原始值（如close=1377）作为输入，分布严重不匹配。解决：从原始CSV计算各特征的mean和std，保存为scaler_{market}.json；推理前对特征做(raw - raw_mean) / raw_std归一化。修复后预测值回归合理范围（如-0.001457，即-0.15%次日收益率）。4.3 SVM训练超时问题：RBF核SVM在77万样本上训练超时（O(n²~n³)复杂度）。解决：改用LinearSVR（线性核，O(n)复杂度），训练时间从>120s降至0.7s。4.4 DLinear序列数据内存溢出问题：构建全量序列数据（970K×60×12 float32 ≈ 2.8GB）超出内存限制。解决：三重优化：seq_len从60降至20；采样量限制20万条；只用hs300/sp500单数据集。内存从2.8GB降至约192MB。4.5 report_service维度key硬编码导致美股报告崩溃问题：report_service硬编码了A股维度key（market_env/capital_flow/technical/news），美股维度key不同（fundamental/technical/capital/sentiment/macro）导致KeyError。解决：改为动态遍历rule['dimensions']字典，兼容任意维度key，并为每个维度提供中文通俗解释。五、构建并部署应用5.1 技术栈与项目结构层次技术版本/作用前端框架Vue3 + Vite组合式API + 快速构建UI组件库Element PlusVue3生态成熟UI库图表库EChartsK线图、均线、成交量后端框架FastAPIPython异步框架，自动OpenAPI文档ML推理onnxruntime + joblibONNX（MLP/DLinear）+ pickle（Ridge/RF/SVR）数据获取requests腾讯财经API + 东方财富API反向代理Nginx前端静态 + 后端API代理运行环境Ubuntu ECS + Systemd生产级进程管理可以使用码道智能体自动完成环境配置。项目关键结构：stock-predict/ ├── backend/ │ ├── app/ │ │ ├── main.py # FastAPI入口 │ │ ├── config.py # 配置 │ │ ├── models/schemas.py # Pydantic数据模型 │ │ ├── routers/ # 5个路由模块 │ │ └── services/ # 6个业务服务 │ ├── ml/ │ │ ├── train.py # MLP/Ridge/RF/SVR训练 │ │ ├── train_dlinear.py # DLinear训练 │ │ ├── models/ # ONNX + PKL + JSON模型文件 │ │ └── seq_cache/ # DLinear序列数据缓存 │ └── requirements.txt ├── frontend/ │ ├── src/ │ │ ├── views/ # 4个页面视图 │ │ ├── api/index.js # API封装 │ │ └── router/index.js # 路由 │ ├── vite.config.js │ └── package.json ├── data/ # 历史CSV数据（hs300/zz500/sp500/nq100） ├── docs/system-design.md # 系统设计文档 ├── feature-modules.md # 功能模块表 └── dev-log.md # 开发日志5.2 关键实现解析5.2.1 规则引擎四维/五维打分A股规则引擎按四个维度量化打分，每维-2~+2分：维度权重数据来源打分逻辑大盘环境30%上证指数K线站上5日/10日均线各+1，近5日上涨+1资金行为30%实时行情涨跌幅涨幅>1%偏强+1，跌幅>1%偏弱-1技术面25%个股K线+RSI站上5日/20日均线各+1，RSI超买-1/超卖+1消息面15%占位（数据受限）默认中性0分加权总分→方向判定→概率量化（上限65%）→交易计划（入场/止损/目标/仓位）→风险提示。5.2.2 多模型集成推理与投票共识ML引擎同时运行5个模型，每个独立输出预测收益率和方向：for model_key in ["mlp", "dlinear", "ridge", "rf", "svr"]: pred_z = _run_model(model_key, market_key, features) pred_return = float(pred_z) * label_std + label_mean # 统计看涨/看跌票数 votes["bullish" if pred_return > 0 else "bearish"] += 1 投票共识：看涨票数 ≥ 看跌票数 → 共识看涨，否则看跌。平均预测收益率作为综合参考。5.2.3 三级数据源策略K线数据获取采用三级回退策略，确保在不同网络环境下都能工作：腾讯财经API（web.ifzq.gtimg.cn）：A股在线日K线，返回最新数据；东方财富push2his（push2his.eastmoney.com）：备选，部分网络环境可用；本地CSV：最终回退，包含2021-2025年A股和2019-2023年美股历史数据。在线数据与本地数据通过日期合并：在线数据补充本地数据截止日之后的新数据。5.3 部署步骤步骤1：上传项目代码使用WinSCP将项目文件夹上传到ECS的 /opt/stock-predict/ 目录（上传前删除 frontend/node_modules）。步骤2：安装系统环境apt update && apt upgrade -y apt install -y python3 python3-pip python3-venv nginx curl -fsSL https://deb.nodesource.com/setup_18.x | bash - apt install -y nodejs步骤3：配置Python后端cd /opt/stock-predict python3 -m venv venv source venv/bin/activate pip install -r backend/requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple pip install joblib -i https://pypi.tuna.tsinghua.edu.cn/simple步骤4：构建前端cd /opt/stock-predict/frontend npm config set registry https://registry.npmmirror.com npm install vite@6 --save-dev npm install npm run build步骤5：配置Nginxserver { listen 80; server_name <ECS公网IP>; location / { root /opt/stock-predict/frontend/dist; index index.html; try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://127.0.0.1:8000/api/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_read_timeout 120s; } } 步骤6：配置Systemd服务[Unit] Description=Stock Predict FastAPI After=network.target [Service] Type=simple User=root WorkingDirectory=/opt/stock-predict ExecStart=/opt/stock-predict/venv/bin/python -m uvicorn backend.app.main:app --host 127.0.0.1 --port 8000 Restart=always RestartSec=5 [Install] WantedBy=multi-user.target步骤7：修复权限并验证chmod 755 /opt /opt/stock-predict /opt/stock-predict/frontend chmod -R 755 /opt/stock-predict/frontend/dist systemctl daemon-reload systemctl enable stock-predict systemctl start stock-predict nginx -t && systemctl restart nginx浏览器访问 http://<ECS公网IP> 即可使用系统。六、功能体验6.1 股票搜索在搜索页输入股票代码（如600519）或名称关键词；选择市场类型（A股/美股）；点击搜索结果进入仪表盘页。6.2 K线图查看仪表盘页展示ECharts K线图，含开盘/收盘/最高/最低/成交量；叠加5日/10日/20日/60日均线；切换时间范围：1月/3月/6月/1年/全部。6.3 双引擎预测点击"发起预测"进入预测对比页；规则引擎：展示四维/五维打分详情（每维得分、权重、数据来源、小白解释）、加权总分、方向判定、概率、价格区间；ML模型：展示5个模型的独立预测结果（方向、预测收益率、方向准确率、IC），以及模型投票共识（看涨/看跌票数、平均收益率）；交易计划：入场价、止损价、目标价TP1/TP2、仓位、时间止损、不做条件；风险提示：3-5个风险点 + 免责声明。6.4 预测报告点击"生成完整报告"进入报告页；展示Markdown格式预测报告，含预测概要、规则引擎分析（每维详细解释）、ML模型预测、交易计划、风险提示；每个专业术语附通俗解释（如"大盘环境就像「天气」"）。七、码道使用总结7.1 使用的码道功能功能使用场景效果评价智能问答分析需求文档，提取30项功能项并分类快速梳理需求，产出模块表智能问答完成系统架构/API/数据结构/页面原型设计一次性产出完整设计文档智能问答编写ML训练脚本，优化SVM超时问题自动编写train.py，解决训练瓶颈智能问答重写5个service文件移除AKShare依赖一次性完成全部service层重构智能问答实现多模型集成推理与投票共识扩展单模型为5模型并行推理代码续写MLP模型定义与训练循环自动补全PyTorch训练代码代码续写FastAPI路由与service层代码自动补全API端点与业务逻辑dev-logger Skill全程记录开发过程自动生成结构化开发日志7.2 关键Skill使用记录A股和美股预测 Skill：是下载的基于规则进行股票预测的专门skill。dev-logger Skill：是使用码道智能体编写的skill，在需求梳理、系统设计、模型训练、服务修复等关键节点自动追加日志记录，按模板结构记录项目信息、实现内容、关键代码、技术难点和码道辅助过程。八、运行维护与故障排查8.1 常用运维命令# 查看后端状态 systemctl status stock-predict # 查看后端日志 journalctl -u stock-predict -f # 重启后端 systemctl restart stock-predict # 查看Nginx状态 systemctl status nginx # 查看端口监听 ss -lntp | grep -E ':80|:8000' 8.2 常见问题现象可能原因处理方法浏览器无法访问安全组未开放80、Nginx未启动检查安全组、systemctl status nginx502 Bad GatewayFastAPI进程未启动systemctl status stock-predict，查看日志K线数据只到2025年底腾讯财经API不可用检查网络，回退到本地CSV数据ML预测值异常特征未归一化检查scaler_*.json文件是否存在美股K线数据较旧美股在线API受限美股使用本地历史数据（截至2023-12-29）九、案例验收清单[✅️] 使用华为云码道（CodeArts）代码智能体完成需求梳理、架构设计和代码开发；[✅️] ECS、EIP和安全组配置完成；[✅️] FastAPI后端在Systemd中正常运行，Nginx为active；[✅️] 浏览器可通过ECS公网IP打开首页；[✅️] A股股票搜索和K线图可正常显示（含最新交易日数据）；[✅️] 规则引擎四维/五维打分可产出方向、概率、交易计划和风险提示；[✅️] ML模型5模型集成推理可正常输出，投票共识可显示；[✅️] 双引擎对比可展示共振/对冲/弱信号判定；[✅️] 预测报告可生成并展示Markdown内容（含术语解释）；[✅️] 预测结果包含免责声明，概率上限为65%。

一、概述1.1 案例介绍项目背景：随着城市生活节奏加快和人们对生活品质的追求，室内绿植养护已成为都市人群的热门生活方式。然而，大量植物爱好者因缺乏专业知识导致养护失败，同时缺少有效的交流渠道分享经验和解决问题。PlantCareHub 应运而生，旨在打造一个集 AI智能诊断、植物百科知识库、个性化养护日志、爱好者社区于一体的综合平台。核心价值： 降低养护门槛：通过 AI 顾问提供零门槛的专业养护指导知识系统化：500+ 植物百科，结构化知识体系养护可视化：时间轴记录植物成长，数据驱动养护决策社交化学习：连接同好，经验共享，共同成长技术定位：采用 Vue 3 + TypeScript + Vite + Pinia 现代前端技术栈，构建高性能、类型安全、可维护的 SPA 应用。初期采用纯前端 + LocalStorage 方案快速验证，为后续云端化预留扩展接口。案例技术选型：华为云码道（CodeArts）代码智能体是基于智能生成、智能问答两大核心能力构建起一套全方位、多层次的智能开发体系。在智能生成方面，它能够依据开发者输入的需求描述，准确且高效地生成高质量代码；智能问答功能则如同开发者身边的专属技术顾问。1.2 适用对象个人开发者高校学生企业开发者1.3 案例时间本案例总时长预计60分钟。1.4 案例流程  说明：本地安装华为云码道（CodeArts）代码智能体；通过码道规范驱动模式开发多体系人格测试应用。1.5 资源总览本案例预计花费0元。资源名称规格单价（元）华为云码道（CodeArts）代码智能体体验版免费二、基础环境与资源准备2.1 华为云码道安装部署本案例基于华为云码道代码智能体完成开发改造，案例开始前请按照以下两步操作开通并使用工具：2.1.1 一键开通华为云码道体验版访问此专属开通链接，免费开通华为云码道（CodeArts）代码智能体体验版，无需复杂配置：一键开通华为云码道体验版！2.1.2 AI IDE华为云码道安装部署参考案例《AI IDE华为云码道（CodeArts）代码智能体安装部署》完成Windows版AI IDE华为云码道（CodeArts）代码智能体安装部署。  三、通过码道分阶段搭建植物养护交流平台3.1 通过规范驱动模式创建需求文档首先我们进入AI IDE后点击码道对话框的 规范驱动模式(Spec-Driven Mode) ：根据 需求规格设计->实现方案创建->编码任务规划->任务执行 进行项目开发。  3.1.1 需求规格设计接着我们在码道对话框输入以下提示词，让码道进行需求规格说明书的创建。 c复制代码帮我在当前目录生成一个web应用项目；项目名称：植物养护交流平台（PlantCareHub）技术栈：Vue 3 + TypeScript + Vite + Pinia + Vue Router + SCSS核心功能：  1. AI植物养护顾问：集成智能问答系统，用户可通过文字描述或上传图片获取植物的光照需求、浇水频率（区分四季）、土壤选择、施肥周期、病虫害防治等专业养护建议。支持基于用户所在城市实时天气数据动态调整养护日历，生成月度养护计划（含浇水、施肥、修剪时间节点及异常预警）  2. 植物百科大全：提供500+种常见植物的详细知识库，包含植物名称（中英对照）、科属分类、形态特征、生长习性、养护难度等级、观赏价值、适宜环境参数（光照/温度/湿度/土壤pH值）、常见病害及防治方法。支持按名称/科属/养护难度/光照需求等多维度筛选与模糊搜索  3. 植物养护日志：用户可为每盆植物创建独立档案（含品种名称、种植日期、生长阶段、摆放位置），记录每次浇水/施肥/换盆/修剪等操作行为及时间，支持上传生长对比照片，以时间轴可视化展示植物成长历程。系统根据操作记录自动生成养护统计报表（月浇水次数、施肥频率等）  4. 社区交流互动：搭建植物爱好者互动社区，支持发帖（图文）、提问求助、经验分享、植物展示等。帖子需按主题分类（如多肉专区、月季栽培、病虫害求助、园艺DIY等），支持点赞、评论、收藏、举报。系统自动检测敏感词并触发审核流程。用户可互相关注、私信交流，基于LBS推荐同城花友和线下活动信息 5. 用户个人中心：包含我的植物园（管理所有养护日志）、我的帖子/评论、收藏夹、消息通知、成就徽章系统（根据养护记录天数/发帖活跃度等维度自动授予）、个人资料设置此时，码道会根据步骤首先创建需求规格说明书。    这时如果我们对项目有要求，可以对spec.md需求规格说明书文件进行编辑。保存过后，我们点击码道对话框的开始实现方案创建。3.1.2 实现方案设计可以看到，码道正在根据我们给出的需求规格文档设计实现方案文档。在创建完成后，我们可以在左侧找到 design.md实现方案设计文档进行查看，如果有需要调整的地方可以直接进行修改，无问题后点击 全部接受-> 开始编码任务。    3.1.3 编码任务规划在实现方案设计书创建完成后，我们可以在左侧找到 tasks.md编码任务文档进行查看，如果有需要调整的地方可以直接进行修改，无问题后点击 全部接受-> 开始任务执行。生成完毕后我们可以看到相应的任务执行顺序。   3.1.4 任务执行这时我们可以任意的去修改需求规格设计、实现方案创建、编码任务规划，在以上设计书都完成的前提下，我们可以根据码道提示进行编码任务。可以看到，码道正在进行编码任务。  当编码任务全部完成后，我们可以点开左侧文件进行查看，如无问题，在码道对话框点击 全部接受。四、启动项目并反馈可能出现的问题在编码任务完成后，我们可以根据启动说明或在码道对话框输入以下提示词启动项目： c复制代码启动项目此时码道会提示我们如何启动，根据指引进行项目启动即可。注意：在启动项目中或项目运行中可能会出现一些错误，遇到问题的时候我们通过自然语言描述，或者截图的方式把错误直接反馈给码道，让码道帮我们解决就可以了。当我们成功启动后可以看到刚刚创建好的应用了！为这个植物养护交流平台是Agent自动生成的，每次提问设计生成的代码及最后的运行结果均存在出入，开发者可根据自己的需求，逐步给智能体发送Prompt进行微调直到生成自己想要的结果。若想体验与案例一样的结果，请下载源码（https://github.com/YL12345678901/plantcarehub）至本地运行。演示视频也在仓库中，可供参考。五、反馈改进建议如您在案例实操过程中遇到问题或有改进建议，可以到开发者论坛评论区反馈即可，我们会及时响应处理，谢谢！ 

本案例将引导构建一个完整的“大黑山羽毛球运动协会管理系统”。该系统旨在解决协会日常运营中的核心痛点，包括9片场地的管理与预定、50名选手的信息维护以及羽毛球比赛的智能排程与成绩统计。

基于华为云码道（CodeArts）的碳足迹与生命周期评价智能系统一、概述1.1 案例介绍碳足迹核算与生命周期评价（LCA）是量化产品全生命周期环境负荷、支撑绿色低碳转型的核心方法。传统工具往往存在清单提取低效、专业门槛高、结果难落地等问题。本案例基于华为云码道（CodeArts） AI 代码智能体，采用 SDD 规格驱动 + Vibe-Coding 开发范式，从零构建一套碳足迹与生命周期评价系统，并以水泥生产为典型行业示例进行落地演示（如“两磨一烧”工艺边界、清单阶段与 IEII 核算参数）。系统采用前后端分离架构（Flask + Vue3），内置 IEII（综合环境负荷指数）核算引擎，支持异构清单文档的大模型智能解析，并通过 LangGraph Agent 实现自然语言驱动的全流程任务调度。完整源码与演示视频见 GitCode 仓库：cid:link_4。1.2 适用对象工业界环境相关从业者（碳足迹核算、LCA 评价、绿色低碳管理等）高校学生（ AI 开发实训）1.3 案例时间直接使用仓库源码：完成资源准备、部署和功能验证，预计需要 60～90 分钟。通过码道手动复现：从 SDD 规格驱动到分阶段 Vibe-Coding 完整走通，预计需要 4～5 小时。1.4 案例流程 前期准备（环境 + 码道 + 大模型 API） ↓ 需求分析 / Skill 规格文档（spec / design / tasks） ↓ 基于码道智能体生成后端（认证、清单解析、LCA 计算等） ↓ 基于码道智能体生成前端及页面美化 ↓ LangGraph Agent：自然语言驱动全流程任务调度说明：前期准备：配置大模型 API Key，准备 PostgreSQL、Python、Node.js 等运行环境；登录华为开发者空间，创建云开发环境，安装并进入码道（CodeArts）AI IDE 的 Vibe-Coding 模式；需求分析 / Skill 文档：使用码道官方 SDD 系列 Skill（如 creating-sdd-directory、managing-spec-document、managing-design-document、managing-tasks-document），完成需求规格、总体设计与任务分解文档；基于智能体生成后端：按业务模块向码道输入 Prompt，分阶段生成认证、LCA 核算、清单智能解析、参数配置等后端能力；基于智能体生成前端及美化：使用码道智能体（可结合 frontend-design Skill）生成项目管理、清单录入、影响评价、对比分析等页面，并完成界面美化与交互打磨；LangGraph Agent 全流程调度：封装建项、清单解析、IEII 计算等工具，通过自然语言对话驱动 LCA 端到端任务链式执行，降低专业操作门槛。1.5 资源总览资源名称规格说明费用参考华为云码道（CodeArts）代码智能体专业版（含 6000 万 Token/月/席位）139 元/月/席位华为云 MaaS 大模型服务 API通过华为云 ModelArts Studio（MaaS）调用 LLM，用于清单解析与 Agent 推理按实际 Token 用量计费（可领取免费额度或使用包月套餐）PostgreSQL 数据库自建，存储项目与清单数据免费说明：码道通用体验版可免费使用，但每月仅 500 万 Token 额度，建议按需升级专业版以保证开发体验。LLM API 推荐使用华为云 MaaS 领取的模型服务（如 DeepSeek、GLM 等），或按实际环境配置可用的 API Key / 模型名称 / 接口地址。PostgreSQL 可在开发环境中直接自建，无需额外付费。二、环境和资源准备2.1 准备华为云码道（CodeArts）AI IDE登录华为开发者空间，进入码道（CodeArts）产品页，开通代码智能体（专业版）服务，获取在线代码生成与迭代能力。参考案例《AI IDE华为云码道（CodeArts）代码智能体安装部署》，完成 Windows 版华为云码道（CodeArts）代码智能体 AI IDE 安装部署，进入码道代码智能体。2.2 领取华为云 MaaS 平台大模型 Tokens登录华为开发者空间，参考案例《华为云MaaS平台大模型Tokens领取使用指导》中的“二、领取 MaaS 平台大模型 Tokens”章节内容，领取 Tokens 代金券并开通模型服务，获取 API 地址、模型名称和 API Key。将获取到的密钥写入后续 backend/.env。2.3 准备本地 / 云开发基础软件本案例技术栈如下：类别选型前端Vue 3 + Vite + ECharts + Vue Router后端Flask 3 + Flask-SQLAlchemy + Flask-CORS数据库PostgreSQL认证JWT + bcrypt + RBAC（admin / normal）AgentLangChain StructuredTool + LangGraph 状态编排大模型通义千问等（DashScope / 华为云 MaaS 兼容接入）文档解析openpyxl / pandas / python-docx / PyMuPDF 等请确保环境满足：Python 3.10+Node.js 18+PostgreSQL 14.2（创建数据库 lca）Redis，用于 Agent 对话检查点持久化；不可用时可降级为内存模式也可在码道中使用 dev-env-setup 专业技能一键安装 Python / Node.js 并校验版本：使用 dev-env-setup 专业技能搭建本地开发环境，安装 Python 3.10+、Node.js 18+、pip 包管理器，配置环境变量并输出版本验证结果。三、基于码道的 AI 开发过程本章聚焦本项目的 AI Coding 开发过程：先明确业务场景与需求边界，再用码道官方 Skill 完成 SDD 规格设计，最后按业务阶段用 Prompt / Vibe-Coding 生成前后端代码。3.1 业务场景与需求概要3.1.1 业务场景与用户角色本平台面向碳足迹与生命周期评价业务，支撑从数据录入、核算执行到结果分析、Agent 辅助调度的端到端工作流；演示数据与工艺边界以水泥“两磨一烧”为例。基于业务权限与操作职责，系统划分为两类核心角色——普通用户与系统管理员。管理员默认继承普通用户的全部业务操作权限，并在系统运维与参数配置层面扩展能力：维度普通用户系统管理员权限范围与功能边界聚焦 LCA 核心业务流：（1）项目全流程管理：创建项目、界定系统边界、录入/解析清单数据、IEII 核算、结果对比；（2）AI 助手对话：通过多轮交互调用 Agent 完成文件上传、数据提取、计算调度等自动化任务继承普通用户全部权限，并扩展：（1）用户管理：角色权限分配、操作日志监控；（2）核算参数配置：物质当量系数、环境类别权重、生产步骤与折算比矩阵等 IEII 基准数据典型使用场景企业环境评估人员执行日常 LCA 评价、工艺数据填报、核算结果分析平台运维人员或领域专家进行底层参数配置、系统配置优化及数据权限管控上述角色通过统一鉴权实现数据视图隔离：普通用户仅可访问本人创建的项目与对话历史；管理员具备全局配置权限，但不可越权修改他人业务数据。3.1.2 功能性需求（1）用户认证与权限管理：支持邮箱密码注册与验证码快捷登录；采用 JWT 无状态会话（有效期 24 小时）；基于 RBAC 区分普通用户与管理员的数据视图与操作边界。（2）LCA 项目全生命周期管理：遵循“项目建档 → 目标与范围界定 → 清单录入 → 执行计算 → 结果分析/对比”流程。范围界定支持水泥品种、基准年、工艺路线、系统边界及评价指标的结构化配置；清单录入依据系统边界动态生成各阶段产出/消耗/排放填报；内置 IEII 引擎，仅对用户勾选指标执行特征化、归一化与加权求和，并支持项目快速复制。（3）大模型辅助清单解析：支持 PDF/Excel/Word 等异构文档上传后由大模型抽取结构化清单，前端预览确认后再入库。（4）Agent 交互与任务调度：基于 LangGraph 状态机实现多轮对话智能体；封装清单解析、项目创建、IEII 计算等工具，完成多步链式编排；可用 Redis 持久化对话记忆；强制结构化响应协议（消息/表格等 blocks），保证前端稳定渲染。（5）系统后台管理：管理员可管理用户账号（查看、禁用等），并动态维护环境类别权重、物质当量系数、生产步骤及折算比矩阵。3.2 使用码道完成 SDD 规格驱动设计本案例强调“先设计、后开发”。请在码道对话框中依次执行以下指令，生成 SDD 文档（生成结果可参考仓库中 .codeartsdoer/specs/lca_system/）。3.2.1 初始化 SDD 目录使用 creating-sdd-directory 技能，基于以下需求创建 SDD 项目目录：基于华为云码道的碳足迹与生命周期评价系统（以水泥生产为示例场景），后端 Flask + PostgreSQL，前端 Vue3 + Vite + ECharts，包含 LCA 核算与评估模块、智能体交互与编排模块、系统运维与参数配置模块。生成后的典型目录：.codeartsdoer/specs/lca_system/ ├── spec.md # 需求规格说明书 ├── design.md # 总设计文档 └── tasks.md # 开发任务分解清单 3.2.2 生成需求规格（spec.md）使用 managing-spec-document 技能，为碳足迹与生命周期评价系统生成 spec.md，核心需求包括：用户认证与权限管理（JWT + RBAC，admin/normal 两级角色）LCA 项目全生命周期管理（项目建档→范围界定→清单录入→IEII 计算→结果对比）大模型辅助异构文档智能解析（PDF/Excel/Word→结构化清单）智能体 Agent 对话交互（LangGraph 工具编排，自然语言驱动任务调度）系统参数配置（环境类型权重、物质当量系数、生产步骤与折算比）生成完成后，在码道中打开 .codeartsdoer/specs/lca_system/spec.md，界面示例如下：3.2.3 生成总体设计（design.md）使用 managing-design-document 技能，基于 spec.md 生成 design.md，包含：前后端分离分层架构（表现层 / 业务逻辑层 / 数据访问层 / 外部集成层）PostgreSQL 数据模型（Users、UserLog、UploadedFile、Project、Step2Record、Step3Record、LcaResult、CategoriesWeight、MaterialsWeight、ProductionStep、ConversionRatio、Conversation 等）RESTful API 设计（/auth/、/lca/、/api/agent/、/api/file/、/api/lca-params/、/user/、/admin/）IEII 计算引擎（特征化→归一化→加权求和）Agent 工具编排（StructuredTool + LangGraph 状态机）生成完成后，打开 design.md，界面示例如下：3.2.4 生成任务分解（tasks.md）使用 managing-tasks-document 技能，基于 design.md 生成 tasks.md，按开发阶段拆解任务，标注优先级（P0 核心 / P1 扩展）和依赖关系。生成完成后，打开 tasks.md，界面示例如下：3.3 使用码道分阶段 Vibe-Coding 开发以下 Prompt 可直接输入码道，按阶段生成代码。实际仓库已按该路径落地，可对照验证或在空白工程中复现。3.3.1 阶段一：项目骨架与认证（后端起步）使用 Flask + Vue3 搭建碳足迹与生命周期评价系统，并以水泥生产为示例业务场景。后端 Flask + SQLAlchemy + PostgreSQL，前端 Vue3 + Vite + ECharts。要求：后端结构：app.py、config.py、models.py；按功能域划分 auth/、calculate/、agent/、file/、user/、lca_params/；定义 Users、UserLog、UploadedFile、Project、Step2Record、Step3Record、LcaResult、CategoriesWeight、MaterialsWeight、ProductionStep、ConversionRatio、Conversation 等 ORM 模型；前端侧边栏导航 + 路由守卫（登录 / 管理员权限）；JWT 认证：邮箱密码注册登录、验证码登录、退出，Token 有效期 24 小时；CORS 允许前端 localhost:5173 访问后端 localhost:5000。3.3.2 阶段二：用户管理与个人中心实现 RBAC 用户管理、操作日志审计、个人中心：管理员用户列表（分页/搜索/筛选）、启用禁用与权限变更、日志查询导出；个人中心支持资料编辑、改密、头像上传；SMTP 发送 6 位验证码（5 分钟有效）；写操作写入 UserLog。3.3.3 阶段三：LCA 核算主流程（ISO 14040/44）以水泥生产为示例，实现 LCA 四阶段流程（示例工艺可按“两磨一烧”配置系统边界与生产步骤）：Step1 项目管理（创建/编辑/删除/复制，状态：空项目→范围界定→清单录入→已计算）；Step2 研究目标与范围（以水泥为例：品种规格、基准年、工艺、系统边界、评价指标 ADP/GWP/AP/HTP/POCP/EP/LU）；Step3 清单录入（按阶段维护产出/消耗/排放 JSON）；Step4 IEII 计算：产出量倒推 → 单位强度 → 特征化 → 归一化 → 加权求和；电力按 0.5703 kg CO₂/kWh 折算；仅计算用户勾选指标。3.3.4 阶段四：大模型清单智能解析支持 PDF/Excel/Word/CSV/图片上传；调用大模型按阶段解析产出/消耗/排放并返回结构化 JSON；前端先预览可编辑，用户确认后再写入 Step3；文件状态 uploaded→parsed→stored。3.3.5 阶段五：Agent 智能助手基于 LangGraph 实现 LCA Agent：对话 CRUD；工具包括 upload_file、create_lca_project、list_lca_projects、parse_inventory_file_for_project、calculate_lca_for_project；结构化响应协议（blocks 消息块/表格块等）；前端对话页解析 blocks 渲染。3.3.6 阶段六：前端生成、美化与对比分析使用 frontend-design 技能生成/优化项目管理、清单录入、影响评价、对比分析等页面；管理员维护环境类型权重与物质当量系数（ECharts 可视化）；使用 data-analysis 技能，以水泥示例数据校验关键阶段（如熟料煅烧）IEII 是否显著偏高、GWP 占比是否符合行业经验。本项目 AI 开发过程中使用的码道 Skill ：阶段Skill作用设计creating-sdd-directory初始化 SDD 目录设计managing-spec-document生成 spec.md设计managing-design-document生成 design.md设计managing-tasks-document生成 tasks.md前端frontend-design生成对比分析、影响评价等高质页面验证data-analysis分析校验 LCA 计算结果四、项目结构与关键代码解析本章说明码道生成后的工程结构，并对认证、IEII 计算、清单解析、Agent 编排等关键能力给出源码 + 分析。4.1 项目结构说明CemLCA/ ├── backend/ # Flask 后端 │ ├── app.py # 入口与 Blueprint 注册 │ ├── config.py # 数据库 / JWT / 邮件 / 模型密钥配置 │ ├── models.py # SQLAlchemy ORM 模型 │ ├── requirements.txt │ ├── auth/ # 认证（注册/登录/验证码） │ ├── calculate/ # LCA 项目、Step2/3、IEII 计算、清单解析 │ ├── agent/ # Agent 对话、工具编排 │ ├── file/ # 文件上传与管理 │ ├── user/ # 个人中心 / 管理员接口 │ ├── lca_params/ # IEII 参数配置 API │ └── utils/ # Token、邮件、响应封装、LLM 工具等 ├── frontend/ # Vue3 前端 │ ├── package.json │ └── src/ │ ├── views/ │ │ ├── lca/ # 项目管理 / 清单 / 影响评价 / 对比 │ │ ├── agent/ # Agent 对话页 │ │ ├── system/ # 用户管理 / 参数配置 │ │ └── user/ # 登录注册 │ ├── components/ # Sidebar 等 │ ├── router/index.js │ └── services/api.js ├── .codeartsdoer/specs/lca_system/ # 码道 SDD 规格文档 ├── chatfile/ # Agent 上传文件目录 └── README.md4.2 关键代码讲解4.2.1 后端入口与模块注册backend/app.py 优先加载 .env，再注册各业务 Blueprint，并在启动时建表、开启 CORS：# backend/app.py（节选） app = Flask(__name__) app.config.from_object(config) app.register_blueprint(auth_bp, url_prefix='/auth') app.register_blueprint(calculate_route) app.register_blueprint(agent_route) app.register_blueprint(file_route) app.register_blueprint(admin_bp) app.register_blueprint(user_bp) app.register_blueprint(lca_params_route) db.init_app(app) with app.app_context(): db.create_all() CORS(app, resources={r"/*": {"origins": ["http://localhost:5173", "http://127.0.0.1:5173"]}}) 分析：按功能域拆 Blueprint，便于码道按模块增量生成；calculate 与 agent 解耦后，同一套 IEII / 清单解析逻辑既可被页面调用，也可被 Agent 工具复用。4.2.2 核心数据模型与 PostgreSQL 存储PostgreSQL 作为核心关系型存储底座，集中管理用户档案、项目元数据、LCA 核算基准参数与评价结果等强事务型业务数据。数据访问层基于 Flask-SQLAlchemy ORM 实现标准化访问；概念设计遵循第三范式，按业务域划分实体，依托主外键约束保障一致性。LCA 核算与评估模块的核心数据表如下：表名表用途projects项目主表，项目归属与进度追踪容器，含用户隔离、示例项目标识等step2_record研究目标与范围表，存储水泥品种、基准年、系统边界和评价指标等元数据step3_record生命周期清单表，以 JSON 结构存储各生产阶段的产出、消耗和排放数据lca_result计算结果表，每条记录对应一个阶段×一种产品，存储单位强度、IEII 与指标分解production_steps生产步骤配置表，定义工艺步骤名称、顺序、默认产出物和启用状态conversion_ratios产出物折算比表，供逆向倒推各步真实产出量materials_weight物质当量系数表，存储各物质在七个环境类别下的特征化系数categories_weight环境影响类型权重表，含 IEII 加权系数和归一化基准系统逻辑数据模型图（ER / 表关系）如下：核心业务表示例如下：# backend/models.py（节选） class Project(db.Model): __tablename__ = "projects" id = db.Column(db.Integer, primary_key=True, autoincrement=True) user_email = db.Column(db.String(50), db.ForeignKey("users.email", ondelete="SET NULL")) name = db.Column(db.String(100), nullable=False) type = db.Column(db.String(50), nullable=True) intro = db.Column(db.Text, nullable=True) is_example = db.Column(db.Boolean, nullable=False, server_default=text("false")) class Step2Record(db.Model): __tablename__ = "step2_record" project_id = db.Column(db.Integer, db.ForeignKey("projects.id", ondelete="CASCADE"), unique=True) cement_spec = db.Column(db.String(100), nullable=True) system_border = db.Column(db.JSON, nullable=True) # 系统边界多选 appraise_index = db.Column(db.JSON, nullable=True) # 评价指标多选 class Step3Record(db.Model): __tablename__ = "step3_record" project_id = db.Column(db.Integer, db.ForeignKey("projects.id", ondelete="CASCADE"), unique=True) phases = db.Column(db.JSON, nullable=True) # 各阶段产出/消耗/排放 分析：Step2/Step3 与 Project 一对一，删除项目时级联清理；phases 用 JSON 承载多阶段异构清单，适配水泥示例中可变系统边界，也方便大模型解析结果整包写入。4.2.3 JWT 登录认证# backend/auth/view.py（节选） @auth_bp.route('/login', methods=['POST']) def login(): data = request.get_json(silent=True) or {} email = data.get('email', '').strip() password = data.get('password', '') res = PgSQL.hasUser(email, password) if res.status != 200 or not res.data: record_log(email=email, operation=LOGIN, detail="登录失败：邮箱或密码不正确", result="failure") return jsonify(Error(message='邮箱或密码不正确').to_dict()), 401 user_data = PgSQL.getUserByEmail(email).data if user_data.get('state') == UserState.disabled.value: return jsonify(Warn(message='您的账号被禁用，请联系管理员开放后重试').to_dict()), 403 auth = user_data.get('auth') or 'normal' if hasattr(auth, 'value'): auth = auth.value token = Token.generate_auth_token(user_data.get('id'), user_email=email, auth=auth) return jsonify(Success(data={ 'token': token, 'user_id': user_data.get('id'), 'username': user_data.get('name'), 'email': email, 'auth': auth, }, message='登录成功！').to_dict()) 分析：登录成功后签发 JWT，payload 携带 user_id 与 auth，支撑后续 @token_required / @admin_required；失败与成功均写 UserLog，满足运维审计需求。4.2.4 IEII 计算引擎（特征化 → 归一化 → 加权）计算主逻辑在 backend/calculate/calculate_service.py，同时被 Flask 路由与 Agent 工具复用。LCA 评价过程与计算链路如下：整体遵循：产出量倒推 → 单位强度 → 特征化 → 归一化 → 加权求和 → 写入 LcaResult（1）产出量倒推：默认末步产出 1 t，按折算比矩阵由后向前倒推。以水泥三阶段为例：水泥制备 1 t → 熟料煅烧约 0.726 t → 生料粉磨约 1.118 t（前一步骤产出 = 后一步骤产出 × 折算比）。（2）单位强度：消耗/排放总量 ÷ 该步真实产出量，得到每功能单位强度；电力按 0.5703 kg CO₂/kWh 折算为 CO₂；石油类燃料可将运输距离纳入修正。（3）特征化 / 归一化 / 加权：# backend/calculate/calculate_service.py（节选：归一化 + 加权） normalized_impacts = {} for category in impacts.keys(): category_data = next( (cw for cw in category_weights if cw.get("category_name") == category), None, ) total_equivalent = category_data.get("total_equivalent") if category_data else 0.0 normalized_impacts[category] = ( impacts[category] / total_equivalent if total_equivalent else 0.0 ) weighted_sum = 0.0 for category, value in normalized_impacts.items(): category_weight = next( (cw.get("weight", 0.0) for cw in category_weights if cw.get("category_name") == category), 0.0, ) weighted_sum += value * category_weight ieii = weighted_sum # 单位强度 IEII ieii_total = weighted_sum * actual_product_amount # 总 IEII 分析：特征化把异构清单统一到七类环境影响（ADP/GWP/AP/HTP/POCP/EP/LU）；归一化消除量纲差异；加权得到可横向对比的单一指数。仅 Step2 勾选的指标子集参与全过程，保证闭运算。4.2.5 大模型清单智能解析# backend/calculate/inventory_extract.py（节选） def extract_inventory_json_from_file(file_path: str, api_key: Optional[str] = None) -> dict: api_key = api_key or os.getenv("API_KEY") if not api_key: raise ValueError("未配置 API_KEY，无法解析文件") client = OpenAI( api_key=api_key, base_url="https://dashscope.aliyuncs.com/compatible-mode/v1", timeout=180.0, ) file_object = client.files.create(file=path.open("rb"), purpose="file-extract") completion = client.chat.completions.create( model="qwen-long-2025-01-25", messages=[ {"role": "system", "content": _inventory_schema_prompt()}, {"role": "system", "content": f"fileid://{file_object.id}"}, {"role": "user", "content": "请根据上述要求，从文件中提取各阶段的产出、消耗与排放，只输出 JSON。"}, ], temperature=0, stream=True, ) full_content = "" for chunk in completion: if chunk.choices and chunk.choices[0].delta.content: full_content += chunk.choices[0].delta.content or "" return _parse_json_from_llm(full_content) 分析：通过兼容 OpenAI 的接口上传文件，并用 Schema Prompt 约束输出结构；temperature=0 降低随机性。业务上采用「解析预览 → 用户确认 → 写入 Step3」两阶段，避免 LLM 偶发误差直接污染正式清单。文件解析提取与处理流程如下：4.2.6 Agent 工具编排与运行Agent 采用工具驱动架构：不自行“编造”业务结果，而是理解意图后调用专项工具，再聚合为结构化 blocks 返回。执行流程架构如下：设计要点：领域专业化：系统提示词限定能力边界（LCA 建项 / 解析 / 计算），降低幻觉；工具编排：经 LangGraph create_agent 注册 StructuredTool，由模型决定调用顺序与参数；结构化响应：强制 ResponseFormat，前端按 message / table 等块类型渲染；状态化对话：优先 Redis Checkpoint，失败则降级内存，维持多轮上下文。当前注册的核心工具：工具名称功能描述upload_file上传文件并返回服务器路径create_lca_project新建 LCA 项目list_lca_projects列出当前用户可见项目parse_inventory_file_for_project解析清单并写入指定项目 Step3calculate_lca_for_project执行 IEII 计算并返回结果摘要工具注册（backend/agent/tools.py）：# backend/agent/tools.py（节选） calculate_lca_for_project = StructuredTool.from_function( func=_calculate_lca_for_project, name="calculate_lca_for_project", description="""执行指定项目的 LCA 计算（复用系统已实现的 IEII 计算算法）...""", parameters={ "type": "object", "properties": { "project_id": {"type": "integer", "description": "项目管理中的整数项目 ID"} }, "required": ["project_id"], }, ) def get_tools(context: Context) -> list: global _ctx _ctx = context return [ upload_file, create_lca_project, list_lca_projects, parse_inventory_file_for_project, calculate_lca_for_project, ] Agent 运行（backend/agent/agent.py）：# backend/agent/agent.py（节选） def run_agent(message: str, user_id: int = 1, thread_id: str = None, is_first_message: bool = False): config = {"configurable": {"thread_id": thread_id or f"user_{user_id}"}} ctx = Context(user_id=user_id) with get_checkpointer() as checkpointer: agent = create_agent( model=get_llm(), system_prompt=SYSTEM_PROMPT, tools=get_tools(ctx), checkpointer=checkpointer, response_format=ResponseFormat, # 强制结构化 blocks 输出 ) result = agent.invoke( {"messages": [{"role": "user", "content": message}]}, config=config, ) final_response = _parse_structured_response(result.get("messages", []), invoke_result=result) return {"messages": result.get("messages", []), "response": final_response, ...} 结构化响应块常用类型：类型主要字段用途messagecontent, style（default/success/warning/error）带样式的文本提示tableheader, rows, title, actions表格与操作按钮filefile_id, file_name, file_path文件信息展示cardtitle, content, actions复杂信息容器分析：这是本案例亮点——自然语言驱动“上传 → 建项 → 解析 → 计算”链式任务。4.2.7 前端路由守卫// frontend/src/router/index.js（节选） router.beforeEach((to, from, next) => { const token = localStorage.getItem('token') const userAuth = localStorage.getItem('auth') if (to.meta.requiresAuth && !token) { loginPromptEmitter.emit(to.fullPath) return } if (to.meta.requiresAdmin && userAuth !== 'admin') { next('/lca/projects') return } next() }) 分析：LCA 业务页与 Agent 页设置 requiresAuth；用户管理、参数配置另加 requiresAdmin，与后端 RBAC 前后端双重校验。五、配置运行与系统功能演示本章完成环境配置与前后端启动，并按业务模块讲解系统功能。5.1 配置环境并运行调试5.1.1 配置后端cd backend python -m venv venv # Windows PowerShell .\venv\Scripts\activate # Linux / macOS # source venv/bin/activate pip install -r requirements.txt1）在 PostgreSQL 中创建数据库：CREATE DATABASE "Cemlca"; 2）复制并编辑环境变量文件：cp .env.example .env在 .env 中配置：API_KEY=你的大模型API密钥3）按实际环境修改 backend/config.py 中的数据库连接，例如：SQLALCHEMY_DATABASE_URI = "postgresql://用户名:密码@127.0.0.1:5432/Cemlca" 4）启动后端：python app.py默认监听：http://127.0.0.1:5000。可用 curl 验证：curl http://127.0.0.1:5000/api/ping期望返回：{"message": "Flask 后端已就绪", "status": "ok"} 5.1.2 配置前端cd frontend npm install npm run dev默认访问：http://localhost:5173。5.2 LCA 核算与评估功能演示LCA 核算与评估是系统核心业务，按四步推进：步骤名称说明Step1项目创建建立评价项目，记录名称、类型、简介，作为后续数据归属容器Step2研究目标与范围确定水泥品种、基准年、工艺、系统边界、评价指标Step3生命周期清单按阶段录入产出/消耗/排放；支持手工录入与大模型解析Step4影响评价计算执行特征化→归一化→加权，得到各阶段 IEII 与指标分解完成后可进行结果对比分析。5.2.1 登录与注册打开前端地址，完成注册或登录（支持邮箱密码 / 验证码登录）。登录成功后 Token 存于本地，后续请求自动携带。5.2.2 项目管理（Step1）进入 项目管理 页：列表默认展示当前用户项目；支持卡片 / 列表两种视图；每个项目显示四节点进度条（创建→范围→清单→计算），已完成节点显示 √，当前节点高亮，未到达节点灰色不可点；状态逻辑简述：step2 必填齐全 → phases 非空 → 存在 LcaResult，据此映射进度 1～4；新建项目：名称为必填，同一用户下不可重名；创建后为空项目状态；复制项目：可复制基本信息，可选复制 Step2/Step3，不复制计算结果；普通用户仅可操作本人项目与示例项目；示例项目禁止写操作。5.2.3 研究目标与范围（Step2）在进度条进入 Step2，填写：水泥品种、基准年、生产工艺、系统边界（多选）、评价指标（多选）。系统边界选项来自生产步骤配置；评价指标来自环境类型权重表（七项：ADP/GWP/AP/HTP/POCP/EP/LU）。仅勾选指标参与后续 IEII 计算。保存采用 upsert。5.2.4 生命周期清单录入（Step3）按 Step2 系统边界动态生成阶段分组；每组含产出表、消耗表、排放表，支持行内增删。两种录入方式：手工录入：编辑后保存，JSON 写入 step3_record.phases；大模型辅助解析：上传 PDF/Excel/Word/CSV/图片 → 大模型按 Schema 抽取 → 前端预览可改 → 确认后入库（两阶段设计，避免脏数据）。5.2.5 影响评价计算（Step4）点击执行计算后，后端完成倒推产出量、单位强度、特征化、归一化与加权，结果写入 lca_result。前端影响评价页：表格按阶段×产品展示 IEII 与七项指标分解，可筛选；ECharts 柱状图对比各阶段 IEII；堆叠柱状图展示指标贡献占比。5.2.6 结果对比分析对已完成计算的项目，可从按生产步骤、按产品等维度查看 IEII 与七项指标对比：按步骤 IEII 条形图 / 七项指标分组柱状图；按产品 IEII 饼图与堆叠柱状图；消耗/排放构成分析。5.3 智能体交互功能演示Agent 页采用左侧会话列表 + 右侧对话区。用户可新建/切换/删除会话，发送文本并附带文件；响应按 blocks 渲染消息、表格等。话术示例（可附带清单文件）：帮我根据附件创建一个LCA项目，名称叫水泥test1[文件路径:D:\桌面\华为\CemLCA\chatfile\2024.11.xlsx]Agent 依次调用建项、解析、计算等工具，并返回结构化结果（如 LCA 结果明细表格）。5.4 系统运维与参数配置演示5.4.1 用户管理与操作日志（管理员）管理员进入用户管理：分页/搜索/按角色状态筛选；启用禁用；查看并筛选操作日志，可导出。认证为 JWT（24 小时）+ @token_required / @admin_required 栈式叠加。5.4.2 个人中心普通用户可编辑姓名/电话/单位，修改密码（需旧密码），上传/删除头像；查看个人日志与项目统计仪表盘。5.4.3 LCA 计算参数配置（管理员）四类参数可视化维护：参数类型说明前端呈现生产步骤工序名称、顺序、默认产出物、启用状态可排序列表折算比矩阵步骤间物料折算关系热力图等环境类型权重类别权重 + 归一化基准（七类）饼图 / 列表物质当量系数物质在各环境类别下的系数（JSON）科学计数法列表 / 图表5.5 系统能力小结模块能力要点LCA 核算与评估Step1～4 全流程、IEII 自动化计算、结果可视化与对比分析大模型清单解析异构文档 → 结构化清单，预览确认后入库智能体编排自然语言驱动建项、解析、计算等链式任务系统运维JWT+RBAC、操作日志、个人中心、LCA 参数可视化配置六、释放资源6.1 停止本地 / 云开发环境中的服务在运行前后端的终端中按 Ctrl + C 停止进程；如使用 Python 虚拟环境，可 deactivate。6.2 释放云开发环境与按量资源进入华为开发者空间，停止或删除本案例创建的云开发环境容器；若额外购买了 ECS、EIP、CCE 等按量资源，进入对应控制台，勾选实例后执行 更多 > 删除，并勾选释放公网 IP 与数据盘，避免持续计费；大模型 Tokens 套餐按实际剩余额度管理，体验结束可不继续调用推理接口。七、扩展资料说明华为开发者空间主页：cid:link_3华为云码道（CodeArts）：https://codearts.huaweicloud.com/华为云 MaaS Tokens 领取指导：《华为云MaaS平台大模型Tokens领取使用指导》LCA 国际标准：ISO 14040 / ISO 14044（生命周期评价原则、框架与要求）Flask 官方文档：https://flask.palletsprojects.com/Vue 3 官方文档：https://vuejs.org/LangGraph 文档：https://langchain-ai.github.io/langgraph/

一、项目简介本次实战我使用华为云码道代码智能体完成了 CloudForum 校园论坛管理系统。项目围绕“会员交流、版主自治、平台治理”三个角色展开，不仅实现了登录、发帖、跟帖、删帖、置顶等论坛基础功能，还补充了版块级权限隔离、本地敏感词 DFA、华为云文本内容审核、人工复核、黑名单、软删除恢复和审计日志，形成了可运行、可管理、可追溯的内容治理闭环。代码仓库：CampusCloudForum（GitCode）前端：Vue 3 + TypeScript + Vite + Element Plus + Pinia + Vue Router + Axios后端：Java 17 + Spring Boot 3 + Spring Security + JWT + MyBatis-Plus数据库与运行：MySQL 8 + Docker Compose + NginxCloudForum 首页二、原始任务与完成情况原题为：论坛管理。实现论坛的版主管理、版块管理、内容管理。需要登陆进入论坛，可以发帖、跟帖和删帖以及置顶等功能。同时能够对敏感词汇进行过滤，拉黑某些会员。我将原题拆成了可验收的功能项，并为每项建立“页面操作 + 后端权限 + 自动化测试”的证据闭环：原题要求实现方式对应证据登录进入论坛JWT 无状态认证、BCrypt 密码、注册、退出、修改密码、禁用账号拦截登录页、认证测试版主管理ADMIN 分配或移除版主；MODERATOR 只能管理被分配版块版块管理页、版主范围页、跨版块 403 测试版块管理创建、编辑、启用、停用、排序、版主列表版块管理页、管理接口测试内容管理帖子/回复分页管理、审核、锁定、删除、恢复审核页、帖子管理页、回复管理页发帖登录会员选择版块并发布，发布前完成黑名单和敏感词审核发帖接口与集成测试跟帖帖子详情页回复，锁帖后禁止回复帖子详情页、回复测试删帖作者或对应管理者可删除；默认软删除，可恢复删除/恢复测试、审计日志置顶ADMIN 或对应版主可置顶/取消置顶，置顶内容优先排序帖子管理页、排序测试敏感词过滤DFA 支持 REJECT、REVIEW、REPLACE，词库动态重载敏感词页、审核队列、四类审核测试拉黑会员全局/版块、永久/限时、解除拉黑；发帖和回复前后端拦截黑名单页、拉黑权限与拦截测试三、码道代码智能体开发实录码道项目与原始任务任务规划与阶段拆分Skill / MCP 使用记录自动化验证我还在仓库中沉淀了项目级规则、阶段 Prompt 和专项 Skill，使智能体后续修改都遵循“读代码 → 实现最小闭环 → 测试 → 文档”的流程，减少前后端契约漂移与权限遗漏。四、系统架构与业务闭环整体架构保持前后端分离，本地容器化运行时由 Nginx 提供统一入口：会员 / 版主 / 管理员 │ ▼ Nginx + Vue 3 Web │ RESTful JSON ▼ Spring Security + JWT │ ├── 论坛业务服务 ── MyBatis-Plus ── MySQL 8 ├── 版块级 RBAC ── 403 越权拦截 ├── 本地敏感词 DFA ── PASS / REVIEW / BLOCK ├── 华为云 Moderation SDK ── 异常时安全降级 └── 审计日志 ── 操作者 / 原因 / 前后状态发帖和回复走统一治理链路：提交内容 → 校验是否被全局或当前版块拉黑 → 本地 DFA 过滤（REJECT / REVIEW / REPLACE） → 按配置调用华为云文本内容审核 → 统一得到 PASS / REVIEW / BLOCK → PASS 公开、REVIEW 进入人工队列、BLOCK 拦截 → 云审核异常时降级到本地结果并记录日志这种设计解决了两个真实问题：一是减轻版主逐条审查的压力；二是避免外部审核服务短暂不可用时整个论坛无法发帖。五、逐项功能实现1. 登录进入论坛系统支持注册、登录、退出和修改密码。登录成功后前端携带 JWT 访问需要授权的接口；密码使用 BCrypt 存储。公开浏览与登录后操作边界由 Spring Security 后端统一控制，匿名发帖返回 401，角色越权返回 403。登录页面注册页面关键安全配置使用精确的数字详情路径，避免把 /api/topics/mine 一类私有接口误判成公开接口：.authorizeHttpRequests(auth -> auth .requestMatchers("/api/auth/**").permitAll() .requestMatchers("/actuator/health").permitAll() .requestMatchers("/api/boards/all").permitAll() .requestMatchers(new RegexRequestMatcher("^/api/boards/\\d+$", "GET")).permitAll() .requestMatchers(HttpMethod.GET, "/api/topics").permitAll() .requestMatchers(new RegexRequestMatcher("^/api/topics/\\d+$", "GET")).permitAll() .requestMatchers(HttpMethod.GET, "/api/comments").permitAll() .anyRequest().authenticated()) 2. 版主管理管理员可以在版块管理页为每个版块分配或移除版主。后端不只判断用户是不是 MODERATOR，还会继续查询“用户—版块”的关联关系；因此版主即使手工构造请求，也不能管理其他版块。核心权限逻辑如下：public boolean canManageBoard(Long userId, Long boardId) { User user = requireUser(userId); if (user.getRole() == UserRole.ADMIN) return true; if (user.getRole() != UserRole.MODERATOR || boardId == null) return false; return boardModeratorMapper.selectCount( new LambdaQueryWrapper<BoardModerator>() .eq(BoardModerator::getUserId, userId) .eq(BoardModerator::getBoardId, boardId) ) > 0; } public void requireBoardManager(Long userId, Long boardId) { if (!canManageBoard(userId, boardId)) { throw BusinessException.forbidden("无权管理该版块"); } } ADMIN 获得全局管理范围，MODERATOR 只获得被分配的版块 ID，MEMBER 没有后台管理权限。帖子、回复、审核、黑名单和审计列表都复用这套后端判定。3. 版块管理系统实现了版块的创建、编辑、启用、停用、排序和版主配置。停用版块不能继续发帖；公开端和管理端使用不同的数据接口，管理接口通过方法级鉴权限制到 ADMIN 或 MODERATOR，并在服务层进一步做版块范围校验。@PostMapping @PreAuthorize("hasRole('ADMIN')") public ApiResponse<BoardDTO> createBoard( @Valid @RequestBody CreateBoardRequest request, @AuthenticationPrincipal UserPrincipal principal) { return ApiResponse.success(boardService.createBoard(request, principal.getId())); } @PutMapping("/{id}") @PreAuthorize("hasAnyRole('ADMIN','MODERATOR')") public ApiResponse<BoardDTO> updateBoard( @PathVariable Long id, @Valid @RequestBody UpdateBoardRequest request, @AuthenticationPrincipal UserPrincipal principal) { return ApiResponse.success(boardService.updateBoard(id, request, principal.getId())); } 4. 发帖与跟帖登录会员可以选择启用中的版块发布帖子，并在帖子详情页回复。发帖与回复都会先检查黑名单，再进入内容审核。帖子支持点赞、浏览量、回复数和最后活跃时间，回复可选填图片地址；锁帖后不允许继续回复。前端通过类型化 API 调用后端，页面不使用 mock 数据冒充功能：export function createTopic(data: { boardId: number title: string content: string }) { return api.post<any, ApiResponse<TopicInfo>>('/topics', data) } export function createComment(data: { topicId: number content: string imageUrl?: string }) { return api.post<any, ApiResponse<CommentInfo>>('/comments', data) } 公开帖子列表在后端固定过滤为 PUBLISHED + PASS，待审、被拒绝或已删除内容不会因修改前端参数而泄露：wrapper.eq(Topic::getStatus, TopicStatus.PUBLISHED); wrapper.eq(Topic::getReviewStatus, ReviewStatus.PASS); wrapper.orderByDesc(Topic::getIsTop); 5. 删帖、恢复、置顶与锁帖作者可以删除自己的帖子，对应版主和管理员可以执行管理删除。删除不是直接清除数据库记录，而是记录 DELETED、删除人、时间和原因；后续可由合法操作者恢复。置顶、取消置顶、锁定、解锁、删除和恢复都会写入审计日志。软删除和审计的关键实现：public void deleteTopic(Long id, Long operatorId, String reason) { Topic topic = topicMapper.selectById(id); if (topic == null) throw BusinessException.notFound("帖子不存在"); checkOwnerOrManager(topic, operatorId); String before = topic.getStatus().name(); topic.setStatus(TopicStatus.DELETED); topic.setDeletedAt(LocalDateTime.now()); topic.setDeletedBy(operatorId); topic.setDeleteReason(reason); topicMapper.updateById(topic); auditLogService.log(operatorId, AuditAction.TOPIC_DELETED, "TOPIC", id, topic.getBoardId(), reason, before, "DELETED", null, true, null); } 置顶操作先做版块权限校验，再更新状态并记录审计：authorizationService.requireBoardManager(operatorId, topic.getBoardId()); topic.setIsTop(true); topicMapper.updateById(topic); auditLogService.log(operatorId, AuditAction.TOPIC_TOPPED, "TOPIC", id, topic.getBoardId(), reason, "false", "true", null, true, null); 6. 内容管理与人工复核管理端提供帖子管理、回复管理和内容审核队列。REVIEW 内容默认不公开，管理员或对应版主可以查看命中信息并选择通过或拒绝；系统会检查内容当前状态，避免重复审批。审核队列同样受版块权限约束：管理员查看全部，版主查询条件被限定到自己负责的版块。审批结果会同步回帖子或回复，并写入审计日志。7. 敏感词过滤与华为云审核敏感词管理支持新增、编辑、启用、停用和动态重载。每个词可以配置不同动作：REJECT：直接判为 BLOCK，阻止公开；REVIEW：进入人工审核队列；REPLACE：将命中内容替换后继续处理；未命中：本地结果为 PASS。系统先执行本地 DFA，再按配置调用华为云官方 Moderation Java SDK，并将不同来源统一映射为 PASS / REVIEW / BLOCK。云服务超时或异常时，系统降级到本地审核结果，同时保存 isDegraded 和脱敏错误摘要，不输出 AK/SK。public ModerationDecision moderateContent( String content, String contentType, Long targetId, Long boardId) { DfaResult dfaResult = matchWithDfa(content); ReviewStatus localStatus = determineLocalStatus(dfaResult.matchedWords()); saveModerationRecord(targetId, parseTargetType(contentType), boardId, ModerationSource.LOCAL, localStatus, null, String.join(",", dfaResult.matchedWords()), null, false, null); if (localStatus == ReviewStatus.BLOCK || !huaweiCloudEnabled) { return new ModerationDecision(localStatus, dfaResult.maskedText()); } try { CloudDecision cloud = callCloudApi(content, contentType); return new ModerationDecision( strictest(localStatus, cloud.status()), dfaResult.maskedText()); } catch (Exception e) { String summary = sanitizeError(e); saveModerationRecord(targetId, parseTargetType(contentType), boardId, ModerationSource.HUAWEI_CLOUD, localStatus, null, String.join(",", dfaResult.matchedWords()), null, true, summary); return new ModerationDecision(localStatus, dfaResult.maskedText()); } } 8. 拉黑会员系统支持两类作用域和两类时效：管理员可以创建全局黑名单；管理员或对应版主可以创建版块黑名单；记录既可以永久生效，也可以设置结束时间。解除拉黑同样需要权限校验并记录原因。发帖和回复前会同时匹配“全局黑名单”与“当前版块黑名单”，并校验记录仍处于有效期内：wrapper.eq(BlacklistRecord::getUserId, userId) .eq(BlacklistRecord::getStatus, BlacklistStatus.ACTIVE) .and(w -> w.eq(BlacklistRecord::getScope, BlacklistScope.GLOBAL) .or(w2 -> w2.eq(BlacklistRecord::getScope, BlacklistScope.BOARD) .eq(BlacklistRecord::getBoardId, boardId))) .and(w -> w.eq(BlacklistRecord::getIsPermanent, true) .or(w2 -> w2.isNull(BlacklistRecord::getEndTime) .or(w3 -> w3.gt(BlacklistRecord::getEndTime, LocalDateTime.now())))); 命中黑名单时后端返回 403 和清晰原因；即使绕过前端按钮也无法发帖或跟帖。9. 审计日志与管理驾驶舱除了原题要求，我增加了审计日志和管理驾驶舱。置顶、锁帖、删除、恢复、拉黑、解除拉黑和人工审核等关键动作都会记录操作者、目标、所属版块、原因、前后状态与时间，便于复盘管理行为和处理争议。六、创新与易用性双层内容治理：本地 DFA 提供低延迟、可控的第一道防线，华为云审核扩展识别范围，人工复核处理模糊内容。故障降级：外部云审核不可用时不阻断整个论坛，改用本地结果并留痕，兼顾可用性和可追溯性。细粒度版主权限：不是简单的“后台角色”，而是把管理权精确限制到负责版块，跨版块请求明确返回 HTTP 403。可恢复内容治理：管理删除采用软删除，保留原因和责任人，并提供恢复能力，降低误删风险。角色化操作体验：会员专注浏览与互动，版主只看到负责范围，管理员获得全局驾驶舱，减少无关菜单和误操作。七、码道新能力与华为云技术使用使用项目级规则与阶段 Prompt 约束技术栈、权限模型、内容治理和质量门禁；建立 forum-sdd、forum-moderation、forum-quality-gate 三个项目 Skill，分别服务于需求设计、内容治理与发布前验证；使用浏览器控制能力对 ADMIN、MODERATOR 等真实页面进行验收和截图，避免以 mock 页面冒充后端功能；接入华为云 Moderation Java SDK，保留 requestId、风险标签、分段结果和降级状态；同时提供 Vue Web 应用、REST 后台服务、MySQL 数据库与 Docker Compose/Nginx 本地容器化运行形态。八、测试与验证结果项目不是只完成页面展示，而是执行了完整质量门禁：验证项结果后端集成测试34/34 通过，0 failure、0 error、0 skipped前端类型检查与生产构建通过Docker Compose 配置与镜像构建通过全新 MySQL 数据卷启动MySQL、backend、frontend 均 healthy浏览器真实验收13 张页面证据，关键页面控制台错误为 0权限专项验证匿名私有接口 401，会员后台接口 403，版主跨版块 403验证命令如下：# 后端测试 cd backend mvn clean test # 前端类型检查和生产构建 cd ../frontend npm run build # 生产形态验证 cd .. docker compose config --quiet docker compose build docker compose up -d docker compose ps curl --fail http://localhost/actuator/health34 项后端测试覆盖：三种角色认证、错误密码、禁用账号、匿名访问、发帖、回复、点赞幂等、置顶排序、锁帖、软删除恢复、敏感词 REJECT/REVIEW/REPLACE、词库动态重载、人工审核、全局/版块黑名单、版主跨版块越权、审计和驾驶舱等关键场景。九、本地运行与容器化验证本地开发# 后端：dev 配置使用 H2，便于本地复现 git clone cid:link_0.git cd CampusCloudForum/backend mvn spring-boot:run -Dspring-boot.run.profiles=dev # 另开终端启动前端 cd CampusCloudForum/frontend npm install npm run dev访问 http://localhost:5173，后端健康检查为 http://localhost:8080/actuator/health。Docker Compose 本地容器化运行cp .env.example .env # 填写本地容器运行所需的 MySQL 密码和 JWT_SECRET docker compose config --quiet docker compose up -d --build curl --fail http://localhost/actuator/health如需在本地自行验证华为云内容审核，可通过环境变量启用；凭证不在代码中硬编码，也不提交到仓库：HUAWEI_CLOUD_MODERATION_ENABLED=true HUAWEI_CLOUD_REGION=cn-north-4 HUAWEI_CLOUD_PROJECT_ID=<project-id> HUAWEI_CLOUD_AK=<ak> HUAWEI_CLOUD_SK=<sk> HUAWEI_CLOUD_MODERATION_TIMEOUT_MS=3000 十、逐项对应评分项项目成果与证据创新易用双层审核、云故障降级、人工复核、版块级权限、软删除与角色化页面功能完备原题 10 个功能点全部闭环；34 项测试、13 张真实页面截图技术能力码道 Prompt/Skill/MCP、华为云 Moderation SDK、Web + REST + Docker/Nginx 多形态文档完整性需求、架构、数据库、API、测试、本地运行、码道过程、验收清单、案例文档和证据目录完整十一、项目成果总结这次实战让我从“实现一个能发帖的页面”，进一步走到了“构建一个权限正确、内容安全、操作可追溯、能够容器化运行的论坛系统”。CloudForum 已在本地完成核心功能、自动化测试、真实页面验收和完整容器验证；仓库中同时保留了需求、架构、API、测试和运行文档，方便评审复现。

在线体验地址：http://113.44.103.96（请复制到浏览器访问）项目源码仓库：cid:link_5一、概述1.1 案例介绍在软件研发和云上运维过程中，遗留代码重构依赖人工经验，故障日志分析又常常跨越应用、容器和函数等多个层次，定位慢、重复劳动多。CodeVerse-Ops 将华为云 MaaS 大模型能力接入研发运维流程，提供智能代码重构、云原生日志诊断、代码质量评分、上下文追问、历史任务分析和代码片段管理等能力。本案例将使用华为云 MaaS 的 DeepSeek-V4-Flash 模型作为推理引擎，基于 Next.js、Prisma 和 SQLite 构建全栈应用，并通过 PM2 与 Nginx 部署到弹性云服务器 ECS。完成案例后，您将掌握：使用 OpenAI 兼容接口调用华为云 MaaS 模型；使用华为云码道的 Spec-Driven 模式，将需求依次转化为规格、设计、任务和代码；理解 Server-Sent Events（SSE）任务事件，并在 AI 追问场景中实现流式回复；将模型能力组合为代码重构、日志根因分析和质量评分工作流；使用 Prisma 与 SQLite 管理任务、对话和收藏数据，并理解质量评分的数据模型；在 Ubuntu ECS 上完成 Node.js 应用的一键部署、验证和运维。说明：模型生成内容可能存在偏差。重构代码和运维修复建议应经过人工审查，并在测试环境验证后再应用到生产环境。1.2 适用对象企业开发者及 DevOps、SRE、云原生运维人员；希望学习大模型应用开发的个人开发者；具备 JavaScript/TypeScript、Linux 命令行基础的高校学生。1.3 案例时间直接使用仓库源码完成资源准备、部署和功能验证，预计需要 60～90 分钟。如通过码道分阶段搭建 CodeVerse-Ops，建议预留 2～3 小时，具体时间取决于代码生成、人工评审、依赖下载和构建速度。1.4 案例流程图 1-1 CodeVerse-Ops 案例流程说明：开通 MaaS：登录华为开发者空间，开通 DeepSeek-V4-Flash 预置服务，创建并妥善保存 API Key；创建 ECS：购买 Ubuntu ECS，绑定弹性公网 IP，并在安全组中开放 SSH 和 HTTP 访问；配置并上传：填写 MaaS API Key、基础地址和数据库连接，将项目部署包上传至 ECS；一键部署：运行部署脚本，自动安装依赖，完成数据库迁移、项目构建、PM2 启动和 Nginx 配置；功能体验：依次验证代码重构、批量处理、日志诊断、质量评分、AI 对话、仪表盘和收藏库；验证并释放：检查应用、代理和数据库状态；体验结束后删除 ECS、EIP 及不再使用的模型凭据。流程说明：图 1-1 展示的是“使用现有源码部署体验”的主流程。如需从需求开始复现项目开发过程，请在获取源码和正式部署前完成第三章的码道 Spec-Driven 四阶段实践。1.5 方案架构图 1-2 CodeVerse-Ops 系统运行架构核心调用链如下：浏览器提交代码或日志，Next.js API 创建任务并写入 SQLite；当前版本的提交接口同步调用华为云 MaaS，解析结果并将任务更新为 COMPLETED；浏览器收到 taskId 后连接任务 SSE 接口，通常直接收到 complete 事件并展示结果；用户继续追问时，服务端通过 thinking、result_chunk、complete 或 error 事件逐段推送模型回复；任务结果、对话记录和收藏内容持久化到 SQLite；质量评分接口在收到 taskId 时可持久化评分；仪表盘聚合任务数据，展示近 30 天趋势、任务分布，并预留质量趋势展示。1.6 资源总览本案例使用按需资源。以 1 小时体验、少量公网流量和少量模型调用估算，费用通常由 ECS 实例费用、EIP 流量费用和 MaaS Token 费用组成。云服务价格会因区域、规格和活动变化，最终以购买页面及账单为准。资源名称推荐规格用途计费说明华为开发者空间已完成实名认证的账号进入开发平台和实战案例免费MaaS 模型即服务DeepSeek-V4-Flash代码重构、日志分析、质量评分和对话按实际 Token 用量计费，可优先使用已领取权益弹性云服务器 ECS2 vCPU、4 GiB、Ubuntu 22.04、40 GiB 系统盘运行 CodeVerse-Ops推荐按需计费，价格以控制台为准弹性公网 IP EIP按流量计费、5 Mbit/sSSH 登录和浏览器访问按流量计费，价格以控制台为准费用提示：体验完成后请及时释放 ECS 和 EIP。仅关闭操作系统不会停止 ECS 计费。二、环境和资源准备2.1 前置条件开始前请确认：已注册华为云账号并完成实名认证；账号余额或代金券足以支付本案例资源；本地可使用 SSH 和 SCP。Windows 10/11 可在 PowerShell 中执行 ssh -V 和 scp 检查；已获得完整的 codeverse-ops 项目目录；不要将 API Key 写入公开仓库、聊天记录或截图。2.2 开通 MaaS 模型并创建 API Key登录华为开发者空间。如尚未领取模型权益，可参考《华为云 MaaS 平台大模型 Tokens 领取使用指导》完成领取。然后按以下步骤开通模型：进入 MaaS 控制台 > 模型推理 > 在线推理 > 预置服务；找到 DeepSeek-V4-Flash，单击 开通服务；服务开通后单击 调用说明，确认模型参数为 deepseek-v4-flash；在调用说明页面创建 API Key，并立即复制到安全位置。API Key 通常只在创建时完整显示；记录 OpenAI 兼容接口地址。中国大陆站的 OpenAI 兼容接口当前仅支持 西南-贵阳一，该区域的完整地址为：https://api.modelarts-maas.com/openai/v1/chat/completions本项目会自动在基础地址后追加 /v1/chat/completions，因此项目配置中应填写：https://api.modelarts-maas.com/openai中国香港站应以控制台“调用说明”显示的地址为准，常见基础地址为：https://api-ap-southeast-1.modelarts-maas.com/openai重要：模型服务、API Key 和调用地址必须属于同一区域，并以控制台“调用说明”为准。不要填写完整的 /v1/chat/completions 地址，否则项目会重复拼接路径；不要使用 https://api.deepseek.com，该地址不是华为云 MaaS 服务地址。Linux、macOS 或 ECS 可使用以下命令验证 API Key：export MAAS_API_KEY="<你的MaaS API Key>" curl -sS "https://api.modelarts-maas.com/openai/v1/chat/completions" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${MAAS_API_KEY}" \ -d '{ "model": "deepseek-v4-flash", "messages": [{"role": "user", "content": "请回复：连接成功"}], "max_tokens": 64 }' 响应中出现 choices 和模型回复即表示调用成功。若返回 401 或 403，请检查 API Key、模型开通状态和区域是否一致。Windows PowerShell 使用以下命令：$env:MAAS_API_KEY = "<你的MaaS API Key>" $headers = @{ "Content-Type" = "application/json" "Authorization" = "Bearer $env:MAAS_API_KEY" } $body = @{ model = "deepseek-v4-flash" messages = @(@{ role = "user"; content = "请回复：连接成功" }) max_tokens = 64 } | ConvertTo-Json -Depth 4 Invoke-RestMethod ` -Uri "https://api.modelarts-maas.com/openai/v1/chat/completions" ` -Method Post ` -Headers $headers ` -Body $body2.3 创建 ECS登录华为云控制台，进入 服务列表 > 计算 > 弹性云服务器 ECS，单击 购买弹性云服务器。图 2-1 选择 ECS 规格、镜像、磁盘和公网访问配置推荐配置如下：配置项推荐值说明计费模式按需计费便于体验结束后及时释放区域与账号和网络规划一致购买后不可直接更换CPU 架构x86与常用 Node.js 依赖兼容规格2 vCPU、4 GiB低于 4 GiB 可能在 next build 时内存不足镜像Ubuntu 22.04 Server 64bit部署脚本使用 apt-get系统盘40 GiB用于系统、依赖、构建产物和 SQLiteEIP现在购买用于 SSH 和 Web 访问带宽计费按流量计费，5 Mbit/s适合短时体验登录方式密钥对或强密码密钥对安全性更高购买完成后，在 ECS 详情页记录：ECS 公网 IP：后文以 <ECS_IP> 表示；登录用户名：本案例部署脚本固定使用 /root 并以 root 用户配置 PM2，因此应选择支持 root 登录的 Ubuntu 公共镜像；密钥文件路径或登录密码。图 2-2 ECS 创建完成并处于运行中说明：截图中的实例名称、IP、价格和区域仅为操作示例，请以实际控制台页面为准。2.4 配置安全组进入 ECS 详情 > 安全组 > 配置规则 > 入方向规则，添加以下规则：协议端口来源用途TCP22本机公网 IP/32SSH 和 SCPTCP80本机公网 IP/32；公开体验时可临时使用 0.0.0.0/0浏览器访问应用图 2-3 配置 ECS 安全组入方向规则安全建议：不要将 22 端口长期对全网开放。生产环境还应配置 HTTPS、Web 应用防火墙、身份认证和访问审计。本案例应用本身未实现用户登录，不应直接承载敏感代码或生产日志。2.5 准备项目环境变量记录从 MaaS 控制台获取的 API Key 和基础地址。为避免凭据进入压缩包，本案例将在代码上传 ECS 后创建 .env.production，文件内容如下：# 华为云 MaaS API Key HUAWEI_MAAS_API_KEY=<你的MaaS API Key> # 仅填写基础地址，不包含 /v1/chat/completions HUAWEI_MAAS_BASE_URL=https://api.modelarts-maas.com/openai # Prisma 会相对 prisma/schema.prisma 解析该路径 DATABASE_URL=file:../dev.db配置要求：HUAWEI_MAAS_API_KEY 不要添加多余空格或中文引号；HUAWEI_MAAS_BASE_URL 末尾有无 / 均可，客户端会移除末尾斜杠；DATABASE_URL 保持为 file:../dev.db，使 Prisma CLI 和应用运行时使用项目根目录下同一个数据库；.env.production 含敏感信息，不得提交到公开代码仓库或打入部署包；项目已通过 .gitignore 排除 .env.production；提交前仍应使用 git status 确认该文件未被暂存；部署脚本不会输出环境变量内容，终端日志中不应出现 API Key。2.6 获取案例源码通过 Git 下载案例源码：git clone cid:link_5.git codeverse-ops cd codeverse-ops仓库地址：CodeVerse-Ops（GitCode）【本帖子开头有】。下载后确认目录中至少包含：codeverse-ops/ ├── package.json ├── package-lock.json ├── scripts/deploy-ecs.sh ├── prisma/ └── src/检查点：执行 git status 能正常显示仓库状态，且 package.json、scripts/deploy-ecs.sh、prisma/ 和 src/ 均存在。三、通过码道分阶段搭建 CodeVerse-Ops本模块参考华为开发者空间案例中心的码道实践组织方式，结合 CodeVerse-Ops 的实际开发记录，演示如何使用华为云码道（CodeArts）代码智能体，以 Spec-Driven 模式将复杂需求依次转化为需求规格、技术设计、任务清单和可运行代码。说明：码道界面、模型列表和按钮位置可能随版本更新而变化，请以实际产品页面为准。生成代码必须经过人工审查、构建测试和安全检查；不要在对话、截图或提交记录中粘贴 API Key、密码等敏感信息。3.1 开通并进入码道登录华为开发者官网，进入华为云码道（CodeArts）代码智能体体验页面；按页面提示完成体验版开通；下载并安装支持码道的开发工具，登录同一华为云账号；打开码道 Agent Space 或 IDE 右侧智能体面板，确认可以选择 氛围编程（Vibe-Coding） 和 规范开发（Spec-Driven）。图 3-1 开通华为云码道代码智能体体验版图 3-2 进入码道 Agent Space图 3-3 在 IDE 中打开码道代码智能体3.2 创建项目并选择 Spec-Driven 模式新建空工作区，在智能体面板选择 规范开发（Spec-Driven）。首次输入应描述业务目标、技术栈、模型服务、核心功能和交付要求，避免只输入“帮我做一个网站”等宽泛指令。可使用以下需求作为起始提示词：请使用 Next.js 14、TypeScript、Tailwind CSS、Prisma 和 SQLite 构建 CodeVerse-Ops。应用接入华为云 MaaS 的 DeepSeek-V4-Flash， 提供单文件/批量代码重构、CCE/FunctionGraph 日志诊断、代码质量评分、 上下文对话、任务仪表盘和代码片段收藏功能。请采用 Spec-Driven 流程， 先生成需求规格，再生成技术设计和任务清单，经确认后分阶段实现。图 3-4 选择 Spec-Driven 模式并提交项目目标Spec-Driven 流程包含四个阶段：需求规格设计：明确目标、边界、用户故事和验收标准；实现方案创建：确定架构、数据模型、接口和部署方案；编码任务规划：将设计拆分为可追踪、可验证的任务；任务执行：按依赖顺序生成代码，并持续构建验证。3.3 第一阶段：生成并评审 spec.md码道首先将自然语言需求整理为 spec.md。评审时重点检查：是否覆盖代码重构、日志诊断、任务状态、模型调用和数据持久化；是否明确“不负责自动修改生产代码、不直接执行模型生成命令”等安全边界；每个核心能力是否具有可验证的验收标准；模型名称、接口兼容方式和部署目标是否与项目实际一致。图 3-5 第一阶段完成需求规格设计若规格有遗漏，先在对话中提出修改要求，确认 spec.md 后再进入设计阶段。不要让智能体在需求边界未确定时直接批量生成代码。3.4 第二阶段：生成并评审 design.mddesign.md 应把需求落实为可实现的技术方案。本项目重点确认：Next.js App Router 同时承载页面和 API；Prisma/SQLite 数据模型覆盖任务、日志、对话、评分和收藏；MaaS 客户端统一处理鉴权、超时、重试及流式响应；首轮任务与 AI 对话的 SSE 行为描述准确；ECS、PM2、Nginx 和容器化部署路径清晰；API Key 仅通过环境变量注入，不进入源码、镜像和日志。图 3-6 第二阶段完成实现方案设计3.5 第三阶段：生成并评审 tasks.md码道根据规格和设计生成 tasks.md，把工作拆分为初始化、数据模型、MaaS 客户端、任务状态、核心 API、前端页面和部署验证等任务。评审任务清单时应确保：每项任务都能回溯到 spec.md 和 design.md；任务依赖顺序正确，可并行项和串行项明确；每项任务包含完成条件，而不只是文件名；构建、数据库迁移、接口验证和安全检查被列入任务。图 3-7 第三阶段完成编码任务规划3.6 第四阶段：按任务清单执行确认任务清单后进入执行阶段。码道会读取规格和设计，按依赖关系创建文件、安装依赖并实现功能。建议采用“小批次执行—查看变更—运行验证—继续下一批”的节奏：先完成项目初始化、环境变量声明和 Prisma Schema；再实现 MaaS 客户端、任务状态和后端 API；然后实现重构、诊断、仪表盘、收藏等页面；最后补充 Dockerfile、ECS/CCE 部署文件和操作文档；每批变更后查看差异，拒绝与规格无关的修改。图 3-8 码道开始执行初始化与配置任务图 3-9 码道继续实现后端接口和前端页面图 3-10 任务执行阶段完成3.7 本地运行与阶段验收智能体完成首轮实现后，在项目目录执行：npm install npx prisma generate npx prisma migrate deploy npm run dev浏览器访问 http://localhost:3000，先验证页面路由和基本交互，再使用脱敏的测试代码与测试日志验证 MaaS 调用。首个可运行版本可能只具备代码重构和日志诊断，应按 tasks.md 的验收条件逐项检查，而不是仅以“页面能打开”作为完成标准。图 3-11 首个本地可运行版本的代码重构页面图 3-12 本地验证日志诊断功能3.8 模型接入的原型记录与正式配置项目早期曾使用 DeepSeek 官方 API 验证 OpenAI 兼容调用链，以下两张图仅用于说明原型演进，不是本案例的最终配置步骤。图 3-13 早期原型的 API Key 创建记录图 3-14 早期原型的环境变量配置正式案例已经切换到华为云 MaaS。请严格按照 2.2 和 2.5 节配置 HUAWEI_MAAS_API_KEY 与 https://api.modelarts-maas.com/openai，不要照抄历史截图中的 https://api.deepseek.com；截图中的凭据已失效或脱敏。3.9 迭代优化与上下文管理首轮功能完成后，可继续让码道基于实际测试结果迭代，但每次指令应说明问题、预期行为、影响范围和验证方式。本项目的后续迭代包括主题系统、命令面板、仪表盘、收藏库、批量重构、上下文对话以及 ECS 部署加固。图 3-15 基于功能差距分析继续迭代图 3-16 依据新增需求升级功能版本长任务会持续占用上下文。阶段验收后可使用会话压缩保留目标、约束、关键文件和未完成任务，再继续下一轮开发。压缩前应确认摘要未包含 API Key、登录密码等敏感信息。图 3-17 使用会话压缩管理长周期开发上下文完成本模块后，项目应通过 npm run build，数据库迁移可执行，核心页面可访问，且所有环境变量和部署步骤与后续章节一致。四、构建并部署 CodeVerse-Ops 应用4.1 技术栈与项目结构主要技术栈如下：层次技术版本/作用Web 框架Next.js14.2.35，App Router 全栈应用前端React、TypeScript、Tailwind CSSReact 18、TypeScript 5、Tailwind CSS 3.4编辑器CodeMirror 6代码输入、语法高亮和只读结果展示图表Recharts仪表盘与五维质量雷达图数据访问Prisma5.22.0，模型定义、迁移和查询数据库SQLite保存任务、日志、对话、评分和收藏模型服务华为云 MaaSDeepSeek-V4-Flash、OpenAI 兼容接口运行环境Node.js、PM2、NginxNode.js 20、进程守护、反向代理项目关键结构：codeverse-ops/ ├── prisma/ │ ├── schema.prisma # 7 个数据模型 │ └── migrations/ # 数据库迁移 ├── src/ │ ├── app/ │ │ ├── page.tsx # 首页 │ │ ├── refactor/page.tsx # 单文件/批量代码重构 │ │ ├── ops/diagnose/page.tsx # CCE、FunctionGraph 日志诊断 │ │ ├── dashboard/page.tsx # 任务统计与趋势 │ │ ├── snippets/page.tsx # 代码片段收藏库 │ │ └── api/ # 重构、诊断、评分、对话等 API │ ├── components/ # 编辑器、对比、图表、命令面板等组件 │ ├── hooks/ # SSE、主题等 React Hooks │ ├── lib/ │ │ ├── huawei-maas.ts # MaaS 客户端、重试和超时控制 │ │ ├── prisma.ts # Prisma 单例 │ │ ├── sse-client.ts # SSE 消息与响应头 │ │ ├── task-state.ts # 任务状态 │ │ ├── conversation-manager.ts # 30 分钟内存上下文 │ │ └── templates.ts # 代码与日志示例模板 │ └── types/ # API、模板和 SSE 类型 ├── .env.example # 环境变量示例 ├── .env.production # 生产配置，需自行创建 ├── scripts/ │ ├── deploy-ecs.sh # ECS 一键部署脚本 │ └── build-image.sh # SWR 镜像构建脚本 ├── deploy/ │ └── cce-deployment.yaml # CCE 部署清单 ├── Dockerfile # 容器化构建文件 ├── package.json # 项目依赖与命令 └── package-lock.json # 锁定依赖版本Prisma 数据模型职责：模型作用Task保存重构或日志诊断任务及状态CloudLog保存待分析日志及分析状态Snippet保存收藏的原始代码、重构代码和说明BatchGroup管理批量重构的总数和完成进度Conversation关联任务与对话Message持久化用户和助手消息QualityScore在评分接口收到 taskId 时，保存安全性、可维护性、性能、可读性和类型安全评分4.2 关键实现解析4.2.1 MaaS 客户端src/lib/huawei-maas.ts 负责：从环境变量读取 API Key 和基础地址；拼接 /v1/chat/completions；使用 Authorization: Bearer <API_KEY> 鉴权；固定调用 deepseek-v4-flash；同步调用最多尝试 3 次，即首次失败后最多重试 2 次，退避时间依次为 1 秒、2 秒；单次调用超时时间为 120 秒；支持普通 JSON 响应和流式响应。核心请求结构如下：const response = await fetch(`${baseUrl}/v1/chat/completions`, { method: "POST", headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}`, }, body: JSON.stringify({ model: "deepseek-v4-flash", messages, temperature: 0.7, max_tokens: 4096, stream: true, }), }); 4.2.2 任务接口与 SSE 事件代码重构和日志诊断采用“同步任务提交 + SSE 结果回传”的两阶段请求：图 4-1 CodeVerse-Ops 首轮任务与对话请求流程图中编号说明：提交代码或日志：浏览器将用户输入发送到对应的 Next.js API；创建任务：服务端在 SQLite 中创建状态为 PENDING 的任务；进入处理状态：开始推理前，将任务状态更新为 PROCESSING；调用模型：服务端通过 OpenAI 兼容接口同步调用华为云 MaaS；返回完整结果：MaaS 返回完整的代码重构或日志分析结果；保存结果：服务端解析模型输出，将结果写入 SQLite，并将任务标记为 COMPLETED；响应提交请求：Next.js API 向浏览器返回 taskId 和完整结果；连接任务 SSE：浏览器使用 EventSource 连接任务 SSE 接口；返回完成事件：SSE 接口查询到已完成任务后，发送 complete 事件。用户继续对话时，应用则通过 SSE 逐段返回模型回复。实现边界：页面上的“正在连接 AI 服务”和 SSE 状态组件已经具备流式展示结构，但首轮重构、诊断请求的等待主要发生在同步 POST 阶段，当前版本不会逐 Token 展示首轮模型输出。对话追问采用真实流式响应。4.2.3 提示词与结构化结果应用通过系统提示词限定模型角色，并要求模型返回 JSON：代码重构：返回 refactoredCode 和 explanation；日志诊断：返回 analysis 和 patchSuggestion；质量评分：返回五个 0～100 的维度分数及 details。服务端会从模型输出中提取 JSON。若模型未严格返回 JSON，部分接口会回退为原始文本。因此，生成结果仍需人工复核。4.3 打包项目在本地打开项目父目录执行。部署包明确排除环境变量、依赖、构建产物、数据库和 Git 元数据：tar -czf codeverse-ops-deploy.tar.gz \ --exclude=codeverse-ops/node_modules \ --exclude=codeverse-ops/.next \ --exclude=codeverse-ops/dev.db \ --exclude=codeverse-ops/.env \ --exclude=codeverse-ops/.env.production \ --exclude=codeverse-ops/.git \ codeverse-ops/Windows PowerShell 使用反引号续行：tar -czf codeverse-ops-deploy.tar.gz ` --exclude=codeverse-ops/node_modules ` --exclude=codeverse-ops/.next ` --exclude=codeverse-ops/dev.db ` --exclude=codeverse-ops/.env ` --exclude=codeverse-ops/.env.production ` --exclude=codeverse-ops/.git ` codeverse-ops/ 打包后检查文件和压缩包内容：Get-Item .\codeverse-ops-deploy.tar.gz tar -tzf .\codeverse-ops-deploy.tar.gz检查点：压缩包中必须包含 package-lock.json、scripts/deploy-ecs.sh、prisma/ 和 src/，不得包含 .env、.env.production、node_modules、.next 或旧的 dev.db。4.4 上传项目并执行一键部署步骤 1：上传部署包在本地项目父目录执行：scp codeverse-ops-deploy.tar.gz root@<ECS_IP>:/root/使用密钥对时执行：scp -i <私钥文件路径> codeverse-ops-deploy.tar.gz root@<ECS_IP>:/root/步骤 2：登录 ECSssh root@<ECS_IP> 使用密钥对时执行：ssh -i <私钥文件路径> root@<ECS_IP> 步骤 3：解压并运行部署脚本cd /root tar -xzf codeverse-ops-deploy.tar.gz rm -f codeverse-ops-deploy.tar.gz cd /root/codeverse-ops vi .env.production在编辑器中填写 2.5 节准备的三个环境变量，保存后限制文件权限：chmod 600 .env.production # 确保 Node.js 主版本为 20 node -v 2>/dev/null || true 若已安装的 Node.js 不是 20.x，先升级：curl -fsSL https://deb.nodesource.com/setup_20.x | bash - apt-get install -y nodejs首次部署执行：chmod +x scripts/deploy-ecs.sh bash scripts/deploy-ecs.sh重新部署时，scripts/deploy-ecs.sh 会先备份 /opt/codeverse-ops/dev.db，替换应用文件后再恢复数据库并执行增量迁移。重要数据仍建议在部署前单独备份。部署脚本自动完成：阶段操作预期结果1/6安装 Node.js 20、PM2、Nginx、SQLite输出各工具版本2/6备份数据库，替换 /opt/codeverse-ops 中的应用文件并恢复数据项目文件部署完成，历史数据保留3/6将 .env.production 复制为 .env应用可读取配置4/6执行 npm ci、Prisma 生成、迁移和 next build数据表和生产构建生成5/6使用 PM2 启动 npm startcodeverse-ops 状态为 online6/6配置 Nginx，将 80 端口代理到 3000nginx -t 成功并重载部署脚本结束时会输出访问地址。请以实际 ECS 公网 IP 为准：http://<ECS_IP>说明：脚本末尾可能显示脚本内预置的示例 IP，该值不一定是当前 ECS 地址，不应作为访问依据。图 4-2 PM2 启动成功且 Nginx 配置校验通过4.5 部署结果验证依次执行：node -v npm -v pm2 status systemctl is-active nginx curl -I http://127.0.0.1:3000 curl -I http://127.0.0.1预期结果：Node.js 主版本为 v20；PM2 中 codeverse-ops 状态为 online；Nginx 状态为 active；两次 curl 均返回 HTTP 200、301 或 307 等正常响应，而不是连接失败。检查数据库：cd /opt/codeverse-ops sqlite3 dev.db ".tables" 预期至少看到与以下模型对应的数据表：BatchGroup CloudLog Conversation Message QualityScore Snippet Task最后，在浏览器访问 http://<ECS_IP>。首页应显示“代码重构”“日志诊断”“仪表盘”和“收藏库”等入口。图 4-3 通过 ECS 公网地址访问 CodeVerse-Ops图 4-4 首页功能入口、核心特性和任务统计五、功能体验5.1 智能代码重构在首页单击 代码重构；保持 单文件 模式；选择 javascript，单击 快捷模板 > 回调地狱；也可粘贴自己的代码；单击 提交重构；提交后等待 MaaS 返回完整结果。当前版本在此阶段可能仅显示按钮处于处理中；页面连接任务 SSE 接口并显示“重构完成”后，查看 TypeScript 结果和优化点；单击 对比查看，检查原代码与重构代码差异；查看五维质量雷达图，比较原始代码和重构代码；使用复制、导出或收藏功能保存结果。图 5-1 提交代码并获得 TypeScript 重构结果图 5-2 对比重构前后代码并查看质量评分示例输入：function getUserData(userId, callback) { db.query("SELECT * FROM users WHERE id = ?", [userId], function (err, user) { if (err) return callback(err); db.query("SELECT * FROM orders WHERE userId = ?", [userId], function (err, orders) { if (err) return callback(err); callback(null, { user, orders }); }); }); } 验收标准：请求完成后页面显示任务成功状态、完整重构结果和任务 ID；结果包含带明确类型的 TypeScript 代码；优化说明能够指出异步流程、错误处理或类型安全等改进；雷达图至少展示安全性、可维护性、性能、可读性和类型安全五个维度。注意：当前重构提示词统一要求输出 TypeScript。即使输入 Python、Java、Go、PHP、Ruby、C 或 C++，输出目标仍是 TypeScript。5.2 批量代码重构进入 代码重构，切换到 批量；单击 添加文件，填写文件名、语言和代码内容；重复添加多个文件；单击批量提交按钮，查看总体和单文件处理状态；等待各文件状态更新为 COMPLETED 或 FAILED。限制条件：单次最多 20 个文件；接口以 JavaScript 字符串长度统计总量，上限约 500 万字符；该限制不等同于严格的 UTF-8 字节大小；每个文件会创建独立任务，并归属同一个批次；批量处理消耗的模型 Token 通常高于单文件处理，请控制测试代码规模。当前版本说明：批量页面仅展示文件名、语言和任务状态，暂不提供单个文件的重构结果详情入口。5.3 云原生日志故障诊断在首页单击 日志诊断；选择 CCE（云容器引擎）；单击 快捷模板 > CCE OOMKilled；单击 提交诊断；等待同步分析完成，查看根因分析和 YAML 修复建议；再选择 FunctionGraph（函数工作流），使用“函数超时”模板重复体验。图 5-3 提交 FunctionGraph 故障日志并查看根因图 5-4 查看结构化修复建议并继续追问示例输入：Warning OOMKilled pod/api-server-7d9f8b6c4-x2k9j Last State: Terminated Reason: OOMKilled Exit Code: 137 Restart Count: 5 Limits: cpu: 1, memory: 512Mi Requests: cpu: 500m, memory: 256Mi验收标准：根因分析能识别容器内存超限和退出码 137；修复建议包含调整 resources.requests、resources.limits 或排查内存泄漏的可执行方向；FunctionGraph 超时案例能给出超时时间、内存、数据读取方式等方面的排查建议。安全提示：提交真实日志前应删除账号、Token、密码、内网地址、用户数据等敏感信息。模型建议不可直接应用于生产集群。5.4 代码质量评分单文件重构完成后，页面会分别调用质量评分接口评估原始代码和重构代码。评分范围为 0～100：维度评估内容常见风险安全性注入、XSS、敏感信息、危险 API拼接 SQL、明文密钥、eval可维护性模块化、重复度、耦合度超长函数、重复逻辑、全局状态性能复杂度、I/O 和资源使用不必要的嵌套循环、重复请求可读性命名、结构、注释单字母变量、深层嵌套类型安全类型覆盖与边界处理any、隐式转换、空值未处理评分由大模型生成，适合辅助比较，不等同于静态代码扫描、单元测试或安全审计结果。当前版本说明：重构页面会展示原始代码和重构代码的即时评分，但页面请求暂未携带 taskId，因此这些评分不会写入 QualityScore 表，仪表盘“质量评分趋势”可能为空。这不影响雷达图展示和其他任务统计。5.5 AI 上下文对话在重构或诊断结果页单击 继续对话；输入针对当前结果的问题，例如“请解释此处的类型设计”或“如何验证该 YAML 修复有效”；查看流式回复；收起对话面板后再次打开，确认历史消息仍可显示。对话消息会写入 SQLite，但服务端用于连续推理的内存上下文有效期为 30 分钟，每 5 分钟清理一次。重新打开“继续对话”面板时，应用会读取持久化消息并重建上下文；如果面板保持打开期间上下文过期，接口会提示重新创建。刷新页面后，当前结果和 taskId 会丢失，现有页面没有从仪表盘重新进入原任务详情的入口。5.6 历史任务仪表盘完成至少一次代码重构和一次日志诊断；进入 仪表盘；查看总任务数、重构次数、诊断次数和成功率；查看近 30 天趋势、任务类型分布、状态分布、质量评分趋势和最近任务；单击 刷新，或保持 30 秒自动刷新。图 5-5 查看任务总量、成功率和近 30 天趋势图 5-6 查看任务分布、质量趋势和最近任务若仪表盘为空，请先确认任务已成功写入数据库，再刷新页面。5.7 代码片段收藏库在代码重构结果页单击 收藏；进入 收藏库；使用关键词或编程语言筛选收藏；复制或导出收藏结果；单击 删除 并确认，可移除不再需要的收藏。图 5-7 搜索、复制、导出或删除收藏内容日志诊断结果也提供收藏入口。收藏前请确认结果中不含敏感日志。5.8 命令面板与主题按 Ctrl+K（macOS 为 Command+K）打开命令面板；输入“重构”“诊断”“仪表盘”“收藏”或“主题”等关键词；使用方向键选择命令，按 Enter 执行，按 Esc 关闭；可通过页面导航切换明暗主题。图 5-8 使用命令面板快速导航图 5-9 切换为浅色主题六、运行维护与故障排查6.1 常用运维命令# 查看进程 pm2 status # 查看最近日志 pm2 logs codeverse-ops --lines 100 # 重启应用 pm2 restart codeverse-ops # 查看 Nginx 状态与配置 systemctl status nginx --no-pager nginx -t # 查看端口监听 ss -lntp | grep -E ':80|:3000' # 查看磁盘和内存 df -h free -h # 查看数据库表和最近任务 cd /opt/codeverse-ops sqlite3 dev.db ".tables" sqlite3 dev.db \ "SELECT id, type, status, language, createdAt FROM Task ORDER BY createdAt DESC LIMIT 10;" 修改 .env 后必须重启应用：cd /opt/codeverse-ops pm2 restart codeverse-ops --update-env6.2 常见问题现象可能原因处理方法浏览器无法访问 http://<ECS_IP>安全组未开放 80、Nginx 未启动、EIP 错误检查安全组、systemctl status nginx 和 ECS 公网 IP502 Bad GatewayNext.js 进程未启动或 3000 端口未监听执行 pm2 status、pm2 logs codeverse-ops，重启 PM2返回 401 或 403API Key 无效、模型未开通、账号区域不匹配重新查看 MaaS 调用说明并创建 API Key返回 404MaaS 基础地址配置错误确保地址不包含 /v1/chat/completions，国内站填写 https://api.modelarts-maas.com/openai页面提示“系统配置异常”环境变量缺失检查 /opt/codeverse-ops/.env 中两个 HUAWEI_MAAS_* 变量AI 请求长时间无响应或连接中断单次 MaaS 调用超时为 120 秒，普通调用最多尝试 3 次缩短输入并检查 MaaS 状态；Nginx 已配置 400 秒读取超时，生产环境仍应结合调用策略统一超时对话流式输出中断Nginx、浏览器网络或模型连接中断检查 PM2/Nginx 日志，重新打开对话面板后重试首轮重构或诊断没有逐 Token 输出当前提交接口同步完成 MaaS 调用后才连接任务 SSE这是当前版本的实现行为；等待请求完成，以最终结果为准next build 被系统终止ECS 内存不足使用 4 GiB 或更高规格，停止无关进程后重试Prisma 报数据库不存在或无表DATABASE_URL 错误或迁移失败恢复 file:../dev.db，执行 npx prisma generate && npx prisma migrate deploy仪表盘有任务但无质量趋势当前重构页面的评分请求未携带 taskId这是当前版本已知限制，不影响即时雷达图和其他任务统计批量任务拒绝提交文件数或字符串总长度超限保持不超过 20 个文件、代码总量约 500 万字符以内6.3 重新构建与升级更新代码后，在 ECS 执行：cd /opt/codeverse-ops npm ci npx prisma generate npx prisma migrate deploy npm run build pm2 restart codeverse-ops --update-env执行数据库迁移前建议备份：cd /opt/codeverse-ops cp dev.db "dev.db.backup.$(date +%Y%m%d%H%M%S)" 6.4 生产化建议本案例以快速体验为目标。用于团队或生产环境前，至少应补充：使用 IAM、统一身份认证或应用登录保护所有页面和 API；使用 ELB/Nginx 配置 HTTPS 证书，禁止明文传输代码和日志；将 API Key 存储到云凭据管理服务，避免落盘和终端输出；使用云数据库替代单机 SQLite，并建立自动备份；将内存对话上下文迁移到 Redis 等共享存储，支持多实例；增加请求限流、输入大小限制、审计日志和敏感信息脱敏；对模型生成代码执行静态扫描、单元测试和人工评审；对模型生成的运维命令和 YAML 建立审批及灰度验证流程；配置 AOM、LTS 或其他可观测服务监控 CPU、内存、错误率和模型调用延迟。七、释放资源7.1 删除 ECS登录华为云控制台，进入 弹性云服务器 ECS > 实例；选择本案例创建的 ECS；单击 更多 > 删除；根据页面提示勾选释放绑定的 EIP、删除系统盘和数据盘；确认资源名称和影响范围后完成删除。删除后再次检查 ECS、云硬盘和 EIP 列表，确认没有遗留按需资源。7.2 处理 MaaS 资源进入 MaaS 控制台 > 模型推理 > 在线推理：预置模型通常按实际调用量计费，停止调用后不会继续产生推理 Token；删除不再使用的 API Key，降低泄露风险；如创建过专属部署实例或其他持续计费资源，请停止并删除；在费用中心检查账单和代金券使用情况。7.3 删除本地敏感文件不再使用项目时，可删除包含 API Key 的部署包和环境变量文件：# Linux/macOS rm -f codeverse-ops-deploy.tar.gz rm -f codeverse-ops/.env.productionWindows PowerShell 执行：Remove-Item .\codeverse-ops-deploy.tar.gz -ErrorAction SilentlyContinue Remove-Item .\codeverse-ops\.env.production -ErrorAction SilentlyContinue若 API Key 曾出现在公开仓库、日志或截图中，应立即在 MaaS 控制台删除并重新创建。八、扩展资料华为云 MaaS OpenAI 兼容接口说明华为云 MaaS 模型列表弹性云服务器 ECS 文档弹性公网 IP 文档云容器引擎 CCE 文档函数工作流 FunctionGraph 文档九、案例验收清单完成以下检查即表示案例体验成功：[ ] 已开通 DeepSeek-V4-Flash，并使用华为云 MaaS API Key 完成接口验证；[ ] 如实践第三章，已通过码道完成 spec.md、design.md、tasks.md 和分阶段任务执行；[ ] ECS、EIP 和安全组配置完成；[ ] codeverse-ops 在 PM2 中为 online，Nginx 为 active；[ ] 浏览器可通过 ECS 公网 IP 打开首页；[ ] 单文件代码重构可通过任务 SSE 接口收到 complete 结果；[ ] 批量重构可显示批次和单文件状态；[ ] CCE 或 FunctionGraph 日志可生成根因分析和修复建议；[ ] 质量雷达图可展示原始代码与重构代码对比；[ ] AI 对话可逐段显示回复，仪表盘和收藏库可正常使用；[ ] 已确认模型输出仅作辅助并经过人工复核；[ ] 体验结束后已释放不再使用的计费资源和 API Key。

一、概述1.1 案例介绍在课程学习中，学生常常同时面对 PDF 讲义、Markdown 笔记、教材摘录和练习题等多种资料。传统学习工具通常只能解决“保存资料”或“回答问题”中的某一个环节，难以持续回答下面几个问题：一门课程到底包含哪些知识点，它们之间有什么层级和前置关系？学生目前真正薄弱的是哪些知识点，判断依据是什么？学习计划能否根据实际作答结果自动调整？AI 给出的知识点、题目和回答是否有课程资料依据？当模型或外部服务不可用时，核心学习流程能否继续运行？基于这些问题，我利用华为云码道（CodeArts）智能体开发了 CoursePilot。它不是一个只负责聊天的通用助手，而是一个以课程资料和学习证据为基础的 AI 个性化学习教练 Agent。系统围绕以下闭环工作：注册登录 → 创建课程 → 添加资料 → 构建知识结构 → 设置学习目标 → 初始诊断 → 生成知识画像 → 制定学习计划 → 学习与练习 → 错因分析 → 更新掌握度 → 动态调整计划 项目仓库：cid:link_7项目地址：115.120.251.21（由于成本限制，该IP发布帖子几日后可能会释放！）演示视频：项目仓库根目录 demo视频.mp41.2 核心设计原则课程无关：不把业务逻辑绑定到某一门固定课程。资料驱动：知识点、题目和学习辅导尽量建立在用户资料之上。来源可追溯：知识点和 AI 生成题目保留对应资料与分块来源。证据驱动：掌握度来自真实作答、难度、耗时和提示使用情况。人机协同：AI 负责提取、生成和辅助判断，用户保留确认与修正权。可解释与可审计：重要算法采用确定性规则，Skill 与 MCP 调用保存日志。可降级：大模型不可用时，资料解析、诊断和掌握度更新等核心流程仍可运行。1.3 适用对象希望完成 AI Agent 项目实践的高校学生；学习 Vue 3、FastAPI、MCP、Skill 与 Docker 的开发者；需要搭建课程资料管理、诊断或个性化学习系统的团队；希望了解如何将本地全栈应用部署到华为云 ECS 的开发者。1.4 案例时间本案例总时长预计240分钟。1.5 案例流程本案例采用“需求规格—架构设计—任务拆解—分阶段开发—测试验证—云端部署—迭代优化”的流程完成 CoursePilot 的设计与实现。使用华为云码道（CodeArts）代码智能体辅助完成需求分析，编写产品规格、功能需求和用户流程文档，明确 CoursePilot 的产品定位、功能范围、验收条件以及“资料驱动、证据驱动、来源可追溯”等核心原则，定义系统“做什么”。完成系统架构与技术方案设计，确定 Vue 3、FastAPI、SQLAlchemy、MCP、Skill 和 Docker Compose 技术栈，并编写领域模型、总体架构、MCP 设计、Skill 设计及关键算法 ADR，定义系统“怎么做”。根据需求和架构生成开发路线及阶段任务清单，将项目拆分为课程资料、知识结构、题库诊断、知识画像、学习计划、学习 Agent、MCP/Skill、学习看板和云端部署等可独立验收的开发任务。按照任务清单逐步开发：搭建 FastAPI 后端和 Vue 3 前端，实现用户认证、课程管理、资料解析、知识结构生成、AI 辅助出题、动态诊断、掌握度计算、个性化学习计划及渐进式辅导 Agent。建立 CoursePilot MCP Server，封装课程资料、题库、作答记录、学习状态和计划管理等工具；同时实现资料结构化、学习诊断、计划生成和苏格拉底式辅导等可插拔 Skill。使用码道代码智能体辅助进行跨文件代码审查、缺陷定位和测试补充；后端及 MCP Server 使用 Pytest 和 Ruff 验证，前端使用 TypeScript 类型检查、ESLint 和 Vite 生产构建验证。使用 Docker Compose 完成前端、后端和 MCP Server 的容器化编排，并部署至华为云 ECS；结合华为云 SWR 镜像加速解决基础镜像拉取问题，使用 Alembic 完成数据库迁移，并通过健康检查和容器日志验证服务状态。根据实际使用结果持续迭代，修复文件上传 413、AI 长任务 504、生成题目知识点 ID 越界、诊断中断后无法继续等问题，进一步提升系统的数据一致性、容错能力和用户体验。1.6 资源总览资源名称本案例使用规格主要用途计费说明弹性云服务器 ECS通用计算增强型 ac9s.large.2；2 vCPU；4 GiB；Ubuntu 24.04 Server 64 位；60 GiB 通用型 SSD运行前端、FastAPI 后端和 MCP Server 容器0.3452元/小时 弹性公网 IP EIP全动态 BGP；按流量计费；5 Mbit/s提供网站公网访问及 SSH 运维入口0.8元/GB虚拟私有云 VPC 和安全组1 个 VPC、1 个子网、1 个安全组提供私有网络及端口访问控制免费容器镜像服务 SWR使用个人专属镜像加速地址加速拉取 Python、Node.js 和 Nginx 等 Docker 基础镜像免费华为云码道（CodeArts）代码智能体专业版辅助需求分析、架构设计、任务拆解、代码开发、测试及问题定位专业版，139元/6000万tokens免排队MaaS - Console个人使用deepseek-v4-flash用于知识结构优化、AI 辅助出题及学习辅导输入：1元/百万tokens  输出：2元/百万tokensECS 本地存储SQLite 数据库及课程上传目录，共用 ECS 系统盘保存业务数据、课程资料和调用记录已包含在本案例 ECS 云硬盘配置中二、系统方案设计2.1 技术栈层级技术选型前端Vue 3、TypeScript、Pinia、Vue Router、Vite、AxiosWeb 服务Nginx后端Python 3.11、FastAPI、Pydantic、异步 SQLAlchemy数据迁移AlembicAgent 协议Model Context Protocol（MCP）业务能力4 个可插拔 Skill大模型接入OpenAI 兼容 Provider，用户自行配置模型数据库SQLite（案例演示）；可切换 PostgreSQL容器化Docker、Docker Compose云资源华为云弹性云服务器 ECS、弹性公网 IP、安全组代码托管GitCodeAI 辅助开发华为云码道（CodeArts）代码智能体2.2 总体架构用户浏览器 │ ▼ Nginx / Vue 3 前端（80/443） │ /api/* ▼ FastAPI 后端（容器内部 8000） ├── SQLAlchemy / Alembic ── SQLite 或 PostgreSQL ├── 课程资料与上传文件 ├── LLM Provider ───────── 用户配置的大模型服务 └── MCP Client │ Streamable HTTP ▼ MCP Server（容器内部 8001） ├── 13 个业务工具 └── 4 个 CoursePilot 运行时 Skill2.3 项目结构CoursePilot/ ├── backend/ # FastAPI、领域模型、服务、Alembic 与测试 ├── frontend/ # Vue 3 前端 ├── mcp-server/ # MCP Server 与业务工具 ├── skills/ # 4 个 CoursePilot 运行时 Skill ├── docs/ # 需求、架构、ADR、验收与阶段报告 ├── AGENTS.md # 项目技术规范与协作约束 ├── docker-compose.yml └── README.md2.4 MCP 与 Skill 设计CoursePilot 的 MCP Server 提供 13 个业务工具，分为四类：课程与资料：课程列表、课程结构、资料检索、资料来源；学习状态：学生画像、知识点掌握度、错题；题库与作答：题目搜索、题目详情、保存作答；计划与掌握度：读取计划、更新计划、更新掌握度。系统还实现了 4 个运行时 Skill：Skill作用course_material_structuring将课程资料整理为知识结构learning_diagnosis根据作答证据分析学习状态和错因study_plan_generator生成及动态调整学习计划socratic_tutor使用分级提示进行启发式辅导三、使用华为云码道进行规范驱动开发3.1 建立项目上下文CoursePilot 涉及课程资料、题库、诊断、知识画像、计划、Agent、MCP 和 Skill 等多个领域。如果只用一句话要求 AI “生成一个学习平台”，很容易得到功能堆叠但规则不一致的代码。因此，本项目先在仓库中沉淀以下上下文：AGENTS.md：技术栈、目录结构、编码规范和测试命令；docs/product-spec.md：产品定位、范围和冻结决策；docs/requirements.md：功能需求与验收条件；docs/domain-model.md：领域实体、关系与约束；docs/architecture.md：系统边界与调用链；docs/adr/：掌握度算法、学习计划算法、Agent 编排等架构决策。3.2 各阶段Prompt每次使用时，可以先附加这段通用要求：请先阅读 AGENTS.md、本阶段相关设计文档和现有代码。 开始修改前必须： 1. 说明当前实现基线； 2. 给出任务拆解、影响文件和数据迁移方案； 3. 明确本阶段边界； 4. 不修改与本阶段无关的模块； 5. 不覆盖用户已有修改； 6. 实现后运行相关自动化测试和质量检查； 7. 最后报告修改文件、测试结果、未完成项和已知限制。 所有新增API统一放在 /api/v1/ 下。 后端IO操作优先使用 async/await。 数据库结构变更必须使用Alembic，不使用create_all代替迁移。 前端使用Vue 3、TypeScript、Pinia和<script setup lang="ts">。前置阶段：需求与规格设计请作为产品经理和系统架构师，为 CoursePilot 建立完整的需求与设计基线。 项目定位： CoursePilot 是一个课程无关、资料驱动、证据驱动、来源可追溯的AI个性化学习教练。系统需要形成： 创建课程 → 添加资料 → 构建知识结构 → 设置学习目标 → 初始诊断 → 知识画像 → 学习计划 → 学习与练习 → 错因诊断 → 掌握度更新 → 动态调整计划 请检查当前项目骨架，并编写或完善： - docs/product-spec.md - docs/requirements.md - docs/mvp-acceptance.md - docs/user-flows.md - docs/domain-model.md - docs/skill-design.md - docs/mcp-design.md - docs/development-roadmap.md - docs/current-gap-analysis.md 具体任务： 1. 定义目标用户、用户痛点、产品定位和产品边界； 2. 将需求划分为Must、Should、Could和Won't； 3. 为每项Must需求定义正常流程、异常流程和验收条件； 4. 使用Given/When/Then编写可执行验收标准； 5. 设计课程、资料、知识点、题目、诊断、画像、计划和Agent等领域实体； 6. 设计4个业务Skill及13个MCP工具； 7. 冻结掌握度、简答题、诊断题数量、模型Provider、账号体系和课程无关性决策； 8. 将开发工作拆分为阶段0至阶段7； 9. 明确每个阶段的目标、任务、边界、验收标准和交付物。 本阶段只编写需求和设计文档，不修改业务代码。 不得提前将尚未实现的功能标记为完成。阶段0：可运行基础设施基线请执行 CoursePilot 阶段0：可运行基础设施基线。 阶段目标： 让FastAPI后端、Vue前端、异步数据库、Alembic和MCP Server形成可启动、可测试的基础工程。 具体任务： 1. 修复FastAPI启动流程，确保GET /health返回200； 2. 建立统一的SQLAlchemy Base、异步engine和AsyncSession； 3. 配置Alembic target_metadata及异步迁移环境； 4. 验证upgrade head、downgrade base、再次upgrade head； 5. 统一Python模块路径和项目依赖，消除循环引用； 6. 修复Vue 3开发启动、TypeScript检查、ESLint和生产构建； 7. 将MCP Server统一为Streamable HTTP传输，端点为/mcp； 8. 确定FastAPI后端是唯一MCP Client，移除前端直连MCP的设计； 9. 修复后端、前端和MCP Server的Dockerfile及docker-compose.yml； 10. 建立后端健康检查、MCP连通性和前端页面加载冒烟测试； 11. 更新AGENTS.md和docs/deployment.md中的启动命令。 阶段边界： - 不实现课程CRUD； - 不实现资料解析； - 不创建完整业务领域模型； - 不实现正式业务Skill和MCP工具； - 不接入真实大模型； - 不实现完整注册、登录和管理员后台。 验收要求： - 后端、前端和MCP Server均可独立启动； - Alembic往返迁移通过； - MCP Streamable HTTP调用通过； - 前端type-check、lint和build通过； - docker compose config验证通过。阶段1：课程、资料与知识结构闭环请执行 CoursePilot 阶段1：课程、资料和知识结构垂直闭环。 请重点阅读： - docs/product-spec.md - docs/requirements.md中的FR-001至FR-003 - docs/domain-model.md - docs/user-flows.md中的流程1至流程4 - docs/mvp-acceptance.md中的AC-001至AC-003 阶段目标： 完成“创建课程→添加资料→解析资料→形成知识结构”的完整闭环。 具体任务： 1. 创建Course、CourseMaterial、MaterialChunk、KnowledgePoint和KnowledgeRelation模型； 2. 编写对应Alembic迁移、约束、外键和索引； 3. 实现课程创建、列表、详情、编辑和软删除API； 4. 实现PDF、Markdown、TXT文件上传及文本粘贴； 5. 实现资料状态、失败原因、重试和删除； 6. 实现规则型文本提取和资料分块； 7. 保存文件名、页码、章节或字符范围等来源信息； 8. 实现知识点新增、编辑、删除、排序和父子层级； 9. 实现prerequisite、contains和related知识关系； 10. 防止知识点关系自引用和循环依赖； 11. 实现课程列表、课程详情、资料管理和知识结构页面； 12. 使用两门内容不同的课程验证业务代码没有学科硬编码。 阶段边界： - 不实现题库和诊断； - 不实现知识画像、掌握度和学习计划； - 不实现正式业务Skill和MCP工具； - 不调用真实大模型。 验收要求： 用户能够创建课程，上传或粘贴资料，查看解析状态、资料分块和来源，并获得可编辑的树形知识结构。阶段2：题库、诊断与作答记录请执行 CoursePilot 阶段2：题库、初始诊断和作答记录。 请重点阅读： - requirements.md中的FR-004、FR-006和FR-010 - mvp-acceptance.md中的AC-004、AC-006和AC-010 - product-spec.md中的D-002和D-003 - domain-model.md中的题目、诊断和作答实体 阶段目标： 完成“建立题库→开始诊断→逐题作答→完成诊断”的业务流程。 具体任务： 1. 创建Question、QuestionOption和QuestionSource模型； 2. 创建question_knowledge_point多对多关联表； 3. 支持单选题、判断题和简答题； 4. 实现题目新增、编辑、删除、列表、筛选和审核状态； 5. 手动题目默认confirmed，AI或导入题目默认pending； 6. 题目必须关联至少一个当前课程知识点； 7. 保存题目对应的资料分块和来源位置； 8. 创建DiagnosticAttempt和AnswerRecord； 9. 按D-003规则选择诊断题： target_count = min(max(核心知识点数量, 10), 20)； 10. 题库不足时阻止诊断并提示用户补充； 11. 诊断开始时保存不可变题目快照； 12. 保存答案、正确性、作答时间、跳过状态、提示次数和最高提示等级； 13. 实现L1至L4渐进式提示，L4完整解析需要二次确认； 14. 实现题库、诊断作答和诊断结果前端页面； 15. 为AI辅助出题预留接口，但本阶段不接入真实模型。 阶段边界： - 不计算知识画像和最终掌握度； - 不实现错因诊断； - 不实现学习目标和学习计划； - 不实现业务Skill、正式MCP工具和Agent。 验收要求： 用户能够管理题库并完成一次10至20题的诊断；系统保存完整作答证据，诊断题响应不得提前泄露正确答案和解析。阶段3：知识画像、错因诊断与掌握度请执行 CoursePilot 阶段3：知识画像、错因诊断和掌握度算法。 请重点阅读： - requirements.md中的FR-007、FR-011和FR-012 - mvp-acceptance.md中的对应验收条件 - product-spec.md中的D-001和D-002 - docs/adr/ADR-003-mastery-algorithm.md 阶段目标： 将用户作答记录转换为确定、可解释、可追溯的知识画像。 具体任务： 1. 创建MasteryRecord和ErrorDiagnosis模型及Alembic迁移； 2. 实现mastery-v1确定性掌握度算法； 3. 掌握度范围为0至100，置信度范围为0至1； 4. 算法考虑正确性、难度、作答时间、提示等级、连续错误、时间间隔和前置知识； 5. 使用Decimal和ROUND_HALF_UP，禁止依赖浮点round； 6. 每次有效证据追加MasteryRecord，不覆盖历史记录； 7. 保存旧值、新值、计算依据、变化原因和关联AnswerRecord； 8. 保证同一作答记录不会重复生成掌握度记录； 9. 实现10类规则型错因判断； 10. 保存错因类型、诊断依据、置信度、建议行动和关联知识点； 11. 支持用户确认或修改错因； 12. 实现知识画像列表和掌握度证据详情API； 13. 实现掌握度、置信度、薄弱点、待复习和证据链前端页面。 阶段边界： - 大模型不能直接计算或写入掌握度； - 本阶段不得调用真实LLM； - 不实现学习目标、学习计划和Agent； - 不实现正式业务Skill和MCP工具。 验收要求： 相同输入必须产生相同掌握度结果，每次变化均可追溯到具体作答记录；未经确认的简答题不得影响掌握度。阶段4：学习目标、计划与动态调整请执行 CoursePilot 阶段4：学习目标、个性化学习计划与动态调整。 请重点阅读： - requirements.md中的FR-005、FR-008和FR-013 - mvp-acceptance.md中的对应验收条件 - docs/adr/ADR-004-study-plan-algorithm.md 阶段目标： 根据学习目标、知识画像、知识点关系和时间约束生成确定、可解释的学习计划。 具体任务： 1. 创建LearningGoal、StudyPlan和StudyTask模型及迁移； 2. 每个用户每门课程只维护一个LearningGoal； 3. 支持目标日期、目标掌握度、每日时长和每周学习日； 4. 实现study-plan-v1确定性计划算法； 5. 根据掌握度差距、重要性、复习状态、连续错误和前置关系计算优先级； 6. 使用Kahn算法对前置关系稳定拓扑排序； 7. 检测知识点关系环； 8. 将任务分配到目标日期范围内的可用学习日； 9. 每日总时长不得超过daily_minutes； 10. 超过60分钟的任务拆分为多个子任务； 11. 容量不足时返回结构化错误和调整建议； 12. 每个任务保存generation_reason和generation_basis； 13. 支持完成、跳过、延期和手动调整； 14. 支持评估是否需要重新规划； 15. 重新规划时将旧计划设为superseded，并通过previous_plan_id保留历史； 16. 实现学习目标、当前计划和历史计划前端页面。 阶段边界： - 不调用真实大模型； - 不实现Agent、业务Skill和正式MCP工具； - 不实现错题本、学习看板、日历同步和消息推送。 验收要求： 计划生成结果可重复、可解释，不违反前置关系和时间容量；用户操作任务后能够评估调整需求并保留计划版本历史。阶段5：Skill、MCP、Agent 与 LLM Provider请执行 CoursePilot 阶段5：业务Skill、MCP工具、Agent和LLM Provider。 请重点阅读： - docs/skill-design.md - docs/mcp-design.md - docs/adr/ADR-005-agent-provider-and-orchestration.md - 阶段1至阶段4已经实现的业务服务 阶段目标： 建立可配置、可审计、可降级的CoursePilot Agent体系。 具体任务： 1. 删除course_recommend、schedule_optimizer和learning_analyzer占位Skill； 2. 实现4个正式Skill： - course_material_structuring - learning_diagnosis - study_plan_generator - socratic_tutor 3. 每个Skill包含skill.py、config.yaml和async execute(params)； 4. Skill不直接操作数据库，通过业务服务或MCP工具获取数据； 5. 实现13个正式MCP业务工具； 6. 将MCP工具划分为只读工具和写入工具； 7. MCP Server通过BackendGateway调用FastAPI业务API； 8. 前端不得直接连接MCP Server； 9. 实现可配置的LLM Provider抽象； 10. 支持Mock Provider和OpenAI兼容Provider； 11. 自动测试只能使用Mock/Fake Provider； 12. 创建AgentSession、AgentMessage和ToolCallLog； 13. 实现Agent会话创建、消息发送、历史查询和结束会话； 14. 实现L1至L4苏格拉底式辅导； 15. 标记course_material、ai_supplement、mixed和unverified来源； 16. 所有Skill和MCP调用保存审计记录； 17. 对API Key、Token、Cookie、密码和密钥进行递归脱敏； 18. Agent写操作必须先请求用户确认； 19. 实现Agent对话和来源展示前端页面； 20. 实现Provider和MCP不可用时的规则降级。 阶段边界： - 不实现错题本和学习看板； - 不实现管理员后台； - 不允许把具体模型写成不可替换依赖； - Skill不得复制确定性掌握度和计划算法。 验收要求： 4个Skill和13个MCP工具能够独立调用；Agent可读取课程资料、画像和计划，能够恢复会话、显示来源、记录调用并在模型不可用时降级。阶段6：错题本、看板与日志展示请执行 CoursePilot 阶段6：完整前端交互、错题本、学习看板和调用日志展示。 请先检查阶段1至阶段5的数据模型和业务调用链，特别是： - AnswerRecord - DiagnosticAttemptQuestion不可变快照 - ErrorDiagnosis - MasteryRecord - StudyPlan和StudyTask - AgentSession和ToolCallLog 阶段目标： 补齐学习数据展示、错题复习和完整前端体验。 具体任务： 1. 实现WrongQuestionState模型及Alembic迁移； 2. 按user_id、course_id和question_id聚合错题； 3. 错题内容优先读取不可变题目快照； 4. 仅将有效错误作答计入错误次数； 5. 支持按知识点、错因、状态和关键词筛选； 6. 展示历史错误、资料来源、错因证据和掌握度证据； 7. 支持标记已掌握； 8. 用户后续再次答错时自动重新打开错题状态； 9. 复用DiagnosticAttempt体系创建单题练习； 10. 实现学习看板10类确定性指标； 11. 展示今日任务、总体进度、掌握度分布、薄弱点、待复习项、错因分布、本周有效作答时长和计划完成率； 12. 实现课程级ToolCallLog查询； 13. 支持类型、状态、工具、会话、时间和分页筛选； 14. 保存日志和查询输出时均执行敏感信息脱敏； 15. 实现错题本、看板和调用日志前端页面； 16. 完善加载状态、错误提示、空状态、导航、路由参数和刷新恢复。 阶段边界： - 不修改4个Skill核心逻辑； - 不修改13个MCP工具契约； - 不修改mastery-v1和study-plan-v1； - 不实现管理员后台和阶段7部署功能。 验收要求： 错题复习、学习看板和调用日志形成前后端闭环；跨用户访问统一返回404；页面刷新后数据可以从API恢复。3.3 Skill前端美化AI直接生成的前端通常不符合我们的胃口，存在以下问题：全站仍是系统默认字体、同一字号层级和同一种 8px 圆角，页面缺少品牌辨识度。紫色高饱和主色、纯白卡片加灰边框在所有页面重复，是典型的通用 AI 后台视觉。顶栏只是文本平铺，当前页面反馈弱，宽屏松散、窄屏拥挤。首页、课程列表和登录页过度居中，信息层级单薄；题库等高频页面则过密。按钮、表单、弹窗样式在各页面重复且状态不统一，Hover、Pressed、Focus 反馈不足。加载和空状态大多只是一行文字，视觉完成度不足。因此我们可以为Code添加Skill对前端进行美化我们选用GitHub - Leonxlnx/taste-skill: Taste-Skill - gives your AI good taste. stops the AI from generating boring, generic slop · GitHub 这个67.7k Star的Github开源skill进行优化请你根据skill修改现有前端界面，做的更好看一些效果也是很明显：美化前首页美化后首页四、核心功能实现具体核心功能展示请参考仓库内的demo视频，或者通过打开网站或本地部署实际操作，这里简单展示一下界面和操作功能4.1 从课程资料生成可追溯知识结构用户可以上传 PDF、Markdown、TXT 文件，或者直接粘贴文本。后端解析后将内容切分为资料块，并保存文件、位置与内容之间的对应关系。知识结构生成时，系统不会只保存一个无法解释的标题，而是将知识点关联到原始资料。用户可以查看、调整层级和关系，降低模型幻觉对后续诊断的影响。如果知识结构生成不清晰，你可以使用AI进行结构的优化，也可以手动进行修改，使结构更加清晰4.2 基于资料的 AI 辅助出题在题库管理界面你可以手动添加题目，也可以使用AI辅助出题AI 出题只允许引用当前课程中有效的知识点 ID 和资料块 ID。模型输出后，后端还会再次校验：题型和难度是否符合请求；knowledge_point_ids 是否属于允许范围；source_chunk_id 是否来自本次课程资料；选项、答案和解析结构是否完整。如果模型第一次返回了越界 ID，系统会把错误约束和合法范围反馈给模型并重试；连续失败时停止保存，避免产生半成品题目。4.3 测验与知识画像当题库足够完整，能够覆盖全部知识点时，可以进行测验与诊断：测验过程中可以申请不同等级的提示，或者跳过，但是这和答错一样会不同程度影响你的掌握度判定！系统不会让大模型直接决定最终掌握度，而是使用确定性规则综合以下证据：作答是否正确；题目难度；作答耗时；提示次数与提示等级；最近正确率；是否重复犯错；前置知识掌握情况。每次掌握度变化都会保存旧值、新值、变化原因和关联作答记录，用户能够查看“为什么发生了这次变化”。错题可以在“错题本”中进行复习，或者重新做题：4.4 学习计划与动态调整用户可以设置目标日期、目标掌握度、每日学习时长和每周可学习日期。系统根据知识画像、知识点重要程度、前置关系、历史错题和可用时间生成学习任务。当用户完成任务、连续答错或掌握度明显变化时，系统可以触发重新规划，并保留计划版本和调整原因。同时用户也可以在学习看板上查看一系列学习数据：4.5 渐进式学习辅导 Agent学习辅导 Agent 通过 MCP 工具读取当前课程资料、知识结构、学生画像和学习计划，再由 Skill 控制提示节奏：L1：提醒相关知识点；L2：指出思路方向；L3：给出关键步骤；L4：在用户确认后给出完整解析。回复通过 SSE 流式返回，并标记内容来自课程资料、AI 补充或混合来源。模型不可用时，系统可以降级为规则型提示。五、部署到华为云 ECS5.1 案例环境本案例采用一台华为云 ECS 完成演示部署：配置项案例选择区域华东-上海一ECS通用计算增强型，2 vCPU / 4 GiB操作系统Ubuntu 24.04 Server 64 位系统盘通用型 SSD，60 GiB公网访问弹性公网 IP，按流量计费，5 Mbit/s容器编排Docker Compose安全组：端口用途来源建议22SSH 运维仅允许管理员当前公网 IP /3280HTTP0.0.0.0/0443HTTPS0.0.0.0/05.2 登录服务器这里我采用的是密钥对登录：$key = "D:\EdgeDownload\KeyPair-e9f4.pem" icacls $key /inheritance:r icacls $key /grant:r "$($env:USERDOMAIN)\$($env:USERNAME):(R)" icacls $key先执行这一步是为了防止Window私钥文件权限过宽然后执行登录：ssh -i $key root@115.120.251.215.3 安装 Docker 和 Git登录 ECS 后执行：apt update apt install -y ca-certificates curl git install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg \ -o /etc/apt/keyrings/docker.asc chmod a+r /etc/apt/keyrings/docker.asc echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo ${UBUNTU_CODENAME:-$VERSION_CODENAME}) stable" \ > /etc/apt/sources.list.d/docker.list apt update apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin systemctl enable --now docker docker --version docker compose version这里可能会出现报错，可能是因为访问 Docker 官方源被重置。直接改用华为云 Docker 镜像源即可。curl -fsSL https://mirrors.huaweicloud.com/docker-ce/linux/ubuntu/gpg \ -o /etc/apt/keyrings/docker.asc chmod a+r /etc/apt/keyrings/docker.asc echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://mirrors.huaweicloud.com/docker-ce/linux/ubuntu $(. /etc/os-release && echo ${UBUNTU_CODENAME:-$VERSION_CODENAME}) stable" \ > /etc/apt/sources.list.d/docker.list apt update apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin systemctl enable --now docker5.4 克隆 CoursePilot输入：cd /opt git clone cid:link_7.git cd CoursePilot5.5 创建生产环境变量先生成三个密钥，分别复制输出结果：python3 -c "import secrets; print(secrets.token_urlsafe(48))" python3 -c "import secrets; print(secrets.token_urlsafe(48))" python3 -c "import base64,secrets; print(base64.urlsafe_b64encode(secrets.token_bytes(32)).decode())"创建环境变量文件：nano .env填入：SECRET_KEY=第一个随机值 MCP_INTERNAL_API_KEY=第二个随机值 LLM_CREDENTIAL_ENCRYPTION_KEY=第三个随机值 ALLOWED_ORIGINS=["http://你的EIP"]保存退出即可。5.6 添加持久化配置现有 Compose 没有持久化 SQLite 和上传文件，所以不要直接启动。创建覆盖文件：nano docker-compose.override.yml填入：services: backend: environment: DATABASE_URL: sqlite+aiosqlite:////data/coursepilot.db DEBUG: "False" SECRET_KEY: ${SECRET_KEY} LLM_CREDENTIAL_ENCRYPTION_KEY: ${LLM_CREDENTIAL_ENCRYPTION_KEY} MCP_INTERNAL_API_KEY: ${MCP_INTERNAL_API_KEY} MCP_SERVER_URL: http://mcp-server:8001/mcp UPLOAD_DIR: /data/uploads ALLOWED_ORIGINS: '${ALLOWED_ORIGINS}' volumes: - ./data:/data restart: unless-stopped frontend: restart: unless-stopped mcp-server: environment: BACKEND_API_URL: http://backend:8000/api/v1 MCP_INTERNAL_API_KEY: ${MCP_INTERNAL_API_KEY} restart: unless-stopped保存退出，创建数据目录：mkdir -p data/uploads chmod 700 data5.7. 构建并启动docker compose build --pull如果出现报错可能是因为Docker Hub 在大陆网络访问超时。需要给 Docker 配置华为云 SWR 镜像加速器。在华为云控制台：切换到“华东-上海一”。搜索并进入“容器镜像服务 SWR”。左侧选择“镜像资源 → 镜像中心”。点击“镜像加速器”。复制地址在ECS执行：mkdir -p /etc/docker nano /etc/docker/daemon.json填入复制的真实地址：{ "registry-mirrors": [ "https://xxxxxxxx.mirror.swr.myhuaweicloud.com" ] }保存退出即可！然后拉取基础镜像：docker pull python:3.11-slim docker pull node:20-alpine docker pull nginx:alpine三个都成功后，重新构建：cd /opt/CoursePilot docker compose build5.8 文件上传问题解决课程文件上传和 AI 知识结构优化都可能超过 Nginx 默认限制。可以在 /api/ 代理中补充：server { listen 80; server_name _; client_max_body_size 20m; location /api/ { proxy_pass http://backend:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_connect_timeout 60s; proxy_send_timeout 300s; proxy_read_timeout 300s; } }修改后重新构建并启动前端容器：docker compose build frontenddocker compose up -d --no-deps frontend六、问题排查与踩坑复盘AI生成的代码在一些小细节上会出现疏忽和错误，同时部署过程中一些文件的配置不完全也可能会带来一些问题。这里是我列出的一部分可能会出现的问题可解决方案，如果大家部署过程中产生错误可参考以下内容：6.1 Docker Hub 连接超时现象failed to resolve source metadata for docker.io/library/python:3.11-slimdial tcp ...:443: i/o timeout原因ECS 访问 Docker Hub 不稳定，构建阶段无法获取基础镜像元数据。解决配置华为云 SWR 镜像加速器，先单独执行 docker pull 验证，再重新执行 Compose 构建。拉取完成后若 referrers 请求偶发超时，可重试构建。6.2 Alembic 找不到 app 模块现象ModuleNotFoundError: No module named 'app'原因迁移进程启动时，后端源码目录没有进入 Python 模块搜索路径。解决docker compose run --rm \ -e PYTHONPATH=/app/backend \ backend python -m alembic upgrade head6.3 上传课程资料返回 413现象Request failed with status code 413原因请求在进入 FastAPI 前就被 Nginx 的默认请求体大小限制拒绝。解决在 Nginx server 中设置 client_max_body_size，同时保证该值不小于后端允许的上传上限。6.4 AI 优化知识结构返回 504现象Request failed with status code 504原因模型需要读取多份资料并生成分层结构，耗时超过 Nginx 默认代理等待时间。解决提高 proxy_read_timeout 和 proxy_send_timeout。更长期的方案是将长任务改造成异步任务，并通过任务状态接口或 SSE 返回进度。6.5 模型返回越界知识点 ID现象第 4 道题结构不合法：knowledge_point_ids 不在允许范围内原因旧逻辑只重试题型和难度错误，知识点 ID 到保存阶段才校验，模型没有纠正机会。解决将知识点 ID 和资料块 ID 校验前移到模型重试阶段，反馈非法值与允许范围；连续失败则停止整批保存。6.6 诊断退出后无法再次进入现象该课程已有进行中的诊断，attempt_id=...原因后端正确阻止了重复创建，但前端没有恢复已有 attempt 的入口。解决将“开始诊断”设计为幂等操作：发现进行中的 attempt 时直接返回原记录，前端显示“继续诊断”，再从下一道未答题恢复。八、案例总结CoursePilot 的开发让我认识到，AI Agent 应用的难点不只是“接入一个大模型”，而是如何把模型放进一个可信、可解释、可恢复的业务闭环中。在开发阶段，华为云码道（CodeArts）代码智能体的价值主要体现在：通过 Codebase 理解跨前后端、MCP 与 Skill 的项目上下文；将自然语言需求拆解成可执行、可追踪的开发任务；在多文件修改、测试补充和日志排障中提高效率；结合仓库规范与验收条件，减少无边界生成；帮助整理从本地开发到 ECS 部署的完整过程。在运行阶段，CoursePilot 则通过资料来源、确定性算法、用户确认、调用审计和降级策略约束大模型，让 AI 真正服务于学习过程，而不是只生成看似合理的答案。九、参考资料华为云社区 HCSD 板块华为云码道（CodeArts）代码智能体产品介绍华为云码道（CodeArts）代码智能体下载安装CoursePilot GitCode 项目仓库