一、概述1.1 案例介绍高校学生在毕业前普遍反复遇到三个缺少统一答案的问题：“现在毕业还差什么”“这学期选课是否冲突”“接下来几个学期该怎么安排”。本案例用华为云码道（CodeArts）代码智能体，以规范驱动开发方式构建了学途 Navigator——一套将学分审计、选课约束检查、多学期修读规划三项判断交由可逐条解释的确定性规则引擎完成，并接入华为云 MaaS 承担自然语言解释与多轮咨询职能的学生自助工具。审计、先修、冲突、风险的判断权始终在规则引擎手中，AI 只负责把结构化结论"翻译"成建议——这也是本案例区别于"成绩单管理 + 大模型问答"类项目的核心设计。系统已部署至华为云 Flexus 云服务器并提供公网访问，可用演示账号直接体验。1.2 适用对象高校学生个人开发者1.3 案例时间本案例完整开发周期约 8 天，覆盖设计、核心引擎开发、前端与部署、AI 接入、增强功能、测试与发布等阶段（详见 3.1 节开发计划）；阅读本文并在本地运行核心功能（AI_PROVIDER=mock 模式，无需华为云凭据）预计需要 40–60 分钟。1.4 案例流程说明：先产出完整的详细设计文档体系（需求规格、系统架构、数据库设计、审计与约束引擎规则、AI 咨询降级链等 17 份文档），作为码道对话的结构化输入；码道生成数据模型、JWT 鉴权模块与管理端 API；码道按规则表生成学分审计引擎、约束检查器、先修图算法，人工核验并固化为单元测试；完成学生端四个核心页面，首次发布到华为云 Flexus 实例，实现公网访问；接入华为云 MaaS，联调 Provider 抽象、上下文组装与降级链；开发进度可视化、推荐排课、多学期修读规划等增强功能；完善单元与集成测试，完成端到端验收场景的测试；整理演示材料，发布案例文档与 GitCode 仓库。1.5 资源总览体验完成后请及时释放云端资源（详见第四节），避免产生多余费用。资源名称规格单价华为云码道（CodeArts）代码智能体通用体验版免费云服务器通用计算型 x1（Flexus X1），1 vCPU / 1 GiB / 40 GiB SSD，Ubuntu 22.04¥0.1228/小时（据实际购买页截图）弹性公网 IP全动态 BGP，5 Mbit/s 独享带宽¥0.80/GB 流量华为云 MaaS 推理服务ModelArts Studio DeepSeek 系列 Tokens 套餐包代金券覆盖（领取方式见 2.1 节）账户保证金满足按需计费账户余额下限要求1 元，实操完成后可提现实际总花费取决于云服务器运行时长与 MaaS 调用量，此处仅列出可核实的单价；如需核实完整费用总额，可在华为云费用中心导出账单进行核对。1.6 公网部署地址访问地址：http://121.37.156.117/GitCode 仓库：https://gitcode.com/2301_79350888/xuetu-navigator （默认分支 main）。演示账号：学生 demo / demo123（中等风险）、demo2 / demo123（高风险）；管理员 admin / admin123。使用说明：该地址为部署在华为云 Flexus 云服务器上的训练营评审演示环境。演示账号密码已公开，请勿录入真实个人数据；评审结束并释放弹性公网 IP 后，该地址将停止访问。二、环境和资源准备2.1 领取华为云 MaaS 平台大模型 Tokens登录华为开发者空间，任选以下一种方式领取模型的 API 地址、模型名称与 API Key：方式一：参考案例《华为开发者空间 - ModelArts Studio大模型通用代金券领取使用指导》中的"二、开通MaaS平台大模型"章节内容领取代金券。方式二：参考案例《华为云MaaS平台大模型Tokens领取使用指导》中的"二、领取MaaS平台大模型Tokens"章节内容，领取MaaS平台DeepSeek V3系列大模型Tokens代金券，购买ModelArts Studio DeepSeek Tokens套餐包，开通模型服务。获取到的三项信息仅需填入服务器端的 .env 文件（对应 MAAS_BASE_URL/MAAS_MODEL/MAAS_API_KEY 三个环境变量），前端代码不涉及。后端请求日志仅记录追踪 ID、请求方法、路径、状态码与耗时，调用 MaaS 失败时也只记录截断后的错误信息，密钥本身不会出现在日志中。本案例不在文档中展示具体的 API 地址、模型名称与 Key 取值。2.2 华为云码道（CodeArts）安装部署登录华为云官网完成账号注册与实名认证，并在华为开发者空间内安装激活码道（CodeArts）代码智能体（官网入口见 1.5 节资源表）。本案例开发过程中码道模型选择 GLM 系列，工作模式为智能体对话模式。2.3 本地开发环境搭建无需任何华为云凭据，AI_PROVIDER=mock 模式即可在本地运行全部核心功能，包括学分审计、选课约束、多学期规划与 AI 咨询的降级路径：# 后端：Python 3.11 + FastAPI cd backend && python -m venv .venv && .venv/Scripts/activate # Linux/Mac: source .venv/bin/activate pip install -r requirements.txt cp .env.example .env # 填写 JWT_SECRET（如 openssl rand -hex 32），AI_PROVIDER=mock 即可全功能开发 python -m app.seeds.seed # 建表并写入种子数据（幂等，可重复执行） uvicorn app.main:app --reload --port 8000 # 前端：Vue3 + Vite cd frontend && npm i && npm run dev # localhost:5173，/api 代理到 8000 # 测试（须先激活 backend/.venv，再执行 python -m pytest，二者缺一均会报错，见下表） cd backend && .venv/Scripts/activate python -m pytest --cov=app/services --cov-report=term-missing测试命令有两个前提条件，缺一均会报错：报错现象根因解决方法ModuleNotFoundError: No module named 'app'使用了裸 pytest 命令而非 python -m pytest；裸 pytest（控制台脚本入口）在 Windows 上不会自动将当前目录加入 sys.path改用 python -m pytest，并确认当前目录为 backendModuleNotFoundError: No module named 'tests.conftest'在全局或共享 Python 环境（如 conda base）下运行，该环境的 site-packages 中恰好安装了同名的顶层 tests 包，屏蔽了项目本地的 backend/tests/改为激活并使用项目自身的 backend/.venv，不使用全局 Python 解释器三、构建学途 Navigator 应用3.1 总体架构与设计思路本案例采用规范驱动开发（Spec-Driven Development）方式：先撰写一套完整的详细设计文档，涵盖需求规格、系统架构、数据库设计、各引擎规则、AI 咨询模块、安全与异常处理、测试设计、部署方案与验收标准等方面，再以这套文档为结构化输入，逐阶段驱动码道生成代码，代码经人工核验后固化为测试用例。整个开发周期约 8 天，按四个关键节点推进：完成数据模型冻结、完成首次云端部署、开展增强功能的集中开发、完成代码冻结，随后进入测试与发布收尾。实际提交记录与该计划安排基本吻合，可在版本提交历史中找到同期的开发记录。系统架构：系统架构遵循自上而下的单向依赖约束：routers → services → models，services 层不允许导入 FastAPI（以保证引擎可脱离 HTTP 直接单测），models 层不允许依赖 services。该规则由代码审查维持，可通过"能否在不依赖 FastAPI/TestClient 的情况下直接单测引擎"验证：test_audit.py、test_checker.py、test_planner.py、test_recommender.py、test_prereq_graph.py 五份测试文件均仅导入 app.services 下的模块，构成该约束成立的可执行证据。系统数据模型共设计 11 张表，涵盖用户与鉴权、专业与培养模块、课程与先修关系、学期与开课计划、选课方案、修读规划、AI 对话记录等业务实体，实体关系如下：其中三处相对初版高层架构设计的修正均记录为正式架构决策：先修关系改用关联表而非 JSON 数组（原因：环检测与链深度计算需要结构化的边表）、开课时段改为 JSON 数组以支持一课多时段、学期独立建立字典表（原因：多学期规划需要有序的学期序列）。模块职责：目录职责关键约束backend/app/routers/鉴权、参数校验、调用 services、组装统一响应 {code,message,data}不承载业务规则backend/app/services/审计、约束、推荐、规划、导入、AI 咨询的全部业务规则以纯函数为主，不依赖 FastAPIbackend/app/services/prereq_graph.py先修图的环检测、链深度、后继链长度、最长路径的唯一实现由审计、检查、推荐、规划、导入五处调用，不允许重复实现backend/app/services/advisor/AI Provider 抽象、MaaS 实现、Mock 实现、上下文组装详见 3.4 节backend/app/models/SQLAlchemy ORM 模型，为数据库 schema 的唯一事实来源不依赖 servicesfrontend/src/stores/Pinia 全局状态，登出时统一调用 $reset()详见 3.5.3 节码道 CodeArts Doer 在本地工作区（.codeartsdoer/ 目录，为机器本地配置，不纳入仓库版本控制）针对开发前期的各阶段任务，生成了 spec.md（需求规格）、design.md（设计方案）、tasks.md（编码任务清单）三段式产出，合计约 8700 行。任务清单中的条目与实际代码逐一对应：例如某阶段的 tasks.md 要求"在 backend/app/services/audit.py 中实现 build_passed_map(records, courses)"，对照实际实现（audit.py 第 25–44 行），函数名、签名与行为完全一致，说明码道在需求分析、任务拆解与代码生成环节确实发挥了实际作用。进一步核查显示，该项目未配置 MCP（模型上下文协议，用于让智能体调用外部工具与数据源）服务，也未使用自定义 Skill 或 Project Expert 等扩展能力，码道的使用范围限定在规范驱动开发流程中的规格生成与代码生成环节。设计文档体系要求任何引擎规则的改动均先补充或修改单元测试用例、再修改实现，以避免规则口径漂移。开发过程中人工核验阶段发现并按此流程修复的若干问题，详见 3.5 节"技术难点与解决思路"。3.2 核心功能与用户流程功能完备性矩阵（下表基于源码与路由表逐项核查，按"已实现/未实现"如实标注各功能的完成状态）：功能重要程度端状态证据认证与账号核心功能通用已实现routers/auth.py、security.py（PyJWT + bcrypt）培养方案与课程库管理（含 JSON 导入校验，覆盖 8 类校验规则）核心功能管理端已实现services/importer.py、test_importer.py学期与开课计划管理核心功能管理端已实现routers/admin/semester.py、routers/admin/offering.py已修课程录入与学分审计（含毕业风险）核心功能学生端已实现services/audit.py（行覆盖率 98%）选课模拟与约束检查（含方案保存）核心功能学生端已实现services/checker.py（行覆盖率 96%）AI 学业咨询核心功能学生端已实现services/advisor/*，详见 3.4 节AI 建议一键应用增强功能学生端已实现详见 3.4.6 节学业进度可视化（雷达图/环形图）重要功能学生端已实现components/ModuleRadar.vue、ProgressRing.vue推荐排课（一键推荐）重要功能学生端已实现services/recommender.py（行覆盖率 90%）多学期修读规划重要功能学生端已实现services/planner.py（行覆盖率 92%）审计报告打印友好导出锦上添花学生端未实现已检索前端全目录，未发现打印或导出相关代码操作日志写入核心功能后端已实现models/log.py::log_operation()操作日志查看界面锦上添花管理端未实现路由中无 admin/logs，无对应页面组件小程序壳不适用—明确不做属产品范围裁剪，本案例不涉及移动端小程序项目验收标准明确规定，"重要功能"与"锦上添花"级别中未实施的部分不影响项目整体验收，但需要如实标注其状态；审计报告打印导出与操作日志查看界面均属于这一情况。四个典型使用场景：① 大四学生登录后查看总进度与毕业风险；② 在校学生选课模拟页勾选候选课程，即时查看冲突/缺先修/学分上限提示；③ 在校学生向 AI 咨询排课建议并一键应用；④ 管理员导入培养方案 JSON 或开课 CSV，查看结构化校验报告。典型操作路径（演示学生账号 demo/demo123，软件工程 2023 级第 7 学期）：登录后进入审计看板：环形进度 106/160（66%）、风险徽标"中等风险"、五模块雷达图；2. 进入"选课模拟"页勾选课程，约 300 毫秒内获得逐课冲突/缺先修提示；3. 进入"AI 咨询"页提问选课建议，AI 结合真实缺口数据分点作答并给出"一键应用"建议卡片；4. 进入"修读规划"页生成分学期时间线。3.3 部署项目代码项目结构说明：xuetu-navigator/ ├── backend/ │ ├── app/ │ │ ├── models/ # SQLAlchemy 模型 │ │ ├── schemas/ # Pydantic 请求/响应契约 │ │ ├── routers/ # API 路由（auth/plan/selection/chat/admin等） │ │ ├── services/ # 领域层：audit/checker/planner/recommender/prereq_graph/advisor │ │ └── seeds/ # 种子数据脚本 │ └── tests/ # pytest 测试（158 项） ├── frontend/ │ └── src/{api,stores,router,views,components} ├── deploy/ # setup.sh / deploy.sh / nginx.conf / systemd unit └── docs/ # 17 份详细设计文档 + 案例文档下载源码：git clone https://gitcode.com/2301_79350888/xuetu-navigator.git关键代码讲解——毕业风险五级确定性规则（backend/app/services/audit.py:204-254），按序评估、首个命中即定级，每条结论均带机器可读的 rule 编码：def assess_risk(missing_required, total_gap, remaining_semesters): if remaining_semesters is None: return RiskResult(level="unknown", reasons=[]) reasons, level = [], "low" for mc in missing_required: if mc.chain_remaining_len > remaining_semesters: reasons.append(RiskReason(rule="R1-先修链", message=f"...")) level = "high" if total_gap > remaining_semesters * MAX_SEMESTER_CREDITS: reasons.append(RiskReason(rule="R2-容量", message=f"...")) level = "high" # R3-紧容量 / R4-链贴线 / R5-默认 略 return RiskResult(level=level, reasons=reasons) 约束检查器为四级管道、按序执行且互不短路（backend/app/services/checker.py）：依次执行重复修读检查、时间冲突检查、先修依赖检查、学分上限检查，用户一次性看到全部问题而非逐条重新提交。先修图的环检测、链深度、后继链长度仅在 backend/app/services/prereq_graph.py 一处实现，供审计、检查、推荐、规划、导入校验五处共用，避免多处口径分歧。运行调试：见 2.3 节本地启动命令；实测 python -m pytest --cov=app/services --cov-report=term-missing：3.4 MaaS 融合方案> 本节说明 MaaS 在系统中的协同边界：审计、先修、冲突、风险的判断权始终在确定性规则引擎手中，MaaS 负责结构化结果的自然语言解释与多轮交互。二者的协同机制、失败处理与成本控制均有明确设计与代码实现。3.4.1 判断权与解释权的分离系统设计明确了这样一条架构原则：AI 只做解释、建议、自然语言交互；学分够不够、课冲不冲突、风险几级，一律由确定性引擎产出并作为事实注入；AI 模块不可用时，学分审计与选课约束等核心功能不受影响。该原则体现在三处具体设计中：AI 的输入是审计引擎 run_audit() 计算完成的结构化 JSON，不参与学分或先修关系的计算；AI 的输出如涉及选课建议，采用标记信号加确定性推荐引擎复用的方式（3.4.6 节），不解析 AI 自由文本以获取课程号；AI 完全不可用时，Mock 作为降级路径直接复用同一份结构化审计数据组装摘要。3.4.2 Provider 抽象与降级链# backend/app/services/advisor/base.py @runtime_checkable class AIProvider(Protocol): @property def name(self) -> str: ... def generate(self, messages: list[dict]) -> AIReply: ... def get_provider() -> AIProvider: settings = get_settings() if settings.AI_PROVIDER == "maas": from app.services.advisor.maas import MaaSProvider return MaaSProvider() from app.services.advisor.mock import MockProvider return MockProvider() MaaSProvider.generate()（maas.py:18-56）使用 httpx 以 OpenAI 兼容协议向 {MAAS_BASE_URL}/chat/completions 发起 POST 请求，超时时间读取自 settings.AI_TIMEOUT。请求过程中的任何异常（超时、非 2xx 响应、JSON 解析失败）均被捕获，并按 AI_FALLBACK 配置决定后续处理：默认值 mock 会实例化 MockProvider 作为降级方案并标记 degraded=True。AI_PROVIDER 与 AI_FALLBACK 的默认值均为 mock，即 Mock 是开发阶段的默认路径，而非后续补充的降级分支。3.4.3 上下文组装与裁剪context.py::build_context() 在每次对话时动态组装：固定 System Prompt、一条携带【学生数据】JSON 的 user 消息，以及最近 6 轮历史对话。裁剪策略（预算约 6000 tokens）按影响程度由小到大依次执行：开课列表仅保留当前存在学分缺口的模块对应课程（context.py:184-206），且已通过或在修的具体课程会被显式排除（第 192 行：if c.code in passed_codes or c.code in enrolled_codes: continue）；先修链仅展开缺失必修课对应的部分；历史对话按 6 轮、4 轮、2 轮逐级压缩；审计摘要不参与裁剪，作为回答质量的底线保留。上下文数据均来自当次对 run_audit() 的实时查询结果，而非缓存或静态文本。3.4.4 防幻觉机制的验证System Prompt（context.py:27-37）明确规定"只依据【学生数据】回答；数据中没有的课程、学分、政策，需说明系统数据中没有"“涉及学分缺口、先修关系、毕业风险时，必须引用数据中的数字与课程号，不得自行推算修改”。浏览器实测截图记录了一次验证：学生提问"我想辅修人工智能，我这学期该如何选课？“，AI 回复第一句明确说明"系统数据中没有辅修人工智能的相关课程、学分要求或政策信息，请咨询教务部门了解辅修方案的具体要求”，随后针对"本学期选课建议"给出的课程号均为学生当前学期的实际开课数据。截图如下：同一次对话中，对超出数据范围的问题作出明确说明、对数据范围内的问题引用真实课程号，两种行为均被截图记录。3.4.5 成本与滥用控制措施值代码位置限流5 次/分钟/用户，内存滑动窗口routers/chat.py::check_rate_limit()超时45 秒（调整过程见 3.5.2 节）config.py::AI_TIMEOUT单次回答长度上限1024 tokensconfig.py::AI_MAX_TOKENS用户输入长度上限2000 字符schema 校验，超长返回 40001历史窗口最近 6 轮config.py::AI_HISTORY_ROUNDS密钥存放仅存于服务器端 .env 文件，前端不涉及；请求日志与错误日志均不记录密钥字段middleware.py（请求日志）、advisor/maas.py（调用失败日志）3.4.6 AI 建议一键应用：AI 与确定性推荐引擎的协同该功能体现了 AI 与确定性推荐引擎的协同关系，而非相互替代。AI 在自然语言中给出选课建议后，学生希望能够一键应用到选课模拟页；若直接解析 AI 输出文本以获取课程号，存在模型编造不存在课程号的风险。解决方式是：System Prompt 要求模型仅在本次回答确实给出具体选课建议时，在回答末尾单独一行输出标记 [[SHOW_COURSE_SUGGESTIONS]]；后端仅识别并剥离该标记（不解析建议内容本身），命中后复用与"一键推荐"相同的确定性推荐引擎，重新计算一份结构化候选：# backend/app/routers/chat.py:44-84（节选） def _build_suggested_offerings(user, db) -> list[SuggestedOffering] | None: """AI 判断本次回答给出了选课建议时，复用确定性推荐引擎现算一份结构化候选， 而不是解析 AI 自由文本猜课程号。任何异常都只记日志并返回 None， 绝不能让这个附加功能打断主聊天回复。""" try: ... result = run_recommend(audit=bundle.result, courses=..., offerings=..., target_credits=24.0, credit_limit=settings.MAX_SEMESTER_CREDITS) return [SuggestedOffering(...) for item in result.items] except Exception: logger.warning("构建聊天选课建议失败，已跳过", exc_info=True) return None 前端消费逻辑位于 SelectionView.vue:418-456（applyExternalOfferings）与 RoadmapView.vue:217-263（applyCurrentSemesterCourses）：回复下方渲染建议卡片，点击后跳转选课模拟页，目标页逐条校验课程状态（已通过/已在修/已在候选中的会被过滤并提示），合法课程与已保存候选合并（而非覆盖），自动执行约束检查，由学生自行确认保存。suggested_offerings 不写入数据库，仅在当次新回复中出现，历史消息重新加载后不再显示按钮。AI 相关的测试要求均已在 test_ai_api.py（22 个测试函数）中实现，包括故障注入模拟 httpx 超时、验证 degraded=True 且响应结构不受影响的测试，在代码层面验证了"AI 不可用时核心功能仍可运行"这一架构设计的成立。3.5 技术难点与解决思路以下问题是开发过程中人工核验环节发现的实际问题，均有明确的根因分析与修复方式。3.5.1 PyJWT 与 python-jose 的依赖声明不一致依赖声明与实际导入不一致的问题仅在全新云服务器上首次暴露：本机开发环境与当时较早阶段的 148/150 项测试均未触发该问题（测试总数其后随功能增补持续增加，最终为 158 项，见 3.6 节），但在全新服务器执行 pip install -r requirements.txt 后，seed.py 因 import app.security 触发 ModuleNotFoundError: No module named 'jwt' 而失败。根因在于 requirements.txt 声明的依赖是 python-jose[cryptography]，而 security.py 实际导入的是 jwt——这是 PyJWT 包的模块名，与 python-jose 是两个不同的第三方库。本机 .venv 因历史遗留同时安装了两个包，掩盖了依赖声明的错误。修复方式是将依赖改为直接声明 PyJWT>=2.8。该问题表明，仅在全新、纯净的目标环境完整执行一次部署脚本，才能验证依赖声明的正确性。3.5.2 MaaS 调用超时阈值的调整Mock 模式开发阶段未暴露相关问题，但接入华为云 MaaS 后，浏览器实测显示多数提问被降级为"离线建议"。排查调用耗时发现，失败请求的耗时精确落在超时阈值上——先后精确落在 15230 毫秒、25230 毫秒，表明是 httpx 的超时机制主动截断了仍在进行的生成过程，而非网络波动所致。改用不设超时的方式直连 MaaS 探测，实测生成耗时约 32.23 秒。超时阈值先后调整为 25 秒（仍不充分）、最终调整为 45 秒（结合探测数据确定），前端超时同步调整为 55000 毫秒并预留余量。3.5.3 前端跨用户状态残留同一 SPA 会话内登出学生账号 A、免刷新登录学生账号 B 后，审计看板短暂显示账号 A 的旧数据，直至强制刷新页面才恢复正确；直接使用账号 B 的 token 调用接口验证，后端返回结果始终正确，确认问题源于前端。根因是审计数据的前端缓存带 5 分钟 TTL，登出逻辑此前仅清除 token 与用户信息，未重置任何按用户维度缓存的状态。修复方式是在登出逻辑中对相关 Pinia store 显式调用 $reset()。3.5.4 AI 自由文本对已修课程的误推荐AI 一键应用功能上线后，浏览器实测发现：AI 针对"专业选修还差多少学分、应如何选课"给出的自然语言建议中，包含了学生已经修过并通过的课程，将其作为"本学期可选课程"推荐。根因在于提供给 AI 的开课列表仅按"课程所属模块是否仍有学分缺口"过滤，未排除学生已通过或在修的具体课程——模块整体存在缺口不代表模块内每一门课程都尚未修读。修复方式是补充已通过/在修课程的排除逻辑，并新增回归测试。该问题也印证了"AI 不解析自由文本、结构化推荐单独由确定性引擎生成"这一架构原则的必要性：同期的结构化推荐卡片有独立的过滤逻辑，未受此问题影响。3.5.5 部署环境差异本机（Windows + Git Bash）安装的 rsync 与远程 SSH 子进程交互存在已知兼容性问题，修复方式是改用 tar czf - | ssh ... tar xzf - 管道方式同步文件；远端 pip install 直连境外源时反复超时，修复方式是加入华为云 PyPI 镜像源。两处问题均在首次云端部署时暴露。3.6 测试、异常处理与降级测试设计将测试划分为四层：单元测试（五个纯函数引擎及导入校验）、集成测试（pytest + TestClient + 临时 SQLite）、安全专项（越权访问、无 token 访问、注入类攻击）、端到端（手动清单辅以 Playwright）。测试结果见 3.3 节"运行调试"，158 项全部通过、核心引擎覆盖率 90% 以上。早期测试套件未显式隔离 AI_PROVIDER 环境变量，存在测试执行过程中意外发起 MaaS 请求的风险，修复方式是在 tests/conftest.py 中强制默认使用 Mock。学分审计与选课约束两个核心功能的路由与服务层代码均不依赖 advisor 模块，可通过 import 语句直接核查。安全与异常处理设计的要点包括：鉴权分层（get_current_user/require_student/require_admin）、越权访问返回 40401 而非 403（避免泄露资源存在性）、输入校验分 Schema 层与业务层两层、CSV 公式注入防护、AI 回复 Markdown 渲染使用白名单不允许原始 HTML、统一异常体系携带 trace_id、请求与错误日志不记录密钥等敏感字段。3.7 华为云部署与运行效果部署拓扑：1 GiB 内存机型属于低规格实例，deploy/setup.sh 在部署流程中自动创建 1 GiB swap 作为内存安全余量。首次初始化通过 setup.sh（幂等）完成 Nginx 与 Python 环境安装、systemd 服务注册；日常发布通过 deploy.sh 完成前端构建、tar+ssh 文件同步、远端依赖安装、种子数据初始化与健康检查。访问验证：项值公网地址http://121.37.156.117/MaaS 云端调用AI_PROVIDER=maas 配置下实测 POST /me/chat：HTTP 200，耗时 15.1 秒，degraded:false，回复引用 demo 账号的实际数据账号密码角色用途adminadmin123管理员培养方案与开课计划导入及校验演示demodemo123学生（中等风险场景，第 7 学期）模块缺口与选课冲突演示demo2demo123学生（高风险场景，第 5 学期）多学期规划演示演示账号密码直接展示在公网登录页，便于访问者体验完整功能，请勿在演示账号下录入真实个人数据。根据安全组规则截图核查，入方向规则实际允许 TCP:22（SSH）、TCP:80、TCP:443、TCP:3389（RDP，在 Ubuntu 服务器上无实际用途）及全部 ICMP，源地址均为 0.0.0.0/0，即不限来源 IP，与设计阶段"入方向仅开放 22 端口（限本机 IP）与 80 端口"的规划不符，推测是华为云"Sys-WebServer"默认安全组模板未作收紧所致。该配置存在明显的收紧空间，正式使用前建议将入方向 22、3389 端口的源地址限制为运维人员的固定出口 IP 段。3.8 总结与展望学途 Navigator 使用三个确定性规则引擎（学分审计、约束检查、多学期规划）与一个共用的先修图算法模块，解决"学分是否达标、选课是否冲突、后续如何安排"三个可审计的问题；华为云 MaaS 承担自然语言层面的解释、多轮交互与选课建议信号判断，通过 Provider 抽象与 Mock 优先的降级链，保证 AI 不可用时核心功能不受影响。开发过程以完整的详细设计文档体系为输入，驱动华为云码道（CodeArts）代码智能体逐模块生成代码，经人工核验、158 项单元与集成测试及浏览器实测完成验证，最终部署在华为云 Flexus 实例上提供公网服务，并经云端 MaaS 调用验证。已知局限：审计报告打印导出与操作日志查看界面尚未实现：二者均属"锦上添花"级别的功能，按项目验收标准，该级别的未实施项不影响项目整体验收。安全组配置范围偏宽：22、3389 端口对全部来源地址开放，详见 3.7 节。当前为 HTTP 而非 HTTPS：尚未配置 SSL 证书，属训练营演示场景下的已知取舍。单实例部署，SQLite 单写者模式：并发能力面向演示场景（约 10 并发以内）设计，非面向生产环境的高并发方案。suggested_offerings 不持久化：AI 一键应用建议仅在当次新回复中出现，页面刷新后不再显示。多学期规划不检查未来学期的时间冲突：因未来学期的开课表尚不存在，选修缺口以模块占位学分表达，而非具体课程。后续改进方向：① 收紧安全组入方向规则，评估启用 HTTPS 的可行性；② 完成审计报告打印导出与操作日志查看界面的开发，后端数据已就绪，主要待补充前端页面实现；③ 如后续出现稳定并发需求，评估已预留的 RDS for MySQL 迁移路径。四、释放资源体验完成后应及时释放全部云资源（云服务器、弹性公网 IP），避免产生持续费用；释放前建议导出数据库备份与操作日志归档至本地。释放路径：进入 ECS 实例列表，选择目标实例，点击"更多 → 删除"，在对话框中选择"释放云服务器绑定的公网 IP 地址"，确认释放。五、扩展资料与复现指引5.1 源码仓库GitCode 公开仓库：https://gitcode.com/2301_79350888/xuetu-navigator默认分支：main仓库内容：backend/ 与 frontend/ 包含前后端源码，backend/tests/ 包含自动化测试，deploy/ 包含华为云部署脚本，docs/ 包含完整设计与验收文档。5.2 推荐阅读与复现路径先体验：使用 1.6 节的公网地址和演示账号查看审计看板、选课模拟、AI 咨询与多学期规划。再运行：阅读仓库根目录 README.md，按快速开始说明启动后端与前端；无华为云 MaaS 凭据时可使用 AI_PROVIDER=mock 完成本地体验。理解设计：从 docs/README.md 进入 01–17 号设计文档，依次查看需求、架构、数据模型、API、规则引擎、AI 咨询、安全、测试与部署设计。验证质量：运行 backend/tests/ 自动化测试，并结合 docs/bugs.md 查看已确认缺陷的现象、根因、修复与回归证据。复现部署：参考 deploy/ 脚本和部署设计文档，在华为云 Flexus 云服务器上完成 Nginx、systemd、SQLite 与应用服务配置。5.3 开源内容边界公开仓库提供复现本案例所需的应用源码、测试、部署脚本和设计文档；训练营内部培训材料、个人凭据、本地开发工具配置及运行期数据按 .gitignore 与安全要求不纳入仓库。评审时建议先体验公网环境，再对照仓库中的实现、测试和设计文档核验关键功能。

