EaiLab/pj0235-eai_agentplatform
11
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
19cf6fb5f2c3dbcc7fd570dacef45581cd463554
pj0235-eai_agentplatform/docs/2026-09-17_对象命名标准化清单.md
T
eaiadminandClaude Code 14f303459e refactor: 后端仓库层收口（A1：课程/产品/素材）+ 收进工作区既有对象化重构 
本提交含两部分。第一部分是本轮工作；第二部分是此前一直留在工作区、
从未提交的对象化重构，与第一部分在文件上互相咬合（internal/repository
整个包都是未跟踪状态，且 api 层已有文件引用它），无法拆成两个可编译的提交。

一、仓库层收口 A1 批（本轮工作）

把 api 层手写的 store.DB 查询收进具名仓库方法，只给真正获益的对象做方法，
不机械包裹全量。本批迁移 22 处裸查询（courses.go 9 / media.go 12 / products.go 1），
新增方法：

- MediaFileRepo.ListByBind / ListForAudit / MarkExtracted
- KnowledgeChunkRepo.CountByMediaFile
- ProductRepo.GetVisibleByID

两条业务口径改由仓库单点持有，避免各处手写漂移：
「只有 approved 素材出现在课程详情」与「已停用产品不在课程详情露出」。

修掉两个真实缺陷：
- ProductRepo.GetByID 缺 Where 条件。此前 GET /api/products/{id} 对任意 id 都返回
  第一条产品、对不存在的 id 返回 200，且 PUT /api/products/{id} 会覆盖第一条产品
  —— 数据损坏级。全仓扫描确认这是唯一一处同型写法。
- ProductRepo.Delete 写 status="deleted"，而 DELETE 处理器文档与回包都声称
  "inactive"，接口在说谎；管理员用 status=all 拉列表会看到前端不认识的状态。
  已对齐为 inactive（与 CourseRepo.Delete 一致）。

删除 8 个零调用且列名不存在的死方法（一调即 SQL 报错）：
- media_file 上的 file_path / file_type / approval_status 三列并不存在，
  GetByPath / ListByType / UpdateStatus 全废
- knowledge_chunk 上的 space_id 列不存在（模型早已改为 knowledge_space_key），
  List / Total / ListBySpaceIDs / DeleteBySpace / SearchByVector 全废
取舍边界：能对当前 schema 跑通的死方法保留，跑不通的删或修。

CourseRepo.List 补齐 status=all 档（此前传给它会当作 status='all' 过滤出空列表）。
该方法此前零调用，现与产品列表语义对齐。

验证：go build ./... 与 go test ./... 全绿；另用真实 HTTP 请求验证 34 项
（课程 17 / 产品 3 / 素材 14），跑在数据库副本与独立 KB_DATA_DIR 上，
含 multipart 真上传 → 审批 → pdftotext 提取 → 分片入库的完整链路。

二、此前未提交的对象化重构（非本轮工作）

- 新增 internal/repository 仓库层、connectors、skills、specialists、xapps、jsonutil，
  model/task_record|task_run|task_artifact、api/task_runtime|action_definition|chat_message
- 删除 api/app_definition、connectors、my_app_center、notification、office_skill、
  export_docx|pptx|xlsx、official_account_* 等，随 XApp/Skill/Specialist/Connector
  可插拔打包方向（AR10/AR11）调整
- 资产目录归位：backend-go/knowledge_source → assets/knowledge/source、
  training_materials → assets/training/materials；README 内相对路径同步加深两级；
  deploy env 补 ASSET_ROOT_DIR 并改 KNOWLEDGE_SOURCE_DIR / TRAINING_MATERIALS_DIR
- 前端新增 skills/ specialists/ connectors/ xapps/ 目录与对应页面

验证：前端 npm run build 通过（7.26s）。

Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-09-19 01:23:51 +08:00

