文档治理规范

本规范是影视CMS 文档（docs/）的单一事实源与变更准绳。任何文档改动必须遵循，确保文档始终与代码一致、无残留、无凭空。

一、核心原则：代码即真相

文档描述的每个功能、配置项、行为，都必须能在代码中找到对应实现。 找不到的一律不写。

• 写之前：先确认代码实现了什么（路由 / 控制器 / 服务 / 前端页面）
• 写之后：每条结论标注来源（功能页可省略行号，但改写时必须回溯代码）
• 存疑时：宁可少写，不凭空补。标注"未实现"或删除，不写"即将支持"

二、端支持必标

影视CMS 有四个客户端形态（Android 移动端、iOS 移动端、TV 端、网页端）+ 后台；两个移动端同出 movie_app 代码库，同一功能各端能力常不同。写任何功能页，必须明确端支持。

统一术语（不可漂移）

规范词	用于
移动端 APP（Android / iOS）	movie_app（自适应手机 / 折叠屏 / 平板）
TV 端	movie_tv
网页端	web-site
后台	web-admin

禁止混用"手机端/APP端/前端"等模糊词——移动端自适应手机、折叠屏与平板，"手机端"无法覆盖全形态。

标注方式

功能页开头或关键节用 VitePress 容器：

::: tip 支持范围
仅 **移动端 APP** 支持。TV 端和网页端不支持。
:::

或表格按端分列注明（如 matrix.md 的 Android 移动端 / iOS 移动端 / TV 端 / 网页端）。

矩阵为权威

/features/matrix 是各端能力对照的单一事实源。各功能页描述与矩阵冲突时，以矩阵为准（矩阵经代码核对）。新增功能时同步更新矩阵。

三、禁止内容（避免残留）

禁止	原因	替代
凭空功能（代码无实现）	误导用户	删除，或进 matrix 的"未实现"清单
拟物面板里的写死假数据（用户名/余额/日期）	非真实配置	功能清单表
营销词（简单/高效/极致/赋能/全方位）	无信息量	写具体能力
标题放 emoji	噪声	纯文字标题
"即将支持/未来计划"	易过期	不写，等实现再写

四、信息漂移治理（一致性）

同一信息在多处出现时，只在一处详细定义，其他处用链接引用。

信息	定义处	引用处
各端能力差异	matrix.md	各功能页 详见[功能矩阵]
VIP 开通方式	user.md	operations.md / payment.md 链接引用
安全措施清单	settings.md	其他页不重复列举
防盗版	operations.md	settings.md / authorization.md 链接引用

改了定义处，检查所有引用处是否需同步——用 grep 搜关键词定位。

五、变更流程（防止再次落后）

每次提交文档改动前，过这个清单：

1. 代码核对：改动描述的功能，代码确实有（贴 file:line 证据到 commit message 或 PR）
2. 端支持标注：涉及客户端的功能，已标端支持
3. 矩阵同步：新增/删除功能，matrix.md 已更新
4. 链接有效：内部链接 [文字](/path) 目标存在
5. 构建通过：cd docs && npm run docs:build 无报错、无死链
6. grep 自检：删掉的功能，grep -rn "关键词" docs/（排除 node_modules）无残留

六、目录职责（单一职责）

docs/
├── guide/        # 入门：简介、授权打包、部署（面向新用户）
├── features/     # 功能：按域分页 + matrix 矩阵（面向使用者）
├── system/       # 系统：设置与安全（面向管理员）
├── public/       # 静态资源：logo、图标、截图（被 .md 引用）
└── .vitepress/   # 配置与主题

• 功能描述进 features/，配置项进 system/settings.md，不混放
• 新增功能页必须在 config.mts 的 sidebar 注册，否则用户找不到
• 文件名用英文短横线（ai-chat.md），不用中文/下划线

七、已知未实现功能（勿写入）

经代码 grep 确认，以下功能当前未实现，文档不得描述：

• 签到、任务中心、每日任务
• 积分 / 金币体系
• 消息中心（仅有工单未读数 + WebSocket 事件推送）
• 追剧日历 / 排期
• 网页端字幕、网页端画质切换

实现后再写入，并从本清单中移除。

八、维护节奏

• 功能发布时：同步改文档（开发者的 PR 应含文档改动）
• 季度审计：按本规范全文 grep 自检一次（凭空词、漂移、死链）
• 矩阵为准：发现文档与实际不符，先改 matrix.md，再辐射各页