personal-assistant-go-backend

name	personal-assistant-go-backend
description	用于 personal_assistant 仓库的 Go 后端开发、重构、代码评审与排障。任务涉及分层实现、DTO到Router链路、BizError错误处理、context传递、路由注册、配置外置和规则合规检查时使用。

Personal Assistant Go Backend

概览

使用本 skill 在当前仓库执行后端任务，确保规则一致、交付稳定、实现路径可复用。

先阅读 references/project-rules.md 作为权威规则，再按下方流程选择执行路径。

任何执行型任务在进入实现流程前，先按项目根目录 plan/README.md 生成 plan/<module>/pending-<task>.md，待用户明确确认后再执行。

做权限相关重构时，先检查是否越过 AuthorizationService 或直接触碰 Enforcer；若有，优先收口，再继续功能改动。

工作流决策树

1. 用户要求新增或修改 API/业务逻辑：
   • 按标准实现流程执行（DTO 到 Router）。
2. 用户要求做代码评审：
   • 按评审清单执行，并按严重级别输出问题。
3. 用户要求排障或重构：
   • 先定位受影响层，再在不破坏边界的前提下做最小改动。
4. 用户要求新增或改造独立基础设施能力（如 Trace/Metric/Audit/限流适配/消息客户端）：
   • 按“独立基础设施实现流程”执行（Config 到 Init，再到接入层）。

AI 子域渐进式 DDD 工作流

当任务落在 AI 子域时，默认按“MVC 主体 + AI 子域渐进式 DDD”理解当前项目，而不是假设仓库已经完成全量 DDD 改造。

第 1 步：先判断当前改动属于哪一层

• HTTP 参数、SSE 入口、路由挂载：
  • 继续放在 internal/controller/system、internal/router/system
• AI 用例编排、上下文组装、tool 注册与授权收口、sink/projector 协调：
  • 放在 internal/service/system
• 稳定协议、事件、tool/runtime 抽象、领域语义：
  • 放在 internal/domain/ai
• Eino / Local runtime、第三方模型 SDK、tool adapter、checkpoint / approval 等技术实现：
  • 放在 internal/infrastructure/ai
• AI 持久化访问：
  • 继续放在 internal/repository/interfaces 与 internal/repository/system

第 2 步：保持 MVC 外壳，不做过度改名

• 不要为了“更像 DDD”把现有 controller/router/service/repository 全部改名成 interfaces/application/infrastructure。
• 当前仓库的推荐方向是：
  • MVC 外壳继续保留
  • AI 子域只在必要处补 domain/ai 与 infrastructure/ai
• 如果用户没有明确要求做全量目录迁移，默认做局部拆分，而不是扩大改造范围。

第 3 步：AI 子域评审重点

• 是否把协议和具体实现耦合在一起。
• 是否让 service/system 直接依赖 Eino/Gin/GORM/Redis 等底层实现细节。
• 是否把 runtime、tool、trace、prompt 拼装、恢复控制全部堆进单个 service 文件。
• 是否把 AI 子域的局部 DDD 演进误做成项目整体全量 DDD 重构。

AI 子域禁止模式

• 在 domain/ai 直接依赖 HTTP、GORM、Eino、Redis。
• 把 tool/runtime/event/trace 的稳定协议继续散落在 service/system 多个文件中而不收口抽象。
• 因为某次 AI 重构就改写全仓目录口径，导致 MVC 主体被迫跟着迁移。
• 对外宣称“项目已经是完整 DDD 架构”，而实际只完成 AI 子域局部拆分。

标准实现流程

第 1 步：DTO

• 在以下目录定义请求和响应 DTO：
  • internal/model/dto/request
  • internal/model/dto/response
• 禁止直接将 Entity 作为 API 契约。
• 校验规则与字段语义需和 Controller 绑定逻辑一致。

第 2 步：Repository

• 在 internal/repository/interfaces 扩展仓储接口。
• 在 internal/repository/system 实现数据访问。
• Repository 不感知业务语义与 BizError。
• 原样返回底层错误。

