EaiLab/pj0235-eai_agentplatform
11
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9157df40f3ea9b2b5d1a576666e274d3656570d7
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

6.3 KiB
Raw Blame History

对象命名标准化清单

日期：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. 给后来者留一份“哪些误导性命名曾真实存在过”的反例库

如果本文与当前代码冲突：

以当前代码 + 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 对象名必须准确

对象准确性 > 历史兼容性 > 书写简短

这条没有过时。

5.2 旧词只能留在兼容层

像下面这些旧词：

  • role
  • worker
  • capability
  • assistant

只有在这三类位置允许保留：

  1. 迁移逻辑
  2. 迁移测试
  3. 历史说明文档

不能再回流到业务模型、API、store、组件和新文档标题。

5.3 页面局部变量也会污染认知

const app = specialistCatalog.getByKey(...) 这种问题之所以要修， 不是因为会报错， 而是因为它会被后续代码继续照抄。

这一判断现在仍然成立。

5.4 入口协议必须抽成共享常量

09-17 的诊断后来被证明完全正确：

能用结构消除的协议分叉，不要靠人工扫描补漏

六、当前建议的阅读顺序

如果现在要继续做命名与对象规范工作，建议按这个顺序看：

  1. AR09_Object_Naming_Standard.md
  2. 更名收尾说明.md
  3. 本文

原因很简单：

  • AR09 讲当前正式规范
  • 更名收尾说明 讲这轮收口后哪些旧名只该留在迁移里
  • 本文只讲09-17 当时发现过什么问题

七、结论

09-17 这份清单的价值不在于“它现在还是不是待办列表”， 而在于它准确记录了当时的混乱来源：

  • 对象主词混用
  • 路径协议分叉
  • 旧变量名继续扩散
  • 局部变量失真
  • 历史术语假装仍是正式术语

而 09-18 的重构已经把这些主问题大体收口。

所以现在最准确的判断是：

这份文档应被视为历史问题记录，而不是当前待办清单。

后续若继续优化，应优先清理仍会误导人的历史文档与剩余孤例， 而不是回头按本文旧路径逐项“照单执行”。

Reference in New Issue View Git Blame Copy Permalink