937 lines
25 KiB
Markdown
937 lines
25 KiB
Markdown
# 技术债务分析报告
|
||
|
||
> 本文档总结了 TravelContentCreator 项目中的主要技术债务，为后续重构提供参考。
|
||
|
||
---
|
||
|
||
## 1. 数据库双端访问问题
|
||
|
||
### 现状
|
||
|
||
Python 端和 Java 端**同时直接访问同一个数据库**，各自维护独立的连接池和查询逻辑。
|
||
|
||
```
|
||
┌─────────────────┐ ┌─────────────────┐
|
||
│ Java 后端 │ │ Python AIGC │
|
||
│ (zwy_picture) │ │ (TravelContent) │
|
||
└────────┬────────┘ └────────┬────────┘
|
||
│ │
|
||
│ 独立连接池 │ 独立连接池
|
||
│ 独立 ORM │ 独立 SQL
|
||
▼ ▼
|
||
┌─────────────────────────────────┐
|
||
│ MySQL (travel_content) │
|
||
└─────────────────────────────────┘
|
||
```
|
||
|
||
### 问题
|
||
|
||
| 问题 | 影响 |
|
||
|-----|------|
|
||
| **数据一致性风险** | 两端可能读到不同状态的数据 |
|
||
| **连接池资源浪费** | 两套连接池，占用更多连接数 |
|
||
| **Schema 同步困难** | 表结构变更需要同时修改两端代码 |
|
||
| **事务边界模糊** | 跨服务操作无法保证事务一致性 |
|
||
| **代码重复** | 相同的查询逻辑在两端各写一遍 |
|
||
|
||
### 涉及文件
|
||
|
||
**Python 端:**
|
||
- `api/services/database_service.py` - 独立的数据库服务
|
||
- `api/services/prompt_service.py` - 也有自己的连接池
|
||
- `infrastructure/database/connection.py` - 新架构的连接管理
|
||
|
||
**Java 端:**
|
||
- `ProductPackageService` - 套餐查询
|
||
- `MaterialService` - 素材查询
|
||
- 各种 Mapper/Repository
|
||
|
||
### 建议方案
|
||
|
||
**方案 A: Python 作为纯算法服务**
|
||
```
|
||
Java 后端 ──HTTP──> Python AIGC
|
||
│ │
|
||
│ │ (无数据库访问)
|
||
▼ │
|
||
MySQL <──────────────┘
|
||
```
|
||
- Python 只接收 Java 传来的完整数据
|
||
- 所有数据库操作由 Java 统一管理
|
||
- Python 变成无状态的计算服务
|
||
|
||
**方案 B: 数据库访问层抽象**
|
||
- 创建统一的数据访问 API (REST/gRPC)
|
||
- 两端通过 API 访问数据，不直接连数据库
|
||
|
||
---
|
||
|
||
## 2. 图片 Base64 传输问题
|
||
|
||
### 现状
|
||
|
||
Java 端从 S3 下载图片 → 转 Base64 → HTTP 传给 Python → Python 解码 → 处理
|
||
|
||
```python
|
||
# poster.py L266
|
||
image_bytes = base64.b64decode(first_image_base64)
|
||
```
|
||
|
||
```java
|
||
// PosterGenerateServiceImpl.java L327
|
||
String base64Image = Base64.getEncoder().encodeToString(imageBytes);
|
||
```
|
||
|
||
### 问题
|
||
|
||
| 问题 | 影响 |
|
||
|-----|------|
|
||
| **带宽浪费** | Base64 编码增加 33% 数据量 |
|
||
| **内存压力** | 大图片需要完整加载到内存 |
|
||
| **延迟增加** | 编解码耗时 + 传输耗时 |
|
||
| **HTTP 请求体过大** | 多图场景可能超过限制 |
|
||
| **重复传输** | 同一图片可能被多次传输 |
|
||
|
||
### 数据示例
|
||
|
||
```
|
||
原始图片: 2MB
|
||
Base64 后: 2.67MB (+33%)
|
||
HTTP 传输: 2.67MB
|
||
Python 解码: 2MB 内存占用
|
||
```
|
||
|
||
### 建议方案
|
||
|
||
**方案 A: URL 引用模式**
|
||
```
|
||
Java 端: 上传图片到 S3，返回 URL
|
||
Python 端: 直接从 S3/CDN 下载
|
||
```
|
||
|
||
**方案 B: 共享存储**
|
||
```
|
||
Java 端: 保存图片到共享目录 /data/images/{id}.png
|
||
Python 端: 直接读取文件路径
|
||
```
|
||
|
||
**方案 C: 图片 ID 引用**
|
||
```json
|
||
{
|
||
"image_ids": [123, 456],
|
||
"image_source": "s3"
|
||
}
|
||
```
|
||
Python 端根据 ID 自行获取图片
|
||
|
||
---
|
||
|
||
## 3. ppid / sid / pid 混乱问题
|
||
|
||
### 现状
|
||
|
||
系统中存在多种 ID 体系，命名不一致，转换逻辑分散：
|
||
|
||
| 缩写 | 全称 | 说明 |
|
||
|-----|------|------|
|
||
| `ppid` | Product Package ID | 套餐 ID (Java 端主用) |
|
||
| `pid` | Product ID | 产品 ID |
|
||
| `sid` | Scenic Spot ID | 景区 ID |
|
||
| `scenic_spot_id` | - | Python 端用的景区 ID |
|
||
| `product_id` | - | Python 端用的产品 ID |
|
||
|
||
### 问题
|
||
|
||
```python
|
||
# topic_generate.py - 需要手动解析 ppid
|
||
if ppid and (not scenic_spot_id or not product_id):
|
||
resolved = await self.db.resolve_ppid(ppid)
|
||
scenic_spot_id = resolved.get('scenic_spot_id')
|
||
product_id = resolved.get('product_id')
|
||
```
|
||
|
||
```java
|
||
// AigcCompatibilityServiceImpl.java - Java 端也要解析
|
||
OriginalIds originalIds = getOriginalIdsByPackageId(packageId);
|
||
```
|
||
|
||
| 问题 | 影响 |
|
||
|-----|------|
|
||
| **命名不一致** | `ppid` vs `packageId` vs `product_package_id` |
|
||
| **解析逻辑重复** | Java 和 Python 各自实现一遍 |
|
||
| **参数传递混乱** | 有时传 ppid，有时传 sid+pid |
|
||
| **向后兼容负担** | 需要同时支持多种参数格式 |
|
||
|
||
### 涉及文件
|
||
|
||
- `domain/aigc/engines/*.py` - 每个引擎都要处理 ppid
|
||
- `infrastructure/database/repositories/product_package_repository.py`
|
||
- `AigcCompatibilityServiceImpl.java`
|
||
|
||
### 建议方案
|
||
|
||
**统一入口点:**
|
||
```
|
||
前端/调用方 ──ppid──> Java 后端 ──解析──> sid + pid ──> Python
|
||
```
|
||
|
||
- 所有 ppid 解析在 Java 端完成
|
||
- Python 端只接收已解析的 `scenic_spot_id` 和 `product_id`
|
||
- 消除 Python 端的 ppid 解析逻辑
|
||
|
||
---
|
||
|
||
## 4. Prompt 拼接方式问题
|
||
|
||
### 现状
|
||
|
||
Prompt 构建分散在多个地方，使用字符串拼接和模板文件混合：
|
||
|
||
```python
|
||
# prompt_builder.py L84-90
|
||
user_prompt = template.build_user_prompt(
|
||
style_content=style_content,
|
||
demand_content=demand_content,
|
||
object_content=object_content,
|
||
product_content=product_content,
|
||
refer_content=refer_content
|
||
)
|
||
```
|
||
|
||
```python
|
||
# prompts.py L64-72
|
||
def build_user_prompt(self, **kwargs) -> str:
|
||
return self.user_template.format(**kwargs)
|
||
```
|
||
|
||
### 问题
|
||
|
||
| 问题 | 影响 |
|
||
|-----|------|
|
||
| **模板文件分散** | 模板在 `prompts/` 目录，配置在 `config/` |
|
||
| **变量命名不统一** | `style_content` vs `style` vs `styleName` |
|
||
| **难以调试** | 最终 prompt 难以追踪 |
|
||
| **版本管理困难** | prompt 变更难以追踪和回滚 |
|
||
| **缺乏验证** | 缺少 prompt 有效性检查 |
|
||
|
||
### 涉及文件
|
||
|
||
- `utils/prompts.py` - 基础模板类
|
||
- `api/services/prompt_builder.py` - 内容 prompt 构建
|
||
- `api/services/prompt_service.py` - prompt 服务
|
||
- `prompts/*.txt` - 模板文件
|
||
|
||
### 建议方案
|
||
|
||
**方案 A: 集中式 Prompt 管理**
|
||
```python
|
||
class PromptRegistry:
|
||
def get_prompt(self, name: str, version: str = "latest") -> PromptTemplate:
|
||
"""从数据库或配置中心获取 prompt"""
|
||
pass
|
||
|
||
def render(self, name: str, context: dict) -> str:
|
||
"""渲染 prompt"""
|
||
pass
|
||
```
|
||
|
||
**方案 B: Prompt 配置化**
|
||
```yaml
|
||
# prompts.yaml
|
||
topic_generate:
|
||
version: "1.2.0"
|
||
system: |
|
||
你是一个旅游营销专家...
|
||
user: |
|
||
请为 {scenic_spot} 生成 {num_topics} 个选题...
|
||
variables:
|
||
- scenic_spot: required
|
||
- num_topics: default=5
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 工具使用方式问题
|
||
|
||
### 现状
|
||
|
||
各种工具类和服务的使用方式不统一：
|
||
|
||
```python
|
||
# 方式1: 全局单例
|
||
from api.dependencies import get_ai_agent, get_config
|
||
|
||
# 方式2: 构造函数注入
|
||
class TopicGenerator:
|
||
def __init__(self, ai_agent: AIAgent, config_manager: ConfigManager):
|
||
|
||
# 方式3: 延迟加载
|
||
def _get_tweet_service(self):
|
||
if self._tweet_service:
|
||
return self._tweet_service
|
||
from api.services.tweet import TweetService
|
||
self._tweet_service = TweetService(...)
|
||
|
||
# 方式4: 直接实例化
|
||
db_service = DatabaseService(config_manager)
|
||
```
|
||
|
||
### 问题
|
||
|
||
| 问题 | 影响 |
|
||
|-----|------|
|
||
| **依赖注入不一致** | 有的用单例，有的用构造函数 |
|
||
| **循环导入风险** | 延迟导入是为了避免循环依赖 |
|
||
| **测试困难** | 难以 mock 依赖 |
|
||
| **生命周期不清晰** | 不知道对象何时创建/销毁 |
|
||
| **资源泄漏风险** | 多个实例可能创建多个连接池 |
|
||
|
||
### 涉及文件
|
||
|
||
- `api/dependencies.py` - 依赖获取
|
||
- `domain/aigc/shared/component_factory.py` - 组件工厂
|
||
- 各个 Engine 类的 `_get_xxx_service()` 方法
|
||
|
||
### 建议方案
|
||
|
||
**统一依赖注入容器:**
|
||
```python
|
||
class Container:
|
||
_instances = {}
|
||
|
||
@classmethod
|
||
def get(cls, service_class: Type[T]) -> T:
|
||
if service_class not in cls._instances:
|
||
cls._instances[service_class] = cls._create(service_class)
|
||
return cls._instances[service_class]
|
||
|
||
@classmethod
|
||
def _create(cls, service_class):
|
||
# 根据类型创建实例，自动解析依赖
|
||
pass
|
||
```
|
||
|
||
**或使用现有框架:**
|
||
- `dependency-injector` 库
|
||
- FastAPI 的 `Depends` 系统
|
||
|
||
---
|
||
|
||
## 总结：优先级建议
|
||
|
||
| 优先级 | 问题 | 原因 |
|
||
|-------|------|------|
|
||
| 🔴 高 | 数据库双端访问 | 数据一致性风险最大 |
|
||
| 🔴 高 | ppid 混乱 | 影响所有 AIGC 调用 |
|
||
| 🟡 中 | 图片 Base64 传输 | 性能问题，但功能正常 |
|
||
| 🟡 中 | Prompt 拼接 | 维护困难，但不影响功能 |
|
||
| 🟢 低 | 工具使用方式 | 代码质量问题，可渐进改进 |
|
||
|
||
---
|
||
|
||
---
|
||
|
||
## 6. 临时文件堆积问题
|
||
|
||
### 现状
|
||
|
||
每次 API 请求都会在 `result/` 目录下创建新的子目录，保存中间产物：
|
||
|
||
```bash
|
||
$ du -sh result/
|
||
943M result/
|
||
|
||
$ ls -1 result/ | wc -l
|
||
6931
|
||
```
|
||
|
||
**6931 个目录，占用 943MB 磁盘空间！**
|
||
|
||
### 问题
|
||
|
||
| 问题 | 影响 |
|
||
|-----|------|
|
||
| **磁盘空间浪费** | 近 1GB 的临时文件 |
|
||
| **无清理机制** | 文件只增不减 |
|
||
| **目录数量过多** | 影响文件系统性能 |
|
||
| **敏感信息泄露风险** | prompt、生成内容可能包含敏感数据 |
|
||
|
||
### 涉及文件
|
||
|
||
- `utils/file_io.py` - `OutputManager` 类
|
||
- 每次请求创建: `result/api_request-{timestamp}-{uuid}/`
|
||
|
||
### 建议方案
|
||
|
||
1. **定期清理**: 添加定时任务清理 7 天前的目录
|
||
2. **按需保存**: 只在调试模式下保存中间产物
|
||
3. **内存缓存**: 中间结果保存在内存，不落盘
|
||
4. **统一存储**: 重要结果上传到 S3，本地只做临时缓存
|
||
|
||
---
|
||
|
||
## 7. 配置分散问题
|
||
|
||
### 现状
|
||
|
||
配置文件分散在多个 JSON 文件中：
|
||
|
||
```
|
||
config/
|
||
├── ai_model.json # AI 模型配置
|
||
├── content_gen.json # 内容生成配置 (含 prompt 路径)
|
||
├── topic_gen.json # 选题生成配置 (含 prompt 路径)
|
||
├── poster_gen.json # 海报生成配置
|
||
├── database.json # 数据库配置
|
||
├── paths.json # 路径配置
|
||
├── resource.json # 资源配置
|
||
├── system.json # 系统配置
|
||
└── cookies.json # Cookie 配置
|
||
```
|
||
|
||
### 问题
|
||
|
||
| 问题 | 影响 |
|
||
|-----|------|
|
||
| **配置分散** | 9 个配置文件，难以统一管理 |
|
||
| **路径嵌套** | 配置中引用其他配置路径 |
|
||
| **环境切换困难** | 没有 dev/prod 环境区分 |
|
||
| **敏感信息明文** | 数据库密码、API Key 明文存储 |
|
||
|
||
### 建议方案
|
||
|
||
1. **环境变量优先**: 敏感信息从环境变量读取
|
||
2. **配置合并**: 合并为 `config.yaml` + 环境覆盖
|
||
3. **配置中心**: 使用 Consul/Nacos 等配置中心
|
||
|
||
---
|
||
|
||
## 8. 错误处理不一致
|
||
|
||
### 现状
|
||
|
||
不同模块的错误处理方式不统一：
|
||
|
||
```python
|
||
# 方式1: 返回 None
|
||
if not topics:
|
||
return None
|
||
|
||
# 方式2: 返回错误字典
|
||
return {"error": str(e)}
|
||
|
||
# 方式3: 抛出异常
|
||
raise ValueError(f"生成海报失败: {str(e)}")
|
||
|
||
# 方式4: 返回元组
|
||
return str(uuid.uuid4()), []
|
||
```
|
||
|
||
### 问题
|
||
|
||
| 问题 | 影响 |
|
||
|-----|------|
|
||
| **调用方难以处理** | 需要检查多种错误格式 |
|
||
| **错误信息丢失** | 有些地方只返回 None |
|
||
| **日志不统一** | 有的记录，有的不记录 |
|
||
| **没有错误码** | 难以区分错误类型 |
|
||
|
||
### 建议方案
|
||
|
||
统一使用 `Result` 模式：
|
||
|
||
```python
|
||
@dataclass
|
||
class Result(Generic[T]):
|
||
success: bool
|
||
data: Optional[T] = None
|
||
error: Optional[str] = None
|
||
error_code: Optional[str] = None
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Prompt 管理方案 (详细设计)
|
||
|
||
### 当前问题分析
|
||
|
||
```
|
||
config/content_gen.json
|
||
└── "content_system_prompt": "resource/prompt/generateContent/system.txt"
|
||
│
|
||
▼
|
||
resource/prompt/generateContent/system.txt (87 行硬编码的 prompt)
|
||
│
|
||
▼
|
||
utils/prompts.py PromptTemplate.format(**kwargs)
|
||
│
|
||
▼
|
||
api/services/prompt_builder.py 拼接变量
|
||
```
|
||
|
||
**问题:**
|
||
1. Prompt 内容硬编码在 `.txt` 文件中
|
||
2. 变量占位符 `{style_content}` 与代码强耦合
|
||
3. 无版本管理，修改后无法回滚
|
||
4. 无 A/B 测试能力
|
||
5. 无效果追踪
|
||
|
||
### 推荐方案: YAML + 版本化 Prompt Registry
|
||
|
||
#### 目录结构
|
||
|
||
```
|
||
prompts/
|
||
├── registry.yaml # Prompt 注册表
|
||
├── topic_generate/
|
||
│ ├── v1.0.0.yaml # 版本化的 prompt
|
||
│ ├── v1.1.0.yaml
|
||
│ └── latest -> v1.1.0.yaml # 软链接
|
||
├── content_generate/
|
||
│ ├── v1.0.0.yaml
|
||
│ └── latest -> v1.0.0.yaml
|
||
└── content_judge/
|
||
└── v1.0.0.yaml
|
||
```
|
||
|
||
#### Prompt 定义格式 (YAML)
|
||
|
||
```yaml
|
||
# prompts/content_generate/v1.0.0.yaml
|
||
meta:
|
||
name: content_generate
|
||
version: "1.0.0"
|
||
description: "小红书风格内容生成"
|
||
author: "team"
|
||
created_at: "2024-12-08"
|
||
|
||
# 模型参数
|
||
model:
|
||
temperature: 0.3
|
||
top_p: 0.5
|
||
presence_penalty: 1.2
|
||
|
||
# 变量定义 (带类型和默认值)
|
||
variables:
|
||
style_content:
|
||
type: string
|
||
required: true
|
||
description: "风格描述"
|
||
demand_content:
|
||
type: string
|
||
required: true
|
||
description: "受众需求"
|
||
object_content:
|
||
type: string
|
||
required: true
|
||
description: "景区/产品信息"
|
||
product_content:
|
||
type: string
|
||
required: false
|
||
default: ""
|
||
description: "产品详情"
|
||
refer_content:
|
||
type: string
|
||
required: false
|
||
default: ""
|
||
description: "参考范文"
|
||
|
||
# System Prompt
|
||
system: |
|
||
你是景区小红书爆款文案策划，你将根据要求创作爆款文案。
|
||
|
||
## 标题创作规则
|
||
1. 必加1个emoji，标题字数18字以内
|
||
2. 有网感，结合所在地
|
||
3. 标题必须结合给出的标题参考格式进行高相似度仿写
|
||
|
||
## 正文创作规则
|
||
1. 以"你"这种有人味的人称代词视角创作
|
||
2. 不要出现"宝子们""姐妹们"这些很假的称呼
|
||
3. 直击用户痛点，有场景感
|
||
4. 分段+分点论述，巧用emoji
|
||
|
||
## 输出格式
|
||
```json
|
||
{
|
||
"title": "标题内容",
|
||
"content": "正文内容",
|
||
"tag": "#标签1 #标签2 ..."
|
||
}
|
||
```
|
||
|
||
# User Prompt (使用 Jinja2 模板语法)
|
||
user: |
|
||
请根据以下材料创作一篇小红书文案：
|
||
|
||
【风格要求】
|
||
{{ style_content }}
|
||
|
||
【目标受众】
|
||
{{ demand_content }}
|
||
|
||
【景区/产品信息】
|
||
{{ object_content }}
|
||
|
||
{% if product_content %}
|
||
【产品详情】
|
||
{{ product_content }}
|
||
{% endif %}
|
||
|
||
{% if refer_content %}
|
||
【参考范文】
|
||
{{ refer_content }}
|
||
{% endif %}
|
||
```
|
||
|
||
#### Prompt Registry 实现
|
||
|
||
```python
|
||
# domain/prompt/registry.py
|
||
|
||
from pathlib import Path
|
||
from typing import Dict, Any, Optional
|
||
import yaml
|
||
from jinja2 import Template
|
||
from dataclasses import dataclass
|
||
|
||
@dataclass
|
||
class PromptConfig:
|
||
"""Prompt 配置"""
|
||
name: str
|
||
version: str
|
||
system: str
|
||
user: str
|
||
variables: Dict[str, Any]
|
||
model: Dict[str, float]
|
||
|
||
class PromptRegistry:
|
||
"""
|
||
Prompt 注册表
|
||
|
||
功能:
|
||
1. 加载和缓存 prompt 配置
|
||
2. 版本管理 (latest, v1.0.0, v1.1.0)
|
||
3. 变量验证
|
||
4. 模板渲染
|
||
"""
|
||
|
||
def __init__(self, prompts_dir: str = "prompts"):
|
||
self.prompts_dir = Path(prompts_dir)
|
||
self._cache: Dict[str, PromptConfig] = {}
|
||
|
||
def get(self, name: str, version: str = "latest") -> PromptConfig:
|
||
"""
|
||
获取 prompt 配置
|
||
|
||
Args:
|
||
name: prompt 名称 (如 "content_generate")
|
||
version: 版本号 (如 "v1.0.0" 或 "latest")
|
||
"""
|
||
cache_key = f"{name}:{version}"
|
||
|
||
if cache_key not in self._cache:
|
||
self._cache[cache_key] = self._load(name, version)
|
||
|
||
return self._cache[cache_key]
|
||
|
||
def render(self, name: str, context: Dict[str, Any],
|
||
version: str = "latest") -> tuple[str, str]:
|
||
"""
|
||
渲染 prompt
|
||
|
||
Returns:
|
||
(system_prompt, user_prompt)
|
||
"""
|
||
config = self.get(name, version)
|
||
|
||
# 验证必填变量
|
||
self._validate_variables(config, context)
|
||
|
||
# 渲染模板
|
||
system = config.system # system 通常不需要变量
|
||
user = Template(config.user).render(**context)
|
||
|
||
return system, user
|
||
|
||
def _load(self, name: str, version: str) -> PromptConfig:
|
||
"""加载 prompt 配置文件"""
|
||
if version == "latest":
|
||
# 读取 latest 软链接指向的文件
|
||
prompt_path = self.prompts_dir / name / "latest.yaml"
|
||
if prompt_path.is_symlink():
|
||
prompt_path = prompt_path.resolve()
|
||
elif not prompt_path.exists():
|
||
# 找最新版本
|
||
versions = sorted(
|
||
(self.prompts_dir / name).glob("v*.yaml"),
|
||
reverse=True
|
||
)
|
||
if versions:
|
||
prompt_path = versions[0]
|
||
else:
|
||
prompt_path = self.prompts_dir / name / f"{version}.yaml"
|
||
|
||
if not prompt_path.exists():
|
||
raise FileNotFoundError(f"Prompt not found: {name}:{version}")
|
||
|
||
with open(prompt_path, 'r', encoding='utf-8') as f:
|
||
data = yaml.safe_load(f)
|
||
|
||
return PromptConfig(
|
||
name=data['meta']['name'],
|
||
version=data['meta']['version'],
|
||
system=data['system'],
|
||
user=data['user'],
|
||
variables=data.get('variables', {}),
|
||
model=data.get('model', {})
|
||
)
|
||
|
||
def _validate_variables(self, config: PromptConfig, context: Dict[str, Any]):
|
||
"""验证变量"""
|
||
for var_name, var_config in config.variables.items():
|
||
if var_config.get('required', False) and var_name not in context:
|
||
raise ValueError(f"Missing required variable: {var_name}")
|
||
|
||
def list_versions(self, name: str) -> list[str]:
|
||
"""列出所有版本"""
|
||
prompt_dir = self.prompts_dir / name
|
||
if not prompt_dir.exists():
|
||
return []
|
||
|
||
versions = []
|
||
for f in prompt_dir.glob("v*.yaml"):
|
||
versions.append(f.stem)
|
||
return sorted(versions, reverse=True)
|
||
```
|
||
|
||
#### 使用示例
|
||
|
||
```python
|
||
# 使用新的 Prompt Registry
|
||
registry = PromptRegistry("prompts")
|
||
|
||
# 渲染 prompt
|
||
system, user = registry.render(
|
||
name="content_generate",
|
||
context={
|
||
"style_content": "攻略风格，实用性强",
|
||
"demand_content": "亲子家庭，周末出游",
|
||
"object_content": "天津冒险湾主题乐园...",
|
||
"product_content": "门票299元/人",
|
||
},
|
||
version="latest" # 或指定 "v1.0.0"
|
||
)
|
||
|
||
# 获取模型参数
|
||
config = registry.get("content_generate")
|
||
model_params = config.model # {"temperature": 0.3, ...}
|
||
```
|
||
|
||
#### 优势
|
||
|
||
| 特性 | 说明 |
|
||
|-----|------|
|
||
| **版本管理** | 每个版本独立文件，可回滚 |
|
||
| **变量验证** | 自动检查必填变量 |
|
||
| **模板语法** | Jinja2 支持条件、循环 |
|
||
| **模型参数绑定** | prompt 和模型参数一起管理 |
|
||
| **缓存** | 加载后缓存，避免重复 IO |
|
||
| **A/B 测试** | 可指定不同版本测试效果 |
|
||
|
||
---
|
||
|
||
## 下一步行动
|
||
|
||
### 已确认的改进方向
|
||
|
||
| # | 问题 | 方案 |
|
||
|---|------|------|
|
||
| 1 | 数据库双端访问 | Python 不访问数据库，改为接口传输 |
|
||
| 2 | 图片 Base64 传输 | 改为 URL/路径引用 |
|
||
| 3 | ppid 混乱 | 放弃 ppid，Java 直接传完整数据 |
|
||
| 4 | Prompt 管理 | YAML + 版本化 Registry |
|
||
| 5 | 依赖注入 | 统一容器模式 |
|
||
| 6 | 临时文件堆积 | 添加清理机制 |
|
||
| 7 | 配置分散 | 合并 + 环境变量 |
|
||
| 8 | 错误处理不一致 | 统一 Result 模式 |
|
||
|
||
### 优先级排序
|
||
|
||
1. **🔴 高优先级** (影响架构)
|
||
- 数据库访问改接口
|
||
- 图片传输改 URL
|
||
- 放弃 ppid
|
||
|
||
2. **🟡 中优先级** (影响维护)
|
||
- Prompt Registry
|
||
- 错误处理统一
|
||
- 临时文件清理
|
||
|
||
3. **🟢 低优先级** (代码质量)
|
||
- 依赖注入优化
|
||
- 配置合并
|
||
|
||
---
|
||
|
||
## 9. 巨型文件问题
|
||
|
||
### 现状
|
||
|
||
部分文件代码量过大，难以维护：
|
||
|
||
| 文件 | 行数 | 问题 |
|
||
|-----|------|------|
|
||
| `demo_refactored_templates.py` | 4219 | 示例/废弃代码？ |
|
||
| `poster_template.py` | 3421 | 根目录下的模板文件 |
|
||
| `api/services/poster.py` | 3031 | 海报服务，职责过多 |
|
||
| `poster/templates/vibrant_template.py` | 1756 | 单个模板文件过大 |
|
||
| `api/services/database_service.py` | 1054 | 数据库服务 |
|
||
| `core/xhs_spider/apis/xhs_pc_apis.py` | 1019 | 小红书 API |
|
||
|
||
### 问题
|
||
|
||
| 问题 | 影响 |
|
||
|-----|------|
|
||
| **难以理解** | 3000+ 行代码难以阅读 |
|
||
| **难以测试** | 职责混杂，难以单元测试 |
|
||
| **合并冲突** | 多人修改同一文件容易冲突 |
|
||
| **废弃代码** | 根目录下的 `poster_template.py` 和 `demo_*.py` 可能是废弃代码 |
|
||
|
||
### 建议方案
|
||
|
||
1. **拆分大文件**: `poster.py` 拆分为多个模块 (已在新架构中完成)
|
||
2. **清理废弃代码**: 删除根目录下的 `poster_template.py`, `demo_*.py`
|
||
3. **单一职责**: 每个类/模块只做一件事
|
||
|
||
---
|
||
|
||
## 10. 重复代码问题
|
||
|
||
### 现状
|
||
|
||
存在多处重复或相似的代码：
|
||
|
||
```
|
||
# 目录重复
|
||
/root/TravelContentCreator/document/ # 旧位置
|
||
/root/TravelContentCreator/core/document/ # 新位置 (重复)
|
||
|
||
# 文件重复
|
||
./document/content_transformer.py
|
||
./core/document/content_transformer.py
|
||
|
||
./document/content_integrator.py
|
||
./core/document/content_integrator.py
|
||
```
|
||
|
||
### 问题
|
||
|
||
| 问题 | 影响 |
|
||
|-----|------|
|
||
| **不知道用哪个** | 两个位置都有相同文件 |
|
||
| **修改遗漏** | 改了一个忘了另一个 |
|
||
| **导入混乱** | `from document.xxx` vs `from core.document.xxx` |
|
||
|
||
### 建议方案
|
||
|
||
1. 确定唯一位置
|
||
2. 删除重复目录
|
||
3. 更新所有 import
|
||
|
||
---
|
||
|
||
## 11. API 路由分散问题
|
||
|
||
### 现状
|
||
|
||
API 路由分散在多个文件中，功能有重叠：
|
||
|
||
```
|
||
api/routers/
|
||
├── aigc.py # 新的统一 AIGC API
|
||
├── tweet.py # 旧的选题/内容 API (470 行)
|
||
├── poster.py # 旧的海报 API
|
||
├── data.py # 数据查询 API
|
||
├── document.py # 文档处理 API
|
||
├── integration.py # 集成 API
|
||
├── content_integration.py # 内容集成 API
|
||
└── prompt.py # 提示词 API
|
||
```
|
||
|
||
### 问题
|
||
|
||
| 问题 | 影响 |
|
||
|-----|------|
|
||
| **功能重叠** | `aigc.py` 和 `tweet.py`/`poster.py` 功能重复 |
|
||
| **命名不一致** | `tweet` vs `content`, `integration` vs `content_integration` |
|
||
| **API 版本混乱** | 没有清晰的 v1/v2 区分 |
|
||
|
||
### 建议方案
|
||
|
||
1. 统一使用 `/api/v2/aigc/*` 作为新入口
|
||
2. 旧 API 标记为 deprecated
|
||
3. 逐步迁移后删除旧路由
|
||
|
||
---
|
||
|
||
## 12. 日志配置问题
|
||
|
||
### 现状
|
||
|
||
每个文件都单独配置 logger：
|
||
|
||
```python
|
||
# 几乎每个 .py 文件都有这行
|
||
logger = logging.getLogger(__name__)
|
||
```
|
||
|
||
但没有统一的日志配置：
|
||
- 日志格式不统一
|
||
- 日志级别分散控制
|
||
- 没有日志轮转
|
||
- 没有结构化日志
|
||
|
||
### 建议方案
|
||
|
||
```python
|
||
# 统一日志配置
|
||
LOGGING_CONFIG = {
|
||
"version": 1,
|
||
"formatters": {
|
||
"default": {
|
||
"format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
|
||
},
|
||
"json": {
|
||
"class": "pythonjsonlogger.jsonlogger.JsonFormatter"
|
||
}
|
||
},
|
||
"handlers": {
|
||
"console": {"class": "logging.StreamHandler", "formatter": "default"},
|
||
"file": {"class": "logging.handlers.RotatingFileHandler", ...}
|
||
},
|
||
"root": {"level": "INFO", "handlers": ["console", "file"]}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 完整问题清单
|
||
|
||
| # | 问题 | 严重程度 | 状态 |
|
||
|---|------|---------|------|
|
||
| 1 | 数据库双端访问 | 🔴 高 | ✅ V2 引擎已解决 |
|
||
| 2 | 图片 Base64 传输 | 🟡 中 | ✅ V2 引擎支持 URL |
|
||
| 3 | ppid 混乱 | 🔴 高 | ✅ 已废弃，Java 端传完整对象 |
|
||
| 4 | Prompt 管理分散 | 🟡 中 | ✅ PromptRegistry 已实现 |
|
||
| 5 | 依赖注入不统一 | 🟢 低 | ✅ Container 已实现 |
|
||
| 6 | 临时文件堆积 | 🟡 中 | ✅ 清理脚本已创建 |
|
||
| 7 | 配置分散 | 🟢 低 | ✅ UnifiedConfig 已实现 |
|
||
| 8 | 错误处理不一致 | 🟡 中 | ✅ 统一异常类已定义 |
|
||
| 9 | 巨型文件 | 🟡 中 | 部分已拆分 |
|
||
| 10 | 重复代码/目录 | 🟡 中 | ✅ document 已统一 |
|
||
| 11 | API 路由分散 | 🟢 低 | 新架构已统一 |
|
||
| 12 | 日志配置缺失 | 🟢 低 | ✅ logging_config 已实现 |
|
||
|
||
> 详细实施记录见 [REFACTORING_IMPLEMENTATION.md](./REFACTORING_IMPLEMENTATION.md)
|