docs: refresh SEO farm architecture notes

This commit is contained in:
DCCONSTRUCTIONS 2026-07-02 13:48:04 +03:00
parent 9582380ba3
commit 4b46936d0b
7 changed files with 69 additions and 1091 deletions

View File

@ -126,9 +126,9 @@ Final Validation
input: workingText, keyword map, media map, approved media changes input: workingText, keyword map, media map, approved media changes
output: validation report output: validation report
Apply / Export Patch / Export
input: approved text/media changes input: approved text/media changes
output: changeset, updated target project, reports/export output: patch artifact, changeset manifest, reports/export
``` ```
## 4. Tool Boundaries ## 4. Tool Boundaries
@ -231,11 +231,23 @@ Codex через `codex exec` используется для смысловых
- предложить alt/caption/filename. - предложить alt/caption/filename.
``` ```
Codex не должен напрямую менять target project до `Apply`. Codex не должен напрямую менять target project. Любая правка проходит через patch artifact.
## 5. Apply Safety Rules ## 5. Patch Safety Rules
До ручного Apply target project считается read-only. Исходники сайта всегда считаются read-only для редактора SEO Mode.
Рабочий контур:
```text
original source
-> original snapshot
-> editor draft
-> patch artifact near imported source / project storage
-> explicit production patch-run after user confirmation
```
Временные черновики, которые видит только редактор, живут в draft storage. Публикуемый результат должен материализоваться как отдельный patch artifact, а не как незаметное изменение source files.
Разрешённые изменения после approval: Разрешённые изменения после approval:
@ -260,7 +272,7 @@ Codex не должен напрямую менять target project до `Apply
- публиковать на хостинг. - публиковать на хостинг.
``` ```
Перед Apply UI обязан показать: Перед production patch-run UI обязан показать:
```text ```text
- affected files; - affected files;
@ -268,18 +280,21 @@ Codex не должен напрямую менять target project до `Apply
- media diff; - media diff;
- filename rename plan; - filename rename plan;
- validation status; - validation status;
- changeset summary. - patch artifact path/name;
- changeset summary;
- patch-run command/status.
``` ```
Apply должен идти транзакционно: Production patch-run должен идти транзакционно:
```text ```text
1. build changeset 1. build patch artifact
2. run dry-run 2. build changeset manifest
3. backup affected files to object storage 3. run dry-run against copied/current source tree
4. apply text/media/filename changes through backend 4. backup affected files to object storage
5. verify references and rename results 5. run patch script against source tree only after explicit user confirmation
6. rollback if any critical step fails 6. verify references and rename results
7. rollback if any critical step fails
``` ```
## 5.1. Repeated Scan / Reconcile Rules ## 5.1. Repeated Scan / Reconcile Rules

View File

@ -31,9 +31,10 @@
- `USER_FLOW.md` — пользовательский сценарий. - `USER_FLOW.md` — пользовательский сценарий.
- `IMPLEMENTATION_GUARDRAILS.md` — pipeline, границы инструментов и риски. - `IMPLEMENTATION_GUARDRAILS.md` — pipeline, границы инструментов и риски.
- `UI_UX_SPEC.md` — UI/UX экраны, состояния и safety-паттерны. - `UI_UX_SPEC.md` — UI/UX экраны, состояния и safety-паттерны.
- `TASK_MANAGER.md` — поэтапный план реализации.
- `CHECK_OVERSEO_SPEC.md` — спецификация локальной проверки переспама. - `CHECK_OVERSEO_SPEC.md` — спецификация локальной проверки переспама.
Актуальные задачи, статусы и следующий маршрут ведутся в Ops-карточках проекта `NDC PLATFORM`.
## Зафиксированные архитектурные решения ## Зафиксированные архитектурные решения
- `Postgres` — основной источник истины. - `Postgres` — основной источник истины.

View File

@ -191,10 +191,10 @@ For MVP we start with `local_folder`, but the application should keep the source
18. UI shows report and diff 18. UI shows report and diff
| |
v v
19. User applies changes to target project 19. User materializes approved patch artifact
| |
v v
20. User can export archive/reports 20. User runs production patch-run or exports archive/reports
``` ```
MVP works with existing code/text only: MVP works with existing code/text only:
@ -298,11 +298,12 @@ app/
-> ru-text status -> ru-text status
-> media SEO status -> media SEO status
Apply / Export Patch / Export
-> affected files -> affected files
-> changeset -> patch artifact
-> changeset manifest
-> manual approval -> manual approval
-> apply to target project -> production patch-run
-> zip target project -> zip target project
-> export reports -> export reports
@ -795,14 +796,12 @@ extract text
v v
changeset changeset
| |
+-- patch artifact near imported source / project storage
+-- dry-run +-- dry-run
+-- backup affected files to object storage +-- backup affected files to object storage
+-- apply through backend +-- explicit production patch-run
+-- verify references/renames +-- verify references/renames
+-- rollback on failure +-- rollback on failure
|
v
apply to target project
``` ```
MVP stores one `workingText` draft per source/section. Full draft versioning and rollback history are future enhancements. MVP stores one `workingText` draft per source/section. Full draft versioning and rollback history are future enhancements.
@ -816,7 +815,8 @@ Related local docs:
- `CHECK_OVERSEO_SPEC.md` - `CHECK_OVERSEO_SPEC.md`
- `IMPLEMENTATION_GUARDRAILS.md` - `IMPLEMENTATION_GUARDRAILS.md`
- `UI_UX_SPEC.md` - `UI_UX_SPEC.md`
- `TASK_MANAGER.md`
Актуальные задачи и статусы разработки ведутся в Ops-карточках проекта `NDC PLATFORM`.
- Codex exec: https://developers.openai.com/codex/noninteractive - Codex exec: https://developers.openai.com/codex/noninteractive
- Codex with ChatGPT plan: https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan - Codex with ChatGPT plan: https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan

