71 lines
7.5 KiB
Markdown
71 lines
7.5 KiB
Markdown
# Product Direction
|
|
|
|
- 模板新增、绑定修改及宣称完成前,执行 pnpm template:doctor 并遵循 docs/template-completion-rules.md。静态校验、输入框出现、mock 成功不能单独证明完成;回归使用真实 manifest,按区域全部可见变量验收。
|
|
|
|
- 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.
|
|
- Templates have exactly one active package manifest/runtime contract. Do not add legacy readers, dual-write paths, inferred defaults, aliases, or silent fallbacks. Convert existing persisted data with a one-time, auditable migration that fails on ambiguity, then remove the old representation.
|
|
- `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
|
|
|
|
- 使用中文提交信息。
|
|
- 格式:`类型: 简短描述`。
|