AI 可执行任务分解

前置依赖

涉及文件 / 表

• app/pages/
• app/middleware/locale.global.ts
• nuxt.config.ts

交付物

app/pages/[locale]/** + 全局中间件 + 根重定向页

执行步骤

1. 1把 app/pages 下除 index.vue 外的页面整体移入 app/pages/[locale]/，保持目录层级不变。
2. 2新增 app/middleware/locale.global.ts：读首段路径，命中已登记语言码则放行；否则 302 到 /{协商语言}/{原完整路径}。
3. 3app/pages/index.vue 只做一件事：redirect 到 /{协商语言}，不渲染任何内容。
4. 4在 [locale] 各页面的 setup 顶部校验语言码合法性，非法则抛 404（防止中间件失效时静默渲染）。

前置依赖

涉及文件 / 表

• app/pages/index.vue
• app/middleware/locale.global.ts
• app/utils/locale.ts

交付物

根路径协商重定向

执行步骤

1. 1服务端读取 useRequestHeaders(['accept-language'])，按 q 值降序取第一个已登记且已启用的语言。
2. 2前缀匹配归一化：zh / zh-Hans / zh-TW 都命中 zh-CN；en-GB 命中 en。
3. 3全部不命中时回落到 fallback。回退值是 zh-CN 而不是 en —— 这是一个以中文为主的站点，把未覆盖的语言送到英文比送到中文更陌生。
4. 4若请求带 ruyi_lang cookie（用户曾手动选择过），cookie 优先级高于 Accept-Language。
5. 5重定向必须走 302 + Location 响应头，不要在客户端脚本里改 location（会闪）；也必须是 302 而不是 301，因为结果依赖请求头。

前置依赖

涉及文件 / 表

• app/middleware/locale.global.ts

交付物

旧路径重定向规则

执行步骤

1. 1中间件识别「首段不是语言码」且「首段命中已登记页面名」两种情况。
2. 2没有 ruyi_lang cookie 时收敛到默认语言（zh-CN）：目标与请求头无关，才可以用 301。
3. 3有 cookie（用户显式选过语言）时尊重它，但改用 302 —— 这次跳转的结果依赖 cookie，301 会被缓存并扩散。
4. 4重定向时保留 query 与 hash，拼接到新路径尾部。
5. 5对 /c/... 社区路径同样处理：/c/php/post/p3 → /zh-CN/c/php/post/p3，帖子 id 不变。

前置依赖

无 —— 可以立即开工

涉及文件 / 表

• app/pages/c/[community]/[...path].vue
• app/data/menuRegistry.ts
• app/data/communityMenus.ts

交付物

无限级菜单 → 独立页面 的完整通路

执行步骤

1. 1菜单数据里凡有 slug 的节点，其 URL 为 /{locale}/c/{community}/{slug 路径}。
2. 2页面按 path 数组到菜单树定位节点，再按注册表解析对应 SFC 加载器。
3. 3未登记的 slug 回落 StubPage，绝不 404 —— 未完成的页面也是产品的一部分。

前置依赖

无 —— 可以立即开工

涉及文件 / 表

• app/pages/c/[community]/post/[id].vue
• app/pages/c/[community]/[...path].vue

交付物

帖子详情路由

执行步骤

1. 1详情页放在 post/[id].vue：两个静态路径段，特异性高于 [...path] 的 catch-all。
2. 2在 [...path].vue 里不额外判断开头是否为 post，交给路由匹配层决定。
3. 3给该优先级写一条回归断言，避免以后有人把目录结构调整成同构层级。

前置依赖

涉及文件 / 表

• app/data/routes.ts
• app/pages/[locale]/tasks.vue
• nuxt.config.ts

交付物

app/data/routes.ts + 构建期交叉校验

执行步骤

1. 1建立 app/data/routes.ts，逐条声明 path / page 文件 / 渲染策略 / 是否 SSR / 是否需要 locale。
2. 2在 tasks 页直接渲染该数组；构建期用 globalThis._importMeta_.glob 扫 app/pages 做一次交叉校验。
3. 3校验失败（有页面没有登记，或有登记没有页面）时在页面上显式标红，不要静默通过。

前置依赖

无 —— 可以立即开工

涉及文件 / 表

• app/pages/c/[community]/[...path].vue
• app/pages/c/[community]/post/[id].vue

交付物

404 语义

执行步骤

1. 1在 setup 阶段解析社区与帖子，解析失败立即 throw createError({ statusCode: 404, fatal: true })。
2. 2不要用「渲染一个提示组件」的方式代替 404。
3. 3错误文案里带上被查找的 id，方便排障。

前置依赖

无 —— 可以立即开工

涉及文件 / 表

• db/migrations/xxx_create_languages.sql
• languages 表

交付物

languages 表 + 初始数据

执行步骤

1. 1建表：code varchar(16) PK、name varchar(64)、native_name varchar(64)、direction enum('ltr','rtl')、enabled tinyint(1)、fallback_code varchar(16) NULL、sort_order int。
2. 2code 用 BCP-47 子集（zh-CN / en / ja / ko / zh-TW），大小写敏感由 utf8mb4_bin 保证。
3. 3插入 zh-CN（enabled=1, fallback=NULL）与 en（enabled=1, fallback='zh-CN'），其余语种 enabled=0 作为扩展位。
4. 4fallback_code 自引用外键，用于「某语言缺内容时回落哪一门」。

前置依赖

涉及文件 / 表

• db/migrations/xxx_create_community_locales.sql
• community_locales 表

交付物

community_locales 表 + 数据迁移

执行步骤

1. 1建表：id、community_id FK、lang_code FK、slug varchar(64)、name、tagline、description、kind、is_default tinyint(1)、status enum('draft','published')。
2. 2唯一键 UNIQUE(lang_code, slug) —— slug 在**同一语言内**唯一，不同语言可复用同名 slug。
3. 3唯一键 UNIQUE(community_id, lang_code)，保证一个社区在一个语言下只有一个版本。
4. 4每个 community_id 必须恰好有一条 is_default=1 的行，用触发器或应用层校验。
5. 5把现有 communities.slug / name / tagline 作为 zh-CN 版本迁移进来。

前置依赖

涉及文件 / 表

• db/migrations/xxx_create_translations.sql
• translations 表

交付物

translations 表

执行步骤

1. 1建表：entity_type varchar(32)、entity_id bigint、lang_code、field varchar(32)、value text。
2. 2唯一键 UNIQUE(entity_type, entity_id, lang_code, field)，使翻译写入天然幂等（可 upsert）。
3. 3索引 KEY(lang_code, entity_type, entity_id) 供按语言批量取回。
4. 4约定 entity_type 取值：community_menu_item / community_rule / flair / page_block。

前置依赖

涉及文件 / 表

• db/migrations/xxx_create_user_locale_prefs.sql
• user_locale_prefs 表

交付物

user_locale_prefs 表

执行步骤

1. 1建表：user_id PK FK、lang_code FK、source enum('manual','browser')、updated_at。
2. 2未登录用户只写 cookie（ruyi_lang），登录后首次访问把 cookie 值回升到本表。
3. 3只有当 source='manual' 时才覆盖用户已存偏好，避免匿名期的浏览器推断覆盖手动选择。

前置依赖

涉及文件 / 表

• posts 表
• comments 表
• db/migrations/

交付物

posts / comments 的语言字段与索引

执行步骤

1. 1posts 增加 lang_code varchar(16) NOT NULL DEFAULT 'zh-CN'，外键指向 languages.code。
2. 2comments 同理；评论区允许与主帖不同语言（回复者可能用别的语言）。
3. 3建复合索引 KEY(community_id, lang_code, created_at)。
4. 4回填历史数据为默认语言，再把 DEFAULT 去掉，避免以后静默写入错语言。

前置依赖

涉及文件 / 表

• communities 表
• 索引重建脚本

交付物

社区唯一键迁移

执行步骤

1. 1先加新唯一键 UNIQUE(lang_code, slug)（此时 lang_code 全为默认语言，约束等价成立）。
2. 2再删除旧的 UNIQUE(slug)。顺序不能颠倒，否则中间态会因两条约束并存而误报冲突。
3. 3应用层查询社区时一律带 lang_code 条件，并 grep 校验没有裸 slug 查询残留。

前置依赖

无 —— 可以立即开工

涉及文件 / 表

• db/migrations/
• db/rollback/

交付物

成对的迁移/回滚脚本 + CI 校验

执行步骤

1. 1每个 up 脚本配一个 down 脚本，down 只做结构性回退（删列/删表），不做数据恢复。
2. 2迁移前自动快照受影响表（CREATE TABLE xxx_bak_YYYYMMDD AS SELECT *）。
3. 3CI 里跑一遍 up → down → up，任一步失败即阻断合并。

前置依赖

涉及文件 / 表

• Meilisearch 索引定义
• search 同步任务

交付物

多语言检索索引

执行步骤

1. 1给 posts / communities 索引增加 filterableAttributes: ['lang_code', 'community_id', 'flair']。
2. 2检索时强制带上 lang_code 过滤；跨语言搜索作为独立开关（默认关闭）。
3. 3Meilisearch 的 locales 设置按内容语言分别声明，让分词器选对。

前置依赖

涉及文件 / 表

• crates/ruyi-api/src/routes/languages.rs

交付物

语言清单接口

执行步骤

1. 1返回 [{ code, name, nativeName, direction, enabled }]，只返回 enabled=1 的项。
2. 2响应设置 Cache-Control: public, max-age=300，并在 ETag 里带上语言表版本。
3. 3不要求登录。

前置依赖

涉及文件 / 表

• crates/ruyi-api/src/routes/communities.rs

交付物

社区列表接口

执行步骤

1. 1GET /api/communities?lang=en&page=&sort= 只 JOIN community_locales 中 status='published' 的行。
2. 2返回体带 availableLangs: ['zh-CN','en']，供前端渲染「该社区还有哪些语言版本」。
3. 3lang 缺省时使用服务端协商结果（Accept-Language），不使用裸默认值。

前置依赖

涉及文件 / 表

• crates/ruyi-api/src/routes/community_detail.rs

交付物

社区详情接口

执行步骤

1. 1GET /api/communities/{slug}?lang= 返回该语言版本的内容 + languages: [{ code, slug, name }]。
2. 2languages 数组里带每个语言的**该社区的 slug**，前端才能拼出正确的切换链接。
3. 3请求的语言版本不存在时返回 404 + 可选语言列表，不静默回落。

前置依赖

涉及文件 / 表

• crates/ruyi-api/src/routes/posts.rs

交付物

发帖接口扩展

执行步骤

1. 1POST /api/posts 入参增加 lang_code（必填）与 translation_of（可选，指向另一语言的同源帖）。
2. 2translation_of 仅在指向的帖子存在且语言不同时接受。
3. 3返回体带上同源帖的 id 清单，供详情页渲染「其他语言版本」入口。

前置依赖

涉及文件 / 表

• crates/ruyi-api/src/i18n/fallback.rs

交付物

字段级回退 + 前端标注

执行步骤

1. 1字段级回退：某语言的 field 缺失时取 fallback_code 语言的值。
2. 2响应里对每个回退过的字段列出，形如 fallbacks: [{ field, from: 'zh-CN' }]。
3. 3前端据此在页面上标注「本段暂为中文」的小标记，而不是假装已经翻译。

前置依赖

无 —— 可以立即开工

涉及文件 / 表

• crates/ruyi-api/src/error.rs

交付物

统一错误体

执行步骤

1. 1定义 { code: string, message: string, details?: object }，code 为稳定标识（如 COMMUNITY_NOT_FOUND）。
2. 2message 按请求语言本地化，code 永远不本地化（供程序判断）。
3. 3所有 4xx/5xx 都经过同一层中间件序列化，禁止各路由自己拼字符串。

前置依赖

无 —— 可以立即开工

涉及文件 / 表

• crates/ruyi-api/src/routes/posts.rs
• crates/ruyi-api/src/routes/comments.rs
• Redis

交付物

幂等提交

执行步骤

1. 1客户端每次提交生成一个 uuid-v4 作为 client_token 一并提交。
2. 2服务端在 Redis 写 SETNX client_token 结果（TTL 24h），命中已存在则直接返回首次的结果。
3. 3client_token 与提交者 id 绑定，防止跨用户复用。

前置依赖

无 —— 可以立即开工

涉及文件 / 表

• comments 表
• crates/ruyi-api/src/routes/comments.rs

交付物

评论树查询

执行步骤

1. 1comments 表维护 path 字段（形如 0001/0007/0003，定宽补零以保证字典序等于层级序）。
2. 2查询某帖评论用 WHERE post_id=? AND path LIKE ? ORDER BY path LIMIT n 一次取回。
3. 3前端按 path 的层级前缀重建树，不依赖服务端返回嵌套结构。

前置依赖

无 —— 可以立即开工

涉及文件 / 表

• app/i18n/config.ts
• app/composables/useLocale.ts

交付物

app/i18n/config.ts + useLocale()

执行步骤

1. 1app/i18n/config.ts 导出 LOCALES: { code, label, nativeLabel, htmlLang, dir, enabled }[]，默认启用 zh-CN 与 en，其余语种以 enabled:false 预登记。
2. 2useLocale() 返回 { locale, locales, isDefault, switchTo, localePath }，locale 由路由首段解析得到。
3. 3localePath(p) 负责给任意站内路径加上当前语言前缀，且幂等（已带前缀不重复加）。

前置依赖

涉及文件 / 表

• app/utils/locale.ts
• app/pages/index.vue

交付物

语言协商函数（同构）

执行步骤

1. 1解析 Accept-Language：按 q 值降序、忽略 q=0，逐个匹配已启用语言；匹配规则为前缀匹配（zh 命中 zh-CN）。
2. 2全不命中时使用 config 里的 fallback。
3. 3服务端与客户端使用同一份解析函数（同构），避免两端结果不一致导致水合警告。

前置依赖

涉及文件 / 表

• app/components/LocaleSwitcher.vue
• app/composables/useLocale.ts

交付物

语言切换器 + 持久化

执行步骤

1. 1切换时写 cookie ruyi_lang（SameSite=Lax，有效期 1 年），再 navigateTo 目标语言下的等价路径。
2. 2切换不得整页刷新：用 navigateTo 做客户端路由，保持滚动位置与已展开的菜单状态。
3. 3登录用户同时异步回写 user_locale_prefs。

前置依赖

涉及文件 / 表

• app/composables/useLocale.ts
• app/components/LocaleSwitcher.vue

交付物

等价路径映射

执行步骤

1. 1切换时把当前 route.fullPath 去掉语言前缀，再拼上目标语言前缀。
2. 2社区路径要额外做一次 slug 映射：目标语言下该社区的 slug 可能不同（community_locales.slug）。
3. 3映射缺失时回落到该社区的首页，而不是 404。

前置依赖

涉及文件 / 表

• app/i18n/messages.ts
• app/composables/useI18n.ts
• app/error.vue

交付物

两份词典 + 键集合校验

执行步骤

1. 1按模块分节组织键名（nav.* / header.* / community.* / post.* / composer.* / common.*）。
2. 2两份词典的键集合必须完全一致，用一个构建期断言校验，缺键直接构建失败。
3. 3缺失键在开发环境下返回 ⟦key⟧ 形式，便于一眼看出漏翻，生产环境回落 fallback 语言。
4. 4错误页（4xx/5xx）同样走词典，不复用框架默认页 —— 它会把内部的 statusMessage 原样打出来。

前置依赖

涉及文件 / 表

• app/data/communityMenus.ts
• app/utils/community.ts
• languages 相关接口

交付物

社区内容本地化

执行步骤

1. 1Community 增加 i18n 覆盖字段：name / tagline / desc / kind 按语言给值。
2. 2菜单项标签与规则文案走 translations 表/字典，以中文原文作为 key 查表，查不到回落中文。
3. 3utils/community.ts 的 resolveCommunity 增加 locale 参数，返回已本地化的对象 —— 保持全站唯一解析入口不变。

前置依赖

涉及文件 / 表

• app/data/feed.ts

交付物

双语信息流

执行步骤

1. 1把标题/摘要/标签/时间/投票选项/正文/评论的文案池按语言拆分，用 locale 选择池子。
2. 2播种 key 里带上 locale（hash(`${id}::${locale}`)），保证中英两版各自稳定且不互相影响。
3. 3保留同一套生成逻辑与深度上限，只换文案池 —— 结构不能因语言而变。

前置依赖

涉及文件 / 表

• app/composables/useLocale.ts
• 各页面 useHead

交付物

SEO 语言标注

执行步骤

1. 1每个页面输出 <link rel="alternate" hreflang="zh-CN" href="..."> 与 hreflang="en"，外加 x-default 指向协商结果。
2. 2htmlAttrs.lang 与当前语言一致，dir 跟随 languages.direction。
3. 3所有 hreflang 的 href 必须是绝对地址（含协议与域名）。

前置依赖

涉及文件 / 表

• app/pages/[locale]/tasks.vue
• 构建期统计脚本

交付物

翻译覆盖率看板

执行步骤

1. 1统计每个语言下：界面词典键覆盖率、社区内容覆盖数、文档页正文是否已翻译。
2. 2在看板上按页面列出状态（已翻译 / 部分 / 未翻译），并给出该页的 key 总数与已覆盖数。
3. 3覆盖率低于阈值时在页面上显式标红，不用绿色掩盖。

前置依赖

涉及文件 / 表

• app/i18n/docs/en/*.ts
• 各文档页

交付物

英文版文档正文

执行步骤

1. 1按页拆分翻译单元，每页一个模块，便于并行与增量。
2. 2技术名词保留英文原形（Nuxt、Meilisearch、megamenu），不要强行意译。
3. 3译完一页即把该页的覆盖率标记为已完成，不必等全部译完。

前置依赖

无 —— 可以立即开工

涉及文件 / 表

• app/components/Breadcrumb.vue
• app/pages/c/[community]/[...path].vue
• app/pages/c/[community]/post/[id].vue
• app/components/apps/StubPage.vue

交付物

无面包屑的页面结构

执行步骤

1. 1删除 Breadcrumb.vue 及全部 3 处引用。
2. 2StubPage 的位置指示改由卡片 header 承担：社区名 + 节点标题 + 上级入口（单个链接，不构成路径链）。
3. 3同步修改 /ui 规范页里 5 处描述面包屑的文案与示意图标注。

前置依赖

涉及文件 / 表

• app/components/SiteHeader.vue
• app/components/CommunityShell.vue
• app/components/LocaleSwitcher.vue

交付物

LocaleSwitcher 组件

执行步骤

1. 1桌面端放在右侧操作组内，形式为地球图标 + 当前语言短码（zh / EN），点击展开菜单。
2. 2移动端收进抽屉，与「社区目录 / 社区演示」并列。
3. 3切换器宽度固定，避免切换语言时顶栏产生横向位移（中英文字宽不同）。

前置依赖

无 —— 可以立即开工

涉及文件 / 表

• app/components/CommunityShell.vue
• app/components/MegaMenu.vue

交付物

无 hero 的社区页

执行步骤

1. 1删除 hero 区块；megamenu 上移到顶栏正下方（lg:sticky lg:top-14）。
2. 2顶栏 logo 改为显示社区名并链回社区主页。
3. 3原本重复的左栏「社区导航」删除，替换为「我的订阅」与「本社区热门标签」。

前置依赖

无 —— 可以立即开工

涉及文件 / 表

• app/components/CommunityShell.vue

交付物

顶栏布局

执行步骤

1. 1外层 flex-1 吃满剩余空间，内层固定 max-w-[560px] 并由外层 justify-center 居中。
2. 2不要用 flex-1 + max-w + mx-auto 的一行写法：auto margin 与 max-width 冻结顺序会让留白偏向一侧。
3. 3操作组用 ml-auto 贴右，并保证在窄屏不换行。

前置依赖

涉及文件 / 表

• app/assets/css/main.css
• 各页面

交付物

分语言排版规则

执行步骤

1. 1按 html[lang] 覆盖行高：中文 1.75，拉丁字母 1.6（拉丁字母视觉重心更高）。
2. 2长英文标识符（形如 components/apps/php/NewsPage.vue）允许在斜杠处断行。
3. 3不要对中文使用 letter-spacing 正值，会显得松散。

前置依赖

涉及文件 / 表

• app/layouts/default.vue
• app/assets/css/main.css

交付物

RTL 支持

执行步骤

1. 1html 的 dir 属性由 languages.direction 驱动，不在组件里写死 ltr。
2. 2把 margin-left / padding-right 这类物理属性逐步换成 margin-inline-start 等逻辑属性。
3. 3图标方向（返回箭头等）用 CSS 在 [dir=rtl] 下翻转，不用两套图标。

前置依赖

无 —— 可以立即开工

涉及文件 / 表

• app/**/*.vue

