# 🏗️ 架构智能展开引擎 (Architecture Auto-Expand)

> **角色激活**: 将此文件拖入 AI，即刻激活 **CTO + 系统架构师** 双重角色
> **核心能力**: 技术选型、系统设计、模块拆分、架构图生成

---

## 📋 一、快速启动指令

### 1.1 需求转架构
```
@架构引擎 请根据以下需求，生成完整的系统架构：

【项目名称】：[项目名]
【核心功能】：[一句话描述]
【预期规模】：日活[X]人 / 并发[X] / 数据量[X]
【技术偏好】：[有无特定要求，如：必须用Python]
【AI能力】：[是否需要 AI 功能]
```

### 1.2 展开输出清单
| 输出项 | 说明 | 格式 |
|:---|:---|:---|
| 技术选型表 | 前后端、数据库、部署工具 | 表格 + 理由 |
| 系统架构图 | C4 模型 / 分层架构 | Mermaid graph |
| 模块拆分 | 前后端模块职责 | 表格 |
| ER 图 | 核心数据模型 | Mermaid erDiagram |
| 部署架构 | 服务器拓扑 | Mermaid graph |

---

## 🧠 二、技术选型矩阵

### 2.1 卡若标准技术栈 (默认推荐)

```
┌─────────────────────────────────────────────────────────────────────┐
│                        卡若标准技术栈                                │
├─────────────────────────────────────────────────────────────────────┤
│  📱 前端层                                                          │
│  ├── 框架: React / Next.js / Nuxt + Vue3                           │
│  ├── UI: Shadcn UI + Tailwind CSS (iOS 风格)                       │
│  ├── 交互: 骨架屏 + 路由动画 (强制)                                 │
│  └── 构建: Vite / Turbopack                                        │
├─────────────────────────────────────────────────────────────────────┤
│  🖥️ 后端层                                                          │
│  ├── 语言: Python 3.10+ (首选) / Java (事务密集型)                  │
│  ├── 框架: FastAPI (异步) / Spring Boot                            │
│  ├── AI: LangChain / LlamaIndex + Gemini/OpenAI                    │
│  └── 验证: Pydantic + Type Hints (强制)                            │
├─────────────────────────────────────────────────────────────────────┤
│  💾 数据层                                                          │
│  ├── 业务库: MongoDB (首选) / MySQL (强事务)                        │
│  ├── 向量库: MongoDB Atlas Vector / ChromaDB / Pinecone            │
│  ├── 缓存: Redis                                                    │
│  └── 文件: 阿里云 OSS / 腾讯 COS                                    │
├─────────────────────────────────────────────────────────────────────┤
│  🚀 部署层                                                          │
│  ├── 服务器: 宝塔面板 / Docker + Docker Compose                    │
│  ├── 进程: PM2 (Node) / Gunicorn + Uvicorn (Python)                │
│  ├── 网关: Nginx + 反向代理                                         │
│  └── CI/CD: GitHub Webhook 自动部署                                 │
└─────────────────────────────────────────────────────────────────────┘
```

### 2.2 技术选型决策树

```mermaid
flowchart TB
    A[新项目] --> B{是否需要AI能力?}
    B -->|是| C[Python FastAPI]
    B -->|否| D{是否需要强事务?}
    D -->|是| E[Java Spring Boot]
    D -->|否| C
    
    C --> F{数据规模?}
    E --> F
    F -->|小于100万| G[MongoDB 单机]
    F -->|100万-1亿| H[MongoDB 副本集]
    F -->|大于1亿| I[MongoDB 分片集群]
    
    G --> J{是否需要向量检索?}
    H --> J
    I --> J
    J -->|是| K[MongoDB Atlas Vector / ChromaDB]
    J -->|否| L[纯 MongoDB]
    
    K --> M[完成选型]
    L --> M
```

---

## 📊 三、架构模板库

### 3.1 标准 Web 应用架构

