From 4e29cc223c518a30a7999dd57a4b7a41bb2ecac8 Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Mon, 6 Jul 2026 15:14:47 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20plan=20=E5=85=AC=E5=BC=80=E9=A6=96?= =?UTF-8?q?=E9=A1=B5=20+=20=E5=AE=A2=E6=88=B7=E7=AB=AF=E4=B8=8B=E8=BD=BD?= =?UTF-8?q?=E5=85=A5=E5=8F=A3=20(T-606)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 06-tasks.md 新增 T-606（路由改造 + DownloadRelease 模型 + SSR 首页/下载页 + SHA256/版本） - 02-requirements.md 新增「公开首页 + 客户端下载」P1 功能行 - progress.md 追加需求+决策记录；前期安装包放本服务器（Nginx 服务），external_url 预留后续切对象存储 Co-Authored-By: Claude Opus 4.8 --- docs/02-requirements.md | 1 + docs/06-tasks.md | 1 + progress.md | 13 +++++++++++++ 3 files changed, 15 insertions(+) diff --git a/docs/02-requirements.md b/docs/02-requirements.md index a91290e..01614ce 100644 --- a/docs/02-requirements.md +++ b/docs/02-requirements.md @@ -36,6 +36,7 @@ | 调用记录 | 每次调用落库：用户、Key、时间、操作、模型、消耗点数、成功/失败、错误 | P0 | | 点数流水 | 每次点数变动（充值/消费/退款/运营调整）落库，可对账 | P0 | | 运营后台 | django-admin 管理用户、点数、计费规则、充值订单、流水、调用记录 | P0 | +| 公开首页 + 客户端下载 | 匿名访客打开域名看到项目介绍与上手引导（注册→充值→建 Key→下载客户端）、并能下载桌面端安装包（含版本/SHA256 校验）；前期安装包托管在本服务器，后续可切对象存储/CDN | P1 | ### 后续迭代 diff --git a/docs/06-tasks.md b/docs/06-tasks.md index 631d81b..67c938d 100644 --- a/docs/06-tasks.md +++ b/docs/06-tasks.md @@ -84,6 +84,7 @@ | T-603 | django-admin 中文化（第 4 层·字段级） | T-602 | 给各模型**字段**加中文 `verbose_name`，使 admin 列表/编辑页的字段标签显示中文，在 T-602（1-3 层）之上做。范围覆盖 `users`/`billing`/`ai`（及 portal 相关）模型的业务字段，例如 `points_balance`→点数余额、`key_prefix`→Key 前缀、`points_delta`→点数变动、`balance_after`→变动后余额、`amount_money`→金额、`exchange_rate`→汇率、`points_granted`→到账点数、`api_type`/`capabilities`/`is_active`/`created_at` 等；`admin.py` 里自定义显示方法（`@admin.display(description=...)`）同步中文。**仅显示层**：`verbose_name` 只改展示，**不改字段名、不改代码引用、英文字段名保持不变**；产出的是 `AlterField`（metadata-only，**无 DB schema 变更**）迁移。验收：`makemigrations`（仅 AlterField，无 schema 变更）→ `migrate` → `check` 0 issues → `test` 全绿 → `/admin/` 字段标签目视中文，并在 `../progress.md` 留证据。T-605 已解除邮箱验证口径阻塞；当前待在稳定 MySQL 测试库上补跑完整验证后再标 `DONE` | TODO | | T-605 | 落实「免邮箱验证」策略 | T-501 | 把 `ACCOUNT_EMAIL_VERIFICATION="none"`（注册即可用、不发验证邮件、邮箱仍必填且唯一）作为**既定策略**清理落地：① `config/settings.py` 把 `ACCOUNT_EMAIL_VERIFICATION = "none"#"mandatory"` 改为干净的 `"none"`（去行内注释），并把免验证下无实际意义的 `ACCOUNT_LOGIN_ON_EMAIL_CONFIRMATION` 设为 `False`；② 更新 `apps/portal/tests.py` 里假设 mandatory 的 2 条测试（signup 不再依赖验证邮件、未验证也可直接登录），改为断言「注册后可直接登录」；③ 同步全项目文档口径（`02-requirements`/`05-coding-rules`/`api`/`04-architecture`/`03-tech-stack`/`routes`/`env`/`deployment`/`00-ai-start-here` 中「邮箱验证」→「免邮箱验证，邮箱仍唯一」）。验收：`check` 通过，`apps.portal` 26 tests OK；全量 `manage.py test` 已尝试，跑到 95/131 后因远程 MySQL 连接超时失败（WinError 10051/10060），非本任务断言失败，详见 `../progress.md` | DONE | | T-604 | 中文敏感词本地过滤（本地 keyword provider） | T-302, T-401 | 按 [`moderation.md`](moderation.md) 实施。**范围收紧**：T-604 只做输入 prompt 的本地敏感词快筛，不做云内容安全、不做输出审核、不做图片审核。**关键时序**：serializer 后先审 prompt，命中即 `400 content_blocked`；不得先下载 `image_url`，不得预扣点，不写 `CallRecord` / `PointsLedger`，不调上游。**核心实现**：新增 `apps.moderation`、`SensitiveWord` 模型/admin/迁移、keyword provider、归一化管线、Aho-Corasick matcher；`ahocorapy` 作为候选依赖，编码前必须验证 PyPI 可用性和 API 形状。**缓存**：matcher 进程内缓存，词库变更用共享 cache 版本号失效，不能只靠 `post_save` signal；生产依赖共享 cache。**配置**：`MODERATION_ENABLED=false` 默认 no-op；启用时 `MODERATION_PROVIDER=keyword`；MVP `SensitiveWord.action` 只支持 `block`。**验收**：`check`/`test` 全绿，覆盖 no-op、命中拦截且不扣点/不建记录/不调上游/不下载图片、归一化防绕过、词库变更后 matcher 重建；真实词库数据不进仓库，`__pycache__` 不进 Git | DONE | +| T-606 | 公开首页 + 客户端下载入口 | T-501 | 给网站补「前门」并提供桌面端下载。**路由改造**：`/` 从「重定向到 `/dashboard`」改为**公开首页**（匿名可访问、不跳登录）；已登录用户显示「进入控制台」，匿名显示「注册/登录 + 下载客户端」。**首页内容**（SSR 模板）：项目一句话介绍（生成标题/图片、按点数计费）+ 三步上手（注册→充值→建 API Key→桌面端填 Key）+ 下载入口 + 文档链接。**`DownloadRelease` 模型**：`platform`（如 windows）、`version`、`file`(FileField，**前期存 `MEDIA_ROOT`、服务器托管**) + `external_url`(URLField 可选，**后续切对象存储/CDN 用，有则优先**)、`sha256`、`is_current`(每平台仅一个当前版本)、`release_notes`、时间戳；admin 可上传安装包并标记当前版本；迁移。**下载区块**：展示当前 release 的版本、下载按钮、**SHA256 校验值**、可选 release notes；无 current release 时优雅提示「暂未发布」。**托管策略**：**前期安装包放本服务器**（生产由 **Nginx 直接服务 media/下载文件、不走 Django**，与 T-403 static/media serving 一致，大文件不占 gunicorn worker）；`external_url` 预留，后续切对象存储只改后台链接不改代码。**安全**：下载走 HTTPS，页面展示 SHA256 供校验；**代码签名**作为决策登记——未签名 Windows 安装包会被 SmartScreen 拦「未知发布者」、macOS 被 Gatekeeper 拦，首页先给「如何忽略警告」说明，正式签名后续补（挂 Backlog / deployment）。**含测试**：`/` 匿名 200 不跳登录、下载区展示当前 release、无 current release 优雅处理、已登录用户显示「进入控制台」。验收 `check`/`test`/`init` 全绿并在 `../progress.md` 留证据 | TODO | ## 里程碑 diff --git a/progress.md b/progress.md index 2f2e32d..ad3b55a 100644 --- a/progress.md +++ b/progress.md @@ -1268,3 +1268,16 @@ - 真实敏感词库数据不入仓库，需要运营在 admin 中维护或后续另做导入命令。 - 生产多 worker 必须使用共享 cache（DatabaseCache/Redis/Memcached）承载 `MODERATION_CACHE_VERSION_KEY`，不能依赖 `LocMemCache` 做跨进程刷新。 - 下一个看板任务仍是 T-603：在稳定 MySQL 测试库上补跑完整验证并收尾。 + +## 2026-07-06 需求+决策：公开首页 + 客户端下载入口（T-606） + +- 背景：域名根 `/` 现为「重定向到 /dashboard → 要登录」，匿名访客直接撞登录墙，无项目介绍、无客户端下载入口（线上没地方下载桌面端）。 +- 决策：加**公开首页**（补「前门」，拉注册）+ **客户端下载入口**。 +- 分析结论： + - 首页是缺失的漏斗第一环（介绍→注册→下载→建 Key→用），成本低（一个 SSR 模板，契合单体），顺带修 `/` 撞登录墙的体验。 + - 安装包是大二进制：**Django 不直接扛**，生产由 **Nginx 直接服务 media/下载文件**（与 T-403 static/media serving 一致）。 + - **前期安装包放本服务器**（`MEDIA_ROOT`）；`DownloadRelease.external_url` 字段预留，后续切对象存储/CDN 只改后台链接不改代码。 + - 生产注意：下载 HTTPS + 页面展示 SHA256 校验；**代码签名**是下载型桌面软件的真实门槛（未签名被 SmartScreen/Gatekeeper 拦），首期先给「忽略警告」说明，签名后续补。 +- 落点：`06-tasks.md` T-606（依赖 T-501）；`02-requirements.md` 新增「公开首页 + 客户端下载」P1 功能行。 +- ID 说明：T-605 已用于「免邮箱验证」，故本任务用 T-606。 +- 下一步：实现 T-606（路由改造 + DownloadRelease 模型/admin/迁移 + 首页/下载 SSR 模板 + 测试）。