交付物

栅格基线

执行步骤

1. 1凡 class 里出现 grid 与 sm/md/lg/xl:grid-cols-N，必须同时有基础 grid-cols-1。
2. 2grid-cols-1 等价于 minmax(0,1fr)，最小值 0 才能真正收缩。
3. 3改代码必须逐行操作并断言字符增量，禁止跨行正则批量替换。

前置依赖

涉及文件 / 表

• app/components/PostComposer.vue

交付物

可用的发帖流程

执行步骤

1. 1提交时生成 client_token，POST /api/posts，处理 4xx 时把服务端 message 展示在表单内。
2. 2提交中禁用按钮并显示进度，防止重复提交。
3. 3成功后跳转到新帖详情页（用服务端返回的 slug/id），不留在弹层里。

前置依赖

无 —— 可以立即开工

涉及文件 / 表

• votes 表
• crates/ruyi-api/src/routes/votes.rs

交付物

投票链路

执行步骤

1. 1votes 表唯一键 UNIQUE(user_id, target_type, target_id)，值为 -1 / 1。
2. 2投票用 INSERT ... ON DUPLICATE KEY UPDATE 实现改票与撤票。
3. 3帖子/评论上的分数字段异步由 outbox_events 收敛，不在请求链路里同步更新。

前置依赖