码道赋能：EduGuide AI智能学习助教系统开发（FastAPI + React）案例介绍本案例依托华为云码道（CodeArts）代码智能体快速完成 EduGuide AI智能学习助教系统项目开发。EduGuide 是一款基于双层数据架构的 AI 驱动学习助手：全局资料库层支持用户上传 PDF/PPTX/DOCX/EPUB 等学习材料或搜索在线书籍，系统自动构建向量知识库（ChromaDB）；项目学习空间层由 AI Agent 自动生成个性化学习路径，通过多轮互动问答、自动测验出题评分、错题追踪与掌握度分析，驱动自适应学习闭环。项目采用 FastAPI + React 19 前后端分离架构，集成 DeepSeek（文本LLM）与 Qwen-VL（视觉模型）双 AI 通道，熔断器保障服务高可用。案例内容 完整案例在线体验地址： EduGuide AI智能学习助教系统（https://kayson.tech/）EduGuide 案例基于 AI 生成搭建，每次生成的项目效果略有不同，如需完整体验该案例可在源码处下载并体验。一、概述1.1 案例介绍本案例依托华为云码道快速完成 EduGuide AI智能学习助教系统项目开发。系统核心能力包括：智能资料管理：支持 PDF/PPTX/DOCX/EPUB/图片上传，AI自动解析提取文本；支持 Z-Library、Project Gutenberg、Library Genesis 三大书源在线搜索导入AI Agent 自适应学习：Agent 多阶段工作流（研究→大纲→教学方案→互动授课），SSE流式实时输出讲解内容多风格互动教学：支持苏格拉底式、隐喻式、严谨式、鼓励式四种教学风格，多轮问答+自由提问智能测验与评分：AI自动生成章节测验（选择/填空/简答/判断/论述），支持图片题AI评分学习报告与错题追踪：掌握度雷达图、薄弱知识点分析、错题重做、学习数据导出案例技术选型：层技术后端FastAPI (Python 3.11+) + SQLAlchemy 2.0 async + Alembic数据库PostgreSQL 16 + Redis 7 + ChromaDBAIDeepSeek (文本) + Qwen-VL (视觉) + sentence-transformers (嵌入)前端React 19 + TypeScript 6 + Ant Design 6 + Zustand 5 + Vite 8部署Nginx (反向代理) + Docker Compose华为云码道（CodeArts）代码智能体：一个理解项目需求，懂得编码之道，善用百器的实干派AI研发专家，开启你的编码自动驾驶模式。本案例中作为核心开发工具，通过智能体模式快速构建 EduGuide AI智能学习助教系统项目代码。EduGuide系统首页效果图1.2 适用对象企业个人开发者高校学生1.3 案例时间本案例总时长预计2小时。1.4 案例流程说明：开发者安装华为云码道 CodeArts 代码智能体；Python 3.11+ 安装配置；Node.js 20+ 安装配置；安装 Docker Desktop（含 Docker Compose）；从 GitHub 克隆 EduGuide 源码到本地；使用华为云码道理解项目代码结构与功能，完成环境配置、数据库初始化与项目启动验证；使用华为云码道进行功能扩展与调试优化。案例流程图1.5 资源总览本案例预计花费如下。资源名称规格 华为云码道（CodeArts）代码智能体专业版 DeepSeek API按量计费 Qwen-VL API按量计费 二、基础环境与资源准备2.1 AI IDE 华为云码道安装部署访问此专属开通链接，免费开通华为云码道（CodeArts）代码智能体体验版，无需复杂配置：一键开通华为云码道体验版！参考案例《AI IDE华为云码道（CodeArts）代码智能体安装部署》完成 Windows 版 AI IDE 华为云码道（CodeArts）代码智能体安装部署。华为云码道IDE主界面2.2 Python 3.11+ 安装配置FastAPI 后端运行依赖 Python 环境。使用快捷键 `Ctrl+Shift+``，新建 AI IDE 终端，输入以下命令查看 Python 环境是否安装？python --version如果没有安装，请参考案例《SKILL快速构建你的Java、Python和Node.js开发环境》一键配置 Python 开发环境。2.3 Node.js 20+ 安装配置React 19 + Vite 8 前端构建依赖 Node.js 环境（需 Node >= 20.19，因为 rolldown 导入 node:util 的 styleText，Node 18 不可用）。使用快捷键 `Ctrl+Shift+``，新建 AI IDE 终端，输入以下命令查看 Node.js 环境是否安装？node --version如果没有安装，请与码道对话，让码道帮助我们下载 Node.js 并配置环境变量。2.4 安装 Docker DesktopDocker Desktop 提供 Docker 引擎与 Docker Compose 编排能力，用于一键启动 PostgreSQL、Redis、后端、前端四个服务。参考 Docker 官方文档安装 Docker Desktop for Windows。安装完成后，在终端验证：docker --versiondocker compose version2.5 获取 AI API 密钥EduGuide 集成双 AI 通道，需分别获取 API 密钥：DeepSeek（文本LLM）：访问 DeepSeek 开放平台注册并获取 API Key，用于讲解生成、测验出题、评分、对话等文本智能能力。Qwen-VL（视觉模型）：访问阿里云百炼平台开通 Qwen-VL 模型并获取 API Key，用于图片资料的文字提取与理解。提示：两个平台均提供免费额度，足够开发调试使用。三、构建 EduGuide 应用3.1 部署项目代码项目技术栈层技术后端FastAPI (Python 3.11+) + SQLAlchemy 2.0 async + Alembic数据库PostgreSQL 16 + Redis 7 + ChromaDBAIDeepSeek (文本) + Qwen-VL (视觉) + sentence-transformers (嵌入)前端React 19 + TypeScript 6 + Ant Design 6 + Zustand 5 + Vite 8部署Nginx (反向代理) + Docker ComposeEduGuide系统架构图从 GitHub 克隆源码在码道终端中，输入以下命令将 EduGuide 源码克隆到本地：git clone https://github.com/HJGisfh/eduguide.gitcd eduguide3.2 码道理解项目代码结构与功能克隆完成后，让码道帮助我们理解整个项目的代码结构与功能。在码道对话框中，输入以下提示词：请分析当前 EduGuide 项目的完整代码结构，包括：1. 后端目录结构（api/models/services/schemas/ai/knowledge/infra 各模块职责）2. 前端目录结构（pages/components/store/services 各模块职责）3. 核心业务流程（用户上传资料→创建项目→Agent工作流→互动学习→测验评估的完整数据流）4. AI双通道架构（DeepSeek文本+Qwen-VL视觉+熔断器机制）5. 向量知识库RAG检索流程码道将自动分析项目代码，输出完整的项目架构说明，帮助开发者快速理解系统设计。码道对话：分析项目代码结构3.2.1 后端代码结构讲解项目入口 backend/main.py：app = FastAPI(title="EduGuide API", version="0.1.0", lifespan=lifespan)app.include_router(materials.router, prefix="/api/v1/materials", tags=["materials"])app.include_router(projects.router, prefix="/api/v1/projects", tags=["projects"])app.include_router(learning.router, prefix="/api/v1/learning", tags=["learning"])app.include_router(quizzes.router, prefix="/api/v1/quizzes", tags=["quizzes"])app.include_router(records.router, prefix="/api/v1/records", tags=["records"])app.include_router(books.router, prefix="/api/v1/books", tags=["books"])app.include_router(user.router, prefix="/api/v1/user", tags=["user"])app.include_router(auth.router, prefix="/api/v1/auth", tags=["auth"])8 个路由模块注册到 FastAPI 应用，统一使用 /api/v1 前缀。lifespan 生命周期管理中启动时检查书源健康状态，关闭时释放数据库连接池。API 路由层 backend/api/（9个文件）：文件职责auth.py用户注册/登录，返回 JWT 令牌user.py用户资料查询、教学风格更新materials.py资料 CRUD、文件上传、重试解析projects.py项目 CRUD、资料关联、Agent 工作流、聊天、测验、报告learning.py学习会话、讲解生成、互动问答、章节总结quizzes.py测验创建/提交/评分records.py学习进度、错题、薄弱点、统计、导出books.py书源搜索/导入deps.py依赖注入（JWT 认证获取当前用户）Service 业务层 backend/services/（11个文件）：文件核心功能auth_service.pybcrypt 密码哈希、JWT 令牌生成、注册/登录user_service.py用户资料查询、教学风格更新material_service.py资料 CRUD、文件解析调度、ChromaDB 清理project_service.py项目 CRUD、资料关联、活动记录、级联删除agent_service.py核心：Agent 多阶段工作流（研究→大纲→方案→授课）learning_service.py学习会话管理、讲解生成、互动问答、进度导航quiz_service.py测验创建/提交、AI 评分、掌握度计算、错题记录project_quiz_service.py项目级测验生成/评分、学习报告（雷达图+薄弱点）record_service.py学习记录查询、错题重做、薄弱点分析、数据导出chat_service.py项目聊天历史、SSE 流式对话（RAG 上下文+教学风格）book_service.py多源书籍搜索（并行）、书籍下载导入（CDN 回退）AI 模块 backend/ai/（7个文件）：文件功能maas_client.py统一 MaaS API 客户端（DeepSeek + Qwen-VL）circuit_breaker.py熔断器模式，AI 通道故障自动切换agent_prompts.pyAgent 工作流 Prompt 模板prompt_manager.pyPrompt 管理器edu_agent.py教育 Agent 编排stream_handler.pySSE 流式响应处理content_filter.py内容安全检查Knowledge 知识库模块 backend/knowledge/（5个文件）：文件功能kb_client.pyChromaDB 向量知识库客户端local_rag.py本地 RAG 检索增强生成text_extractor.py文档文本提取text_splitter.py文本分块处理parse_scheduler.py文档解析调度Models 数据模型层 backend/models/（21个模型类）：核心模型关系链：User → Material → Project → ProjectMaterial → AgentSession → ProjectOutline → TeachingPlan → LessonDesign，以及 Project → Quiz → Question → AnswerRecord → MistakeRecord，Outline → Chapter → Topic → LearningStep → Interaction，Chapter → Mastery。枚举定义 backend/models/enums.py：MaterialFormat：PDF/PPTX/DOCX/TXT/EPUB/PNG/JPG/JPEG/WEBP/BMPMaterialStatus：PARSING/READY/FAILEDSourceType：LOCAL/EXTERNAL/UPLOAD/ZLIBRARY/GUTENBERG/LIBRARY_GENESISTeachingStyle：SOCRATIC/METAPHOR/STRICT/ENCOURAGINGQuizStatus：IN_PROGRESS/COMPLETEDQuestionType：CHOICE/FILL/SHORT_ANSWER/TRUE_FALSE/ESSAYMasteryTrend：IMPROVING/STABLE/DECLININGTopicStatus：主题状态（DRAFT/LEARNING/COMPLETED）ChapterStatus：章节状态（NOT_STARTED/IN_PROGRESS/COMPLETED）StepStatus：学习步骤状态（PENDING/COMPLETED）InteractionType：互动类型（QUESTION/FREE_ASK）3.2.2 前端代码结构讲解路由配置 frontend/src/App.tsx：/login → 登录/注册页/learnspace → 学习空间（默认首页，项目列表）/library → 资料库/booksource → 书源广场/profile → 个人资料/project/:id → 项目详情（Tab导航）页面组件 frontend/src/pages/（6个页面目录）：页面功能Auth/登录/注册页面LearnSpace/学习空间主页（项目列表+新建项目）Library/资料库页面（上传/管理学习资料）BookSourcePlaza/书源广场（搜索/导入在线书籍）Profile/个人资料页面（教学风格设置）ProjectDetail/项目详情（GuidedLearning/LearningOutline/QuizCenter/LearningReport）核心组件 frontend/src/components/（8个组件目录）：组件功能Layout/AppLayout.tsx应用主布局（侧边栏+内容区）ChatWidget/聊天组件（消息列表+输入框+SSE流式显示）QuizRenderer/测验渲染器（5种题型交互式答题）BookSourceModal/书源搜索弹窗OutlineView/学习大纲视图（章节列表+确认/重新生成）NewProjectDrawer/新建项目抽屉StyleModal/教学风格选择弹窗MasteryRadar/掌握度雷达图组件状态管理 frontend/src/store/（7个 Zustand Store）：Store管理状态authStoretoken/userId/username/loading/errormaterialStorematerials[]/loadingprojectStoreprojects[]/currentProjectId/selectedTablearningStorechatMessages[]/isStreaming/agentPhase/agentProgress/outlinequizStorequestions[]/answers{}/results/currentQuizIdrecordStorereport(radarData/weakPoints/suggestions)userStoreprofile/teachingStyle/styleModalVisibleAPI 客户端 frontend/src/services/：apiClient.ts：axios 实例，自动注入 Bearer Token，401 时清除本地 TokensseClient.ts：SSE EventSource 封装，支持自定义事件监听api/index.ts：所有 API 函数集合（Auth/User/Materials/Projects/Books/Chat/Agent/Quiz/Report）3.3 环境配置与项目启动3.3.1 配置环境变量根据 backend/.env.example 创建 backend/.env，需配置以下变量：DATABASE_URL / REDIS_URL：数据库与缓存连接MAAS_API_KEY / MAAS_API_URL / MAAS_MODEL：DeepSeek API 密钥与地址QWEN_API_KEY / QWEN_API_URL / QWEN_MODEL：Qwen-VL API 密钥与地址JWT_SECRET：JWT 签名密钥注意：请将 API Key 替换为步骤 2.5 中获取的实际密钥。3.3.2 Docker Compose 一键启动在码道终端中，输入以下命令启动所有服务并验证：docker compose up -ddocker compose pscurl http://localhost:8000/health预期返回 {"status":"ok"}。终端：Docker Compose启动并验证Docker Compose 将自动启动 4 个服务：服务端口说明backend8000FastAPI 后端frontend80React 前端（Nginx）db15432PostgreSQL 16redis16379Redis 7启动后，后端 Dockerfile 会自动执行： 1. 使用 tomllib 从 pyproject.toml 提取依赖列表并安装 2. 等待 PostgreSQL 就绪 3. 运行 Alembic 数据库迁移（自动创建所有表） 4. 启动 Uvicorn 服务在浏览器中访问 http://localhost 验证前端页面是否正常加载。浏览器：EduGuide前端首页加载成功查看后端日志确认数据库迁移与书源健康检查：docker compose logs backend3.4 核心功能验证3.4.1 用户注册与登录验证在码道对话框中，输入以下提示词：请测试验证用户注册和登录功能：1. 注册用户：用户名 testuser，邮箱 test@example.com，密码 test1234562. 使用注册的用户登录，获取 JWT 令牌3. 使用令牌获取用户资料码道将调用 API 接口完成注册→登录→获取资料的完整流程验证。码道对话：测试注册登录接口浏览器：EduGuide登录页面3.4.2 学习资料上传与解析验证在码道对话框中，输入以下提示词：请测试验证学习资料上传功能：1. 使用上一步获取的 JWT 令牌2. 上传一个 PDF 文件到资料库3. 查看资料列表，确认资料状态从 parsing 变为 ready4. 查看资料详情，确认解析成功注意：资料上传后系统会自动解析并构建向量知识库，首次加载 sentence-transformers 嵌入模型需要下载约 90MB 模型文件。浏览器：资料库页面上传PDF浏览器：资料解析状态从parsing变为ready3.4.3 在线书源搜索验证在码道对话框中，输入以下提示词：请测试验证书源搜索功能：1. 搜索关键词 "machine learning"2. 确认返回搜索结果（书名、作者、来源）3. 选择一本书导入到资料库浏览器：书源广场搜索结果3.4.4 项目创建与 Agent 工作流验证在码道对话框中，输入以下提示词：请测试验证项目学习功能：1. 创建学习项目 "机器学习入门"，关联之前上传的资料2. 启动 Agent 工作流，观察 SSE 流式输出3. 确认 Agent 阶段从 idle → researching → outline_generated4. 确认学习大纲生成成功5. 确认大纲后，观察 Agent 进入 planning → ready 阶段6. 开始章节授课，观察 SSE 流式讲解输出这是系统最核心的功能验证，Agent 工作流完整阶段为：idle → researching → outline_generating → outline_generated → planning → ready → teaching → complete浏览器：学习空间-项目列表浏览器：Agent工作流启动-SSE流式输出浏览器：AI生成学习大纲3.4.5 互动问答与教学风格验证在码道对话框中，输入以下提示词：请测试验证互动问答功能：1. 在授课过程中，发送自由提问 "请解释一下梯度下降的原理"2. 观察 AI 流式回答3. 切换教学风格为 "metaphor"（隐喻式）4. 再次提问，观察回答风格变化浏览器：AI互动授课-SSE流式讲解浏览器：教学风格切换3.4.6 测验生成与评分验证在码道对话框中，输入以下提示词：请测试验证测验功能：1. 为第一章生成测验2. 查看生成的题目（确认包含多种题型）3. 提交答题结果4. 查看 AI 评分结果与评语5. 查看学习报告，确认雷达图数据与薄弱点分析浏览器：AI生成测验-多种题型浏览器：测验评分结果3.4.7 错题追踪与学习记录验证在码道对话框中，输入以下提示词：请测试验证学习记录功能：1. 查看学习进度概览2. 查看错题列表3. 重做一道错题4. 查看薄弱知识点分析5. 查看学习统计数据6. 导出学习数据浏览器：学习报告-掌握度雷达图浏览器：错题列表与薄弱知识点3.5 测试验证3.5.1 后端测试在码道终端中，运行后端测试（108个测试用例）：docker compose exec backend python -m pytest -v --tb=short终端：后端108个测试用例全部通过关键测试文件：文件测试内容tests/test_auth_service.py认证服务测试tests/test_api_auth.py认证 API 测试tests/test_material_service.py资料服务测试tests/test_project_service.py项目服务测试tests/test_api_projects.py项目 API 测试tests/test_chat_service.py聊天服务测试tests/test_quiz_service.py测验服务测试3.5.2 前端测试在码道终端中，运行前端测试（50个测试用例）：cd frontend && npm test终端：前端50个测试用例全部通过关键测试文件：文件测试内容store/__tests__/authStore.test.ts认证 Store 测试store/__tests__/materialStore.test.ts资料 Store 测试store/__tests__/projectStore.test.ts项目 Store 测试store/__tests__/learningStore.test.ts学习 Store 测试store/__tests__/quizStore.test.ts测验 Store 测试components/ChatWidget/__tests__/ChatWidget.test.tsx聊天组件测试components/QuizRenderer/__tests__/QuizRenderer.test.tsx测验渲染器测试3.5.3 前端类型检查docker compose exec frontend npx tsc -b注意：tsc -b 在 Docker 中捕获的类型错误比 vite dev 更严格，务必在推送前端代码前运行。至此，EduGuide 应用的构建与验证已全部完成。四、释放资源本案例所有服务均在本地 Docker 环境中运行，不涉及华为云付费资源。完成后在终端执行以下命令释放本地资源：docker compose down五、扩展资料说明如您在案例实操过程中遇到问题或有改进建议，欢迎到论坛帖评论区反馈，我们会及时响应处理。扩展学习资料： - FastAPI 官方文档：https://fastapi.tiangolo.com/ - React 官方文档：https://react.dev/ - Ant Design 组件库：https://ant.design/ - Docker Compose 文档：https://docs.docker.com/compose/ - 华为云码道（CodeArts）代码智能体：https://codearts.huaweicloud.com/案例关键亮点总结：维度说明构建方向学习智能助教、个性化学习计划核心创新双层架构（资料库+学习空间）+ AI Agent 多阶段工作流 + 双 AI 通道熔断技术特色FastAPI async + SQLAlchemy 2.0 + ChromaDB RAG + SSE 流式 + React 19码道价值代码结构理解、环境配置、功能验证、扩展开发全流程赋能源码获取GitHub 克隆到本地，码道直接分析已有代码进行改造调试 

