chore: 以本地为准，上传全部并替换 GitHub
This commit is contained in:
卡若
448
开发文档/2、架构/_智能展开.md
Normal file
448
开发文档/2、架构/_智能展开.md
Normal file
@@ -0,0 +1,448 @@
|
||||
# 🏗️ 架构智能展开引擎 (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` 进行界面原型设计
|
||||
Reference in New Issue
Block a user