涉及文件 / 表

• app/components/ThreadComment.vue
• app/pages/c/[community]/post/[id].vue

交付物

评论分页

执行步骤

1. 1详情页首屏仍加载 120 条（COMMENT_CAP），底部给出「继续加载」（Reddit 的 load more comments）。
2. 2按 path 游标翻页，不使用 offset（新增评论会导致重复/漏项）。
3. 3顶部计数同时展示「总数」与「已加载」，两个数字必须来自同一来源，避免自相矛盾。

前置依赖

无 —— 可以立即开工

涉及文件 / 表

• notifications 表
• notification_templates 表

交付物

通知系统

执行步骤

1. 1写入走 outbox_events，由后台消费者展开成 notifications 行，避免在请求链路里同步扇出。
2. 2未读计数用 Redis 计数器，登录时一次性种子化。
3. 3已读用 last_read_at 时间戳而不是逐行标记，减少写放大。

前置依赖

涉及文件 / 表

• Meilisearch 索引配置
• search 同步任务

交付物

检索索引与同步任务

执行步骤

1. 1建 communities / posts 两个索引，声明 searchableAttributes 与 sortableAttributes。
2. 2用 outbox_events 做增量同步，禁止在请求链路里同步写索引。
3. 3提供重建索引的幂等任务（全量重灌）。