第 3 步：Service

• 在 internal/service/system 编排业务逻辑。
• 持久化只通过 Repository。
• 业务错误使用 pkg/errors 包装。
• 长链路调用必须贯穿 context.Context。

第 4 步：Controller

• 完成请求绑定与参数校验。
• 使用请求上下文调用 Service。
• 失败统一 global.Log.Error 记录。
• 统一使用 pkg/response 返回。
• BizError 路径使用 response.BizFailWithError(err, c)。

第 5 步：Router

• 在 internal/router/system 注册模块路由。
• 每个模块仅提供一个 InitXRouter(*gin.RouterGroup)。
• 统一接入中央路由组注册流程。

第 6 步：收尾检查

• 检查是否存在分层越界。
• 检查配置是否通过 global.Config 外置读取。
• 检查错误链路是否统一。
• 至少执行最小必要测试或校验命令。

独立基础设施实现流程

第 1 步：Config

• 在 internal/model/config 增加设施配置结构（开关、endpoint、timeout、采样率、batch 等）。
• 通过 configs 驱动，运行时仅从 global.Config 读取。
• 仅保留必要零值兜底，禁止硬编码运行参数。
• pkg/* 若需可复用配置，定义模块内 Options 结构体；由 core/init 映射后注入。
• 禁止在 pkg/* 直接读取 viper 或 global.Config。

第 2 步：Core

• 在 internal/core 实现设施初始化、连接创建与生命周期管理。
• 初始化失败返回原始 error，交给上层编排决定是否 fail-fast。
• 避免在 core 外部重复创建同类客户端实例。

第 3 步：Init

• 在 internal/init/init.go 按依赖顺序编排初始化。
• 仅编排，不承载具体初始化细节。
• 确保同一设施不会重复启动。

第 4 步：接入层

• 通用调用能力优先沉淀到 pkg/*。
• HTTP 入口接入放在 internal/middleware 或 internal/router/system。
• internal/router/router.go 只做挂载，不写设施业务细节。

第 5 步：业务层使用

• Controller 不直接依赖第三方设施 SDK。
• Service 不直接 new 第三方客户端；统一通过 pkg/* 或已初始化实例调用。
• Repository 继续只负责数据访问，不承担设施编排。
• Redis/MySQL 等基础资源的 CRUD/JOIN 继续由 Repository 承担，禁止下沉到“通用基础设施层”。

第 6 步：验证

• 验证开关生效、降级路径、日志可观测性。
• 至少执行最小必要的 build/test 或启动自检。

禁止模式

• 在 Controller 写业务逻辑。
• Service 直接访问 DB 或 global.DB。
• Controller 直接调用 Repository。
• 业务层直接读 Viper。
• 绕过 pkg/response 返回散装响应。
• 硬编码可变运行参数。
• 在 Controller/Service 直接 new 第三方基础设施客户端。
• 在 internal/init/init.go 写具体设施初始化细节。
• 重复初始化或重复启动同一基础设施组件。

仓库导航

• 启动编排：internal/init/init.go
• 核心初始化：internal/core
• 路由入口：internal/router/router.go
• 领域路由注册：internal/router/system
• Controller：internal/controller/system
• Service：internal/service/system
• Repository：internal/repository/system
• Repository 契约：internal/repository/interfaces
• DTO：internal/model/dto
• 配置结构体：internal/model/config
• 公共能力：
  • pkg/errors
  • pkg/response
  • pkg/jwt
  • pkg/util

评审执行规则

• 当用户要求 “review” 时，重点关注：
  • 缺陷
  • 行为回归
  • 测试缺口
  • 分层越界
• 先输出问题项，并附文件与行号。
• 总结放在后面。
• 若无发现，明确说明并给出剩余风险。

交付前清单

• 规则已按 references/project-rules.md 对齐。
• 受影响模块已按 references/repo-map.md 定位。
• 已执行 references/review-checklist.md。
• 可选执行静态探针 scripts/rule_probe.ps1。
• 需要时执行 scripts/install_skill.ps1 完成本机安装/同步。