View File

@ -302,28 +302,30 @@ Codex получает структурированное задание:
Важно: `Apply` нельзя делать после media-правок без повторной финальной проверки. Важно: `Apply` нельзя делать после media-правок без повторной финальной проверки.
### 3.14. Apply / Export ### 3.14. Patch / Export
Перед применением UI показывает: Перед materialize/production patch-run UI показывает:
- affected files; - affected files;
- affected sections; - affected sections;
- text diff; - text diff;
- media diff; - media diff;
- filename rename plan; - filename rename plan;
- patch artifact path/name;
- validation status. - validation status.
Пользователь нажимает `Apply to target project`. После apply создаётся changeset и сохраняется история. Пользователь подтверждает создание patch artifact. Исходники сайта при этом не меняются. Production меняется только отдельным явным patch-run шагом, когда пользователь подтверждает, что выбранный patch можно запускать по source tree.
Безопасный apply-пайплайн: Безопасный patch-пайплайн:
```text ```text
1. собрать changeset 1. собрать patch artifact
2. сделать dry-run 2. собрать changeset manifest
3. сохранить backup affected files в object storage 3. сделать dry-run против текущего source tree
4. применить изменения через backend 4. сохранить backup affected files в object storage
5. проверить rename/update references 5. запустить patch script только после явного подтверждения production patch-run
6. если что-то упало, выполнить rollback 6. проверить rename/update references
7. если что-то упало, выполнить rollback
``` ```
Export: Export:
@ -1018,4 +1020,5 @@ Media SEO не даёт забыть alt, poster, видео-контекст и
- `CHECK_OVERSEO_SPEC.md` — спецификация локального анти-переспам инструмента. - `CHECK_OVERSEO_SPEC.md` — спецификация локального анти-переспам инструмента.
- `IMPLEMENTATION_GUARDRAILS.md` — порядок backend pipeline, границы инструментов и риски разработки. - `IMPLEMENTATION_GUARDRAILS.md` — порядок backend pipeline, границы инструментов и риски разработки.
- `UI_UX_SPEC.md` — обязательные UI/UX-экраны, компоненты, состояния и safety-паттерны. - `UI_UX_SPEC.md` — обязательные UI/UX-экраны, компоненты, состояния и safety-паттерны.
- `TASK_MANAGER.md` — поэтапный план реализации с подзадачами и критериями готовности.
Актуальные задачи, статусы и критерии следующего этапа ведутся в Ops-карточках проекта `NDC PLATFORM`.

File diff suppressed because it is too large Load Diff

View File

@ -694,9 +694,9 @@ Soft warnings:
- low confidence classification; - low confidence classification;
- stylistic warning. - stylistic warning.
### 5.14. Apply / Export ### 5.14. Patch / Export
Цель: показать все изменения и применить их только после подтверждения. Цель: показать все изменения, материализовать patch artifact и запускать production patch-run только после отдельного подтверждения.
Обязательные элементы: Обязательные элементы:
@ -708,12 +708,14 @@ Soft warnings:
- media diff; - media diff;
- filename rename plan; - filename rename plan;
- validation status; - validation status;
- patch artifact path/name;
- changeset summary; - changeset summary;
- confirmation checkbox; - confirmation checkbox;
- Apply button; - Build Patch button;
- Run Patch button;
- Export button. - Export button.
Apply должен быть заблокирован, если: Build Patch должен быть заблокирован, если:
- нет финальной проверки; - нет финальной проверки;
- есть hard errors; - есть hard errors;
@ -721,6 +723,13 @@ Apply должен быть заблокирован, если:
- pending changes пустые; - pending changes пустые;
- пользователь не подтвердил changeset. - пользователь не подтвердил changeset.
Run Patch должен быть заблокирован, если:
- patch artifact не создан;
- dry-run не прошёл;
- пользователь не подтвердил production patch-run;
- source tree изменился после dry-run.
Export: Export:
- zip target project; - zip target project;

View File

@ -639,4 +639,4 @@ Projects
UI/UX-набор обязательных экранов, компонентов и состояний вынесен в `UI_UX_SPEC.md`. UI/UX-набор обязательных экранов, компонентов и состояний вынесен в `UI_UX_SPEC.md`.
Пошаговый план реализации с критериями готовности вынесен в `TASK_MANAGER.md`. Актуальный пошаговый план, статусы и критерии готовности ведутся в Ops-карточках проекта `NDC PLATFORM`.