前置依赖

涉及文件 / 表

• Meilisearch 同义词配置

交付物

多语言检索配置

执行步骤

1. 1按语言分别声明 locales，让分词器选对（中文需要 CJK 分词）。
2. 2维护跨语言同义词表，作为独立配置文件便于非开发同学维护。
3. 3搜索结果按用户语言加权，但不硬过滤（跨语言结果排在后面）。

前置依赖

无 —— 可以立即开工

涉及文件 / 表

• app/pages/c/index.vue

交付物

社区目录

执行步骤

1. 116 个领域分类 + 关键词搜索 + 4 种排序（活跃 / 成员 / 新增 / 字母）+ 3 档行密度。
2. 2排序与筛选逻辑集中在一处，避免列表与计数各算一遍导致数字对不上。
3. 3长列表用虚拟滚动或分页，并保证滚动位置在筛选变化时复位。

前置依赖

无 —— 可以立即开工

涉及文件 / 表

• mod_actions 表
• audit_logs 表

交付物

治理动作留痕

执行步骤

1. 1mod_actions 记录 actor / action / target / reason / created_at。
2. 2所有管理动作强制要求 reason，不接受空理由。
3. 3审计日志只追加不修改，并提供按目标与按操作者两种查询路径。

前置依赖

涉及文件 / 表

