# sofrware

**Repository Path**: rowinnyan/sofrware

## Basic Information

- **Project Name**: sofrware
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-06-08
- **Last Updated**: 2026-06-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ICity — 程序化城市生成套件

ICity 包含三个相互配合的部分：

- **Blender 插件** (`__init__.py`) — 在 Blender 4.0+ 中程序化生成 3D 城市场景
- **AI 大模型调用模块** (`llm_client.py`) — 基于 DeepSeek API 的自然语言指令解析，将用户输入映射为 Blender 操作
- **CityGen Web 管理平台** (`frontend/`) — 配套的业务管理系统，用于资产管理、渲染队列、权限控制

---

## 目录

- [Blender 插件](#blender-插件)
  - [架构](#架构)
  - [功能阶段 P1–P7](#功能阶段-p1p7)
  - [关键对象与集合](#关键对象与集合)
  - [开发说明](#开发说明)
- [AI 大模型调用模块](#ai-大模型调用模块)
- [CityGen Web 平台](#citygen-web-平台)
  - [技术栈](#技术栈)
  - [目录结构](#目录结构)
  - [快速启动](#快速启动)
  - [用户角色与权限](#用户角色与权限)
  - [API 端点](#api-端点)

---

## Blender 插件

### 架构

所有代码集中在 `__init__.py`（约 4960 行）。类名前缀 `SNA_`、十六进制后缀均为可视化脚本工具生成的产物，无构建步骤。

**三个运行时全局字典：**

| 变量 | 作用 |
|------|------|
| `all_assets` | 原始资产目录：`{'sna_l': [(分类名, [资产名]), ...]}` |
| `append` | 资产目录的过滤视图（主题、城市资产、景观、材质等） |
| `variables` | UI 枚举和编辑器状态（浏览器选中项、预设列表） |

**面板类（3 个）：**

| 类 | 位置 | 说明 |
|----|------|------|
| `SNA_PT_ICITY_EDITOR_6D34D` | 主编辑面板 | 场景初始化后显示，包含所有城市编辑控件 |
| `SNA_PT_ICITY_754AD` | 入门面板 | YouTube / Discord / 文档链接 |
| `SNA_PT_APPEND_PANEL_590A1` | 资产追加面板 | 资产浏览器 |

### 功能阶段 P1–P7

| 阶段 | 功能 | 面板位置 | 核心操作符 |
|------|------|---------|-----------|
| **P1** | 道路纹理预设 + 路灯 | Road → Assets → Texture / Street Furniture | 属性回调自动触发 |
| **P2** | 场景模板（现代都市 / 古典小镇 / 工业区） | 面板顶部 Template 下拉 | `SNA_OT_Apply_Template_G6A7B` |
| **P3** | 自然语言指令（night/day/rain/fog/建筑高度/树型） | 面板底部文本框 + Send | `SNA_OT_NL_Command_8F23A` |
| **P4** | 静态交通（沿道路放置代理汽车） | Road → Assets → Cars | `SNA_OT_Generate_Cars_I9J0K` |
| **P5** | 生态元素（地形 + 湖泊 + 船只） | 面板底部生态区 | `SNA_OT_Generate_Terrain_L3N4M` / `SNA_OT_Generate_Lake_V9W0X` |
| **P6** | 精确布局（从坐标输入生成道路） | 面板底部精确布局区 | `SNA_OT_Layout_Roads_A5B6C` |
| **P7** | 动态动画（汽车 / 船 / 行人关键帧动画） | 面板底部动画区 | `sna.generate_dynamic_cars_a1b2d` / `_lake_b5c6e` / `_crowds_g9h0i` |

**P7 路径生成算法（四步）：**
1. 找路口：degree ≠ 2 的顶点 → 路口/端点集合
2. 提直线段：在路口之间追踪 degree-2 顶点 → 完整直线链
3. 建简化图：节点=路口，边=链 → 简化道路图
4. 随机游走：在简化图上走 4–15 段，优先直行（点积最大）→ 路线

### 关键对象与集合

点击 `Start` 按钮（`SNA_OT_Start_5209E`）后，从 `assets/ICity start.blend` 追加 `ICity` 集合：

| 对象 | 用途 |
|------|------|
| `ICity Base` | 主可编辑网格，通过面属性分配空间类型（Procedural / Park / Presets） |
| `ICity Road` | 道路网络（材质、车道、人行道） |
| `ICity Road Boundry` | 道路边界定义 |
| `ICity Spces` | 城市地块定义 |
| `ICity Procedural ground` | 地面平面 |
| `ICity building procedural base` | 程序化建筑基础 |
| `ICity Assets` | 隐藏集合，存储资产数据 |

### 开发说明

- **没有测试套件**，修改后需在 Blender 中手动验证
- 热重载：在 Blender Python 控制台执行 `bpy.ops.script.reload()`
- 所有新函数/类使用 `sna_` / `SNA_OT_` 前缀 + 6 位十六进制后缀
- Scene 属性在 `register()` 开头注册，在 `unregister()` 开头删除，**必须一一对应**
- 当前注册状态：类 66 / Scene 属性 46（均已平衡）
- P1–P7 代码段均有 `=== P{N} ... ===` 注释标记，搜索即可定位
- 详细开发指南见 [`CHANGELOG_AND_GUIDE.md`](CHANGELOG_AND_GUIDE.md)

---

## AI 大模型调用模块

`llm_client.py` 封装了对 DeepSeek API 的调用，将用户自然语言指令解析为结构化的 Blender 操作命令。

### 核心类：`LLMClient`

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `api_key` | DeepSeek API 密钥，或从环境变量 `DEEPSEEK_API_KEY` 读取 | — |
| `base_url` | API 地址 | `https://api.deepseek.com` |
| `model` | 使用的模型 | `deepseek-v4-flash` |

### 工作流程

1. 从 `tools.json` 加载工具定义（Tool Call schema）
2. 调用 `client.call(user_input)` 发送用户指令
3. 模型强制返回工具调用，解析为 `{'tool_name': '...', 'arguments': {...}}`
4. 通过 `__init__.py` 中的 `NL_API_COMMAND_MAP` 将短名映射为实际 Blender 操作函数

### 快速使用

```python
from llm_client import LLMClient

client = LLMClient(api_key='YOUR_KEY')  # 或设置环境变量 DEEPSEEK_API_KEY
result = client.call('把场景切换到夜晚')
# {'tool_name': 'set_time', 'arguments': {'time': 'night'}}
```

> 注意：`deepseek-chat` / `deepseek-reasoner` 模型名将于 2026-07-24 弃用，请使用 `deepseek-v4-flash` 或 `deepseek-v4-pro`。

---

## CityGen Web 平台

### 技术栈

| 层 | 技术 |
|----|------|
| 前端框架 | React 19 + TypeScript + Vite |
| 样式 | Tailwind CSS 4 |
| 动画 | Framer Motion |
| 图表 | Recharts |
| 后端 | Express 4.21 + TypeScript |
| 数据库 | SQLite（sql.js，持久化至 `server/data/citygen.db`） |
| 认证 | JWT（24h 过期）+ bcryptjs |

### 目录结构

```
frontend/
├── src/
│   ├── App.tsx                     # 根组件，视图状态机
│   ├── types.ts                    # TypeScript 类型定义
│   ├── components/
│   │   ├── Auth.tsx                # 登录 / 注册 / 重置密码
│   │   ├── MainLayout.tsx          # 主布局（侧边栏 + 内容区）
│   │   ├── DashboardView.tsx       # 数据控制台（指标 + 图表）
│   │   ├── AdminViews.tsx          # 用户管理 + 权限矩阵
│   │   ├── AnalystViews.tsx        # 财务报告 + 行业标准 + 审核
│   │   ├── ModelerViews.tsx        # 资产库 + 渲染队列 + 预览
│   │   ├── ReviewView.tsx          # 场景审核台
│   │   ├── SettingsView.tsx        # 个人设置
│   │   ├── Modal.tsx               # 通用模态框
│   │   └── Toast.tsx               # 通知提示
│   ├── context/
│   │   └── AuthContext.tsx         # 全局认证状态（user / token / 登出）
│   └── lib/
│       ├── api.ts                  # HTTP 客户端（自动附加 Bearer token）
│       └── utils.ts                # 工具函数
├── server/
│   ├── index.ts                    # Express 入口（:3001）
│   ├── db.ts                       # SQLite schema 初始化（7 张表）
│   ├── seed.ts                     # 初始数据填充
│   ├── routes/
│   │   ├── auth.ts                 # 登录 / 注册 / 重置密码
│   │   ├── users.ts                # 用户 CRUD
│   │   ├── reports.ts              # 财务报告
│   │   ├── standards.ts            # 行业标准
│   │   ├── tasks.ts                # 渲染任务
│   │   ├── assets.ts               # 3D 资产
│   │   ├── reviews.ts              # 场景审核
│   │   └── permissions.ts          # 权限矩阵
│   └── middleware/
│       └── auth.ts                 # JWT 认证中间件
└── package.json
```

### 快速启动

```bash
cd frontend

# 1. 安装依赖（首次）
npm install

# 2. 启动开发环境（前端 :3000 + 后端 :3001）
npm run dev:all

# 3. 填充初始数据（可选）
npm run seed
```

浏览器打开 http://localhost:3000，使用下方演示账号登录。

**演示账号：**

| 用户名 | 密码 | 角色 |
|--------|------|------|
| `admin` | `password123` | ADMIN |
| `analyst` | `password123` | ANALYST |
| `modeler` | `password123` | MODELER |

### 用户角色与权限

| 角色 | 权限 | 可访问功能 |
|------|------|-----------|
| ADMIN | 全部（0–5） | 用户管理、权限矩阵、所有业务功能 |
| ANALYST | 2, 3 | 财务报告、行业标准、场景审核 |
| MODELER | 4, 5 | 渲染任务、资产库、场景预览 |
| GUEST | 无 | 仅登录后首页 |

权限矩阵由 ADMIN 在 UI 中实时修改，存储于 `permissions` 表。

### API 端点

所有端点需在 `Authorization` 头携带 `Bearer <token>`。

```
POST   /api/auth/login              登录 → { token, user }
POST   /api/auth/register           注册
GET    /api/auth/me                 获取当前用户

GET    /api/users                   用户列表
POST   /api/users                   创建用户
PUT    /api/users/:id               修改用户
DELETE /api/users/:id               删除用户

GET    /api/permissions             权限矩阵
PUT    /api/permissions             更新权限

GET    /api/assets                  资产列表
POST   /api/assets                  上传资产
DELETE /api/assets/:id              删除资产

GET    /api/tasks                   渲染任务列表
POST   /api/tasks                   创建任务
PUT    /api/tasks/:id               更新进度 / 状态

GET    /api/reports                 财务报告
PUT    /api/reports/:id             更新报告

GET    /api/standards               行业标准
PUT    /api/standards/:id           更新标准

GET    /api/reviews                 审核列表
PUT    /api/reviews/:id             更新审核状态（pending / approved / rejected）
```

---

**Blender 插件详细开发指南** → [`CHANGELOG_AND_GUIDE.md`](CHANGELOG_AND_GUIDE.md)