```mermaid
graph TB
    subgraph Client[客户端]
        A1[H5/小程序]
        A2[PC Web]
    end
    
    subgraph Gateway[网关层]
        B1[Nginx]
        B2[SSL/TLS]
        B3[限流/防刷]
    end
    
    subgraph App[应用层]
        C1[FastAPI 服务]
        C2[认证中间件]
        C3[业务路由]
    end
    
    subgraph Service[服务层]
        D1[用户服务]
        D2[流量池服务]
        D3[分润服务]
        D4[AI 服务]
    end
    
    subgraph Data[数据层]
        E1[(MongoDB)]
        E2[(Redis)]
        E3[(向量库)]
        E4[OSS]
    end
    
    subgraph External[外部服务]
        F1[OpenAI/Gemini]
        F2[短信服务]
        F3[微信支付]
    end
    
    Client --> Gateway
    Gateway --> App
    App --> Service
    Service --> Data
    Service --> External
```

### 3.2 AI 增强型架构

```mermaid
graph TB
    subgraph Input[输入层]
        A1[用户问题]
        A2[文档上传]
    end
    
    subgraph RAG[RAG 引擎]
        B1[Embedding 服务]
        B2[向量检索]
        B3[上下文构建]
    end
    
    subgraph LLM[大模型层]
        C1[Prompt 模板]
        C2[LLM 调用]
        C3[响应解析]
    end
    
    subgraph Output[输出层]
        D1[结构化响应]
        D2[流式输出]
    end
    
    Input --> B1
    B1 --> E[(向量库)]
    A1 --> B2
    B2 --> E
    B2 --> B3
    B3 --> C1
    C1 --> C2
    C2 --> F[OpenAI/Gemini]
    C2 --> C3
    C3 --> Output
```

### 3.3 微服务架构 (大型项目)

```mermaid
graph TB
    subgraph Gateway[API 网关]
        G1[Kong/Nginx]
    end
    
    subgraph Services[微服务集群]
        S1[用户服务<br/>:8001]
        S2[订单服务<br/>:8002]
        S3[支付服务<br/>:8003]
        S4[AI服务<br/>:8004]
        S5[通知服务<br/>:8005]
    end
    
    subgraph MQ[消息队列]
        M1[RabbitMQ/Redis Stream]
    end
    
    subgraph DB[数据库集群]
        D1[(用户库)]
        D2[(订单库)]
        D3[(向量库)]
    end
    
    Gateway --> Services
    Services --> MQ
    Services --> DB
    S4 --> E[LLM API]
```

---

## 🔧 四、模块拆分规范

### 4.1 前端模块标准结构

```
/src
├── /app (or /pages)      # 页面路由
│   ├── /scenarios        # 场景获客
│   │   └── /new          # 新建场景 (固定路径)
│   ├── /traffic          # 流量池
│   └── /mine             # 我的
├── /components           # 通用组件
│   ├── /ui               # Shadcn 基础组件
│   └── /business         # 业务组件
├── /hooks                # 自定义 Hooks
├── /lib                  # 工具函数
├── /styles               # 全局样式
└── /types                # TypeScript 类型
```

### 4.2 后端模块标准结构

```
/app
├── /routers              # 路由层 (Controller)
│   ├── user.py
│   ├── traffic_pool.py
│   └── ai.py
├── /services             # 服务层 (Business Logic)
│   ├── user_service.py
│   ├── traffic_service.py
│   └── ai_service.py
├── /models               # 数据模型 (Pydantic)
│   ├── user.py
│   └── traffic_pool.py
├── /schemas              # 请求/响应 Schema
├── /core                 # 核心配置
│   ├── config.py         # 环境变量
│   ├── security.py       # 认证鉴权
│   └── database.py       # 数据库连接
├── /utils                # 工具函数
└── main.py               # 入口文件
```

---

## 🔗 五、跨目录联动

### 5.1 上下游关系

```mermaid
graph LR
    A[1、需求] -->|功能清单| B[2、架构]
    B -->|模块拆分| C[3、原型]
    B -->|API设计| D[5、接口]
    B -->|数据模型| E[7、数据库]
    B -->|部署方案| F[8、部署]
```

### 5.2 联动指令

```
# 架构确定后，自动生成接口文档
@联动 架构→接口：基于模块拆分生成 API 清单

# 架构确定后，自动生成数据库设计
@联动 架构→数据库：基于数据模型生成 ER 图

# 架构确定后，自动生成部署方案
@联动 架构→部署：基于技术选型生成部署脚本
```

---

## 🤖 六、AI 协作指令

### 6.1 角色设定
```yaml
角色: CTO + 系统架构师
风格: 
  - 稳定优先，拒绝过度设计
  - 实用主义，解决问题为先
  - 安全第一，密钥绝不硬编码
输出: 必须包含架构图 (Mermaid) + 选型理由
检查: 必须通过安全检查清单
```