• bans 表
• appeals 表

交付物

封禁申诉

执行步骤

1. 1bans 支持临时与永久，临时封禁必须有 expires_at。
2. 2appeals 有明确状态机：pending → accepted / rejected，且终态不可回退。
3. 3不接受的申诉必须填写理由，展示给用户。

前置依赖

无 —— 可以立即开工

涉及文件 / 表

• /etc/nginx/sites-available/
• certbot

交付物

Nginx 配置 + 证书

执行步骤

1. 1location / → Nuxt SSR（127.0.0.1:3000），location /api/ → Rust（127.0.0.1:8080），location /search/ → Meilisearch。
2. 2证书用 certbot webroot 方式签发并配置自动续期。
3. 3响应头不要泄露服务器指纹与内部端口。

前置依赖

无 —— 可以立即开工

涉及文件 / 表

• mysqldump 定时任务
• 恢复演练脚本

交付物

备份策略 + 演练记录

执行步骤

1. 1每日全量 + binlog 增量，备份文件异地存放。
2. 2每季度做一次恢复到临时库的演练，并记录恢复耗时（RTO）。
3. 3备份文件加密，密钥不与备份同处存放。

前置依赖

涉及文件 / 表

• Redis 键名规范
• crates/ruyi-api/src/cache/

交付物

