# 更名收尾说明

> 给正在做更名与收口的 AI。**结论：本轮命名与数据结构迁移已经完成闭环；业务代码已切到新口径，旧名只应保留在迁移逻辑、迁移测试与历史说明中。**

---

## 一、当前状态

代码、数据库迁移、种子与前端调用口径现在已经对齐。当前正式口径如下：

| 维度 | 当前正式名 |
|---|---|
| 任务主表 | `task_record` |
| 任务运行表 | `task_run` |
| 任务产物表 | `task_artifact` |
| 我的应用中心表 | `user_xapp_center` |
| 专员形态列 | `specialist_mode` |
| APP 模式列 | `xapp_mode` |
| AI 用量列 | `usage_kind` |
| 技能对象分类列 | `object_kind` |

旧库升级路径也已经补齐，并挂在启动链上、位于 `AutoMigrate` 之前：

- `migrateLegacyTaskRuntimeSchema`
- `migrateLegacyXAppSchema`
- `migrateObjectModeColumns`
- `migrateAIUsageKindColumn`
- `migrateSkillObjectKindColumn`
- `normalizeSkillObjectKinds`

这意味着：

- **业务代码**必须只使用新名；
- **迁移逻辑 / 迁移测试**必须保留旧名，才能识别升级前状态。

---

## 二、此前会挂的点，现已修复

编译器抓不到 —— 表名列名在 Go 里是**字符串**。`go build ./...` 退出码 0，我验过。

### 1. `workbench_overview.go` 的旧表名字符串

```go
artifactQuery := store.DB.Table("worker_artifact").
    Select("worker_artifact.id, worker_artifact.title, ... worker_task.id as task_id, ...").
    Joins("left join worker_task on worker_task.id = worker_artifact.task_id")
...
artifactQuery = artifactQuery.Where("worker_task.owner IN ?", ...)
...
artifactQuery.Order("worker_artifact.created_at DESC, worker_artifact.id DESC")
```

这类引用现在已经改到新口径，不再打旧表名。

### 2. `specialist.go` 的旧列名统计

```go
resp.DW = count("specialist_mode", "dw")
resp.ADW = count("specialist_mode", "adw")
```

这处也已经修完，不再依赖 `worker_type`。

---

## 三、绝对不要全局替换的地方

如果你想 `sed -i 's/worker_/task_/g'`，**这两处会被改坏**：

- **`db.go:117-133`** `migrateLegacyTaskRuntimeSchema` —— 迁移**必须**写旧名，否则它不知道自己要改什么。改成 `task_task` 就永远不生效。
- **`db_migration_test.go:237-276`** —— 测试**必须**断言旧名消失，才能证明迁移真的跑了。

> **判据：这行代码是在「改」名字，还是在「用」名字。**
> 改名字的地方（迁移 + 迁移的测试）保留旧名；用名字的地方（业务代码、API、前端 store、种子、文档规范）必须改新名。

---

## 四、本轮已顺手清掉的账

下面这些本来属于“改名后会继续扩散歧义”的源头，本轮已经补掉：

| 项 | 现状 |
|---|---|---|
| `ai_call_log.capability` | 已迁到 `usage_kind`，并补迁移与测试 |
| `skill_definition` 中的 `assistant` 对象分类 | 已收口，正式值只保留 `specialist / skill` |
| `eai-app-center` 本地存储 key | 前端改为一次迁移后清旧 key，不再长期兼容 |
| `capabilitySchema` fallback | 已移除，统一为 `runtimeSchema` |
| 工作台局部 `appKey` | 已收口为 `workspaceKey`，避免把工作台状态误导成 APP 私有状态 |

---

## 五、文档也同步收口

下面这些文档引用与描述也需要跟代码现实一致，当前已按此原则更新：

- `store/workerRuntime.js` → 现在是 `store/taskRuntime.js`
- `api/assistant.js` / `smart_assistant.go` 这类旧主对话引用 → 现在应对齐 `api/chatMessage.js` / `chat_message.go`
- `capability` 作为 AI 用量字段 → 现在应为 `usage_kind`
- `assistant / specialist / skill` 作为 `object_kind` 值 → 现在应为 `specialist / skill`

历史方案文档如果要保留，也应明确标注：

1. 哪些是**历史阶段描述**
2. 哪些是**当前规范**
3. 哪些旧词是**迁移专用，不可再回流业务代码**

---

## 附：怎么自己复现这些结论

```bash
cd eai_agentplatform/backend-go

# 1. 编译能过 —— 证明编译器帮不上忙
go build ./...            # 退出码 0

# 2. 代码里的正式表名 / 列名
grep -n 'TableName' internal/model/task_*.go
grep -n 'usage_kind' internal/model/ai_call_log.go internal/api/ai_usage.go
grep -n 'object_kind' internal/model/skill_definition.go internal/api/skill_action_definition.go

# 3. 迁移入口都挂在启动链上
sed -n '20,110p' internal/store/db.go

# 4. 迁移测试覆盖了旧库升级场景
go test ./internal/store
```