# 后端重构与环境隔离规划

## 1. 技术锐评 (Technical Review)

### 1.1 架构层面
*   **环境隔离缺失**：当前主要依赖在 `app.conf` 中手动注释/取消注释代码块来切换环境（如 MySQL 配置、认证地址）。这种方式极易出错，且难以在 CI/CD 流程中自动化。
*   **硬编码泛滥**：
    *   `utils/config.go` 中直接硬编码了生产环境 URL (`https://aqai.shudaodsj.com:22000`)。
    *   `controllers/` 下多个文件（`shudaooss.go`, `hazard.go`, `chroma.go` 等）硬编码了 IP 地址和端口（如 `172.16.17.52:8060`, `172.16.35.50:18080`）。
    *   这导致代码与特定部署环境强耦合，本地开发和测试环境极易连接到错误的服务（如本地连上了生产库）。
*   **部署差异**：由于配置散落在代码中，部署到新环境（如测试环境）需要修改源码并重新编译，违反了 "Build Once, Run Anywhere" 原则。

### 1.2 代码层面
*   **配置管理混乱**：没有统一的配置加载层。有的配置在 `app.conf`，有的在 `utils`，有的直接在 `controllers` 的常量或变量中。
*   **代码位置不当**：
    *   `views/` 目录下存在 `.vue` 文件 (`liushitest.vue`) 和测试 HTML 文件，这些是前端源码或临时测试文件，不应出现在 Go 后端项目的构建目录中。
    *   `chat.go` 被标记为已弃用但仍存在于项目中，造成维护困扰。
*   **可测试性差**：由于依赖硬编码的外部服务地址，单元测试难以在隔离环境下运行（必须有网络且对应 IP 可达）。

### 1.3 重构难度评估
*   **成本**：**中等**。主要工作量在于全局搜索硬编码字符串并替换为配置读取逻辑。
*   **风险**：**低**。只要严格遵循"只读配置，不改逻辑"的原则，业务逻辑不会受影响。主要风险在于遗漏某些隐蔽的硬编码值。

---

## 2. 重构方案 (Refactoring Strategy)

### 2.1 核心原则
1.  **单一数据源**：所有可变参数必须且只能在 `conf/app.conf` 中定义。代码中严禁出现 IP、端口、URL、密钥等字面量。
2.  **环境无侵入**：代码不感知当前是 "dev" 还是 "prod"，它只管读取配置。环境差异由 `app.conf` 的内容决定。
3.  **本地热重载**：利用 Beego 框架自带的 `bee run` 命令实现本地开发热重载。

### 2.2 配置文件管理策略
根据您的要求，采用 **"单文件 + 模板"** 策略：

1.  **`conf/app.conf`**：
    *   **加入 `.gitignore`**。
    *   这是实际生效的配置文件，由开发者/运维在部署时手动创建和维护。
2.  **`conf/app.conf.example`** (新增)：
    *   **加入版本控制 (Git)**。
    *   包含所有必要的配置项 Key，Value 留空或设为默认占位符。
    *   包含详细的注释，说明每个配置项在不同环境（本地、测试、生产）应填写的典型值。

### 2.3 目录结构调整建议
```text
shudao-go-backend/
├── conf/
│   ├── app.conf          (被 git 忽略，实际配置)
│   └── app.conf.example  (新增，配置模板，含所有环境说明)
├── utils/
│   └── config.go         (增强，提供类型安全的配置读取方法)
├── controllers/          (移除硬编码，改为调用 utils.GetConfig)
├── views/                (清理 .vue 和测试 html)
└── ...
```

---

## 3. 执行批次 (Execution Batches)

### 第一批次：配置收拢与标准化 (Configuration Centralization)
**目标**：消除代码中的硬编码，建立统一配置读取机制。

1.  **创建配置模板 `conf/app.conf.example`**：
    *   整理所有散落在 `app.conf` 和代码中的配置项。
    *   为 MySQL, Redis, OSS, YOLO, Chroma, DeepSeek, Qwen 等所有外部服务定义标准的 Key 命名（如 `oss_endpoint`, `yolo_base_url`）。
    *   添加注释说明本地、测试、生产环境的推荐值。