缓存层

执行步骤

1. 1键名统一前缀 ruyi:，按域分层（ruyi:sess: / ruyi:hot: / ruyi:idem:）。
2. 2热帖用 ZSET 维护，按时间窗滚动，不用全量重算。
3. 3所有键必须显式设置 TTL，禁止出现无过期键（用定期扫描兜底告警）。

前置依赖

无 —— 可以立即开工

涉及文件 / 表

• media_assets 表
• media_variants 表
• POST /api/uploads

交付物

媒体上传链路

执行步骤

1. 1前端直传对象存储（预签名 URL），不经应用服务器中转。
2. 2上传成功后回调写入 media_assets，异步生成 media_variants（缩略图/中图）。
3. 3列表页只引用缩略图变体，详情页才用原图。

前置依赖

无 —— 可以立即开工

涉及文件 / 表

• docker-compose.yml
• .env.example
• 部署文档

交付物

可复现部署

执行步骤

1. 1compose 声明 nginx / web / api / mysql / redis / meilisearch 六个服务与依赖顺序。
2. 2所有密钥与连接串走环境变量，仓库里只留 .env.example。
3. 3启动脚本幂等：重复执行不产生重复数据或端口冲突。

前置依赖

无 —— 可以立即开工

涉及文件 / 表

• e2e/audit.mjs

