From 9954fbcc0dd55568ccfc4d7e8a01e8aa0b140fc7 Mon Sep 17 00:00:00 2001 From: Amirhossein Khalili Date: Sun, 27 Sep 2026 12:26:33 +0330 Subject: [PATCH] docs: record mock content initialization workflow --- tasks/bundle1-seed-review.md | 16 ++++++++++++++++ tasks/bundle1-simplification-plan.md | 4 ++-- tasks/todo.md | 16 ++++++++-------- 3 files changed, 26 insertions(+), 10 deletions(-) create mode 100644 tasks/bundle1-seed-review.md diff --git a/tasks/bundle1-seed-review.md b/tasks/bundle1-seed-review.md new file mode 100644 index 0000000..da0c8d5 --- /dev/null +++ b/tasks/bundle1-seed-review.md @@ -0,0 +1,16 @@ +# Bundle 1 — mock content initialization + +The owner approved the original source-content review, then directed that the frontend show mock content until staff enter content through Django admin. The existing migrations, including [0005_seed_current_website_copy.py](../../guilan-ace-backend/apps/content/migrations/0005_seed_current_website_copy.py), remain unchanged. + +Use the backend management command [seed_mock_content.py](../../guilan-ace-backend/apps/content/management/commands/seed_mock_content.py) after migrations and before enabling CMS page rendering: + +```sh +python manage.py seed_mock_content --dry-run +python manage.py seed_mock_content +``` + +It replaces content for records without a Django admin change-history entry with clearly labeled Persian sample copy, including About items. A record with an admin change entry is preserved as a whole. Re-running the command is safe; `--dry-run` reports intended work without writing. The command is explicit and is not run automatically by deployment or migration. + +Images remain empty because no approved mock image files exist; the frontend treats them as optional. Contact mock URLs use `example.invalid` and the mock email uses that reserved domain. + +The frontend flag remains off by default. The page routes still use legacy rendering until later Bundle 1 tasks wire them to the adapter. Do not enable CMS rendering in a target environment until T08's database audit is complete and the command's dry-run output is reviewed. diff --git a/tasks/bundle1-simplification-plan.md b/tasks/bundle1-simplification-plan.md index d27cd2e..dcbf0dc 100644 --- a/tasks/bundle1-simplification-plan.md +++ b/tasks/bundle1-simplification-plan.md @@ -33,9 +33,9 @@ Expose only the small public read API needed by the frontend for shared site con ### 4. Populate reviewed starting content -Use the existing content inventory to prepare the four fixed records and site identity. Review disputed claims, contacts, and media rights before they become public. Import approved values once without overwriting subsequent admin edits. A small repeatable initialization/data migration is preferable to a general-purpose seed workflow; a dry run is only needed if the environment audit reveals existing data that could be overwritten. +Leave all existing migrations unchanged. Use an explicit `seed_mock_content` management command after migrations to ensure the five fixed records contain obvious mock copy until staff save content through Django admin. It replaces untouched migration-provided copy, preserves records with a Django admin change-history entry, supports `--dry-run`, and is never run automatically. Complete the T08 database audit before running it against a target environment; inspect the dry-run output first. -**Check:** compare each imported value and image with its approved source; a second initialization leaves edited records unchanged. +**Check:** confirm the command fills mock copy, skips admin-edited records, and is idempotent. Optional media remains empty. The owner reviews the mock output before frontend cutover. ### 5. Connect the frontend and verify SEO diff --git a/tasks/todo.md b/tasks/todo.md index 7377ff5..89e2070 100644 --- a/tasks/todo.md +++ b/tasks/todo.md @@ -6,7 +6,7 @@ Bundle 0 started 2026-09-24 and was approved by the owner on 2026-09-26. Deliver ## 0. Discovery and design contract (4–5 person-days) -- [x] **T01 — Classify static public content (M; deps: none).** Files: F `src/views/*`, `src/components/Navbar.tsx`, `Footer.tsx`, `src/app/*`. Acceptance: every public route/string/image/SEO field is mapped to CMS editorial, existing domain data, or code-owned functional UI; conflicts and asset ownership are flagged. Verify: owner reviews the manifest against live desktop/mobile pages. Owner accepted the content boundary and exclusions in `bundle0-review.md` on 2026-09-26; uncertain claims remain excluded from the initial seed. +- [x] **T01 — Classify static public content (M; deps: none).** Files: F `src/views/*`, `src/components/Navbar.tsx`, `Footer.tsx`, `src/app/*`. Acceptance: every public route/string/image/SEO field is mapped to CMS editorial, existing domain data, or code-owned functional UI; conflicts and asset ownership are flagged. Verify: owner reviews the manifest against live desktop/mobile pages. Owner accepted the content boundary and exclusions in `bundle0-review.md` on 2026-09-26. The unchanged `0005` migration retains legacy About affiliations and years; the mock-content command replaces that copy on untouched records before CMS rendering. - [x] **T02 — Capture flow and performance baseline (M; deps: none).** Files: D `tasks/` evidence, F test artifacts. Acceptance: route/state map covers auth, event registration/payment, blog, and staff admin; screenshots and bundle/accessibility baselines have dated device widths. Verify: manually replay each existing happy path and one failure path on staging/local. Owner accepted the recorded local baseline on 2026-09-26 with the historical test run and unexercised external paths documented; the current pytest suites passed on 2026-09-26 (see rerun record). - [x] **Checkpoint A (deps: T01–T02).** Content categories, current behavior, and baseline evidence reviewed; no business-rule changes inferred. Accepted 2026-09-26 with the limits documented in `bundle0-review.md`. - [x] **T03 — Review product truth and assets (S; deps: T01).** Files: F `PRODUCT.md`, asset inventory. Acceptance: initial product record is checked against source assets and owner input; logo sources are cataloged; conflicting contacts/statistics remain pending rather than guessed. Verify: owner signs off facts and supplies approved contact channels before production seed publication. Concept-scope sign-off: owner confirmed repository facts/assets and chose About-page contacts; claim-to-entity mapping remains a T12 seed gate. @@ -16,20 +16,20 @@ Bundle 0 started 2026-09-24 and was approved by the owner on 2026-09-26. Deliver ## 1. CMS foundation and migration (9–12 person-days) -Checkpoint C was approved by the owner on 2026-09-27 after reviewing [the schema and validation record](bundle1-checkpoint-c-review.md). T08–T09 were implemented under the old contract but rejected as too complex on 2026-09-27. Their pending [Checkpoint D review](bundle1-checkpoint-d-review.md) is superseded, not approved. Follow the [course correction plan](bundle1-simplification-plan.md) below. +Checkpoint C was approved by the owner on 2026-09-27 after reviewing [the schema and validation record](bundle1-checkpoint-c-review.md). The old T08–T09 draft/publish workflow was rejected. The direct-save Unfold admin was reviewed and approved by the owner on 2026-09-27; the old [Checkpoint D review](bundle1-checkpoint-d-review.md) is superseded. The current-content API and Checkpoint E were approved on 2026-09-27. Follow the [course correction plan](bundle1-simplification-plan.md); the seeded About content review is documented in [Checkpoint F review](bundle1-seed-review.md). - [x] **T06 — Add site identity and page schema (M; deps: T05).** Files: B new content app models/migration/tests. Acceptance: one site identity, stable page slugs, ordered typed sections, image/alt and SEO fields exist with uniqueness/validation; migrations are additive. Verify: migration test and `python manage.py check` on a test database. - [x] **T07 — Validate fields and media handling (M; deps: T06).** Files: B content validators/tests. Acceptance: URLs, section payloads, image type/size, alt text, and unsafe markup are constrained; absent optional media renders safely. Verify: invalid/oversize/malicious inputs rejected in focused tests. - [x] **Checkpoint C (deps: T06–T07).** Schema and validation reviewed before permissions/API work. Approved by the owner on 2026-09-27. -- [ ] **T08 — Audit current CMS data and permissions (S; deps: T06–T07).** Files: B migration/data audit, D environment record. Acceptance: applied migrations, real content/media rows, and content-specific group/permission assignments are known for each target environment; any data/access migration is mapped. Verify: fresh and current-schema database copies. This replaces the old draft/publish T08. -- [ ] **T09 — Simplify content schema and use native Unfold forms (M; deps: T08).** Files: B content models/migrations/admin/forms/tests. Acceptance: one editable record per fixed page and shared site identity; explicit text/image/alt/SEO fields; direct Save; standard Django model change permissions; no arbitrary page creation, custom admin templates, draft/revision/approval workflow, or delete action. Verify: permission tests, migrations, and superuser/authorized staff admin walkthrough at 390px and desktop against the existing Unfold Blog Category form. This replaces the old T09 and its review criteria. -- [ ] **Checkpoint D (deps: T09).** Owner reviews the real Unfold content forms and direct-save permission behavior before API work. +- [ ] **T08 — Audit current CMS data and permissions (S; deps: T06–T07).** Files: B migration/data audit, D environment record. Repository review found migrations `0001`–`0005`; `0004` carries prior content-editor access to standard model change permissions. Deployment files describe PostgreSQL and Django media volumes but do not record applied migrations, existing content/media rows, or actual group/user assignments for target environments. The environment-specific audit and database-copy check remain open; no deployment database was accessed. Complete this before applying the migrations to a target environment. +- [x] **T09 — Simplify content schema and use native Unfold forms (M; deps: T08).** Files: B content models/migrations/admin/forms/tests. Acceptance: one editable record per fixed page and shared site identity; explicit text/image/alt/SEO fields; direct Save; standard Django model change permissions; no arbitrary page creation, custom admin templates, draft/revision/approval workflow, or delete action. Verified: backend suite passed 248 tests; Django and migration checks passed; owner reviewed and approved the Unfold admin on 2026-09-27. Implementation is approved; the unresolved T08 audit remains a deployment gate. +- [x] **Checkpoint D (deps: T09).** Owner approved the direct-save Unfold forms and permissions on 2026-09-27. The old draft/publish review is superseded. - [x] **T10 — Expose current-content read API (M; deps: T09).** Files: B content Ninja router/schemas/tests, `config/api.py`; contract: backend [content API v1 note](../../guilan-ace-backend/docs/content-api-v1.md). Acceptance: shared site record and four fixed pages expose current content and SEO, with explicit missing/unknown behavior and no revision/status/preview fields. Verified: anonymous read, save-then-read, missing content, and cache behavior; backend suite passed 255 tests and Django checks passed. Owner approved the API checkpoint on 2026-09-27. - [x] **Checkpoint E (deps: T10).** The current-content API shape was checked and approved by the owner on 2026-09-27. No private preview API is planned. -- [ ] **T12 — Review starting content and media (M; deps: T01, T09).** Files: D source review, B initial content data. Acceptance: exact legacy values and sources are reviewed; disputed claims/links and unlicensed media are excluded until approved. Verify: owner checks the content that will become public. -- [ ] **T13 — Initialize fixed content records safely (S; deps: T12).** Files: B data migration or small initialization command/tests. Acceptance: approved starting values are inserted once, existing admin edits are preserved, and no draft status exists. Verify: apply twice on a database copy; second run leaves edited records unchanged. Add a dry run only if the T08 audit finds overwrite risk. +- [x] **T12 — Review starting content and media (M; deps: T01, T09).** Files: D source review, B initial content data. Owner reviewed the source content and approved blank CMS image fields, then directed that mock copy be used until staff save content. No current-site claims or media are in the mock content. +- [ ] **T13 — Initialize fixed content records safely (S; deps: T12).** Files: B management command/tests; do not change existing migrations. Implemented as `python manage.py seed_mock_content`, with `--dry-run` and `--database` options. It replaces current migration copy only for records without a Django admin change entry, preserves admin-edited records, and supplies mock About items. Three focused command tests passed. The command has not been run against an environment database; T08 audit and dry-run review are required first. - [ ] **Checkpoint F (deps: T12–T13).** Starting public content and images are reviewed before frontend cutover. -- [ ] **T14 — Add frontend CMS adapter and cutover flag (M; deps: T10).** Files: F content fetch/types/flag tests. Acceptance: current content can be fetched server-side with typed fallback; flag defaults to legacy rendering until launch; saving in admin does not leave stale public content. Verify: integration tests with CMS available, unavailable, and changed content. +- [ ] **T14 — Add frontend CMS adapter and cutover flag (M; deps: T10).** Files: F `src/lib/content-cms.ts`, `.env.sample`. Acceptance: current content can be fetched server-side with typed mock fallback; blank CMS fields and request failures use mock copy; the flag defaults off; `no-store` fetches expose the latest admin save. The adapter returns mock values rather than caller-provided legacy copy; page rendering is still legacy until later tasks connect it. ## 2. Home/About and shared public shell (9–12 person-days)