Webgis-fullStack

Imported from YYY677/Webgis-fullStack (AGENTS.md). Install upstream with npx 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                # 本文件 — 项目整体级上下文

技术栈速览

关键架构约定

• 后端分层: 模块化 + 内部三层（详见 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 转换读写空间几何，新增映射时沿用该模式或明确实现转换逻辑。

本地开发端口

常用命令

# 前端
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）。

核心规则

1. 收到任务时，先检查是否有匹配的 skill — 哪怕只有 1% 的可能性也要检查
2. 设计先于编码 — 收到功能需求时，先用 brainstorming skill 做需求分析
3. 测试先于实现 — 写代码前先写测试（TDD）
4. 验证先于完成 — 声称完成前必须运行验证命令

可用 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 检查。