violet: Instructions file for Codex

violet (blog-project)

全栈博客平台 monorepo。

架构与代码边界

• 后端 (api/): Go 1.26, Chi 路由, PostgreSQL 16, Redis 7。
  • 关键: 后端为 DDD 单一架构: internal/{domain,application,infrastructure,interfaces,app}(旧 handler/service/repository 分层已移除)。依赖注入为 app/ 下手工容器装配(*Container + container.go 聚合,不使用 wire)。
• 前端 (web/): React 19, Vite, Tailwind CSS v4。
  • 关键: 使用 pnpm 作为包管理器，切勿使用 npm 或 yarn。
  • 状态管理: Zustand + TanStack Query。

架构耦合约束

本节规定代码归属；commit 边界与依赖顺序统一见「提交流程规范」。

• 前端通用组件与站点公共层各归其位。跨 feature 的通用 React 组件及基础语义 token 在 web/packages/ui/，从 @violet/ui 根入口使用组件；Tailwind v4 后导入 @violet/ui/styles.css。web/src/styles/dialects/ 保留站点方言；web/src/shared/ 只放站点级通用能力，以上两层均不夹带 posts / comments / editor 等 feature 业务逻辑。FSD 分层(shared → entities → features → widgets)不允许向业务层反向依赖。
• 组件库以单元组织并标记成熟度。所有组件在 web/packages/ui/src/components/<name>/，结构、按需 typed recipe、CSS、导出与测试共置；component-manifest.json 是公开单元、入口、CSS、文档与 foundation / legacy 状态的事实源。src/legacy.ts 仅为兼容 barrel，不放实现副本。基础单元的 React 与 HTML 共用唯一 BEM CSS；其余 legacy 的样式逐个迁移。共享 lib/ 只接收真实复用能力，字体、签名与站点装饰动画留在 web/src/styles/site-theme.css。组件库规范以 web/packages/ui/docs/architecture.md 与 component-design.md 为权威；web/src/features/ui-docs/ 展示同一正文与同源组件示例，公开入口为 /ui；新增单元按包内规范执行清单同步、源码检查、构建与外部 tarball 消费验收。
• 后端各层各司其职:领域逻辑进 domain,用例编排进 application,基础设施细节进 infrastructure,HTTP 适配进 interfaces;internal/middleware/ 只放通用横切中间件(auth/cors/csrf/ratelimit 等)。通用基础设施(错误码、observability、通用中间件)不夹带具体业务实体逻辑。
• 判断「是否公共」看真实消费方,不是位置。feature 私有逻辑被第二个 feature 复用时先上提；通用组件进 web/packages/ui/，站点专用基础能力进 web/src/shared/，有业务语义的实体逻辑进 web/src/entities/（提交顺序见「依赖与迁移」）。

开发流与命令 (Makefile)

所有核心操作都通过根目录的 Makefile 统管：

• 启动本地开发: make dev (一键启动 Postgres、Redis、API 和 Web)
• 数据库迁移: make migrate (使用 golang-migrate)

后端 (api/) 须知

• 环境依赖: 后端需要 Go 1.26。本机无 Go 时不擅自安装,按 .agents/skills/api-toolchain 的流程问用户一次并记住决定(本地安装或容器执行)。
• 测试: make api-test (本机无 Go 时按上方容器方式执行,下同)
• 代码检查: make api-lint (使用 golangci-lint)