2.  **增强 `utils/config.go`**：
    *   封装 Beego 的 `AppConfig`，提供如 `GetString(key)`, `MustGetString(key)` 等方法，确保配置缺失时能快速报错（Fail Fast）。
    *   **修正**：修改 `GetProxyURL` 方法，不再硬编码域名，而是从配置读取 `base_url`。
3.  **替换 Controller 硬编码**：
    *   `controllers/shudaooss.go`: 替换 `ossEndpoint` 为配置读取。
    *   `controllers/hazard.go`: 替换 `yoloBaseURL` 为配置读取。
    *   `controllers/chroma.go`: 替换 `apiURL` 为配置读取。
    *   `controllers/chat.go`: 替换 `http://172.16.35.50:8000` 等硬编码地址。

### 第二批次：代码清理与环境准备 (Cleanup & Environment Setup)
**目标**：清理废弃代码和无关文件，确保项目纯净。

1.  **清理前端残留**：
    *   删除 `views/liushitest.vue`。
    *   移动或删除 `views/*.html` 测试文件（如果必须保留，移至 `tests/test_data/` 或类似目录，不要混在视图层）。
2.  **处理弃用代码**：
    *   将 `controllers/chat.go` 和 `models/chat.go` 移动到 `_deprecated/` 目录（或直接删除，如果确认无用），并在文件名加 `_deprecated` 后缀，防止误引用。
    *   *注意：如果前端仍依赖某些接口路径，需确认微服务网关是否已接管这些路径。如果后端仍需保留接口定义但转发流量，需重写为代理模式（Proxy）。鉴于您提到"前端有用"，建议先保留文件但清理内部逻辑，或确认前端调用地址已变更。*
3.  **本地热重载验证**：
    *   确认开发环境安装了 `bee` 工具。
    *   使用 `bee run` 启动项目，验证修改文件后是否自动重新编译。

### 第三批次：验证与文档 (Verification)
**目标**：确保重构后各环境功能正常。

1.  **本地环境验证**：
    *   复制 `app.conf.example` 为 `app.conf`。
    *   配置为本地参数（连接本地/开发库）。
    *   启动服务，验证基础接口。
2.  **测试/生产环境验证指南**：
    *   编写 `DEPLOY.md`，说明在新环境部署时如何准备 `app.conf`。

---

## 4. 风险点与检查清单 (Risks & Checklist)

*   [ ] **风险**：`app.conf` 中的 Key 命名变更导致旧代码读取失败。
    *   **对策**：在 `utils/config.go` 中使用 `MustGet` 类方法，如果配置缺失直接 Panic，避免静默失败。
*   [ ] **风险**：OSS 或第三方服务的 URL 拼接逻辑错误（如多加了 `/`）。
    *   **对策**：统一使用 `strings.TrimRight(url, "/")` 处理配置项。
*   [ ] **风险**：`chat.go` 删除导致前端旧版本报错。
    *   **对策**：暂时保留 `chat.go` 文件，但将其内部逻辑标记为 `Deprecated`，并确认前端请求是否已路由到微服务。

## 5. 附录：app.conf.example 预览

```ini
appname = shudao-chat-go
httpport = 22001
runmode = dev

# ==========================================
# 基础配置 (Base Config)
# ==========================================
# 本地: https://127.0.0.1:22000
# 生产: https://aqai.shudaodsj.com:22000
base_url = "https://aqai.shudaodsj.com:22000"

# ==========================================
# 数据库配置 (Database)
# ==========================================
mysql_user = "root"
mysql_pass = "password"
mysql_urls = "127.0.0.1"
mysql_port = "3306"
mysql_db   = "shudao"

# ==========================================
# 外部服务 (External Services)
# ==========================================
# 认证服务
auth_api_url = "http://127.0.0.1:28004/api/auth/verify"

# OSS 配置
oss_endpoint = "http://172.16.17.52:8060"
oss_access_key = "..."
oss_secret_key = "..."
oss_bucket = "gdsc-ai-aqzs"

# 模型服务
deepseek_api_url = "https://api.deepseek.com"
deepseek_api_key = "..."

yolo_base_url = "http://172.16.35.50:18080"
```