1 概述1.1 案例介绍汽车经销商的业务链路横跨车辆采购、库存周转、客户跟进、报价审批、订单履约、金融保险、收款结算和车辆交付。传统系统通常按部门分散建设，容易出现数据重复录入、库存状态不一致、利润口径不统一、客户跟进遗漏及交付检查不完整等问题。智车云以 VIN 为车辆唯一主线、以客户旅程为成交主线、以单车利润为经营主线，构建覆盖 DMS、CRM、F&I 和 BI 的一体化汽车经销商智能经营平台。系统提供经营驾驶舱、车辆库存、车型商品、客户线索、报价管理、销售订单、金融保险、收款结算、交付中心、经营分析和 AI 助手等功能，实现从车辆入库、客户跟进、成交签约到交付复盘的完整业务闭环。1.2 建设目标建立以 VIN 为核心的车辆全生命周期台账。实现客户线索分级、跟进计划、公海流转和销售漏斗管理。通过利润防火墙控制低价报价和负利润订单。通过订单状态机规范审批、签约、收款、结算和交付流程。使用幂等机制避免重复创建订单和重复收款。通过标准化检查清单降低车辆交付遗漏风险。通过经营驾驶舱和 AI 助手辅助管理者发现经营异常。借助华为云码道代码智能体提高开发、测试和调试效率。1.3 适用对象本案例适合企业开发者、高校学生、个人开发者以及需要建设汽车经销商 DMS、CRM、进销存或多门店经营系统的研发人员学习和实践。2 系统架构设计2.1 总体架构智车云采用前后端分离和容器化部署架构：前端采用 Vue 3、TypeScript、Element Plus 和 ECharts。后端采用 Java 17、Spring Boot 3、Spring Data JPA 和 Sa-Token。PostgreSQL 负责保存交易和业务数据。Redis 负责登录会话、缓存和临时状态。RabbitMQ 负责领域事件和异步通知。MinIO 负责附件及影像对象存储。Flyway 负责数据库结构和演示数据版本管理。Nginx 负责前端静态资源和 API 反向代理。Docker Compose 负责六个服务的一键编排和启动。2.2 核心业务模块经营驾驶舱：展示在库车辆、新增线索、待交付订单、超期库存、销售漏斗和 AI 经营建议。车辆库存：管理 VIN、库存状态、库龄、采购成本、总成本、合格证和库位信息。客户线索：管理客户来源、意向等级、跟进记录、下一步计划和公海认领。报价与订单：完成报价、利润计算、价格审批、订单签约、结算和交付状态推进。财务结算：管理金融申请、保险、收款、退款、发票和单车利润。交付中心：通过标准化检查清单控制交付过程。经营分析：使用销售漏斗和库存分布图辅助经营决策。AI 助手：支持自然语言查询库存、线索、销售和交付数据，并生成库存优化建议。3 使用华为云码道辅助开发及调试3.1 项目理解与任务拆解项目开发初期，首先使用华为云码道代码智能体读取 README、后端依赖、前端依赖、数据库迁移脚本和 Docker Compose 配置，梳理系统架构、业务域、状态机、金额计算及多租户边界。智能体将复杂需求拆分为“领域实体—数据访问—业务服务—接口—前端页面—自动化测试”等可验证任务，避免一次性生成大量缺少业务约束的代码。3.2 跨文件代码开发在车辆、客户、报价、订单和交付等模块开发中，码道代码智能体辅助完成：Java 领域实体、Repository、Service 和 Controller 的生成与修改。Vue 3 页面、API 封装和 TypeScript 类型定义。前后端字段和统一响应结构校对。车辆与订单状态转换规则补充。报价利润计算和审批前置条件实现。Docker Compose、Nginx 和应用配置检查。3.3 测试补齐与问题定位项目使用码道代码智能体辅助生成和完善 JUnit 5 单元测试，覆盖车辆状态机、订单状态机、客户公海、报价利润和库存成本等关键规则。在前后端联调过程中，将浏览器 Network 请求、响应数据和后端异常日志提供给智能体，定位并解决了 API 路径重复、鉴权头缺失、分页结构不一致、枚举显示异常以及图表数据映射错误等问题。3.4 容器化调试码道代码智能体辅助检查 PostgreSQL、Redis、RabbitMQ、MinIO、后端和前端之间的容器依赖及网络配置，并按照“基础设施—数据库迁移—后端服务—代理转发—前端页面”的顺序定位启动问题。4 核心技术难点与解决思路4.1 车辆与订单状态一致性系统使用显式状态机集中维护车辆和订单的合法转换规则，禁止页面或接口直接修改状态。业务服务在事务中同时更新业务对象和状态日志，防止车辆越级交付、订单终态回退或取消后未释放车辆。4.2 金额精度与利润防火墙交易金额统一使用 PostgreSQL DECIMAL 和 Java BigDecimal，避免浮点误差。系统集中计算车辆成交总额、采购成本、资金占用成本、附加收入、佣金和综合利润。当报价低于保护价或综合利润为负时，系统自动标记风险，并要求填写降价原因和进入价格审批流程。4.3 多租户与数据权限核心业务对象包含 tenantId 和 storeId，通过租户、门店、角色和数据范围控制用户可见数据。Sa-Token 负责登录认证，服务层校验业务对象归属，关键操作同时记录审计日志。4.4 幂等与重复请求订单和收款接口使用 idempotencyKey 识别重复请求，并结合数据库唯一约束和事务避免重复创建订单、重复收款及金额重复累计。4.5 消息可靠性车辆和订单状态变化通过 RabbitMQ 发布领域事件。普通通知发送失败时不阻塞主交易；对于生产环境中的关键事件，可进一步使用 Outbox、消费幂等、失败重试和死信队列提高可靠性。4.6 演示数据设计演示数据不是简单随机生成，而是围绕真实业务故事构建：超过 90 天的车辆触发库存预警。高意向但长期未跟进的客户触发跟进建议。低价报价触发利润审批。待交付订单展示检查清单。已完成订单支撑销售漏斗和经营分析。5 构建与运行5.1 环境要求JDK 17Maven 3.8+Node.js 20Docker DesktopDocker Compose v2建议配置为 4 核 CPU、8 GB 内存5.2 启动项目cd deploy/docker docker compose up -d --build ‘’‘ #6 demo视频链接 https://www.bilibili.com/video/BV1dFg96MEPL/?vd_source=ac4e7ae16e8e5366bd0510ab13603e8d