交付物

e2e/audit.mjs

执行步骤

1. 1遍历 320 / 360 / 390 / 480 / 640 / 768 / 900 / 1024 / 1180 / 1280 / 1366 / 1440 / 1600 / 1920。
2. 2断言两件事：documentElement 无横向溢出；无元素在 overflow:hidden 容器内被裁切。
3. 3排除三类误报：sr-only、aria-hidden、已带 ellipsis 的元素，以及已在滚动容器内的元素。

前置依赖

涉及文件 / 表

• e2e/i18n-smoke.mjs

交付物

e2e/i18n-smoke.mjs

执行步骤

1. 1对每个已启用语言，依次访问 首页 / 目录 / 社区页 / 帖子页 / tasks。
2. 2断言 HTTP 200、html lang 正确、页面内不出现其它语言的界面文案。
3. 3断言语言切换器在每页都能找到，且切换后 URL 前缀正确。

前置依赖

无 —— 可以立即开工

涉及文件 / 表

• e2e/a11y.mjs
• 各页面

交付物

可访问性报告

执行步骤

1. 1跑 axe-core，先清零 critical 与 serious 两级。
2. 2所有交互元素可 Tab 到达且有可见 focus 环。
3. 3图标按钮必须有 aria-label；菜单用 role=menubar 并支持方向键。

前置依赖

无 —— 可以立即开工

涉及文件 / 表

• 性能预算配置
• CI

交付物

性能预算与 CI 门禁

执行步骤

1. 1设定预算：单页 JS ≤ 180KB（gzip）、LCP ≤ 2.0s（4G 模拟）、CLS ≤ 0.1。
2. 2在 CI 中对首页、社区页、帖子页三条路径采集指标，超预算阻断合并。
3. 3社区菜单的异步组件必须按 slug 分包，不允许整包预载。