补充测试覆盖率 + 新增部署引导命令 bootstrap_deployment
- 新增 apps/blog、apps/solutions、apps/home、apps/api 测试文件，覆盖标签/排序/ 草稿过滤、HomePage.subpage_types 回归测试、page_preview 预览接口 - apps/core/tests.py 新增健康检查端点、发布 webhook 信号、bootstrap_deployment 命令的测试用例，pytest 用例数从 40 增至 65，全部通过 - 修复 apps/api/urls.py 中 PagePreviewAPIViewSet.get_object() 未捕获 DoesNotExist 导致 500 而非文档承诺 404 的 bug - 新增 apps/core/management/commands/bootstrap_deployment.py：部署时按环境变量 幂等创建首个超级管理员账号并联动初始化 RBAC 权限组，.env.example 补充对应 环境变量说明 - 新增 OpenSearch + 中文分词本地 PoC 脚手架（docker-compose.opensearch.yml + docker/opensearch/Dockerfile），调研结论详见设计文档 §2.10 - 更新设计文档 §2.16 Phase 1 进度清单
This commit is contained in:
+25
-3
@@ -296,10 +296,31 @@ Next.js 侧对应 `revalidateTag` API Route，收到 webhook 后失效对应 ISR
|
||||
|
||||
### 2.10 搜索、SEO、多语言
|
||||
|
||||
- 搜索：中文分词是关键缺失点，OpenSearch 需配置 **IK 分词插件**（原文档完全没提中文分词，这是国内落地必须解决的问题）。
|
||||
- 搜索：中文分词是关键缺失点，OpenSearch 需配置 **IK 分词插件**（原文档完全没提中文分词，这是国内落地必须解决的问题）。调研结论见下方小节。
|
||||
- SEO：站点级 `sitemap.xml`（`wagtail.contrib.sitemaps`）+ 页面级 `schema_json`（JSON-LD）+ `robots.txt` 动态生成。
|
||||
- 多语言：`WAGTAIL_I18N_ENABLED` + `wagtail-localize`，URL 采用 `/zh/`、`/en/` 前缀，默认 `/zh/` 对国内用户免前缀（根路径直接是中文）。
|
||||
|
||||
#### OpenSearch + 中文分词调研（Phase 2 提前调研，新增）
|
||||
|
||||
- **Wagtail 原生已支持 OpenSearch**：本仓库安装的 Wagtail 7.4.2 底层依赖 `django-modelsearch`，已内置 `wagtail.search.backends.opensearch2`（OpenSearch 2.x）与 `opensearch3`（OpenSearch 3.x）两个后端模块，配置方式与 Elasticsearch 后端一致，**不需要任何第三方 Wagtail 插件**：
|
||||
```python
|
||||
WAGTAILSEARCH_BACKENDS = {
|
||||
"default": {
|
||||
"BACKEND": "wagtail.search.backends.opensearch2",
|
||||
"URLS": [env("OPENSEARCH_URL", default="http://localhost:9200")],
|
||||
"INDEX_PREFIX": "wagtailcms_",
|
||||
}
|
||||
}
|
||||
```
|
||||
需额外安装客户端包 `pip install "opensearch-py>=2,<3"`（版本需与 OpenSearch 服务端大版本一致）。**此配置尚未写入 settings**，留待真正接入、且本地/测试环境有可用 OpenSearch 服务时再启用，避免开发环境无 OpenSearch 服务导致搜索功能报错。
|
||||
- **中文分词方案**：OpenSearch 官方未内置中文分词器，采用社区插件 [infinilabs/analysis-ik](https://github.com/infinilabs/analysis-ik)（同一套插件同时支持 Elasticsearch 和 OpenSearch，Apache-2.0 协议，17k+ star，长期维护），提供 `ik_smart`（粗粒度，适合短语查询）与 `ik_max_word`（细粒度，适合词项查询）两个分析器，典型字段 mapping 为 `"analyzer": "ik_max_word", "search_analyzer": "ik_smart"`。Wagtail 侧可通过 `WAGTAILSEARCH_BACKENDS['default']['INDEX_SETTINGS']` 覆盖默认 `analysis.analyzer.default` 让 Wagtail 自动生成的索引改用 IK 分词，无需改 Wagtail 源码。
|
||||
- ⚠️ **插件版本必须与 OpenSearch 核心版本完全一致**才能加载成功，接入前需在 https://release.infinilabs.com/ 或用 `bin/opensearch-plugin install https://get.infini.cloud/opensearch/analysis-ik/<version>` 确认存在对应构建。
|
||||
- **本地 PoC 脚手架（已创建，未在本环境验证）**：新增 [docker-compose.opensearch.yml](../docker-compose.opensearch.yml) + [docker/opensearch/Dockerfile](../docker/opensearch/Dockerfile)，基于官方 `opensearchproject/opensearch:2.19.6` 镜像叠加 IK 插件安装，`plugins.security.disabled=true` 仅用于本地免证书调试。**当前开发环境未安装 Docker CLI，本次调研未能实际拉起容器验证**，需在具备 Docker 的机器上执行 `docker-compose -f docker-compose.opensearch.yml up -d`，并完成以下验证步骤后再正式接入：
|
||||
1. `curl http://localhost:9200/_cat/plugins` 确认 `analysis-ik` 已加载；
|
||||
2. 安装 `opensearch-py`，在 settings 中启用上面的 `opensearch2` 后端配置；
|
||||
3. `python manage.py update_index` 重建索引，用中文短语（如“产品案例”）人工验证检索召回是否符合预期的分词粒度。
|
||||
- **生产替代方案**：若不想自建/自运维 OpenSearch 集群（插件升级、扩缩容等），可评估阿里云“开放搜索 OpenSearch 版”或腾讯云 ES Serverless 的托管中文分词能力，二者原生支持中文分词、无需自装 IK 插件，代价是绑定云厂商，需按实际预算/团队运维能力二选一（已同步写入 §2.17 风险表）。
|
||||
|
||||
### 2.11 安全设计（落地到具体配置）
|
||||
|
||||
```python
|
||||
@@ -383,16 +404,17 @@ CI 中要求单元测试覆盖率不低于 70%，核心 `apps/forms`（涉及线
|
||||
- [x] Next.js 前端脚手架（独立仓库）：Header/Footer/layout、首页、博客/产品/案例/解决方案列表与详情页、`BlockRenderer`、ISR + revalidate route，`lint`/`build` 已验证通过
|
||||
- [x] pytest 基础测试框架（pytest-django + factory_boy）：`pytest.ini` + `conftest.py`（root_page/home_page fixtures），为 `apps/core`（SEOablePage 字段、FormBlock API 表示、SimpleContentPage 页面树、Snippet 模型与只读 API）、`apps/products`、`apps/cases`、`apps/forms`（线索提交 API、蜜罐反垃圾字段、PIPL 数据删除权申请/确认流程）编写了基础单元测试，共 31 个用例均通过
|
||||
- [x] `apps/core.SimpleContentPage`：通用富文本法务/说明类页面模型，用于隐私政策等内容，配套 `seed_privacy_policy` management command 用于幂等创建/更新隐私政策页面（需在 HomePage 实例存在后手动运行）
|
||||
- [x] 部署引导 management command `bootstrap_deployment`：读取 `DJANGO_SUPERUSER_USERNAME`/`_EMAIL`/`_PASSWORD` 三个环境变量，若均已设置且用户名不存在则创建首个超级管理员账号（已存在则跳过，不覆盖密码），随后自动调用 `setup_rbac_groups` 初始化 RBAC 权限组；幂等，可放入部署脚本/容器启动流程的 `migrate` 之后执行，解决“首次部署后如何登录 Wagtail 后台”的鸡生蛋问题；`.env.example` 已补充对应三项环境变量说明；新增 4 个单元测试覆盖建号/跳过/不覆盖密码/联动 RBAC 四种场景
|
||||
- [x] Snippet：`TeamMember`/`Testimonial`/`Partner`（简单 `@register_snippet`，均含 `order` 排序字段）、`NavigationMenu`+`NavigationMenuItem`（`ClusterableModel`+`Orderable`+`InlinePanel`，内部页面/外部链接二选一）、`SiteSettings`（`wagtail.contrib.settings` + `BaseSiteSetting`，公司信息/ICP备案/社交账号全局配置）均已创建；只读 API 挂载于 `/api/v1/custom/core/`（`team/`、`testimonials/`、`partners/`、`navigation/?name=`、`site-settings/`，限流 public 100/min）；前端 `Header`/`Footer` 已接入 `NavigationMenu`/`SiteSettings`（接口不可用时回退静态内容），`TeamMember`/`Testimonial`/`Partner` 已提供 service 层，页面级展示留待对应 StreamField Block（见下）落地时接入
|
||||
- [x] 预览模式：后端引入 `wagtail-headless-preview`（0.9.0），`SEOablePage` 混入 `HeadlessPreviewMixin`（自动覆盖全部 6 个页面模型），新增自定义 `PagePreviewAPIViewSet` 挂载于 `/api/v2/page_preview/`；前端新增 `services/preview.service.ts`（`getPreviewOrFallback`/`fetchPreviewPage`/`resolvePreviewPath`）、`/preview`与 `/preview/disable` 两个 Route Handler（基于 Next.js Draft Mode + httpOnly cookie），并在首页/博客/产品/案例/解决方案详情页接入草稿优先逻辑，`layout.tsx` 新增预览模式提示条（含退出链接）；`lint`/`build` 均验证通过，后端 31 个现有用例均通过（本次未新增自动化测试，仅依靠人工验证）
|
||||
- [x] 剩余 6 个 StreamField Block（`ProductCardBlock`/`PricingBlock`/`TimelineBlock`/`TeamBlock`/`TechStackBlock`/`VideoBlock`）已全部开发完成：`apps/core/blocks.py` 新增对应 Block 类并扩充 `COMMON_BLOCKS`（现共 14 个内容 Block + 1 个 `richtext`），因 Wagtail StreamField 会将 Block 结构写入迁移（`use_json_field=True` 不代表可跳过迁移），已为 blog/cases/home/products/solutions 五个 Page 模型生成并应用 `alter field body` 迁移；`TeamBlock` 复用 `FormBlock` 的 `get_api_representation` 覆写模式，新增 `TeamMemberChooserBlock(SnippetChooserBlock)` 展开 `TeamMember` 完整字段（含 `serialize_image` 复用），并补充对应的空值/展开单元测试（新增 2 个用例，后端共 33 个测试全部通过）；前端 `types/wagtail.ts` 新增 6 个 Block 值类型与 `StreamFieldBlock` 联合类型分支，新建 6 个渲染组件（`ProductCardGrid`/`Pricing`/`Timeline`/`Team`/`TechStack`/`Video`）并接入 `BlockRenderer.tsx` 映射表，`lint`/`build` 均验证通过
|
||||
- [x] RBAC 落地：`python manage.py setup_rbac_groups` 幂等命令创建 5 个 Wagtail Group（站点管理员/编辑/审核员/作者/查看者）并按 §2.8 矩阵配置 `GroupPagePermission`/`GroupCollectionPermission`/Snippet 与用户管理 `Permission`；Author“仅自己”利用 Wagtail 内置 `OwnershipPermissionPolicy`（仅 add 权限）原生实现，无需自定义 hook；新增 7 个后端单元测试，全仓库 pytest 从 33 增至 40，全部通过
|
||||
|
||||
未完成（待规划排期）：
|
||||
- [ ] 测试覆盖率仍不完整（已有基础单元测试，但集成测试、前端组件测试、E2E 均未编写，当前无 CI 流水线）
|
||||
- [ ] 测试覆盖率持续提升中：后端 pytest 用例从 40 个增至 65 个，新增覆盖 `apps/blog`（标签、列表排序/草稿过滤）、`apps/solutions`（页面树、草稿过滤）、`apps/home`（`HomePage.subpage_types` 回归测试，覆盖此前"后台无法添加子页面"的 bug 场景）、`apps/core` 健康检查端点 `/healthz`/`/readyz`、发布后 revalidate webhook 信号（含正常/未配置/网络异常三种路径）、`apps/api` 预览接口 `page_preview`（含无效 token/content_type 场景，过程中顺带修复了一个真实 bug：无效 token 之前会 500 而非文档承诺的 404）、`bootstrap_deployment` 部署引导命令（建号/跳过/不覆盖密码/联动 RBAC）；但集成测试、前端组件测试、E2E 均未编写，当前无 CI 流水线
|
||||
- [x] 生产安全 settings（§2.11 中 `SECURE_*`/CORS/CSRF 白名单等）已在 `production.py` 中逐项落实，并补充 `SECURE_PROXY_SSL_HEADER`（适配国内云厂商 SLB/CLB 边缘终止 TLS 场景）；实际域名需在部署时通过 `.env` 填入
|
||||
- [x] ICP 备案、页脚备案号展示、隐私政策内容、Cookie 同意条控件、表单 PIPL 数据删除权支持、字体/地图/验证码/CDN 国内可访问排查均已完成，§2.15 合规与本地化清单已全部完成
|
||||
- [ ] 中文分词、OpenSearch 集成（Phase 2 提前项）未开始
|
||||
- [ ] 中文分词、OpenSearch 集成（Phase 2 提前项）：**调研已完成**（结论见 §2.10 “OpenSearch + 中文分词调研”小节：确认 Wagtail 7.4.2 原生内置 `opensearch2`/`opensearch3` 后端 + infinilabs `analysis-ik` 插件的可行方案，并新增本地 Docker Compose PoC 脚手架 `docker-compose.opensearch.yml`），**实际接入（拉起容器验证插件加载、切换 `WAGTAILSEARCH_BACKENDS`、建站内容重建索引）仍未开始**，待具备 Docker 环境后再验证落地
|
||||
|
||||
### 2.17 风险与备选方案
|
||||
|
||||
|
||||
Reference in New Issue
Block a user