案例介绍本项目为基于 Vue3+TS 开发的 KPL 赛段晋级推演 Web 工具，内置官方完整赛制规则，适配 18 支战队两阶段常规赛、卡位赛及季后赛对阵链路。支持录入各轮对战大小场战绩，自动核算积分，遍历剩余赛程计算战队组别升降、出线概率。搭载可视化图表展示积分榜单与晋级形势，可完整模拟胜者组、败者组淘汰赛进程。数据本地持久化存储，支持多分组独立运算、推演记录管理，为电竞爱好者提供赛事形势量化分析工具。案例内容一、概述1.1 案例介绍KPL 职业联赛受众规模持续增长，大量电竞爱好者热衷于分析赛事积分走势、推演战队晋级形势，但目前缺少贴合官方完整赛制、可自主录入赛果的可视化推演工具，爱好者仅能依靠人工统计积分，推演门槛高、容易出错。 市场潜力：国内电竞用户规模持续攀升，电竞赛事数据推演、观赛分析类工具需求持续上涨。 用户习惯：赛事周期内大量观众热衷于讨论小组排名、卡位赛形势、季后赛出线可能性，具备较强的数据讨论与分享需求。 场景拓展：满足普通观众观赛推演、赛事博主数据复盘、电竞爱好者赛前形势模拟等多元场景。 依托华为云码道（CodeArts）代码智能体快速生成 Vue3+TS+Vite 全套前端工程，打造 KPL 赛段晋级推演 Web 应用。项目内置官方完整赛制规则，适配 18 支战队常规赛分组循环、卡位赛升降级、胜者组与败者组完整季后赛链路；支持录入对局大小场战绩、自动核算积分、批量推演战队晋级概率，搭配可视化图表展示积分榜单与晋级形势，数据本地持久化存储，为电竞爱好者提供量化赛事分析工具。案例技术选型：华为云码道（CodeArts）代码智能体是基于智能生成、智能问答两大核心能力构建起一套全方位、多层次的智能开发体系。在智能生成方面，它能够依据开发者输入的需求描述，准确且高效地生成高质量代码；智能问答功能则如同开发者身边的专属技术顾问。1.2 适用对象个人开发者 高校学生 电竞数据爱好者1.3 案例时间本案例总时长预计 180 分钟。1.4 案例流程说明： 本地安装华为云码道（CodeArts）代码智能体； 通过码道规范驱动模式开发 KPL 赛段晋级推演 Web 应用。1.5 资源总览本案例预计花费 0 元。  二、基础环境与资源准备2.1 华为云码道安装部署本案例基于华为云码道代码智能体完成开发改造，案例开始前请按照以下两步操作开通并使用工具：2.1.1 一键开通华为云码道体验版2.1.2 AI IDE 华为云码道安装部署参考案例《AI IDE 华为云码道（CodeArts）代码智能体安装部署》完成 Windows 版 AI IDE 华为云码道（CodeArts）代码智能体安装部署。三、通过码道分阶段搭建 KPL 赛段晋级推演 Web 应用3.1 通过规范驱动模式创建需求文档首先我们进入 AI IDE 后点击码道对话框的 规范驱动模式 (Spec-Driven Mode)：根据 需求规格设计 -> 实现方案创建 -> 编码任务规划 -> 任务执行 进行项目开发。3.1.1 需求规格设计接着我们在码道对话框输入以下提示词，让码道进行需求规格说明书的创建   此时，码道会根据步骤首先创建需求规格说明书。这时如果我们对项目有要求，可以对 spec.md 需求规格说明书文件进行编辑。 我们可以把需求内容复制并粘贴进 spec.md 文件内并进行保存。保存过后，我们点击码道对话框的开始实现方案创建。3.1.2 实现方案设计可以看到，码道正在根据我们给出的需求规格文档设计实现方案文档。在创建完成后，我们可以在左侧找到 design.md 实现方案设计文档进行查看，如果有需要调整的地方可以直接进行修改，无问题后点击 全部接受 -> 开始编码任务。3.1.3 编码任务规划在实现方案设计书创建完成后，我们可以在左侧找到 tasks.md 编码任务文档进行查看，如果有需要调整的地方可以直接进行修改，无问题后点击 全部接受 -> 开始任务执行。生成完毕后我们可以看到相应的任务执行顺序。3.1.4 任务执行这时我们可以任意的去修改需求规格设计、实现方案创建、编码任务规划，在以上设计书都完成的前提下，我们可以根据码道提示进行编码任务。可以看到，码道正在进行编码任务。当编码任务全部完成后我们可以点开左侧文件进行查看，如无问题，在码道对话框点击 全部接受。四、启动项目并反馈可能出现的问题在编码任务完成后，我们可以根据启动说明或在码道对话框输入提示词启动项目，此时码道会提示我们如何启动，根据指引进行项目启动即可。注意：在启动项目中或项目运行中可能会出现一些错误，遇到问题的时候我们通过自然语言描述，或者截图的方式把错误直接反馈给码道，让码道帮我们解决就可以了。当我们成功启动后可以看到刚刚创建好的应用了！ 五、反馈改进建议如您在案例实操过程中遇到问题或有改进建议，可以到开发者论坛评论区反馈即可，我们会及时响应处理，谢谢！源码仓库地址：https://github.com/Aria1102/HuaWeiProject

请教一下各位大佬，我从v26.3.4版本升级到v26.6.1版本，发现修改.m文件后不再弹出Diff视图和“全部接收/全部拒绝”按钮，但是修改.py文件还有。请问这个现象是bug吗，后续会不会修复？我要不要退回v26.3.4版本？

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）至本地运行。演示视频也在仓库中，可供参考。五、反馈改进建议如您在案例实操过程中遇到问题或有改进建议，可以到开发者论坛评论区反馈即可，我们会及时响应处理，谢谢！