spec(wpmc S4): URL router design — legacy wp_query patch + ACF page_unic + 301

2026-05-13 23:13:54 +05:00
parent 259470ca63
commit 1ddbc55204
1 changed files with 357 additions and 0 deletions
@@ -0,0 +1,357 @@
 # S4 — URL-роутер `/{city}/{path}/` + `page_unic` + `main_page_alt`
 - Beads: `cp-83m` (parent epic `cp-cw4`)
 - Depends on: `cp-arq` (S3 — `[shortcode_dmr]` + helpers, закрыт)
 - Blocks: `cp-i17` (S5 — глобальные фильтры the_title/the_content/the_permalink + rest_url)
 - Дата: 2026-05-13
 ## Цель
 Городской URL-роутинг для мультигородского сайта: URL `/{city-slug}/{path}/` загружает страницу с указанным `path` в контексте города `city-slug`. Реализация повторяет washanyanya legacy-подход — патчит global `$wp_query` на действии `wp` priority 9999, без `add_rewrite_rule`.
 Поддерживает:
 - индивидуальную главную города (term-meta `main_page_alt`) с fallback на опцию `index_town_alt`
 - клоны страниц (repeater `page_unic`: orig → clone для конкретного term'а town)
 - 301 redirect для пользователя, открывшего оригинал клонированной страницы в контексте не-главного города
 - список путей-исключений из роутинга (`page_no_rep`)
 ## Архитектура
 Четыре новых класса + расширение `Helpers`:
 ```
 includes/
 ├── class-options-page.php       ← WPMultiCity\OptionsPage
 ├── class-term-meta.php          ← WPMultiCity\TermMeta
 ├── class-router.php             ← WPMultiCity\Router
 ├── class-redirect.php           ← WPMultiCity\Redirect
 └── class-helpers.php (extend)   ← +4 новых метода
 ```
 Все четыре регистрируются в `Plugin::boot()` (становится 8 регистраций суммарно). Каждый класс — статический, с `register()` (вешает хук) и handler-методом.
 ## ACF data model
 ### Options page (OptionsPage::register)
 ```php
 acf_add_options_page([
    'page_title' => 'WP Multi City',
    'menu_title' => 'WP Multi City',
    'menu_slug'  => 'wp-multi-city',
    'capability' => 'manage_options',
    'redirect'   => false,
 ]);
 ```
 Field group `group_wpmc_routing` (title "WPMultiCity / Routing", location: options_page == wp-multi-city):
 | Field name | Type | Settings |
 |---|---|---|
 | `main_town_slug` | taxonomy | taxonomy=town, single, return_format=slug, allow_null=1 |
 | `index_town_alt` | post_object | post_type=page, return_format=id, allow_null=1, multiple=0 |
 | `page_unic` | repeater | layout=table, sub_fields=3 (см. ниже) |
 | `page_no_rep` | repeater | layout=table, sub_fields=1 (см. ниже) |
 `page_unic` sub_fields:
 - `page_old` (post_object, post_type=page, return_format=id, allow_null=0)
 - `page_new` (post_object, post_type=page, return_format=id, allow_null=0)
 - `town` (taxonomy=town, return_format=id, single, allow_null=0)
 `page_no_rep` sub_fields:
 - `link` (text, instructions: "Префикс URL, например /privacy/")
 ACF group keys: `group_wpmc_routing`, `field_wpmc_main_town_slug`, `field_wpmc_index_town_alt`, `field_wpmc_page_unic`, `field_wpmc_page_unic_page_old`, `field_wpmc_page_unic_page_new`, `field_wpmc_page_unic_town`, `field_wpmc_page_no_rep`, `field_wpmc_page_no_rep_link`.
 ### Term meta (TermMeta::register)
 ```php
 acf_add_local_field_group([
    'key'    => 'group_wpmc_town_main_page',
    'title'  => 'WPMultiCity / Town main page',
    'fields' => [[
        'key'           => 'field_wpmc_main_page_alt',
        'label'         => 'Главная страница для этого города',
        'name'          => 'main_page_alt',
        'type'          => 'post_object',
        'post_type'     => ['page'],
        'return_format' => 'id',
        'allow_null'    => 1,
        'multiple'      => 0,
    ]],
    'location' => [[['param' => 'taxonomy', 'operator' => '==', 'value' => 'town']]],
 ]);
 ```
 ## Helpers — новые методы
 ```php
 public static function main_town_slug(): ?string;
 public static function is_routable_path(?string $path = null): bool;
 public static function page_unic_swap(int $page_id_old, string $town_slug): ?int;
 public static function index_town_alt_page_id(): ?int;
 ```
 ### `main_town_slug()`
 Читает `get_field('main_town_slug', 'option')` (ACF). Возвращает slug или null. Сам зарегистрирован как `add_filter('wpmc_main_town_slug', [Helpers::class, 'main_town_slug'], 5)` — это обеспечивает default в S3 `current_town()` без затирания пользовательских фильтров.
 Регистрация фильтра — внутри `OptionsPage::register()` (близко к контексту опций).
 ### `is_routable_path(?string $path = null)`
 - `$path === null` → берёт `$_SERVER['REQUEST_URI']`.
 - Читает `get_field('page_no_rep', 'option')` (массив с `link`).
 - Если любой `$item['link']` встречается в `$path` через `str_contains` → возвращает false (исключение).
 - Иначе → true.
 ### `page_unic_swap(int $page_id_old, string $town_slug): ?int`
 - Получает term по slug (`Helpers::get_term_by_slug`).
 - Если term не найден → null.
 - Читает `get_field('page_unic', 'option')` (массив с `town`/`page_old`/`page_new`).
 - Ищет row, где `(int) $row['town'] === $term->term_id && (int) $row['page_old'] === $page_id_old`.
 - Возвращает `(int) $row['page_new']` или null.
 Per-request cache по ключу `$page_id_old . '|' . $town_slug`.
 ### `index_town_alt_page_id(): ?int`
 `get_field('index_town_alt', 'option')` → int|null. Возвращает null если пусто или 0.
 ## Router::route() — алгоритм
 Регистрируется через `add_action('wp', [self::class, 'route'], 9999)`.
 ```
 1. if (is_admin()) return.
 2. if (defined('DOING_AJAX') && DOING_AJAX) return.  // Не трогаем admin-ajax
 3. $town_slug = Helpers::current_town();
 4. $main = Helpers::main_town_slug();
 5. if ($town_slug === null) return.                    // нет городского контекста
 6. if ($main !== null && $town_slug === $main) return. // главный город — patching не нужен
 7. $request_uri = $_SERVER['REQUEST_URI'] ?? '/';
 8. if (!Helpers::is_routable_path($request_uri)) return.
 9. $url_original = self::strip_town_prefix($request_uri, $town_slug);
    // /{slug}/about/?foo=1 → /about/?foo=1
 10. global $wp_query, $wp_the_query, $post;
 11. if (self::is_root($url_original)):  // "/" или "/?...query"
      $term = Helpers::get_term_by_slug($town_slug);
      if ($term === null) return;
      $page_id = (int) (\get_field('main_page_alt', 'town_' . $term->term_id) ?? 0);
      if (!$page_id) $page_id = Helpers::index_town_alt_page_id() ?? 0;
      if (!$page_id) return;
      $post = \get_post($page_id);
      $wp_query = new \WP_Query(['page_id' => $page_id, 'town' => $town_slug]);
      $wp_query->is_page = true;
      $wp_query->is_front_page = true;
      $wp_the_query = $wp_query;
      \status_header(200);
      return;
 12. // url_original — внутренняя страница:
    $page_id = \url_to_postid($url_original);
    if (!$page_id) return;  // 404 от стандартного WP
    $swap = Helpers::page_unic_swap($page_id, $town_slug);
    if ($swap !== null) $page_id = $swap;
    $post = \get_post($page_id);
    $wp_query = new \WP_Query(['page_id' => $page_id, 'town' => $town_slug]);
    $wp_query->is_page = true;
    $wp_the_query = $wp_query;
    \status_header(200);
 ```
 Helper методы `strip_town_prefix` и `is_root` приватные:
 ```php
 private static function strip_town_prefix(string $uri, string $town_slug): string
 {
    $path = strtok($uri, '?');
    $query = (strpos($uri, '?') !== false) ? substr($uri, strpos($uri, '?')) : '';
    $new_path = preg_replace('#^/' . preg_quote($town_slug, '#') . '(/|$)#', '/', (string) $path);
    return ($new_path ?? '/') . $query;
 }
 private static function is_root(string $url): bool
 {
    $path = strtok($url, '?');
    return $path === '/' || $path === false || $path === '';
 }
 ```
 Также Router регистрирует `query_vars` filter:
 ```php
 add_filter('query_vars', static function (array $vars): array {
    $vars[] = 'town';
    return $vars;
 });
 ```
 Это нужно чтобы `get_query_var('town')` работал в шаблонах (WP стрипит query vars, не объявленные через filter).
 ## Redirect::handle() — алгоритм
 Регистрируется через `add_action('wp', [self::class, 'handle'], 9998)` (до Router).
 ```
 1. if (is_admin() || (defined('DOING_AJAX') && DOING_AJAX)) return.
 2. $town_slug = Helpers::current_town();
 3. $main = Helpers::main_town_slug();
 4. if ($town_slug === null || $main === null || $town_slug === $main) return.
   // Только если мы НЕ в городском префиксе URL'а
   if (preg_match('#^/' . preg_quote($town_slug, '#') . '(/|$)#', $_SERVER['REQUEST_URI'])) return.
 5. global $post;
   if (!isset($post->ID)) return.
   $current_page_id = (int) $post->ID;
 6. // Ищем: текущая страница — клон (page_new) для page_unic в контексте $town_slug?
   $page_unic = \get_field('page_unic', 'option');
   if (!is_array($page_unic)) return;
   $term = Helpers::get_term_by_slug($town_slug);
   if ($term === null) return;
   foreach ($page_unic as $row):
       if ((int) ($row['town'] ?? 0) === $term->term_id
           && (int) ($row['page_new'] ?? 0) === $current_page_id):
           $orig_id = (int) ($row['page_old'] ?? 0);
           if (!$orig_id) return;
           $orig_permalink = \get_permalink($orig_id);
           if (!$orig_permalink) return;
           $path_only = Helpers::remove_domain_link($orig_permalink);
           $redirect_to = '/' . $town_slug . $path_only;
           \wp_safe_redirect($redirect_to, 301);
           exit;
       end
   end
 ```
 Логика: если посетитель попал на оригинал-клон-страницу через нестандартный URL (без префикса города), 301 редирект на городской вариант. Поведение voluntary для SEO.
 ## Plugin::boot() — изменение
 После S2-S3 регистраций добавить:
 ```php
 OptionsPage::register();
 TermMeta::register();
 Redirect::register();   // priority 9998, до Router
 Router::register();     // priority 9999
 ```
 ## wp-multi-city.php — изменение
 `tests/TestCase.php` оставляем без изменений (REQUEST_URI cleanup уже есть). В `tearDown` дополнительно очищаем `$GLOBALS['wp_query']`, `$GLOBALS['wp_the_query']`, `$GLOBALS['post']`.
 ## tests/bootstrap.php — добавить WP_Query stub
 ```php
 if (!class_exists('WP_Query', false)) {
    eval('class WP_Query {
        public array $constructor_args = [];
        public bool $is_page = false;
        public bool $is_front_page = false;
        public bool $is_404 = false;
        public function __construct($args = []) { $this->constructor_args = is_array($args) ? $args : []; }
        public function set_404(): void { $this->is_404 = true; }
        public function set($k, $v): void {}
    }');
 }
 ```
 ## TestCase::tearDown — расширить
 ```php
 protected function tearDown(): void
 {
    unset(
        $_SERVER['REQUEST_URI'],
        $GLOBALS['wp_query'],
        $GLOBALS['wp_the_query'],
        $GLOBALS['post']
    );
    Monkey\tearDown();
    parent::tearDown();
 }
 ```
 ## Тестовый план (~35 тестов)
 ### OptionsPageTest (4)
 1. `register` вешает `acf/init` action.
 2. `do_register` вызывает `acf_add_options_page` с key `wp-multi-city`.
 3. `do_register` вызывает `acf_add_local_field_group` с group_key `group_wpmc_routing`, наличие 4 fields (main_town_slug, index_town_alt, page_unic, page_no_rep).
 4. `register` также вешает фильтр `wpmc_main_town_slug` на `Helpers::main_town_slug` priority 5.
 ### TermMetaTest (3)
 5. `register` вешает `acf/init` action.
 6. `do_register` no-op если ACF отсутствует (`function_exists('acf_add_local_field_group')` false).
 7. `do_register` вызывает `acf_add_local_field_group` с group_key `group_wpmc_town_main_page`, location=taxonomy==town, field name=main_page_alt.
 ### HelpersTest extension (6)
 8. `main_town_slug()` читает `get_field('main_town_slug', 'option')` и возвращает значение.
 9. `main_town_slug()` возвращает null если опция пуста/false.
 10. `is_routable_path('/foo/')` без page_no_rep → true.
 11. `is_routable_path('/privacy/')` когда page_no_rep содержит '/privacy/' → false.
 12. `page_unic_swap(10, 'tyumen')` находит row → возвращает clone id.
 13. `page_unic_swap` кэширует результат per-request.
 ### RouterTest (12)
 14. `register` вешает `wp` action priority 9999 + `query_vars` filter.
 15. `route()` skip если `is_admin()=true`.
 16. `route()` skip если `current_town()=null`.
 17. `route()` skip если current_town == main_town_slug.
 18. `route()` skip если `is_routable_path()=false`.
 19. `route()` для /tyumen/ + main_page_alt term-meta → $wp_query построен с page_id=main_page_alt, town=tyumen, is_front_page=true.
 20. `route()` для /tyumen/ без main_page_alt + index_town_alt опция → page_id=index_town_alt.
 21. `route()` для /tyumen/ без обоих → не патчит $wp_query.
 22. `route()` для /tyumen/about/ → url_to_postid('/about/'), $wp_query с page_id из url_to_postid.
 23. `route()` для /tyumen/about/ + page_unic swap → page_id заменён на page_new.
 24. `route()` для /tyumen/unknown/ (url_to_postid=0) → не патчит.
 25. После `route()` глобал `$wp_query->constructor_args['town']` === current_town_slug (для тестируемости get_query_var).
 ### RedirectTest (5)
 26. `register` вешает `wp` action priority 9998.
 27. `handle()` skip когда current_town === main_town_slug.
 28. `handle()` skip когда `$post` не установлен.
 29. `handle()` 301 redirect на /{town}{permalink_path} когда $post->ID — page_new клон для текущего town и текущий URL не имеет городского префикса.
 30. `handle()` skip когда URL уже имеет городской префикс (`/spb/...`).
 ### PluginBootS4Test (2)
 31. `Plugin::boot()` вешает `OptionsPage::do_register` на acf/init.
 32. `Plugin::boot()` вешает `TermMeta::do_register` на acf/init, `Router::route` на wp@9999, `Redirect::handle` на wp@9998.
 ### Reset tests (1)
 33. `Helpers::reset_cache()` обнуляет page_unic_swap_cache.
 ## Acceptance verification (после green-тестов)
 1. `vendor/bin/phpunit` — 67 тестов / 110+ assertions, 0 risky/warnings.
 2. Активировать плагин на чистом WP + ACF Pro. Создать терм `tyumen`, страницу `about`.
 3. Открыть admin → WP Multi City → выставить main_town_slug=`spb`. Добавить page_unic row (page_old=10 about, page_new=20 about-tyumen, town=tyumen).
 4. Зайти на `/tyumen/about/` → загружается page id 20 (clone), get_query_var('town')='tyumen'.
 5. Зайти на `/tyumen/` (term без main_page_alt, index_town_alt не выставлен) → стандартный WP fallback (вероятно главная или 404).
 6. Выставить term-meta main_page_alt=30 → `/tyumen/` грузит page 30 как is_front_page=true.
 7. Зайти на `/about-tyumen/` (без префикса) → 301 redirect на `/tyumen/about/` (clone маппинг сработал в Redirect).
 ## Что НЕ входит в S4
 - `home_url` фильтр — добавление городского префикса в WP-генерируемые ссылки → S5 (cp-i17)
 - `acf/load_value` фильтр — добавление префикса в URL'ы ACF полей → S5
 - `the_title` / `the_content` / `the_permalink` фильтры с `do_shortcode` → S5
 - `rest_url` фильтр (HTTP_HOST replacement) → S5
 - Кастомный sitemap (`add_sitemap_custom_items`) — out of MVP
 - Routing для post types кроме page (нянь, single posts) — washanyanya поддерживает, но не входит в MVP
 ## Open questions
 Нет. Все решения зафиксированы.