Imported from YYY677/Webgis-fullStack (
AGENTS.md). Install upstream withnpx skills add YYY677/Webgis-fullStack. Copyright stays with the author.
WebGIS 全栈项目
项目定位
综合 WebGIS 平台 — 空间数据可视化 + 业务管理系统 + 时空查询分析。 前端 Vue 3 + 后端 Spring Boot + GeoServer + PostgreSQL/PostGIS。
目录结构
Webgis-fullStack/
├── .agents/ # Codex 项目级 skills;与仓库规则一起维护
├── .claude/ # Claude Code 的 settings、skills 与历史 plans
├── .codex/ # Codex 项目级 hooks 配置
├── .github/ # GitHub 自动化配置(当前含 deploy workflow)
├── .git/ # 本地 Git 元数据;不手动编辑、不提交
├── .claudeignore # Claude 的无需读取文件清单
├── .gitignore # Git 忽略规则
├── .gitattributes # Git 文件属性规则
├── frontend/ # Vue 3 + Vite 前端 → 详见 frontend/AGENTS.md
├── backend/ # Spring Boot 3.5 后端 → 详见 backend/CLAUDE.md
├── geoserver/ # GeoServer 配置同步包与 Data Directory 备份
├── data/ # PostgreSQL SQL 备份
├── docs/ # 项目经验、设计和计划文档
└── AGENTS.md # 本文件 — 项目整体级上下文
技术栈速览
| 层 | 技术 | 版本 |
|---|---|---|
| 前端框架 | Vue 3 + TypeScript + Vite | 3.5.32 / ~5.9 / 7.3.1 |
| 地图 2D | OpenLayers | 10.9.0 |
| 地图 3D | CesiumJS (自托管) | 1.142.0 |
| UI 组件 | Element Plus | 2.13.1 |
| 状态管理 | Pinia | 3.0.4 |
| 后端框架 | Spring Boot | 3.5.15 |
| ORM | MyBatis-Plus | 3.5.12 |
| 空间库 | GeoTools | 35.0 (Jakarta EE) |
| 数据库 | PostgreSQL + PostGIS | PostgreSQL 17(本机)/ PostGIS(以实例为准) |
| 地图服务 | GeoServer | 2.26.1(本机) |
关键架构约定
- 后端分层: 模块化 + 内部三层(详见 backend/CLAUDE.md)
- 前端分层: 标准 Vue 项目结构,
pages、api、services、stores、composables、utils(详见 frontend/AGENTS.md) - API 规范: RESTful,统一响应体
{code, message, data} - 认证: JWT 无状态,前端 Header
Authorization: Bearer <token> - 空间数据: PostGIS 存储 → GeoServer 发布 WMS/WFS/WMTS → OpenLayers 与 Cesium 通过前端代理加载;后端负责空间 CRUD、JTS/pgRouting 分析及 GeoServer 管理代理
- 后端空间依赖约束: GeoTools 固定 35.0(Jakarta EE),禁止使用 GeoTools ≤34.x;MyBatis-Plus 固定
mybatis-plus-spring-boot3-starter,不得换用旧版 starter。 - PostGIS Geometry 映射: 不假设 ORM 会自动处理 Geometry;当前项目通过 WKT/SQL 转换读写空间几何,新增映射时沿用该模式或明确实现转换逻辑。
本地开发端口
| 服务 | 端口 |
|---|---|
| 前端 (Vite) | 5173 |
| 后端 (Spring Boot) | 8080 |
| GeoServer | 8081 |
| PostgreSQL | 5432 |
常用命令
# 前端
cd frontend && npm run dev # 启动开发服务器
cd frontend && npm run build # 生产构建
cd frontend && npm run test # Vitest 测试
# 后端
cd backend && mvn spring-boot:run # 启动
cd backend && mvn compile # 编译
cd backend && mvn spring-boot:run -Dspring-boot.run.profiles=dev # 开发模式
Agent 工作方式
- 默认直接在当前工作区开发。
- 仅当当前工作区有需要保护的未提交改动、需要并行维护多个任务,或用户明确要求时,才创建 Git worktree。
- 创建 worktree 前必须说明原因并获得用户确认。
- 已合并的 worktree 不自动删除;仅在用户明确确认后清理。
docs/superpowers/下的设计与计划文档可提交、可推送,作为学习阶段的过程留痕。- 提交前必须在对话中展示文件级变更摘要。
项目经验记忆
docs/memory/是本项目唯一的详细经验库;docs/memory/MEMORY.md是它的总索引。- 涉及 Cesium、OpenLayers、GeoServer、PostGIS、pgRouting、Flyway 或相关排障时,先阅读
docs/memory/MEMORY.md,再按索引打开对应专题。 frontend/AGENTS.md与backend/CLAUDE.md只说明各自工程的结构、命令、接口和硬性依赖,不再重复维护“技术笔记”或“关键坑点”。- 新出现且已验证、可复用、与项目有关的经验:在
docs/memory/新建或更新专题文件,并同步更新docs/memory/MEMORY.md;不要把同一条经验再复制到子工程上下文。 - 当用户说“记录到 memory / 记忆 / 经验”时,均指项目目录
docs/memory/,不得用 Agent 会话临时缓存、工具状态或口头承诺代替写入。
测试与界面验证策略
- 业务逻辑、数据转换、接口、权限、状态管理及可复现的功能缺陷:编写能验证用户可见行为的自动化测试。
- 既有页面的纯 CSS、布局、文案等低风险展示修改:不新增单元测试或源码正则断言,不制作临时原型;直接实现,由 Agent 判断改动风险并完成构建验证,用户在真实页面中确认效果。
- 核心交互、复杂响应式布局或高风险视觉回归:优先浏览器端行为测试或视觉回归测试,不以检查源码字符串替代实际渲染验证。
- 新建页面或开发新界面:仅在视觉方向未确定、存在多个布局方案,或用户明确要求时制作模拟展示;其余情况直接实现并在真实页面验证。
学习项目的轻量改动
- 对仅影响单个学习页面、改动很小且行为直观的内容(如展示文案、注释、静态配置、简单条件或单点坐标转换),可直接实施;不要求新增测试,也不要求执行完整的 superpowers 流程(brainstorming、设计文档、TDD 等)。
- Agent 按风险进行最小必要检查;只有新增模块、大篇幅改动、跨模块、接口/数据库写入、鉴权、复杂空间计算或用户明确要求时,才回到完整测试与设计流程。
Superpowers-ZH 中文增强版
本项目已安装 superpowers-zh 技能框架(20 个 skills)。
核心规则
- 收到任务时,先检查是否有匹配的 skill — 哪怕只有 1% 的可能性也要检查
- 设计先于编码 — 收到功能需求时,先用 brainstorming skill 做需求分析
- 测试先于实现 — 写代码前先写测试(TDD)
- 验证先于完成 — 声称完成前必须运行验证命令
可用 Skills
Skills 位于 .Codex/skills/ 目录,每个 skill 有独立的 SKILL.md 文件。
- brainstorming: 在任何创造性工作之前必须使用此技能——创建功能、构建组件、添加功能或修改行为。在实现之前先探索用户意图、需求和设计。
- chinese-code-review: 中文 review 沟通参考——话术模板、分级标注(必须修复/建议修改/仅供参考)、国内团队常见反模式应对。仅在用户显式 /chinese-code-review 时调用,不要根据上下文自动触发。
- chinese-commit-conventions: 中文 commit 与 changelog 配置参考——Conventional Commits 中文适配、commitlint/husky/commitizen 中文模板、conventional-changelog 中文配置。仅在用户显式 /chinese-commit-conventions 时调用,不要根据上下文自动触发。
- chinese-documentation: 中文文档排版参考——中英文空格、全半角标点、术语保留、链接格式、中文文案排版指北约定。仅在用户显式 /chinese-documentation 时调用,不要根据上下文自动触发。
- chinese-git-workflow: 国内 Git 平台配置参考——Gitee、Coding.net、极狐 GitLab、CNB 的 SSH/HTTPS/凭据/CI 接入差异与镜像同步配置。仅在用户显式 /chinese-git-workflow 时调用,不要根据上下文自动触发。
- dispatching-parallel-agents: 当面对 2 个以上可以独立进行、无共享状态或顺序依赖的任务时使用
- executing-plans: 当你有一份书面实现计划需要在单独的会话中执行,并设有审查检查点时使用
- finishing-a-development-branch: 当实现完成、所有测试通过、需要决定如何集成工作时使用——通过提供合并、PR 或清理等结构化选项来引导开发工作的收尾
- mcp-builder: MCP 服务器构建方法论 — 系统化构建生产级 MCP 工具,让 AI 助手连接外部能力
- receiving-code-review: 收到代码审查反馈后、实施建议之前使用,尤其当反馈不明确或技术上有疑问时——需要技术严谨性和验证,而非敷衍附和或盲目执行
- requesting-code-review: 完成任务、实现重要功能或合并前使用,用于验证工作成果是否符合要求
- subagent-driven-development: 当在当前会话中执行包含独立任务的实现计划时使用
- systematic-debugging: 遇到任何 bug、测试失败或异常行为时使用,在提出修复方案之前执行
- test-driven-development: 在实现任何功能或修复 bug 时使用,在编写实现代码之前
- using-git-worktrees: 当需要开始与当前工作区隔离的功能开发,或在执行实现计划之前使用——通过原生工具或 git worktree 回退机制确保隔离工作区存在
- using-superpowers: 在开始任何对话时使用——确立如何查找和使用技能,要求在任何响应(包括澄清性问题)之前调用 Skill 工具
- verification-before-completion: 在宣称工作完成、已修复或测试通过之前使用,在提交或创建 PR 之前——必须运行验证命令并确认输出后才能声称成功;始终用证据支撑断言
- workflow-runner: 在 Codex / OpenClaw / Cursor 中直接运行 agency-orchestrator YAML 工作流——无需 API key,使用当前会话的 LLM 作为执行引擎。当用户提供 .yaml 工作流文件或要求多角色协作完成任务时触发。
- writing-plans: 当你有规格说明或需求用于多步骤任务时使用,在动手写代码之前
- writing-skills: 当创建新技能、编辑现有技能或在部署前验证技能是否有效时使用
如何使用
当任务匹配某个 skill 时,使用 Skill 工具加载对应 skill 并严格遵循其流程。绝不要用 Read 工具读取 SKILL.md 文件。
如果你认为哪怕只有 1% 的可能性某个 skill 适用于你正在做的事情,你必须调用该 skill 检查。