207 lines
6.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 对象命名标准化清单
> 日期：2026-09-17
> 性质：**阶段性清单 / 历史记录**
> 2026-09-18 补注：本文原本记录的是 09-17 当天的待改项。其后代码与规范已大幅收口，**请勿再把本文当作当前现状说明**。当前规范以 `AR09_Object_Naming_Standard.md`、`TOP_CODING_RULES.md` 与代码现实为准。
> 关联文档：
> - `docs/对象标准化与解耦总则.md`
> - `docs/2026-09-17_六层架构与三对象建设重点阶段性复盘.md`
> - `docs/02_Architecture/AR09_Object_Naming_Standard.md`
> - `更名收尾说明.md`
---
## 一、这份清单现在该怎么读
这不是“还有哪些问题没修”的现状文档，
而是一次命名收口行动的**问题发现记录**。
它现在有两个用途：
1. 解释我们当时为什么要动那些名字
2. 给后来者留一份“哪些误导性命名曾真实存在过”的反例库
如果本文与当前代码冲突：
```text
以当前代码 + AR09 + 更名收尾说明 为准
```
---
## 二、09-18 后的总状态
### 1. 已完成的主收口
以下问题已经在 09-18 这轮重构中完成：
| 项 | 09-17 问题 | 09-18 结果 |
|---|---|---|
| 应用对象主词 | `app` 与对象体系冲突 | 已统一为 `xapp` |
| 任务运行命名 | `worker_*` 混杂“专员形态 / 任务运行”两层语义 | 已统一为 `task_*` |
| 技能对象分类字段 | `RoleKind / role_kind` 带旧 `role` 心智 | 已迁到 `ObjectKind / object_kind` |
| AI 用量字段 | `capability` 停留在存储层 | 已迁到 `usage_kind` |
| 工作台入口协议 | 写读参数不一致 | 已统一为 `xapp_specialist / xapp_skill / xapp_prompt`，并抽成共享常量 |
| 静态旧目录变量 | `businessApps`、`availableSkills` | 前者已删；后者已更名 `staticSkillCatalog` |
| 默认聊天入口旧名 | `assistant.js` / `smart_assistant.go` | 已收口到 `chatMessage.js` / `chat_message.go` |
| XApp 中心旧存储 key | `eai-app-center` 长期兼容 | 已改为一次迁移后清旧 key |
### 2. 仍可继续优化，但不再是主阻塞
这些点还值得继续做，但已经不是“命名体系没立住”的主问题：
| 项 | 当前状态 |
|---|---|
| `projectStore.js` 文件名后缀 | 仍是孤例，可继续收口为 `project.js` |
| 某些历史方案文档 | 仍保留旧路径名，需逐步补“历史映射”说明 |
| 一些研究/阶段性文档中的 `app_*` 或 `capability` | 多属历史语境，不应再回流到代码实现 |
---
## 三、09-17 当时识别出的核心问题
下面这些判断在当时是成立的，之所以保留，是因为它们解释了后续为什么要那样改。
### 3.1 旧术语和新术语混用
当时代码里同时混着：
- `role`
- `assistant`
- `specialist`
- `skill`
- `app`
- `worker`
- `capability`
这个判断是对的，也是后续重构的出发点。
### 3.2 文件名、字段名、变量名在讲旧故事
当时最典型的误导项包括：
- `capability_definition.go`
- `RoleKind`
- `businessApps`
- `availableSkills`
- 页面局部 `const app = specialistCatalog.getByKey(...)`
- `assistant.js`
- `workerRuntime.js`
这些名字的共同问题不是“难看”，而是**让对象边界持续失真**。
### 3.3 入口协议写读不对称
09-17 时，应用目录与工作台的 query 参数协议不统一，这不是风格问题，而是功能 bug。
这一条后来直接推动了共享常量 `XAPP_ENTRY_QUERY_KEYS` 的建立。
---
## 四、旧结论与新现实映射表
为了避免后续阅读时把旧清单直接套到现代码，这里给出一张映射表。
| 本文旧说法 | 当前应理解为 |
|---|---|
| `app` 对象 | `xapp` 对象 |
| `appCatalog.js` | `xappCatalog.js` |
| `assistant.js` | `chatMessage.js` |
| `smart_assistant.go` | `chat_message.go` |
| `workerRuntime.js` | `taskRuntime.js` |
| `api/worker.js` | `api/taskRuntime.js` |
| `worker_task.go` / `worker_run.go` / `worker_artifact.go` | `task_record.go` / `task_run.go` / `task_artifact.go` |
| `app_specialist / app_skill / app_prompt` | `xapp_specialist / xapp_skill / xapp_prompt` |
| `RoleKind` | `ObjectKind` |
| `capability`（AI 用量字段） | `usage_kind` |
| `capability_definition.go` | `skill_action_definition.go` |
| `businessApps` | 已删除，不应复活 |
| `availableSkills` | `staticSkillCatalog` |
---
## 五、保留下来的有效原则
这份旧清单里，有些原则到今天仍然完全成立：
### 5.1 对象名必须准确
```text
对象准确性 > 历史兼容性 > 书写简短
```
这条没有过时。
### 5.2 旧词只能留在兼容层
像下面这些旧词：
- `role`
- `worker`
- `capability`
- `assistant`
只有在这三类位置允许保留：
1. 迁移逻辑
2. 迁移测试
3. 历史说明文档
不能再回流到业务模型、API、store、组件和新文档标题。
### 5.3 页面局部变量也会污染认知
`const app = specialistCatalog.getByKey(...)` 这种问题之所以要修，
不是因为会报错，
而是因为它会被后续代码继续照抄。
这一判断现在仍然成立。
### 5.4 入口协议必须抽成共享常量
09-17 的诊断后来被证明完全正确：
```text
能用结构消除的协议分叉，不要靠人工扫描补漏
```
---
## 六、当前建议的阅读顺序
如果现在要继续做命名与对象规范工作，建议按这个顺序看：
1. [AR09_Object_Naming_Standard.md](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/docs/02_Architecture/AR09_Object_Naming_Standard.md)
2. [更名收尾说明.md](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/更名收尾说明.md)
3. 本文
原因很简单：
- `AR09` 讲**当前正式规范**
- `更名收尾说明` 讲**这轮收口后哪些旧名只该留在迁移里**
- 本文只讲**09-17 当时发现过什么问题**
---
## 七、结论
09-17 这份清单的价值不在于“它现在还是不是待办列表”，
而在于它准确记录了当时的混乱来源：
- 对象主词混用
- 路径协议分叉
- 旧变量名继续扩散
- 局部变量失真
- 历史术语假装仍是正式术语
而 09-18 的重构已经把这些主问题大体收口。
所以现在最准确的判断是：
```text
这份文档应被视为历史问题记录，而不是当前待办清单。
```
后续若继续优化，应优先清理仍会误导人的历史文档与剩余孤例，
而不是回头按本文旧路径逐项“照单执行”。
Reference in New Issue View Git Blame Copy Permalink