From f6babd9e5e66f5d462142ea12ee0fd4d3deeeaf6 Mon Sep 17 00:00:00 2001 From: Renko6626 <2300011496@stu.pku.edu.cn> Date: Sun, 8 Nov 2026 01:20:37 +0800 Subject: [PATCH 1/4] feat: add pinyin candidate search with Redis caching --- docs/CHANGELOG.md | 8 + docs/README.md | 4 +- docs/api/voteable-api-contract.md | 42 ++-- .../2026-11-08-pinyin-candidate-search.md | 192 ++++++++++++++ ...26-11-08-pinyin-candidate-search-design.md | 235 ++++++++++++++++++ pyproject.toml | 1 + src/apps/autocomplete/candidate_search.py | 69 +++++ src/apps/autocomplete/dao.py | 25 ++ src/apps/autocomplete/pinyin.py | 87 +++++++ src/apps/autocomplete/router.py | 26 +- src/apps/autocomplete/schemas.py | 20 +- tests/integration/test_autocomplete.py | 107 ++++++++ tests/integration/test_vote_objects.py | 38 +++ tests/unit/test_pinyin_matcher.py | 33 +++ 14 files changed, 868 insertions(+), 19 deletions(-) create mode 100644 docs/superpowers/plans/2026-11-08-pinyin-candidate-search.md create mode 100644 docs/superpowers/specs/2026-11-08-pinyin-candidate-search-design.md create mode 100644 src/apps/autocomplete/candidate_search.py create mode 100644 src/apps/autocomplete/pinyin.py create mode 100644 tests/unit/test_pinyin_matcher.py diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index d57c7889..edbd7cd4 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -5,6 +5,14 @@ > 创建日期:2026-04-27 > **2026-08-31 整理**:合并 9 组重复条目、按日期倒序重排;**2026-07-01 之前**的条目已迁至 [CHANGELOG-archive-2026H1.md](./CHANGELOG-archive-2026H1.md)。 +## [2026-11-08] 拼音候选搜索迁至 Python 后端 + +- **Added**:`pypinyin==0.55.0` 与项目内纯匹配器,支持原文、全拼、声母简拼、多音字、混输和原有模糊音;新增 `POST /api/v1/autocomplete/candidates/search`,按分类与年度返回全部匹配 candidate IDs。 +- **Added**:Redis 派生语料及查询结果各缓存 60 秒,复用现有 autocomplete 写入失效、手动清理及故障直算逻辑;不增加数据库字段或 JS 运行时。 +- **Changed**:配套前端角色、音乐与 CP 成员选择使用新接口;保留个人筛选与排序,增加等待/失败提示并忽略过期响应,移除前端 Pinin。设计、实施计划和 API 契约已同步。 +- **兼容性影响**:旧 `/autocomplete/search` 不变;需先发布后端,再发布配套前端;回滚先前端后后端。当前只在两个 `feat/pinyin-backend-search` 分支本地实现,未部署。 +- **数据迁移 / 配置变更**:无数据迁移或新增配置;后端安装新增 Python 依赖。Redis 沿用既有配置。 + ## [2026-10-29] 生产上线前加固:关闭 API 文档 + 移除测试登录旁路 + deploy-prod 流水线 - **Added**:`Settings.expose_api_docs`(`EXPOSE_API_DOCS`,默认 `false`)。`src/main.py` 按开关传 `docs_url`/`redoc_url`/`openapi_url`,并给 `AppGraphQLRouter` 传 `graphql_ide`——关闭时 `/docs`、`/redoc`、`/openapi.json`、浏览器打开 `/graphql` 均 404,`POST /graphql` 不受影响。回归用例 `tests/unit/test_expose_api_docs.py`(8 例)。 diff --git a/docs/README.md b/docs/README.md index a8e50bec..45523989 100644 --- a/docs/README.md +++ b/docs/README.md @@ -154,6 +154,7 @@ |---|---| | [`2026-06-08-questionnaire-backend-design.md`](./superpowers/specs/2026-06-08-questionnaire-backend-design.md) | 问卷结构化后端(B-039):4 结构表 + admin 整树导入 + structure 查询 + 完成校验升级 | | [`2026-06-08-vote-objects-backend-design.md`](./superpowers/specs/2026-06-08-vote-objects-backend-design.md) | 投票对象迁后端(B-040):`merged_into` 去重合并 + 分类查询端点 | +| [`2026-11-08-pinyin-candidate-search-design.md`](./superpowers/specs/2026-11-08-pinyin-candidate-search-design.md) | **已确认、本地实现**:pypinyin 匹配模块、候选 ID 搜索、Redis 派生语料与结果缓存、投票页三个入口迁移 | ### 前端侧设计(`thvote-fe` / `Touhou-Vote` 仓库) @@ -178,7 +179,7 @@ ## 实施计划(`superpowers/plans/`) -> **只剩未实施完的 5 份 + 本轮 1 份**。已执行完毕/废弃的 26 份在 [`archive/superpowers/plans/`](./archive/superpowers/plans/)。 +> 本节保留尚需实施或追溯的计划;已执行完毕/废弃的历史计划见 [`archive/superpowers/plans/`](./archive/superpowers/plans/)。具体确认与实施状态见各文档头部。 > ⚠️ plans 里的 `- [ ]` checkbox **从未被维护过**(BACKLOG **B-057⑤**),不要拿它判断完成度。 | 文档 | 状态 | @@ -189,6 +190,7 @@ | [`2026-06-08-vote-objects-frontend.md`](./superpowers/plans/2026-06-08-vote-objects-frontend.md) | 待实施(B-040 前端) | | [`2026-06-08-questionnaire-admin-frontend.md`](./superpowers/plans/2026-06-08-questionnaire-admin-frontend.md) | 待实施(B-041 投票前端) | | [`2026-07-21-work-table-unified.md`](./superpowers/plans/2026-07-21-work-table-unified.md) | **部分实施**:后端主体已合入 main,收尾清单见 BACKLOG **B-057** | +| [`2026-11-08-pinyin-candidate-search.md`](./superpowers/plans/2026-11-08-pinyin-candidate-search.md) | **已本地实现、未部署**:匹配器 → 后端 API 与缓存 → 前端请求状态 → 三入口替换和依赖清理 | --- diff --git a/docs/api/voteable-api-contract.md b/docs/api/voteable-api-contract.md index dcad4244..b9921dd3 100644 --- a/docs/api/voteable-api-contract.md +++ b/docs/api/voteable-api-contract.md @@ -460,25 +460,36 @@ GET /vote-objects/{category}/{candidateId} ## 七、自动补全 -### `POST /autocomplete/search` +### `POST /autocomplete/search`(原接口保留) -```typescript -// Request: -{ - "query": "博麗", - "categories": ["character", "music", "cp"], - "limit": 10 -} +```json +// Request +{ "query": "博麗", "limit": 10 } +// Response +{ "suggestions": [{ "name": "博麗靈夢", "type": "character", "origin": "東方紅魔鄉" }] } +``` -// Response: -{ - "character": [{ "name": "博麗靈夢", "origin": "東方紅魔鄉", ... }], - "music": [...], - "cp": [] -} +该接口按配置年度提供名称 ILIKE 建议,不返回候选 ID;不接受 categories 筛选。角色与音乐合并在 `suggestions` 中,CP 组合建议仍未实现。 + +### `POST /autocomplete/candidates/search`(2026-11-08 本地实现,未部署) + +完整路径为 `/api/v1/autocomplete/candidates/search`;投票前端通过现有 API_PREFIX 转发。 + +```json +// Request(vote_year 可省略,默认服务配置年度) +{ "category": "character", "query": " MLS ", "vote_year": 12 } +// Response(ID 仅为格式示例) +{ "category": "character", "query": "mls", "vote_year": 12, "candidate_ids": [123] } ``` -> 🚧 本次改动后,前端投票页改用 `/vote-objects` 返回的 `aliasMap` 做本地匹配。此接口保留,供其他场景使用。 +- `category` 限 `character` / `music`;CP 成员按 character 搜索,不推荐 CP 组合。 +- query 原始长度最多 64 个 Unicode 码点,去首尾空白并转小写;vote_year 为正整数。非法输入返回 422。 +- 搜索当年候选的名称、各别名和主作品/专辑名;各字段独立匹配,不跨字段拼接,不含 name_jp 或音乐 include。 +- 支持原文、全拼、声母简拼、多音字、混输、末音节前缀及既有模糊音规则;详细规则见 [设计](../superpowers/specs/2026-11-08-pinyin-candidate-search-design.md)。 +- 返回全部匹配的 **candidate ID**,升序去重,无 limit;空查询返回当年该分类全部 ID,未知年度返回空数组。 +- 前端将整数 ID 转字符串,与当前候选求交;个人已选项排除、CP 可重复成员、作品/类别筛选及日期排序留在前端。空查询不发请求;等待与失败有提示,过期响应不会覆盖新查询。 +- 派生拼音语料和查询结果(含空数组)各缓存 60 秒;Redis 失败直接读数据库计算,数据库失败正常报错。现有写入失效及 `scope=autocomplete` 同时清理两类缓存。绕过正常失效时,两层 TTL 叠加最多约 120 秒旧结果。 +- 无数据库 schema 或数据迁移。发布顺序为后端先、前端后;回滚先前端,再按需回后端。 --- @@ -712,6 +723,7 @@ Query: category?, vote_year? | 投票对象列表/详情 | `vote_objects:{year}:{category}[:{id}]` | 600s | work CRUD、voteable 导入/改归属/改资源、候选导入/改/删/合并 | | 问卷结构 | `questionnaire:structure:{year}` | 1800s | 问卷/题组/问题/选项 CRUD、整树导入 | | 自动补全 | `autocomplete:{year}:{limit}:{q}` | 60s | 候选/作品变更 | +| 拼音候选语料/结果 | `autocomplete:pinyin:v1:{year}:{category}:corpus` / `...:q:{sha256(query)}` | 各 60s | 与自动补全共用失效前缀 | | 已通过提名 | `nominations:approved:{page}:{size}` | 60s | 提名 approve/reject | - 失效用 `SCAN` 前缀删除(非 `KEYS`);管理台可用 `POST /admin/cache/flush` 手动强刷。 diff --git a/docs/superpowers/plans/2026-11-08-pinyin-candidate-search.md b/docs/superpowers/plans/2026-11-08-pinyin-candidate-search.md new file mode 100644 index 00000000..8571e93a --- /dev/null +++ b/docs/superpowers/plans/2026-11-08-pinyin-candidate-search.md @@ -0,0 +1,192 @@ +# 拼音候选搜索后端化实施计划 + +> 状态:2026-11-08 用户已确认;四项任务已本地实现并通过相关检查及最终只读审阅。未发布或部署。 +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans when implementing inline; use superpowers:subagent-driven-development only when the user chooses delegated execution. Steps use checkbox (`- [x]`) syntax. Project AGENTS.md and current user authorization take precedence. + +**Goal:** 将角色、音乐与 CP 成员选择中的拼音搜索迁到 Python 后端,保留原文、简拼、混输和已配置的模糊音。 + +**Architecture:** 纯匹配器位于 `apps/autocomplete/pinyin.py`;候选用例负责 DAO 与 Redis;加法式 ID 搜索接口供前端三个选择入口使用。前端继续过滤个人已选项及作品类别,保持日期排序。派生语料与搜索结果首版只存 Redis。 + +**Tech Stack:** Python >=3.12、pypinyin==0.55.0、现有 FastAPI / SQLAlchemy / Redis;现有 Vue 3 / TypeScript / node:test / tsx。 + +**Spec:** [拼音候选搜索后端化设计](../specs/2026-11-08-pinyin-candidate-search-design.md)。本文与设计一起阅读;本轮仅执行已确认范围。 + +## Global Constraints + +- 只覆盖投票页角色、音乐和 CP 成员搜索;不扩展结果页、CP 组合推荐或管理端拼音编辑。 +- 不改变旧 `/api/v1/autocomplete/search`;新增 `/api/v1/autocomplete/candidates/search`,返回全部匹配 candidate IDs。 +- character 搜索 `name/aliases/work.name`;music 搜索 `name/aliases/work.name`;不跨字段匹配,不扩大到 `name_jp/include`。 +- query 长度最多 64 个 Unicode 码点;规范化为 `strip().lower()`。年度按请求或 settings 明确解析。 +- Redis 内部前缀 `autocomplete:pinyin:v1:`,语料和结果各 TTL 60 秒;不使用 `result:*`。 +- 无数据库 schema、数据回填、进程级候选缓存、锁、等待队列、自动重试或恢复流程。 +- 未获授权不 commit、push、发布、部署、重新计票或写真实数据库。不要把每段完成等同于提交授权。 +- 保留两仓库无关改动;合作者分支只读。UI 验证最多截图,不自动点击或填表。 +- 新测试只覆盖关键新增行为,复用现有 SQLite / fakeredis / node:test;本计划不要求全量测试或新端到端环境。 + +## Review Focus + +以下五点分别归入相应任务的测试,不另建重复测试层: + +1. 缩写或模糊音扩大匹配范围:`limi` 不应匹配“灵米”;Task 1。 +2. 不同名称、别名和作品被拼接后误命中,以及不同年度 ID 混用;Task 2。 +3. 空结果缓存、写后失效及 Redis 故障不能被当作业务零命中;Task 2。 +4. 连续输入、清空或请求先后颠倒时旧结果覆盖新结果;Task 3。 +5. 返回整数 ID 与前端字符串 ID、已选项排除、CP 可重复成员及日期排序;Task 4。 + +## 开始执行前(已完成) + +确认设计中的模块位置、新接口和 Redis 存储方案。两端均使用 `feat/pinyin-backend-search`。前端原目录的未提交现场已归档和 stash,切换后保留尚未被上游包含的本地修改;原快照未删除。 + +查一次当前远端是否变化;若搜索相关实现出现新改动,先更新基线记录。不得借此自动发布或清理分支。依赖已经存在且无代码改动时,不为准备工作反复安装依赖或跑全量测试。 + +## Task 1:纯拼音准备与匹配 + +**Files:** +- Create: `src/apps/autocomplete/pinyin.py` +- Modify: `pyproject.toml` +- Create: `tests/unit/test_pinyin_matcher.py` + +**Interfaces:** +- Consumes: 原始独立文本,以及由用例层规范化后的 query。 +- Produces: `TextUnit`(原字、多个声母/韵母二元组)、`PreparedText = tuple[TextUnit, ...]`、`prepare_text(text: str) -> PreparedText`、`contains(text: PreparedText, query: str) -> bool`。 + +- [x] 在一个参数化用例中放设计 §4.4 的独立正反例,新增多音字不同读音、查询末尾未输完、单向规则不能反向扩大、英文标点原文的最小覆盖。不枚举所有读音组合。 +- [x] 运行 `python -m pytest tests/unit/test_pinyin_matcher.py -q`,确认新增行为尚未实现。不要把依赖未安装造成的 import error 当作行为失败的充分证据。 +- [x] 经已确认依赖路线添加 `pypinyin==0.55.0`。逐字获取无声调多读音,保留原文分支;按设计 §4 的字面声母/韵母拆分和非递归规则生成匹配选项。 +- [x] 用记忆化查询位置匹配或等价二维 DP 实现 `contains`:从任意原文位置开始,消费连续原文字,可在各字原文/声母/完整读音间混合选择;只有查询结束时允许读音前缀未输完。不跳过原文字,不用正则解释 query。 +- [x] 示例预期必须直接成立,不依赖旧库输出或复制生产算法: + +```python +assert contains(prepare_text("雾雨魔理沙"), "mo理sha") is True +assert contains(prepare_text("二小姐"), "rxiaojie") is True +assert contains(prepare_text("路米"), "lvmi") is True +assert contains(prepare_text("灵米"), "limi") is False +assert contains(prepare_text("魔甲理沙"), "mls") is False +``` + +- [x] 再运行该测试文件。对关键样例有分歧时定位读音来源或匹配规则;不为消除分歧擅自修改产品预期。需要时在临时环境对照旧 Pinin,不能将 JS 加进生产或永久 Python 测试依赖。 + +**交付:** 可独立调用的纯匹配器;它不知候选、年度、数据库或 Redis。 + +## Task 2:候选 ID 接口、语料与结果缓存 + +**Files:** +- Create: `src/apps/autocomplete/candidate_search.py` +- Modify: `src/apps/autocomplete/dao.py` +- Modify: `src/apps/autocomplete/schemas.py` +- Modify: `src/apps/autocomplete/router.py` +- Modify only if an existing invalidation call is missing: `src/apps/admin/router.py` +- Extend: `tests/integration/test_autocomplete.py` +- Extend narrowly for HTTP contracts: `tests/integration/test_vote_objects.py` +- Read / reuse: `src/common/cache.py`, `tests/unit/test_cache.py` + +**Interfaces:** +- Consumes: Task 1 的准备与匹配函数。 +- Produces: `AutocompleteDAO.load_search_documents(self, category: Literal["character", "music"], vote_year: int) -> list[tuple[int, tuple[str, ...]]]`。 +- Produces: `CandidateSearchRequest(category, query, vote_year=None)`、`CandidateSearchResponse(category, query, vote_year, candidate_ids)`,精确约束见设计 §5。 +- Produces: `CandidateSearchService(dao, redis, default_year)` 与 `async search(request: CandidateSearchRequest) -> CandidateSearchResponse`;HTTP POST `/api/v1/autocomplete/candidates/search`。 + +- [x] 复用 `test_autocomplete.py` 的真实 SQLite session;加入新 DAO 和服务行为用例。使用现有 fakeredis 条件,不另建测试工程。 +- [x] 用同一 voteable 的两个年度候选验证返回的是请求年度的 candidate ID;名称、别名、work.name 均可独立命中。让 query 只能跨两个字段拼接时不命中。 +- [x] 一次增加 11 条可匹配候选,断言全部 11 个 ID 返回且无重复;覆盖空查询全部、未知年度空集合。这个用例专门避免旧默认 limit=10 被带入新接口。 +- [x] 在真实 DAO + fakeredis 服务测试中验证:缓存命中、空结果命中、改变查询仍可复用派生语料,以及调用现有 autocomplete 前缀失效后能看到修改后的别名。不用“执行了某个内部函数”代替返回值断言。 +- [x] Redis 故障使用一个明确抛连接异常的缓存替身,但 DAO 和匹配器保持真实;断言仍返回实际命中 ID。数据库失败须传播错误,不缓存成空集合。 +- [x] 按设计 §6 实现两个 JSON 缓存;共享 namespace 不包含用户已选项,结果值只存完整 ID 列表。语料存原字及音节二元组,缓存版本为 `v1`,两层 TTL 都为 60 秒;复用现有 fail-open helpers。 +- [x] 在 `test_vote_objects.py` 复用现有 app/engine/patch_redis,仅覆盖新 POST 路径、回显字段、非法 category、超长 query、默认年度和显式年度。原有算法/DAO 场景不复制到 HTTP 层。 +- [x] 保留旧 service、schemas 与 `/search` 行为;不得通过修改旧接口配额来适配新前端。 +- [x] 核对管理写入已有失效回调,必要时仅接入已有 helper。手动 `scope=autocomplete` 应同时移除新两类键,`result:*` 不受影响。 +- [x] 在后端目录集中运行: + +```bash +python -m pytest tests/unit/test_pinyin_matcher.py tests/unit/test_autocomplete_service.py tests/unit/test_cache.py tests/integration/test_autocomplete.py tests/integration/test_vote_objects.py -q +``` + +**交付:** 旧前端可继续使用;新接口可独立返回正确 ID。没有数据库迁移和发布动作。 + +## Task 3:前端请求函数与 Vue 搜索状态 + +**Files in Touhou-Vote:** +- Create: `packages/shared/api/candidateSearch.ts` +- Create: `packages/vote/src/common/lib/useCandidateSearch.ts` +- Create: `packages/vote/src/common/lib/__tests__/candidateSearch.test.ts` +- Create: `packages/vote/src/common/lib/__tests__/useCandidateSearch.test.ts` + +**Interfaces:** +- Consumes: Task 2 的完整响应;URL 为 `${API_PREFIX}/api/v1/autocomplete/candidates/search`;当前 voteYear 显式传入请求。 +- Produces: `fetchCandidateSearch(baseUrl, category, query, voteYear): Promise`,类型定义见设计 §7。 +- Produces: `useCandidateSearch(category: CandidateCategory, query: Ref)`,返回 `matchedIds: Ref>`、`loading: Ref`、`error: Ref`。 + +- [x] 请求 helper 测试实际 JSON 请求/响应转换:整数 ID 转字符串在 Vue hook 内处理;HTTP 失败、回显类别/年度/query 不符或 ID 数组无效时抛出可展示错误。不重写全套 HTTP 验证框架。 +- [x] 用 Vue `effectScope`、`ref`、`nextTick` 调用真实 hook,并用可手动 resolve 的 fetch Promise 模拟返回。覆盖 query A 后输入 B、B 先返回、A 后返回,以及输入后清空两种核心场景;断言只保留当前输入结果。无需浏览器或 DOM 工程。 +- [x] 实现 hook:空查询不请求;非空查询清旧 ID 后请求;watch cleanup 使过期回调无效;成功设置 ID,当前失败设置 error。不要增加额外 debounce、重试、请求队列或历史查询缓存。 +- [x] 运行前端现有工具: + +```bash +./node_modules/.bin/tsx --test packages/vote/src/common/lib/__tests__/candidateSearch.test.ts packages/vote/src/common/lib/__tests__/useCandidateSearch.test.ts +``` + +**交付:** 可复用的前端异步搜索状态,尚不移除旧 Pinin。 + +## Task 4:三个入口切换、旧依赖清理与文档收尾 + +**Files in Touhou-Vote:** +- Modify: `packages/vote/src/vote-character/lib/characterList.ts` +- Modify: `packages/vote/src/vote-music/lib/musicList.ts` +- Modify: `packages/vote/src/vote-couple/components/CharacterSelect.vue` +- Modify: `packages/vote/src/vote-character/components/CharacterSelect.vue` +- Modify: `packages/vote/src/vote-music/components/MusicSelect.vue` +- Modify: `packages/vote/src/common/components/AutoComplete.vue`(仅补输入长度约束,保留节流) +- Modify: `packages/vote/src/common/lib/characterSearch.ts`(保留筛选与排序) +- Remove when no callers remain: `packages/vote/src/common/lib/pinin.ts`, `packages/vote/src/vote-music/lib/musicSearch.ts` +- Replace / remove obsolete cases: `packages/vote/src/vote-music/lib/__tests__/musicSearch.test.ts` +- Modify: `packages/vote/package.json`, `pnpm-lock.yaml`, `doc/ai-generated/vote-dev-notes.md`, `docs/CHANGELOG.md` + +**Backend docs:** `docs/api/voteable-api-contract.md`, `docs/CHANGELOG.md`,以及本设计/计划状态。后端 API 文档原自动补全示例与实际格式有漂移,修改时保留旧 suggestions 契约,单列新 ID 搜索端点,不将提案描述成已经上线。 + +**Interfaces:** +- Consumes: Task 3 hook 与已加载的候选列表。 +- Produces: 三个选择入口统一走后端匹配;已选项、CP 重复成员规则、作品/类别过滤和日期排序保持现状。 + +- [x] 角色与音乐 list 模块用命中 ID 对当前已有过滤列表求交,空 query 直接保留原列表;不取后端结果顺序替代日期排序。CP 本地 query 使用同一 hook,但保留允许选择重复成员的规则。 +- [x] 在三个选择框接入设计 §7 的等待和失败提示;公共搜索输入与 CP 输入增加 `maxlength=64`。非空 query 待返回时不显示旧关键词的列表。本命选择仍从现有已投项中选择,不改投票提交或草稿。 +- [x] Task 3 的真实 hook 测试断言成功响应产生 `Set`。源列表求交只保留现有简单 filter 与排序,不另写复制 filter 实现的测试。自查角色/音乐排除已选项与 CP 不排除的差别。 +- [x] 所有入口切换后搜索 Pinin 调用,移除已无调用的源文件、依赖和过时测试。后端已有拼音规则测试,前端不复制这些场景,也不新增测试证明旧文件被删。 +- [x] 同步前端开发说明、后端 API 契约、两端 changelog 和设计状态;记录后端先于前端提供接口、回滚先前端后后端,以及无数据库迁移。 +- [x] 运行 Task 3 两个前端测试文件和投票页构建: + +```bash +./node_modules/.bin/tsx --test packages/vote/src/common/lib/__tests__/candidateSearch.test.ts packages/vote/src/common/lib/__tests__/useCandidateSearch.test.ts +pnpm --filter @touhou-vote/vote build +``` + +- [x] 按完整改动做一次自查、`git diff --check` 和必要截图。没有 UI 交互授权时,不自动点击或输入;真实搜索体验由用户人工试用反馈。测试已过且无新问题后结束验证。 + +**交付:** 拼音词典和匹配计算不再随投票前端执行,旧后端接口仍兼容。产品验收前仍须实际部署授权与人工试用;本计划不包含这些操作的授权。 + +## 计划自查与交接 + +- 纯匹配器、搜索服务、DAO、API 与 Vue hook 的函数名和 ID 类型在设计与计划中保持一致。 +- 每一项首版匹配范围与缓存行为都有对应任务;数据持久化、结果页、CP 推荐和读音编辑没有被带入范围。 +- 新增测试集中于实际新行为,复用既有层次;没有新增端到端环境或性能工作流。 +- 用户已确认,四项任务在当前会话顺序执行;最终只做一次整体只读审阅。 + + +## 执行记录(2026-11-08) + +- 两端功能分支均为 `feat/pinyin-backend-search`;已核对远端基线,保留原有无关修改。实施阶段未执行 commit、push、部署或真实数据写入;用户随后授权按两阶段分别提交。 +- 后端:`python -m pytest tests/unit/test_pinyin_matcher.py tests/unit/test_autocomplete_service.py tests/unit/test_cache.py tests/integration/test_autocomplete.py tests/integration/test_vote_objects.py -q --tb=short` → 45 passed;有现存 asyncio / Strawberry 弃用提示。 +- 后端:`python -m flake8 src/ --max-line-length=88` → 通过。新增匹配器及 autocomplete 集成测试静态检查也通过;没有扩展到修复原 vote_objects 测试文件的已有样式问题。 +- 前端:`./node_modules/.bin/tsx --test packages/vote/src/common/lib/__tests__/candidateSearch.test.ts packages/vote/src/common/lib/__tests__/useCandidateSearch.test.ts` → 4 passed。 +- 前端:`pnpm --filter @touhou-vote/vote build` → 通过。构建仍提示现有 Browserslist 数据过期,本次不更新无关依赖。 +- 前端:对本次相关 TS/Vue 文件运行既有 ESLint;两端 `git diff --check` 通过。 +- 不运行浏览器自动交互;未验证线上数据、线上接口或部署后的完整链路。发布需另获授权,并遵循后端先、前端后的顺序。 + +- 最终整体只读审阅未发现 Critical / Important / Minor 问题;按已确认范围暂不引入并发回填恢复机制、不扩展搜索字段与 CP 组合推荐,不以本地验证替代线上体验验收。 +- 锁文件:`pnpm install --lockfile-only --frozen-lockfile --ignore-scripts --offline` 通过,Pinin 的 importer、package 与 snapshot 三处条目已移除,没有更新其他依赖。 + +### 工作区交接 + +- 沿用用户要求的两个现有功能分支,保留无关未提交改动;误归属时可用原始备份对照,不自动清理。 +- 前端原始现场备份位于 `/tmp/sunyunbo/thvote-frontend-pinyin-before-1meloex6/`,指针 `/tmp/sunyunbo/thvote-frontend-pinyin-backup`;stash 也保留。 +- codegen 冲突保留远端新 schema 地址与原本地退出码修复,changelog 保留唯一旧条目;如果需要复原,使用归档中的原文件核对。 +- 用户追加授权将当前迁移与后续接口收敛分开提交;不推送、合并或部署。原 vote_objects 测试文件已有样式问题未扩展修复,新增功能与生产静态检查已通过。 diff --git a/docs/superpowers/specs/2026-11-08-pinyin-candidate-search-design.md b/docs/superpowers/specs/2026-11-08-pinyin-candidate-search-design.md new file mode 100644 index 00000000..7d8b3da9 --- /dev/null +++ b/docs/superpowers/specs/2026-11-08-pinyin-candidate-search-design.md @@ -0,0 +1,235 @@ +# 拼音候选搜索后端化设计 + +> 状态:用户已确认,两个同名分支已本地实现;未发布或部署。2026-11-08。 +> 已确认方向:使用 pypinyin 提供读音,在项目内实现需要的匹配行为,不引入 JS 运行时。 +> 模块位置、接口、缓存和前端接入方案均已确认;下文保留设计依据。 + +## 1. 目标与当前实现 + +将投票页的角色、音乐和 CP 成员选择中的拼音匹配移到 Python 后端。后端统一处理公开候选的名称、别名、作品或专辑搜索,前端保留展示、筛选、排序和个人已选项处理。 + +代码基线:后端分支 `feat/pinyin-backend-search`,`265ab63`,已包含 `origin/main` 的 `6d8afc1`;前端同名分支指向 `ef028e0`,与调研时的 `origin/dev` 一致。实施前已归档并 stash 前端 `fix/codegen-exit-status` 未提交现场,切到同名功能分支,并保留尚未被上游包含的本地改动。 + +迁移前前端使用 `pinin@0.2.0`。角色和 CP 成员共用 `characterSearch.ts`;音乐由 `musicSearch.ts` 创建搜索器。迁移前后端 `apps/autocomplete` 只有名称 ILIKE 和 60 秒响应缓存,响应没有候选 ID;旧接口继续保留。结果页正则筛选不使用 Pinin,本次不改。源码和迁移目录没有现成拼音字段;本次不据此声称线上数据库已核验。 + +## 2. 路线与取舍 + +| 路线 | 优点 | 代价与结论 | +|---|---|---| +| pypinyin 加项目内匹配器 | 成熟词典、纯 Python;规则可审阅;可导出派生拼音 | 需要维护匹配算法和行为测试;用户已认可此方向 | +| PinInPy | 搜索接口接近现有 Pinin | 已发现 Python 3.13 导入错误和模糊规则差异,需要维护封装或原生补丁;暂不采用 | +| 后端 JS Pinin | 易沿用现有行为 | 增加运行时及进程边界;用户已排除 | + +拼音存储仍有两个可行选择: + +- **推荐首版保存在 Redis**:拼音是候选原文的派生语料,可随时重新生成;与搜索结果一起复用现有失效前缀,无数据库迁移。 +- **新增数据库派生字段**:适合后续需要管理读音、审阅或离线导出的场景,但需要 schema、写入同步和回填。当前尚无这类已确认需求,本轮不实施。 + +首版不创建拼音表、任务队列、锁、后台构建任务或跨进程索引同步机制。也不添加 Python 进程级候选缓存,避免额外失效状态。 + +## 3. 模块位置与依赖 + +放在唯一实际消费者 `src/apps/autocomplete/` 内,不提前抽到 `common`,也不新增顶级子系统。 + +| 文件 | 职责 | +|---|---| +| 新增 `src/apps/autocomplete/pinyin.py` | 纯 Python 的读音准备、21 条规则和文字匹配;不依赖 DAO、Redis、FastAPI | +| 新增 `src/apps/autocomplete/candidate_search.py` | 候选搜索用例:加载语料、调用匹配器、使用公共 Redis 缓存 | +| 修改 `src/apps/autocomplete/dao.py` | 增加当前年度候选的搜索字段读取;保留旧查询 | +| 修改 `src/apps/autocomplete/schemas.py` | 新接口的显式请求和响应 | +| 修改 `src/apps/autocomplete/router.py` | 新路由与依赖注入;旧 `/search` 保持原契约 | +| 复用 `src/common/cache.py` | JSON 缓存及前缀失效;不扩展成新的缓存框架 | + +依赖方向:router → candidate_search → DAO / pinyin / common.cache;pinyin 只依赖标准库和 `pypinyin==0.55.0`。原 `service.py` 继续服务旧自动补全接口,避免将两种响应混在一个流程中。 + +前端在 `packages/shared/api/candidateSearch.ts` 放无框架请求函数,在 `packages/vote/src/common/lib/useCandidateSearch.ts` 放 Vue 请求状态;三个选择入口复用这两处逻辑。 + +## 4. 匹配契约 + +### 4.1 搜索范围 + +| 类别 | 独立搜索文本 | +|---|---| +| character | `name`、每条 `aliases`、关联 `work.name` | +| music | `name`、每条 `aliases`、关联 `work.name`(当前主专辑) | + +任一文本匹配即命中同一候选,按 candidate ID 去重。不同文本之间不能拼接出一个命中。`name_jp` 和 `include` 当前未显式加入前端 Pinin 索引,首版不顺带扩展;假名、英文若已出现在上述字段中,支持原文匹配。 + +CP 页面复用 character 搜索来选择成员;不搜索已提交的 CP 组合,不实现 B-062。年度只影响候选关联,不修改 voteable ID 或 candidate ID。 + +### 4.2 输入与读音 + +- 查询和语料均采用 `lower()`;查询仅去首尾空白,内部空格、标点和数字保留,不作为正则解释。 +- 查询原始长度最多 64 个 Unicode 码点;超长返回 422,不截断后继续搜索。空白查询视为空查询。 +- 每个原文字位置保存原字和零到多个读音。使用 pypinyin 的逐字、无声调、多音字模式;不把每个字的所有读音预先做整词笛卡尔积。 +- 字典能提供读音的字使用这些读音,其他字符保持原文。大小写处理后的原字始终可以直接匹配。 +- 为接近现有 Pinin,声母/韵母拆分按其 standard 模式的字面规则:优先 `zh/ch/sh`,其余非 `a/e/i/o/u/v` 开头取首字母为声母;保留 `y/w` 输入。不能直接用 pypinyin 严格 `INITIALS` 输出代替该逻辑。 +- `ü` 在拼音表示中统一为 `v`。不在整段用户输入上做全局 `sh→s` 等替换。 +- 首版不支持声调数字、双拼、注音输入和通用拼写纠错。字典内容与旧 Pinin 不同可能造成少量读音差异,按下述样例和实际反馈核对,不承诺完全复刻旧引擎。 + +### 4.3 模糊规则 + +保留 `common/lib/pinin.ts` 的 7 条双向关系及 14 条单向关系: + +```text +双向:sh|s, ch|c, zh|z, u|v, ang|an, eng|en, ing|in +单向:an>a, ang>a, ai>a, ao>a, ou>o, ong>o, en>e, eng>e, + ei>e, er>e, er>r, ui>u, un>u, vn>v +``` + +规则作用于单个读音的声母或韵母;双向生成两个方向,单向只允许原音素到配置的替代形式。每条规则对原音素做一次首处替换,不递归应用,不求规则的传递闭包。保留原音素。这样不会因一次规则替换又触发另一条规则而扩大匹配范围。 + +### 4.4 匹配过程 + +按原文位置和查询位置推进,可从任意原文位置开始。每个字可消费原字、完整读音或完整声母;查询结束时允许停在某个读音音素的前缀处。声母和韵母分别应用规则后组成读音。字与字之间连续,不跳过任意原文字,不跨搜索字段。 + +使用记忆化的查询位置匹配或等价的二维动态规划,避免反复探索相同位置;这是混输匹配的核心算法,不引入业务请求状态机。先逐条遍历候选,不构建搜索树或倒排索引。准备好的语料在同一次搜索和 Redis 缓存中复用。 + +核心接口: + +```python +# pinyin.py:TextUnit 是原字与 (声母, 韵母) 候选的不可变结构。 +PreparedText = tuple[TextUnit, ...] +def prepare_text(text: str) -> PreparedText: ... +def contains(text: PreparedText, query: str) -> bool: ... +``` + +必须保留的独立预期值: + +| 原文 | 查询 | 结果 | +|---|---|---| +| 雾雨魔理沙 | `mls`、`wuyumolisha`、`mo理sha` | 命中 | +| 博丽灵梦 | `灵m`、`博l灵m` | 命中 | +| 十六夜咲夜 | `siliuye` | 命中 | +| 二小姐 | `rxiaojie` | 命中 | +| 路米 | `lvmi` | 命中,检查 u→v 方向 | +| 绿米 | `lumi` | 命中,检查 v→u 方向 | +| 灵米 | `limi` | 不命中,不能将 ing 任意缩成 i | +| 小米 | `ximi` | 不命中,不能将 iao 任意缩成 i | +| Bad Apple!! | `bad apple` | 命中 | +| U.N.オーエンは彼女なのか? | `オーエン` | 命中原文 | +| 魔甲理沙 | `mls` | 不命中,不跳过甲 | + +多音字、规则方向、末尾未输完和原文分支的独立覆盖放在同一层测试,不在前后端重复整套算法场景。旧 Pinin 只用于一次性对照调查,不能成为永久测试依赖,也不能把新实现自己的输出当预期值。 + +## 5. 新接口与数据访问 + +推荐增加 `POST /api/v1/autocomplete/candidates/search`,不改变现有 `POST /api/v1/autocomplete/search` 的请求、响应、配额和 ILIKE 行为。 + +```json +请求:{"category":"character","query":"mls","vote_year":12} +响应:{"category":"character","query":"mls","vote_year":12,"candidate_ids":[123]} +``` + +示例 ID 123 仅表示响应形状,不代表已核验的云端候选。 + +- `category` 只能为 `character` 或 `music`;`query` 必填字符串、允许空串、最多 64 码点;`vote_year` 可省略,省略时使用 `settings.vote_year`,显式给出时须为正整数。 +- 响应回显规范化 query 和实际 vote_year。candidate IDs 为整数,稳定升序、无重复。 +- 返回完整命中集合,不设默认 10 条截断,不新增分页。空查询返回该年度该类别全部 candidate IDs;未知年度返回空集合。 +- 不带用户已选项、用户身份、筛选项或排序参数。前端将 ID 转为字符串,与已加载对象求交集后继续已有筛选和排序。 +- 新接口与旧公开候选接口一样公开读取,不改变现有鉴权和提交规则。 + +数据层新增: + +```python +# dao.py;旧 DAO 的 vote_year 构造参数和旧方法保留。 +async def load_search_documents( + self, category: Literal["character", "music"], vote_year: int +) -> list[tuple[int, tuple[str, ...]]]: ... +``` + +DAO 经 candidate → voteable → work JOIN 返回搜索原文,直接使用数据库 aliases;不查询选票或静态白名单。它与现有候选列表查询用途不同,只取候选 ID 和搜索字段;不为这一次查询重构投票对象模块。 + +## 6. Redis 与派生拼音存储 + +`CandidateSearchService(dao, redis, default_year)` 提供 `async search(request: CandidateSearchRequest) -> CandidateSearchResponse`。规范化查询后,处理流程如下: + +```mermaid +flowchart LR + Q[规范化 query 与年度] --> R{结果缓存命中} + R -->|是| O[返回完整候选 ID 集合] + R -->|否| C{拼音语料缓存命中} + C -->|是| M[纯 Python 匹配] + C -->|否| D[DAO 读取原文] + D --> P[pypinyin 准备语料并缓存] + P --> M + M --> W[缓存结果 60 秒] + W --> O +``` + +使用已有 `autocomplete:` 前缀,内部版本初始为 `v1`: + +| 内容 | key | TTL | +|---|---|---| +| 原字及按位置排列的声母/韵母候选 | `autocomplete:pinyin:v1:{year}:{category}:corpus` | 60 秒 | +| 完整命中 ID 列表,包括空结果 | `autocomplete:pinyin:v1:{year}:{category}:q:{sha256(query)}` | 60 秒 | + +语料以 JSON 列表存储 candidate ID、独立文本和每个位置的原字/读音二元组。只保存当前年度该类别的搜索字段,不保存图片、音频、票数或个人已选项。按位置保留多音候选,不展开完整读音组合;序列化和恢复逻辑只留在 candidate_search.py。空查询直接由语料取全部 ID,不另外写 query 结果键。 + +规则或内部语料格式变动时将内部版本升为 `v2`;这只是代码常量,不新增数据库版本字段。依赖版本固定为 pypinyin 0.55.0,升级时核对读音差异并同步缓存版本。 + +### 失效与故障行为 + +- 复用管理写入后的 `_clear_vote_objects_cache()`:其已有 `autocomplete:` 前缀清理会同时移除语料和结果。实施时核对候选变更、导入、作品修改、别名修改是否均接入该调用。 +- 管理端现有 `scope=autocomplete` 手动刷新覆盖新缓存;`scope=vote_objects` 仍只清自己的 scope,不能声称它单独也会清拼音结果。 +- 复用 `cache_get_json` / `cache_set_json`。Redis 不可用时直接从 DAO 准备和匹配,跳过缓存写入;不伪装成零命中。数据库失败沿用项目错误响应,不将错误写成成功空结果。 +- 不创建分布式锁、等待队列、单飞协调或自动恢复任务。并发 miss 可以各自计算;管理变更与读写交错的短暂陈旧允许由 TTL 或手动刷新处理。 +- 没有触发正常失效时,两层缓存可能接续陈旧,保守按最多约 120 秒理解,不能宣称数据总在 60 秒内更新;频繁改名或严格即时更新需求出现后再单独讨论。 +- 现有 `result:*` 是计票产物,与这次缓存无关,不加入任何清理操作。 + +## 7. 前端接入 + +前端请求使用 `${API_PREFIX}/api/v1/autocomplete/candidates/search`,即 `/v12-be/api/v1/autocomplete/candidates/search`。已核对 Vite 与 `Dockerfile.vote.template` 的通用 `/v12-be/` 转发:均剥离该前缀后到达后端 `/api/v1/...`。因此无需增加代理路径或改变部署拓扑。 + +新增共享函数: + +```typescript +type CandidateCategory = 'character' | 'music' +type CandidateSearchResult = { + category: CandidateCategory + query: string + vote_year: number + candidate_ids: number[] +} +function fetchCandidateSearch( + baseUrl: string, + category: CandidateCategory, + query: string, + voteYear: number, +): Promise +``` + +`baseUrl` 在此指完整的搜索端点 URL;helper 不再追加路径。请求沿用已有同源 API 的 `credentials: 'include'`,发送 JSON POST。 + +Vue 层统一 `useCandidateSearch(category, query: Ref)`,使用当前 `voteYear` 和 API_PREFIX。返回 `matchedIds: Ref>`、`loading: Ref`、`error: Ref`。不缓存历史 query 结果,不持久化浏览器搜索缓存。 + +- 保留输入端现有 100ms 节流,不叠加另一套 debounce。公共输入框与 CP 输入框增加 `maxlength=64`;后端仍独立校验码点长度。空查询立即展示本地已有列表,不发搜索请求。 +- 角色/音乐列表和 CP 选择框以公共命中 ID 集合过滤当前列表;已选项目的排除、类别/作品筛选、日期排序及 CP 允许重复成员等规则不变。 +- 非空查询等待期间清除上一关键词的命中列表,显示“正在搜索…”;失败显示“搜索失败,请修改关键词重试”,清空关键词可继续浏览全部列表。不自动重试,不回退第二套拼音引擎。 +- 使用 Vue watch 的 cleanup 忽略过期请求返回,确保快速输入或清空后旧结果不会盖掉当前结果;不增加请求队列、版本恢复或持久化状态。 +- 请求 helper 检查 HTTP 状态、category/year/query 回显及 ID 数组,再更新 Vue 状态。这是新异步搜索的核心响应契约,不扩展到无关请求。 +- 三个选择框都显示上述等待/失败状态。本命从已投选项中选择的现有流程不改。 +- 候选对象仍由已有 vote-objects 数据源加载;移走 Pinin 词典与计算,不代表免除列表展示和导图所需的对象数据下载。 + +完成三处接入后才移除 `pinin` 依赖和 `pinin.ts`、`musicSearch.ts`。`characterSearch.ts` 中的排序、作品筛选函数保留;仅删除已无调用的 Pinin 构建与 searchAndSort。现有 musicSearch 测试按新职责替换或删除,不能保留只断言已删除实现的测试。 + +## 8. 验证、兼容和回滚 + +实施分为三个交付段:纯匹配器;后端公开搜索与缓存;前端三个入口替换。只有整个链路完成后才能声称迁移完成。 + +- 核心匹配在一个 Python 单测文件中覆盖,以明确正反例锁定原文、简拼、混输、规则方向和多音字;不为同一算法在前端再复制一套。 +- 后端集成层使用现有 SQLite/fakeredis 测试条件,覆盖年度和类别、别名/作品独立匹配、完整集合与候选 ID、缓存命中/空结果/失效/Redis 不可用。 +- 前端用现有 node:test 与 tsx 工具覆盖真实请求 helper、ID 映射、错误和过期返回;不建立新的端到端测试工程。UI 按项目约定最多截图,不自动点击或填写表单。 +- 不以小样本全部相同证明完全兼容;若关键名字或常见输入与预期不符,先明确字典差异还是匹配错误,再调整该用例或将产品差异交用户确认。 +- 后端先提供加法接口,旧前端照常工作;前端切换后再清理 Pinin 依赖。前端上线依赖新接口可用,不以静默本地降级掩盖后端未更新。 +- 回滚先回前端旧版本,再按需回后端;数据库与投票记录无需回滚。新 Redis 键可自然过期或用原 autocomplete scope 清理。无数据迁移、真实回填或重新计票。 + +## 9. 实施状态与剩余验证 + +2026-11-08 用户确认了模块边界、新 ID 接口、两层 Redis 缓存及前端接入方案。纯匹配器、DAO、API、缓存、三个选择入口和依赖替换均已本地实现。 + +已验证关键匹配正反例、年度/字段隔离、缓存与失效、Redis 故障直算、HTTP 输入输出及前端请求竞态。最终命令与结果见 [实施计划](../plans/2026-11-08-pinyin-candidate-search.md) 执行记录。 + +未进行线上数据查询、真实链路部署或浏览器交互验收;本次不包含这些授权。两端保留本地未提交改动,旧 CP 组合自动补全问题不在本次范围。 + +参考:[pypinyin 用法](https://pypinyin.readthedocs.io/zh-cn/master/usage.html)、前端 `ef028e0` 的 `pinin.ts` / `characterSearch.ts` / `musicSearch.ts`。官方需求中的角色和音乐拼音搜索见 `docs/requirements/VoileLabs-人气投票项目-需求文档-投票系统.md` 的角色选择框与曲目选择框。 diff --git a/pyproject.toml b/pyproject.toml index 441ccf63..4a57ae2d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -38,6 +38,7 @@ dependencies = [ "lxml>=5.0.0", "aiohttp>=3.9", "lark>=1.1.0", + "pypinyin==0.55.0", ] [project.optional-dependencies] diff --git a/src/apps/autocomplete/candidate_search.py b/src/apps/autocomplete/candidate_search.py new file mode 100644 index 00000000..6606fa31 --- /dev/null +++ b/src/apps/autocomplete/candidate_search.py @@ -0,0 +1,69 @@ +"""Public candidate matching with regenerable Redis caches.""" + +from hashlib import sha256 + +import redis.asyncio as aioredis + +from src.apps.autocomplete.dao import AutocompleteDAO +from src.apps.autocomplete.pinyin import PreparedText, TextUnit, contains, prepare_text +from src.apps.autocomplete.schemas import ( + CandidateCategory, + CandidateSearchRequest, + CandidateSearchResponse, +) +from src.common.cache import cache_get_json, cache_set_json + +CACHE_TTL = 60 +CACHE_PREFIX = "autocomplete:pinyin:v1" +Corpus = list[tuple[int, tuple[PreparedText, ...]]] + + +class CandidateSearchService: + def __init__( + self, dao: AutocompleteDAO, redis: aioredis.Redis, default_year: int + ) -> None: + self.dao = dao + self.redis = redis + self.default_year = default_year + + async def _corpus(self, category: CandidateCategory, year: int) -> Corpus: + key = f"{CACHE_PREFIX}:{year}:{category}:corpus" + cached = await cache_get_json(self.redis, key) + if cached is not None: + return [ + (cid, tuple( + tuple(TextUnit(literal, tuple(tuple(r) for r in readings)) + for literal, readings in text) + for text in texts + )) + for cid, texts in cached + ] + documents = await self.dao.load_search_documents(category, year) + corpus = [ + (cid, tuple(prepare_text(text) for text in texts)) + for cid, texts in documents + ] + serialized = [ + [cid, [[[unit.literal, unit.readings] for unit in text] for text in texts]] + for cid, texts in corpus + ] + await cache_set_json(self.redis, key, serialized, CACHE_TTL) + return corpus + + async def search(self, request: CandidateSearchRequest) -> CandidateSearchResponse: + query = request.query.strip().lower() + year = request.vote_year if request.vote_year is not None else self.default_year + fingerprint = sha256(query.encode("utf-8")).hexdigest() + key = f"{CACHE_PREFIX}:{year}:{request.category}:q:{fingerprint}" + ids = await cache_get_json(self.redis, key) if query else None + if ids is None: + corpus = await self._corpus(request.category, year) + ids = sorted({ + cid for cid, texts in corpus + if not query or any(contains(text, query) for text in texts) + }) + if query: + await cache_set_json(self.redis, key, ids, CACHE_TTL) + return CandidateSearchResponse( + category=request.category, query=query, vote_year=year, candidate_ids=ids, + ) diff --git a/src/apps/autocomplete/dao.py b/src/apps/autocomplete/dao.py index f2b61ade..61fd4c27 100644 --- a/src/apps/autocomplete/dao.py +++ b/src/apps/autocomplete/dao.py @@ -1,5 +1,7 @@ """Autocomplete data access objects.""" +from typing import Literal + from sqlalchemy import or_, select from sqlalchemy.ext.asyncio import AsyncSession @@ -13,6 +15,29 @@ def __init__(self, session: AsyncSession, vote_year: int): self.session = session self.vote_year = vote_year + async def load_search_documents( + self, category: Literal["character", "music"], vote_year: int + ) -> list[tuple[int, tuple[str, ...]]]: + candidate, voteable = { + "character": (CandidateCharacter, VoteableCharacter), + "music": (CandidateMusic, VoteableMusic), + }[category] + stmt = ( + select(candidate.id, voteable.name, voteable.aliases, Work.name) + .select_from(candidate) + .join(voteable, candidate.voteable_id == voteable.id) + .outerjoin(Work, voteable.work_id == Work.id) + .where(candidate.vote_year == vote_year) + .order_by(candidate.id) + ) + rows = (await self.session.execute(stmt)).all() + return [ + (cid, tuple(dict.fromkeys( + term for term in (name, *(aliases or []), work) if term + ))) + for cid, name, aliases, work in rows + ] + async def search_characters(self, query: str, limit: int = 10) -> list[dict]: stmt = ( select( diff --git a/src/apps/autocomplete/pinyin.py b/src/apps/autocomplete/pinyin.py new file mode 100644 index 00000000..3218b401 --- /dev/null +++ b/src/apps/autocomplete/pinyin.py @@ -0,0 +1,87 @@ +"""Literal, abbreviated and mixed pinyin matching for candidate selectors.""" + +from dataclasses import dataclass +from functools import lru_cache +from itertools import product + +from pypinyin import Style, pinyin + +_BIDIRECTIONAL = ( + ("sh", "s"), ("ch", "c"), ("zh", "z"), ("u", "v"), + ("ang", "an"), ("eng", "en"), ("ing", "in"), +) +_ONE_WAY = ( + ("an", "a"), ("ang", "a"), ("ai", "a"), ("ao", "a"), + ("ou", "o"), ("ong", "o"), ("en", "e"), ("eng", "e"), + ("ei", "e"), ("er", "e"), ("er", "r"), ("ui", "u"), + ("un", "u"), ("vn", "v"), +) +_RULES = _ONE_WAY + _BIDIRECTIONAL + tuple((b, a) for a, b in _BIDIRECTIONAL) + + +@dataclass(frozen=True) +class TextUnit: + literal: str + readings: tuple[tuple[str, str], ...] + + +PreparedText = tuple[TextUnit, ...] + + +def prepare_text(text: str) -> PreparedText: + units = [] + for char in text.lower(): + readings = [] + for reading in pinyin(char, style=Style.NORMAL, heteronym=True)[0]: + if reading == char: + continue + reading = reading.replace("ü", "v") + split = 0 + if reading[0] not in "aeiouv": + split = 2 if reading.startswith(("zh", "ch", "sh")) else 1 + readings.append((reading[:split], reading[split:])) + units.append(TextUnit(char, tuple(dict.fromkeys(readings)))) + return tuple(units) + + +def _variants(phoneme: str) -> set[str]: + # Each rule acts once on the original phoneme, never on another rule's output. + return {phoneme} | { + phoneme.replace(source, target, 1) + for source, target in _RULES if source in phoneme + } + + +def _forms(unit: TextUnit) -> set[str]: + forms = {unit.literal} + for initial, final in unit.readings: + initials, finals = _variants(initial), _variants(final) + forms.update(a + b for a, b in product(initials, finals)) + if initial: + forms.update(initials) + return forms + + +def contains(text: PreparedText, query: str) -> bool: + """Match contiguous source characters; only the query's end may be partial.""" + if not query: + return True + forms = tuple(_forms(unit) for unit in text) + + @lru_cache(maxsize=None) + def match(position: int, offset: int) -> bool: + if offset == len(query): + return True + if position == len(text): + return False + remaining = query[offset:] + for form in forms[position]: + if form.startswith(remaining): + return True + if query.startswith(form, offset) and match( + position + 1, offset + len(form) + ): + return True + return False + + return any(match(start, 0) for start in range(len(text))) diff --git a/src/apps/autocomplete/router.py b/src/apps/autocomplete/router.py index ff80e344..955b20a9 100644 --- a/src/apps/autocomplete/router.py +++ b/src/apps/autocomplete/router.py @@ -6,8 +6,14 @@ from fastapi import APIRouter, Depends from sqlalchemy.ext.asyncio import AsyncSession +from src.apps.autocomplete.candidate_search import CandidateSearchService from src.apps.autocomplete.dao import AutocompleteDAO -from src.apps.autocomplete.schemas import AutocompleteRequest, AutocompleteResponse +from src.apps.autocomplete.schemas import ( + AutocompleteRequest, + AutocompleteResponse, + CandidateSearchRequest, + CandidateSearchResponse, +) from src.apps.autocomplete.service import AutocompleteService from src.common.cache import cache_get_json, cache_set_json from src.common.config import Settings, get_settings @@ -28,6 +34,24 @@ async def get_autocomplete_service( return AutocompleteService(dao) +async def get_candidate_search_service( + session: AsyncSession = Depends(get_db_session), + settings: Settings = Depends(get_settings), + redis: aioredis.Redis = Depends(get_redis), +) -> CandidateSearchService: + return CandidateSearchService( + AutocompleteDAO(session, settings.vote_year), redis, settings.vote_year + ) + + +@router.post("/candidates/search", response_model=CandidateSearchResponse) +async def search_candidates( + request: CandidateSearchRequest, + service: CandidateSearchService = Depends(get_candidate_search_service), +) -> CandidateSearchResponse: + return await service.search(request) + + @router.post("/search", response_model=AutocompleteResponse) async def search_autocomplete( request: AutocompleteRequest, diff --git a/src/apps/autocomplete/schemas.py b/src/apps/autocomplete/schemas.py index 80c51d80..d5a95eb4 100644 --- a/src/apps/autocomplete/schemas.py +++ b/src/apps/autocomplete/schemas.py @@ -1,8 +1,8 @@ """Autocomplete schemas for request/response validation.""" -from typing import Optional +from typing import Literal, Optional -from pydantic import BaseModel +from pydantic import BaseModel, Field class AutocompleteRequest(BaseModel): @@ -24,3 +24,19 @@ class AutocompleteResponse(BaseModel): """Response schema for autocomplete.""" suggestions: list[AutocompleteSuggestion] + + +CandidateCategory = Literal["character", "music"] + + +class CandidateSearchRequest(BaseModel): + category: CandidateCategory + query: str = Field(max_length=64) + vote_year: int | None = Field(default=None, gt=0) + + +class CandidateSearchResponse(BaseModel): + category: CandidateCategory + query: str + vote_year: int + candidate_ids: list[int] diff --git a/tests/integration/test_autocomplete.py b/tests/integration/test_autocomplete.py index 7dcf200b..b3e6c573 100644 --- a/tests/integration/test_autocomplete.py +++ b/tests/integration/test_autocomplete.py @@ -143,3 +143,110 @@ async def test_wrong_year_returns_nothing(session): dao = AutocompleteDAO(session, vote_year=9999) results = await dao.search_characters("灵梦", 10) assert results == [] + + +@pytest.mark.asyncio +async def test_candidate_search_fields_year_and_cache(session, patch_redis): + from src.apps.admin.router import _clear_vote_objects_cache + from src.apps.autocomplete.candidate_search import CandidateSearchService + from src.apps.autocomplete.schemas import CandidateSearchRequest + from src.db_model.candidate import CandidateCharacter + from src.db_model.voteable import VoteableCharacter + + char = await session.get(VoteableCharacter, 101) + char.aliases = ["黑白", "魔理沙"] + session.add(CandidateCharacter(vote_year=2027, voteable_id=101)) + await session.commit() + service = CandidateSearchService( + AutocompleteDAO(session, VOTE_YEAR), patch_redis, VOTE_YEAR + ) + + async def search(query, year=VOTE_YEAR, category="character"): + return (await service.search(CandidateSearchRequest( + category=category, query=query, vote_year=year, + ))).candidate_ids + + current = (await session.execute(text( + "SELECT id FROM candidate_character WHERE vote_year=2026 AND voteable_id=101" + ))).scalar_one() + other = (await session.execute(text( + "SELECT id FROM candidate_character WHERE vote_year=2027 AND voteable_id=101" + ))).scalar_one() + assert await search(" MLS ") == [current] + keys = [key async for key in patch_redis.scan_iter(match="autocomplete:pinyin:*")] + assert len(keys) == 2 + for key in keys: + assert 0 < await patch_redis.ttl(key) <= 60 + assert await search("黑白") == [current] + assert await search("mls", 2027) == [other] + assert await search("mls", category="music") == [] + assert len(await search("hongmoxiang")) == 3 + assert await search("黑白东方") == [] # Separate fields never concatenate. + assert await search("", 9999) == [] + assert len(await search("")) == 3 + + # Both positive and empty results, and the prepared corpus, remain reusable. + assert await search("新别名") == [] + char.aliases = ["新别名"] + await session.commit() + assert await search("黑白") == [current] + assert await search("新别名") == [] + assert await search("别名") == [] # New query still uses the cached corpus. + await patch_redis.set("result:keep", "unchanged") + await _clear_vote_objects_cache(patch_redis) + assert await search("黑白") == [] + assert await search("新别名") == [current] + assert await patch_redis.get("result:keep") == "unchanged" + + +@pytest.mark.asyncio +async def test_candidate_search_all_matches_and_redis_failure(session): + from src.apps.autocomplete.candidate_search import CandidateSearchService + from src.apps.autocomplete.schemas import CandidateSearchRequest + from src.db_model.candidate import CandidateCharacter + from src.db_model.voteable import VoteableCharacter + + class UnavailableRedis: + async def get(self, key): + raise ConnectionError("test unavailable") + + async def set(self, *args, **kwargs): + raise ConnectionError("test unavailable") + + for index in range(11): + char = VoteableCharacter(name=f"测试对象{index}", aliases=["共同别名"]) + session.add(char) + await session.flush() + session.add(CandidateCharacter(vote_year=2028, voteable_id=char.id)) + await session.commit() + expected = list((await session.execute(text( + "SELECT id FROM candidate_character WHERE vote_year=2028 ORDER BY id" + ))).scalars()) + service = CandidateSearchService( + AutocompleteDAO(session, 2028), UnavailableRedis(), 2028 + ) + result = await service.search( + CandidateSearchRequest(category="character", query="共同") + ) + assert result.vote_year == 2028 + assert result.candidate_ids == expected + + +@pytest.mark.asyncio +async def test_candidate_search_does_not_cache_database_errors( + session, patch_redis, monkeypatch +): + from src.apps.autocomplete.candidate_search import CandidateSearchService + from src.apps.autocomplete.schemas import CandidateSearchRequest + + dao = AutocompleteDAO(session, VOTE_YEAR) + + async def fail(*args): + raise RuntimeError("test database failure") + + monkeypatch.setattr(dao, "load_search_documents", fail) + with pytest.raises(RuntimeError, match="test database failure"): + await CandidateSearchService(dao, patch_redis, VOTE_YEAR).search( + CandidateSearchRequest(category="character", query="mls") + ) + assert await patch_redis.dbsize() == 0 diff --git a/tests/integration/test_vote_objects.py b/tests/integration/test_vote_objects.py index 5d363bb6..3b10301b 100644 --- a/tests/integration/test_vote_objects.py +++ b/tests/integration/test_vote_objects.py @@ -91,6 +91,44 @@ async def _seed_work_and_voteable(session): await session.commit() +@pytest.mark.asyncio +async def test_candidate_search_http_contract(app): + from src.common.config import get_settings + + a, maker = app + settings = get_settings().model_copy(update={"vote_year": 2026}) + a.dependency_overrides[get_settings] = lambda: settings + async with maker() as session: + await _seed_work_and_voteable(session) + await session.execute(text( + "INSERT INTO candidate_character (vote_year, voteable_id) VALUES (2026, 11)" + )) + await session.commit() + cid = (await session.execute(text( + "SELECT id FROM candidate_character WHERE vote_year=2026 AND voteable_id=11" + ))).scalar_one() + url = "/api/v1/autocomplete/candidates/search" + async with AsyncClient(transport=ASGITransport(app=a), base_url="http://test") as client: + result = await client.post(url, json={"category": "character", "query": " MLS "}) + assert result.status_code == 200 + assert result.json() == { + "category": "character", + "query": "mls", + "vote_year": 2026, + "candidate_ids": [cid], + } + other = await client.post(url, json={ + "category": "character", "query": "mls", "vote_year": 2027, + }) + assert other.json()["vote_year"] == 2027 + assert other.json()["candidate_ids"] == [] + for fields in ({"category": "cp"}, {"query": "x" * 65}, {"vote_year": 0}): + response = await client.post(url, json={ + "category": "character", "query": "x", **fields, + }) + assert response.status_code == 422 + + @pytest.mark.asyncio async def test_characters_grouped_by_work(app): a, maker = app diff --git a/tests/unit/test_pinyin_matcher.py b/tests/unit/test_pinyin_matcher.py new file mode 100644 index 00000000..d899e384 --- /dev/null +++ b/tests/unit/test_pinyin_matcher.py @@ -0,0 +1,33 @@ +"""Observable matching rules used by the voting selectors.""" + +import pytest + +from src.apps.autocomplete.pinyin import contains, prepare_text + + +@pytest.mark.parametrize(("text", "query", "expected"), [ + ("雾雨魔理沙", "mls", True), + ("雾雨魔理沙", "wuyumolisha", True), + ("雾雨魔理沙", "mo理sha", True), + ("博丽灵梦", "灵m", True), + ("博丽灵梦", "博l灵m", True), + ("十六夜咲夜", "siliuye", True), + ("二小姐", "rxiaojie", True), + ("路米", "lvmi", True), + ("绿米", "lumi", True), + ("啊米", "anmi", False), + ("灵米", "limi", False), + ("小米", "ximi", False), + ("魔甲理沙", "mls", False), + ("重行", "chongxing", True), + ("重行", "zhonghang", True), + ("雾雨魔理沙", "molish", True), + ("Bad Apple!!", "bad apple", True), + ("U.N.オーエンは彼女なのか?", "オーエン", True), + ("Bad Apple!!", ".*", False), + ("[demo]", "[", True), + ("", "m", False), + ("灵梦", "", True), +]) +def test_contains(text, query, expected): + assert contains(prepare_text(text), query) is expected From 5285a0e0deae5dedf03549eb2a3c28215f26cba2 Mon Sep 17 00:00:00 2001 From: Renko6626 <2300011496@stu.pku.edu.cn> Date: Sun, 8 Nov 2026 01:25:56 +0800 Subject: [PATCH 2/4] refactor: consolidate autocomplete into candidate search endpoint --- docs/BACKLOG-archive.md | 1 + docs/BACKLOG.md | 3 +- docs/CHANGELOG.md | 8 ++ docs/README.md | 1 + docs/api/voteable-api-contract.md | 18 +--- ...11-08-autocomplete-search-consolidation.md | 51 ++++++++++ .../2026-11-08-pinyin-candidate-search.md | 2 +- ...26-11-08-pinyin-candidate-search-design.md | 30 +++--- src/apps/autocomplete/candidate_search.py | 69 ------------- src/apps/autocomplete/dao.py | 69 +------------ src/apps/autocomplete/router.py | 42 +------- src/apps/autocomplete/schemas.py | 25 +---- src/apps/autocomplete/service.py | 96 ++++++++++++------- tests/integration/test_autocomplete.py | 74 ++------------ tests/integration/test_vote_objects.py | 2 +- tests/unit/test_autocomplete_service.py | 57 ----------- 16 files changed, 159 insertions(+), 389 deletions(-) create mode 100644 docs/superpowers/plans/2026-11-08-autocomplete-search-consolidation.md delete mode 100644 src/apps/autocomplete/candidate_search.py delete mode 100644 tests/unit/test_autocomplete_service.py diff --git a/docs/BACKLOG-archive.md b/docs/BACKLOG-archive.md index 26776727..b63aef07 100644 --- a/docs/BACKLOG-archive.md +++ b/docs/BACKLOG-archive.md @@ -5,6 +5,7 @@ | 编号 | 主题 | 严重度/状态 | 可并行做? | 源文档 | |---|---|---|---|---| +| **B-062** | `AutocompleteDAO.search_cps()` 恒返回 `[]`(`src/apps/autocomplete/dao.py:78`)——CP 自动补全端点 `POST /autocomplete/search` 的 CP 分类**永远为空**。角色/音乐走 `candidate_character`/`candidate_music` 表 ILIKE 已实现,CP 无现成候选表,需从已提交的 `cp.cp_list` JSON 抽唯一 CP 名做模糊匹配(**2026-08-31 文档整理时从 `REFACTOR_TODO.md` 迁入,代码侧已复核仍成立**) | ✅ 已废弃(2026-11-08,本地未部署):旧建议链路及空 CP 方法随统一候选搜索移除;CP 成员使用 character 搜索,未新增 CP 组合推荐 | — | `src/apps/autocomplete/dao.py:77-78`;原始记录见 [archive/2026-05-30-refactor-todo](./archive/2026-05-30-refactor-todo.md) §六 | | **B-008** | ~~MongoDB → PostgreSQL 历史用户数据回填脚本~~ | ✅ 已废弃 (2026-09-06):上线即空库,不再从旧 Mongo 导入用户;`map_voter`/voters 同步项随身份模型归一化删除,见 CHANGELOG 2026-09-06 | — | [medium-priority-backlog-design](./superpowers/specs/2026-05-16-medium-priority-backlog-design.md) | | **B-011** | ~~SSO 落地后移除 `User.at_least_one_identifier` CHECK 约束(约束仍在 `src/db_model/user.py:49` + migration 0001)~~ | ✅ 已完成 (2026-09-06):CHECK 约束随 migration 0018(`user_identity`)一并删除 | — | [design §九 F7](./superpowers/specs/2026-04-27-user-auth-design.md) | | **B-064** | ~~迁移 0018 回填把「管理员封禁」当成「自助注销」,`WHERE removed = FALSE` 把封禁账号一并排除,其邮箱/手机被释放、解封后无身份可登录~~ | ✅ 已完成 (2026-09-12):**并非 GDPR 与封禁二选一** —— 旧 `remove_voter` 把 email/phone/password 全部置空而 `ban_user` 一个不动,两者可区分。回填范围改用 `_BACKFILL_SCOPE`(`removed = FALSE OR email IS NOT NULL OR phone_number IS NOT NULL`),封禁账号完整回填、自助注销账号一条不回填(含旧实现漏清的 qq/thbwiki)。真 PG 四形态验证通过 | — | [design §七](./superpowers/specs/2026-09-06-user-identity-model-design.md) | diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md index 6e379f5d..408fd892 100644 --- a/docs/BACKLOG.md +++ b/docs/BACKLOG.md @@ -1,7 +1,7 @@ # 后续开发 BACKLOG(单一仪表盘) > 创建日期:2026-04-27 -> 最后更新:2026-08-31(文档大扫除:新增 B-062/B-063——从已归档的 `REFACTOR_TODO.md` 迁入两条经代码复核仍成立的缺口;docs 树归档重整,详见 CHANGELOG 2026-08-31)。此前:2026-08-13 第二轮(大扫除:31 条已完成/废弃项迁至 [BACKLOG-archive.md](./BACKLOG-archive.md);B-028/B-054/B-042②/B-043尾项标 ⏸ 等外部——用户确认只能等;前端队列确认我方负责) +> 最后更新:2026-11-08(B-062 随旧建议链路移除,归档为废弃项);此前:2026-08-31(文档大扫除:新增 B-062/B-063——从已归档的 `REFACTOR_TODO.md` 迁入两条经代码复核仍成立的缺口;docs 树归档重整,详见 CHANGELOG 2026-08-31)。此前:2026-08-13 第二轮(大扫除:31 条已完成/废弃项迁至 [BACKLOG-archive.md](./BACKLOG-archive.md);B-028/B-054/B-042②/B-043尾项标 ⏸ 等外部——用户确认只能等;前端队列确认我方负责) 把散落在 5 份文档里的 follow-up 收拢到这里。**这是仪表盘,不是真理来源**——每项的上下文还在原文档里,本表只给一行摘要 + 跳转。 @@ -43,7 +43,6 @@ | **B-045** | 反机器人时序特征:提交耗时 `fill_duration_ms`(客户端挂载→提交,新列 migration 0012)+ 服务端 `attempt` 改票计数(复用死列,首次=1/改票≥2)。只取证不拦截;"耗时短=可疑"只对首次生效,改票豁免(根治改票假阳性) | 🟡 **后端已合并已部署** (0012 已在测试库,2026-08-13 盘点确认在 main,07-24 tally 系列还补了首填耗时防洗白);前端(Touhou-Vote `f59585a`)状态需在前端仓核对。待:①前端侧确认已推+真人验证 ②Phase 2 管理端多信号聚类 | — | [design](./superpowers/specs/2026-07-17-submit-timing-signal-design.md) | | **B-044** | 反刷票证据采集:设备 UUID 指纹(注册 + 每票)+ 可信客户端 IP(读 X-Real-IP、CIDR 信任、REST 覆盖)。只取证不拦截,供事后按 IP/设备聚类多账号 | 🟡 **Phase 0 已联调验证** (2026-07-17):后端(0011+deviceId落库+IP修复,355 passed,已部署)+前端(Touhou-Vote `4b9f4c5`,已部署:8082)+Nacos `TRUSTED_PROXY_IPS` 已配;真人投票实测:新票记真实公网 IP(对照旧票 nginx 内网 172.18.0.7)+设备指纹已落 raw_*。待:①Phase 1 FingerprintJS(+ HTTP 兜底改 crypto.getRandomValues) ②Phase 2 管理端聚类视图 ③~~投票记录 append-only 评估~~✅**已完成**(2026-08-29,B-050-后补2 Step 2:迁移 0017 落地 `raw_*`/`paper_answer` append-only 存储,见 CHANGELOG 同日条目) ④admin 端点暴露 register_device_id/投票指纹(现仅 CSV 出 user_ip) | — | [design](./superpowers/specs/2026-07-17-anti-vote-farming-design.md) | | **B-042** | 测试环境配置硬化(2026-07-14 联调准备中实测发现):①✅ **已解决**(2026-07-17)——Nacos `thvote_be` 已配 `ADMIN_SECRET`(测试弱值 `abc123`,公开前换强值),`require_admin` fail-closed(secret+IP 白名单)已覆盖 `/api/v1/admin/*` 两路由 **+ `main.py` 三个 ops 端点**(`reload-config`/`discover*`),admin 不再裸奔;② scraper **Pixiv 凭据仍未配**(`Pixiv authentication failed`),二创提名刮削 Pixiv 源不可用,**上线前必须配**(配完需重启容器,B-017) | 低(仅剩 Pixiv 配置项,且 2026-08-13 用户示意**可能不再需要 Pixiv**) | ⏸ 等上游/待定(若确认不用 Pixiv 即可关闭本项) | Nacos 控制台见 `docs/operations/nacos-config-center.md` | -| **B-062** | `AutocompleteDAO.search_cps()` 恒返回 `[]`(`src/apps/autocomplete/dao.py:78`)——CP 自动补全端点 `POST /autocomplete/search` 的 CP 分类**永远为空**。角色/音乐走 `candidate_character`/`candidate_music` 表 ILIKE 已实现,CP 无现成候选表,需从已提交的 `cp.cp_list` JSON 抽唯一 CP 名做模糊匹配(**2026-08-31 文档整理时从 `REFACTOR_TODO.md` 迁入,代码侧已复核仍成立**) | 低(功能缺口,非阻塞) | 🟢 可立即做 | `src/apps/autocomplete/dao.py:77-78`;原始记录见 [archive/2026-05-30-refactor-todo](./archive/2026-05-30-refactor-todo.md) §六 | | **B-063** | `apps/scraper` 模块**无任何测试**(`tests/` 下无 scraper 相关用例)——外部 HTTP 依赖需 mock。与 B-010(覆盖率门禁切 `fail_under=80`)同域:scraper 是当前最大的未覆盖面(**2026-08-31 文档整理时从 `REFACTOR_TODO.md` 迁入,已复核仍成立**) | 低 | 🟢 可立即做 | `src/apps/scraper/`;原始记录见 [archive/2026-05-30-refactor-todo](./archive/2026-05-30-refactor-todo.md) §十 | --- diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index edbd7cd4..95f72880 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -5,6 +5,14 @@ > 创建日期:2026-04-27 > **2026-08-31 整理**:合并 9 组重复条目、按日期倒序重排;**2026-07-01 之前**的条目已迁至 [CHANGELOG-archive-2026H1.md](./CHANGELOG-archive-2026H1.md)。 +## [2026-11-08] 统一 autocomplete 搜索入口(第二阶段) + +- **Changed**:唯一公开入口收敛到 `POST /api/v1/autocomplete/search`,采用分类/关键词/年度输入及完整 candidate IDs 输出;候选服务归入 `service.py`,DAO 年度参数只在查询时传入。 +- **Removed**:旧 suggestions 请求响应模型、限量 ILIKE 查询、空 `search_cps()`、临时 `/autocomplete/candidates/search` 路由及重复服务文件;旧行为测试随对应功能移除,保留真实候选与缓存测试。 +- **Changed**:配套前端调用统一路由,公共输入框更名为 `CandidateSearchInput.vue`;拼音算法、两层 Redis 缓存和筛选排序行为不变。 +- **兼容性影响**:明确替换原 `/search` 的 suggestions 契约,临时候选路径不保留兼容别名;仓库内未发现旧建议业务调用方。前后端须使用同一阶段的配套版本,回滚亦同。B-062 旧 CP 空实现随功能移除,不代表新增 CP 组合搜索。 +- **数据迁移 / 配置变更**:无数据库迁移、依赖或配置变化;沿用现有 autocomplete 缓存失效,新语料/结果 namespace 不变。未推送或部署。 + ## [2026-11-08] 拼音候选搜索迁至 Python 后端 - **Added**:`pypinyin==0.55.0` 与项目内纯匹配器,支持原文、全拼、声母简拼、多音字、混输和原有模糊音;新增 `POST /api/v1/autocomplete/candidates/search`,按分类与年度返回全部匹配 candidate IDs。 diff --git a/docs/README.md b/docs/README.md index 45523989..2789488d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -191,6 +191,7 @@ | [`2026-06-08-questionnaire-admin-frontend.md`](./superpowers/plans/2026-06-08-questionnaire-admin-frontend.md) | 待实施(B-041 投票前端) | | [`2026-07-21-work-table-unified.md`](./superpowers/plans/2026-07-21-work-table-unified.md) | **部分实施**:后端主体已合入 main,收尾清单见 BACKLOG **B-057** | | [`2026-11-08-pinyin-candidate-search.md`](./superpowers/plans/2026-11-08-pinyin-candidate-search.md) | **已本地实现、未部署**:匹配器 → 后端 API 与缓存 → 前端请求状态 → 三入口替换和依赖清理 | +| [`2026-11-08-autocomplete-search-consolidation.md`](./superpowers/plans/2026-11-08-autocomplete-search-consolidation.md) | **已确认、第二阶段**:统一 `/autocomplete/search`、移除旧建议实现,前端输入框改名 | --- diff --git a/docs/api/voteable-api-contract.md b/docs/api/voteable-api-contract.md index b9921dd3..e90212e3 100644 --- a/docs/api/voteable-api-contract.md +++ b/docs/api/voteable-api-contract.md @@ -460,20 +460,11 @@ GET /vote-objects/{category}/{candidateId} ## 七、自动补全 -### `POST /autocomplete/search`(原接口保留) +### `POST /autocomplete/search`(唯一候选搜索入口;本地实现,未部署) -```json -// Request -{ "query": "博麗", "limit": 10 } -// Response -{ "suggestions": [{ "name": "博麗靈夢", "type": "character", "origin": "東方紅魔鄉" }] } -``` - -该接口按配置年度提供名称 ILIKE 建议,不返回候选 ID;不接受 categories 筛选。角色与音乐合并在 `suggestions` 中,CP 组合建议仍未实现。 - -### `POST /autocomplete/candidates/search`(2026-11-08 本地实现,未部署) +2026-11-08 第二阶段统一接口:原 `{query, limit} → {suggestions}` 名称建议契约被替换为下面的候选搜索契约。第一阶段临时的 `/autocomplete/candidates/search` 路径已移除,无别名路由。仓库内未发现旧建议接口业务调用方;配套前端必须与后端使用同一阶段的路径及契约。 -完整路径为 `/api/v1/autocomplete/candidates/search`;投票前端通过现有 API_PREFIX 转发。 +完整路径为 `/api/v1/autocomplete/search`;投票前端通过现有 API_PREFIX 转发。 ```json // Request(vote_year 可省略,默认服务配置年度) @@ -489,7 +480,7 @@ GET /vote-objects/{category}/{candidateId} - 返回全部匹配的 **candidate ID**,升序去重,无 limit;空查询返回当年该分类全部 ID,未知年度返回空数组。 - 前端将整数 ID 转字符串,与当前候选求交;个人已选项排除、CP 可重复成员、作品/类别筛选及日期排序留在前端。空查询不发请求;等待与失败有提示,过期响应不会覆盖新查询。 - 派生拼音语料和查询结果(含空数组)各缓存 60 秒;Redis 失败直接读数据库计算,数据库失败正常报错。现有写入失效及 `scope=autocomplete` 同时清理两类缓存。绕过正常失效时,两层 TTL 叠加最多约 120 秒旧结果。 -- 无数据库 schema 或数据迁移。发布顺序为后端先、前端后;回滚先前端,再按需回后端。 +- 无数据库 schema 或数据迁移。发布需配套前后端;从第一阶段切换时两端须同步到本阶段,回滚也须使用同一阶段的配套版本。 --- @@ -722,7 +713,6 @@ Query: category?, vote_year? |---|---|---|---| | 投票对象列表/详情 | `vote_objects:{year}:{category}[:{id}]` | 600s | work CRUD、voteable 导入/改归属/改资源、候选导入/改/删/合并 | | 问卷结构 | `questionnaire:structure:{year}` | 1800s | 问卷/题组/问题/选项 CRUD、整树导入 | -| 自动补全 | `autocomplete:{year}:{limit}:{q}` | 60s | 候选/作品变更 | | 拼音候选语料/结果 | `autocomplete:pinyin:v1:{year}:{category}:corpus` / `...:q:{sha256(query)}` | 各 60s | 与自动补全共用失效前缀 | | 已通过提名 | `nominations:approved:{page}:{size}` | 60s | 提名 approve/reject | diff --git a/docs/superpowers/plans/2026-11-08-autocomplete-search-consolidation.md b/docs/superpowers/plans/2026-11-08-autocomplete-search-consolidation.md new file mode 100644 index 00000000..ec06614f --- /dev/null +++ b/docs/superpowers/plans/2026-11-08-autocomplete-search-consolidation.md @@ -0,0 +1,51 @@ +# 统一 autocomplete 搜索入口 + +> 状态:2026-11-08 用户已确认;接口收敛已实现,相关检查及整体只读审阅通过,按两阶段分别本地提交。未推送或部署。 +> 执行方式:按 superpowers:executing-plans 在当前分支执行;工作区约定优先,不引入额外机制。 + +## 目标与已确认取舍 + +第一阶段已提交:后端 `77f43cf`、前端 `26f79df`。原方案为了兼容旧 suggestions 契约保留了两套搜索;仓库内未发现旧接口业务调用方,用户确认只保留一个入口。 + +最终唯一入口为 `POST /api/v1/autocomplete/search`,采用第一阶段的 `CandidateSearchRequest` / `CandidateSearchResponse`:category、query、可选 vote_year → category、规范化 query、实际 vote_year、全部 candidate_ids。旧 `{query, limit} → {suggestions}` 契约被替换,临时 `/autocomplete/candidates/search` 路径移除,不增加兼容分流或别名路由。 + +拼音规则、DAO 查询字段、Redis namespace / TTL / 失效、前端筛选及排序语义沿用第一阶段。旧建议缓存键不再读写,现有 autocomplete scope 仍可清理。无数据库迁移、数据操作、新配置或依赖变更。发布需配套前后端;回滚前端与后端到同一阶段,不能混用两个阶段的前端和搜索契约。 + +## 文件与职责 + +- 后端 `src/apps/autocomplete/service.py`:用第一阶段候选服务替换旧建议服务;移除重复 `candidate_search.py`。 +- `dao.py`:只保留 `load_search_documents`,删除旧 ILIKE 方法和空 CP 方法;DAO 不再保存未使用的默认年度,年度由 service 明确传入。 +- `schemas.py`:只保留 CandidateCategory 与候选搜索输入输出;`router.py` 只保留 `/search` 和一个 service 依赖。 +- `tests/integration/test_autocomplete.py`:保留真实 DAO + Redis 的新行为测试,更新服务导入和 DAO 构造;删除只测旧契约的用例。 +- `tests/integration/test_vote_objects.py`:原 HTTP 用例改为 `/search`;原断言继续验证完整新契约、默认/显式年度及非法输入。 +- 移除 `tests/unit/test_autocomplete_service.py`,其旧 limit 分配断言随已删除建议功能过时,不新增测试证明删除。 +- 前端 hook 及两份相关测试改为统一路径;将 `common/components/AutoComplete.vue` 改为 `CandidateSearchInput.vue`,更新角色和音乐导入及模板。CP 独立输入继续使用共享 hook。 +- 同步 API 文档、设计当前状态、两端 changelog 与前端开发说明;第一阶段计划作为历史实施记录保留。B-062 随旧建议链路移除归档为废弃项,不宣称实现 CP 组合推荐。 + +## 实施顺序 + +- [x] 先改已有 HTTP 用例和真实 hook 测试的目标路径,运行观察新契约尚未接到统一入口的失败。 +- [x] 合并 service / route / schema / DAO;保留拼音与缓存行为;清理过时测试并更新保留用例的导入。 +- [x] 更新前端路径及输入框命名,不改变交互或已确认功能范围。 +- [x] 更新文档与 changelog;集中运行下面的相关检查。 +- [x] 对第二阶段做一次整体只读审阅;只修具体关键问题,完成第二阶段两仓库提交。保留全部无关工作区改动,不 push / merge / deploy。 + +## 验证与审阅重点 + +- 真实 HTTP 请求 `/search` 使用新候选契约,query/year/category 校验仍成立。 +- 前端 hook 实际发往 `/v12-be/api/v1/autocomplete/search`,忽略过期响应、清空和失败状态仍成立。 +- 单一 router/service,旧 schemas、ILIKE 路径及临时候选路由已无业务引用;不机械复制拼音规则测试。 +- backend: `python -m pytest tests/unit/test_pinyin_matcher.py tests/unit/test_cache.py tests/integration/test_autocomplete.py tests/integration/test_vote_objects.py -q --tb=short`;`python -m flake8 src/ --max-line-length=88`。 +- frontend: `./node_modules/.bin/tsx --test packages/vote/src/common/lib/__tests__/candidateSearch.test.ts packages/vote/src/common/lib/__tests__/useCandidateSearch.test.ts`;本次相关文件 ESLint;`pnpm --filter @touhou-vote/vote build`。 +- 两端 `git diff --check`;检查暂存区只包含本阶段改动。无浏览器自动交互或线上验收。 + + +## 本地验证记录 + +- 第一阶段提交前:后端相关 45 项测试与 flake8 通过;前端 4 项测试与投票页构建通过。 +- 第二阶段:先将真实 HTTP 用例指向 `/search`,观察返回旧 suggestions 导致契约断言失败;真实 hook 用例观察仍请求临时候选 URL,路径断言失败。合并实现后两项恢复通过。 +- 后端集中命令:上述保留范围 `33 passed`,两条现存 asyncio / Strawberry 弃用提示;删除的 12 项仅对应已移除的旧建议行为。生产 `flake8 src/ --max-line-length=88` 通过。 +- 前端两个测试文件:`4 passed`;相关文件 ESLint 通过;投票页构建通过(现有 Browserslist 数据过期提示未改)。 +- 不运行浏览器自动交互、线上请求或数据库操作;无关改动保留在工作区,不纳入两阶段提交。 + +- 最终整体只读审阅未发现 Critical / Important / Minor 问题;确认服务代码搬移及输入框重命名的内容完全一致,无需追加修复。两端暂存区检查通过,无关文件原始哈希未改变。 diff --git a/docs/superpowers/plans/2026-11-08-pinyin-candidate-search.md b/docs/superpowers/plans/2026-11-08-pinyin-candidate-search.md index 8571e93a..85464c2f 100644 --- a/docs/superpowers/plans/2026-11-08-pinyin-candidate-search.md +++ b/docs/superpowers/plans/2026-11-08-pinyin-candidate-search.md @@ -1,6 +1,6 @@ # 拼音候选搜索后端化实施计划 -> 状态:2026-11-08 用户已确认;四项任务已本地实现并通过相关检查及最终只读审阅。未发布或部署。 +> 状态:第一阶段已提交(后端 `77f43cf`、前端 `26f79df`),未发布或部署。本文保留该阶段的历史契约;当前接口以 [第二阶段收敛计划](2026-11-08-autocomplete-search-consolidation.md) 及设计/API 文档为准。 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans when implementing inline; use superpowers:subagent-driven-development only when the user chooses delegated execution. Steps use checkbox (`- [x]`) syntax. Project AGENTS.md and current user authorization take precedence. **Goal:** 将角色、音乐与 CP 成员选择中的拼音搜索迁到 Python 后端,保留原文、简拼、混输和已配置的模糊音。 diff --git a/docs/superpowers/specs/2026-11-08-pinyin-candidate-search-design.md b/docs/superpowers/specs/2026-11-08-pinyin-candidate-search-design.md index 7d8b3da9..54ad777d 100644 --- a/docs/superpowers/specs/2026-11-08-pinyin-candidate-search-design.md +++ b/docs/superpowers/specs/2026-11-08-pinyin-candidate-search-design.md @@ -2,7 +2,7 @@ > 状态:用户已确认,两个同名分支已本地实现;未发布或部署。2026-11-08。 > 已确认方向:使用 pypinyin 提供读音,在项目内实现需要的匹配行为,不引入 JS 运行时。 -> 模块位置、接口、缓存和前端接入方案均已确认;下文保留设计依据。 +> 模块位置、接口、缓存和前端接入方案均已确认;第二阶段经用户确认统一到 `/autocomplete/search`,下文描述当前方案。 ## 1. 目标与当前实现 @@ -10,7 +10,7 @@ 代码基线:后端分支 `feat/pinyin-backend-search`,`265ab63`,已包含 `origin/main` 的 `6d8afc1`;前端同名分支指向 `ef028e0`,与调研时的 `origin/dev` 一致。实施前已归档并 stash 前端 `fix/codegen-exit-status` 未提交现场,切到同名功能分支,并保留尚未被上游包含的本地改动。 -迁移前前端使用 `pinin@0.2.0`。角色和 CP 成员共用 `characterSearch.ts`;音乐由 `musicSearch.ts` 创建搜索器。迁移前后端 `apps/autocomplete` 只有名称 ILIKE 和 60 秒响应缓存,响应没有候选 ID;旧接口继续保留。结果页正则筛选不使用 Pinin,本次不改。源码和迁移目录没有现成拼音字段;本次不据此声称线上数据库已核验。 +迁移前前端使用 `pinin@0.2.0`。角色和 CP 成员共用 `characterSearch.ts`;音乐由 `musicSearch.ts` 创建搜索器。迁移前后端 `apps/autocomplete` 只有名称 ILIKE 和 60 秒响应缓存,响应没有候选 ID;第二阶段用候选搜索契约替换旧接口,移除旧建议实现。结果页正则筛选不使用 Pinin,本次不改。源码和迁移目录没有现成拼音字段;本次不据此声称线上数据库已核验。 ## 2. 路线与取舍 @@ -34,13 +34,13 @@ | 文件 | 职责 | |---|---| | 新增 `src/apps/autocomplete/pinyin.py` | 纯 Python 的读音准备、21 条规则和文字匹配;不依赖 DAO、Redis、FastAPI | -| 新增 `src/apps/autocomplete/candidate_search.py` | 候选搜索用例:加载语料、调用匹配器、使用公共 Redis 缓存 | -| 修改 `src/apps/autocomplete/dao.py` | 增加当前年度候选的搜索字段读取;保留旧查询 | +| 更新 `src/apps/autocomplete/service.py` | 候选搜索用例:加载语料、调用匹配器、使用公共 Redis 缓存 | +| 修改 `src/apps/autocomplete/dao.py` | 按请求年度读取候选搜索字段;移除旧 ILIKE 查询和空 CP 方法 | | 修改 `src/apps/autocomplete/schemas.py` | 新接口的显式请求和响应 | -| 修改 `src/apps/autocomplete/router.py` | 新路由与依赖注入;旧 `/search` 保持原契约 | +| 修改 `src/apps/autocomplete/router.py` | 唯一 `/search` 路由与依赖注入,返回候选 ID 契约 | | 复用 `src/common/cache.py` | JSON 缓存及前缀失效;不扩展成新的缓存框架 | -依赖方向:router → candidate_search → DAO / pinyin / common.cache;pinyin 只依赖标准库和 `pypinyin==0.55.0`。原 `service.py` 继续服务旧自动补全接口,避免将两种响应混在一个流程中。 +依赖方向:router → service → DAO / pinyin / common.cache;pinyin 只依赖标准库和 `pypinyin==0.55.0`。`service.py` 只承载候选搜索;旧建议模型和临时候选路由均已移除。 前端在 `packages/shared/api/candidateSearch.ts` 放无框架请求函数,在 `packages/vote/src/common/lib/useCandidateSearch.ts` 放 Vue 请求状态;三个选择入口复用这两处逻辑。 @@ -114,7 +114,7 @@ def contains(text: PreparedText, query: str) -> bool: ... ## 5. 新接口与数据访问 -推荐增加 `POST /api/v1/autocomplete/candidates/search`,不改变现有 `POST /api/v1/autocomplete/search` 的请求、响应、配额和 ILIKE 行为。 +唯一入口为 `POST /api/v1/autocomplete/search`。第二阶段替换旧 suggestions 契约,不再保留限量 ILIKE 建议或临时候选路由;仓库内未发现旧建议业务调用方。这一契约变更已获用户确认。 ```json 请求:{"category":"character","query":"mls","vote_year":12} @@ -132,7 +132,7 @@ def contains(text: PreparedText, query: str) -> bool: ... 数据层新增: ```python -# dao.py;旧 DAO 的 vote_year 构造参数和旧方法保留。 +# dao.py;构造函数只接收 session,查询年度显式传入。 async def load_search_documents( self, category: Literal["character", "music"], vote_year: int ) -> list[tuple[int, tuple[str, ...]]]: ... @@ -164,7 +164,7 @@ flowchart LR | 原字及按位置排列的声母/韵母候选 | `autocomplete:pinyin:v1:{year}:{category}:corpus` | 60 秒 | | 完整命中 ID 列表,包括空结果 | `autocomplete:pinyin:v1:{year}:{category}:q:{sha256(query)}` | 60 秒 | -语料以 JSON 列表存储 candidate ID、独立文本和每个位置的原字/读音二元组。只保存当前年度该类别的搜索字段,不保存图片、音频、票数或个人已选项。按位置保留多音候选,不展开完整读音组合;序列化和恢复逻辑只留在 candidate_search.py。空查询直接由语料取全部 ID,不另外写 query 结果键。 +语料以 JSON 列表存储 candidate ID、独立文本和每个位置的原字/读音二元组。只保存当前年度该类别的搜索字段,不保存图片、音频、票数或个人已选项。按位置保留多音候选,不展开完整读音组合;序列化和恢复逻辑只留在 service.py。空查询直接由语料取全部 ID,不另外写 query 结果键。 规则或内部语料格式变动时将内部版本升为 `v2`;这只是代码常量,不新增数据库版本字段。依赖版本固定为 pypinyin 0.55.0,升级时核对读音差异并同步缓存版本。 @@ -179,7 +179,7 @@ flowchart LR ## 7. 前端接入 -前端请求使用 `${API_PREFIX}/api/v1/autocomplete/candidates/search`,即 `/v12-be/api/v1/autocomplete/candidates/search`。已核对 Vite 与 `Dockerfile.vote.template` 的通用 `/v12-be/` 转发:均剥离该前缀后到达后端 `/api/v1/...`。因此无需增加代理路径或改变部署拓扑。 +前端请求使用 `${API_PREFIX}/api/v1/autocomplete/search`,即 `/v12-be/api/v1/autocomplete/search`。已核对 Vite 与 `Dockerfile.vote.template` 的通用 `/v12-be/` 转发:均剥离该前缀后到达后端 `/api/v1/...`。因此无需增加代理路径或改变部署拓扑。 新增共享函数: @@ -203,7 +203,7 @@ function fetchCandidateSearch( Vue 层统一 `useCandidateSearch(category, query: Ref)`,使用当前 `voteYear` 和 API_PREFIX。返回 `matchedIds: Ref>`、`loading: Ref`、`error: Ref`。不缓存历史 query 结果,不持久化浏览器搜索缓存。 -- 保留输入端现有 100ms 节流,不叠加另一套 debounce。公共输入框与 CP 输入框增加 `maxlength=64`;后端仍独立校验码点长度。空查询立即展示本地已有列表,不发搜索请求。 +- 保留输入端现有 100ms 节流,不叠加另一套 debounce。公共输入框 `CandidateSearchInput.vue` 与 CP 输入框增加 `maxlength=64`;后端仍独立校验码点长度。空查询立即展示本地已有列表,不发搜索请求。 - 角色/音乐列表和 CP 选择框以公共命中 ID 集合过滤当前列表;已选项目的排除、类别/作品筛选、日期排序及 CP 允许重复成员等规则不变。 - 非空查询等待期间清除上一关键词的命中列表,显示“正在搜索…”;失败显示“搜索失败,请修改关键词重试”,清空关键词可继续浏览全部列表。不自动重试,不回退第二套拼音引擎。 - 使用 Vue watch 的 cleanup 忽略过期请求返回,确保快速输入或清空后旧结果不会盖掉当前结果;不增加请求队列、版本恢复或持久化状态。 @@ -221,15 +221,15 @@ Vue 层统一 `useCandidateSearch(category, query: Ref)`,使用当前 - 后端集成层使用现有 SQLite/fakeredis 测试条件,覆盖年度和类别、别名/作品独立匹配、完整集合与候选 ID、缓存命中/空结果/失效/Redis 不可用。 - 前端用现有 node:test 与 tsx 工具覆盖真实请求 helper、ID 映射、错误和过期返回;不建立新的端到端测试工程。UI 按项目约定最多截图,不自动点击或填写表单。 - 不以小样本全部相同证明完全兼容;若关键名字或常见输入与预期不符,先明确字典差异还是匹配错误,再调整该用例或将产品差异交用户确认。 -- 后端先提供加法接口,旧前端照常工作;前端切换后再清理 Pinin 依赖。前端上线依赖新接口可用,不以静默本地降级掩盖后端未更新。 -- 回滚先回前端旧版本,再按需回后端;数据库与投票记录无需回滚。新 Redis 键可自然过期或用原 autocomplete scope 清理。无数据迁移、真实回填或重新计票。 +- 初次迁移前的 Pinin 前端不使用此接口;第一阶段与第二阶段的前后端须分别配套发布,不能混用路径与契约。前端不保留第二套本地拼音引擎。 +- 回滚前后端到同一阶段的配套版本;数据库与投票记录无需回滚。新 Redis 键可自然过期或用原 autocomplete scope 清理。无数据迁移、真实回填或重新计票。 ## 9. 实施状态与剩余验证 -2026-11-08 用户确认了模块边界、新 ID 接口、两层 Redis 缓存及前端接入方案。纯匹配器、DAO、API、缓存、三个选择入口和依赖替换均已本地实现。 +2026-11-08 用户确认了模块边界、新 ID 接口、两层 Redis 缓存及前端接入方案。纯匹配器、DAO、API、缓存、三个选择入口和依赖替换均已本地实现。第一阶段后端 `77f43cf`、前端 `26f79df` 已分别提交;随后用户确认统一接口与命名,第二阶段见 [收敛计划](../plans/2026-11-08-autocomplete-search-consolidation.md)。 已验证关键匹配正反例、年度/字段隔离、缓存与失效、Redis 故障直算、HTTP 输入输出及前端请求竞态。最终命令与结果见 [实施计划](../plans/2026-11-08-pinyin-candidate-search.md) 执行记录。 -未进行线上数据查询、真实链路部署或浏览器交互验收;本次不包含这些授权。两端保留本地未提交改动,旧 CP 组合自动补全问题不在本次范围。 +未进行线上数据查询、真实链路部署或浏览器交互验收;本次不包含这些授权。两端无关本地改动继续保留;旧 CP 空实现随建议链路移除,不表示实现了 CP 组合推荐。 参考:[pypinyin 用法](https://pypinyin.readthedocs.io/zh-cn/master/usage.html)、前端 `ef028e0` 的 `pinin.ts` / `characterSearch.ts` / `musicSearch.ts`。官方需求中的角色和音乐拼音搜索见 `docs/requirements/VoileLabs-人气投票项目-需求文档-投票系统.md` 的角色选择框与曲目选择框。 diff --git a/src/apps/autocomplete/candidate_search.py b/src/apps/autocomplete/candidate_search.py deleted file mode 100644 index 6606fa31..00000000 --- a/src/apps/autocomplete/candidate_search.py +++ /dev/null @@ -1,69 +0,0 @@ -"""Public candidate matching with regenerable Redis caches.""" - -from hashlib import sha256 - -import redis.asyncio as aioredis - -from src.apps.autocomplete.dao import AutocompleteDAO -from src.apps.autocomplete.pinyin import PreparedText, TextUnit, contains, prepare_text -from src.apps.autocomplete.schemas import ( - CandidateCategory, - CandidateSearchRequest, - CandidateSearchResponse, -) -from src.common.cache import cache_get_json, cache_set_json - -CACHE_TTL = 60 -CACHE_PREFIX = "autocomplete:pinyin:v1" -Corpus = list[tuple[int, tuple[PreparedText, ...]]] - - -class CandidateSearchService: - def __init__( - self, dao: AutocompleteDAO, redis: aioredis.Redis, default_year: int - ) -> None: - self.dao = dao - self.redis = redis - self.default_year = default_year - - async def _corpus(self, category: CandidateCategory, year: int) -> Corpus: - key = f"{CACHE_PREFIX}:{year}:{category}:corpus" - cached = await cache_get_json(self.redis, key) - if cached is not None: - return [ - (cid, tuple( - tuple(TextUnit(literal, tuple(tuple(r) for r in readings)) - for literal, readings in text) - for text in texts - )) - for cid, texts in cached - ] - documents = await self.dao.load_search_documents(category, year) - corpus = [ - (cid, tuple(prepare_text(text) for text in texts)) - for cid, texts in documents - ] - serialized = [ - [cid, [[[unit.literal, unit.readings] for unit in text] for text in texts]] - for cid, texts in corpus - ] - await cache_set_json(self.redis, key, serialized, CACHE_TTL) - return corpus - - async def search(self, request: CandidateSearchRequest) -> CandidateSearchResponse: - query = request.query.strip().lower() - year = request.vote_year if request.vote_year is not None else self.default_year - fingerprint = sha256(query.encode("utf-8")).hexdigest() - key = f"{CACHE_PREFIX}:{year}:{request.category}:q:{fingerprint}" - ids = await cache_get_json(self.redis, key) if query else None - if ids is None: - corpus = await self._corpus(request.category, year) - ids = sorted({ - cid for cid, texts in corpus - if not query or any(contains(text, query) for text in texts) - }) - if query: - await cache_set_json(self.redis, key, ids, CACHE_TTL) - return CandidateSearchResponse( - category=request.category, query=query, vote_year=year, candidate_ids=ids, - ) diff --git a/src/apps/autocomplete/dao.py b/src/apps/autocomplete/dao.py index 61fd4c27..5fd1f898 100644 --- a/src/apps/autocomplete/dao.py +++ b/src/apps/autocomplete/dao.py @@ -2,7 +2,7 @@ from typing import Literal -from sqlalchemy import or_, select +from sqlalchemy import select from sqlalchemy.ext.asyncio import AsyncSession from src.db_model.candidate import CandidateCharacter, CandidateMusic @@ -11,9 +11,8 @@ class AutocompleteDAO: - def __init__(self, session: AsyncSession, vote_year: int): + def __init__(self, session: AsyncSession) -> None: self.session = session - self.vote_year = vote_year async def load_search_documents( self, category: Literal["character", "music"], vote_year: int @@ -37,67 +36,3 @@ async def load_search_documents( ))) for cid, name, aliases, work in rows ] - - async def search_characters(self, query: str, limit: int = 10) -> list[dict]: - stmt = ( - select( - VoteableCharacter.name, - Work.name, - VoteableCharacter.name_jp, - VoteableCharacter.type, - ) - .join( - CandidateCharacter, - CandidateCharacter.voteable_id == VoteableCharacter.id, - ) - .outerjoin(Work, VoteableCharacter.work_id == Work.id) - .where( - CandidateCharacter.vote_year == self.vote_year, - or_( - VoteableCharacter.name.ilike(f"%{query}%"), - VoteableCharacter.name_jp.ilike(f"%{query}%"), - ), - ) - .limit(limit) - ) - rows = (await self.session.execute(stmt)).all() - return [ - {"name": r[0], "origin": r[1] or None, "name_jp": r[2], "type": r[3]} - for r in rows - ] - - async def search_music(self, query: str, limit: int = 10) -> list[dict]: - stmt = ( - select( - VoteableMusic.name, - Work.name, - VoteableMusic.name_jp, - VoteableMusic.type, - ) - .join( - CandidateMusic, - CandidateMusic.voteable_id == VoteableMusic.id, - ) - .outerjoin(Work, VoteableMusic.work_id == Work.id) - .where( - CandidateMusic.vote_year == self.vote_year, - or_( - VoteableMusic.name.ilike(f"%{query}%"), - VoteableMusic.name_jp.ilike(f"%{query}%"), - ), - ) - .limit(limit) - ) - rows = (await self.session.execute(stmt)).all() - return [ - { - "name": r[0], - "origin": r[1] or None, - "name_jp": r[2], - "type": r[3], - } - for r in rows - ] - - async def search_cps(self, query: str, limit: int = 10) -> list[dict]: - return [] diff --git a/src/apps/autocomplete/router.py b/src/apps/autocomplete/router.py index 955b20a9..1ed7f1f4 100644 --- a/src/apps/autocomplete/router.py +++ b/src/apps/autocomplete/router.py @@ -1,4 +1,4 @@ -"""Autocomplete API routes.""" +"""Public candidate search API routes.""" from __future__ import annotations @@ -6,33 +6,18 @@ from fastapi import APIRouter, Depends from sqlalchemy.ext.asyncio import AsyncSession -from src.apps.autocomplete.candidate_search import CandidateSearchService from src.apps.autocomplete.dao import AutocompleteDAO from src.apps.autocomplete.schemas import ( - AutocompleteRequest, - AutocompleteResponse, CandidateSearchRequest, CandidateSearchResponse, ) -from src.apps.autocomplete.service import AutocompleteService -from src.common.cache import cache_get_json, cache_set_json +from src.apps.autocomplete.service import CandidateSearchService from src.common.config import Settings, get_settings from src.common.database import get_db_session from src.common.redis import get_redis router = APIRouter(prefix="/autocomplete", tags=["autocomplete"]) -# 按 (年份, 关键词, limit) 缓存;候选名单变更时按 autocomplete: 前缀失效。 -AUTOCOMPLETE_CACHE_TTL = 60 - - -async def get_autocomplete_service( - session: AsyncSession = Depends(get_db_session), - settings: Settings = Depends(get_settings), -) -> AutocompleteService: - dao = AutocompleteDAO(session, settings.vote_year) - return AutocompleteService(dao) - async def get_candidate_search_service( session: AsyncSession = Depends(get_db_session), @@ -40,32 +25,13 @@ async def get_candidate_search_service( redis: aioredis.Redis = Depends(get_redis), ) -> CandidateSearchService: return CandidateSearchService( - AutocompleteDAO(session, settings.vote_year), redis, settings.vote_year + AutocompleteDAO(session), redis, settings.vote_year ) -@router.post("/candidates/search", response_model=CandidateSearchResponse) +@router.post("/search", response_model=CandidateSearchResponse) async def search_candidates( request: CandidateSearchRequest, service: CandidateSearchService = Depends(get_candidate_search_service), ) -> CandidateSearchResponse: return await service.search(request) - - -@router.post("/search", response_model=AutocompleteResponse) -async def search_autocomplete( - request: AutocompleteRequest, - service: AutocompleteService = Depends(get_autocomplete_service), - settings: Settings = Depends(get_settings), - redis: aioredis.Redis = Depends(get_redis), -) -> dict: - """Search for autocomplete suggestions (Redis cached, 60s).""" - query = (request.query or "").strip().lower()[:64] - key = f"autocomplete:{settings.vote_year}:{request.limit}:{query}" - cached = await cache_get_json(redis, key) - if cached is not None: - return cached - result = await service.search(request) - payload = result.model_dump() - await cache_set_json(redis, key, payload, AUTOCOMPLETE_CACHE_TTL) - return payload diff --git a/src/apps/autocomplete/schemas.py b/src/apps/autocomplete/schemas.py index d5a95eb4..748a25f7 100644 --- a/src/apps/autocomplete/schemas.py +++ b/src/apps/autocomplete/schemas.py @@ -1,31 +1,10 @@ -"""Autocomplete schemas for request/response validation.""" +"""Public candidate search request and response contracts.""" -from typing import Literal, Optional +from typing import Literal from pydantic import BaseModel, Field -class AutocompleteRequest(BaseModel): - """Request schema for autocomplete.""" - - query: str - limit: Optional[int] = 10 - - -class AutocompleteSuggestion(BaseModel): - """Autocomplete suggestion item.""" - - name: str - type: str - origin: Optional[str] = None - - -class AutocompleteResponse(BaseModel): - """Response schema for autocomplete.""" - - suggestions: list[AutocompleteSuggestion] - - CandidateCategory = Literal["character", "music"] diff --git a/src/apps/autocomplete/service.py b/src/apps/autocomplete/service.py index 38b06270..6606fa31 100644 --- a/src/apps/autocomplete/service.py +++ b/src/apps/autocomplete/service.py @@ -1,41 +1,69 @@ -"""Autocomplete service layer.""" +"""Public candidate matching with regenerable Redis caches.""" -import math +from hashlib import sha256 + +import redis.asyncio as aioredis from src.apps.autocomplete.dao import AutocompleteDAO +from src.apps.autocomplete.pinyin import PreparedText, TextUnit, contains, prepare_text from src.apps.autocomplete.schemas import ( - AutocompleteRequest, - AutocompleteResponse, - AutocompleteSuggestion, + CandidateCategory, + CandidateSearchRequest, + CandidateSearchResponse, ) +from src.common.cache import cache_get_json, cache_set_json + +CACHE_TTL = 60 +CACHE_PREFIX = "autocomplete:pinyin:v1" +Corpus = list[tuple[int, tuple[PreparedText, ...]]] + + +class CandidateSearchService: + def __init__( + self, dao: AutocompleteDAO, redis: aioredis.Redis, default_year: int + ) -> None: + self.dao = dao + self.redis = redis + self.default_year = default_year + async def _corpus(self, category: CandidateCategory, year: int) -> Corpus: + key = f"{CACHE_PREFIX}:{year}:{category}:corpus" + cached = await cache_get_json(self.redis, key) + if cached is not None: + return [ + (cid, tuple( + tuple(TextUnit(literal, tuple(tuple(r) for r in readings)) + for literal, readings in text) + for text in texts + )) + for cid, texts in cached + ] + documents = await self.dao.load_search_documents(category, year) + corpus = [ + (cid, tuple(prepare_text(text) for text in texts)) + for cid, texts in documents + ] + serialized = [ + [cid, [[[unit.literal, unit.readings] for unit in text] for text in texts]] + for cid, texts in corpus + ] + await cache_set_json(self.redis, key, serialized, CACHE_TTL) + return corpus -class AutocompleteService: - def __init__(self, autocomplete_dao: AutocompleteDAO): - self.autocomplete_dao = autocomplete_dao - - async def search(self, request: AutocompleteRequest) -> AutocompleteResponse: - per_cat = math.ceil(request.limit / 2) - results: list[AutocompleteSuggestion] = [] - - for item in await self.autocomplete_dao.search_characters( - request.query, per_cat - ): - results.append( - AutocompleteSuggestion( - name=item.get("name", ""), - type="character", - origin=item.get("origin"), - ) - ) - - for item in await self.autocomplete_dao.search_music(request.query, per_cat): - results.append( - AutocompleteSuggestion( - name=item.get("name", ""), - type="music", - origin=item.get("origin"), - ) - ) - - return AutocompleteResponse(suggestions=results[: request.limit]) + async def search(self, request: CandidateSearchRequest) -> CandidateSearchResponse: + query = request.query.strip().lower() + year = request.vote_year if request.vote_year is not None else self.default_year + fingerprint = sha256(query.encode("utf-8")).hexdigest() + key = f"{CACHE_PREFIX}:{year}:{request.category}:q:{fingerprint}" + ids = await cache_get_json(self.redis, key) if query else None + if ids is None: + corpus = await self._corpus(request.category, year) + ids = sorted({ + cid for cid, texts in corpus + if not query or any(contains(text, query) for text in texts) + }) + if query: + await cache_set_json(self.redis, key, ids, CACHE_TTL) + return CandidateSearchResponse( + category=request.category, query=query, vote_year=year, candidate_ids=ids, + ) diff --git a/tests/integration/test_autocomplete.py b/tests/integration/test_autocomplete.py index b3e6c573..1667dd71 100644 --- a/tests/integration/test_autocomplete.py +++ b/tests/integration/test_autocomplete.py @@ -83,72 +83,10 @@ async def session(): await engine.dispose() -@pytest.mark.asyncio -async def test_search_characters_by_name(session): - dao = AutocompleteDAO(session, VOTE_YEAR) - results = await dao.search_characters("灵梦", 10) - assert len(results) == 1 - assert results[0]["name"] == "博丽灵梦" - assert results[0]["origin"] == "东方红魔乡" - - -@pytest.mark.asyncio -async def test_search_characters_by_name_jp(session): - dao = AutocompleteDAO(session, VOTE_YEAR) - results = await dao.search_characters("霊夢", 10) - assert len(results) == 1 - assert results[0]["name"] == "博丽灵梦" - - -@pytest.mark.asyncio -async def test_search_characters_no_match(session): - dao = AutocompleteDAO(session, VOTE_YEAR) - results = await dao.search_characters("不存在的名字xyz", 10) - assert results == [] - - -@pytest.mark.asyncio -async def test_search_characters_limit(session): - dao = AutocompleteDAO(session, VOTE_YEAR) - results = await dao.search_characters("夜", 1) - assert len(results) <= 1 - - -@pytest.mark.asyncio -async def test_search_music_by_name(session): - dao = AutocompleteDAO(session, VOTE_YEAR) - results = await dao.search_music("Bad", 10) - assert len(results) == 1 - assert results[0]["name"] == "Bad Apple!!" - assert results[0]["origin"] == "Akyu's Untouched Score vol.5" - - -@pytest.mark.asyncio -async def test_search_music_no_album_returns_none_origin(session): - dao = AutocompleteDAO(session, VOTE_YEAR) - results = await dao.search_music("U.N", 10) - assert len(results) == 1 - assert results[0]["origin"] is None - - -@pytest.mark.asyncio -async def test_search_cps_returns_empty(session): - dao = AutocompleteDAO(session, VOTE_YEAR) - results = await dao.search_cps("anything", 10) - assert results == [] - - -@pytest.mark.asyncio -async def test_wrong_year_returns_nothing(session): - dao = AutocompleteDAO(session, vote_year=9999) - results = await dao.search_characters("灵梦", 10) - assert results == [] - - @pytest.mark.asyncio async def test_candidate_search_fields_year_and_cache(session, patch_redis): from src.apps.admin.router import _clear_vote_objects_cache - from src.apps.autocomplete.candidate_search import CandidateSearchService + from src.apps.autocomplete.service import CandidateSearchService from src.apps.autocomplete.schemas import CandidateSearchRequest from src.db_model.candidate import CandidateCharacter from src.db_model.voteable import VoteableCharacter @@ -158,7 +96,7 @@ async def test_candidate_search_fields_year_and_cache(session, patch_redis): session.add(CandidateCharacter(vote_year=2027, voteable_id=101)) await session.commit() service = CandidateSearchService( - AutocompleteDAO(session, VOTE_YEAR), patch_redis, VOTE_YEAR + AutocompleteDAO(session), patch_redis, VOTE_YEAR ) async def search(query, year=VOTE_YEAR, category="character"): @@ -201,7 +139,7 @@ async def search(query, year=VOTE_YEAR, category="character"): @pytest.mark.asyncio async def test_candidate_search_all_matches_and_redis_failure(session): - from src.apps.autocomplete.candidate_search import CandidateSearchService + from src.apps.autocomplete.service import CandidateSearchService from src.apps.autocomplete.schemas import CandidateSearchRequest from src.db_model.candidate import CandidateCharacter from src.db_model.voteable import VoteableCharacter @@ -223,7 +161,7 @@ async def set(self, *args, **kwargs): "SELECT id FROM candidate_character WHERE vote_year=2028 ORDER BY id" ))).scalars()) service = CandidateSearchService( - AutocompleteDAO(session, 2028), UnavailableRedis(), 2028 + AutocompleteDAO(session), UnavailableRedis(), 2028 ) result = await service.search( CandidateSearchRequest(category="character", query="共同") @@ -236,10 +174,10 @@ async def set(self, *args, **kwargs): async def test_candidate_search_does_not_cache_database_errors( session, patch_redis, monkeypatch ): - from src.apps.autocomplete.candidate_search import CandidateSearchService + from src.apps.autocomplete.service import CandidateSearchService from src.apps.autocomplete.schemas import CandidateSearchRequest - dao = AutocompleteDAO(session, VOTE_YEAR) + dao = AutocompleteDAO(session) async def fail(*args): raise RuntimeError("test database failure") diff --git a/tests/integration/test_vote_objects.py b/tests/integration/test_vote_objects.py index 3b10301b..82f5c348 100644 --- a/tests/integration/test_vote_objects.py +++ b/tests/integration/test_vote_objects.py @@ -107,7 +107,7 @@ async def test_candidate_search_http_contract(app): cid = (await session.execute(text( "SELECT id FROM candidate_character WHERE vote_year=2026 AND voteable_id=11" ))).scalar_one() - url = "/api/v1/autocomplete/candidates/search" + url = "/api/v1/autocomplete/search" async with AsyncClient(transport=ASGITransport(app=a), base_url="http://test") as client: result = await client.post(url, json={"category": "character", "query": " MLS "}) assert result.status_code == 200 diff --git a/tests/unit/test_autocomplete_service.py b/tests/unit/test_autocomplete_service.py deleted file mode 100644 index bab23ec0..00000000 --- a/tests/unit/test_autocomplete_service.py +++ /dev/null @@ -1,57 +0,0 @@ -"""Unit tests for AutocompleteService limit distribution.""" - -import math -from unittest.mock import AsyncMock - -import pytest - -from src.apps.autocomplete.schemas import AutocompleteRequest -from src.apps.autocomplete.service import AutocompleteService - - -def _make_suggestions(n: int, type_: str) -> list[dict]: - return [{"name": f"{type_}{i}", "origin": "orig", "name_jp": "", "type": type_} for i in range(n)] - - -@pytest.fixture -def mock_dao(): - dao = AsyncMock() - dao.search_characters = AsyncMock(return_value=_make_suggestions(10, "char")) - dao.search_music = AsyncMock(return_value=_make_suggestions(10, "music")) - dao.search_cps = AsyncMock(return_value=[]) - return dao - - -@pytest.mark.asyncio -async def test_limit_distributed_equally(mock_dao): - """Each category gets ceil(limit/2) items queried from DAO.""" - service = AutocompleteService(mock_dao) - await service.search(AutocompleteRequest(query="x", limit=10)) - mock_dao.search_characters.assert_called_once_with("x", math.ceil(10 / 2)) - mock_dao.search_music.assert_called_once_with("x", math.ceil(10 / 2)) - - -@pytest.mark.asyncio -async def test_total_capped_at_limit(mock_dao): - """Total suggestions never exceed request.limit.""" - service = AutocompleteService(mock_dao) - result = await service.search(AutocompleteRequest(query="x", limit=6)) - assert len(result.suggestions) <= 6 - - -@pytest.mark.asyncio -async def test_odd_limit_distributed(mock_dao): - """ceil(7/2) = 4 per category.""" - service = AutocompleteService(mock_dao) - await service.search(AutocompleteRequest(query="x", limit=7)) - mock_dao.search_characters.assert_called_once_with("x", 4) - mock_dao.search_music.assert_called_once_with("x", 4) - - -@pytest.mark.asyncio -async def test_cp_not_counted_in_limit(mock_dao): - """CP returns [] and doesn't consume limit quota.""" - service = AutocompleteService(mock_dao) - mock_dao.search_cps = AsyncMock(return_value=[]) - result = await service.search(AutocompleteRequest(query="x", limit=4)) - assert len(result.suggestions) == 4 From b8e4973e537caa801932eee8ec1646bdbe00e82a Mon Sep 17 00:00:00 2001 From: Renko6626 <2300011496@stu.pku.edu.cn> Date: Sun, 8 Nov 2026 02:09:24 +0800 Subject: [PATCH 3/4] docs: reconcile historical backlog with current implementation --- docs/BACKLOG-archive.md | 23 ++ docs/BACKLOG.md | 162 ++++-------- docs/CHANGELOG.md | 8 + docs/README.md | 19 +- .../database-schema-management.md | 3 + docs/archive/2026-05-30-refactor-todo.md | 3 + docs/archive/README.md | 2 +- docs/migration/backlog-audit-2026-11-08.md | 62 +++++ docs/migration/legacy-rest-compat.md | 3 + .../result-stats-audit-2026-08-14.md | 3 + docs/operations/cicd-pipeline.md | 243 +++--------------- docs/operations/nacos-config-center.md | 3 + ...2026-06-08-questionnaire-admin-frontend.md | 4 + .../2026-06-08-questionnaire-frontend.md | 4 + .../plans/2026-06-08-security-frontend.md | 4 + .../plans/2026-06-08-vote-objects-frontend.md | 4 + .../plans/2026-07-21-work-table-unified.md | 4 + .../specs/2026-04-27-user-auth-open-issues.md | 3 + .../specs/2026-05-13-autocomplete-design.md | 4 +- ...-08-questionnaire-admin-frontend-design.md | 4 + ...026-06-08-questionnaire-frontend-design.md | 4 + .../2026-06-08-security-frontend-design.md | 4 + ...2026-06-08-vote-objects-frontend-design.md | 4 + ...26-07-18-result-recount-id-based-design.md | 21 +- .../2026-07-21-work-table-unified-design.md | 4 +- 25 files changed, 262 insertions(+), 340 deletions(-) create mode 100644 docs/migration/backlog-audit-2026-11-08.md diff --git a/docs/BACKLOG-archive.md b/docs/BACKLOG-archive.md index b63aef07..6cfb11db 100644 --- a/docs/BACKLOG-archive.md +++ b/docs/BACKLOG-archive.md @@ -3,8 +3,31 @@ > 从 [BACKLOG.md](./BACKLOG.md) 迁出的历史条目,**行文保留迁出时原样**(含当时措辞、链接与遗留注记)。 > 首次归档:2026-08-13(31 项)。之后每当 BACKLOG 有项完成,按其维护规则把整行移到本表顶部。 +## 2026-11-08 源码核对补记 + +以下迁出行的主题保留原历史措辞,状态列更新为本轮结论。迁出依据以 [本轮核对记录](migration/backlog-audit-2026-11-08.md) 为准;“实现已存在”不代表本次执行过部署或数据核验。 + +- **B-028**:源码已实现:现有 workflow 的 deploy-prod job 由 workflow_dispatch + deploy_prod 触发;本次未核验实际发布环境。 +- **B-039**:源码已实现:当前问卷页面消费后端结构并使用 submitPaperV2;早期固定槽方案已由 B-041 数组契约取代。 +- **B-040**:源码已实现:角色、音乐和 CP 成员来自后端候选;资源、别名、candidate ID 与筛选 metadata 已接入。 +- **B-041**:源码已实现:问卷数组、category/order、required、隐藏组及结构化答案提交/回填已消费;本次未验证题库或线上验收。 +- **B-050**:v1 与后补2/5/6 均已实现,不能再把 trend、DSL、数据库白名单列为未做;上届对比单独保留为 B-050-后补3。 +- **B-050-后补2**:append-only 净增量趋势已由主榜和 DSL 子集路径消费;原尾项 attempt 列也已在源码展示。 +- **B-057**:实现收口:管理列表/归属编辑、导入按名称查找/创建 work、前端 Task8/9 与 candidateId 已具备,CP metadata 收口为前端 edeaeea;历史榜单导入并入 B-050-后补3。 +- **B-061**:源码已有 API attempt 字段、DAO 取值和管理界面列,原“未展示”描述失实。 +- **B-063**:已补关键站点解析、URL 路由及限流测试,见 2026-10-20 CHANGELOG;不表示穷尽每个站点成功路径。 + | 编号 | 主题 | 严重度/状态 | 可并行做? | 源文档 | |---|---|---|---|---| +| **B-028** ⚡ | `.github/workflows/deploy-test.yml` 当前唯一的部署 workflow 没有 prod 路径——main 分支推送也只触发部署到 test 环境(镜像 tag 区分为 `prod` vs `test`,但部署目标都是 TEST_SERVER_HOST)。需要确认是否真的没有 prod 发布通道,或补一个 `deploy-prod.yml`。**注:2026-05-19 的 3 个 `fix(ci)` 提交只是修 deploy-test.yml 的 YAML/包发现 bug,未补 prod 通道,此项仍开放** | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期 | — | [cicd-pipeline §二](./operations/cicd-pipeline.md) | +| **B-039** | 问卷结构化系统(Block 3A):后端 4 结构表 + admin 整树导入 + structure 查询 + 结构化答题 + 完成校验升级;前端 questionnaireV2 改从后端拉(一次性切换) | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期,旧方案由 B-041 取代 | — | 后端✅:模型0008/assembler/completion/domain/graphql submitPaperV2/门禁升级/整树导入+UI;前端[plan](./superpowers/plans/2026-06-08-questionnaire-frontend.md)待做 | +| **B-040** | 投票对象迁后端(Block 3B):角色/音乐 merged_into 去重合并(自动+admin手调) + /vote-objects/characters\|music\|{id} 分类查询;前端角色/音乐/CP 改从后端拉 | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期 | — | 后端✅:merged_into 0009/detect_merges/merge端点/compute归并/vote-objects端点/合并UI;前端[plan](./superpowers/plans/2026-06-08-vote-objects-frontend.md)待做 | +| **B-041** | 问卷管理增强:自由问卷列表(去年份,持续迭代) + 全层级 CRUD(问卷/题组/题/选项) + 自研嵌套编辑器;契约改问卷数组(migration 0010);取代 B-039 的 admin/契约部分 | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期 | — | 后端✅:模型重塑+0010/assembler数组/importer数组/completion required/结构端点去年份/扁平答案/13 CRUD端点/自研嵌套编辑器UI;前端[plan](./superpowers/plans/2026-06-08-questionnaire-admin-frontend.md)待做 | +| **B-050** ⚡ | **计票系统大重写** —— ✅ **v1 完成 (2026-07-18)**:计票已改读真实提交表 `raw_*`(取每 `vote_id` 最新、排除 `invalidated`);按角色/音乐 id 归票 + 白名单丢未知 id;CP 改无序 multiset(顺序/主动方不进 key)+ 主动率 + 组合票数 1 不计;名次口径对齐权威文档(票数→本命数→系统ID,同票数同名次虚位);`RankingEntity` schema 补 `id`/`favorite_percentage_of_all`。删死表 vote_data 已完成(2026-07-17)。**v1 后补子项:1/4/8 已在 `feat/result-graphql-compat` 分支完成(2026-07-19,见下),2/3/5/6 仍开放**。 | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期;历史对比/数据剩余并入 B-050-后补3 | — | **[设计稿:纯 id 记票重写](./superpowers/specs/2026-07-18-result-recount-id-based-design.md)**(§九 v1 实现落地);`compute_dao.py`/`compute.py`/`compute_service.py`/`whitelist.py`;数据落点见 B-049 | +| **B-050-后补2** | trend 投票演进 | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期 | — | 同上设计稿 §9.4;CHANGELOG 2026-08-29 两条目 | +| **B-057** | voteable/work 重构收尾清单(2026-07-23 合入盘点发现):①✅**已完成**(2026-08-22,`feat/b060-b057`)——`GET /admin/voteables`(联 work 出 workId/workName/workType,q/分页)+ `POST /admin/voteables/{id}` 编辑 work 归属(清 vote-objects 缓存),5 测试;admin-ui 消费页面可后补;② admin import 的 work 按 name 匹配/自动建 work(Task 5,计划内 tech-debt);③ 上届 `final_ranking`(year=11) 导入未执行(会议结论要求"只导上届");④ 前端 Task 8/9(characterList/musicList 过滤逻辑、专辑名反查)+ **提交侧切 candidateId**(前置 B-050-后补6 已于 08-13 解除;**前端=我方负责**);⑤ 设计稿/plan 的 checkbox 与状态维护(与 zfq 沟通) | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期;历史对比/数据剩余并入 B-050-后补3 | — | [work 统一设计稿](./superpowers/specs/2026-07-21-work-table-unified-design.md);[实施计划](./superpowers/plans/2026-07-21-work-table-unified.md);CHANGELOG 2026-07-23 条目 | +| **B-061** | admin 监控投票列表(`src/apps/admin/monitor/`)展示 `attempt` 列:B-050-后补2 Step 2 把 `raw_*`/`paper_answer` 改成 append-only 后,同一选民多次改票会在监控列表出现多条历史行,当前列表未展示批次号,管理员不易一眼分辨"哪几行属于同一次改票" | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期 | — | `src/apps/admin/monitor/`;CHANGELOG 2026-08-29 append-only 条目 | +| **B-063** | `apps/scraper` 模块**无任何测试**(`tests/` 下无 scraper 相关用例)——外部 HTTP 依赖需 mock。与 B-010(覆盖率门禁切 `fail_under=80`)同域:scraper 是当前最大的未覆盖面(**2026-08-31 文档整理时从 `REFACTOR_TODO.md` 迁入,已复核仍成立**) | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期 | — | `src/apps/scraper/`;原始记录见 [archive/2026-05-30-refactor-todo](./archive/2026-05-30-refactor-todo.md) §十 | | **B-062** | `AutocompleteDAO.search_cps()` 恒返回 `[]`(`src/apps/autocomplete/dao.py:78`)——CP 自动补全端点 `POST /autocomplete/search` 的 CP 分类**永远为空**。角色/音乐走 `candidate_character`/`candidate_music` 表 ILIKE 已实现,CP 无现成候选表,需从已提交的 `cp.cp_list` JSON 抽唯一 CP 名做模糊匹配(**2026-08-31 文档整理时从 `REFACTOR_TODO.md` 迁入,代码侧已复核仍成立**) | ✅ 已废弃(2026-11-08,本地未部署):旧建议链路及空 CP 方法随统一候选搜索移除;CP 成员使用 character 搜索,未新增 CP 组合推荐 | — | `src/apps/autocomplete/dao.py:77-78`;原始记录见 [archive/2026-05-30-refactor-todo](./archive/2026-05-30-refactor-todo.md) §六 | | **B-008** | ~~MongoDB → PostgreSQL 历史用户数据回填脚本~~ | ✅ 已废弃 (2026-09-06):上线即空库,不再从旧 Mongo 导入用户;`map_voter`/voters 同步项随身份模型归一化删除,见 CHANGELOG 2026-09-06 | — | [medium-priority-backlog-design](./superpowers/specs/2026-05-16-medium-priority-backlog-design.md) | | **B-011** | ~~SSO 落地后移除 `User.at_least_one_identifier` CHECK 约束(约束仍在 `src/db_model/user.py:49` + migration 0001)~~ | ✅ 已完成 (2026-09-06):CHECK 约束随 migration 0018(`user_identity`)一并删除 | — | [design §九 F7](./superpowers/specs/2026-04-27-user-auth-design.md) | diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md index 408fd892..478a8a82 100644 --- a/docs/BACKLOG.md +++ b/docs/BACKLOG.md @@ -1,119 +1,65 @@ -# 后续开发 BACKLOG(单一仪表盘) +# 后续开发 BACKLOG -> 创建日期:2026-04-27 -> 最后更新:2026-11-08(B-062 随旧建议链路移除,归档为废弃项);此前:2026-08-31(文档大扫除:新增 B-062/B-063——从已归档的 `REFACTOR_TODO.md` 迁入两条经代码复核仍成立的缺口;docs 树归档重整,详见 CHANGELOG 2026-08-31)。此前:2026-08-13 第二轮(大扫除:31 条已完成/废弃项迁至 [BACKLOG-archive.md](./BACKLOG-archive.md);B-028/B-054/B-042②/B-043尾项标 ⏸ 等外部——用户确认只能等;前端队列确认我方负责) +> 创建:2026-04-27。当前核对:2026-11-08。 +> 源码基准:后端 `44bd972`(包含 `origin/main=6d8afc1`),前端 `edeaeea`(包含 `origin/dev=ef028e0`);本次已 fetch 核对远端。 +> 只核验已提交源码及维护记录,没有查询线上数据库、Nacos、告警服务或部署状态,也没有运行浏览器验收。完整证据见 [核对记录](migration/backlog-audit-2026-11-08.md)。 -把散落在 5 份文档里的 follow-up 收拢到这里。**这是仪表盘,不是真理来源**——每项的上下文还在原文档里,本表只给一行摘要 + 跳转。 +本表记录尚需决策或处理的事项。历史文档、空 checkbox、与其他语言实现不同或缺少某项可选能力,都不能单独作为缺陷证据。已实现/废弃内容进入 [归档](BACKLOG-archive.md),不继续重复排期。 -如果新发现 follow-up,**两件事都要做**:(1)写进对应主题的源文档;(2)在本表加一行。 +## 已确认仍有源码差异或待决定的行为 ---- +| 编号 | 当前事实 | 剩余范围/边界 | 证据 | +|---|---|---|---| +| **B-037** | 提名校验响应、待审核提示及问卷门禁已接入前端;“前端待做”失实 | 原计划逐条 index 提示与现有合并原因/重复数量展示有差异,是否调整待产品判断;可选 approved 列表不自动变为需求 | [前端计划](superpowers/plans/2026-06-08-security-frontend.md);`Touhou-Vote/packages/vote/src/vote-doujin/VoteDoujin.vue` | +| **B-050-后补3** | 主榜与 DSL 子集仍传空 historical,历史字段返回 -1/-1.0;旧 load_historical 已删除 | 若需要上届对比,需确认历史数据、ID 对应及接口接线。2026-08-22 旧 API 可用只是历史记录,本轮未核验数据/服务,不执行导入 | `src/apps/result/compute_service.py`、`advanced_search/service.py`、`src/api/graphql/result_compat.py` | +| **B-059** | Nacos 失败会记 warning,再尝试本地配置并可能回退默认值;并非无日志“静默”回退 | 是否改为 fail-fast 及适用运行模式仍需确认;历史事故不能自动授权增加恢复机制 | `src/common/nacos.py`、`src/common/config.py`;[Nacos 手册](operations/nacos-config-center.md) | +| **monitor 文案** | `_B050_NOTE` 仍说“需 B-050 落地后生效”,但计票已排除作废票 | 真实残留为提示文案;处置后仍需重算结果。本轮只核对文档,未修改业务响应 | `src/apps/admin/monitor/router.py`、`src/apps/result/compute_dao.py` | -## 状态总览(现存开放项;已完成/废弃项见 [BACKLOG-archive.md](./BACKLOG-archive.md)) +## 发布、运营及外部状态事项 -| 编号 | 主题 | 严重度 | 可并行做? | 源文档 | -|---|---|---|---|---| -| **B-010** | 测试覆盖率门禁切到 `fail_under=80` | 低 | 🟡 待模块稳定 1-2 sprint | [design §九 F6](./superpowers/specs/2026-04-27-user-auth-design.md) / spec §九 | -| **B-013** | 邮件/短信发送的"已发送"幂等性(避免阿里云调用成功但写日志失败造成的双发) | 低 | 🟡 低优先级,待发送链路稳定 | [design §九 F9](./superpowers/specs/2026-04-27-user-auth-design.md) | -| **B-019** | 错误响应 `{"detail":"..."}` 与 Rust 的 `{"error":"...","service":"..."}` 不一致 | 低 | 🟡 等前端反馈是否需要 | [open-issues §三 U-11](./superpowers/specs/2026-04-27-user-auth-open-issues.md) | -| **B-020** | mypy 在 CI 不是硬门禁;先清现存告警,再去掉 `\|\| true` | 低 | 🟢 可立即做 | [open-issues §三 U-12](./superpowers/specs/2026-04-27-user-auth-open-issues.md) | -| **B-026** | DB 治理纪律:PR 模板 model 改动提示 / CI `alembic check` / `db_model 改动必须有 migration` 检查 | 低 | 🟢 可立即做(**阻塞已解除**:B-025 已完成) | [schema-mgmt §三阶段 4](./architecture/database-schema-management.md) | -| **B-028** ⚡ | `.github/workflows/deploy-test.yml` 当前唯一的部署 workflow 没有 prod 路径——main 分支推送也只触发部署到 test 环境(镜像 tag 区分为 `prod` vs `test`,但部署目标都是 TEST_SERVER_HOST)。需要确认是否真的没有 prod 发布通道,或补一个 `deploy-prod.yml`。**注:2026-05-19 的 3 个 `fix(ci)` 提交只是修 deploy-test.yml 的 YAML/包发现 bug,未补 prod 通道,此项仍开放** | 高 | ⏸ **等上游拍板**(2026-08-13 用户确认:只能等) | [cicd-pipeline §二](./operations/cicd-pipeline.md) | -| **B-031** | `src/common/nacos.py` 的 `_parse_config_content` 自带 JS 风格 JSON 容错解析(正则提取),属于隐式技术债——上游 Nacos 配置应该写标准 JSON,让解析器走 `json.loads`。如果是为了兼容某个老 dataId,需文档化该 dataId 的写法约束 | 低 | 🟢 可立即做 | `src/common/nacos.py:29-97` | -| **B-037** | 安全块:二创提名校验(域名/发布时间/udid去重)+ 人工审核队列 + 提名时间窗 + 投票问卷门禁(弱校验) | 🟡 后端+管理端已完成 (2026-06-08);前端待做(**前端=我方负责,准备开做**,2026-08-13) | — | 后端✅[plan](./archive/superpowers/plans/2026-06-08-security-backend.md):配置/模型0007/纯校验/DAO/编排+门禁/GraphQL/管理端审核UI/公开查询;前端[plan](./superpowers/plans/2026-06-08-security-frontend.md)待实施 | -| **B-039** | 问卷结构化系统(Block 3A):后端 4 结构表 + admin 整树导入 + structure 查询 + 结构化答题 + 完成校验升级;前端 questionnaireV2 改从后端拉(一次性切换) | 🟡 后端已完成 (2026-06-08, 已合并 main 2026-07-14);前端待做(**前端=我方负责,准备开做**,2026-08-13) | — | 后端✅:模型0008/assembler/completion/domain/graphql submitPaperV2/门禁升级/整树导入+UI;前端[plan](./superpowers/plans/2026-06-08-questionnaire-frontend.md)待做 | -| **B-040** | 投票对象迁后端(Block 3B):角色/音乐 merged_into 去重合并(自动+admin手调) + /vote-objects/characters\|music\|{id} 分类查询;前端角色/音乐/CP 改从后端拉 | 🟡 后端已完成 (2026-06-08, 已合并 main 2026-07-14);前端待做(**前端=我方负责,准备开做**,2026-08-13) | — | 后端✅:merged_into 0009/detect_merges/merge端点/compute归并/vote-objects端点/合并UI;前端[plan](./superpowers/plans/2026-06-08-vote-objects-frontend.md)待做 | -| **B-041** | 问卷管理增强:自由问卷列表(去年份,持续迭代) + 全层级 CRUD(问卷/题组/题/选项) + 自研嵌套编辑器;契约改问卷数组(migration 0010);取代 B-039 的 admin/契约部分 | 🟡 后端+管理端已完成 (2026-06-09, 已合并 main 2026-07-14);投票前端待做(**前端=我方负责,准备开做**,2026-08-13) | — | 后端✅:模型重塑+0010/assembler数组/importer数组/completion required/结构端点去年份/扁平答案/13 CRUD端点/自研嵌套编辑器UI;前端[plan](./superpowers/plans/2026-06-08-questionnaire-admin-frontend.md)待做 | -| **B-043** | 注册防刷:发验证码前强制人机验证(阿里云验证码 2.0,service 层双入口收口,默认 fail-closed)+ 补齐发码端点 per-IP 限流与短信 per-号码守卫(当前发码端点**无任何后端限流**,2026-07-16 勘探发现) | 🟡 **人机验证已通真人验收** (2026-07-17):后端壳+Nacos(ENABLED=true,fail-closed)+前端 widget(Touhou-Vote `11a7630`,含 getInstance 触发时机修复)全链路打通,浏览器实测弹窗→过验→倒计时→收码正常;剩:①~~发码 per-IP 限流+短信 per-号码守卫~~✅已做(2026-07-17,service 层 per-IP 30/60s@captcha前 + 短信 per-号码 1/60s@captcha后,367 passed) ②海外网络加载实测 ③上线前切公家账户(手册§六,⏸ 等上游,2026-08-13) | — | [design](./superpowers/specs/2026-07-16-captcha-anti-abuse-design.md) / [接入手册](./operations/captcha-onboarding.md) | -| **B-048** | 拦脚本:让变更请求尽量来自真人浏览器。① 服务端 Origin/Referer 校验(对 GraphQL mutation + REST 提交/发码/登录要求带浏览器头,不带→403)② 端口收口(`:18000` 直连关闭,走 nginx) | 🟡 ①**已合并已部署,默认关** (2026-08-13 确认在 main:`REQUIRE_BROWSER_ORIGIN` 默认 false)——待 Nacos 置 true 灰度开启+真人回归;②**待办**(阻塞:前端 codegen 直连 :18000,收口前须先改走 nginx 代理) | 🟢 ①只差配置开关;②需先改前端 codegen | [design](./superpowers/specs/2026-07-17-block-scripts-design.md) | -| **B-047** | 反机器人特征 IP→ASN/数据中心归属:投票/注册 IP 富化出 ASN、标记机房/代理 IP(阿里云 ECS/AWS 等机房 IP 投票=高度可疑)。写入时或离线查;或用数据中心 IP 段名单。只取证不拦截 | ⏳ 待办(用户 2026-07-17 指定放待办) | 🟢 可独立做(依赖 B-044 可信 IP,已具备) | [反机器人特征清单见 submit-timing/anti-vote-farming 设计] | -| **B-049** | 管理端安全监控台:`require_admin` 统一闸门(secret 常量时间比较 + IP 白名单,fail-closed) + 监控 API(概览/IP·设备聚类/可疑打分/投票浏览器/账号钻取) + 处置动作(单条投票作废/恢复、账号人工复核,仅记录) | 🟡 **后端 Plan 1 已实现** (2026-07-17):migration `0014`(`raw_*.invalidated` + 索引 + `voter_review` 表) + `src/apps/admin/monitor/`(只读查询 + 处置端点,401 passed,flake8 clean)。**处置动作仅写标记/行,不接入排名计算**——排名效果推迟到 B-050。①✅ `main.py` 三个 ops 端点(`reload-config`/`discover*`)已纳入 `require_admin` 闸门(2026-07-17,勘察确认无内部/自动调用方,唯一调用方是带 secret 的 admin UI);②前端 Plan 2 **Phase 1+2 已实现** (2026-07-18):`admin-ui/` Vue3+Vite+TS 模块化(api client/composable/共享组件/view)。Phase 1=仪表盘+5 监控页+Users;Phase 2=**全部 6 个旧工具已迁**(候选项/数据同步/提名审核/问卷 4 层嵌套编辑器/审计日志/导出)。旧面板 `/admin-ui-legacy` 暂留兜底。**待:①视觉验收后删 legacy**(dir+挂载+nav 入口);②几个无 UI 端点补上(用户详情钻取/建合并/ranking preview) | 🟢 验收后清理 legacy;无 UI 端点可选补 | [design](./superpowers/specs/2026-07-17-admin-console-vue-security-monitoring-design.md) / [backend plan](./archive/superpowers/plans/2026-07-17-admin-console-security-monitoring-backend.md) | -| **B-050** ⚡ | **计票系统大重写** —— ✅ **v1 完成 (2026-07-18)**:计票已改读真实提交表 `raw_*`(取每 `vote_id` 最新、排除 `invalidated`);按角色/音乐 id 归票 + 白名单丢未知 id;CP 改无序 multiset(顺序/主动方不进 key)+ 主动率 + 组合票数 1 不计;名次口径对齐权威文档(票数→本命数→系统ID,同票数同名次虚位);`RankingEntity` schema 补 `id`/`favorite_percentage_of_all`。删死表 vote_data 已完成(2026-07-17)。**v1 后补子项:1/4/8 已在 `feat/result-graphql-compat` 分支完成(2026-07-19,见下),2/3/5/6 仍开放**。 | 🟡 中(核心闭环已修复,后补项非阻塞) | — | **[设计稿:纯 id 记票重写](./superpowers/specs/2026-07-18-result-recount-id-based-design.md)**(§九 v1 实现落地);`compute_dao.py`/`compute.py`/`compute_service.py`/`whitelist.py`;数据落点见 B-049 | -| **B-050-后补2** | trend 投票演进 | ✅ **已完成**(两步交付,2026-08-29):**Step 1**——`compute_paper_results` 已产出按提交行 `created_at` 分桶的近似 trend,`queryQuestionnaireTrend` 已接通(含 DSL 子集路径)。**Step 2**——`raw_*`/`paper_answer` 四表改造为 **append-only** 存储(迁移 0017,`paper_answer` 加 `attempt` 批次号 + 索引、删原 UNIQUE 约束;`SubmitDAO._upsert` 不再删旧插新),新纯函数 `src/apps/result/trend.py::net_delta_trends` 把角色/音乐/CP/问卷全类别 `trend`/`trend_first` 升级为真实净增量序列(改票产生负桶,不变量:每实体分桶净增量之和 == 最终票数),`compute_all` 与 DSL 子集重算路径均已接入。剩余小尾巴见 **B-061**(admin 监控列表展示 attempt 列) | — | 同上设计稿 §9.4;CHANGELOG 2026-08-29 两条目 | -| **B-050-后补3** | 上届对比:需历史 `final_ranking` 表有数据,且 `compute_dao.load_historical` 的 key 是 name、与 id-based 归票路径未对齐(现 `compute_service.py` 传空 `{}`)。**仍开放**——本轮契约层 `RankingEntry`/`CPRankingEntry` 的 8 个 `*_last_1`/`*_last_2` 历史字段已按 brief 要求固定填 -1 哨兵(见契约层 `_ranking_entry_from_dict` docstring 的"移除条件"),此项落地后需同步把契约层从硬编码 0 改成读 `rank[1]`/`rank[2]` 快照。**数据源已验证**(2026-08-22):老 Rust 生产 API `touhou.ai/vote-be/graphql` 的 `query*Ranking(voteYear:11)` 可直取上届完整榜(char totalVotes=13283 实测),字段与 `final_ranking` 表一一对应,无需找 dump;**导入动作等用户与协作方沟通后再执行** | 低 | ⏸ 等沟通(数据源就绪) | 同上设计稿 §9.4 | -| **B-053** | 通用"任意问卷题 × 投票结果"交叉分析 API + 前端(与 B-050-后补5 高级搜索同组,共用 `vote_id → {题code: [选项code]}` 索引,**该索引已在 2026-08-14 落地于 `src/apps/result/advanced_search/subset.py` 的 `build_facts`/`evaluate_subset`,可直接复用**):本轮只落地了"性别"这一个特例分段(经配置指定的固定题),通用查询(任选一道问卷题作为切分轴,交叉任意投票结果)与配套前端本轮未做——全题目预聚合会撑爆 Redis 榜单(244 角色 × 32 题 × 40 选项),应按需算 | 低 | 🟢 可独立做(与 B-050-后补5 同组) | 本设计稿 §五「C1.2」/§九「BACKLOG」;子集原语见 `src/apps/result/advanced_search/subset.py` | -| **B-054**(运营) | 录入真实问卷内容并回填 `question_def`/`option_def` 的 `code` 列:线上问卷结构是占位文案 + 非语义自增 id(问卷 id=1,2,3/组 id=1,2/题 id=1,2,3/选项 id=1,2),**在此之前性别票(B-050-后补1)与问卷结果(B-050-后补4)的统计管道虽已就绪,数字恒为 0**。前端 legacy `Touhou-Vote/packages/shared/data/questionnaire.ts` 含真实问卷内容 + 真实 7 位 id,是现成的导入源,不必手敲 | 高(阻塞两个契约层字段出真实数据) | ⏸ **等出题方**(2026-08-13 用户确认:只能等) | 本设计稿 §四「B」;`Touhou-Vote/packages/shared/data/questionnaire.ts` | -| **B-055**(前端,Touhou-Vote 仓库) | Task 7 验收时勘察 `packages/result/src` 发现的前端已知缺口(与本仓库后端无关,记录以便跨仓库跟踪):① `characterConnect.vue`/`MusicConnect.vue` 是"维护中"占位页(covote 契约本轮已修好,但无消费方);② `Doujin.vue` 总票数硬编码字面量 `1272`,无 GraphQL 查询;③ CP 部门只有 `Couple`/`CoupleDetail`/`CoupleSingleDetail`/`CoupleReason` 四页,缺角色/音乐都有的 compare/evolution 页;④ `router.ts` 里 `/test` → `Test.vue` 调试路由无条件注册在生产路由表 | 低(另一仓库,不阻塞本仓库任何工作) | — | `Touhou-Vote/packages/result/src/{pages/characterConnect.vue,pages/MusicConnect.vue,pages/Doujin.vue,router.ts}` | -| **B-056** | 迁移编号约定漂移:zfq_dev 的 voteable/work 重构引入 autogenerate 哈希名迁移 `12a5f2e6dbed_voteable_cross_year_stable_id`(约定应为 `00XX` 顺延)。测试库 `alembic_version` 已记录该 id,**改名需 stamp 修正、不建议轻动**——文档化现状即可;`0015` 已重接其后成单链(`0014→12a5f2e6dbed→0015`),**后续新迁移从 `0016` 顺延、down_revision 指 `0015`**。与 zfq 同步一下命名约定,避免下次再产生哈希名 | 低 | 🟢 纯约定沟通 | `alembic/versions/12a5f2e6dbed_*.py`;[[branch-ownership-zfq-dev]] 约定见 CLAUDE.md §9 | -| **B-057** | voteable/work 重构收尾清单(2026-07-23 合入盘点发现):①✅**已完成**(2026-08-22,`feat/b060-b057`)——`GET /admin/voteables`(联 work 出 workId/workName/workType,q/分页)+ `POST /admin/voteables/{id}` 编辑 work 归属(清 vote-objects 缓存),5 测试;admin-ui 消费页面可后补;② admin import 的 work 按 name 匹配/自动建 work(Task 5,计划内 tech-debt);③ 上届 `final_ranking`(year=11) 导入未执行(会议结论要求"只导上届");④ 前端 Task 8/9(characterList/musicList 过滤逻辑、专辑名反查)+ **提交侧切 candidateId**(前置 B-050-后补6 已于 08-13 解除;**前端=我方负责**);⑤ 设计稿/plan 的 checkbox 与状态维护(与 zfq 沟通) | 中 | 🟢 ①②③可独立;④前置已解除,入我方前端队列 | [work 统一设计稿](./superpowers/specs/2026-07-21-work-table-unified-design.md);[实施计划](./superpowers/plans/2026-07-21-work-table-unified.md);CHANGELOG 2026-07-23 条目 | -| **B-059** | 后端 Nacos 不可达时**静默回退**默认配置(localhost DB)再崩——08-13 事故中真实根因(Nacos auth 500)被掩埋在 asyncio 未回收异常里,排障绕了一圈。改法:`NACOS_ENABLED=true` 且拉取失败时 fail-fast 抛明确错误(带"检查 mynacos 容器"提示),不要带默认值起跑。与 B-017(热更新限制)同域 | 中(排障成本,已有 CI 前置检查兜一层) | 🟢 可立即做 | `src/common/nacos.py`/`config.py`;事故记录 `docs/operations/nacos-config-center.md` §八 | -| **B-061** | admin 监控投票列表(`src/apps/admin/monitor/`)展示 `attempt` 列:B-050-后补2 Step 2 把 `raw_*`/`paper_answer` 改成 append-only 后,同一选民多次改票会在监控列表出现多条历史行,当前列表未展示批次号,管理员不易一眼分辨"哪几行属于同一次改票" | 低 | 🟢 可独立做 | `src/apps/admin/monitor/`;CHANGELOG 2026-08-29 append-only 条目 | -| **B-058** | dependabot 9 个 npm 告警(3 高 6 中,2026-08-13 push 时发现):全部位于 `admin-ui/` 构建链(vite≤6.4.2 fs.deny 绕过/路径穿越、esbuild dev-server、nanoid、postcss)。**均为 dev/构建期依赖,不进运行时**(admin-ui 走 commit-dist);风险=开发者本机跑 `pnpm dev/build` 时。修法:`cd admin-ui && pnpm update vite esbuild postcss nanoid` + 重建 dist | 低(构建期,非线上面) | 🟢 可立即做 | https://github.com/PatchyVideo/thvote-be-re/security/dependabot | -| **B-046** | 反机器人特征:User-Agent(服务端取)+ 浏览器环境(tz/screen/lang,前端采)落 `raw_*.client_env`(单 JSON 列 migration 0013)。只取证不拦截 | 🟡 **后端已合并已部署** (0013 已在测试库,2026-08-13 盘点确认在 main);前端(Touhou-Vote `4b89a23`)状态需在前端仓核对。待:①前端侧确认已推+真人验证 ②Phase 2 聚类纳入 | — | [design](./superpowers/specs/2026-07-17-submit-timing-signal-design.md) | -| **B-045** | 反机器人时序特征:提交耗时 `fill_duration_ms`(客户端挂载→提交,新列 migration 0012)+ 服务端 `attempt` 改票计数(复用死列,首次=1/改票≥2)。只取证不拦截;"耗时短=可疑"只对首次生效,改票豁免(根治改票假阳性) | 🟡 **后端已合并已部署** (0012 已在测试库,2026-08-13 盘点确认在 main,07-24 tally 系列还补了首填耗时防洗白);前端(Touhou-Vote `f59585a`)状态需在前端仓核对。待:①前端侧确认已推+真人验证 ②Phase 2 管理端多信号聚类 | — | [design](./superpowers/specs/2026-07-17-submit-timing-signal-design.md) | -| **B-044** | 反刷票证据采集:设备 UUID 指纹(注册 + 每票)+ 可信客户端 IP(读 X-Real-IP、CIDR 信任、REST 覆盖)。只取证不拦截,供事后按 IP/设备聚类多账号 | 🟡 **Phase 0 已联调验证** (2026-07-17):后端(0011+deviceId落库+IP修复,355 passed,已部署)+前端(Touhou-Vote `4b9f4c5`,已部署:8082)+Nacos `TRUSTED_PROXY_IPS` 已配;真人投票实测:新票记真实公网 IP(对照旧票 nginx 内网 172.18.0.7)+设备指纹已落 raw_*。待:①Phase 1 FingerprintJS(+ HTTP 兜底改 crypto.getRandomValues) ②Phase 2 管理端聚类视图 ③~~投票记录 append-only 评估~~✅**已完成**(2026-08-29,B-050-后补2 Step 2:迁移 0017 落地 `raw_*`/`paper_answer` append-only 存储,见 CHANGELOG 同日条目) ④admin 端点暴露 register_device_id/投票指纹(现仅 CSV 出 user_ip) | — | [design](./superpowers/specs/2026-07-17-anti-vote-farming-design.md) | -| **B-042** | 测试环境配置硬化(2026-07-14 联调准备中实测发现):①✅ **已解决**(2026-07-17)——Nacos `thvote_be` 已配 `ADMIN_SECRET`(测试弱值 `abc123`,公开前换强值),`require_admin` fail-closed(secret+IP 白名单)已覆盖 `/api/v1/admin/*` 两路由 **+ `main.py` 三个 ops 端点**(`reload-config`/`discover*`),admin 不再裸奔;② scraper **Pixiv 凭据仍未配**(`Pixiv authentication failed`),二创提名刮削 Pixiv 源不可用,**上线前必须配**(配完需重启容器,B-017) | 低(仅剩 Pixiv 配置项,且 2026-08-13 用户示意**可能不再需要 Pixiv**) | ⏸ 等上游/待定(若确认不用 Pixiv 即可关闭本项) | Nacos 控制台见 `docs/operations/nacos-config-center.md` | -| **B-063** | `apps/scraper` 模块**无任何测试**(`tests/` 下无 scraper 相关用例)——外部 HTTP 依赖需 mock。与 B-010(覆盖率门禁切 `fail_under=80`)同域:scraper 是当前最大的未覆盖面(**2026-08-31 文档整理时从 `REFACTOR_TODO.md` 迁入,已复核仍成立**) | 低 | 🟢 可立即做 | `src/apps/scraper/`;原始记录见 [archive/2026-05-30-refactor-todo](./archive/2026-05-30-refactor-todo.md) §十 | +以下不是“当前代码完全没实现”。历史部署/人工验证记录保留在原主题文档,本次不重复执行,也不把未核验推断成仍有故障。 ---- - -## ⏸ 等外部 / 上游(2026-08-13 用户确认:只能等,我方不排期) - -- **B-028** prod 部署通道——等上游拍板部署形态 -- **B-054** 真实问卷录入 + code 回填——等出题方定稿(性别票/问卷统计出真实数字的唯一阻塞) -- **B-042②** Pixiv 凭据——等上游;且**可能不再需要 Pixiv**,若确认不用即可关闭 -- **B-043 尾项** 切公家验证码账户——等上游(海外网络加载实测可自行随时做) - -## 🎨 前端队列(Touhou-Vote 仓,我方负责,2026-08-13 确认) - -按依赖顺序: - -1. **提交侧切 candidateId**(B-057④)——✅ **前端已上线并端到端验证** (2026-08-14):测试机前端已全打 `/v12-be/`、vote-objects 返回 candidateId,投 candidateId 13/22/21→compute vote_year=12→queryCharacterRanking 正确归票(雾雨魔理沙/明罗/Flower战车),B-050-后补6 真实验证通过。剩:与 zfq 收口分支(功能修复在 zfq_dev_fe,dev 落后) -2. **B-039** questionnaireV2 改拉后端结构(一次性切换) -3. **B-040** 角色/音乐/CP 投票对象改拉后端 `/vote-objects/*` -4. **B-041** 问卷前端消费数组契约 -5. **B-037** 安全块前端(提名校验交互) -6. 核对 **B-045**(`f59585a`)/**B-046**(`4b89a23`) 两个前端 commit 是否已推已部署 -7. **B-055** 已知缺口(connect 占位页、Doujin 硬编码 1272、`/test` 调试路由) - -## 🟢 后端可立即做(7 项) - -按建议优先级排序: - -| 编号 | 一句话 | 估时 | +| 编号 | 已有内容/历史记录 | 尚待核验或决定 | |---|---|---| -| **B-059** | Nacos 不可达时 fail-fast(08-13 事故教训,取代静默回退 localhost DB) | 半天 | -| **B-026** | DB 治理纪律:PR 模板 + CI `alembic check`(防 B-051 类漂移复发) | 半天 | -| **B-057①③** | `GET /admin/voteables` 补实现;上届 final_ranking(year=11) 导入 | 各半天 | -| **B-020** | mypy 接入 CI(现状:lint job 只 pip install 了 mypy 但从未运行),先清告警再当门禁 | 半天-1 天 | -| **B-058** | admin-ui 构建链 9 个 npm 告警:`pnpm update` + 重建 dist | 1 小时 | -| **B-031** | Nacos 配置约束为标准 JSON 后删除 `_parse_config_content` 容错分支 | 1 小时(视上游配置是否能改) | +| **B-042** | 历史测试环境配置硬化及 Pixiv 凭据事项 | 当前凭据与 Pixiv 是否仍需要均未核验;不得据旧快照补造配置或要求新功能 | +| **B-043** | 人机验证与发码限流已有实现和历史验收记录 | 公用账号切换、海外网络体验等运营事项本次未核验 | +| **B-044 / B-045 / B-046** | 历史 IP/设备、提交耗时、clientEnv 采集已有记录;提交态前端角色/音乐/CP/提名已传耗时和环境字段 | 当前部署与真实落库未核验;问卷 V2 的提交签名不含相同字段,不宣称所有提交入口一致。后续指纹/聚类是独立需求 | +| **B-048** | Origin 校验已有代码;历史记录默认关闭。前端 codegen 仍使用测试机端口地址 | 开关、端口和当前部署状态未核验;收口之前须核对实际调用,不直接修改配置或网络 | +| **B-054** | 问卷语义 code 与统计管道已有历史实现记录 | 当前题库内容、code 与统计值未查库;删除“线上仍是占位、统计恒为0”的现状断言。内容由出题方确认,不执行导入或重新计票 | +| **B-058** | 2026-08-13 的 admin-ui 依赖告警是历史快照 | 未重跑在线告警/依赖审计,旧“9个、3高6中”不能当当前结果,也不据此自动升级依赖 | -## 🟡 需要判断 / 等条件成熟 +## 按需优化、兼容及待确认需求 -- **B-010** 覆盖率门禁切 `fail_under=80`(依赖模块运行 1-2 sprint 稳定后再切) -- **B-013** 邮件/短信发送幂等性(低优先级,发送链路已稳定后做) -- **B-019** 错误响应 `{"detail"}` → 与 Rust `{"error","service"}` 统一(等前端反馈是否需要) -- **B-033** 删除 legacy-compat 路由层(移除条件:Rust gateway 下线 + 前端迁 `/api/v1` 新 shape;与 B-019 同属契约收敛,详见 `docs/migration/legacy-rest-compat.md`) -- **B-050-后补2/3 + B-053** 记票深水区(trend 需 append-only 存储改造;上届对比依赖 B-057③ 数据;交叉分析共用"子集重算"原语)——适合打包出一份设计稿再动手。**2026-08-14 结果统计三方审计确认**:这几项正是结果站前端已具备入口、后端仍是桩的缺口——`characterCompare` 有往届对比页、`QuestionnaireDetail` 拿问卷趋势,后端一实现即点亮;`/res-be` 通路已通、result 站可联调。详见 [result-stats-audit-2026-08-14](./migration/result-stats-audit-2026-08-14.md)。(后补5 高级搜索已于 2026-08-14 完成,见 [BACKLOG-archive.md](./BACKLOG-archive.md),不再属于此"仍是桩"分组。) -- **前端 result 可维护性债(Touhou-Vote 仓,B-055 归口)** 审计新发现:`voteYear:11`+`voteStart` 硬编码散落 20+ 处未走 `lib/voteYear.ts`;characterEvolution.vue 过期日期文案;`/test` 调试路由在生产路由表;Doujin 页总票数等全硬编码(每届手改代码)。见审计文档 §三E/§C -- **B-049 尾项** admin-ui legacy 面板视觉验收后删除;无 UI 端点可选补 -- **B-047** IP→ASN 机房归属取证(可独立,属反作弊 Phase 2) -- **B-056** 迁移命名约定与 zfq 沟通(顺带同步:下一个迁移编号 **0018**、down=0017) -- ~~**B-066** 全站权限扫描后的两处加固~~ ✅ **已完成**(2026-09-13,`fix/scraper-ratelimit-email-code-attempts`):`POST /scraper/scrape` per-IP 10/min;邮箱验证码错 5 次作废。扫描的其余结论收进 `docs/operations/production-readiness-checklist.md`(P-1 关文档/GraphiQL、P-2 admin IP 白名单为**上线硬性项**;S-1 SSO `state`/`sid` 在接 SSO 前必须修) -- ~~**B-065** REST 提交/回读接口的 vote_id 越权~~ ✅ **已完成**(2026-09-13,`fix/rest-readback-token-auth`):6 个 `get-*`/`voting-status` 改按 `vote_token` 回读;5 个提交端点把 `meta.vote_id` 强制绑定为 token 的 user_id。契约见 `docs/api/voteable-api-contract.md` §3.2–3.4,细节见 CHANGELOG 2026-09-13 -- ~~**B-060** 高级搜索 per-IP 限流细化 + 两条终审小尾巴~~ ✅ **已完成**(2026-08-22,`feat/b060-b057`):`ClientIPMiddleware`(ContextVar) + 双层预算(per-IP 10/min + 全局 30/min) + 扣费后置到真正执行重算处(小尾巴①注释失实随之消除)+ 等锁改跟随锁存活轮询(上限 60s,锁消失提前接手;真机实测重算 ~8s,原固定 5s 会让等锁者集体重复计算)+ 3 个新测试真实覆盖等锁分支(小尾巴②销账:sleep 让出事件循环即可在 fakeredis 下触发 waiter 路径) +这些条目不等同于产品故障;没有具体场景或明确要求时,不自动变为本分支必做事项。 -## 🟢 模块功能缺口(不在 B 编号体系内) - -- **autocomplete CP 搜索**:`src/apps/autocomplete/dao.py` 的 `search_cps()` 仍 `return []`(角色/音乐已实现);需从已提交 `cp.cp_list` JSON 提取唯一 CP 名 -- **`GET /server-time` 端点**:旧 gateway 有,Python 侧未移植(低优先级) -- **scraper 测试**:18 站点全部移植但无测试(外部 HTTP 依赖,需 mock) -- **monitor invalidate 过时文案**:`_B050_NOTE`(`src/apps/admin/monitor/router.py`)作废投票时返回"影响排名需 B-050 计票重写落地后生效"——2026-08-14 实测作废后 compute 排名确实变化(chars 3→0),B-050 v1 早落地,此文案已过时误导,应更新(一行改动) - ---- - -## 推荐的下一步 - -- **前端(我方)**:candidateId 切换打头——同时解锁 B-057④ 与计票全链路真实数据,是当前唯一不受外部阻塞的高价值主线。 -- **后端穿插**:`B-059 + B-026` 打包一个"配置/DB 韧性"小 PR(都是 08-13 事故与 B-051 的直接教训);暖手 `B-058`(1 小时)。 -- **等外部的四项**不排期,条件一到再捡。 - ---- - -## 维护规则 - -- **新发现 follow-up:** 写进对应主题的源文档;在本表加一行;编号顺延 B-028, B-029... -- **某项完成:** 先把"严重度"改为 ✅ 已完成 + 完成日期 + commit hash / PR #;再把整行**移入 [BACKLOG-archive.md](./BACKLOG-archive.md)**(原文保留),保持本表只有活项 -- **三个状态分组**(🟢🟡🔴)随完成情况调整:依赖项落地后,相关项可以从 🔴 升到 🟡 或 🟢 -- 本表过 50 项时考虑分类拆文件(按主题:security backlog / schema backlog / test backlog 等),但目前规模够小不必拆 +| 编号 | 当前判断 | 下一步条件 | +|---|---|---| +| **B-010** | `fail_under=80` 是旧质量门禁建议 | 按实际风险决定阈值,不因旧数字自动扩充测试或 CI | +| **B-013** | 发码幂等性是历史边角情况建议 | 先看重复提交的实际影响和频率,未经确认不增加队列/状态机制 | +| **B-019** | Python 与 Rust 的错误 shape 有差异 | 只有具体调用方不兼容才构成修复需求;不为形式一致重做契约 | +| **B-020** | CI 安装 mypy 但未执行;flake8 已是 88 字符硬门禁 | 删除“去掉 mypy/flake8 的 `\|\| true`”旧描述。是否加入类型检查门禁另行决定;本轮未评估 mypy 告警 | +| **B-026** | CI 已在真实 Postgres 应用迁移;未增加 PR model 差异/alembic check 机制 | 更细治理检查仍是建议,新增 CI 工作需按项目规模单独确认 | +| **B-031** | 现有 Nacos 解析器支持 JSON、JS 风格兼容及 Properties | 当前配置写法未核验,不能直接删兼容分支;是否统一格式先由配置维护方决定 | +| **B-033** | legacy token-status 仍由前端 `${API_PREFIX}/user-token-status` 使用 | 兼容层仍有调用方,不能因“legacy”字样直接删除;[兼容说明](migration/legacy-rest-compat.md)记录退出条件 | +| **B-047** | IP→ASN/机房归属是用户明确保留的后续取证方向 | 保持待办,实施前确认数据源、成本及使用场景 | +| **B-049 尾项** | 管理端主体已有实现;历史还留 legacy 面板清理、可选钻取/合并/preview UI | 先核对实际入口及使用情况,再决定清理或补界面,不把“无UI”自动当缺陷 | +| **B-053** | 任意问卷题的 DSL 过滤与回答索引已存在;专用任意轴多分组输出 API/前端尚未提供 | 专用交叉展示是否需要是产品决定,不能再写成“通用问卷筛选全无” | +| **B-055** | connect 占位页此前已审计为无需求;result `/test` 已移除,统一年份和 timeline 日期已接入。Doujin 仍是示例数据,CP compare/evolution 不在现有页面范围 | 不自动补 connect 或 CP 页面;Doujin 是否数据化由运营需要决定,保留现状记录而非阻塞缺陷 | +| **B-056** | 历史哈希迁移保留;本地迁移图为单 head `0022` | 不重命名已执行迁移,不使用旧文档中的“下一编号0016/0018”;新增迁移前重新核对本地链与云端状态 | + +## 本轮已退出开放队列 + +B-028、B-039、B-040、B-041、B-050 主项、B-050-后补2、B-057、B-061、B-063 已移入 [归档](BACKLOG-archive.md),原始描述及本轮判定同时保留。 + +- 候选 ID、后端候选/资源、问卷数组契约已接入,不再安排“从零迁移”。 +- CP 静态作品分类依赖已由前端 `edeaeea` 清理;拼音搜索与唯一 `/autocomplete/search` 入口见后端 `77f43cf`、`44bd972`。 +- B-062 旧 CP 空实现已经随旧建议链路废弃;本轮删除“模块功能缺口”中的重复记录,不将 CP 组合推荐认定为应补功能。 +- scraper 的“无测试”重复记录删除;趋势、DSL、数据库白名单及 attempt 列不再重复列为未实现。 +- B-060/B-065/B-066 的历史完成项已有归档记录,不在活跃清单再次展开。 + +## 后续维护 + +1. 新条目先写清复现/实际使用场景、源码证据及对应需求,区分缺陷、运营事项与可选建议。 +2. 状态变更同步对应主题文档的当前状态;历史正文和旧 checkbox 保留为过程记录,不能据其重新执行迁移、导入或部署。 +3. 结项保留编号与证据后移入归档;接口缺失或界面占位本身不构成需求授权。 +4. 本轮不修改产品代码、测试策略、工作流或真实数据;后续事项按具体需求单独推进。 diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 95f72880..5c91f002 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -5,6 +5,14 @@ > 创建日期:2026-04-27 > **2026-08-31 整理**:合并 9 组重复条目、按日期倒序重排;**2026-07-01 之前**的条目已迁至 [CHANGELOG-archive-2026H1.md](./CHANGELOG-archive-2026H1.md)。 +## [2026-11-08] 历史 BACKLOG 与文档状态核对 + +- **Changed**:按后端 44bd972、前端 edeaeea 核对,9 个已实现/过期条目退出开放队列并保留原始归档;修正“候选/问卷前端待做”“无生产通道”“爬虫无测试”“attempt 未展示”等失实状态。 +- **Changed**:区分实际源码差异、外部/运营事项和按需建议;撤销 connect 必补、结果站旧 test/日期缺口、固定测试门禁等自动排期前提,保留历史对比接线和 monitor 提示等真实残留。 +- **Changed**:同步索引、相关迁移计划/设计的当前状态、计票后补及 CI/CD 说明;证据、未核验范围和边界见 [核对记录](migration/backlog-audit-2026-11-08.md)。 +- **兼容性影响**:仅文档,没有修改接口、功能、测试门禁或工作流;不据旧 checkbox 重跑迁移和部署。 +- **数据迁移 / 配置变更**:无;未核验线上数据、Nacos、依赖告警或部署,不执行回填、重算、发布或依赖升级。 + ## [2026-11-08] 统一 autocomplete 搜索入口(第二阶段) - **Changed**:唯一公开入口收敛到 `POST /api/v1/autocomplete/search`,采用分类/关键词/年度输入及完整 candidate IDs 输出;候选服务归入 `service.py`,DAO 年度参数只在查询时传入。 diff --git a/docs/README.md b/docs/README.md index 2789488d..43ba433c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -20,6 +20,7 @@ | **维护结果趋势时间轴** | [`api/result-timeline.md`](./api/result-timeline.md) —— 快照日期、GraphQL 字段及前后端发布顺序 | | **核对结果统计口径** | [`api/result-statistics.md`](./api/result-statistics.md) —— 部门有效票与逐问卷完成情况 | | **维护详情页人群筛选** | [`api/result-detail-filters.md`](./api/result-detail-filters.md) —— 原约束、目标交集及组合 DSL | +| **核对历史待办是否仍成立** | [`migration/backlog-audit-2026-11-08.md`](migration/backlog-audit-2026-11-08.md) —— 源码、历史需求与外部状态分开判断,避免重复实施 | --- @@ -158,7 +159,7 @@ ### 前端侧设计(`thvote-fe` / `Touhou-Vote` 仓库) -> 这四块的**后端已于 2026-07-14 合入 main,前端侧全部待做**(2026-08-13 确认由我方负责)。 +> 2026-11-08 已核对提交态:B-039/040/041 前端主路径已实现;B-037 主要接入已具备,逐条提示仍有计划差异。下列早期设计用于追溯,不能据旧状态重新排期。见 [核对记录](migration/backlog-audit-2026-11-08.md)。 | 文档 | 对应 | |---|---| @@ -171,7 +172,7 @@ | 文档 | 被谁取代 | |---|---| -| [`2026-05-13-autocomplete-design.md`](./superpowers/specs/2026-05-13-autocomplete-design.md) | 无取代;CP 搜索缺口见 BACKLOG **B-062** | +| [`2026-05-13-autocomplete-design.md`](./superpowers/specs/2026-05-13-autocomplete-design.md) | 已被 [拼音候选搜索](./superpowers/specs/2026-11-08-pinyin-candidate-search-design.md) 取代;B-062 旧空实现随建议链路废弃 | | [`2026-05-13-result-query-design.md`](./superpowers/specs/2026-05-13-result-query-design.md) | 计票部分已由 [`2026-07-18-result-recount-id-based-design.md`](./superpowers/specs/2026-07-18-result-recount-id-based-design.md) 重写取代 | | [`2026-06-07-admin-panel-design.md`](./superpowers/specs/2026-06-07-admin-panel-design.md) | 单文件 Web UI 已由 [`2026-07-18-admin-console-vue-frontend-design.md`](./superpowers/specs/2026-07-18-admin-console-vue-frontend-design.md) 取代 | @@ -180,16 +181,16 @@ ## 实施计划(`superpowers/plans/`) > 本节保留尚需实施或追溯的计划;已执行完毕/废弃的历史计划见 [`archive/superpowers/plans/`](./archive/superpowers/plans/)。具体确认与实施状态见各文档头部。 -> ⚠️ plans 里的 `- [ ]` checkbox **从未被维护过**(BACKLOG **B-057⑤**),不要拿它判断完成度。 +> 历史计划的 checkbox 不保证逐项维护;以文档当前状态、源码和核对记录为准,避免重复实施已完成工作。 | 文档 | 状态 | |---|---| | [`2026-09-06-user-identity-model.md`](./superpowers/plans/2026-09-06-user-identity-model.md) | **已实施**(2026-09-06):`user` + `user_identity` 归一化,migration 0018 | -| [`2026-06-08-security-frontend.md`](./superpowers/plans/2026-06-08-security-frontend.md) | 待实施(B-037 前端) | -| [`2026-06-08-questionnaire-frontend.md`](./superpowers/plans/2026-06-08-questionnaire-frontend.md) | 待实施(B-039 前端) | -| [`2026-06-08-vote-objects-frontend.md`](./superpowers/plans/2026-06-08-vote-objects-frontend.md) | 待实施(B-040 前端) | -| [`2026-06-08-questionnaire-admin-frontend.md`](./superpowers/plans/2026-06-08-questionnaire-admin-frontend.md) | 待实施(B-041 投票前端) | -| [`2026-07-21-work-table-unified.md`](./superpowers/plans/2026-07-21-work-table-unified.md) | **部分实施**:后端主体已合入 main,收尾清单见 BACKLOG **B-057** | +| [`2026-06-08-security-frontend.md`](./superpowers/plans/2026-06-08-security-frontend.md) | 主要接入已实现;逐条提示存在差异,可选功能待决定 | +| [`2026-06-08-questionnaire-frontend.md`](./superpowers/plans/2026-06-08-questionnaire-frontend.md) | 历史方案已被 B-041 数组契约取代;主路径已后端化 | +| [`2026-06-08-vote-objects-frontend.md`](./superpowers/plans/2026-06-08-vote-objects-frontend.md) | 已实现;资源/candidateId/metadata 已消费,CP 收口 edeaeea | +| [`2026-06-08-questionnaire-admin-frontend.md`](./superpowers/plans/2026-06-08-questionnaire-admin-frontend.md) | 已实现;数组契约、提交与回填已有源码消费 | +| [`2026-07-21-work-table-unified.md`](./superpowers/plans/2026-07-21-work-table-unified.md) | **代码收口已具备**:B-057 实现结项,历史数据/接线并入 B-050-后补3 | | [`2026-11-08-pinyin-candidate-search.md`](./superpowers/plans/2026-11-08-pinyin-candidate-search.md) | **已本地实现、未部署**:匹配器 → 后端 API 与缓存 → 前端请求状态 → 三入口替换和依赖清理 | | [`2026-11-08-autocomplete-search-consolidation.md`](./superpowers/plans/2026-11-08-autocomplete-search-consolidation.md) | **已确认、第二阶段**:统一 `/autocomplete/search`、移除旧建议实现,前端输入框改名 | @@ -204,7 +205,7 @@ | [`archive/superpowers/plans/`](./archive/superpowers/plans/) | 25 份已执行完 / 已废弃的实施计划 | | [`archive/superpowers/specs/`](./archive/superpowers/specs/) | 4 份已废弃 / 纯操作性 / 事后记录类设计稿 | | [`archive/superpowers/handoffs/`](./archive/superpowers/handoffs/) | 1 份一次性任务交接记录 | -| [`archive/2026-05-30-refactor-todo.md`](./archive/2026-05-30-refactor-todo.md) | 模块级迁移进度快照(内容已过期;仍成立的缺口已转 B-062 / B-063) | +| [`archive/2026-05-30-refactor-todo.md`](./archive/2026-05-30-refactor-todo.md) | 模块级迁移进度快照(内容已过期;B-062 已废弃、B-063 已补测试,见当前核对记录) | --- diff --git a/docs/architecture/database-schema-management.md b/docs/architecture/database-schema-management.md index 8b9989f7..69f22aa9 100644 --- a/docs/architecture/database-schema-management.md +++ b/docs/architecture/database-schema-management.md @@ -1,5 +1,8 @@ # 数据库 Schema 管理 — 现状与演进路线图 +> 当前核对补记:2026-11-08:当前 CI 已在 Postgres 上应用 Alembic 迁移;PR 模板/model 差异/alembic check 为尚未采用的治理建议,不是新的强制需求。本地静态迁移图 head=0022,云端状态未查;不要使用旧文档中的“下一编号”。 见 [证据记录](../migration/backlog-audit-2026-11-08.md)。 + + > 创建日期:2026-04-27 > 最后更新:2026-05-31(§四 加 `_maybe_baseline_existing_schema` 待删除告警 → B-032) > diff --git a/docs/archive/2026-05-30-refactor-todo.md b/docs/archive/2026-05-30-refactor-todo.md index f4d8bc7f..48b8edec 100644 --- a/docs/archive/2026-05-30-refactor-todo.md +++ b/docs/archive/2026-05-30-refactor-todo.md @@ -1,5 +1,8 @@ # REFACTOR_TODO.md — 重构进度总览 +> 当前核对补记:2026-11-08:B-062 随旧建议链路废弃;B-063 已补关键爬虫测试。本文原始缺口不再作为当前待办,保留迁移时记录。 见 [证据记录](../migration/backlog-audit-2026-11-08.md)。 + + > **归档状态**:已归档 —— 2026-05-30 的模块级迁移进度快照,**内容已过期**(例:表中 `vote_data ✅` 一行所指的模块已于 2026-07-17 作为死代码删除;`查询结果 ✅ 9 端点` 所指实现已于 2026-07-18 由 B-050 计票重写取代)。 > 迁出时经代码复核**仍成立**的两条缺口已迁入 BACKLOG:**B-062**(`search_cps()` 恒空)、**B-063**(scraper 无测试)。 > 模块级现状请改看 [BACKLOG.md](../BACKLOG.md) 与 [CHANGELOG.md](../CHANGELOG.md)。归档于 2026-08-31。 diff --git a/docs/archive/README.md b/docs/archive/README.md index face3c33..fa1ccddd 100644 --- a/docs/archive/README.md +++ b/docs/archive/README.md @@ -18,7 +18,7 @@ | 文档 | 状态 | 说明 | |---|---|---| -| [`2026-05-30-refactor-todo.md`](./2026-05-30-refactor-todo.md) | 已归档 | 2026-05-30 的模块级迁移进度快照;内容已过期。迁出时经代码复核仍成立的两条缺口已转为 BACKLOG **B-062**(`search_cps()` 恒空)与 **B-063**(scraper 无测试) | +| [`2026-05-30-refactor-todo.md`](./2026-05-30-refactor-todo.md) | 已归档 | 2026-05-30 的模块级迁移进度快照;内容已过期。迁出时转入 B-062/B-063;2026-11-08 核对时,前者已随旧建议链路废弃,后者已补关键测试,见 [本轮记录](../migration/backlog-audit-2026-11-08.md) | --- diff --git a/docs/migration/backlog-audit-2026-11-08.md b/docs/migration/backlog-audit-2026-11-08.md new file mode 100644 index 00000000..91eaec66 --- /dev/null +++ b/docs/migration/backlog-audit-2026-11-08.md @@ -0,0 +1,62 @@ +# BACKLOG 与历史状态核对(2026-11-08) + +## 范围与基准 + +本轮针对“历史遗留,实际已实现、已废弃或没有需求”的条目核对源码,并修正 BACKLOG、现役索引与相关主题文档入口。没有实施待办中的功能。 + +- 后端:`feat/pinyin-backend-search`,`44bd972`,包含远端 `origin/main=6d8afc1`。 +- 前端:同名分支,`edeaeea`,包含远端 `origin/dev=ef028e0`。本次 fetch 后两条远端基线未变化。 +- 前端原有 voteDraft、voteData、codegen、LOCAL_DEV 等未提交修改保留,未当成已提交功能计入结论。CP 元数据迁移已经单独提交 `edeaeea`。 +- 未查询线上数据库、Nacos、依赖告警或实际部署;历史文档中的数据值、凭据状态和上线记录不作为本次实时结论。 + +## 退出开放队列的 9 个条目 + +原条目移入 [BACKLOG 归档](../BACKLOG-archive.md),主题保留历史措辞,状态列及补记写明本轮判定。 + +| 编号 | 核对结果 | 当前源码证据 | +|---|---|---| +| B-028 | 同一 workflow 已有手动生产发布通道,“没有 prod 路径”已过时 | `.github/workflows/deploy-test.yml:39` 的 deploy_prod 输入、`:354` deploy-prod job、`:358` 条件及独立生产目标;不以缺少单独 deploy-prod.yml 判缺功能 | +| B-039 | 问卷主路径已经后端驱动,早期固定槽方案由 B-041 数组契约取代 | 前端 `questionnaire/Questionnaire.vue:140,239`、`questionnaire/lib/questionnaireStateV2.ts:22,60,199,254` | +| B-040 | 角色、音乐、CP 候选与资源已经从后端读取 | 前端 `common/lib/voteObjectsDataSource.ts:18,61,80`、角色/音乐 list 模块、CP CharacterSelect 使用共同角色列表 | +| B-041 | 问卷数组、category/order、required、隐藏组、答案提交及回填均有消费 | 前端 `questionnaireStateV2.ts:25,63,159`、`home/components/UserQuestionnaire.vue:54`、`questionnaireV2Parser.ts:72` | +| B-050 主项 | v1 已完成;“后补2/3/5/6仍开放”的集合失实 | trend、DSL 和 DB 白名单已接入;上届对比单独保留 B-050-后补3,不把整个计票工程重新列为待做 | +| B-050-后补2 | append-only 净增量趋势已接到主榜及 DSL 子集 | `src/apps/result/trend.py:21`、`compute_service.py:82,111`、`advanced_search/service.py:220`;历史提交 b230e37 | +| B-057 | 管理端、导入与前端收口已具备;历史数据部分合并到 B-050-后补3 | `src/apps/admin/router.py:827,878`;`voteable_import_service.py:209,299`(60a233e);前端 metadata、candidateId 与专辑名反查,CP edeaeea | +| B-061 | API、DAO 与管理界面已展示 attempt | `src/apps/admin/monitor/schemas.py:48`、`dao.py:158,184`、`admin-ui/src/views/monitor/VotesView.vue:29,136` | +| B-063 | 已有关键解析、URL 路由与限流测试 | `tests/unit/test_scraper_sites.py`、`test_scraper_parse_url.py`、`tests/integration/test_scraper_rate_limit.py`;1559ea0 与 CHANGELOG 2026-10-20。未声称所有站点成功路径均穷尽覆盖 | + +前端路径均位于 `Touhou-Vote/packages/vote/src/`,另有标注的 result 路径除外。源码行号对应本轮基准,后续可能变化。 + +## 不应自动当成功能缺口的记录 + +- **B-055 connect**:结果页仍有占位文件,但入口已注释;旧结果审计 §六已经确认无对应需求。不能因看到“维护中”就安排补页。 +- **B-055 CP compare/evolution**:现有结果站确实只有四个 CP 页面,页面数量与角色/音乐不同本身不是已批准需求。 +- **B-055 Doujin**:当前 `packages/result/src/pages/Doujin.vue:13` 仍有 1272 及示例作品/评论;旧审计允许运营维护。是否数据化留待具体运营需要。 +- **B-055 `/test` 与日期**:当前 result router 已无旧 `/test`;vote 包自己的 TestPage 是另一对象,本轮不转造新待办。结果页已使用统一 voteYear 与后端 timeline,不能继续沿用“20多处 year11/2022 日期”的旧描述。 +- **B-062**:旧建议链路和 CP 空方法已在 44bd972 移除;这表示该历史实现被废弃,不表示新增了 CP 组合搜索。删除 BACKLOG 中未编号的重复记录。 +- **B-010/013/020/026**:覆盖率阈值、幂等性、mypy 和新增 schema 治理检查仍是按场景决定的建议。缺少这些机制不自动证明当前功能有 bug,也不授权扩大测试或 CI。 +- **B-031/056**:配置格式兼容与历史迁移命名需要维护约束,不能直接删除兼容或重命名已执行迁移。本地静态解析迁移图为单 head 0022,云端 Alembic 状态未查询。 +- **GET /server-time**:当前源码未发现该接口;当前业务调用方也未发现相关调用。旧 gateway 曾有此端点不构成必须移植的证据。 + +## 仍存在或只完成一部分的内容 + +| 项目 | 本次确认的边界 | +|---|---| +| B-037 | 主要提名校验响应、待审核提示与问卷门禁已有实现;逐条 index 提示与原计划有差异,现为合并原因/重复数量。可选 approved 展示原本就待产品确认,不自动升级需求 | +| B-050-后补3 | 主榜 `compute_service.py:111` 和子集 `advanced_search/service.py:249` 仍传空 historical,GraphQL `result_compat.py:164` 使用 -1/-1.0。旧 load_historical 已删除;“现有函数按name取值”和“硬编码0”均需撤销。线上历史数据与旧 API 可用性未核验 | +| B-053 | 任意问卷题 DSL 过滤已有回答索引和 QCond;专用任选轴一次输出多个分组的 API/前端尚未提供,是否需要另行决定 | +| B-059 | `nacos.py:357`、`config.py:20` 会 warning,再尝试本地或默认配置;未 fail-fast 属实,“静默无日志”不准确。是否改变启动规则仍需具体决策 | +| monitor 提示 | `_B050_NOTE` 仍声称要等计票重写;实际 `compute_dao.py:41` 已排除作废的最新票。残留问题是提示文案,不是作废能力未接计票 | +| B-033 | 前端 `home/lib/user.ts:190` 仍调用 `${API_PREFIX}/user-token-status`,后端仍挂载 legacy router。不能直接删除兼容层 | + +B-045/046 的前端耗时与 clientEnv 已在角色、音乐、CP、提名提交中传递;问卷 V2 提交仅 voteToken+answers,不能扩成“所有提交入口都一致”的结论。当前部署、真实落库、问卷内容与语义 code、Nacos 开关以及旧依赖告警均保持“未核验”。 + +## 文档处理与验证 + +- BACKLOG 分为源码仍有差异、外部/运营状态、按需建议,取消重复的旧“立即做”和“推荐下一步从零迁移”队列。 +- 相关前端计划/设计、work 统一、计票后补、autocomplete 旧设计增加当前状态;历史正文和 checkbox 只保留追溯用途,不伪装成逐步重新执行。 +- 更新文档索引、旧 refactor-todo 归档入口及结果审计入口,防止“已归档”状态又从另一入口重新出现。 +- CP 改动提交前相关测试 5 passed,ESLint 通过;生产构建在该代码版本通过。文档整理不新增产品测试,不重跑全量测试,也不触发部署、迁移、重算或依赖升级。 +- 文档改动验证使用 `git diff --check`、新增 Markdown 链接目标检查、编号归档一致性检查;原有未提交文件保留。 + +本轮已通过新增 Markdown 链接目标检查、9 项编号唯一归档/移出开放表检查及两仓库 `git diff --check`;后端源码、测试、workflow、迁移和依赖均无改动。 diff --git a/docs/migration/legacy-rest-compat.md b/docs/migration/legacy-rest-compat.md index d9d78fe3..375167f8 100644 --- a/docs/migration/legacy-rest-compat.md +++ b/docs/migration/legacy-rest-compat.md @@ -1,5 +1,8 @@ # Legacy REST 兼容层(旧 Rust gateway 扁平契约) +> 当前核对补记:2026-11-08:当前前端 API_PREFIX 为 /v12-be,home/lib/user.ts 仍调用 /user-token-status,后端仍挂载兼容路由,不能删除。文中 /v11-be、共享产物/上线状态属于 05-31 的历史背景,本轮未核验部署。GET /server-time 未发现当前调用需求,不单凭旧 gateway 曾有便要求移植。 见 [证据记录](backlog-audit-2026-11-08.md)。 + + > 迁移主题文档,按 CLAUDE.md §3 维护:写现状与约束,不只写理想方案。 > 创建:2026-05-31 diff --git a/docs/migration/result-stats-audit-2026-08-14.md b/docs/migration/result-stats-audit-2026-08-14.md index 68e14f6f..b9d5e8e6 100644 --- a/docs/migration/result-stats-audit-2026-08-14.md +++ b/docs/migration/result-stats-audit-2026-08-14.md @@ -1,5 +1,8 @@ # 结果统计层三方审计:前端需求 × Python 后端 × legacy Rust +> 当前核对补记:2026-11-08:DSL、数据库白名单、append-only 净增量趋势已实现;result 已统一年份、读取后端 timeline,旧 /test 路由已无。connect 在本文 §六已确认为无需求,不补页;Doujin 示例数据与 CP 页面范围按需决定。上届对比仍未接线,当前历史数据/旧 API 未核验。下面保留 08-14 时点观察,后续修正优先。 见 [证据记录](backlog-audit-2026-11-08.md)。 + + > 日期:2026-08-14 > 方法:三份并行代码审计(Python `src/apps/result` + GraphQL 契约层 / Touhou-Vote `packages/result` origin/zfq_dev_fe / legacy `thvote-be/result-query` Rust),交叉核实。 > 目的:定位"结果统计/展示层"(区别于计票 compute)从 Rust 迁到 Python 的完整性缺口,及与前端页面需求的匹配度。 diff --git a/docs/operations/cicd-pipeline.md b/docs/operations/cicd-pipeline.md index c65b428e..3dd78bb1 100644 --- a/docs/operations/cicd-pipeline.md +++ b/docs/operations/cicd-pipeline.md @@ -1,217 +1,46 @@ # CI/CD 流水线说明 -> 创建日期:2026-04-27 -> 最后更新:2026-05-31(手动触发 workflow_dispatch 现在会完整部署 + `--force-recreate`,用于改完 Nacos 配置后免 SSH 重启) -> -> 用途:说清当前 GitHub Actions workflow 的职责、触发条件、关键步骤,并记录最近的改动与遗留问题。 -> 关联:[`operations/aliyun-onboarding.md`](./aliyun-onboarding.md)、[`operations/nacos-config-center.md`](./nacos-config-center.md)、[`superpowers/specs/2026-04-27-user-auth-implementation-report.md`](../archive/superpowers/specs/2026-04-27-user-auth-implementation-report.md) +> 创建:2026-04-27。最后核对:2026-11-08,按当前 workflow 源码更新。 +> 本文说明代码中的通道与条件;没有重新验证生产/测试机器、Secrets、Nacos 或实际部署状态,不构成执行发布的授权。 ---- +## 当前流水线 -## 一、Workflow 总览 +仓库使用 [deploy-test.yml](../../.github/workflows/deploy-test.yml) 一个 workflow 管理后端检查、构建和部署。它已有独立 `deploy-prod` job;不需要另有 `deploy-prod.yml` 才算具备生产通道。B-028 原“没有 prod 路径”已结项,见 [BACKLOG 核对记录](../migration/backlog-audit-2026-11-08.md)。 -> ⚠️ **重大变更(2026-05-12)**:原 4 个 workflow(`pylint.yml` / `deploy-test.yml` / `deploy-prod.yml` / `deploy.yml`)被精简为**只剩 1 个** `deploy-test.yml`。同时移除仓库内 `docker/` 目录、`requirements.txt`、Apollo 接入;改用 Nacos 配置中心。 - -| 文件 | 触发 | 作用 | -|---|---|---| -| `.github/workflows/deploy-test.yml` | push 到 `main` / `zfq_dev` + 这些分支的 PR + `workflow_dispatch` | **唯一**部署流水线(lint → test → build-backend → deploy-test → notify) | - -**没有独立的 prod workflow** —— 见 §五 B-028(这是需要确认/补齐的事项)。 - ---- - -## 二、`deploy-test.yml`(当前唯一的部署流水线) - -### 2.1 Job 拓扑 - -``` -lint ──► test ──► build-backend ──► deploy-test ──► notify - (push only) (main 或 zfq_dev 才部署) -``` - -### 2.2 关键步骤 - -| Job | 关键内容 | +| 触发 | 源码行为 | |---|---| -| **lint** | Python 3.12 + flake8(`max-line-length=120`,仍是 `\|\| true` 软门禁 → 见 §五 B-027) | -| **test** | 起 `postgres:15-alpine` + `redis:7-alpine` service container,注入 `DATABASE_URL` / `REDIS_URL` / `JWT_SECRET_KEY` / `VOTE_*_ISO`;先跑 `alembic upgrade head` 把迁移用真 Postgres 烟测一遍,再跑 `pytest --cov=src` | -| **build-backend** | 多阶段 Dockerfile 的 `production` target → 推到 `ghcr.io/patchyvideo/thvote-backend:`;`` 为 `prod`(main 分支)或 `test`(zfq_dev 分支) | -| **deploy-test** | SSH 到测试服务器;`sparse-checkout` 拉部署机本地的 `docker/` 配置;写 `.env` 注入 Nacos 配置;启动 redis container、等 Postgres 就绪;`docker-compose run --rm backend alembic upgrade head` 应用迁移;最后 `docker-compose up -d backend` | -| **notify** | 简单回显成功/失败 | - -### 2.3 部署阶段写入的 `.env` - -CI 阶段从 GitHub Secrets / Variables 拼出来,落到部署机的 `$DEPLOY_DIR/.env`: - -```env -# Nacos 接入(取代原 Apollo) -NACOS_ENABLED=true -NACOS_SERVER_ADDRS=${{ secrets.NACOS_SERVER_ADDRS }} -NACOS_NAMESPACE=${{ secrets.NACOS_NAMESPACE }} -NACOS_GROUP=${{ secrets.NACOS_GROUP || 'DEFAULT_GROUP' }} -NACOS_DATA_ID=thvote-be -NACOS_ACCESS_KEY=${{ secrets.NACOS_ACCESS_KEY }} -NACOS_SECRET_KEY=${{ secrets.NACOS_SECRET_KEY }} - -# 服务注册(让其他服务通过 Nacos naming service 发现本服务) -NACOS_SERVICE_NAME=thvote-be -NACOS_SERVICE_IP=... # 一般用部署机内网 IP -NACOS_SERVICE_PORT=8000 - -# DB(Aliyun RDS,仓库内不再有 postgres 容器编排) -POSTGRES_DB=thvote_test -POSTGRES_USER=thvote_test -POSTGRES_PASSWORD=${{ secrets.TEST_DB_PASSWORD }} - -# JWT -JWT_SECRET_KEY=${{ secrets.TEST_JWT_SECRET || 'dev-secret' }} - -# 镜像 -BACKEND_IMAGE=ghcr.io/patchyvideo/thvote-backend:test -``` +| push 到 main/zfq_dev,命中 paths | lint → test → build-backend → deploy-test | +| 针对上述分支的 PR | lint、test;build-backend 限 push/workflow_dispatch,不发布 | +| workflow_dispatch | 可用 skip_tests 跳过 test;lint 成功后构建并部署测试环境 | +| workflow_dispatch 且 deploy_prod=true | build-backend 与 deploy-test 成功后再执行 deploy-prod,复用同一镜像 digest | -`ALIYUN_PNVS_*` / `ALIYUN_DM_*` **不在 `.env` 里**——它们由 Nacos 配置中心提供,详见 §四 与 `operations/nacos-config-center.md`。 +`zfq_dev` 属合作者分支,仍遵守工作区只读约定。本文记录触发器,不授权修改或推送该分支。 -### 2.4 镜像 tag 规则 +## 检查、镜像与部署职责 -`BACKEND_TAG = main 分支 ? 'prod' : 'test'`: - -- push 到 `main` → 推 `ghcr.io/patchyvideo/thvote-backend:prod` -- push 到 `zfq_dev` → 推 `ghcr.io/patchyvideo/thvote-backend:test` - -⚠️ 但**部署目标始终是 TEST_SERVER_HOST**(即使 tag 是 `prod`)。要么是历史遗留,要么 prod 部署其他途径完成 → B-028 待确认。 - ---- - -## 三、与部署机的耦合 - -仓库内不再维护 `docker/docker-compose*.yml`,但 deploy job 仍调用: - -- `docker-compose up -d redis` -- `docker exec thvote-postgres pg_isready ...`(不要被名字误导:实际指向阿里云 RDS 还是本地 container,取决于部署机的 compose) -- `docker-compose run --rm backend alembic upgrade head`(对任何状态的 DB 都幂等——`env.py` 会自动 baseline 祖传 schema,详见 `architecture/database-schema-management.md`) -- `docker-compose up -d backend` - -这些 `docker-compose` 命令读取的是**部署服务器上 `$DEPLOY_DIR` 目录里手工维护的 compose 文件**——不在仓库版本控制中。 - -**含义:** -- 仓库 push 不会带 compose 改动到部署机 -- compose 文件谁来改、谁来同步是部署机维护者的责任 -- 这是有意识的解耦(让生产敏感配置不进 git),但需要文档化 → 见 §五 B-029 - ---- - -## 四、配置交付路径(Nacos) - -代码读取顺序: -``` -环境变量 / .env → Nacos 配置中心(src/common/nacos.py:load_nacos_config) → Settings() 实例化(src/common/config.py) -``` - -> ⚠️ Nacos 加载发生在 **import time**:`src/common/config.py:46` 顶层调用 `_load_nacos_sync()`,会在 import 期阻塞做网络请求 → Nacos 故障会让全部 import 链挂掉。见 BACKLOG B-030。 - -**`ALIYUN_PNVS_*` 与 `ALIYUN_DM_*` 17 个字段**应写到 Nacos 配置中(`DATA_ID=thvote-be`,`GROUP=DEFAULT_GROUP` 或自定义): - -| Key(环境变量风格) | 值来源 | +| Job | 当前代码 | |---|---| -| `ALIYUN_PNVS_ACCESS_KEY_ID` | RAM 子账号 | -| `ALIYUN_PNVS_ACCESS_KEY_SECRET` | RAM 子账号 | -| `ALIYUN_PNVS_ENDPOINT` | `dypnsapi.aliyuncs.com` | -| `ALIYUN_PNVS_REGION_ID` | `cn-hangzhou` | -| `ALIYUN_PNVS_SCHEME_NAME` | 阿里云控制台「认证方案管理」 | -| `ALIYUN_PNVS_SMS_SIGN_NAME` | 系统赠送签名 | -| `ALIYUN_PNVS_SMS_TEMPLATE_CODE` | 系统赠送模板 | -| `ALIYUN_PNVS_CODE_LENGTH` | `6` | -| `ALIYUN_PNVS_VALID_TIME` | `300` | -| `ALIYUN_PNVS_INTERVAL` | `120` | -| `ALIYUN_DM_ACCOUNT_NAME` | `noreply@` | -| `ALIYUN_DM_FROM_ALIAS` | `THVote` | -| `ALIYUN_DM_TAG_NAME` | (可选) | -| `ALIYUN_DM_SMTP_HOST` | `smtpdm.aliyun.com` | -| `ALIYUN_DM_SMTP_PORT` | `465` | -| `ALIYUN_DM_SMTP_USERNAME` | 同 `ACCOUNT_NAME` | -| `ALIYUN_DM_SMTP_PASSWORD` | 阿里云控制台单独设置 | - -具体接入步骤见 [`aliyun-onboarding.md`](./aliyun-onboarding.md);Nacos 自身的配置写法见 [`nacos-config-center.md`](./nacos-config-center.md)。 - -> ⚠️ 不要把 `*_ACCESS_KEY_SECRET` 与 `*_SMTP_PASSWORD` 写进仓库内的 `.env.test.example` / `.env.prod.example`,必须放 Nacos 加密命名空间或 GitHub Secrets。CLAUDE.md §5 强制要求。 - ---- - -## 五、Follow-up(仍待处理) - -> 🎯 全部 follow-up 在 [`docs/BACKLOG.md`](../BACKLOG.md) 里有对应编号。本表保留 CI/CD 视角的细节。 - -| 编号 | 项目 | 优先级 | -|---|---|---| -| **B-027** | `pylint.yml` 已删除;剩下 `deploy-test.yml` 内 `flake8 \|\| true` 软门禁仍需改硬失败 | 中 | -| **B-028** | 没有独立 prod workflow——main push 也只走 `deploy-test.yml` 部署到 TEST_SERVER_HOST。要么补 `deploy-prod.yml`,要么确认 prod 通过其他方式(手工 / Nacos 控制) | **高** | -| **B-029** | 部署机上 `docker-compose.yml` 不在仓库——归属、版本管理、敏感字段处理需文档化 | 中 | -| **B-030** | Nacos import-time 阻塞加载——改成 lazy 或加超时熔断 | 中 | -| **B-031** | Nacos `_parse_config_content` 的 JS 风格 JSON 容错解析是隐式技术债 | 低 | -| **F-cicd-3** | `init_db()` + Alembic 并存。**已修复(2026-04-27)**:`src/main.py` 现在仅在 `DEBUG=true` 时调 `init_db()` | ✅ 已完成 | -| **B-025** | 移除 `init_db()` 后门彻底改 `ensure_schema_ready()`(B-001 已完成,阻塞解除) | 中 | -| **B-010** | 测试覆盖率切到 `fail_under=80` | 低 | - -### 5.1 已删除的历史 workflow(仅做归档) - -| 文件 | 删除时间 | 原因 | -|---|---|---| -| `.github/workflows/deploy-prod.yml` | 2026-05-12 合入 zfq_dev | 与 Apollo / 仓库内 docker-compose 强耦合,新部署模型不复用 | -| `.github/workflows/deploy.yml` | 2026-05-12 合入 zfq_dev | 同上;功能与 deploy-test.yml 重叠 | -| `.github/workflows/pylint.yml` | 2026-05-12 合入 zfq_dev | 软门禁 `--exit-zero` 永不失败,与 deploy-test.yml 的 lint job 重复 | - -如需恢复 prod workflow,应基于当前 `deploy-test.yml` + Nacos 模型重写,**不要**回滚到 Apollo 版本。 - ---- - -## 六、触发约定 - -### 6.1 测试环境部署 - -push 到 `main` 或 `zfq_dev`(或对这两个分支开 PR)→ 自动触发 `deploy-test.yml` 完整流水线。 - -push 触发只在改动以下路径时生效: -- `src/**`、`pyproject.toml`、`Dockerfile`、`scripts/**`、`docker/**`(已删但触发器仍写着,无害)、`.github/workflows/deploy-test.yml` - -PR 触发:上述分支的 PR 都会跑 lint+test+build,但 **不会** 触发 deploy-test job(job 内 `if` 限制为 push 事件)。 - -### 6.2 手动触发 - -`workflow_dispatch` 输入:`skip_tests: false/true`。 - -**2026-05-31 起:手动触发现在会完整跑 build-backend + deploy-test**(之前 deploy-test 仅限 push 事件,手动触发只跑 lint+test)。deploy 步骤用 `docker-compose up -d --force-recreate backend`,**即使镜像未变也会重建容器**。 - -主要用途:**改完 Nacos 配置后,在 Actions 点 "Run workflow" 即可让配置生效**(容器重启→重新读 Nacos),不必 SSH 上服务器 `docker restart`。注意 `--force-recreate` 配合 `skip_tests`:救火时可勾 `skip_tests=true` 跳过测试直接重建。 - -### 6.3 生产环境部署 - -**当前缺失。** B-028 待办。 - -如需立刻发 prod: -- 选项 A:手动 `docker pull ghcr.io/patchyvideo/thvote-backend:prod` 到 prod 机后手工 `docker-compose up` -- 选项 B:通过 Nacos 改 `DATA_ID=thvote-be` 让运行中的实例热加载(仅限非 schema 变更) - ---- - -## 七、最近改动(2026-05-12 合入 zfq_dev) - -| 改动 | 落点 | -|---|---| -| 删除 `pylint.yml` / `deploy-prod.yml` / `deploy.yml` | 不再仓内 | -| Apollo 集成(`src/common/apollo.py`)→ Nacos(`src/common/nacos.py`,812 行,含配置中心 + naming service) | `src/common/` | -| `requirements.txt` 移除,依赖收敛到 `pyproject.toml` | 根目录 | -| `docker/` 目录完全删除(compose / apollo SQL / bootstrap 脚本全部移除) | 不再仓内 | -| 本地 Postgres 容器移除,依赖阿里云 RDS | 部署机维护 | -| 健康检查增加异常处理,DB 不可用返回降级状态而非失败 | `src/main.py` `/health` | -| 启动期 Nacos 加载有本地文件回退 | `src/common/nacos.py` | - -## 八、历史改动(2026-04-27 用户与认证 PR) - -| 改动 | 落点 | -|---|---| -| test job 在 pytest 之前跑 `alembic upgrade head` | `.github/workflows/deploy-test.yml` | -| Dockerfile development + production stage 都 `COPY alembic/` 与 `alembic.ini` | `Dockerfile` | -| deploy 步骤加 `docker-compose run --rm backend alembic upgrade head` | `deploy-test.yml`(已删 workflow 不再适用) | - -提交:`feat(ci): wire alembic upgrade head into test and deploy stages` 及合入 zfq_dev 后的 workflow 删除。 +| lint | Python 3.12;安装 flake8/black/isort/mypy,实际只执行 `flake8 src/ --max-line-length=88`,为硬失败。未运行 mypy;不再描述为 `\|\| true` 软门禁 | +| test | Postgres 15 与 Redis 7 服务;应用 `alembic upgrade head` 并查看 current 后,运行带覆盖率的 pytest。未设置固定 fail_under=80 门禁 | +| build-backend | 构建后端 production 镜像,输出 tag 与 digest;main 使用 prod 标签,其他分支使用 test 标签。标签本身不触发生产 job | +| deploy-test | 使用测试目标和 Nacos 配置;先执行迁移,再重建 backend。实际环境及状态本轮未核验 | +| deploy-prod | 仅手动 deploy_prod=true;使用独立 PROD_SERVER_* 与 PROD_SERVER_DIR,默认目录 `/opt/thvote/prod`,同样先迁移后重建;不能与测试目标混称 | +| notify | 当前依赖 deploy-test 的通知;不据此推断生产发布完成 | + +push 的路径过滤包含 `src/**`、`alembic/**`、`pyproject.toml`、`Dockerfile`、`scripts/**`、`docker/**` 与 workflow 本身;仅文档变化不触发 push 发布路径。 + +## 配置与操作边界 + +- Nacos 配置由既有 GitHub Secrets/Variables 和部署配置交付;workflow 使用 dataId `thvote_be`。不要照早期文档中的 `thvote-be` 示例直接覆盖实际配置。 +- 生产与测试使用各自 namespace/部署目录;具体值以受控配置为准,不在文档中保存明文认证值。 +- 后端改配置仍需按现有启动/重建流程生效;实际部署必须遵循项目 AGENTS 的服务器约束及用户当前授权,不据本页自动执行。 +- 本 workflow 只负责后端。Touhou-Vote 前端由独立仓库流水线处理,不能用后端状态推断前端已发布。 + +## 历史跟踪项的处理 + +- B-027 旧 flake8 软门禁已不存在;B-028 生产通道已有代码。 +- B-020 事实是“安装 mypy 但未执行”;是否加入门禁由实际需求决定。 +- B-026 更细的 model-diff/alembic check 仍为治理建议,不能把缺少可选检查描述成当前迁移完全无检查。 +- B-031 仍有配置格式兼容解析;当前配置写法未核验,不直接删除兼容。 +- 旧 B-025/029/030 等过程记录保留在历史提交和 BACKLOG 归档,不从过期 checklist 重新安排工作。 +- 2026-05-12 删除过独立的 deploy-prod.yml/deploy.yml/pylint.yml,属于历史文件收敛;2026-10-29 在现有 workflow 内加入生产 job,已取代“需要恢复旧 prod 文件”的建议。 diff --git a/docs/operations/nacos-config-center.md b/docs/operations/nacos-config-center.md index 07b2f465..2b612711 100644 --- a/docs/operations/nacos-config-center.md +++ b/docs/operations/nacos-config-center.md @@ -1,5 +1,8 @@ # Nacos 配置中心 + 服务注册接入说明 +> 当前核对补记:2026-11-08 源码核对:拉取失败会记 warning,再尝试本地配置并可能回退默认值;“完全无日志的静默回退”不准确。历史事故事实保留,是否改为 fail-fast 另行决定,本次未改配置或启动行为。 见 [证据记录](../migration/backlog-audit-2026-11-08.md)。 + + > 创建日期:2026-05-12 > 最后更新:2026-05-30(补 §四 R-NACOS 双控制台访问方式;注明测试 dataId 为 thvote_be) > diff --git a/docs/superpowers/plans/2026-06-08-questionnaire-admin-frontend.md b/docs/superpowers/plans/2026-06-08-questionnaire-admin-frontend.md index 0a1eb9d8..a48b5af3 100644 --- a/docs/superpowers/plans/2026-06-08-questionnaire-admin-frontend.md +++ b/docs/superpowers/plans/2026-06-08-questionnaire-admin-frontend.md @@ -1,5 +1,9 @@ # 问卷契约变更 — 投票前端(thvote-fe)Implementation Plan +> 当前状态(2026-11-08 源码核对):前端已消费问卷数组、category/order、required、隐藏组以及结构化答案提交/回填;题库内容和部署/真人验收本次未核验。 +> 本文后续为原始设计/实施记录;旧状态与 checkbox 不代表当前待办。证据见 [BACKLOG 核对记录](../../migration/backlog-audit-2026-11-08.md)。 + + > **For agentic workers:** 前端 Vue 3 monorepo,手工验收为主。**一次性切换**,后端结构端点(数组契约)+ submitPaperV2 先合并并录入题库。 > 仓库:`D:\personal\thvote-fe`,包:`packages/vote` > 前置:后端 B-041 合并(structure 数组契约 + 扁平答案数组)。 diff --git a/docs/superpowers/plans/2026-06-08-questionnaire-frontend.md b/docs/superpowers/plans/2026-06-08-questionnaire-frontend.md index 18367498..03b88d42 100644 --- a/docs/superpowers/plans/2026-06-08-questionnaire-frontend.md +++ b/docs/superpowers/plans/2026-06-08-questionnaire-frontend.md @@ -1,5 +1,9 @@ # Block 3A 问卷结构化系统 — 前端(thvote-fe)Implementation Plan +> 当前状态(2026-11-08 源码核对):问卷主路径已使用后端 V2;本旧固定槽/按年度方案已由 questionnaire-admin-frontend 的数组契约取代,不再按旧步骤迁移。 +> 本文后续为原始设计/实施记录;旧状态与 checkbox 不代表当前待办。证据见 [BACKLOG 核对记录](../../migration/backlog-audit-2026-11-08.md)。 + + > **For agentic workers:** 前端 Vue 3,手工验收为主。**一次性切换**,务必后端 structure/submitPaperV2 先合并并灌入题库。 > 仓库:`D:\personal\thvote-fe`,包:`packages/vote` > 前置:后端 3A 合并 + `/admin/questionnaire/import` 已灌入现有题库。 diff --git a/docs/superpowers/plans/2026-06-08-security-frontend.md b/docs/superpowers/plans/2026-06-08-security-frontend.md index b1e2b2d5..29a715fc 100644 --- a/docs/superpowers/plans/2026-06-08-security-frontend.md +++ b/docs/superpowers/plans/2026-06-08-security-frontend.md @@ -1,5 +1,9 @@ # Block 1 安全 — 前端(thvote-fe)Implementation Plan +> 当前状态(2026-11-08 源码核对):主要前端接入已有实现;逐条 index 提示仍有展示差异,可选已通过列表仍需产品决定。部署/真人验收本次未核验。 +> 本文后续为原始设计/实施记录;旧状态与 checkbox 不代表当前待办。证据见 [BACKLOG 核对记录](../../migration/backlog-audit-2026-11-08.md)。 + + > **For agentic workers:** 前端为 Vue 3 monorepo,以手工验收为主。本计划描述改动点与验收清单,代码以仓库现有 `.vue` 模式为准。 > 仓库:`D:\personal\thvote-fe`,包:`packages/vote` > 配套:后端 plan `2026-06-08-security-backend.md` 必须**先合并**(前端依赖新 SDL + 错误码)。 diff --git a/docs/superpowers/plans/2026-06-08-vote-objects-frontend.md b/docs/superpowers/plans/2026-06-08-vote-objects-frontend.md index d35ff97b..93815b3a 100644 --- a/docs/superpowers/plans/2026-06-08-vote-objects-frontend.md +++ b/docs/superpowers/plans/2026-06-08-vote-objects-frontend.md @@ -1,5 +1,9 @@ # Block 3B 投票对象迁后端 — 前端(thvote-fe)Implementation Plan +> 当前状态(2026-11-08 源码核对):角色/音乐/CP 已使用后端候选与资源,candidateId 和 metadata 已接入;响应契约以后续 work 统一和资源后端化实现为准,CP 分类依赖由前端 edeaeea 收口。 +> 本文后续为原始设计/实施记录;旧状态与 checkbox 不代表当前待办。证据见 [BACKLOG 核对记录](../../migration/backlog-audit-2026-11-08.md)。 + + > **For agentic workers:** 前端 Vue 3,手工验收为主。**一次性切换**,后端 `/vote-objects/characters|music` 先合并。 > 仓库:`D:\personal\thvote-fe`,包:`packages/vote` > 前置:后端 3B 合并 + 候选数据导入(含自动合并)。 diff --git a/docs/superpowers/plans/2026-07-21-work-table-unified.md b/docs/superpowers/plans/2026-07-21-work-table-unified.md index 98680187..790f64d1 100644 --- a/docs/superpowers/plans/2026-07-21-work-table-unified.md +++ b/docs/superpowers/plans/2026-07-21-work-table-unified.md @@ -1,5 +1,9 @@ # Work 表 + 前后端统一 — 实现计划 +> 当前状态(2026-11-08 源码核对):管理列表/归属编辑与按名称匹配/自动创建 work 已实现;前端 Task6–9、candidateId 与 CP metadata 已接通。历史榜单导入并入 B-050-后补3;不重新执行旧迁移。 +> 本文后续为原始设计/实施记录;旧状态与 checkbox 不代表当前待办。证据见 [BACKLOG 核对记录](../../migration/backlog-audit-2026-11-08.md)。 + + > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** 新增 unified `work` 表,voteable 用 work_id FK 替代 origin/album,前后端同步适配 API 契约。 diff --git a/docs/superpowers/specs/2026-04-27-user-auth-open-issues.md b/docs/superpowers/specs/2026-04-27-user-auth-open-issues.md index 0e76f163..2bc61d93 100644 --- a/docs/superpowers/specs/2026-04-27-user-auth-open-issues.md +++ b/docs/superpowers/specs/2026-04-27-user-auth-open-issues.md @@ -1,5 +1,8 @@ # 用户与认证模块 — 已知问题与待办 +> 当前核对补记:2026-11-08:U-12 的现状是 CI 安装 mypy 但未执行,flake8 已是 max-line-length=88 硬门禁;旧软门禁描述不再成立。是否追加类型门禁仍是待确认建议。 见 [证据记录](../../migration/backlog-audit-2026-11-08.md)。 + + > **状态**:部分实施 —— [CHANGELOG 2026-04-27](../../CHANGELOG.md) 的 Fixed 小节记录 U-1/U-4/U-V1/U-16/U-17/U-19 已修复上线;但 U-11/U-12/U-14/U-15/U-18 仍在 [BACKLOG.md](../../BACKLOG.md) 以 B-019/B-020/B-022/B-023/B-024 开放。 > 本文件是**设计稿**,记录当时的设计意图与取舍;实现细节可能已演进。状态核对于 2026-08-31。 diff --git a/docs/superpowers/specs/2026-05-13-autocomplete-design.md b/docs/superpowers/specs/2026-05-13-autocomplete-design.md index 6eea1dcc..01893b86 100644 --- a/docs/superpowers/specs/2026-05-13-autocomplete-design.md +++ b/docs/superpowers/specs/2026-05-13-autocomplete-design.md @@ -1,7 +1,7 @@ # Autocomplete 模块设计规格 -> **状态**:已实施 —— `search_characters`/`search_music` 已按本设计实现(`src/apps/autocomplete/dao.py`);`search_cps()` 按设计明确不实现,现状仍 `return []`,与设计范围一致([BACKLOG.md](../../BACKLOG.md)「模块功能缺口」把 CP 补全列为本设计之外的独立后续项)。 -> 本文件是**设计稿**,记录当时的设计意图与取舍;实现细节可能已演进。状态核对于 2026-08-31。 +> **状态(2026-11-08)**:本 ILIKE 建议契约已被 [拼音候选搜索](2026-11-08-pinyin-candidate-search-design.md) 取代;唯一 `/autocomplete/search` 返回完整 candidate IDs。旧 service/schema/ILIKE 查询与 `search_cps()` 已移除(44bd972),B-062 按废弃归档,未新增 CP 组合推荐。 +> 下文是历史设计,不代表当前接口,不作为待实现需求。 > 创建日期:2026-05-13 > 最后更新:2026-05-13 diff --git a/docs/superpowers/specs/2026-06-08-questionnaire-admin-frontend-design.md b/docs/superpowers/specs/2026-06-08-questionnaire-admin-frontend-design.md index 33f225df..4f92adfc 100644 --- a/docs/superpowers/specs/2026-06-08-questionnaire-admin-frontend-design.md +++ b/docs/superpowers/specs/2026-06-08-questionnaire-admin-frontend-design.md @@ -1,5 +1,9 @@ # 问卷契约变更 — 投票前端设计稿(thvote-fe) +> 当前状态(2026-11-08 源码核对):前端已消费问卷数组、category/order、required、隐藏组以及结构化答案提交/回填;题库内容和部署/真人验收本次未核验。 +> 本文后续为原始设计/实施记录;旧状态与 checkbox 不代表当前待办。证据见 [BACKLOG 核对记录](../../migration/backlog-audit-2026-11-08.md)。 + + > **状态**:部分实施 —— 配套后端 B-041 已于 2026-07-14 合并 `main`(见 [BACKLOG](../../BACKLOG.md) B-041、[CHANGELOG](../../CHANGELOG.md) 2026-07-14 条目),但本文件描述的投票前端(thvote-fe)改造仍未开始,见 [BACKLOG](../../BACKLOG.md)「前端队列」第 4 项「B-041 问卷前端消费数组契约」。 > 本文件是**设计稿**,记录当时的设计意图与取舍;实现细节可能已演进。状态核对于 2026-08-31。 diff --git a/docs/superpowers/specs/2026-06-08-questionnaire-frontend-design.md b/docs/superpowers/specs/2026-06-08-questionnaire-frontend-design.md index 63f548b3..5d7911f4 100644 --- a/docs/superpowers/specs/2026-06-08-questionnaire-frontend-design.md +++ b/docs/superpowers/specs/2026-06-08-questionnaire-frontend-design.md @@ -1,5 +1,9 @@ # Block 3A 问卷结构化系统 — 前端设计稿(thvote-fe) +> 当前状态(2026-11-08 源码核对):问卷主路径已使用后端 V2;本旧固定槽/按年度方案已由 questionnaire-admin-frontend 的数组契约取代,不再按旧步骤迁移。 +> 本文后续为原始设计/实施记录;旧状态与 checkbox 不代表当前待办。证据见 [BACKLOG 核对记录](../../migration/backlog-audit-2026-11-08.md)。 + + > **状态**:部分实施 —— 配套后端 B-039 已于 2026-07-14 合并 `main`,但本文件针对的「固定 8 槽 + questionnaireV2 静态结构」前端契约已被 [`2026-06-08-questionnaire-admin-frontend-design.md`](./2026-06-08-questionnaire-admin-frontend-design.md)(B-041 数组契约)取代,且无论哪版方案,投票前端的实际切换均仍开放,见 [BACKLOG](../../BACKLOG.md)「前端队列」第 2/4 项。 > 本文件是**设计稿**,记录当时的设计意图与取舍;实现细节可能已演进。状态核对于 2026-08-31。 diff --git a/docs/superpowers/specs/2026-06-08-security-frontend-design.md b/docs/superpowers/specs/2026-06-08-security-frontend-design.md index 3c1dded3..f98c2beb 100644 --- a/docs/superpowers/specs/2026-06-08-security-frontend-design.md +++ b/docs/superpowers/specs/2026-06-08-security-frontend-design.md @@ -1,5 +1,9 @@ # Block 1 安全 — 前端设计稿(thvote-fe) +> 当前状态(2026-11-08 源码核对):主要前端接入已有实现;逐条 index 提示仍有展示差异,可选已通过列表仍需产品决定。部署/真人验收本次未核验。 +> 本文后续为原始设计/实施记录;旧状态与 checkbox 不代表当前待办。证据见 [BACKLOG 核对记录](../../migration/backlog-audit-2026-11-08.md)。 + + > **状态**:部分实施 —— 配套后端 B-037 已于 2026-07-14 合并 `main`,但本文件描述的投票前端(提名结果提示/问卷门禁错误处理)改造仍未开始,见 [BACKLOG](../../BACKLOG.md)「前端队列」第 5 项「B-037 安全块前端」。 > 本文件是**设计稿**,记录当时的设计意图与取舍;实现细节可能已演进。状态核对于 2026-08-31。 diff --git a/docs/superpowers/specs/2026-06-08-vote-objects-frontend-design.md b/docs/superpowers/specs/2026-06-08-vote-objects-frontend-design.md index 574556ac..aa1204b0 100644 --- a/docs/superpowers/specs/2026-06-08-vote-objects-frontend-design.md +++ b/docs/superpowers/specs/2026-06-08-vote-objects-frontend-design.md @@ -1,5 +1,9 @@ # Block 3B 投票对象迁后端 — 前端设计稿(thvote-fe) +> 当前状态(2026-11-08 源码核对):角色/音乐/CP 已使用后端候选与资源,candidateId 和 metadata 已接入;响应契约以后续 work 统一和资源后端化实现为准,CP 分类依赖由前端 edeaeea 收口。 +> 本文后续为原始设计/实施记录;旧状态与 checkbox 不代表当前待办。证据见 [BACKLOG 核对记录](../../migration/backlog-audit-2026-11-08.md)。 + + > **状态**:部分实施 —— 配套后端 B-040 已于 2026-07-14 合并 `main`,但本文件描述的角色/音乐/CP 投票前端改拉后端 `/vote-objects/*` 仍未开始,见 [BACKLOG](../../BACKLOG.md)「前端队列」第 3 项「B-040 角色/音乐/CP 投票对象改拉后端」。 > 本文件是**设计稿**,记录当时的设计意图与取舍;实现细节可能已演进。状态核对于 2026-08-31。 diff --git a/docs/superpowers/specs/2026-07-18-result-recount-id-based-design.md b/docs/superpowers/specs/2026-07-18-result-recount-id-based-design.md index 89378acf..34a727aa 100644 --- a/docs/superpowers/specs/2026-07-18-result-recount-id-based-design.md +++ b/docs/superpowers/specs/2026-07-18-result-recount-id-based-design.md @@ -145,9 +145,9 @@ - `src/apps/result/compute_service.py`:接线——`compute_all` 依次 `load_*_votes` → `load_whitelist("character"|"music")` → `compute_ranking`/`compute_cp_ranking` → 写 Redis,替换掉原先读死表 + 走 `CandidateMeta` 元数据的旧管线。 - `src/apps/result/schemas.py`:`RankingEntity` 加 `id: Optional[str] = None`、`favorite_percentage_of_all: float = 0.0`,与上述 compute 输出对齐。 -### 9.2 白名单快照重新提取步骤(前端列表变更时) +### 9.2 历史白名单快照步骤(已停止作为生产步骤) -前端 `Touhou-Vote` 的 `character.ts`/`music.ts` 每次增删角色/曲目/改 `system_id` 顺序后,需要重新生成快照并提交: +当前生产计票使用 `load_whitelist_db`。以下命令仅为 v1 历史步骤,不再要求前端列表变动后重新提取,不执行生产回填: ```bash node scripts/extract_whitelist.mjs /data/sunyunbo/www/Touhou-Vote /data/sunyunbo/www/Thvote-be/thvote-be-re @@ -165,14 +165,13 @@ node scripts/extract_whitelist.mjs /data/sunyunbo/www/Touhou-Vote /data/sunyunbo - **CP 组合票数 == 1 不计入**排名与 `global_stats`(`all_keys = [k for k in vote_count if vote_count[k] >= 2]`)。 - **计票取每 vote_id 最新、排除 invalidated**:`ComputeDAO._latest_per_vote` 对同一账号的多次提交只留最新一条(`created_at` 为主、`attempt` 兜底),`invalidated=true`(B-049 管理端作废标记)的行在取最新之前就被过滤,不参与去重比较。 -### 9.4 v1 明确后补(未做) - -以下项目在设计稿 §8.4 已列为后补,v1 未实现,GraphQL/REST 对应字段暂不产出或喂空值: - -- **性别男女票**:`compute_ranking` 里 `male_vote_count`/`female_vote_count` 依赖 `compute_gender_map`,该函数需要 `raw_paper`(问卷)按性别题 `q11011` join 每个 `vote_id`;v1 的 `load_questionnaire_votes` 读的是旧 `Questionnaire` 死模型的空表,故性别恒为 `unknown`,统计结果恒 0。**需切到 `raw_paper` 才能出真实性别票**。 -- **trend 演进**:`raw_*` 各表当前是"改票即覆盖"式存储(`_upsert` 只留最新一条,详见 B-045 CHANGELOG),没有保留历史提交行;而 trend 需要画"随时间推移的新增/累计"曲线,要求**逐次提交都留痕(append-only)**。现有 `compute_ranking`/`compute_cp_ranking` 里的 `trend`/`trend_first` 字段基于的是"取最新那一条的 `created_at`"分桶,**不是**真实的历史演进(改票会让旧的 hour bucket 计数消失),这是已知的近似值而非目标口径——真正复刻需要先把 `raw_*` 改造成 append-only 存储,记入 B-050 后补项而非本次交付范围。 -- **上届对比**:需要历史 `final_ranking` 表(`FinalRanking` 模型,`compute_dao.load_historical`)有上一/上上届数据;测试库目前该表为空,且 `load_historical` 的 key 是 name(而非 id),与本次 id-based 归票路径尚未对齐,v1 未接线(`compute_ranking` 签名保留了 `historical: dict[str, dict]` 参数,但 `compute_service.py` 传入的是空 `{}`)。 -- **问卷结果页**:`compute_paper_results` 仍是占位实现,读的是死表 `Questionnaire`;真实问卷统计需要 B-039 结构化问卷表(`raw_paper`/`paper_answer`)接入,本次不动。 -- **高级搜索、candidate 表迁移 `object_id`**:均按设计稿 §四"非目标"/§8.4"后补"处理,v1 未涉及。 +### 9.4 后补项的当前状态(2026-11-08) +本节替换早期“全部未做”的状态快照,证据见 [核对记录](../../migration/backlog-audit-2026-11-08.md)。不据旧数据库快照推断当前数据或统计值。 +- 性别/问卷统计:已有后续实现与归档记录,不再把读取死表或占位统计当当前状态;题库、code 和实际统计值未查库。 +- trend:append-only 与净增量已接入主榜及 DSL 子集,B-050-后补2 结项。 +- 上届对比:仍未接线;主榜与子集传空 historical,输出 -1/-1.0,见 B-050-后补3。旧 load_historical 已删除,不再按旧函数名安排改造;旧 API 可用性与真实历史数据未核验。 +- 高级搜索:DSL、任意问卷题回答索引与子集重算已实现,后补5 已归档。 +- DB 白名单:已从 candidate/voteable/work 加载,不依赖重新提取前端静态表,后补6 已归档。 +- attempt 管理列:API、DAO 和 UI 已存在,B-061 结项。 diff --git a/docs/superpowers/specs/2026-07-21-work-table-unified-design.md b/docs/superpowers/specs/2026-07-21-work-table-unified-design.md index a60e03fd..8be4eb89 100644 --- a/docs/superpowers/specs/2026-07-21-work-table-unified-design.md +++ b/docs/superpowers/specs/2026-07-21-work-table-unified-design.md @@ -1,7 +1,7 @@ # Work 表 + 前后端统一设计 -> **状态**:部分实施 —— 后端主体(work 表+种子/voteable 重构/新 vote-objects 契约/admin works CRUD+WorksView/前端 Task 6-7)已于 2026-07-23 合入 main;原文所记 `GET /admin/voteables`(404) 缺口已由 [B-057①](../../BACKLOG.md) 于 2026-08-22 补齐,提交侧切 candidateId 已于 2026-08-14 完成端到端验证;仍开放:B-057②(import 按 name 匹配自动建 work)、B-057③(上届 final_ranking(year=11) 导入)、前端 Task 8/9(B-057④,见 [BACKLOG](../../BACKLOG.md))。 -> 本文件是**设计稿**,记录当时的设计意图与取舍;实现细节可能已演进。状态核对于 2026-08-31。 +> **状态(2026-11-08)**:代码收口已具备。管理列表/归属编辑、导入按名称查找/创建 work、前端 Task6–9 与 candidateId 已接入;CP 元数据收口为前端 edeaeea。B-057 实现部分结项,历史榜单数据/接线并入 B-050-后补3,当前线上数据未核验。 +> 本文其余内容保留设计时记录,不以旧 checkbox 或过期接口描述重新执行迁移。见 [核对记录](../../migration/backlog-audit-2026-11-08.md)。 > 创建日期:2026-07-21 > 最后更新:2026-07-21 From f08798e26431d4d0e1cdd7280bc450f7dc838deb Mon Sep 17 00:00:00 2001 From: Renko6626 <2300011496@stu.pku.edu.cn> Date: Sun, 8 Nov 2026 02:32:25 +0800 Subject: [PATCH 4/4] docs: archive completed plans and consolidate current guides --- docs/BACKLOG-archive.md | 8 +- docs/BACKLOG.md | 2 +- docs/CHANGELOG-archive-2026Q3.md | 753 ++++++++++++++++++ docs/CHANGELOG.md | 746 +---------------- docs/README.md | 45 +- docs/architecture/backend-overview.md | 42 + docs/archive/README.md | 15 +- ...2026-06-08-questionnaire-admin-frontend.md | 5 +- .../2026-06-08-questionnaire-frontend.md | 5 +- .../plans/2026-06-08-security-frontend.md | 5 +- .../plans/2026-06-08-vote-objects-frontend.md | 5 +- .../plans/2026-07-21-work-table-unified.md | 5 +- .../plans/2026-09-06-user-identity-model.md | 5 +- ...11-08-autocomplete-search-consolidation.md | 3 + .../2026-11-08-pinyin-candidate-search.md | 5 +- .../specs/2026-05-13-autocomplete-design.md | 5 +- .../specs/2026-06-07-admin-panel-design.md | 9 +- ...026-06-08-questionnaire-frontend-design.md | 11 +- docs/superpowers/plans/README.md | 9 + .../specs/2026-06-07-mongodb-sync-design.md | 4 +- .../2026-06-08-candidate-management-design.md | 2 +- ...2026-06-08-questionnaire-backend-design.md | 4 +- ...26-11-08-pinyin-candidate-search-design.md | 4 +- docs/superpowers/specs/README.md | 13 + 24 files changed, 921 insertions(+), 789 deletions(-) create mode 100644 docs/CHANGELOG-archive-2026Q3.md create mode 100644 docs/architecture/backend-overview.md rename docs/{ => archive}/superpowers/plans/2026-06-08-questionnaire-admin-frontend.md (93%) rename docs/{ => archive}/superpowers/plans/2026-06-08-questionnaire-frontend.md (91%) rename docs/{ => archive}/superpowers/plans/2026-06-08-security-frontend.md (93%) rename docs/{ => archive}/superpowers/plans/2026-06-08-vote-objects-frontend.md (90%) rename docs/{ => archive}/superpowers/plans/2026-07-21-work-table-unified.md (99%) rename docs/{ => archive}/superpowers/plans/2026-09-06-user-identity-model.md (85%) rename docs/{ => archive}/superpowers/plans/2026-11-08-autocomplete-search-consolidation.md (94%) rename docs/{ => archive}/superpowers/plans/2026-11-08-pinyin-candidate-search.md (97%) rename docs/{ => archive}/superpowers/specs/2026-05-13-autocomplete-design.md (88%) rename docs/{ => archive}/superpowers/specs/2026-06-07-admin-panel-design.md (89%) rename docs/{ => archive}/superpowers/specs/2026-06-08-questionnaire-frontend-design.md (84%) create mode 100644 docs/superpowers/plans/README.md create mode 100644 docs/superpowers/specs/README.md diff --git a/docs/BACKLOG-archive.md b/docs/BACKLOG-archive.md index 6cfb11db..309af231 100644 --- a/docs/BACKLOG-archive.md +++ b/docs/BACKLOG-archive.md @@ -20,12 +20,12 @@ | 编号 | 主题 | 严重度/状态 | 可并行做? | 源文档 | |---|---|---|---|---| | **B-028** ⚡ | `.github/workflows/deploy-test.yml` 当前唯一的部署 workflow 没有 prod 路径——main 分支推送也只触发部署到 test 环境(镜像 tag 区分为 `prod` vs `test`,但部署目标都是 TEST_SERVER_HOST)。需要确认是否真的没有 prod 发布通道,或补一个 `deploy-prod.yml`。**注:2026-05-19 的 3 个 `fix(ci)` 提交只是修 deploy-test.yml 的 YAML/包发现 bug,未补 prod 通道,此项仍开放** | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期 | — | [cicd-pipeline §二](./operations/cicd-pipeline.md) | -| **B-039** | 问卷结构化系统(Block 3A):后端 4 结构表 + admin 整树导入 + structure 查询 + 结构化答题 + 完成校验升级;前端 questionnaireV2 改从后端拉(一次性切换) | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期,旧方案由 B-041 取代 | — | 后端✅:模型0008/assembler/completion/domain/graphql submitPaperV2/门禁升级/整树导入+UI;前端[plan](./superpowers/plans/2026-06-08-questionnaire-frontend.md)待做 | -| **B-040** | 投票对象迁后端(Block 3B):角色/音乐 merged_into 去重合并(自动+admin手调) + /vote-objects/characters\|music\|{id} 分类查询;前端角色/音乐/CP 改从后端拉 | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期 | — | 后端✅:merged_into 0009/detect_merges/merge端点/compute归并/vote-objects端点/合并UI;前端[plan](./superpowers/plans/2026-06-08-vote-objects-frontend.md)待做 | -| **B-041** | 问卷管理增强:自由问卷列表(去年份,持续迭代) + 全层级 CRUD(问卷/题组/题/选项) + 自研嵌套编辑器;契约改问卷数组(migration 0010);取代 B-039 的 admin/契约部分 | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期 | — | 后端✅:模型重塑+0010/assembler数组/importer数组/completion required/结构端点去年份/扁平答案/13 CRUD端点/自研嵌套编辑器UI;前端[plan](./superpowers/plans/2026-06-08-questionnaire-admin-frontend.md)待做 | +| **B-039** | 问卷结构化系统(Block 3A):后端 4 结构表 + admin 整树导入 + structure 查询 + 结构化答题 + 完成校验升级;前端 questionnaireV2 改从后端拉(一次性切换) | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期,旧方案由 B-041 取代 | — | 后端✅:模型0008/assembler/completion/domain/graphql submitPaperV2/门禁升级/整树导入+UI;前端[plan](archive/superpowers/plans/2026-06-08-questionnaire-frontend.md)待做 | +| **B-040** | 投票对象迁后端(Block 3B):角色/音乐 merged_into 去重合并(自动+admin手调) + /vote-objects/characters\|music\|{id} 分类查询;前端角色/音乐/CP 改从后端拉 | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期 | — | 后端✅:merged_into 0009/detect_merges/merge端点/compute归并/vote-objects端点/合并UI;前端[plan](archive/superpowers/plans/2026-06-08-vote-objects-frontend.md)待做 | +| **B-041** | 问卷管理增强:自由问卷列表(去年份,持续迭代) + 全层级 CRUD(问卷/题组/题/选项) + 自研嵌套编辑器;契约改问卷数组(migration 0010);取代 B-039 的 admin/契约部分 | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期 | — | 后端✅:模型重塑+0010/assembler数组/importer数组/completion required/结构端点去年份/扁平答案/13 CRUD端点/自研嵌套编辑器UI;前端[plan](archive/superpowers/plans/2026-06-08-questionnaire-admin-frontend.md)待做 | | **B-050** ⚡ | **计票系统大重写** —— ✅ **v1 完成 (2026-07-18)**:计票已改读真实提交表 `raw_*`(取每 `vote_id` 最新、排除 `invalidated`);按角色/音乐 id 归票 + 白名单丢未知 id;CP 改无序 multiset(顺序/主动方不进 key)+ 主动率 + 组合票数 1 不计;名次口径对齐权威文档(票数→本命数→系统ID,同票数同名次虚位);`RankingEntity` schema 补 `id`/`favorite_percentage_of_all`。删死表 vote_data 已完成(2026-07-17)。**v1 后补子项:1/4/8 已在 `feat/result-graphql-compat` 分支完成(2026-07-19,见下),2/3/5/6 仍开放**。 | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期;历史对比/数据剩余并入 B-050-后补3 | — | **[设计稿:纯 id 记票重写](./superpowers/specs/2026-07-18-result-recount-id-based-design.md)**(§九 v1 实现落地);`compute_dao.py`/`compute.py`/`compute_service.py`/`whitelist.py`;数据落点见 B-049 | | **B-050-后补2** | trend 投票演进 | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期 | — | 同上设计稿 §9.4;CHANGELOG 2026-08-29 两条目 | -| **B-057** | voteable/work 重构收尾清单(2026-07-23 合入盘点发现):①✅**已完成**(2026-08-22,`feat/b060-b057`)——`GET /admin/voteables`(联 work 出 workId/workName/workType,q/分页)+ `POST /admin/voteables/{id}` 编辑 work 归属(清 vote-objects 缓存),5 测试;admin-ui 消费页面可后补;② admin import 的 work 按 name 匹配/自动建 work(Task 5,计划内 tech-debt);③ 上届 `final_ranking`(year=11) 导入未执行(会议结论要求"只导上届");④ 前端 Task 8/9(characterList/musicList 过滤逻辑、专辑名反查)+ **提交侧切 candidateId**(前置 B-050-后补6 已于 08-13 解除;**前端=我方负责**);⑤ 设计稿/plan 的 checkbox 与状态维护(与 zfq 沟通) | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期;历史对比/数据剩余并入 B-050-后补3 | — | [work 统一设计稿](./superpowers/specs/2026-07-21-work-table-unified-design.md);[实施计划](./superpowers/plans/2026-07-21-work-table-unified.md);CHANGELOG 2026-07-23 条目 | +| **B-057** | voteable/work 重构收尾清单(2026-07-23 合入盘点发现):①✅**已完成**(2026-08-22,`feat/b060-b057`)——`GET /admin/voteables`(联 work 出 workId/workName/workType,q/分页)+ `POST /admin/voteables/{id}` 编辑 work 归属(清 vote-objects 缓存),5 测试;admin-ui 消费页面可后补;② admin import 的 work 按 name 匹配/自动建 work(Task 5,计划内 tech-debt);③ 上届 `final_ranking`(year=11) 导入未执行(会议结论要求"只导上届");④ 前端 Task 8/9(characterList/musicList 过滤逻辑、专辑名反查)+ **提交侧切 candidateId**(前置 B-050-后补6 已于 08-13 解除;**前端=我方负责**);⑤ 设计稿/plan 的 checkbox 与状态维护(与 zfq 沟通) | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期;历史对比/数据剩余并入 B-050-后补3 | — | [work 统一设计稿](./superpowers/specs/2026-07-21-work-table-unified-design.md);[实施计划](archive/superpowers/plans/2026-07-21-work-table-unified.md);CHANGELOG 2026-07-23 条目 | | **B-061** | admin 监控投票列表(`src/apps/admin/monitor/`)展示 `attempt` 列:B-050-后补2 Step 2 把 `raw_*`/`paper_answer` 改成 append-only 后,同一选民多次改票会在监控列表出现多条历史行,当前列表未展示批次号,管理员不易一眼分辨"哪几行属于同一次改票" | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期 | — | `src/apps/admin/monitor/`;CHANGELOG 2026-08-29 append-only 条目 | | **B-063** | `apps/scraper` 模块**无任何测试**(`tests/` 下无 scraper 相关用例)——外部 HTTP 依赖需 mock。与 B-010(覆盖率门禁切 `fail_under=80`)同域:scraper 是当前最大的未覆盖面(**2026-08-31 文档整理时从 `REFACTOR_TODO.md` 迁入,已复核仍成立**) | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期 | — | `src/apps/scraper/`;原始记录见 [archive/2026-05-30-refactor-todo](./archive/2026-05-30-refactor-todo.md) §十 | | **B-062** | `AutocompleteDAO.search_cps()` 恒返回 `[]`(`src/apps/autocomplete/dao.py:78`)——CP 自动补全端点 `POST /autocomplete/search` 的 CP 分类**永远为空**。角色/音乐走 `candidate_character`/`candidate_music` 表 ILIKE 已实现,CP 无现成候选表,需从已提交的 `cp.cp_list` JSON 抽唯一 CP 名做模糊匹配(**2026-08-31 文档整理时从 `REFACTOR_TODO.md` 迁入,代码侧已复核仍成立**) | ✅ 已废弃(2026-11-08,本地未部署):旧建议链路及空 CP 方法随统一候选搜索移除;CP 成员使用 character 搜索,未新增 CP 组合推荐 | — | `src/apps/autocomplete/dao.py:77-78`;原始记录见 [archive/2026-05-30-refactor-todo](./archive/2026-05-30-refactor-todo.md) §六 | diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md index 478a8a82..5e2fd991 100644 --- a/docs/BACKLOG.md +++ b/docs/BACKLOG.md @@ -10,7 +10,7 @@ | 编号 | 当前事实 | 剩余范围/边界 | 证据 | |---|---|---|---| -| **B-037** | 提名校验响应、待审核提示及问卷门禁已接入前端;“前端待做”失实 | 原计划逐条 index 提示与现有合并原因/重复数量展示有差异,是否调整待产品判断;可选 approved 列表不自动变为需求 | [前端计划](superpowers/plans/2026-06-08-security-frontend.md);`Touhou-Vote/packages/vote/src/vote-doujin/VoteDoujin.vue` | +| **B-037** | 提名校验响应、待审核提示及问卷门禁已接入前端;“前端待做”失实 | 原计划逐条 index 提示与现有合并原因/重复数量展示有差异,是否调整待产品判断;可选 approved 列表不自动变为需求 | [前端计划](archive/superpowers/plans/2026-06-08-security-frontend.md);`Touhou-Vote/packages/vote/src/vote-doujin/VoteDoujin.vue` | | **B-050-后补3** | 主榜与 DSL 子集仍传空 historical,历史字段返回 -1/-1.0;旧 load_historical 已删除 | 若需要上届对比,需确认历史数据、ID 对应及接口接线。2026-08-22 旧 API 可用只是历史记录,本轮未核验数据/服务,不执行导入 | `src/apps/result/compute_service.py`、`advanced_search/service.py`、`src/api/graphql/result_compat.py` | | **B-059** | Nacos 失败会记 warning,再尝试本地配置并可能回退默认值;并非无日志“静默”回退 | 是否改为 fail-fast 及适用运行模式仍需确认;历史事故不能自动授权增加恢复机制 | `src/common/nacos.py`、`src/common/config.py`;[Nacos 手册](operations/nacos-config-center.md) | | **monitor 文案** | `_B050_NOTE` 仍说“需 B-050 落地后生效”,但计票已排除作废票 | 真实残留为提示文案;处置后仍需重算结果。本轮只核对文档,未修改业务响应 | `src/apps/admin/monitor/router.py`、`src/apps/result/compute_dao.py` | diff --git a/docs/CHANGELOG-archive-2026Q3.md b/docs/CHANGELOG-archive-2026Q3.md new file mode 100644 index 00000000..5ef233a5 --- /dev/null +++ b/docs/CHANGELOG-archive-2026Q3.md @@ -0,0 +1,753 @@ +# CHANGELOG 归档:2026 年第三季度 + +> 2026-11-08 从主 CHANGELOG 按完整条目迁出,保留历史正文及日期,仅修正已归档文档的链接。这里不代表当前部署、数据或需求状态。 +> 最近变更见 [CHANGELOG](CHANGELOG.md),仍开放事项见 [BACKLOG](BACKLOG.md)。 + +## [2026-09-17] 公共读接口 Redis 缓存 + 管理台手动刷缓存 + +> `vote-objects`/问卷结构/自动补全/公开提名列表此前每次直查数据库;项目 Redis 一直存在 +> 却只用于限流/会话/计票锁。本次接入缓存(写入即失效 + TTL 兜底),并给管理台加刷缓存入口。 + +### Added +- **`src/common/cache.py`**:JSON/原始文本读写 + `invalidate_prefix`(**SCAN 游标**删除,替代 `KEYS`);全部 fail-open(Redis 故障不影响请求)。 +- **vote-objects 缓存**(`src/apps/vote_objects/router.py`):列表 `vote_objects:{year}:{category}`、详情 `vote_objects:detail:{category}:{id}`,TTL 600s;命中直接返回缓存字节,`GZipMiddleware` 仍压缩。 +- **问卷结构缓存**:`questionnaire:structure:{year}`,TTL 1800s。 +- **自动补全缓存**:`autocomplete:{year}:{limit}:{q}`,TTL 60s。 +- **公开提名列表缓存**:`nominations:approved:{page}:{size}`,TTL 60s。 +- **管理端刷缓存**(`src/apps/admin/router.py`):`GET /admin/cache/stats`(各 scope 键数)、`POST /admin/cache/flush`(scope 白名单 `all|vote_objects|questionnaire|autocomplete|nominations`,未知 → 422)。管理台 Dashboard 新增「缓存」卡片(计数 + 单项/一键刷新)。 + +### Changed +- 失效逻辑补齐:`_clear_vote_objects_cache` 改为 SCAN 并同时清 `autocomplete:`;候选导入/改/删/合并/拆分、提名 approve/reject、问卷 admin 全部 13 个写端点都接上对应前缀失效(此前候选变更根本不失效)。 + +### 兼容性 +- 无接口 shape 变化(vote-objects 响应不变,只是更快)。 +- 明确**不缓存**带 `vote_token`/用户身份的读接口与所有写端点。 +- `result:*` 仍是计票产物,由 `POST /admin/compute-results` 重建,不纳入手动刷缓存。 + +### Tests +- 新增 `tests/unit/test_cache.py`(往返/前缀失效/fail-open)。 +- `test_vote_objects.py` 增缓存写入断言;`test_admin_voteables.py` 增 stats/flush/scope 校验/鉴权。 +- 全量 `666 passed, 4 skipped`。 + +## [2026-09-16] 投票对象资源 URL 后端化(0019) + +> 角色立绘 / 曲目封面 / 试听 URL 原存在前端 `packages/shared/data/{character,music}.ts`, +> 由前端**按 `name`** 匹配挂到后端候选上,管理台无法配置、改名即失效。本次迁到后端 +> 与 voteable 1:1 绑定,公共接口下发,管理台可编辑,前端静态表与匹配逻辑整体删除。 + +### Added +- **迁移 `0019_voteable_resources`**(`alembic/versions/0019_voteable_resources.py`):`voteable_character.image_url`、`voteable_music.image_url`、`voteable_music.music_url`、`voteable_music.include`(JSON,默认 `[]`)。Postgres-only 幂等;`aliases` 列已存在仅回填。 +- **公共接口下发资源**(`src/apps/vote_objects/dao.py`):`GET /api/v1/vote-objects/{characters|music}` 与 `/{category}/{id}` 的 item 新增 `imageUrl`、`aliases`(音乐另加 `musicUrl`、`include`)。 +- **管理端资源配置**:`GET /admin/voteables` 补资源字段;新增 `PUT /admin/voteables/{id}/resources`(部分更新、空串清空、URL 仅 http(s) 且 ≤2048、写后清缓存)。复用路由级 `require_admin`。 +- **迁移工具**:`scripts/voteable_resources.json`(一次性数据工件,含来源 commit)+ `scripts/import_voteable_resources.py`(按 name 导入,默认 dry-run/只填空值,`--apply --yes` 写入,`--overwrite` 覆盖)。 +- 管理台新页「投票对象资源」(`admin-ui/src/views/VoteableResourcesView.vue` + `api/voteables.ts`),产物已重建提交到 `src/admin_ui/`。 +- 前端统一加载层 `packages/shared/api/voteObjects.ts`;结果页资源索引 `packages/result/src/lib/voteObjectResources.ts`。 + +### Changed +- 投票页 `voteObjectsDataSource` 不再按 name 匹配静态表,直接映射后端字段;sessionStorage 缓存加 5 分钟 TTL(后端资源可被管理台修改)。 +- class 定义抽到 `packages/shared/model/{character,music}.ts`。 + +### Removed +- 删除 `packages/shared/data/character.ts`、`music.ts`(Touhou-Vote 仓库)及按 name 取 URL 的老逻辑;连带清理死代码 `vote/common/lib/getNickName.ts`、`result/lib/getIDtoName.ts`、`result/pages/Test.vue`。 + +### Fixed(顺带) +- 修复 `admin-ui/src/views/WorksView.vue`:此前对不上现有 `useAsync`/`usePagination`/`DataTable` API,`vue-tsc` 直接失败,admin-ui 无法构建。 + +### Performance(同日后补:修复投票列表页变慢) +- **后端加 `GZipMiddleware`**(`src/main.py`):vote-objects JSON 实测角色 `100KB→23KB`、曲目 `255KB→32KB`(4~8×)。此前仅 vote 的 nginx 配了 gzip,result 的 `/res-be` 与 dev 代理都未压缩。 +- **前端投票页按类别懒加载**:`VoteCharacter.vue` 只调 `loadCharacterVoteObjects()`、`VoteMusic.vue` 只调 `loadMusicVoteObjects()`(原都调 `loadVoteObjects()` 一次拉两个列表)。角色列表页不再为曲目付 32KB + 一次 DB 查询。 +- **缓存改「先渲染、后台 revalidate」**:sessionStorage 命中即同步渲染并立即返回,TTL 只决定何时在后台刷新,不再阻塞页面。原来 5 分钟 TTL 会让已缓存的列表页重新等待网络(测试机 TTFB 0.3~1.3s),这是"变慢"的主因。 +- 量化:静态表删除使 JS 少 **371KB(min)/50KB(gzip)**;API 增 ~38KB(gzip)。首次加载净约 −12KB,命中缓存后不再有阻塞请求。 + +### 兼容性 +- 只增列/只增字段,旧前端与旧调用方不受影响;但**新前端强依赖新字段 → 必须后端先发布、再发布前端**。 +- 数据迁移为一次性人工步骤(测试库已执行:角色 image 164、aliases 175;曲目 image 605、music 612、include 231)。 +- 无 GraphQL schema 变更;`color`/`title` 不建列(源数据分别为全表常量和全空),前端用常量/空串。 + +## [2026-09-15] 修正音乐候选「我的女仆,我甜美的女仆」的错误数据 + +> 稀翁玉曲目 `My Maid, Sweet Maid` 在早期导入时被英文逗号拆坏,后端白名单快照和测试库里存成了 `name="My Maid"`、`name_jp=" Sweet Maid"`、旧 id `d60777dd`。前端 `packages/shared/data/music.ts` 早已改正(id `462e28a2`)。投票页按曲名把后端候选对到前端静态表取封面和试听音频,名字对不上,这首歌在投票页没有封面、也放不了。 + +### Fixed +- `src/apps/result/data/whitelist_music.json`:用 `scripts/extract_whitelist.mjs` 从前端重新提取,diff 只有这一条(id `d60777dd`→`462e28a2`,name/name_jp 改正),其余 611 条和 244 条角色不变。 +- 测试库 `voteable_music` id=417:`name` 改为 `我的女仆,我甜美的女仆`,`name_jp` 改为 `My Maid, Sweet Maid`(直接 SQL,带原值条件,`UPDATE 1`;admin 没有改 voteable 名称的接口)。改完用 `POST /api/v1/admin/compute-results?vote_year=12` 重跑了计票。 + +### 兼容性 +- 计票已改读 DB(`load_whitelist_db`),JSON 快照只是 `scripts/whitelist_to_import.py` 的导入数据源,id 变化不影响计票。`candidate_music` id=601、voteable id=417 不变,已有投票(按整数 candidateId 存)不受影响;`old_id` 全表为 NULL,未改。 +- 结果计算的 `historical` 目前固定为 `{}`,按名字查历史的路径没有数据,改名不断链。 +- 无接口 shape、schema、migration、配置变更。生产环境仍是老 Rust 服务,不涉及。 + +## [2026-09-13] B-066 全站权限扫描:scraper 限流 + 邮箱验证码错 5 次作废 + +> B-065 之后对登录/token 签发、admin、投票侧数据端点、中间件与配置做了一轮只读扫描(4 个并行审计 + 人工复核)。结论:没有第二个越权洞;本条目落地两处加固,其余结论收进新文档 `docs/operations/production-readiness-checklist.md`。 + +### Fixed +- **`POST /api/v1/scraper/scrape` 增加 per-IP 限流**(`src/apps/scraper/router.py`):10 次/60 秒,超出 `429 REQUEST_TOO_FREQUENT`。此前公开、无鉴权、无限流,任何人都能驱动服务器用自己的 Pixiv 凭据去刷第三方站点。出站目标本就被各站点正则锁死在固定域名,不是任意 SSRF。 +- **邮箱验证码错 5 次作废**(`src/common/verification/email_code.py`,新增 `MAX_WRONG_ATTEMPTS`、`email-verify-attempts-{email}` 计数键,TTL 与码同为 3600s):此前 6 位码有效 1 小时,唯一防线是登录接口 per-IP 5 次/分钟,多 IP 可撞。旧 Rust 也没有次数限制,属新增防线。发新码时计数清零;成功消费时一并删除。错误码保持 `INCORRECT_VERIFY_CODE`,客户端契约不变。短信码由阿里云 PNVS 校验,其自身有次数控制,不在本条范围。 + +### Added +- `docs/operations/production-readiness-checklist.md`:生产上线待办清单。硬性项:关 `/docs`/`/openapi.json`/GraphiQL(测试机实测公网 200)、`ADMIN_ALLOWED_IPS`+`TRUSTED_PROXY_IPS` 必配、`ADMIN_SECRET` 换强值、删测试登录旁路、CORS 收紧、前端截止时间改回。建议项含 SSO `state`/`sid` 未校验(当前路径不可达)等。 +- 测试:`tests/unit/test_email_code_service.py` +3 例(第 5 次错作废、第 4 次错后正确码仍可用、发新码清零);`tests/integration/test_scraper_rate_limit.py` +1 例(第 11 次 429)。 + +### 兼容性 +- 无接口 shape 变化、无 schema/migration/配置变更。scraper 限流阈值对正常填表用户(粘几个链接)不可感知。 +- 邮箱码连错 5 次后即使输对也报 `INCORRECT_VERIFY_CODE`,用户需重新发码(受 120s 发码守卫约束)。 + +## [2026-09-13] B-065 REST 提交/回读接口按 vote_token 绑定身份(安全修复) + +> 外部 review 指出 6 个 REST 回读接口零鉴权;复核后确认,且写入路径有同源问题。根因:Rust 里 `/v1/get-*`、`/v1/voting-status/` 是 `submit-handler` 的**内网**路由,gateway 从 token 解出 vote_id 再转发;Python 重写把它们原样挂到公网 `/api/v1`,测试机 nginx `/v12-be/` 兜底可直达。`vote_id` 即 user_id(uuid4),会出现在 vote_token 载荷、管理端与导出数据里,不算秘密。 + +### Fixed +- **回读接口不再接受裸 `vote_id`**(`src/apps/submit/router.py`):`POST /get-character/`、`/get-music/`、`/get-cp/`、`/get-paper/`、`/get-dojin/`、`/voting-status/` 改为从请求体 `vote_token` 解出 user_id 再查,只返回调用者自己的提交。缺 token → `401 VOTE_TOKEN_REQUIRED`,伪造/过期 → `401` + 校验错误码。与 GraphQL 桥接 `getSubmit*Vote` / `getVotingStatus` 和 legacy `/user-token-status` 语义对齐。 +- **提交接口的 `vote_id` 改为强制取 token 的 user_id**(新增 `_bind_submit_identity`):此前 5 个 `POST /character/` 等端点只校验 token,`meta.vote_id` 仍原样落库,任何持有效 token 的用户都能以他人 vote_id 写入或改票。现与 Rust gateway `generate_submit_metadata`、GraphQL 桥接 `_make_meta` 一致,客户端传值被覆盖。 +- `docs/api/voteable-api-contract.md` §3.3 原文写"需要 userToken 鉴权"但实现没有,文档与代码已同步;2026-05-13 提交完成度设计稿中"get-* 不需要鉴权"一句加勘正注。 + +### Added +- `tests/integration/test_submit.py` 新增 15 例:6 路由 × 无 token 401、6 路由 × 伪造 token 401、跨用户 token 读不到他人提交、客户端伪造 `meta.vote_id` 不生效。 + +### 兼容性 +- **REST 回读请求体变更**:`{"vote_id"}` → `{"vote_token"}`。仓内排查:前端 Touhou-Vote、admin-ui 均不调用这 6 个 REST 接口(前端回读走 GraphQL),唯一调用方是本仓集成测试,已随改。`QuerySubmitRequest.vote_id` 暂留为可选并忽略,让旧请求得到 `401` 而非 `422`;**移除条件**:确认无调用方再发 `vote_id`。 +- 提交接口请求体 shape 不变;行为变化仅"客户端 `meta.vote_id` 不再生效",正常客户端本就不该传(Rust 时代前端从不控制该字段)。 +- 无 schema / migration / 配置变更;GraphQL 契约不变。 + +## [2026-09-12] #29 归一化的登录链路复核:六处修复 + 迁移回填前置检查 + +> 对 #29(`user` + `user_identity` 归一化)做的独立复核。七条候选问题逐条在真环境验证:六条确认并修复,一条确认为潜伏(加护栏)。 + +### Fixed +- **验证码登录不再漏掉「提升为已验证」**(`identity_service.touch_login(proven=True)` / `bind()` 已绑分支)。`_new_identity` 只在创建时写 `verified=True`,`src/` 里**没有任何地方**事后赋值 `verified`;而迁移 0018 是从 legacy `email_verified`/`phone_verified` 回填的,可能为 `false`。这类账号能正常登录,但 `_maybe_sign_vote_token` 里的 `identity.verified` 永远为假 → **静默拿不到 vote_token、投不了票,且任何地方都不报错**。#29 之前的实现有 `if not user.email_verified: user.email_verified = True`,归一化时丢了。 +- **密码登录不再在校验口令前泄露封禁状态**(`service.login_with_email_password` 改用新增的 `IdentityService.find_owner`)。`resolve()` 对封禁账号抛 `USER_REMOVED`/403,且跑在 `verify_password` 之前,未认证调用方因此能区分「该邮箱属于封禁账号」与「查无此邮箱」。改为先验口令,口令正确才告知 `USER_REMOVED`。 +- **登录顺带的 SSO 合并不再顶掉已有绑定**(`_merge_sso_session`)。它调的 `bind()` 语义是**替换**,被顶掉的 openid 随之释放、可被他人认领,且该路径此前**完全没有审计记录**(`_rebind_contact` 是有的)。现在已有绑定且 subject 不同则跳过并告警,真正新增绑定时补写 `bind_sso` 审计。换绑仍走 `update_*` / `bind_sso` 显式入口。> 注:设计稿 §一 已载明该路径在生产链路上暂不可达(GraphQL 桥接不传 redis/sid),属防御性修复。 +- **`VOTE_ELIGIBLE_PROVIDERS` 写错不再让进程起不来**(`config.Settings`)。`nacos.py` 把配置原样塞进 `os.environ`(全是字符串),pydantic-settings 对 `list[str]` 默认按 JSON 解析,写成 `phone` 或 `email,phone`(旁边字符串型键就长这样)会在 **source 层**抛 `SettingsError`——比字段校验器更早,所以 `mode="before"` 的校验器拦不住。改用 `Annotated[list[str], NoDecode]` 关掉预解析 + 校验器宽容解析(JSON 数组/逗号分隔/单个名字),看着像 JSON 却解不出数组时记错误日志并回默认值。 +- **Argon2 rehash 显式落库**(`login_with_email_password`)。此前只靠 `touch_login` 顺手 `save()`,而它在 `user.identity(provider) is None` 时会提前 return——今天不可达,但让一次写入依赖无关方法的内部实现是隐患。 + +### Added +- `alembic/versions/0018_user_identity.py`:`_assert_no_backfill_collisions()`,在**建表之前**拒绝会撞 `uq_user_identity_provider_subject` 的回填。旧 partial unique index 建在原始列上且大小写敏感,`Foo@Example.com` 与 `foo@example.com` 可合法共存,回填的 `lower(trim(...))` 会让两者塌成同一 subject(`trim(phone_number)` 同理)。真 PG 16 复现:原实现跑到一半抛 `UniqueViolation` 整体回滚;现在开工前报错并点名冲突账号,`alembic_version` 不动、`user_identity` 不建、`user` 列不删。 +- 回归测试 `tests/integration/test_identity_login_regressions.py`(6 例)与 `tests/unit/test_vote_eligible_providers_config.py`(7 例)。前者含两个对照用例(口令正确时正常报封禁、空位时正常补绑),确保修复不是「把功能关掉」。 + +### 兼容性 +- **无破坏性**:无 schema / migration 版本变化(0018 仍是 0018)、无 GraphQL 契约变化、无需数据迁移或配置变更。 +- ⚠️ 0018 的**回填范围**有变(B-064)。现有环境不受影响:测试机的 0018 已在近乎空库上跑完,新环境是空 `user` 表上跑 0018(回填为空操作),且设计稿 §9 已定「上线即空库」、`COLLECTION_CONFIG` 里没有 user 映射 —— 不存在 legacy 用户导入通道。改动只在「拿 0018 之前的存量库重放迁移」时生效,那正是它要修的场景。 +- 行为变化仅三处,都是修正:① 回填出的未验证身份在验证码登录后变为已验证(此前永久投不了票);② 封禁账号 + 错误口令改报 `INCORRECT_PASSWORD`(此前报 `USER_REMOVED`);③ 登录路径不再改绑已有 SSO 身份。 +- `VOTE_ELIGIBLE_PROVIDERS` 现在多接受两种写法,原 JSON 数组写法不受影响。 + +### Fixed(续)— B-064:0018 回填不再把「管理员封禁」当成「自助注销」 +- 原回填用 `WHERE removed = FALSE` 一刀切,把 `ban_user` 封禁的账号也排除了。而 `IdentityService.resolve` 正是靠身份行对封禁 subject 抛 `USER_REMOVED` 来阻止对方拿同一邮箱/手机改头换面重新注册 —— 没有身份行,**封禁形同虚设,解封出来的账号又没有任何登录方式**。真 PG 已复现:封禁账号回填得 0 条 identity。 +- **这不是「GDPR 抹除」与「封禁可执行」的二选一**——复核时查实两者可区分(此前误判为不可区分):旧 `remove_voter` 在同一次提交里把 `email` / `phone_number` / `password_hash` **全部置空**,而 `ban_user`(`UserDAO.set_removed`)一个都不动;旧 CHECK `at_least_one_identifier` 又保证活跃账号必有 email 或 phone,封禁前是活跃的,故必有其一。 +- 回填范围改用 `_BACKFILL_SCOPE = (removed = FALSE OR email IS NOT NULL OR phone_number IS NOT NULL)`,前置检查复用同一条件(否则查不到新纳入的封禁账号之间的冲突)。两个目标同时成立:封禁账号身份行完整回填;自助注销账号一条都不回填 —— **包括旧 `remove_voter` 漏清的 `qq_openid` / `thbwiki_uid`**(设计稿 §一.2 记的缺陷),不借回填把用户要求抹除的标识搬进新表。 +- 真 PG 16 上四种形态逐一验证:活跃账号 3 条身份;封禁账号 3 条(封禁可执行、解封可登录);只有手机号的封禁账号 1 条(判别式靠 phone 兜住);自助注销账号 0 条(含其残留的 qq_openid)。并复验前置检查在新范围下能拦住「活跃账号 vs 封禁账号」的大小写冲突。 + +## [2026-09-11] 回退 `UserDAO.save()` 的 `session.merge()`,改为显式拒绝 detached 实例(B-024 / U-18) + +> 承接 #30。#30 把 `save()` 改走 `session.merge()` 以「防 detached 静默 no-op」,但该前提不成立、且引入三条静默数据损坏路径,故回退并改为硬约束。 + +### Fixed +- `UserDAO.save()` 不再 `session.merge()`(`src/apps/user/dao.py`)。`merge()` 会按传入的陈旧副本重建 `User.identities`,而该关系是 `delete-orphan` —— **DB 里有、副本里没有的绑定会被 DELETE**。同一次盲写还会把 `removed` 覆盖回 `False`(**解封已封禁账号**)、把已硬删的行重新 INSERT(**复活账号**)。三者均已用探针在 sqlite 上复现。 +- `save()` 改为显式 `_reject_detached()`:非本 session 托管的实例直接抛 `InvalidRequestError` 并给出补救指引。此前 `refresh()` 也会抛同名异常,但属偶然行为;现在是写明的契约。 +- 更正 #30 的立论:`save()` 对 detached 实例**从未**静默 no-op —— 合入前的实现在 `refresh()` 处就抛 `InvalidRequestError`,调用方立刻知情。 + +### Changed +- 回归测试 `tests/integration/test_user_dao_save.py` 重写为 4 例:托管实例正常落库、detached 实例被拒、**不得删掉别处新建的绑定**、**不得解封或复活**。后三例在 `merge()` 版下会红(已验证),不是永远绿的测试。 +- `tests/integration/conftest.py` 按 B-023 本意收口为单行 `import fakeredis.aioredis`(必须带子模块名),删除 #30 留下的注释掉的旧代码、裸 `except:`(会吞 `BaseException`,且兜底换成的是**同步** FakeRedis,交给 `await` 会在无关模块炸 `TypeError`)与未被引用的 `FakeRedis` 死变量。 +- BACKLOG 复位:#30 把已归档的 **B-022 / B-024** 重新加回开放表(陈旧 rebase 产物),**B-023** 一度同时列在开放表与归档中。现统一以归档为准,开放表不再残留这三项。 + +### 兼容性 +- **无破坏性**:无 schema / migration / 配置 / GraphQL 契约变化,无需数据迁移。 +- 行为面:现网 5 个 `save()` 调用方(`identity_service.py:115,123,128`、`service.py:277,300`)全部持有同一 session 的托管实例,走的是正常路径,**行为不变**。只有传 detached 实例才会拿到报错,而这在合入前同样是报错。 + +## [2026-09-06] 用户身份模型归一化:`user` + `user_identity`(migration 0018,破坏性,无兼容期) + +> 设计:[user-identity-model-design](./superpowers/specs/2026-09-06-user-identity-model-design.md)。系统尚未公开上线,用户库允许重建。 + +### Changed +- **`user` 表只留账号属性**(id / nickname / pfp / password_hash / removed / register_*);邮箱、手机、QQ openid、THBWiki uid 各成一行进入新表 **`user_identity`**(`provider` / `subject` / `verified` / `verified_at` / `created_at` / `created_ip` / `created_device_id` / `last_login_at`)。唯一约束 `(provider, subject)` 与 `(user_id, provider)`,`provider` 有 CHECK。每条身份自带绑定时间、绑定 IP 与设备指纹,供反刷聚类使用。 +- **登录 / 改绑 / SSO 绑定 / 注销收敛为一条路径**:`src/apps/user/identity_service.py`(`resolve` / `register` / `bind` / `unbind_all`),provider 规则集中在 `src/apps/user/identity.py`。加一个认证来源只需加枚举值 + 放宽 CHECK。 +- **投票 token 资格可配置**:新配置项 `VOTE_ELIGIBLE_PROVIDERS`(JSON 数组,默认 `["email","phone"]`,与旧 Rust 规则一致)。是否收紧为仅手机号,上线前另行决定。 +- `remove_voter` 改为删除全部身份行 + 清密码;账号行留作 tombstone。 +- 管理端 `/admin/users` 的 `email` / `phone` / `email_verified` / `phone_verified` 改由身份行推导,**响应形状不变**;搜索改为 join 身份表。 +- `VoterFE` / GraphQL `LoginResult` **形状不变**:`thbwiki` = 是否绑定 THBWiki 身份。 + +### Fixed +- 注销后 QQ / THBWiki 身份不再被永久占用(此前 `remove_voter` 不清 SSO 列,且查找不过滤 `removed`,他人再绑报 `SSO_ID_ALREADY_BOUND`)。 +- 登录时合并 Redis SSO 会话撞到他人的 openid:此前 `IntegrityError` → 500 且 sid 已被消费;现记 warning 跳过,不阻断登录。 +- 被管理端封禁的邮箱/手机再登录:此前撞 partial unique index → 500;现返回 `USER_REMOVED`(403),且该标识不能被新账号注册。 + +### Removed +- legacy bcrypt+salt 密码路径(`legacy_salt` 列、`verify_legacy_password` / `verify_any_password`、`bcrypt` 依赖)。 +- 旧 Mongo `voters` 集合同步(`map_voter`、`COLLECTION_CONFIG` 项、`scripts/bson_to_sql.py` / `scripts/import_mongo_dump.py` 的 voters 注册)。其余集合同步不变。 +- `UserDAO.get_by_email` / `get_by_phone` / `find_by_thbwiki_uid` / `find_by_qq_openid`;`User.at_least_one_identifier` CHECK 与四个 partial unique index。 + +### 测试 +- 新增 `tests/helpers/users.py::make_user/build_user`;`tests/integration/test_identity_binding.py`(注册元数据、改绑替换、409、注销重注册、封禁、大小写归一、资格配置);`test_identity_pg_constraints.py`(PG-only,非 PG 自动 skip);`test_sso_flows.py` 重写。全量 614 passed(sqlite)。 + +### 兼容性 / 迁移 +- **需要数据迁移**:`alembic upgrade head`(0018:建表 → 从旧列回填 → 删旧列)。回填近似:每身份 `created_*` 取账号 `register_*`;`removed=TRUE` 账号不回填身份。**无兼容期**;`downgrade` 反向回填可回滚。 +- **配置**:可选新增 Nacos key `VOTE_ELIGIBLE_PROVIDERS`;不配即默认。 +- **对外接口形状无变化**(REST `VoterFE`、GraphQL、admin 用户列表)。新增错误码 `USER_REMOVED`(403)。 +- 关闭 BACKLOG B-008(废弃)、B-011、B-022、B-024。 + +## [2026-08-31] 文档树大扫除:归档过程产物、重建索引、整理 CHANGELOG(docs,无代码变更) + +> 文档累积到 131 份约 1.75 MB,过程产物占七成;索引停更在 2026-06-08,07–08 月新增的约 25 份文档从未进索引; +> 多份设计稿的 `状态` 行已与事实不符。本次只动文档,**不涉及任何代码、接口、schema、配置或部署**。 + +### Changed +- **30 份过程产物迁入 `docs/archive/superpowers/`**:25 份已执行完/已废弃的 plans、4 份已废弃或属事后记录的 specs、1 份一次性 handoff。每份头部插入归档状态块(状态 + 证据 + 落地去向 + 「不代表当前实现」)。判定依据是 BACKLOG / BACKLOG-archive / CHANGELOG 三者交叉核对**加代码复核**——plans 里的 `- [ ]` checkbox 从未被维护(B-057⑤),不可作为完成度依据。 +- **36 份现役设计稿统一补 `状态` 块**(已实施 14 / 部分实施 15 / 已实施(部分被取代)6 / 待实施 1)。其中**修正 7 份与事实不符的旧状态行**,例如:`2026-08-14-advanced-search-dsl-design` 仍写「待实施」而功能当天即上线;`2026-07-21-work-table-unified-design` 仍称 `GET /admin/voteables` 未实现而该缺口已于 2026-08-22 由 B-057① 补齐;`2026-07-23-tally-db-truth-source-design` 仍写「待实施」而 Phase 1 已随 #26 于 2026-08-13 上线。 +- **本文件**:合并 9 组重复条目(均为「孤儿标题紧跟真正条目」的合并残留)、按日期倒序重排(修正 2026-08-22 错位于 08-14 之前)、2026-07-01 之前的 15 条切至 `CHANGELOG-archive-2026H1.md`。**正文逐行比对确认零丢失**,条目数 59 → 50。 +- **`docs/README.md` 全量重写**:补齐此前缺失的约 25 份文档,设计稿按主题分组(用户认证 / GraphQL 契约 / 计票结果 / 候选项 / 安全 / 管理端 / 前端侧),并新增「归档」与「维护规则」两节。 + +### Added +- `docs/archive/README.md` —— 归档索引与**归档规则**(什么该归档、归档时必须做什么、判定状态时不要凭印象)。 +- `docs/CHANGELOG-archive-2026H1.md` —— 2026 上半年变更记录归档。 +- `docs/requirements/` —— VoileLabs 官方需求文档(投票系统 / 投票结果页面,md + docx 原件)从 `docs/` 根迁入。 +- BACKLOG **B-062**:`AutocompleteDAO.search_cps()` 恒返回 `[]`(`src/apps/autocomplete/dao.py:78`),CP 自动补全永远为空。 +- BACKLOG **B-063**:`apps/scraper` 模块无任何测试。 + > 两条均从 `REFACTOR_TODO.md` 迁出,**迁出前经代码复核确认仍成立**。 + +### Removed +- `REFACTOR_TODO.md`(子项目根目录,违反 CLAUDE.md §2,且内容已过期——其中 `vote_data ✅` 所指模块已于 2026-07-17 作为死代码删除)→ 归档至 `docs/archive/2026-05-30-refactor-todo.md`。 +- `.github/PR_DRAFT_user_and_verify.md`(2026-05-30 的 PR 草稿,对应 PR 早已合入 main)。 + +### 兼容性 / 迁移 +- **无兼容性影响**;**不需要数据迁移或配置变更**。 +- 过期文档一律**归档而非删除**,全文保留可查。 + +## [2026-08-29] append-only 提交历史 + 真实净增量 trend(B-050-后补2 Step 2,Task 4-8) + +### Changed +- 提交存储改为 append-only:`SubmitDAO._upsert` 覆盖的全部 `raw_*` 表(`raw_character`/`raw_music`/`raw_cp`/`raw_paper`/`raw_dojin`)与结构化问卷表 `paper_answer` 改票不再删除/覆盖旧行,`_upsert` 与 `questionnaire/dao.py::replace_answers` 均改为追加(`paper_answer` 新增可空 `attempt` 批次号列 + 索引,一次提交的所有行归入同一 `attempt`;`raw_*` 天然按行追加,无需批次号)。读方经 `latest_batch`/等价逻辑只取最新批次,行为与迁移前一致。 +- `queryQuestionnaireTrend` 及角色/音乐/CP 三类榜单的 `trend`/`trendFirst` 全部升级为**真实净增量序列**:新纯函数 `src/apps/result/trend.py::net_delta_trends` 取代 Step 1 的"最新提交分桶"近似——改票产生的旧选择在原分桶记负值、新选择记正值,不变量为每个实体全部分桶净增量之和 == 该实体最终 `vote_count`。`compute_all`(预计算主路径)与 `advanced_search/service.py::_compute_filtered`(DSL 子集重算路径)均已接入。 +- 前端契约无变化:`Trends(trend, trend_first)` 字段本就按净增量语义消费(`QuestionnaireDetail.vue` 等组件直接绘制为增量柱状图),无需前端跟进发版。 + +### Added +- 迁移 `0017`:`paper_answer` 新增可空 `attempt` 列 + 索引,**删除** 原 `uq_paper_answer_voter_group` UNIQUE 约束(`vote_id, vote_year, questionnaire_id, group_id`),改由 append-only 语义承接(`down_revision=0016`)。 +- `ComputeDAO` 新增历史加载器:`load_char_history`/`load_music_history`/`load_cp_history`/`load_questionnaire_history`,按时间序读取 append-only 提交历史供净增量计算消费。 +- `src/apps/result/trend.py::net_delta_trends`:纯函数,输入按时间排序的提交历史(含改票批次),输出真实净增量分桶序列;配套不变量测试(每实体分桶净增量之和 == 最终票数)。 + +### 兼容性 +- **需跑 `alembic upgrade head`(落地到 0017)**:`paper_answer` 表结构变化,未升级迁移则新版应用代码写入会失败(`attempt` 列不存在)。 +- **需重跑一次 `compute_all`**(或等定时任务下一轮):Redis 里的旧近似 trend 快照需要用净增量口径重新计算才会生效;重跑前行为保持 Step 1 的近似值,不报错。 +- admin 监控投票列表会开始出现**历史行**(同一选民多次改票会看到多条 `paper_answer`/`raw_*` 记录,而非过去覆盖后的单行)——作废(软删)历史行不影响计票(只读最新批次),作废最新行的效果仍等价于该选民出局,管理员操作口径不变。 +- **历史断点**:迁移上线前发生的改票历史已被旧覆盖式存储永久抹掉,无法回填;真实净增量曲线从上线时刻起才开始积累,上线当天已存在的单行选民数据会被当作一次性净增量处理(近似值),属于数据侧自然退化,不需要额外兼容代码。 +- **已知限制**:同一选民短时间内**并发**重复提交理论上可能落在同一个 `attempt` 批次号(`prev + 1` 的读-算-写非原子),导致两次提交的行被误合并为一批——旧版本的 UNIQUE 约束曾意外挡住这种情况,现实并发窗口极窄、概率很低;问卷侧若观察到异常,可在读方按 `created_at` 取最大值兜底识别真正的最新批次。 + +## [2026-08-29] 问卷趋势接通近似版(B-050-后补2 Step 1,Task 3) + +### Added +- `queryQuestionnaireTrend` GraphQL 字段接通真实数据:`_query_questionnaire_trend_entries` 不再固定返回空 `Trends` 列表,改为逐题读取 `compute_paper_results` 产出的 `"trend"`(近似口径:按每条问卷回答行 `created_at` 分桶,与 legacy Rust 网关口径一致,非真实净增量——问卷题允许改答案,`paper_answer` 同一 `vote_id`+`group_id` 只留最新一行);`trendFirst` 恒为空列表(问卷题没有"本命"概念,是本字段永久形状,不是退化);某道题从未算过时该条目仍退化为 `Trends(trend=[], trend_first=[])`,不中断其余题目。 +- DSL `query` 子集路径(`advanced_search/service.py::_compute_filtered`)同样接通 trend:筛选后的子集重算复用同一 `compute_paper_results(..., vote_start=, total_hours=)` 调用,子集 trend 与全集同口径。 +- 两个调用点补齐 `vote_start`/`total_hours` 透传:`compute_service.py::compute_all`(预计算主路径)与 `advanced_search/service.py::_compute_filtered`(筛选子集路径)。 +- 测试:`tests/integration/test_result_compat_rest.py` 新增/改写 `queryQuestionnaireTrend` 集成测试——不同小时 `created_at` 的问卷回答验证 trend 精确分桶、`trendFirst` 恒空;DSL `query` 子集路径同样返回非空 trend(子集 counts ≤ 全集)。 + +### 兼容性 +- **无 GraphQL schema 变化**:字段签名/返回类型不变,只是内容从恒空变成真实近似值——消费方(`QuestionnaireDetail.vue`)本就按 `[Trends!]!` 消费,无需跟进。 +- **需重跑 compute 才有数据**:本轮改动只影响 `compute_paper_results` 调用参数,不改数据模型;线上现有 Redis 缓存需重跑一次 `compute_all`(或等定时任务下一轮)才会写入非空 `trend`,重跑前该字段行为不变(仍是恒空)。 +- 真实净增量(Step 2)仍需 append-only 提交历史存储落地,属于同一 BACKLOG 项(B-050-后补2)的后续步骤,本轮不含。 + +## [2026-08-22] B-060 高级搜索限频/单飞加固 + B-057① admin voteables 端点 + +### Added +- **B-057①**:`GET /api/v1/admin/voteables`(category/q/分页,联 work 表出 `workId`/`workName`/`workType`)+ `POST /api/v1/admin/voteables/{id}`(编辑 work 归属,null 清空;不存在的 work→409),挂 `require_admin`,变更后清 vote-objects 缓存。5 个集成测试。admin-ui 消费页面可后补(B-049 无 UI 端点清单)。 +- **B-060**:`ClientIPMiddleware`(`src/common/middleware/client_ip.py`)把 B-044 可信代理解析的 client IP 放 ContextVar,供深层服务读取。 + +### Changed +- **B-060 高级搜索 miss 限频升级为双层**:per-IP `ADV_MISS_LIMIT_PER_IP_PER_MINUTE=10` + 全局 30/min 兜底;**扣费点后置到真正执行重算处**——缓存命中、等锁后从缓存拿到结果的赛跑者不再扣预算(消除终审小尾巴"注释与行为不符")。 +- **等锁策略**:由固定 5s(25×200ms)改为**跟随锁存活轮询**(200ms 间隔,上限 60s,锁消失提前接手)。依据:真机实测单次重算 ~8s(4 万行问卷载票),固定 5s 会让并发等锁者在最贵场景集体转入重复计算。 +- 新增 3 个测试真实覆盖等锁分支(等锁缓存命中零扣费/锁消失提前接手含耗时断言/per-IP 隔离)——终审小尾巴"锁竞争分支覆盖为空"销账。 + +### 兼容性 +- 无契约变化;`ADVANCED_SEARCH_BUSY` 语义不变,只是触发口径更精确(真重算才计数)。无 DB 迁移。 + +## [2026-08-14] 高级搜索/筛选 DSL 实现落地(B-050-后补5,Task 1-6 全部完成) + +### Added +- 新子包 `src/apps/result/advanced_search/`(`dsl.py`/`subset.py`/`service.py`):lark 文法解析器(`chars`/`musics`/`chars_first`/`musics_first`/`q=