文档修改

Project/fonrey/prompt/提示词模板/创建项目骨架提示词_v2.3.md

@@ -1,6 +1,6 @@
 # Fonrey 项目骨架搭建 — 工程执行提示词
-> **版本**：v2.2（2026-04-28）｜v2.0 修复 P0×5+P1×4；v2.1 修复 P0×9（交叉比对 AGENTS.md / 测试规范.md / 系统管理技术文档.md）；v2.2 收口剩余一致性问题（URL 分离、Admin 弃用、密钥变量统一、测试 settings 一致性、环境变量占位修复）
-> **v2.2 主要变更**：统一 `config/urls.py` / `config/urls_public.py` 职责并修正执行清单；移除 Django Admin 路由引用（对齐系统管理技术文档）；PII 密钥统一为 `PHONE_ENCRYPTION_KEY`；`pyproject.toml` 测试 settings 对齐 `config.settings.testing` 并新增 `testing.py` 生成要求；修复 AWS/R2 示例占位符与 `.env.example` 断行问题；修正 docker-compose 服务数量描述
+> **版本**：v2.3（2026-04-29）｜v2.0 修复 P0×5+P1×4；v2.1 修复 P0×9（交叉比对 AGENTS.md / 测试规范.md / 系统管理技术文档.md）；v2.2 收口剩余一致性问题（URL 分离、Admin 弃用、密钥变量统一、测试 settings 一致性、环境变量占位修复）；v2.3 修复开工阻塞（R2 密钥变量名、release 结构冲突、DB 连接参数）并补齐 API_CONTRACT 核对清单
+> **v2.3 主要变更**：修复 `AWS_SECRET_ACCESS_KEY` 环境变量占位错误（统一为 `R2_SECRET_ACCESS_KEY`）；移除 `DATABASES.OPTIONS.pool_size` 非标准参数；修正执行清单中 `apps/release` 误要求 `services/` 与 `tasks.py` 的冲突；补充 API_CONTRACT 强制核对清单（路径/方法/参数/响应 envelope/错误码/@extend_schema/openapi.json/schemathesis）；统一 URL 命名口径说明（`config.urls` 对应系统文档 `config.urls_tenant`）
 ## 你的角色与约束
 你是一名资深 Django 后端工程师。你的任务是**严格按照规范**搭建 Fonrey 项目骨架，不得自行发明技术方案，不得引入文档未授权的第三方库。每一步操作后必须验证结果。
 **项目工作目录**：`/mnt/c/Project/`（在此目录下创建 `fonrey/` 子目录）