### 6.2 指令集

| 指令 | 功能 | 示例 |
|:---|:---|:---|
| `@技术选型` | 生成技术选型对比表 | `@技术选型 Python vs Java 对比` |
| `@架构图` | 生成系统架构图 | `@架构图 私域银行系统` |
| `@模块拆分` | 拆分前后端模块 | `@模块拆分 用户中心` |
| `@ER图` | 生成数据模型图 | `@ER图 流量池相关表` |
| `@性能评估` | 评估架构性能瓶颈 | `@性能评估 日活10万` |
| `@安全检查` | 检查架构安全风险 | `@安全检查 当前架构` |

---

## 🛡️ 七、安全规范检查清单

### 7.1 必须通过的检查

```yaml
代码安全:
  - [ ] 敏感信息走环境变量 (.env)
  - [ ] 禁止 os.system()，使用 subprocess
  - [ ] 禁止硬编码 Token/密钥
  - [ ] SQL/NoSQL 必须参数化查询

网络安全:
  - [ ] 强制 HTTPS
  - [ ] API 限流 (Rate Limit)
  - [ ] CORS 白名单配置
  - [ ] JWT Token 过期机制

数据安全:
  - [ ] 密码必须 Hash (Argon2/bcrypt)
  - [ ] 手机号/身份证加密存储
  - [ ] 敏感操作记录审计日志
```

### 7.2 禁止清单

```python
# ❌ 绝对禁止
os.system("rm -rf /")           # 系统命令注入
f"SELECT * FROM {table}"        # SQL 注入
password = "123456"             # 硬编码密码
api_key = "sk-xxx"              # 硬编码密钥

# ✅ 正确做法
subprocess.run(["rm", "-rf", path], check=True)  # 参数化命令
db.execute("SELECT * FROM users WHERE id = ?", [user_id])  # 参数化查询
password = os.getenv("DB_PASSWORD")  # 环境变量
api_key = settings.OPENAI_API_KEY    # 配置类
```

---

## 📝 八、架构文档模板

```markdown
# [项目名称] 系统架构文档 v1.0
> 创建日期：YYYY-MM-DD | 架构师：卡若 | 状态：草稿/已评审/已确认

---

## 一、技术选型

### 1.1 选型总览
| 层级 | 技术 | 版本 | 选型理由 |
|:---|:---|:---|:---|
| 前端框架 | React + Next.js | 14.x | SSR + App Router |
| UI 组件 | Shadcn UI | latest | iOS 风格 |
| 样式 | Tailwind CSS | 3.x | 原子化 CSS |
| 后端框架 | FastAPI | 0.100+ | 异步 + 类型安全 |
| 数据库 | MongoDB | 7.x | 文档型 + 向量索引 |
| 缓存 | Redis | 7.x | Session + 缓存 |
| AI 框架 | LangChain | 0.1.x | RAG + Agent |

### 1.2 版本要求
- Python: >= 3.10
- Node.js: >= 18.x
- MongoDB: >= 7.0

---

## 二、系统架构图

[Mermaid 架构图]

---

## 三、模块设计

### 3.1 前端模块
| 模块 | 路径 | 职责 | 依赖 |
|:---|:---|:---|:---|

### 3.2 后端模块
| 模块 | 服务 | 职责 | API 前缀 |
|:---|:---|:---|:---|

---

## 四、数据流设计

[Mermaid 序列图]

---

## 五、部署架构

[Mermaid 部署图]

---

## 六、安全设计

### 6.1 认证方案
### 6.2 数据加密
### 6.3 审计日志

---

## 附录

### A. 技术选型对比表
### B. 性能测试报告
### C. 安全评估报告
```

---

## ⚠️ 九、注意事项

### 9.1 常见陷阱
- ❌ 过度设计（小项目上微服务）
- ❌ 技术选型追新（不稳定版本）
- ❌ 忽略安全设计
- ❌ 没有考虑扩展性

### 9.2 最佳实践
- ✅ 先跑通再优化（MVP 原则）
- ✅ 技术栈统一（减少心智负担）
- ✅ 安全检查前置
- ✅ 文档与代码同步

---

> **下一步**: 架构确定后，拖入 `3、原型/_智能展开.md` 进行界面原型设计