AI增强观测模拟平台

人道主义

人道主义 是人工智能增强的 观测与仿真平台 在那里，自主的人类互动、交流知识，并生成连贯的历史时间线。它被构建为一个展示项目，展示了全栈架构、契约驱动开发和敏捷交付实践。

它的作用

• 用户认证 --注册、登录、基于JWT的会话，刷新令牌轮换
• 城市管理 --创建城市，播种人口，浏览和搜索
• 确定性模拟 --基于蜱虫的文明模拟，具有可重复的结果（相同的种子⇒ 相同的结果）
• 历史时间线 --源自模拟状态的事件、发明和人工智能丰富的叙述
• 交互式可视化 --实时Pixi.js画布在地图上展示人类，事件提要，发明面板
• MCP集成 --所有后端功能都可以通过模型上下文协议工具进行测试，无需用户界面

建筑

monorepo包含三个应用程序：

技术亮点

认证

• 具有访问+刷新令牌的无状态JWT
• Spring安全集成
• 路由保护和HTTP拦截器用于令牌附件和401刷新重试
• MCP工具支持无需UI的后端烟雾测试的身份验证流

合同驱动前端和MCP

• 后端作为唯一的真相来源 --OpenAPI规范 /v3/api-docs
• 前端 --使用生成的类型化Angular服务和模型 OpenAPI生成器 (@openapitools/openapi-generator-cli).后端DTO的完整映射 src/app/api/；功能服务包装生成的客户端。
• 主控程序 --生成的类型 openapi-typescript 迭代中使用的每个后端功能都作为MCP工具公开，并且可以进行端到端测试。

MCP首次测试

该项目将MCP视为一级消费面。关键流量（auth→ city → 模拟→ 历史）可通过MCP工具执行，无需前端即可进行后端验证。烟雾流动和合同漂移检查是工作流程的一部分。

文档

Markdown下 docs/ 是 非权威的 背景 行为由代码定义 （并从生成OpenAPI客户端/类型 /v3/api-docs).看 docs/README.md 用于活动文件列表；旧材料生活在 docs/archive/.

项目结构

humanaity/
├── apps/
│   ├── backend/     # Spring Boot API
│   ├── ui/          # Angular frontend
│   └── mcp/         # MCP server
├── docs/
│   ├── milestones.md
│   ├── dev-log.md
│   └── archive/     # Historical docs and sprint material
└── .cursor/         # Rules and skills for AI-assisted development

快速开始

先决条件： Java 17，Node.js 20+，可选 OPENAI_API_KEY 用于丰富人工智能

1. 后端 （端口8080）：

   复制

   cd apps/backend
   zsh -lc 'set -a; [ -f .env ] && source .env; set +a; sh ./mvnw spring-boot:run'
   

2. 前端 （端口4200）：

   复制

   cd apps/ui
   npm install && npm start
   

3. 主控程序 （适用于游标/代理工作流）：

   复制

   cd apps/mcp
   npm install
   zsh -lc 'set -a; [ -f ../backend/.env ] && source ../backend/.env; set +a; npm run dev'
   

合同生成

• 后端OpenAPI： http://localhost:8080/v3/api-docs
• 前端客户端： npm run api:generate 在 apps/ui
• MCP类型： npm run api:generate 在 apps/mcp

进一步阅读

• 后端自述 -API摘要、模块、本地配置
• 前端自述 --功能、路由、OpenAPI客户端使用
• MCP自述文件 --工具、烟雾流、合同工作流程
• 文档索引 --活动文档列表和存档指针