@@ -188,7 +188,7 @@ from django.urls import path, include
 from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView
 
 urlpatterns = [
-    path("api/client/updates/latest/", include("apps.release.urls")),
+    path("api/client/", include("apps.release.urls")),  # apps.release.urls 内定义 updates/latest/
     # OpenAPI — 仅 DEBUG 暴露，production 通过 nginx ACL 限制
     path("api/schema/", SpectacularAPIView.as_view(), name="schema"),
     path("api/docs/", SpectacularSwaggerView.as_view(url_name="schema"), name="swagger-ui"),
@@ -200,6 +200,7 @@ urlpatterns = [
 # config/settings/base.py — 多租户 URL 分离配置（必须显式声明）
 ROOT_URLCONF = "config.urls"                          # tenant schema 路由入口
 PUBLIC_SCHEMA_URLCONF = "config.urls_public"          # public schema 路由入口
+# 口径说明：系统管理技术文档中的 `config.urls_tenant` 在本骨架中命名为 `config.urls`，语义等价。
 ```
 
 > `config/urls.py` 仅包含 `urlpatterns`（tenant 路由），`config/urls_public.py` 包含 `urlpatterns`（public 路由）。两个文件分开维护，**不得合并**。
@@ -255,7 +256,7 @@ DATABASES = {
         "HOST": env("DB_HOST", default="localhost"),
         "PORT": env("DB_PORT", default="5432"),
         "CONN_MAX_AGE": 60,
-        "OPTIONS": {"pool_size": 10},  # PgBouncer 协同
+        # PgBouncer 连接池在 DB/Proxy 层管理；此处不注入非标准 DSN 参数，避免驱动报错
     }
 }
 DATABASE_ROUTERS = ["django_tenants.routers.TenantSyncRouter"]
@@ -317,7 +318,7 @@ SPECTACULAR_SETTINGS = {
     "VERSION": "1.0.0",
     "SERVE_INCLUDE_SCHEMA": False,
     "COMPONENT_SPLIT_REQUEST": True,
-    "ENUM_GENERATE_CHOICE_DESCRIPTION": False,  # 枚举说明由 ENUMS.md 权威维护
+    "ENUM_GENERATE_CHOICE_DESCRIPTION": True,   # 对齐 API_CONTRACT.md §11，Schema 中展开枚举说明
 }
 # 日志（骨架，production 扩展）
 LOGGING = {
@@ -785,7 +786,7 @@ CELERY_BROKER_URL=redis://redis:6379/1
 # Cloudflare R2
 R2_ENDPOINT_URL=https://<account_id>.r2.cloudflarestorage.com
 R2_ACCESS_KEY_ID=
-R2_SECRET_ACCESS_KEY=
+R2_SECRET_ACCESS_KEY=<your_r2_secret_access_key>
 R2_BUCKET_NAME=media
 R2_CUSTOM_DOMAIN=
 # Sentry（production 填写）
@@ -840,7 +841,21 @@ python_files = ["test_*.py", "*_test.py"]
 addopts = "--reuse-db --cov=apps --cov=core --cov-report=term-missing -n auto"
 ```
 ---
-## 十五、执行顺序与验证清单
+## 十五、API_CONTRACT 契约核对清单（强制）
+在生成任何 API 相关骨架（含 `apps/release`、OpenAPI 路由、契约测试占位）时，必须逐项核对：
+
+- [ ] **路径与方法**：端点路径/HTTP Method 与 `TECH_STACK/API_CONTRACT.md` 及模块文档一致
+- [ ] **请求参数**：query/path/body 字段名、类型、必填/可选与契约一致
+- [ ] **响应 envelope**：成功返回 `ok=true` + `data` + `meta`；失败返回 `ok=false` + `error` + `code` + `details` + `meta`
+- [ ] **错误码**：`code` 使用稳定 `UPPER_SNAKE_CASE`，并与模块前缀语义一致
+- [ ] **OpenAPI 注解**：视图补齐 `@extend_schema`（或 `@extend_schema_view`）
+- [ ] **Schema 文件**：可执行 `python manage.py spectacular --file openapi.json` 成功生成
+- [ ] **契约测试**：`schemathesis` 命令可运行（至少保留 Positive 路径骨架）
+
+交付时必须附带“API 契约核对结果”小节，按以上 7 项逐项标注 ✅/❌ 与证据（文件路径 + 行号）。
+
+---
+## 十六、执行顺序与验证清单
 按以下顺序执行，每步完成后打 ✅：
 ```
 [ ] 1. 创建根目录 fonrey/ 及上述完整目录树（含所有 __init__.py）
@@ -857,7 +872,7 @@ addopts = "--reuse-db --cov=apps --cov=core --cov-report=term-missing -n auto"
 [ ] 11. 创建 core/htmx.py（htmx_response 工具）
 [ ] 12. 创建 core/templatetags/heroicons.py
 [ ] 13. 创建 core/middleware/audit.py（骨架）
-[ ] 14. 为每个 App 创建目录结构（含 apps.py、models/__init__.py、services/__init__.py、tasks.py 骨架、views.py 骨架、urls.py 骨架）
+[ ] 14. 为每个 App 创建目录结构（`apps/release` 除外；其余含 apps.py、models/__init__.py、services/__init__.py、tasks.py 骨架、views.py 骨架、urls.py 骨架）
 [ ] 15. 创建 apps/tenant/models.py（Tenant、Domain 模型，django-tenants 规范）
 [ ] 16. 创建 templates/ 完整目录树及 base.html、layouts/app.html、layouts/auth.html 骨架
 [ ] 17. 创建 components/ 模板骨架（topbar, sidebar, pagination, toast, modal, empty-state）
@@ -871,9 +886,10 @@ addopts = "--reuse-db --cov=apps --cov=core --cov-report=term-missing -n auto"
 [ ] 25. 创建 manage.py
 [ ] 26. 验证：python manage.py check --deploy 无致命错误
 [ ] 27. 验证：项目目录树与第二节规范 100% 匹配
+[ ] 28. 验证：API_CONTRACT 核对清单 7 项全部完成（含 openapi.json 生成与 schemathesis 骨架）
 ```
 ---
-## 十六、关键注意事项
+## 十七、关键注意事项
 1. **django-tenants `apps/tenant/models.py`** 必须定义 `Tenant`（继承 `TenantMixin`）和 `Domain`（继承 `DomainMixin`），且 `Tenant` 的 `auto_create_schema = True`。
 2. **`shared/` App** 的 `apps.py` 中 `name = "shared"`，用于公共 Schema 的跨租户共享数据（如 PermissionDef 等）。
 3. **所有 App 的 `apps.py`** 必须包含正确的 `name`（含包路径，如 `apps.property`）和 `verbose_name`（中文）。
@@ -883,4 +899,4 @@ addopts = "--reuse-db --cov=apps --cov=core --cov-report=term-missing -n auto"
 7. **模板中所有异步 HTMX 请求**在骨架阶段只需占位，但必须包含正确的 `hx-` 属性结构，不可省略 `hx-target` 和 `hx-swap`。
 8. **Toast 系统**：前端监听 `htmx:afterRequest` 事件，检查响应头 `HX-Trigger` 中的 `fonrey:toast`，动态插入 Toast DOM，4 秒自动消失。
 9. **小屏拦截**：`layouts/app.html` 中内嵌 JS，`window.innerWidth < 1280` 时显示全屏遮罩，文案："Fonrey 当前仅支持桌面端（≥1280px），请在电脑上访问"。
-10. **所有密码、密钥、Tenant ID** 禁止出现在任何 Python 文件中，统一从 `python-decouple` 的 `env()` 读取。
+10. **所有密码、密钥、Tenant ID** 禁止出现在任何 Python 文件中，统一从 `python-decouple` 的 `env()` 读取。