Files
persionalBrand/AGENTS.md

7.0 KiB

Product Direction

  • The core product is a personal-brand platform whose primary goal is to build trust and convert that trust into qualified inquiries or collaborations.
  • Personal-brand identity, positioning, proof of work, communication expectations, and contact paths are higher priority than any single industry workflow.
  • Industry behavior is implemented as replaceable templates. Food, consulting, design, photography, and future industries must not hard-code their terminology or fields into the shared brand model or shared UI.
  • The food template is supported, but it is an example template rather than the product definition.
  • Backend configuration is the source of truth for brand content, services, template selection, trust-building content, and industry-specific fields. The mini program only renders configuration and submits user input.
  • Template packages are the source of truth for template manifests, visual structure, default/sample content, field declarations, assets, and capabilities. Do not copy every template's sample data into Prisma seed or global database tables. A template's sample content may be copied into the database only when an administrator explicitly imports it for one specific brand; the resulting rows are brand content, not template registration.
  • apps/api/prisma/seed.ts may contain a small, explicit development fixture for the seeded demo brands, but it must never become the catalog of all templates or require one seed block per production template. New templates must be discoverable and validated from their package manifest without editing global seed data.
  • Any delivered backend endpoint must have an automated test covering its authorization and successful behavior before it is considered complete.
  • Keep personal-brand trust details explicit: biography, positioning, credentials, portfolio/proof, process, expectations, availability, contact methods, and clear follow-up status.

Engineering Architecture Rules

Backend boundaries

  • NestJS controllers only handle transport concerns: authentication, DTO binding, status codes, and response shape.
  • Domain behavior belongs in services; Prisma access must not be duplicated across controllers.
  • DTOs are the runtime validation boundary. Do not use Partial<T> or plain TypeScript interfaces as request bodies for validated endpoints.
  • Every protected endpoint must test missing credentials, invalid credentials or wrong role, and the successful authorized path.
  • Public endpoints may only expose published content and must enforce brand isolation through the configured brand identifier.

Admin frontend boundaries

  • React pages must be split by feature under apps/admin/src/features/<feature>/; a page component should coordinate UI, not contain the entire application.
  • Shared API construction, authentication-aware fetch, query keys, and error handling belong under apps/admin/src/lib/.
  • Shared visual elements belong under apps/admin/src/components/; feature-specific forms and tables stay inside their feature module.
  • Routing belongs in apps/admin/src/app/ and navigation must use React Router. Do not use a local state variable as the primary page router.
  • A mutation must close or reset a form only after onSuccess; failed requests must preserve user input and show an actionable error.
  • API base URLs must come from VITE_API_BASE_URL with a documented local fallback; no feature may hard-code an environment-specific host.
  • Admin session expiry must clear the token, notify the user, and return to the login screen consistently.

Formatting, testing, and delivery

  • Prettier is the formatting source of truth. New or changed files must pass pnpm format:check.
  • Before delivery, run relevant type checks, API integration tests, and frontend production builds. Do not claim an endpoint is delivered without a passing automated test.
  • Prefer cohesive commits that complete a reviewable unit of work; do not submit speculative fragments while the feature is broken.
  • When a code review identifies a recurring design issue, update this file or a focused architecture document before implementing the next related feature.
  • Before delivery, follow docs/engineering-delivery-checklist.md; a feature is incomplete when its API path, failure path, data migration, client contract, UI states, or user-visible operation semantics are unverified.

Production engineering standards

  • Record material architectural decisions in docs/adr/ using the format NNNN-title.md: context, decision, alternatives, consequences, and migration plan. Do not silently introduce a second state-management, validation, routing, or persistence pattern.
  • Treat the API Client types and DTOs as an explicit contract. Any response or request shape change must update the shared client, its tests, and the consuming feature in the same change.
  • Keep API responses consistent: successful payloads use the established envelope, errors use the global error filter with a stable machine-readable code and requestId. Never expose stack traces or database errors to clients.
  • Validate all external input at the boundary, use allow-lists for enums and template keys, and apply authorization before loading or mutating tenant/brand data. Never trust a client-supplied brandId.
  • Secrets and environment-specific URLs belong in environment configuration. Commit .env.example, never real credentials, and fail fast when a required production variable is missing.
  • Database changes must be additive and reversible where practical: update Prisma schema, migration, seed data, API behavior, and integration tests together. Avoid destructive migrations without an explicit migration plan.
  • Follow a testing pyramid: focused unit tests for pure domain rules, API integration tests for authorization and persistence, and a small number of frontend interaction tests for critical flows. Tests must isolate data and clean up fixtures.
  • Make asynchronous UI states explicit: loading, empty, error, success, and retry. Mutations must be idempotent where possible and must invalidate or update affected query caches.
  • Keep observability intentional: include requestId in errors and logs, log state-changing admin actions without secrets, and use structured log fields rather than concatenated messages.
  • Use dependency and type safety gates before merge: formatting, lint, typecheck, relevant tests, production build, and a clean diff. A known warning must be documented with an owner or follow-up issue.
  • Prefer small, cohesive modules with one reason to change. A feature may depend on shared infrastructure, but shared infrastructure must not import feature modules.
  • Public and admin behavior must be documented at the route or feature boundary, including authentication, roles, validation, status transitions, and failure behavior.

Codex Code Guidelines

中文回复

  • 所有回复使用简体中文。
  • 技术术语保留 English,首次出现可添加中文解释。
  • 代码变量名保持 English,注释使用中文。

Git Commit

  • 使用中文提交信息。
  • 格式:类型: 简短描述。