人道主义
人道主义 是人工智能增强的 观测与仿真平台 在那里，自主的人类互动、交流知识，并生成连贯的历史时间线。它被构建为一个展示项目，展示了全栈架构、契约驱动开发和敏捷交付实践。
它的作用
- 用户认证 --注册、登录、基于JWT的会话，刷新令牌轮换
- 城市管理 --创建城市，播种人口，浏览和搜索
- 确定性模拟 --基于蜱虫的文明模拟，具有可重复的结果（相同的种子⇒ 相同的结果）
- 历史时间线 --源自模拟状态的事件、发明和人工智能丰富的叙述
- 交互式可视化 --实时Pixi.js画布在地图上展示人类，事件提要，发明面板
- MCP集成 --所有后端功能都可以通过模型上下文协议工具进行测试，无需用户界面
建筑
monorepo包含三个应用程序：
| 应用程序 | 技术 | 角色 |
|---|---|---|
| 后端 | Spring Boot 3.5，Java 17 | REST API，auth，模拟引擎，AI丰富，H2/PostgreSQL ready |
| 前端 | Angular 20，TypeScript 5.8 | 带材质的SPA，Pixi.js画布，SSR支持 |
| MCP 服务器 | Node.js、TypeScript | 在MCP stdio上桥接后端API，用于代理驱动的测试和探索 |
技术亮点
认证
- 具有访问+刷新令牌的无状态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 用于丰富人工智能
- 后端 （端口8080）：
cd apps/backend
zsh -lc 'set -a; [ -f .env ] && source .env; set +a; sh ./mvnw spring-boot:run'- 前端 （端口4200）：
cd apps/ui
npm install && npm start- 主控程序 （适用于游标/代理工作流）：
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