VW Corporate
项目接手报告

主要风险

• 授权判定散落在 24 个控制器方法体内，路由表不是权限的事实来源：Routes.php 里 105 条 API 只标了 auth/auth_no_mfa/logout_auth 三种过滤器，具体要什么权限码必须逐个方法读代码。新增接口时「忘了加 requirePermission」不会有任何静态或运行时告警，ContentController 与 ChannelController 就是这么整体漏掉的。
• 身份来源双轨（JWT claim 与 Session）且两条路径校验强度不同：requirePermission 查库（含 is_active），requireRoles 只信 JWT。任何涉及禁用账号、角色降级、强制下线的需求，在当前实现下都无法在 token 有效期内生效。
• user_sessions 表的吊销语义只写不读，「禁止并发登录」「登出即失效」两个安全承诺目前是纸面功能。改动认证链路时若不先补上 jti 校验，会持续误以为这些机制已生效。
• confirm_token（二次确认）的 operation 字符串是纯约定：签发方 AuthController::confirmToken 与消费方各控制器靠字面量对齐（content_delete / content_publish / dam_force_delete / rbac_manage / user_reset_mfa 等十余种），没有常量表也没有集中注册。写错一个字符串的后果是「二次确认永远失败」，且只有跑到线上才发现。
• 错误码 1xxx-9xxx 的分段是口头约定而非枚举：同一个 4000/4001/4004 在 DAM、栏目、分类三个域里含义不同，3001/3005/3006/3007/3008 在内容、FAQ、关联三处复用。前端按 code 做分支时极易误判。
• 非 API 的三条交付路径（/AdM SPA 回退、/asset/:id、/page-css/:file）绕开了 ApiController 的响应封装与审计，各自手写鉴权与响应，其中 /asset 的 JWT 分支是坏的、/page-css 完全无鉴权（靠文件名正则防目录穿越）。

---

和 CMS 的其余部分相比，HTTP 层的代码本身不难读——写法高度重复，几乎每个方法都是「取当前用户 → 校权限 → 取参数 → 调 Service/Model → 写审计 → 返回封装」。真正的风险不在于看不懂，而在于这一套模板在若干控制器里被整段跳过了，而路由表上看不出任何区别。接手第一件事应该是拿本文的接口清单表逐条核对，而不是相信 Routes.php。

一、边界与规模

范围内共 33 个文件、7,942 行：app/Config/Routes.php（172 行）、app/Config/Filters.php（116 行）、app/Controllers/ 下 4 个非 API 控制器（AdminController 36、AssetDeliveryController 173、BaseController 45、Home 11）、app/Controllers/Api/ 下 24 个控制器（7,238 行，最大的是 ContentController 852 行、AuthController 769 行、DamController 645 行、UserController 569 行）、app/Filters/ 下 3 个过滤器（151 行）。

Routes.php 里共 111 条路由声明（GET 47 / POST 31 / PUT 22 / DELETE 11），其中 6 条是非 API 路径，105 条在 api 分组内（namespace 为 App\Controllers\Api⁠）。自动路由已关闭（Config/Routing.php:97 autoRoute = false⁠），所以路由表是穷尽的——不存在「没写在 Routes.php 里但能访问到」的控制器方法。

二、鉴权管线：三个 Filter 的差异

Config/Filters.php:30-43 注册了三个自研过滤器，全局过滤器（$globals⁠，:79-89）与按方法/按 URI 的过滤器（$methods :104、$filters :115）全部为空⁠——csrf、invalidchars、secureheaders、honeypot 都被注释掉了。也就是说：除了路由上显式声明的那一个过滤器，请求不经过任何其他前置处理⁠。$required.before 里的 forcehttps 因为 Config/App.php:160 forceGlobalSecureRequests = false 而是空转。

AuthFilter.php:21-35 的关键逻辑：JWT 优先，JwtService::verify 失败（含过期）就静默回退到 Session。三个过滤器都不查库⁠——不校验 users.is_active⁠，不查 user_sessions.revoked_at⁠。

完整鉴权管线共四层，每层都可能缺席：

1. 过滤器层（路由声明）：登录 + MFA。
2. 控制器入口层⁠：多数方法会再写一遍 $userId = $this->getCurrentUserId(); if (!$userId) return $this->fail('未登录', 1001);⁠——这是对 auth 过滤器的冗余重复，但也是 preview/access 这类无过滤器接口的唯一防线。
3. 权限码层⁠：ApiController::requirePermission()（:200）查库，或 requireRoles()（:215）读 JWT claim。这一层在 ContentController、ChannelController 的 CRUD、DashboardController、EntryRelationController、FaqPageController、SearchController、SeoConfig 读接口、SystemConfig 读接口里完全不存在⁠。
4. 对象级层⁠：created_by == $userId || role === 'sys_admin'（ContentController.php:493/:719、FaqQuestionController.php:233、FaqTopicController.php:182、FaqPageController.php:84、EntryRelationController.php:83），以及工作流的栏目级授权 WorkflowService::checkChannelPermission（WorkflowController.php:48/:122/:196）。二次确认 confirm_token 也归在这一层。

权限码校验的实现在 PermissionService::hasPermission（:23-49）：查 role_permissions ⋈ roles ⋈ permissions⁠，要求 roles.is_active = 1⁠，并且明确注释了「不做 sys_admin 特例」⁠——这点必须记住：sys_admin 如果在角色管理里没被授予某权限码，一样会被拒。

三、JSON 响应封装与错误码分段

封装定义在 ApiController.php:47-70⁠，四个字段固定：

success: HTTP 200, { code: 0, message, data, trace_id }
fail:    HTTP 400, { code: <业务码>, message, data, trace_id }

注意三个坑：其一，fail 恒定 HTTP 400⁠，业务语义全在 body.code；而过滤器返的是 401/403（AuthFilter.php:39-58），两套语义并存。其二，trace_id 是 bin2hex(random_bytes(8)) 现场生成的（:53、:68），与 AuditLogger.php:47 写进 operation_logs.trace_id 的那个（16 字节）毫无关系⁠，拿用户报的 trace_id 去审计表里查是查不到的。其三，路由未命中和未捕获异常走 CI4 的 HTML 错误页（Config/Routing.php:87 override404 = null⁠），而前端 admin-frontend/js/api/index.js:88 只按 data.code !== 0 判断，遇到 HTML 会直接解析炸掉。

两个接口不走封装⁠：GET /api/audit/export 返回 text/csv 带 BOM（AuditController.php:161-164），GET /asset/:id 返回文件二进制。

错误码分段（从 24 个控制器里逐个 fail 调用统计得出，注意这是事后归纳的约定，不是枚举常量）：

分段并不互斥⁠：4000/4001/4004 在 DAM、栏目、分类三处含义不同；3001/3006/3007/3008 在内容、FAQ、关联三处复用；「无权限」有 6001、6101、4031、3006 四种写法。前端做分支判断时必须结合接口路径，不能只看 code。

四、完整接口清单（按业务域）

「权限」列写的是控制器内实际执行的校验；标注「无⁠」的是只有过滤器把关、控制器内零校验，这些就是本次审计的主要发现。

4.1 非 API 路径（6 条）

4.2 认证与会话（11 条）

4.3 内容（9 条）——全域无权限码

4.4 栏目（8 条）——CRUD 无权限码

4.5 工作流与发布（8 条）

4.6 DAM（16 条）

4.7 用户与 RBAC（11 条）

4.8 审计、配置、搜索、FAQ、Figma、预览、仪表盘（其余 42 条）

五、三条非 API 路径的机制

/AdM SPA 回退（Routes.php:20-21 + AdminController.php:18-35⁠）：(:any) 在 CI4 里编译成 (.)⁠，所以 /AdM/任意/多级/路径 都会命中同一个控制器，返回 FCPATH . 'AdM/index.html' 的内容，并强制 Cache-Control: no-cache, no-store, must-revalidate⁠。静态资源不会走到这里的原因在 public/.htaccess⁠：RewriteCond %{REQUEST_FILENAME} !-f 让实际存在的文件（/AdM/assets/.js 等）由 Apache 直接吐出。这意味着换 Nginx 部署时必须手工复刻这条 !-f 判断，否则 SPA 的 JS/CSS 会全部被当成路由返回 HTML。 文件缺失时返回 404 纯文本「管理后台前端文件未找到，请先构建前端应用。」——看到这句话就是前端没构建或没同步到 public/AdM/⁠。

资产交付鉴权（AssetDeliveryController.php:37-104⁠）：查 assets → 若有 category_id 则查分类的 access_level⁠；只有 auth 级才拦截，public 直接放行。身份识别顺序是 Session 优先、JWT 兜底——但 JWT 分支在 :59 写错了（详见缺陷清单），会 500。通过后按 ?quality=high 选变体，从 WRITEPATH . storage_key 读文件，用 file_get_contents 一次性载入内存后 setBody 返回。注意这里没有 Range 支持、没有流式输出⁠，大视频会把整个文件读进 PHP 内存；也没有 Content-Disposition 的文件名转义（:102 直接拼 $filename⁠）。/asset/:id/info 是同一套判断的只读版本，返回 requires_auth⁠、can_access⁠、qualities 供前端决定是否弹登录。

page-css 交付（PageCssDeliveryController.php:17-43⁠）：这是三条里防护做得最规矩的一条。先 basename() 去掉路径成分，再用正则 ^page-\d+(?:-[a-z]+)?-\d{8}-\d{6}-[a-f0-9]{6}\.css$ 严格白名单（:21），然后拼 WRITEPATH + Config/Figma.php 的 cssDir(uploads/page-css)⁠，返回 text/css 并带 Cache-Control: public, max-age=300⁠。文件名由两处生成且格式一致：FigmaController::attachPreviewCssUrlIfNeeded（:161-165，预览用）与 EntryCssVersionService（:66-69，落盘版本用），都是 date('Ymd-His') + substr(sha1(...), 0, 6)⁠。改动任一处的文件名格式，必须同步改这条正则，否则 CSS 全部 404。 该路径不做任何鉴权——CSS 内容被视为公开资源。

六、接手前必须知道的隐式约定

1. getVar() 与 getJsonPayload() 混用⁠。CI4 的 getVar() 对 JSON 请求返回 stdClass 而非数组，所以 ApiController::getJsonPayload()（:234-254）做了归一化。但大部分控制器仍直接用 getVar('field') 取单字段（对 JSON body 是能工作的），只有需要整包的地方才用 getJsonPayload()⁠。ContentController::update 里两种混着用（:499-501）。PUT + JSON 的场景还有第三种写法：getJSON(true) → getVar() → getRawInput() 三级回退（WorkflowController.php:301-307、SystemConfigController.php:62-68、RoleController.php:146-149）。新写接口时照抄最近的那个就行，别自创第四种。
2. 审计是手写的，不是切面⁠。每个需要留痕的分支都要显式调 AuditLogger::log(module, operation, {actor_id, actor_role, object_type, object_id}, result, error_code, request_summary, $request)⁠。漏写不会报错，只会在合规检查时暴露。唯一自动化的是 failForbidden()（ApiController.php:159-195），它会按 AuditPolicyService::shouldLogAccessDenied() 决定是否记 access_denied⁠，并同时喂给 AuditAnomalyService⁠。
3. confirm_token 的 operation 是裸字符串约定⁠。签发端 AuthController::confirmToken 不校验 operation 取值合法性，消费端各自 verify($token, $userId, '<字面量>')⁠。目前在用的有 content_delete、content_publish、content_unpublish、dam_delete、dam_force_delete、faq_question_delete、faq_topic_delete、preview_revoke、rbac_manage、user_delete、user_reset_password、user_reset_mfa。拼错一个字母的表现是「二次确认永远失败」。
4. requireRoles 和 requirePermission 强度不同⁠，见缺陷 3。需要「立即生效」的权限变更，只能用 requirePermission⁠。
5. ContentController::index 的 channel_id 过滤是手拼 SQL（:63-71）：JSON_CONTAINS(channel_id, CAST('[17]' AS JSON), '$')⁠，先 $db->escape() 再拼串、并用 where(..., null, false) 关掉转义。改这里要格外小心；$cid 已经 (int) 过，目前是安全的。类似的裸 SQL 还有 DamController::assets 的 EXISTS(...)（:256-261）和 FAQ 列表里 join(... 'i.lang = ' . $db->escape($lang))（FaqQuestionController.php:46、FaqTopicController.php:39、FaqPageController.php:43、EntryRelationController.php:42）。
6. CSP 是开着的（Config/App.php:201 CSPEnabled = true⁠，策略见 Config/ContentSecurityPolicy.php⁠，script/style 均为 self⁠、autoNonce=true）。这就是 Figma 导入必须把 CSS 落盘成外部文件而不能内联 <style> 的原因（FigmaController.php:113-115 的注释写明了）。
7. WorkflowService.php:63 等处往 EntryModel 的 ?datetime cast 字段塞字符串导致工作流提交 500 这个已知缺陷，从 HTTP 层看表现为 POST /api/workflow/submit 返回 CI4 的 HTML 错误页而非 JSON——前端会显示成网络错误，排查时容易被误导到接口层，实际要去 Service 层修。

七、修复建议的优先级

第一批（阻断上线）：给 ContentController 与 ChannelController 的 CRUD 补 requirePermission⁠；删掉 public/test-putenv.php⁠。第二批（安全基线）：requireRoles 改为查库并校验 is_active⁠；AuthFilter 增加 is_active 与 user_sessions.revoked_at 两项检查（这一步同时把「登出即失效」和「禁止并发登录」两个功能真正接通）。第三批（可用性）：修 AssetDeliveryController 的 stdClass 下标 bug；把 trace_id 打通到审计；给 /api/* 加一个 JSON 版的 404 与异常处理器（Config/Routing.php 的 override404 + 自定义 ExceptionHandler）。

建议同时做一件结构性的事：把权限码从控制器方法体里挪到路由声明上（CI4 的 filter 支持传参，['filter' => 'perm:content:edit']⁠），这样 Routes.php 就重新成为授权的事实来源，「新接口忘了加校验」会在 code review 时一眼可见。这项改造约需 3 人天，但能一次性消除本次审计里最主要的一类风险。

主要风险

• 干净库不可重建：迁移 2026-03-04-100031 的 created_by=1 + RESTRICT 外键把 51 条迁移卡在第 33 条，加上数据库导出缺失、RolePermissionSeeder 必须手动执行且非幂等，本模块目前不具备「一条命令从零起环境」的能力，灾难恢复严重依赖生产库的物理备份——而备份本身也不在交接物里。
• 隐式约定密度高且无文档承载：entries.channel_id 是 JSON 数组而非外键、draft_of_entry_id 表示「已发布内容的编辑副本」、asset_categories 靠中文名 '网站素材' 字符串定位根节点、封面同时存在 entries.cover_asset_id / entry_i18n.og_asset_id / asset_entry_i18n(role=thumbnail) 三套机制。这些只在注释和代码里，任何一处误改都会在前台静默表现为「图没了」而非报错。
• DataCaster 时间字段是运行时地雷：同一个 EntryModel，publish_at 等字段必须传 CodeIgniter\I18n\Time 对象，传字符串直接抛异常；而 UserModel 通过重写 setUpdatedField / transformDataToArray / convertToReturnType 三个框架方法来规避同一问题（UserModel.php:45-230）。新人按 UserModel 的写法去改 EntryModel，或反过来，都会踩坑，且错误只在特定接口被调用时才暴露。
• 写入路径缺事务与缺校验叠加：25 个 Model 全部没有 validationRules，内容创建（ContentController.php:348-446）无事务，权限的 scope 字段是假开关。数据完整性完全依赖 MySQL 的严格模式与外键，换环境（sql_mode 不同）或删除 id=1 用户，都会以难以定位的方式出问题。
• 模式定义存在双写：sitecore_files_import / sitecore_news_import 由迁移和 Python 脚本各建一份（collation 不同），role_permissions 由迁移 100051 和 Seeder 各写一份 figma:import。真实 schema 取决于执行顺序，无法只靠读迁移目录推断线上表结构，必须以生产库的 SHOW CREATE TABLE 为准。

---

一、范围与总体判断

本文覆盖 /Volumes/ProjectsAPFS/VWCORP/w2r.site/backend 的整个持久层：app/Database/Migrations/ 全部 51 个迁移、app/Database/Seeds/RolePermissionSeeder.php⁠、app/Models/ 全部 25 个模型、app/Config/Database.php⁠，合计 78 个文件、约 5,895 行。

一句话结论：表设计本身是合格的企业 CMS 结构（双语分表、两级审核、DAM 引用计数、RBAC 三表），但迁移链在干净库上跑不通，且有大量约束不在数据库、也不在模型，而是散落在 Service/Controller 里。 接手者可以放心读表结构，但不能假设「迁移目录 = 线上 schema」。

---

二、35 张表的最终形态

数据库连接见 app/Config/Database.php:27-52⁠：MySQLi、utf8mb4 / utf8mb4_general_ci、DBPrefix 为空、strictOn = false（不主动追加 STRICT_ALL_TABLES，实际严格性取决于服务器 sql_mode）。凭据全部走 .env（键名见 backend/.env:25-31⁠，值不在此转录）。迁移状态表名 migrations⁠，时间戳格式 Y-m-d-His_（app/Config/Migrations.php:29,47⁠）。

以下按功能域分组，34 张业务表 + 1 张框架 migrations 表 = 35。

2.1 账号与安全（5 张）

2.2 RBAC（4 张）

2.3 内容（8 张）

2.4 FAQ 子域（5 张，2026-01-24-100013 一个迁移建全）

faq_questions（题库主表，status draft/published/archived）、faq_question_i18n（UK question_id+lang）、faq_topics（UK slug）、faq_topic_i18n（UK topic_id+lang）、faq_question_topics（多对多）、faq_page_questions（把题目挂到 entries.type='faq_page' 的页面上，UK entry_id+question_id）。共 6 张——注意这一个迁移建了 6 张表，是全仓最大的单个迁移（313 行）。

2.5 资产 / DAM（7 张）

2.6 搜索与迁移临时表（4 张）

search_hotwords（lang+keyword 热词，带 start_at/end_at 生效窗口）、search_pins（关键词置顶到某 entry，UK lang+keyword+entry_id）、sitecore_files_import（100034⁠，31 列的 Sitecore 文件导入落地表）、sitecore_news_import（100044⁠，Sitecore 新闻导入落地表，UK sitecore_id+language_val）。

---

三、核心实体关系图

erDiagram
    USERS ||--o{ ENTRIES : "created_by (RESTRICT)"
    USERS ||--o{ ASSETS : "created_by"
    USERS ||--o| MFA_SECRETS : "1:1 totp"
    USERS ||--o{ USER_SESSIONS : "jti"
    USERS }o--|| ROLES : "users.role = roles.code 字符串，无 FK"

    ROLES ||--o{ ROLE_PERMISSIONS : ""
    PERMISSIONS ||--o{ ROLE_PERMISSIONS : ""
    ROLES ||--o{ CHANNEL_ROLE_PERMISSIONS : ""
    PERMISSIONS ||--o{ CHANNEL_ROLE_PERMISSIONS : ""
    CHANNELS ||--o{ CHANNEL_ROLE_PERMISSIONS : "栏目级 allow/deny"

    CHANNELS ||--o{ CHANNELS : "parent_id 自引用"
    CHANNELS ||--o| ASSET_CATEGORIES : "UK channel_id 镜像栏目树"
    CHANNELS }o..o{ ENTRIES : "entries.channel_id 是 JSON 数组，无 FK 无索引"

    ENTRIES ||--o{ ENTRY_I18N : "UK(entry_id,lang) zh/en"
    ENTRIES ||--o| ENTRIES : "draft_of_entry_id 修订稿"
    ENTRIES ||--o{ ENTRY_RELATIONS : "entry_id"
    ENTRIES ||--o{ ENTRY_RELATIONS : "related_entry_id"
    ENTRIES ||--o{ WORKFLOW_ACTIONS : "状态流水"
    ENTRIES ||--o{ PREVIEW_TOKENS : "预览链接"
    ENTRIES ||--o{ ENTRY_CSS_VERSIONS : "Figma 导入样式版本"
    ENTRIES ||--o{ FAQ_PAGE_QUESTIONS : "type=faq_page 时组装题目"

    ENTRY_I18N ||--o| ASSET_ENTRY_I18N : "UK(entry_i18n_id,role) 每语言一张封面"
    ASSETS ||--o{ ASSET_ENTRY_I18N : ""
    ASSETS ||--o{ ASSET_REFS : "引用计数，删除保护"
    ASSETS ||--o{ ASSET_VARIANTS : "UK(asset_id,quality) 高清变体"
    ASSET_CATEGORIES ||--o{ ASSETS : "category_id SET NULL"
    ASSET_CATEGORIES ||--o{ ASSET_CATEGORIES : "parent_id 树"
    UPLOAD_SESSIONS ||--o{ UPLOAD_CHUNKS : "FK 指向 upload_id 唯一列"
    UPLOAD_SESSIONS ||--o| ASSETS : "合并后产出 asset_id"

    FAQ_QUESTIONS ||--o{ FAQ_QUESTION_I18N : ""
    FAQ_QUESTIONS ||--o{ FAQ_QUESTION_TOPICS : ""
    FAQ_TOPICS ||--o{ FAQ_QUESTION_TOPICS : ""
    FAQ_TOPICS ||--o{ FAQ_TOPIC_I18N : ""
    FAQ_QUESTIONS ||--o{ FAQ_PAGE_QUESTIONS : ""

---

四、内容模型的概念解释（最需要先理解的一节）

4.1 channels：栏目树，同时是三种东西的锚点

channels 是自引用树（parent_id⁠），双语字段直接平铺在主表上（name_zh/name_en/slug_zh/slug_en⁠），不像 entries 那样分 i18n 表——这是全仓第一个不一致点。它承担三个职责：内容归属、栏目级权限（channel_role_permissions⁠）、以及资产分类的镜像源（asset_categories.channel_id 唯一外键）。i18n_strategy 列（loose/strict）决定提交审核时是否强制要求英文完整，判定逻辑在 WorkflowService.php:231-255⁠。

4.2 entries + entry_i18n：语言无关骨架 + 每语言正文

entries 存所有与语言无关的东西：类型、栏目、状态、时间线、审核痕迹、排序、置顶。entry_i18n 每条 entry 最多两行（lang ENUM 只有 zh/en，UK(entry_id,lang)），存标题、摘要、正文 content_json⁠、slug⁠、SEO 字段、附件 files JSON、结构化数据 schema_json⁠。中英不是「翻译对」而是「同一骨架下的两份内容」——英文可以完全缺失（loose 策略下只警告，WorkflowService.php:250-252⁠）。

content_json 名字有误导：它既可能是编辑器的 JSON，也可能是纯 HTML 富文本。AssetRefService::refreshEntryRefs（AssetRefService.php:52-68⁠）先尝试 json_decode⁠，失败就当 HTML 用正则扫 data-asset-id 和 /asset/{id}⁠。content_text 是从中抽出的纯文本，专供 FULLTEXT 搜索。

4.3 channel_id 是 JSON 数组，不是外键

2026-02-10-100030 把 entries.channel_id 从 BIGINT 改成 JSON（[1] 或 [1,2]⁠），为的是让新闻可以同时挂多个栏目。代价是删掉了外键和索引，并且再没补回⁠。取「主栏目」的约定是取数组第 0 个元素，封装在 EntryModel::primaryChannelId()（EntryModel.php:85-92⁠）——工作流查 i18n_strategy、权限查栏目授权都走它。筛选则用 JSON_CONTAINS（ContentController.php:70⁠），全表扫描。

4.4 uuid：对外标识

entries.uuid 是 CHAR(36)，从 Sitecore 新闻迁移时直接复用源站 itemid（回填 SQL 见 2026-02-09-100029:28-32⁠），其余条目用 EntryModel::generateUuid()（:134-141⁠）生成。所有对外 API 既接受数字 id 也接受 uuid，统一由 EntryModel::resolveId()（:97-105⁠）解析。主键仍是自增 id，外键全部用 id。

4.5 草稿与已发布：两套并存的机制

第一套是状态机⁠。entries.status 六态：draft → review_l1 → review_l2 → published⁠，另有 unpublished（手动下线）、expired（到期自动下线）。每一次跃迁写一行 workflow_actions 流水。审核级数可配（config 表 key=workflow.rules 的 review_levels⁠，WorkflowService.php:93-95⁠），设为 1 时初审通过直接发布。

第二套是修订稿（draft_of_entry_id⁠）⁠。已发布内容不能直接编辑，必须先「生成修订稿」：EntryDraftService::createDraftFromPublished()（:40-104⁠）克隆出一条新 entry，status='draft'⁠、draft_of_entry_id 指向原条目，并连带克隆 i18n、缩略图关联、entry_relations、faq_page_questions、CSS 版本。修订稿在列表页被过滤掉（ContentController.php:77 的 draft_of_entry_id IS NULL⁠），只通过正式条目的 edit_draft_id 字段暴露。发布修订稿时走 publishDraftOverOriginal()（:111-162⁠）：把内容合并回原条目、原条目保持 published、然后删除修订稿⁠。所以修订稿是临时物，不是版本历史——本系统没有内容版本历史，只有 CSS 有（entry_css_versions⁠）。

4.6 封面图有三条路径，这是最容易踩的坑

1. entries.cover_asset_id⁠——建表时就有，但没有外键，且当前控制器写入路径不用它；
2. entry_i18n.og_asset_id⁠——SEO 分享图，按语言；
3. asset_entry_i18n（role='thumbnail'）——实际在用的封面⁠，UK(entry_i18n_id, role) 保证每语言每角色一张，读取见 ContentController.php:100-114（优先中文、回退英文），写入见 :429/:437（用 MySQL REPLACE INTO⁠）。

asset_refs 是第四张相关表，但它不是封面，而是引用索引⁠：每次内容保存后 AssetRefService::refreshEntryRefs() 先删后建，扫出内容里引用的所有 asset_id，供 DAM 删除保护使用（有引用则禁止删除）。asset_variants 则是同一逻辑资产的高清版本（Sitecore EntityList 里的 HD 文件），UK(asset_id, quality)。

---

五、RBAC 数据模型与 22 个权限点

5.1 判定链路

users.role（字符串）→ roles.code → role_permissions → permissions.code⁠。判定代码在 PermissionService::hasPermission()（:40-49⁠），三表 join 且要求 roles.is_active=1⁠；注释明确写了不做 sys_admin 特例⁠，超管的全部权限来自数据。前端菜单靠 getPermissionCodes()（:101-108⁠）返回的 code 数组驱动。

栏目级授权是第二层：WorkflowService::checkChannelPermission()（:197-229⁠）查 channel_role_permissions⁠，deny 优先于 allow，无记录默认放行⁠，且 sys_admin 在这一层被硬编码短路（:199-201⁠）——与上一层的「不做特例」互相矛盾，是设计不一致处。

permissions.requires_confirm / requires_mfa 两个标志位驱动二次确认与 MFA 复验。

5.2 7 个角色（RolePermissionSeeder.php:28-36⁠）

editor 内容编辑 / reviewer_l1 初审 / reviewer_l2 终审 / publisher 发布人 / dam_admin 资产管理员 / sys_admin 系统管理员 / audit_readonly 只读审计。

5.3 22 个权限点（RolePermissionSeeder.php:53-93⁠）

授权矩阵共 58 条：editor 8、reviewer_l1 7、reviewer_l2 8、publisher 8、dam_admin 3、sys_admin 全部 22、audit_readonly 2。注意 content:edit_all 只给了 sys_admin；publisher 没有 content:submit⁠。

figma:import 存在两个来源：2026-04-29-100051 迁移（幂等追加）和 Seeder 第 92 行。哪个生效取决于执行顺序，Seeder 会 DELETE 全表重来，所以最终以 Seeder 为准。

5.4 scope 是假开关

role_permissions.scope（own/all）在界面上可编辑（RoleController.php:199-206⁠）、会被导出到配置包（ConfigPromotionService.php:120⁠），但判定代码从不读它⁠。真正的「只能改自己的」是硬编码的 created_by != userId && role !== 'sys_admin'（如 EntryDraftService.php:59⁠、:176⁠）。改 scope 不产生任何行为变化，这一点必须写进运维手册，否则会有人以为改了权限。

---

六、迁移在干净库上的可重放性 —— 逐条排查结论

按时间戳顺序执行 51 条，逐条评估结果如下（只列有问题的）：

硬阻断（1 条）

• 2026-03-04-100031:35 插入「网站素材」根分类时 created_by => 1⁠，而 asset_categories.created_by 是 RESTRICT 外键（100024:64⁠）。干净库 users 为空 → MySQL 1452 → 迁移在第 33 条中断。后续 18 条全部不执行。绕过方式：先 spark migrate --to 2026-02-25-100000⁠，再 spark admin:create-super⁠，再继续 migrate；根治方式是把 created_by 改成动态取 SELECT MIN(id) FROM users⁠，或新增一条「引导管理员」迁移排在 100024 之前。

数据错位（2 条）

• 2026-03-12-100042:17 把 7 个 Sitecore channel GUID 映射到 asset_categories.id 2–8。这些 id 是原开发者机器上 100031 同步既有栏目树后的偶然结果，干净库上 asset_categories 只有 id=1。
• 2026-03-04-100032 合并重复「网站素材」根节点，是针对 100031 被重复执行过的历史数据修复；干净库上 count($rows) <= 1 直接 return，无害但也说明 100031 曾在生产上跑重过。

约束可能没建上（1 条）

• 2026-02-09-100029:21 用 forge->addColumn(['uuid' => [... 'unique' => true]]) 声明唯一性。CI4 的 ALTER TABLE ADD COLUMN 路径对 unique 属性的处理不保证生成索引，全仓也没有别的地方建这个唯一键。接手第一步：SHOW INDEX FROM entries WHERE Column_name='uuid' 核实⁠，缺了就补。

不幂等 / 重跑必炸（4 条）

• 2026-01-27-100025:24-25（idx_category_id⁠、fk_assets_category⁠）、2026-03-04-100031:15-24（idx_parent_id⁠、fk_asset_categories_parent⁠、uk_channel_id⁠、fk_asset_categories_channel⁠）、2026-03-11-100036:30（idx_sitecore_id⁠）都是无守卫的裸 DDL。由于 100031 本身会中途失败，它前半段的 ALTER 已经生效但迁移未记账，重跑必然撞 Duplicate key name，只能手工 DROP 后重来。
• 反面样板：100041（先查 INFORMATION_SCHEMA 再建 UK）、100040（tableExists 守卫）、100043（fieldExists 守卫）、2026-02-25-100000（fieldExists 守卫）写得是对的。

静默降级（1 条）

• 2026-01-24-100021:24-28 建 FULLTEXT 索引整个包在 try/catch 里，失败不报错不记录。搜索会静默退化成 LIKE（SearchService.php:103-109 有运行时探测与回退，所以不会 500，但也永远不会有人发现索引没建上）。

前缀 / 环境假设（2 条）

• 2026-02-10-100030:19-27,41 混用带前缀（getPrefix()⁠）与不带前缀的字面表名，且删索引时用 LIMIT 1 取 STATISTICS 第一行——若 channel_id 参与了复合索引，会删错索引。
• 2026-03-12-120000:33-42 对 LONGTEXT 的 meta_json 调 JSON_EXTRACT⁠。干净库 assets 为空无事；从生产备份恢复时，只要有一行 meta_json 不是合法 JSON，MySQL 8 报 3141 中断迁移。

down() 有损（3 条）

• 100030 的 down 用 $[0] 把 JSON 压回单值，多栏目关联丢失；100032 的 down 是空实现；100031 的 down 直接 DELETE 所有 channel_id 非空的分类。这一层没有安全回滚，rollback 前必须先备份。

跨源双写（2 条）

• sitecore_files_import / sitecore_news_import 同时由迁移（100034⁠、100044⁠）和 Python 脚本（scripts/import_sitecore_files.py:321⁠、scripts/import_sitecore_news.py:306⁠，CREATE TABLE IF NOT EXISTS⁠）创建，脚本显式用 utf8mb4_unicode_ci⁠，迁移走默认 utf8mb4_general_ci⁠。先跑脚本则迁移静默跳过（createTable(..., true)⁠），两条路径产出的 collation 不同。

迁移与 Seeder 互相依赖

• 2026-04-29-100051 需要 roles/permissions 表里已有数据，而这些数据只来自 Seeder。干净库上它会 continue 掉所有角色授权、只插一条 permission；随后 Seeder 又把 permissions 全表 DELETE 重来。最终结果正确纯属巧合（Seeder 列表里也有 figma:import）。正确的新库启动顺序是：migrate（含 100031 绕过）→ spark admin:create-super → spark db:seed RolePermissionSeeder⁠，且 Seeder 在已有库上禁止重跑。

---

七、模型层的实现约定与坑

1. DataCaster 时间字段⁠：CI4 4.7 的 datetime cast 在写入时只接受 CodeIgniter\I18n\Time 实例。EntryModel.php:50-59 把 8 个时间字段声明成 ?datetime⁠，于是 WorkflowService.php:63 传字符串就抛异常（提交审核 500）；同一个 Service 的 :99/:112/:128/:131/:157/:159/:174/:177/:276 是同样的写法。正确样板是 PublishService.php:27/118/134 与 AssetRefService.php:145-148（返回 Time 对象）。
2. UserModel 的三个方法重写（:45-59 setUpdatedField、:65-151 transformDataToArray、:188-230 convertToReturnType）以及 updateLastLogin() 直接走裸 SQL（:235-249⁠），全都是为了绕开同一个 cast 问题。注释里写得很直白（:30-32⁠）。不要把 UserModel 的写法照搬到别的模型，也不要给 UserModel 加回时间字段的 cast。
3. useTimestamps 混用⁠：EntryModel/EntryI18nModel/ChannelModel/ConfigModel 等开启（框架自动写 created_at/updated_at），AssetModel/AssetRefModel/WorkflowActionModel/PreviewTokenModel 等关闭并把 created_at 放进 allowedFields 由调用方自己传。判断依据是模型里的 protected $useTimestamps⁠，没有统一规则。
4. JSON cast 只在模型路径生效⁠：EntryModel 的 channel_id => 'json'（:47⁠）让模型查询返回 PHP 数组，但 SearchService.php:88 用裸 builder 查同一列，返回的是原始 JSON 字符串。所以同一个字段在不同 API 里类型不一致，前端要两套处理（ContentController::normalizeChannelIdForResponse 就是补丁）。
5. 8 张表没有模型⁠：roles / permissions / role_permissions / channel_role_permissions / user_sessions / audit_rate_buckets / asset_entry_i18n / 两张 sitecore 导入表，全靠 $db->table('...') 裸写。改这些表结构必须全仓 grep。
6. 全部模型没有校验规则⁠：25 个模型的 $validationRules 都是空数组，唯一的输入校验散在控制器里，且很不完整（ContentController.php:327-329 的报错文案说「类型、栏目、中文标题和slug不能为空」，实际只检查了栏目）。

---

八、接手第一周建议动作

1. 先在跑通的 Docker 库上导出 SHOW CREATE TABLE（34 张）作为真实 schema 基线⁠，不要以迁移目录为准；重点核实 entries.uuid 的唯一索引、ft_entry_i18n_search 是否存在、两张 sitecore 表的 collation。
2. 补一条迁移修掉 100031 的 created_by（或加引导管理员迁移），使 spark migrate 在空库上一次跑通；这是恢复能力的前提。
3. 修 WorkflowService 的 9 处时间字符串（改成 Time::now(config('App')->appTimezone)⁠），并给 ContentController::create 包事务、补 type/title/slug 校验。
4. 给 entries.channel_id 建生成列 + 索引（或改成 entry_channels 关联表），恢复栏目筛选的可扩展性与引用完整性。
5. 把 role_permissions.scope 要么接进 PermissionService⁠，要么从界面上摘掉——留着比删掉更危险。
6. 应用时区固定为 Asia/Shanghai（app/Config/App.php:136⁠），所有 DATETIME 列都按本地时间裸存、无时区信息；任何跨时区需求都要先改这一层的约定。

主要风险

• WorkflowService 的私有 now() 返回 string，向 EntryModel/WorkflowActionModel 的 datetime cast 字段写入，CI 4.7.2 的 DatetimeCast::set() 只接受 CodeIgniter\I18n\Time 实例，导致提交审核/初审/终审四条路径全部 500。这是 Services 层唯一残留的同类缺陷簇，共 11 个调用点。
• user_sessions 表只写不读：AuthFilter 与 ApiController 从不校验 jti 是否已 revoke，登出与「禁止并发登录」都只是记账，被撤销的 JWT 在 exp（2 小时）内依然全权可用。
• MFA 密钥与备用码只做 base64 编码却在注释里自称「加密存储」，且 /api/auth/mfa/verify 完全没有节流，6 位 TOTP 加 ±1 时间窗可被无限次爆破。
• 发布链绕过审核状态机：PublishService::manualPublish 只查 content:publish 权限、不查 status，runSchedule 只看 publish_at 不看 status，草稿与在审内容都能直接变 published，且这两条路径不写 workflow_actions，审核链审计出现断点。
• 栏目级授权 checkChannelPermission 默认放行且硬编码 sys_admin 特例，与 PermissionService 明确声明的「不做 sys_admin 特例」互相矛盾；entries.channel_id 已改为无索引的 JSON 列，栏目维度查询全表扫。
• auth/RBAC/workflow/publish/DAM 五个核心域零单测，tests/ 下 576 行测试全部只覆盖 Figma 子服务。任何改动都没有回归网。

---

说明：本文只覆盖 w2r.site/backend/app/Services/（24 个顶层服务）与 Services/Figma/（8 个），共 32 个文件、6,905 行。app/Helpers/ 是空目录，0 个文件⁠——交接清单里若写了「Helpers 若干」，那是不存在的东西。所有行号均已按仓库真实文件核对。

---

0. 先说三件必须知道的事

0.1 全层唯一的硬伤：?datetime cast 只吃 Time 对象

CI 4.7.2（backend/system/CodeIgniter.php:58 确认版本）的 DatetimeCast::set() 写死了类型断言：

// system/DataCaster/Cast/DatetimeCast.php:50-57
public static function set(mixed $value, ...): string {
    if (! $value instanceof Time) {
        self::invalidTypeValueError($value);   // 抛 InvalidArgumentException
    }

只接受 CodeIgniter\I18n\Time⁠，字符串不行，DateTime/DateTimeImmutable 也不行⁠。另有一条容易漏的规则：system/DataCaster/DataCaster.php:152-156⁠，Model 侧的 DataCaster 是 strict = true（DataConverter.php:66 构造时不传 strict，默认 true），所以往没有 ? 前缀的 cast 字段传 null 同样抛异常（Field "x" is not nullable, but null was passed.⁠）。

好消息：created_at / updated_at 的自动时间戳不受影响⁠。BaseModel.php:888-890 显示 setCreatedField/setUpdatedField 是在 transformDataToArray()（做 cast 的地方，:886）之后才注入的，注入的字符串绕过了 caster。所以只有「调用方显式传了这个 key」时才会撞上——setCreatedField 里的 ! array_key_exists(...) 判断（BaseModel.php:931-936⁠）正是这个含义。

判定规则，接手后请当成 checklist 用：

任何 Model->insert()/update()/save() 的数组里出现了该 Model $casts 中声明为 datetime 或 ?datetime 的键，值必须是 Time 实例（?datetime 额外允许 null⁠）。否则 500。

0.2 已知缺陷清单里有一条是过时的，请更正

交接材料称「PublishService 的 manualPublish 已用 nowTime() 修复但 runSchedule() 第 46/68 行未修」。按当前文件状态，这条不成立⁠：

// Services/PublishService.php:27
$now    = $this->nowTime();              // 返回 Time（见 :138-141）
$nowStr = $now->format('Y-m-d H:i:s');   // 字符串只用于 SQL 比较
...
// :46 与 :68
'published_at'   => $now,                // 传的是 Time 对象，不是字符串
'unpublished_at' => $now,

PublishService 四个写入点（:46、:68、:118、:133）全部已经是 Time⁠，整个文件干净。真正没修的是 WorkflowService⁠，见下。

0.3 Services 层 ?datetime 缺陷穷举结果

我对 Services 层全部 37 处 Model 写入调用逐一核过（grep -rn "Model->insert(\|Model->update(\|model->insert(\|model->update(" Services/⁠）。残留缺陷全部集中在 WorkflowService 一个文件⁠，根因是它自己的私有 now() 返回字符串：

// Services/WorkflowService.php:280-288
private function now(): string      // ← 根因，返回 date('Y-m-d H:i:s')

第 11 条最容易被漏修：recordAction() 写的是另一张表，useTimestamps=false 意味着框架不会自动补 created_at⁠，代码必须自己传——所以哪怕把前 10 处的 entry 更新修好了，submit()／两级审核每一条都还会在写 workflow_actions 时二次崩溃。

修复方式⁠：把 WorkflowService::now() 改成 nowTime(): Time⁠，与 PublishService.php:138-141⁠、EntryDraftService.php:549-552⁠、PreviewService.php:116-119⁠、AssetRefService.php:145-148 保持一致（这四个已经是正确写法）。注意 :276 若继续走 Model 就传 Time⁠，若改走 $db->table() 就传字符串——别混⁠。

已核对为安全（无需改动）的写入点⁠，列出来是为了让接手者别做无用功：

• PublishService.php:46/68/118/133 — Time⁠，安全。
• PreviewService.php:41/44/58 — now()/parseDateTime() 都返回 Time（:116-125），revoked_at => null 命中 ?datetime（PreviewTokenModel.php:28-32），安全。
• EntryDraftService.php:139/140/142/248/249 — $draft->publish_at 来自 find()⁠，已被 DatetimeCast::get() 转成 Time⁠；$now 来自 nowTime()⁠。安全。
• DamUploadService.php:69/70/281/311/456/490/501 — 每处都先 Time::createFromFormat('Y-m-d H:i:s', $now)（:59, :265, :291, :306, :436, :484, :500），且源码里 :263-264 明确写了「DataCaster 的 DatetimeCast::set() 期望 Time 对象」，说明原作者踩过这个坑并修好了。安全。
• AssetCategorySyncService.php:53/54/75 — Time::now()⁠。安全（但另有 created_by 硬编码问题，见 §3.6）。
• AssetRefService.php:88 — now() 返回 Time（:145-148）。安全。
• Figma/EntryCssVersionService.php:94⁠、Figma/FigmaImageToDamService.php:306 — 都先转 Time⁠。安全。
• AuditLogger.php:75/77 — OperationLogModel 的 $casts 故意留空（OperationLogModel.php:35-38 有注释说明「不设置 cast，避免 DataCaster 插入时类型转换错误」），传字符串正确。安全。
• ChannelRolePermissionService.php:79/80⁠、UserSessionService.php:89/90/107/116⁠、AuditAnomalyService.php:142/153/162⁠、EntryDraftService.php:287/310/312/338/340/413/438/440/468/470 — 全部走 $db->table()->insert()/update() 绕过 Model⁠，不经 caster，传字符串正确。安全。

Services 层之外的同类缺陷（不在本次范围，但根因一致，建议同批修）： Controllers/Api/SearchHotwordController.php:63-68（start_at/end_at 直接透传 request 值，created_at/updated_at 传 $this->now() 字符串）与 :114⁠；Controllers/Api/SearchPinController.php:72-76 与 :122⁠。两个 Model 都把 start_at/end_at/created_at/updated_at 声明成不可空的 'datetime'（SearchHotwordModel.php:30-38、SearchPinModel.php:30-38），所以给值撞类型断言、不给值撞 not-nullable 断言，新建/编辑热词与置顶在任何入参下都必炸⁠。

其余控制器写入点已核对安全：EntryRelationController.php:115/117⁠、FaqPageController.php:116/118⁠、ContentController.php:433/441/663/675（均走 $db->table()⁠，且源码里有注释「Query Builder 的 insertBatch 需要字符串格式」）、AssetCategoryController.php:124/125/220⁠、FaqQuestionController.php:180/278（Time::now()⁠）、RoleController.php:189/207/208（无对应 Model，走 QB）。

---

1. 分层与总体形态

Controllers/Api/*            ← HTTP 边界，权限门禁 + 审计埋点
  └── Services/*             ← 本文范围，无接口无抽象，全是 new 出来的具体类
        └── Models/*         ← CI4 Model，casts 是隐形雷区（见 §0）
              └── MySQL 8

共性特征，先看懂这几条能省一天：

1. 无 DI 容器⁠。所有服务都在构造函数里 new XxxModel()⁠，服务间也是 new（如 PublishService.php:99 new EntryDraftService⁠、ConfigPromotionService.php:22-25 new 四个）。只有 Figma 那一支做了构造函数注入（FigmaImportService.php:24-36⁠），因此也只有它有单测。
2. 返回值有两种风格⁠，不统一：业务服务返回 ['ok' => bool, 'code' => int, 'message' => string, 'data' => array] 数组（Workflow / Preview / EntryDraft / DamUpload / ConfigPromotion / Search），基础设施服务直接返回标量或 bool（Auth / Jwt / Permission / PasswordPolicy）。AuditLogger::log() 是唯一的静态方法。
3. 有四套 now()⁠，返回类型不一致⁠——这是 §0 缺陷的土壤：
4. 返回 Time⁠：PublishService.php:138⁠、PreviewService.php:116⁠、EntryDraftService.php:549⁠、AssetRefService.php:145
5. 返回 string⁠：WorkflowService.php:280⁠、DamUploadService.php:540⁠、SearchService.php:211⁠、AuditLogger.php:62-66（内联）

其中 DamUploadService 和 AuditLogger 返回字符串是对的（前者随后转 Time⁠，后者目标 Model 无 cast），WorkflowService 返回字符串是错的⁠。接手后建议统一成 Time⁠，字符串场景显式 ->format()⁠。

1. 异常几乎不外抛⁠。业务错误走返回值，底层异常靠 catch-all 吞掉（JwtService.php:93-96⁠、SearchService.php:205-207⁠、WorkHoursService.php:60-62⁠）。好处是接口不 500，坏处是配置错误无声无息——JwtService 的密钥问题（§3.8）就是这么被藏起来的。
2. 测试覆盖极不均衡⁠。backend/tests/unit/Figma/ 下 5 个文件 576 行，覆盖 Figma 子服务；auth 链、RBAC、workflow、publish、DAM 零测试⁠。

---

2. 逐服务速查表

PHP 扩展依赖汇总（部署前必须确认）：gd（CaptchaService、FigmaImageResizeService）、curl（FigmaClient）、dom/libxml（FigmaSanitizerService、FigmaImageToDamService）、fileinfo（FigmaImageToDamService.php:220-227，有降级）、mbstring⁠、hash⁠、json⁠。

---

3. 鉴权链（重点展开）

3.1 完整登录时序

POST /api/auth/captcha   → CaptchaService::generate()   写 Cache(captcha_md5(token))，返回 base64 PNG
POST /api/auth/login
  ├─ LoginThrottleService::checkLock(ip)          AuthController.php:58
  ├─ CaptchaService::verify(token, code)          :102       ← 失败 recordFailure
  ├─ AuthService::login(username, password)       :144       ← password_verify + is_active
  ├─ LoginThrottleService::clearThrottle(ip)      :182
  ├─ session: user_id / user_role / mfa_verified=false      :185-189
  ├─ JwtService::generate(uid, role, mfa=false)   :205       ← 此时已发 token
  └─ PasswordPolicyService::isPasswordExpired()   :213
POST /api/auth/mfa/setup  → AuthService::generateMfaSecret()   写 mfa_secrets，is_enrolled=0
POST /api/auth/mfa/verify
  ├─ AuthService::verifyMfaCode()                 :480       ← 无节流（见 §3.5）
  ├─ completeMfaEnrollment()（首次）              :498-500
  ├─ session mfa_verified=true                    :503
  ├─ JwtService::generate(uid, role, mfa=true)    :510       ← 换发第二枚 token
  └─ UserSessionService::establishAuthenticatedSession()  :535-543

注意⁠：MFA 未通过时已经发了一枚 token（AuthController.php:205⁠）。这枚 token 的 mfa_verified=false⁠，AuthFilter 会在 :50-59 挡下（返回 1002）；但 AuthNoMfaFilter 保护的路由不挡。接手时要清楚哪些路由挂了哪个 filter（见 app/Config/Filters.php⁠）。

3.2 请求鉴权（Filters/AuthFilter.php⁠）

// AuthFilter.php:21-35
if ($token) { $payload = $jwtService->verify($token); ... }
if (!$userId) {                       // ← JWT 失败静默回退到 Session
    $userId = session()->get('user_id');
    $mfaVerified = session()->get('mfa_verified') ?? false;
}

两个坑：

• JWT 验签失败与「没带 token」不可区分⁠，都无声回退 Session。密钥配错（§3.8）时表现为「时灵时不灵」，没有任何日志线索。
• 完全不查 user_sessions⁠。见 §3.4。

ApiController::getCurrentUserId()（:77-93）/ getCurrentUserRole()（:100-116）/ getMfaVerified()（:123-137）是同一套「JWT 优先、Session 兜底」逻辑的第二份拷贝。改鉴权语义要同时改这两个地方⁠。

3.3 JwtService 细节

• generate()（:48-75）：payload 结构 {iss, aud, iat, nbf, exp, jti, data:{user_id, role, mfa_verified}}⁠。jti 可由 $additionalClaims['jti'] 覆盖，refresh()（:210-240）正是靠这个保持 jti 不变⁠，从而不破坏 user_sessions 关联。
• verifyAllowExpired()（:104-126）：签名通过但已过期时仍返回 payload，用于登出审计（「谁退出的」）。过期超过 refreshExpiration 才拒绝。设计合理。
• claimsData()（:134-146）是静态工具，处理 data 可能是 stdClass 的情况——所有读 claims 的地方都必须走它⁠，直接 $payload['data']['user_id'] 会在某些解码路径上拿不到。
• getTokenFromRequest()（:181-202）接受三个来源：Authorization header、jwt_token cookie、?token= query 参数⁠。query 传 token 会进 access log 与 Referer，是给 AssetDeliveryController 用的便利，但也是泄露面。

3.4 会话撤销是摆设（高危）

UserSessionService 写 user_sessions（:84-91）、撤销（:100-117）、检测并发（:45-74）都实现了，但全仓没有任何地方读它做鉴权判断⁠：

grep -rn "user_sessions" app/  →  只命中 Services/UserSessionService.php 自身

后果：

• AuthController.php:298 登出时把 jti 标 revoked，但那枚 JWT 在 exp（默认 7200 秒，Config/Jwt.php:35⁠）内继续全权可用。
• auth.allow_concurrent_sessions=0 时，UserSessionService.php:77-82 批量把旧会话 revoked_at 置位，旧终端毫无感知地继续工作⁠。这个开关在 UI 上是有的（AuditPolicyService::KEY_ALLOW_CONCURRENT⁠），运维会以为它生效了。
• 禁用/删除用户后已签发 token 仍能过 AuthFilter（PermissionService 会在权限层拦住，因为它查 is_active⁠，但 filter 层先放行了）。

修法⁠：在 AuthFilter::before 里用 JwtService::extractJti() 取 jti，查 user_sessions.revoked_at IS NULL⁠，结果进 Cache（TTL 30-60 秒）避免每请求一次 DB。

3.5 MFA 三个问题

1. 密钥不是加密是编码⁠。AuthService.php:110-112 注释写「加密存储（Base64编码）」，实际就是 base64_encode⁠。:217 读回来 base64_decode 再 base32Decode⁠。拿到 mfa_secrets 表 = 拿到所有人的 TOTP 种子 + 8 个明文备用码。
2. verify 无节流⁠。LoginThrottleService 在 AuthController 里只出现在 login()（:58/83/104/125/147/182），mfaVerify()（:453-495）一次都没调。verifyMfaCode 还接受 ±1 时间步（:240-247），单请求命中率 3/10⁶，可无限并发爆破。
3. reset 后 verify 会 500⁠。resetMfa（:304-308）把 secret/backup_codes 写成 '' 但保留行⁠；verifyMfaCode 的 findByUserAndProvider 仍返回该行，:221 的 json_decode(base64_decode('')) 得到 null⁠，:222 的 in_array($code, null, true) 在 PHP 8 抛 TypeError。

另有两处小雷：AuthService.php:77 和 :134 都是 $this->userModel->find($userId)->username⁠，无 null 检查，用户被删则致命错误。

3.6 其余环节

• ConfirmTokenService（63 行）用 Session 存票据（:30、:40）。10 个控制器依赖它做危险操作二次确认。风险：管理后台是 JWT 无状态鉴权，这里却要求有 Session cookie；前端若跨域/不带 cookie，二次确认永远失败。另外 verify() 只在过期时删票据（:49-50），用户 ID/操作不匹配时（:54-56）不删，可被反复试。
• PasswordPolicyService（92 行）⁠：干净，逻辑全在 Config/Auth.php（min 8、大小写数字特殊字符全开、passwordMaxDays = 90⁠）。唯一瑕疵是 :29 用 strlen() 而非 mb_strlen()⁠，中文密码的长度按字节算（偏松，不是安全问题）。
• CaptchaService（248 行）⁠：见缺陷表。核心问题是 :162 的 WRITEPATH.'fonts/arial.ttf' 在交接件里必然不存在（backend/writable/ 整个缺失），所以永远走 imagestring 的位图分支，验证码强度极低。

---

4. RBAC 求值算法

系统里有两套并存且语义不同的授权，这是最容易写出越权 bug 的地方。

4.1 全局 RBAC — PermissionService

// PermissionService.php:39-49
$result = $db->table('role_permissions')
    ->join('roles',       'roles.id = role_permissions.role_id')
    ->join('permissions', 'permissions.id = role_permissions.permission_id')
    ->where('roles.code', $user->role)     // 用户只有一个 role（users.role 是字符串码）
    ->where('roles.is_active', 1)
    ->where('permissions.code', $permissionCode)
    ->get()->getRow();
return $result !== null;                   // 存在即允许，纯白名单

关键性质：

• 用户 ↔ 角色是 1:N=1（users.role 存 role code 字符串，不是关联表）。
• 纯白名单，无 deny 概念⁠。
• 无 sys_admin 特例⁠——:38 和 :99 两处注释明确声明。sys_admin 的权限完全靠 role_permissions 里配全。这意味着 seed 数据一旦丢失，超管什么都干不了⁠。
• 每次调用 2 次查询（find($userId) + join），无缓存⁠。ApiController::checkPermission()（:145-154）每次 new PermissionService()⁠。WorkflowController::actions()（:260-263）连调 3 次 → 6 次查询。

4.2 栏目级 ACL — WorkflowService::checkChannelPermission + ChannelRolePermissionService

// WorkflowService.php:197-229
if ($roleCode === 'sys_admin') return true;          // ← 硬编码特例，与 §4.1 矛盾
$rows = ... channel_role_permissions ⋈ roles ⋈ permissions
        where channel_id = ? and r.code = ? and p.code = ?
if (empty($rows)) return true;                        // ← 无配置 = 放行
foreach ($rows as $r) if ($r['policy'] === 'deny')  return false;   // deny 优先
foreach ($rows as $r) if ($r['policy'] === 'allow') return true;
return true;                                          // ← 兜底也是放行

求值顺序：sys_admin 直通 → 无规则放行 → deny 优先 → allow → 默认放行⁠。

这套 ACL 只能做减法⁠。运营若期望「只给编辑 A 开放栏目 X」，配了 allow 也没用——因为其它栏目没配规则同样默认放行。要实现真正的隔离必须给所有栏目铺 deny 规则，实践上没人会这么做。

ChannelRolePermissionService::replaceForChannel（:46-102）是全量替换语义：先 delete 整个 channel 的规则（:55）再逐条 insert，包在 transStart/transComplete 里（:53/:90）。逐条 insert 前还各查一次 roles/permissions 存在性（:68-69）——N 条规则 = 2N+1 次查询，规则多时慢。

调用点⁠：只有 WorkflowController 的 submit/reviewL1/reviewL2 三处（:48、:122、:196）在用栏目级判定。PublishController⁠、ContentController 都不调⁠——所以栏目级 deny 挡得住「提交审核」，挡不住「直接发布」。

4.3 权限码给前端

PermissionService::getPermissionCodes()（:84-111）返回当前用户全部权限码，前端拿去控制菜单与路由。它和 hasPermission 是两条独立的查询⁠，语义必须保持一致——改一个忘了另一个，就会出现「菜单能看到但点了报无权限」。

---

5. 编辑工作流状态机

5.1 状态图

stateDiagram-v2
    direction LR
    [*] --> draft: 新建内容

    draft --> review_l1: submit<br/>WorkflowService.php:45,63
    unpublished --> review_l1: submit（允许）
    expired --> review_l1: submit（允许）

    review_l1 --> published: reviewL1 pass<br/>且 review_levels<=1<br/>:94-107
    review_l1 --> review_l2: reviewL1 pass<br/>且 review_levels>=2<br/>:109-118
    review_l1 --> draft: reviewL1 reject<br/>（reject_reason 必填 :121）

    review_l2 --> published: reviewL2 pass<br/>:154-164
    review_l2 --> draft: reviewL2 reject<br/>:171-183

    published --> expired: runSchedule<br/>unpublish_at<=now<br/>PublishService.php:66
    published --> unpublished: manualUnpublish<br/>PublishService.php:131

    draft --> published: manualPublish 绕过审核<br/>PublishService.php:116 ⚠
    review_l1 --> published: manualPublish / runSchedule 绕过 ⚠
    review_l2 --> published: manualPublish / runSchedule 绕过 ⚠

    published --> published: 修订稿合并回写<br/>EntryDraftService.php:133-144

    note right of published
      修订稿是另一条 entries 记录
      （draft_of_entry_id 指向原件），
      原件在整个修订期间保持 published
    end note

5.2 提交前的 i18n 完整性闸门

checkI18nCompleteness（WorkflowService.php:231-255⁠）：

• 中文标题与 slug 缺一 → 硬阻断（无视策略）。
• 英文缺失：channel.i18n_strategy === 'strict' → 阻断；否则只产生 warning，不阻断（:246-252）。
• 策略取自主栏目⁠：EntryModel::primaryChannelId($entry) 取 channel_id JSON 数组的第一个元素（EntryModel.php:85-92⁠）。channel_id 已在迁移 2026-02-10-100030 里从 BIGINT 改成 JSON 并删掉了外键与索引（该迁移 :19-23），所以按栏目筛内容是全表扫。

5.3 审核级数配置

getConfig()（:25-31）从 config 表读 workflow.rules⁠，默认 ['review_levels' => 2]⁠。reviewL1 在 :94 读 review_levels⁠，<= 1 就直接发布。风险⁠：ConfigModel::getValue()（ConfigModel.php:52-61）把存储值 json_decode 后返回，若有人把 workflow.rules 存成了标量字符串，$cfg['review_levels'] 取到 null → (int)null = 0 → 0 <= 1 成立 → 一级审核直接上线⁠。没有任何校验拦这个。

5.4 审核链断点

workflow_actions 只有 WorkflowService::recordAction（:257-278）在写。PublishService 的四条状态变更（:44、:66、:116、:131）与 EntryDraftService::publishDraftOverOriginal（:133）都不写⁠。所以从 workflow_actions 看，一条内容可能「提交了、初审过了」，然后状态莫名其妙变成 published——真实原因在 operation_logs 里（PublishController 有 AuditLogger 埋点），但两张表没有关联字段可拼。合规审计时这是个说不清的洞。

5.5 WorkHoursService（82 行）

严格说不属于工作流，是审计的时间维度输入。getWorkHours()（:21-34）从 config.auth.work_hours 读 {timezone, weekdays, start, end}⁠，默认周一到周五 09:00-18:00 / Asia/Shanghai。isOutsideWorkHours()（:53-81）支持跨夜班次（start > end 时走 :80 的反向判断）。时区非法时静默回落 Asia/Shanghai（:60-62）。被 AuthController（登录时标 outside_work_hours⁠）、AuditAnomalyService（:63、:72 决定是否统计）、AuditPolicyService（:54 透出配置）消费。

---

6. 发布 · 预览 · 草稿

6.1 PublishService（143 行）

• runSchedule()（:24-86）：两条独立扫描。发布条件 publish_at IS NOT NULL AND publish_at <= now AND published_at IS NULL（:35-37）；下线条件 unpublish_at <= now AND status = 'published'（:57-59）。逐行 entryModel->update()⁠，不分批不加锁⁠，条目多时是一串单条 UPDATE。updated_by => null（:47、:69）表示系统操作（entries.updated_by 可空，迁移 2025-01-19-100005:79-83 确认）。由 php spark publish:run-schedule（Commands/RunPublishSchedule.php⁠）驱动，cron 配置不在仓库里，需要向运维索取⁠。
• manualPublish()（:91-127）：若目标是修订稿（draft_of_entry_id 非空，:98）就转交 EntryDraftService::publishDraftOverOriginal⁠；否则只拦「已发布」（:112），其余状态一律直接 published。这是审核绕过的入口⁠。
• 幂等性：runSchedule 靠 published_at IS NULL 保证发布只做一次；但下线不幂等⁠——unpublish_at 满足条件的 published 内容每次跑都会被再置一次 expired（重复执行结果相同，但 unpublished_at 会被反复刷新）。

6.2 PreviewService（136 行）

• createToken()（:20-54）：32 位 hex 随机 token，可选 device（白名单 mobile/tablet/desktop，:28）与 expires_at⁠。
• accessByToken()（:73-114）：要求提供用户名密码（复用 AuthService::login⁠，:80-81），再验 revoked（:90）与过期（:93）。校验顺序是「先验密码后验 token」，因此无效 token 也会消耗一次密码校验——PreviewController 挂了 LoginThrottleService⁠，尚可。
• timeToTimestamp()（:127-134）同时兼容 Time 与字符串，是因为 PreviewTokenModel 的 expires_at cast 会把值转成 Time⁠——防御性写法，保留。

6.3 EntryDraftService（553 行，本层最复杂）

核心模型⁠：修订稿是 entries 表里的另一条记录⁠，draft_of_entry_id 指回原件，status='draft'⁠。原件在整个修订期间保持 published，前台不受影响。

• createDraftFromPublished()（:40-104）：五道前置校验（不存在 / 已是修订稿 / 已是草稿 / 状态不在 EDITABLE_SOURCE_STATUSES（:16，published/unpublished/expired）/ 非本人且非 sys_admin，:59）→ 已有草稿则直接返回（:63-73，幂等）→ 事务内克隆 entry 行、i18n + 缩略图、关联内容、FAQ 页题目、CSS 版本，最后 refreshEntryRefs⁠。
• publishDraftOverOriginal()（:111-162）：事务内把草稿的字段回写原件（:133-144）、逐项 merge（i18n / 缩略图 / 关联 / FAQ / CSS）、delete($draftEntryId)（:152）、刷新资产引用。草稿行删除后，entry_i18n⁠、workflow_actions⁠、entry_css_versions⁠、preview_tokens 都靠 FK ON DELETE CASCADE 连带清理（各迁移文件已确认）；但 asset_refs 的 object_id 没有外键（迁移 2026-01-24-100018:51 只对 asset_id 建了 FK），所以 deleteEditDraft（:190）才要手工 delete⁠。publishDraftOverOriginal 路径没有做这个手工清理⁠——草稿被删后，指向它的 asset_refs 行成为孤儿。这会让「资产被引用中，不可删除」的判断出现假阳性。
• copyLatestCssVersionsBetweenEntries()（:485-523）：读磁盘文件内容重新落盘⁠，而不是只改库里的文件名。注释（:481-483）解释了原因：只改库名会让前台 404。这是踩过坑之后的正确写法，别「优化」掉。
• 事务缺陷：:76-83 的 transRollback() 后直接 return，没有 transComplete()⁠，事务深度泄漏（详见缺陷表）。

---

7. DAM

7.1 DamUploadService（550 行）

分片协议：initSession → N × saveChunk → merge（或 mergeAsVariant⁠）。

• initSession()（:28-79）：upload_id 由前端提供，已存在则做参数一致性校验（:52）后幂等返回。上限来自 Config/Dam.php⁠：单文件 5GB、分片 1-10MB、最多 1000 片。
• saveChunk()（:81-142）：分片落 writable/uploads/dam_chunks/{upload_id}/{i}.part⁠，可选 md5 校验，同 hash 则幂等跳过（:112-122）。
• merge()（:163-318）：流式拼接并同步算 SHA256（:209-245），校验总大小与最终 hash，落 writable/uploads/dam/YYYY/MM/⁠，写 assets⁠，更新会话状态。全程无事务（详见缺陷表）。合并后不删分片（:314 注释说留给 cron，但仓库里没有这个 cron）。
• resolveAssetType()（:463-474）：扩展名或 MIME 命中任一即通过（$extOk || $mimeOk⁠，:469）。改扩展名即可绕过类型限制——但 sanitizeFilename（:523-529）会把文件名清洗成 [A-Za-z0-9._-]⁠，且文件落在 writable/ 下由 AssetDeliveryController 中转，未直接暴露，风险可控但值得记一笔。
• mergeAsVariant()（:331-461）：给已有资产加高清变体，同 quality 先删旧文件与记录（:440-446）——先删后插，中间失败就两边都没了⁠。

7.2 AssetRefService（150 行）

refreshEntryRefs($entryId)（:26-91）：delete + rebuild。扫描三个来源——entries.cover_asset_id⁠、entry_i18n.og_asset_id⁠、content_json⁠。content_json 有两条解析路径：能 json_decode 成数组就递归扫 key（:96-114），否则当富文本 HTML 用正则抓 data-asset-id 与 /asset/{id}（:121-143）。

坑⁠：递归扫描的匹配条件是 str_contains($k, 'asset')（:104），任何 key 里带 "asset" 且值是数字的字段都会被当成资产引用（比如 asset_count: 5 会生成一条指向 asset#5 的假引用）。这会让「资产删除保护」误判。

7.3 AssetCategorySyncService（78 行）

栏目建/改时镜像到「网站素材」资产分类树下。syncOnChannelCreate（:26-56）挂父分类（找不到父就挂根，:33-39），syncOnChannelUpdate（:61-77）只在 name_zh/name_en 变了才同步（:63）。:52 硬编码 'created_by' => 1⁠，而 asset_categories.created_by 带 FK RESTRICT（迁移 2026-01-27-100024:64⁠）——干净库上建栏目会因外键失败而无法生成镜像分类。

---

8. 搜索与 SEO

8.1 SearchService（221 行）

search()（:61-143）：FULLTEXT 优先、LIKE 兜底。hasFulltextIndex()（:196-209）用 SHOW INDEX ... WHERE Key_name='ft_entry_i18n_search' 探测，结果缓存在 static 变量里（:198-201）——只在单次请求内有效，每个请求都会多一次 SHOW INDEX⁠。

置顶（pins）只在第一页生效（:78-84），置顶结果被 whereNotIn 从主查询排除（:97）后前置拼接（:126），并且 $total += count($pinnedList)（:127）——分页总数计算不严谨⁠，第一页的 total 与后续页不一致。

escape 用法：$db->escape($q) 的结果直接拼进 MATCH(...) AGAINST (...) 字符串（:101-104、:115），走的是 where(..., null, false) 关闭转义。escape() 会加引号并转义，SQL 注入面已堵住，但可读性差、审计时容易误判。

hotwords()/pins() 通过 ->builder() 绕开 Model（:22、:43），因此不受 §0 的 cast 问题影响⁠——但也意味着 start_at/end_at 读出来是原始字符串而非 Time⁠。同一个 Model 走 find() 就会因为 NULL 触发 DatetimeCast::get() 的类型断言（get() 要求 string，见 DatetimeCast.php:29-34）。读热词/置顶时不要改用 Model 的 find()/findAll()⁠，除非先把 cast 改成 ?datetime⁠。

8.2 SeoSchemaService（307 行）

纯计算，无副作用（配置读写除外）。三块能力：

1. getSeoConfig()（:16-63）：四组配置带内置默认值——seo.site⁠、seo.meta_rules⁠、seo.organization_profile（中英双份 Corporation 档案）、seo.schema_mappings⁠。
2. buildSuggestedJsonLdForEntry()（:75-150）：映射键优先 meta_json.page_kind⁠，回退 entry_type:{type}（:261-267），再回退 WebPage（:88）。
3. mergeSuggestedAndOverride()（:158-189）：override 为对象则深度合并（list 数组直接覆盖，关联数组递归，:290-305），为数组则输出 JSON-LD 数组。validateJsonLd()（:191-212）只查 @context 与 @type 是否存在——校验很浅⁠，不保证 Google 能吃。

datePublished/dateModified 直接塞 $entry->published_at（:93），而它已被 cast 成 Time 对象——JSON 序列化时会变成 {"date":"...","timezone_type":3,...} 这种对象结构，不是 ISO8601 字符串⁠。这是 schema.org 输出格式的潜在问题，接手时值得实测一次。

---

9. 审计三件套

AuditLogger（写）  ←  AuditPolicyService（开关/阈值）  ←  AuditAnomalyService（频率告警）

9.1 AuditLogger（112 行）

唯一的静态入口 AuditLogger::log($module, $operation, $context, $result, $errorCode, $request, $httpRequest)⁠，返回 32 位 trace_id⁠。被 28 个文件调用，是全系统的审计动脉。

• 脱敏：sanitizeRequest()（:95-111）递归把 password/password_hash/mfa_code/token/confirm_token/secret 换成 *（清单在 :11-18）。匹配是精确的键名小写比对，new_password⁠、api_key⁠、access_token 这类变体不会被脱敏**。加字段时务必同步这个清单。
• OperationLogModel 的 $casts 故意留空（OperationLogModel.php:35-38），配 useTimestamps=false⁠，所以这里传字符串时间戳是对的（:75、:77）。
• log() 不做任何异常处理⁠。审计表写失败（比如 request_summary 超长）会把主业务请求一起带崩。

9.2 AuditPolicyService（151 行）

config 表上的一层带边界的读写封装。阈值边界写死在常量里：bulk_export_threshold 限 100-10000（:22-24、:38-40），access_denied_window_sec 下限 60（:50），query_rate_window_sec 下限 300（:52）。注意类注释明说「不提供关闭审计写入的开关」（:8）——只能关 access_denied 与 audit_query 两类的记录（:44-45），审计主干不可关。

性能坑：getBulkExportThreshold()/shouldLogAccessDenied()/shouldLogAuditQuery()（:125-138）每个都调一次完整的 getPolicy()⁠，而 getPolicy() 内含 9 次 config 表查询 + 1 次 WorkHours 查询⁠。ApiController::failForbidden（:168）每次拒绝都会触发一次。

9.3 AuditAnomalyService（181 行）

时间桶计数 + 阈值一次性告警。桶键 floor(now/window)*window 对齐（:125），桶行在 audit_rate_buckets 上有 (bucket_key, event_type, window_start) 唯一索引（迁移 :93）。

三类事件：access_denied（按 actor 或 IP 分桶，:40-41）、audit_query⁠、user_list（后两类只在非工作时间统计⁠，:63、:72）。达阈值时先把 threshold_logged=1（:157-162）再写审计，保证一个窗口只告警一次。

并发缺陷⁠：:128-155 是「查 → 有则 update / 无则 insert」的经典 check-then-act，两个并发请求会同时走 insert 分支，被唯一索引挡下一个 → 抛异常打断主请求⁠。正确写法是 INSERT ... ON DUPLICATE KEY UPDATE hit_count = hit_count + 1⁠。

9.4 ConfigPromotionService（235 行）

配置导出/导入，支持 5 类（:13）。导出全部实现；导入只有 workflow 与 channel_auth 真正可用，rbac 与 channels 直接返回「未开放」（:88、:90）。dryRun（:72-83）是假的⁠——不做任何校验，直接返回 validated: true 和全零变更数。别信它的返回值。

importChannelAuth（:175-219）对每行规则各查一次 roles 和 permissions（:194-195），再按 channel 分组调 replaceForChannel⁠。N 行规则 = 2N 次查询 + M 次全量替换事务。

---

10. Figma 导入管线

10.1 编排（FigmaImportService⁠，243 行）

parseShareUrl(url)                      FigmaClient.php:33-67
  → getNodes(fileKey,[nodeId]) 或 getFile(fileKey)      :76-99
  → FigmaToHtmlCssService::convert(node)                 → {html, css, images[], stats}
  → getImageFills(fileKey)      imageRef → CDN URL       :138-150
  → getImages(fileKey, nodeIds) nodeId  → 导出 URL       :108-130
  → applyExportNodeIdFallbacks()  节点导出失败时回退父节点  FigmaImportService.php:209-225
  → FigmaImageToDamService::importBatch()  下载→压缩→入 DAM
  → FigmaImageToDamService::applyToHtml()  回填 src / data-asset-id
  → FigmaSanitizerService::sanitize()      白名单净化

唯一注入了依赖的服务（FigmaImportService.php:24-36 全部可选注入），所以也是唯一有单测的（backend/tests/unit/Figma/⁠，5 个文件 576 行）。

exportNodeIdFallbacks()（:168-200）是踩坑产物：Figma /images 对组件实例子节点（形如 I9006:2823;1000:3676⁠）返回 null，代码逐级剥 ; 段并尝试实例根。这段逻辑没有文档，只有 :162-165 的注释⁠，别删。

10.2 FigmaToHtmlCssService（842 行，本层最大文件）

节点树递归转 HTML + CSS。按 type 分派（:110-137）：TEXT → renderText⁠，容器类 → renderContainer⁠，图形类 → renderShape⁠，其余有子节点则当容器。节点数上限 Config/Figma.php:41 的 800，超了标 truncated 并截断（:97-100）。

值得记住的隐式约定：

• 语义标签靠图层名猜⁠：resolveContainerTag（:221-236）用 str_contains(name, 'header'/'footer'/'nav'/'main'/'aside') 决定标签；resolveTextTag（:238-250）用字号 + 字重推 h1~h4。
• 布局双轨⁠：auto-layout（layoutMode⁠）映射 flex（:299-325），非 auto-layout 走绝对定位（:361-370），父容器 min-height 由 recordAbsoluteChildExtent 反推（:775-793）。
• compileCss()（:794-842）尾部硬编码了设计稿图层名⁠——card_awards⁠、Badge⁠、Badge Text（:826-831），带 !important⁠。设计师一改名，样式补丁静默失效，而没人会想到去看后端 PHP。

10.3 FigmaSanitizerService（142 行）

白名单净化，标签 22 个（:19-26）、属性 12 个（:28-33），一律剥 script/style/iframe/object/embed/form（:76-79）、on* 事件（:95-98）、内联 style（:99-102）。不在白名单的标签保留子节点、只脱掉自身（:81-87）。href 只放行 /⁠、#⁠、https/mailto/tel（:126-133）；img src 只放行 / 与 data:image/（:135-141）。质量不错。

10.4 EntryCssVersionService（209 行）

按 entry_id + lang 版本化落盘 page-{id}-{lang}-{Ymd-His}-{rand}.css 到 WRITEPATH/uploads/page-css⁠，checksum 相同则跳过（:50-63，只更新 source_url）。落盘失败或入库失败会 @unlink 回滚文件（:97-100）。历史版本永不清理⁠，磁盘只增不减。公开访问路径 /page-css/{filename}（Config/Figma.php:63⁠），由 PageCssDeliveryController 中转。

---

11. 接手 checklist

第 1 天必做的四件事

1. 读完本文 §0，把「datetime cast 只吃 Time」刻进肌肉记忆。
2. 修 WorkflowService::now()⁠，把 11 个调用点验一遍（含 :276 的 workflow_actions⁠）。这是让系统可用的最小改动。
3. 向前任/运维索取三样东西：.env 里的 JWT_SECRET 与 figma.token（别看真实值，确认存在即可⁠，位置见 backend/.env 与 Config/Jwt.php:56-70⁠、Config/Figma.php:74⁠）、publish:run-schedule 的 cron 配置、backend/writable/ 的媒体备份。
4. 确认 PHP 装了 gd/curl/dom/fileinfo⁠——缺任何一个，验证码、Figma 导入、图片压缩会静默降级而非报错。

改动前必查

• 动 Models/* 的 $casts → 把 Services 里所有写该字段的地方过一遍（用 §0.3 的表当模板重跑一次 grep）。
• 动鉴权语义 → Filters/AuthFilter.php 与 Controllers/Api/ApiController.php:77-137 是两份独立实现⁠，必须同改。
• 动 PermissionService → hasPermission() 与 getPermissionCodes() 是两条独立查询，必须同改，否则前端菜单和后端判定会打架。
• 动工作流状态 → 记得 PublishService 的四条路径不受状态机约束也不写 workflow_actions⁠。
• 动 Figma 转换 → 先跑 backend/tests/unit/Figma/⁠，这是全层唯一的回归网。

评级依据

• 理解难度 4/5⁠：文件多但个体不复杂，难在三条无文档的隐式约定（DataCaster 只吃 Time⁠；getWithI18n 动态挂 ->i18n 属性；channel_id 是 JSON 数组必须走 primaryChannelId()⁠）、状态机散落在 Workflow/Publish/EntryDraft 三个服务且互不知情、同一层里四套返回类型不同的 now()⁠。docs/ 下 31 份文档没有一份讲 Services 架构（grep -rl "DataCaster\|casts" docs/ 零命中）。
• 接手风险 4/5⁠：所有内容写入都要穿过带 cast 雷区的 EntryModel⁠；鉴权链有两处静默回退（JWT→Session）会把配置错误伪装成偶发掉线；user_sessions 只写不读意味着「已修复的安全需求」其实没生效，而没人会主动去验；auth/RBAC/workflow/publish/DAM 零单测⁠。
• 上手 8 人天⁠：读代码 2 天 + 补 §0 的 cast 心智模型并修工作流 1 天 + 摸清双套授权语义 1 天 + 跑通 DAM 分片与 Figma 管线各 1 天 + 补关键路径测试 2 天。
• 稳态维护 2.5 人天/月⁠：无重构前提下，按当前缺陷密度估算——bug 修复约 1.5 天，配置/权限/栏目类运营支持约 0.5 天，磁盘（CSS 历史版本、DAM 分片、审计日志）与 cron 巡检约 0.5 天。

主要风险

• 「验收」命令实为生产写操作：audit:accept 与 audit:accept-ext 名字像测试，实际会伪造 sys_admin token、TRUNCATE 表、改用户角色、覆盖全局审计策略、删除审计日志。它们由 spark 自动发现并出现在 php spark list 里，接手者极可能出于「先跑一下看看系统是否正常」的直觉执行，从而在第一天就造成不可逆的生产事故。这是整个交接中最危险的单点。
• 部署面是黑盒：仓库内没有任何 nginx/Docker 配置，而现场证据（public/404.html 的 nginx 页、public/index.html 的宝塔面板页）表明 .htaccess 全部失效。同时 writable/ 目录缺失、.env 只有一份 CI_ENVIRONMENT=development 的开发配置。换机、扩容、灾备恢复这三件事目前都没有可执行路径，必须先在生产机上把 nginx server 段、目录权限、真实 .env 逐项抄回来。
• 环境变量的生效链路是隐式的：数据库、会话、日志阈值全靠 CI4「.env 里 database.default.hostname 自动覆盖 Config\Database::$default['hostname']」这套约定，代码里搜不到读取点。App.php:19 的 baseURL 因为 .env 未提供 app.baseURL 而以硬编码 https://w2r.site/ 生效。接手者改 Config 类却被 .env 静默覆盖、或改 .env 却因键名拼写不匹配而无效，都不会有任何报错。
• 安全基线是纸面上的：App.php:201 开了 CSP 且 ContentSecurityPolicy.php 全面收紧到 'self'，但 Filters.php:87 的 secureheaders 被注释、CSP frame-ancestors 为 null（无点击劫持防护）、Cookie.php:57 secure=false（会话 cookie 无 Secure 标记）、Security.php 的 CSRF 全局未挂载，同时两个 MFA 命令把超管的 TOTP 密钥发往境外第三方二维码服务。等保验收时这套自相矛盾的配置很难解释。
• 测试无法作为回归网：79 条断言全部集中在 Figma 导入链路，认证、JWT、MFA、RBAC、工作流、发布调度、DAM 分片上传、审计埋点全部零覆盖。已知的工作流 500（EntryModel ?datetime cast）和创建内容非事务性两个缺陷正是这块空白的直接后果。任何对 Config 或 Service 的改动目前都只能靠人工点击验证。
• 破坏性命令缺少护栏：publish:revert-pages-to-draft 无权限校验无确认、dam:delete-video-mp4 无确认无审计、user:reset-mfa 直接清除现有绑定。多个命令的默认操作人硬编码为 'test' 账号（PublishPagesAsUser.php:30、RevertPagesToDraft.php:29），一旦执行，审计日志会把责任落到一个开发期测试账号头上，事后无法追溯真实执行人。

---

CMS 后端 · 配置 / CLI / 测试 交接文档

范围：/Volumes/ProjectsAPFS/VWCORP/w2r.site/backend 的配置与运维面。下文所有路径相对 w2r.site/⁠。框架为 CodeIgniter 4.7.2（backend/system/CodeIgniter.php:58⁠），框架源码与 vendor/ 均被 git 跟踪（.gitignore 只排除了 .env⁠、writable/⁠、.DS_Store⁠），所以仓库自带一份可运行的框架副本，不需要 composer install 也能起。

---

1. 一句话结论

配置层本身很浅，八成是 CI4 骨架原样；真正需要交接的是四件事：哪些 Config 被动过⁠、.env 的键怎么隐式生效⁠、14 条 spark 命令里哪几条会毁生产⁠、部署产物为什么复原不了⁠。其中 audit:accept / audit:accept-ext 两条命令是整个交接里最危险的东西——它们名字叫「验收」，实际会伪造超管令牌、清空生产表、改用户角色、删审计日志。接手第一天不要跑它们。

---

2. app/Config 清单与相对 CI4 4.7.2 原版的改动

共 45 个 app/Config/.php + 3 个 app/Config/Boot/.php⁠。

2.1 项目自建（CI4 原版没有的类）

Dam.php:49-50⁠、Figma.php:58 都把目录钉在 WRITEPATH 下，见第 6 节。

2.2 被改动过的 CI4 原版类

• App.php⁠：:19 baseURL = 'https://w2r.site/'（生产域名硬编码，且 .env 未提供 app.baseURL⁠，所以这行真的在生效⁠）；:136 appTimezone = 'Asia/Shanghai'（原版 UTC）；:201 CSPEnabled = true（原版 false）。其余字段与原版一致。
• ContentSecurityPolicy.php⁠：大改。scriptSrc/scriptSrcElem/scriptSrcAttr/styleSrc/styleSrcElem/styleSrcAttr/childSrc/connectSrc/fontSrc/objectSrc/formAction 一律 'self'⁠，imageSrc = ['self','data:']（:114⁠，给验证码 base64 留口），reportOnly = false（:27⁠，强制拦截而非只报告），autoNonce = true（:225⁠）。frameAncestors 仍为 null（:164⁠）⁠——不输出 frame-ancestors 指令。
• Filters.php⁠：:40-42 新增三个业务别名 auth / auth_no_mfa / logout_auth⁠；:66 注释掉 toolbar⁠；:79-89 $globals 前后钩子全部注释掉；:115 $filters 为空。也就是说没有任何全局过滤器⁠，鉴权完全靠 Routes.php 每条路由手写 ['filter' => 'auth']⁠。
• Events.php⁠：:28 ini_set('session.cookie_lifetime','0') 强制关浏览器即失效；:48-57 注释掉 Debug Toolbar 监听；:60-64 保留了 development 下的 __hot-reload 路由。
• Session.php⁠：:34 cookieName = 'w2r_cms_session'（原版 ci_session，注释说明是为了甩掉旧的长过期 cookie）；:47 expiration = 0⁠。注意 .env:44-45 又提供了 session.cookieName 与 session.expiration⁠，会覆盖这两行。
• Logger.php⁠：:42 threshold 改成 production ? 4 : 9⁠；:48 新增了原版没有的 retentionDays = 180⁠，由 logs:cleanup 读取。
• Routes.php⁠：172 行，全部业务路由，含 SPA fallback（:20-21⁠）、资产投递（:11-12⁠）、页面级 CSS 投递（:16⁠）和 api 分组下的全部接口。
• Migrations.php⁠：:64 lock = false（并发部署无迁移锁，多实例同时部署会打架）。

2.3 与原版逐行一致（可当作不存在）

Autoload / Cache / Constants / Cookie / Cors / CURLRequest / Database / DocTypes / Email / Encryption / Exceptions / Feature / ForeignCharacters / Format / Generators / Honeypot / Images / Kint / Mimes / Modules / Optimize / Pager / Paths / Publisher / Routing / Security / Services / Toolbar / UserAgents / Validation / View / WorkerMode / Boot/{development,production,testing}.php⁠。

其中几个「原版不动」本身就是问题：

• Database.php 全空凭据（:29-32⁠），完全靠 .env 注入；
• Security.php 的 CSRF 配置形同虚设——Filters.php 里 csrf 从未挂载；
• Cors.php 全空（:37-96⁠），前后端同域部署所以没影响，但一旦拆域名要从零配；
• Cookie.php:57 secure = false⁠，HTTPS 站点的会话 cookie 没有 Secure 标记；
• Encryption.php:24 key 为空——目前全仓库没有代码使用 encrypter 服务，暂时无害，但别指望它能用；
• WorkerMode.php 是 4.7 给 FrankenPHP 准备的，项目没用 FrankenPHP，纯骨架残留。

---

3. 环境变量全清单与缺省行为

CI4 的 BaseConfig 会用 .env 里 类名小写.属性名 形式的键自动覆盖 Config 类属性，代码里搜不到读取点⁠。这是本项目最容易踩的隐式约定。当前 .env（24 个有效键，值一律见 backend/.env:<行号>⁠）分四类：

A. 靠 CI4 约定自动覆盖 Config 属性

B. 代码显式读取

JWT_SECRET 的三段兜底逻辑有坑：:54 读 $_ENV 是唯一真正生效的路径；:57-68 的手工读 .env 用 strpos($line,'JWT_SECRET=')===0 匹配，而实际 .env:37 写成 JWT_SECRET = ...（等号前有空格），永不命中，是死代码⁠；:71-73 在 development 下用 bin2hex(random_bytes(16)) 现编——每个请求一个新密钥，表现为「登录后随机掉线」，本地调试时看到这个现象先查这里。

C. 存在于 .env 但无任何代码读取（死键，需吊销）

sitecore.LOGGING_URL⁠、sitecore.username⁠、sitecore.password⁠、sitecore.backendnewslisturl（.env:16-19⁠）。全仓库（PHP / Python / Vue / demo 站）grep 不到读取点，是 Sitecore 迁移期遗留的凭据。

D. 应该有但 .env 里没有的

app.baseURL（导致 App.php:19 的 https://w2r.site/ 硬编码生效）、app.forceGlobalSecureRequests⁠、app.CSPEnabled⁠、encryption.key⁠、cookie.secure⁠。另外 env 模板文件 69 行全是注释⁠，没有任何项目专属键的说明——接手方无法从模板知道该配哪些。

---

4. 14 条 spark 命令逐条说明

CI4 自动发现 app/Commands/ 下所有 BaseCommand 子类，全部出现在 php spark list⁠。

推荐 crontab（三条，其余一律手动）：

*/5 * * * * cd <backend> && php spark publish:run-schedule
0 0 1 * *   cd <backend> && php spark audit:cleanup
5 0 1 * *   cd <backend> && php spark logs:cleanup

注意 CleanApplicationLogs.php:15 的注释里写死了生产路径 /www/wwwroot/w2r.site/backend⁠，这是目前唯一能推断线上部署位置的线索。

---

5. tests/ 现状：有真实断言，但覆盖面只有 Figma

8 个测试文件、33 个测试方法、79 条真实 $this->assert*⁠，不是空壳：

对照 app/ 的规模：24 个 API 控制器、5 个根控制器、32 个 Service、25 个 Model、3 个 Filter、51 个迁移。认证、JWT、MFA、RBAC、工作流、发布调度、DAM 分片上传、审计埋点全部零覆盖。

phpunit.xml.dist 要点：bootstrap 指向 system/Test/bootstrap.php（:5⁠）；failOnRisky / failOnWarning 都是 true（:10-11⁠）；覆盖率范围只含 ./app 并排除 Views 与 Routes（:37-42⁠）；测试库走 Database.php:165-191 的 SQLite3 :memory: + 前缀 db_⁠。注意⁠：业务迁移里有 MySQL 专属裸 SQL（如 2026-03-12-100041_AddUniqueSitecoreIdToAssets.php:16 查 INFORMATION_SCHEMA.STATISTICS⁠），一旦有人写带 $migrate = true 的数据库测试，在 SQLite 下必炸——要么把测试库改成 MySQL，要么别用 DatabaseTestTrait 跑业务迁移。

build/logs/（testdox.html、logfile.xml 等）是测试产物却被 git 跟踪，应加进 .gitignore。

---

6. public/ 暴露面：哪些文件不该对外可达

public/.htaccess:14-16 的规则是「文件存在就直接给」，所以文档根下每个文件都是可达的：

另一条关键事实：public/404.html:6 写着 nginx、public/index.html 是宝塔默认页 —— 生产跑的是 nginx，.htaccess 里的全部重写规则实际不生效⁠。仓库内 find 不到任何 .conf / Dockerfile / docker-compose⁠，真正生效的 nginx server 段没有交接。

AdminController.php:20-34 直接 file_get_contents 吐 public/AdM/index.html⁠，配合 index.html:20 的 {csp-style-nonce} 占位符由 CI4 的 autoNonce（ContentSecurityPolicy.php:225⁠）在响应阶段替换。改动 CSP 配置前务必确认这条链路仍通⁠，否则管理后台会白屏。

---

7. 全部硬编码的绝对路径与生产域名

---

8. 运行期目录：全部状态都在缺失的 writable/ 下

Paths.php:56 定义 WRITEPATH = backend/writable⁠，该目录不存在（.gitignore:2 排除）。依赖它的有：

• Session.php:64 → writable/session（会话）
• Cache.php:84 → writable/cache（LoginThrottleService.php:24 登录限流、CaptchaService.php:25 验证码都靠它）
• Logger FileHandler（Logger.php:127 path 为空即默认）→ writable/logs
• Dam.php:49-50 → writable/uploads/dam⁠、writable/uploads/dam_chunks
• Figma.php:58 → writable/uploads/page-css

这些缺失不会在启动时报错⁠，而是在运行时以「登录失败」「验证码不出」「上传 500」的形式零散冒出来。接手第一步就是按上面的清单把目录建好并给 php-fpm 用户写权限。

---

9. 接手第一周的行动清单

1. 先给 audit:accept / audit:accept-ext 加保险⁠：最省事的做法是这两个类的 run() 开头判断 ENVIRONMENT === 'production' 就直接退出，或者干脆把两个文件移出 app/Commands/⁠。在这之前不要在生产机上敲 php spark list 之后手贱。
2. 删 public/test-putenv.php⁠、groupui-showcase.html⁠、index.html⁠、404.html⁠、AdM/.vite/⁠，并把 build/logs/ 加进 .gitignore⁠。
3. 上生产机抄回三样东西⁠：nginx server 段、真实 .env（重点确认 CI_ENVIRONMENT 到底是不是 production）、writable/ 的目录结构与权限。抄回来后写成 docs/deploy.md 和一份填好键名的 env.example⁠。
4. 吊销 sitecore.* 那套凭据（.env:16-19⁠），确认无人使用后从 .env 删掉。
5. 补两条安全配置⁠：Filters.php:87 打开 secureheaders⁠，ContentSecurityPolicy.php:164 设 frameAncestors = 'self'⁠。改完必须回归 /AdM 能正常登录（CSP 一收紧最容易打死管理后台）。
6. 把 MFA 二维码改成本地生成（SetupSuperAdminMfa.php:111⁠、ResetUserMfa.php:86⁠），不要再把 TOTP 种子发给第三方。
7. 给 publish:revert-pages-to-draft 和 dam:delete-video-mp4 加权限校验 + --force 确认 + 审计埋点⁠，参照 CleanAuditLogs.php:34/79 的 job_start/job_finish 写法。
8. 建三条 crontab（第 4 节末尾），并先在预发跑一遍 publish:run-schedule 确认 datetime cast 缺陷已修。
9. 补认证与工作流的冒烟测试⁠：登录→MFA→拿 token→提交工作流→发布，这条主链路一条测试都没有，是目前所有线上事故的共同来源。
10. 重写 README.md 与 composer.json 的 name/description⁠，把 PHP 版本要求统一到 8.2（README.md:45 现在写的 8.1 是错的）。

主要风险

• 工作流 UI 整体缺失：后端 workflow/submit、review-l1、review-l2、actions 四个路由无任何前端调用方，content:submit / workflow:review_l1 / workflow:review_l2 三个权限点在界面上无法行使。列表筛选器里的「待初审 / 待终审」状态在正常操作下永远筛不出数据，reviewer_l1 / reviewer_l2 两个角色登录后没有任何可做的事
• 审计日志查询的筛选与分页全部失效：api/audit.js:5 把参数对象又包了一层 params，实际请求为 ?params=[object Object]，后端读不到任何过滤条件，永远返回第 1 页 50 条。而导出走的是另一条正确的代码路径，会按筛选条件导出——屏幕上看到的和导出的 CSV 内容不一致，这在合规审计场景里是危险的
• 按钮级权限管控几乎不存在：全部 174 个 @click 中只有「发布」和「栏目授权」两处做了权限判断，删除内容、删除栏目、上传/强删资产、创建用户等按钮对所有能进入该页面的角色一律可见。editor 角色没有 content:delete，却能看到并点击删除按钮，输入密码后才被后端 403 拒绝
• 富文本正文的净化只用正则删除 <script> 标签（RichTextEditor.vue:240），onerror / onload / javascript: / iframe 等一概不过滤。这些 HTML 直接存入 content_json 并由官网前台渲染，构成存储型 XSS 通道
• 交接件与 GitLab 不同步：admin-frontend 的 git HEAD 停在 2026-05-25，工作区有 8 个文件已改（675 行新增）、6 个功能文件（发布、预览、修订稿三套 composable 与 API）从未提交。远端 gitlab.onedevops.vw.com.cn 上没有这批代码，本地这份是唯一副本
• 构建链路无自动化：.gitlab-ci.yml 只配了 SAST 与密钥扫描，没有 build/deploy job。产物 backend/public/AdM 靠人工在本机跑 npm run build 生成后提交进后端仓库，且 npm run build 会顺带删除 AdM/index.php 与 .htaccess，重建前必须先确认这两个文件是否为部署所需
• cms/components 下的可视化页面搭建器（VisualEditor 及其 registry/components/ComponentNode/ComponentPreview/ComponentProperties）共约 1,890 行，占前端代码 14%，没有任何视图或路由引用它，属于完整的死代码分支，会持续误导接手者

---

CMS 管理后台前端 交接文档

路径⁠：/Volumes/ProjectsAPFS/VWCORP/w2r.site/admin-frontend 规模⁠：59 个一方文件，13,656 行（其中 js/ 13,570 行；任务书给的 12,840 是排除两个 .ts 文件后的数字） 技术栈⁠：Vue 3.5.34 + Vue Router 5.0.7 + Pinia 3.0.4 + Element Plus 2.14.0 + Vite 6.4.2，无 TypeScript 全量接入（仅 4 个文件用 TS），无测试，无 ESLint/Prettier 配置

README.md 是 GitLab 自动生成的模板原文，93 行里没有一个字与本项目相关。本模块没有任何文档⁠，下面的内容全部来自读源码。

---

一、构建与部署（先看这段，坑最多）

vite.config.js 关键配置：

• base: '/AdM/'⁠，outDir 指向 ../backend/public/AdM⁠，emptyOutDir: true
• 手工分包：element-plus / vue-vendor / pinia 三个 vendor chunk
• 开发服务器固定 5173 端口，strictPort: true

package.json 的 build 脚本是：vite build && rm -f ../backend/public/AdM/index.php ../backend/public/AdM/.htaccess⁠。注意这个 rm⁠：构建会把后端 public/AdM 目录清空（emptyOutDir⁠）后再删掉两个文件。接手后第一次构建前，务必先确认生产环境的 AdM/index.php 与 .htaccess 是否是部署所需产物——脚本这么写，说明历史上这两个文件被 CI4 或 nginx 生成过并且会干扰 SPA 路由。

.gitlab-ci.yml 只有 SAST 与 Secret Detection 两个 job，没有 build，没有 deploy⁠。也就是说构建是原开发者在本机手工执行、产物提交进后端仓库的。该文件顶部还有一段 :stages: / :sast: / :include: 带前导冒号的无效 YAML 键，下面才是正确的第二段配置，属于两次模板叠加的残留。

index.html 里有一处服务端协作约定，容易被误删：

<span id="csp-style-nonce" class="csp-nonce-holder" {csp-style-nonce}></span>

后端把 {csp-style-nonce} 占位符替换成真实的 nonce="..." 属性，js/main.js:5-17 在任何框架代码执行前劫持 document.createElement⁠，给所有动态创建的 <style> 打上该 nonce。这是 Element Plus 在 CSP style-src 'self' 'nonce-xxx' 下能正常显示样式的唯一保障⁠，改动 main.js 顶部或 index.html 那个 span，会导致整个后台样式和登录验证码白屏。css/csp-utils.css 唯一的作用就是把这个 span 移出视口。

构建产物与源码是否一致

backend/public/AdM 现有产物时间戳为 2026-06-21 22:14，源码 mtime 是 2026-07-20 与 07-22（两批文件时间戳完全相同，是整目录拷贝的痕迹，不是逐个编辑）。我用 20 多个中文 UI 字符串逐一比对产物：已生成修订稿⁠、发布修订⁠、删除修订⁠、网站跳转链接⁠、替换高清版本⁠、配置包导入导出⁠、审计策略与工作时间⁠、拖动左侧手柄⁠、exclude_type⁠、edit_draft_id⁠、figma_url_zh 全部命中⁠。.vite/manifest.json 的 17 个入口与当前 11 个视图 + 2 个 Auth 视图一一对应，没有多余也没有缺失，VisualEditor 无对应 chunk（已被 tree-shaking 剔除，符合它是死代码的判断）。

结论：产物与源码在功能上一致，未发现源码有产物中不存在的特性。 但无法做字节级验证（本次审计禁止执行构建），且这份产物比后端仓库对 public/AdM 的最后一次提交（2026-05-26）更新，说明生产上跑的这个 build 本身也没进版本库⁠。

---

二、应用架构

入口链路

index.html → js/main.js → App.vue（仅一个 <router-view />⁠）→ router/index.js⁠。

main.js 依次做四件事：注入 CSP nonce 劫持 → 全量注册 @element-plus/icons-vue 的所有图标 → 装配 Pinia / Router / ElementPlus（中文 locale）→ import './cms/components/components' 做组件注册表的副作用导入（这一句是死代码的入口，见第六节）。

路由表

createWebHistory('/AdM/')⁠。全部路由集中在 js/router/index.js:7-94⁠，两个顶层公开路由 + 一个 Layout 容器带 11 个子路由，全部懒加载：

路由守卫（router/index.js:105-164⁠）

每次跳转都无条件 await authApi.getMe()⁠，没有任何缓存⁠。因此后台每切一次页面就打一次 /api/auth/me⁠。守卫顺序：

1. 拿到 res.data.id 才算已登录，否则 next('/login')
2. MFA 检查：requiresMfa && !mfa_verified 时，mfa_enrolled 为真跳 /login（去输 6 位码），为假跳 /mfa-enroll
3. 权限检查：canAccessRoute(res.data.permissions, meta.requiresPermission)⁠，不通过静默重定向到 /dashboard（无任何提示）
4. 副作用：每次都把用户信息写进 Pinia（appStore.setUserInfo⁠），这是 userInfo.permissions 的唯一来源

访问 /login 时若已登录且 mfa_verified⁠，反向重定向到 /dashboard⁠。

页面标题被硬编码统一为「大众汽车集团（中国）官方网站管理系统」，meta.title 定义了但从未使用。

Pinia store（js/store/index.js⁠，全部 25 行）

只有一个 useAppStore⁠，state 三项：sidebarCollapsed⁠、userInfo（含 permissions 数组、role⁠、role_name⁠）、sessionConfig.inactivity_logout_minutes⁠。actions 三个：toggleSidebar⁠、setUserInfo⁠、setSessionConfig⁠。没有持久化⁠，刷新后靠守卫的 getMe() 重新填充。

HTTP 客户端（js/api/index.js⁠，182 行，全部手写 fetch，无 axios）

• baseURL⁠：/api（相对路径，前后端同源部署）
• Token 存储⁠：sessionStorage 的 jwt_token 键（tokenManager⁠，第 9-28 行）。选 sessionStorage 是有意的——关闭浏览器即失效
• 请求拦截⁠：自动加 Authorization: Bearer⁠；body 是对象且非 FormData 时自动 JSON.stringify
• Token 自动续期⁠：第 83-85 行，任何响应体里带 data.token 就自动覆写本地 token
• 业务错误约定⁠：后端统一返回 {code, message, data}⁠，code !== 0 一律抛 Error 并挂上 error.code 供调用方分支判断（如 4001 资产被引用、6001 无权限）
• 401 处理⁠：code === 1001（凭证失效）或 1002（MFA 未验证）时，先调 reportLogoutAudit() 上报登出原因（这条请求刻意绕开 request 以免递归），再清 token，再用 window.location.href 硬跳转到 /AdM/login⁠。第 96 行会先判断当前是否已在 login/mfa-enroll 页以避免循环跳转
• 方法⁠：get（URLSearchParams 拼串）/ post / put / delete（可带 body，用于 confirm_token）/ getBlob（审计 CSV 导出专用）

js/api/ 下 18 个模块按后端控制器一一对应：auth、content、channel、dam、users、roles、system、config、seo、faq、workflow、publish、preview、relations、audit、dashboard、figma、index。

其中三个模块把「生成 confirm_token」封装进了业务方法内部——users.js:28/43/56⁠、roles.js:17⁠、channel.js:63⁠——这是重复生成 token 缺陷的根源（见缺陷 5）。

会话超时（composables/useInactivityTimeout.js⁠，167 行）

全前端设计最讲究的一个文件，在 layout/Index.vue:123 挂载，默认 30 分钟。要点：

• 用「时间戳 + 每 30 秒轮询」代替单次长 setTimeout，绕开浏览器对后台标签页的定时器节流
• mousemove/scroll 节流 5 秒，mousedown/keydown/touchstart/click 不节流
• visibilitychange 回到前台立即校验
• 启动后异步拉 /system/session-config 覆盖默认值；Settings 页保存后通过 window.dispatchEvent(new CustomEvent('w2r:session-config-updated')) 广播，无需刷新即时生效
• 开发环境默认 2 分钟，且支持 ?idle_test_sec=N 覆盖（import.meta.env.DEV 保护，生产构建会被剔除）

---

三、权限模型：22 个后端权限点 ↔ 前端映射

后端 RolePermissionSeeder.php:54-90 定义 22 个权限点，7 个角色（editor / reviewer_l1 / reviewer_l2 / publisher / dam_admin / sys_admin / audit_readonly）。前端的实际覆盖情况：

7 个权限点在前端完全没有对应实现⁠。菜单过滤逻辑在 config/menu-permissions.js⁠，MENU_ITEMS 是与路由表平行维护的第二份权限表——两张表已经出现不一致（缺陷 13）。

---

四、视图逐页说明（按业务域分组）

A. 认证域

views/Auth/Login.vue（618 行） — 单页完成「密码 + 图形验证码 → MFA 6 位码」两阶段登录。第一阶段调 /auth/login⁠，返回 mfa_enrolled 或 has_pending_mfa 时把表单切换成 MFA 输入框（mfaEnrolled ref 同时承担这两种语义），第二阶段调 /auth/mfa/verify 并用返回的新 token 覆写本地 token。未注册 MFA 则跳 /mfa-enroll⁠。前 235 行是纯装饰用的 SVG 动画背景（网格线、粒子、多边形），随机数刻意走 utils/random.js 的 Web Crypto 封装而非 Math.random⁠，注释写明是为了过 Sonar S2245 规则。

views/Auth/MfaEnroll.vue（278 行） — 两步：调 /auth/mfa/enroll 拿 secret 与 totp_uri⁠，用 qrcode 库画到 canvas，展示备用码，再调 /auth/mfa/verify 完成。挂载时先查 /auth/mfa/status⁠，若有 has_pending_secret 直接跳到第二步。

B. 内容域（本模块的核心，2,800+ 行）

views/Content.vue（1,573 行，全模块最大文件） — 非新闻内容（page / blog / faq_page）的列表与全屏编辑弹窗。列表查询固定带 exclude_type: 'news'⁠。调用接口：/content⁠、/content/{id}⁠、/channels⁠、/content/{id}/relations⁠、/seo/schema/preview⁠、/faq-pages/{id}/questions⁠、/figma/css/versions⁠、/figma/css/persist⁠、/figma/css/source-url⁠、/preview/tokens⁠、/auth/confirm-token⁠、/publish/publish⁠、/content/{id}/draft⁠。

views/News.vue（1,253 行） — 新闻专用，FIXED_TYPE = 'news'⁠，栏目限定为「新闻」「媒体新闻」两个多选。与 Content.vue 有约 600 行逐字重复的逻辑，但用 el-tabs 分中英文（Content.vue 是上下平铺）。缺预览和删除修订两个按钮（缺陷 10）。

views/FaqQuestions.vue（541 行） — 两个 tab：题库题目（带分页）与主题管理（无分页⁠，全量返回）。题目与主题的中英文在同一个弹窗内一起填。删除都要密码 + confirm_token（操作名 faq_question_delete / faq_topic_delete⁠）。

views/Channel.vue（691 行） — 栏目树。用 el-tree 的 draggable 实现拖拽排序与改父子关系，handleNodeDrop 后用 collectTreeOrderItems 重算整棵树的 parent_id 与 sort_order（步长 10）批量 PUT 到 /channels/reorder⁠，失败则重新拉取回滚。api/channel.js:5 的 normalizeChannelTree 递归把 id 转 Number——因为 MySQL/CI4 会把 id 序列化成字符串，而 el-tree-select 的 v-model 需要严格相等。栏目授权弹窗是全前端唯一按 rbac:manage 做按钮级管控的地方，保存要密码 + MFA。

C. 资产域（DAM）

views/Media.vue（980 行） — 资产列表、编辑弹窗（含图片/视频/音频/PDF 分类型预览）、高清变体管理。删除是三级流程：确认 → 密码 → dam_delete token → 删除；若后端返回 code === 4001（被引用），弹出强删确认 → 密码 → MFA → dam_force_delete token → /dam/assets/{id}/force-delete⁠。资产状态 0/1/2/3 对应草稿/已保存/已发布/已修改。

views/AssetCategories.vue（305 行） — 分类树表，带 channel_id 的分类是从栏目同步来的，名称只读。

D. 系统域

views/Users.vue（834 行）⁠、views/Roles.vue（379 行）⁠、views/Audit.vue（215 行）⁠、views/Settings.vue（662 行）⁠、views/Dashboard.vue（173 行）⁠。

Settings 页按权限分四块：会话超时（全员）、审计策略（仅 role === 'sys_admin'⁠，硬编码角色名而非权限码）、配置包导入导出（config:export/config:import⁠）、工作流设置 + SEO 设置（无任何门禁⁠，workflow:config 用户也会看到「保存 SEO 设置」按钮，点了拿 403）。

---

五、内容编辑器细节

content_json 的三种形态

后端存的 content_json 历史上有三种格式，normalizeContentJson（Content.vue:1129⁠、News.vue:849 两份重复实现）负责统一还原成 HTML 字符串：

1. 直接的 HTML 字符串（手工编辑产生）
2. JSON 字符串，如 "\"<p>...</p>\""
3. [{type:"html", html:"..."}] 数组（Python 迁移脚本产生）

写回时一律写成裸 HTML 字符串⁠，不还原成原格式。这是个单向收敛，接手时要知道数据库里三种格式会长期并存。

中英文切换

不是切换，是同页双份字段⁠。form 里每个可翻译字段都有 _zh / _en 两份（title、slug、cover_asset_id、summary、content、seo_title、seo_desc、og_asset_id、schema_json、files）。Content.vue 上下平铺，News.vue 用 tabs。只有中文标题和中文 slug 是必填（formRules⁠），英文全部可选。栏目上有 i18n_strategy（loose/strict）字段控制发布时是否强制中英齐全，但该策略只在后端生效，前端不做任何校验⁠。

富文本编辑器（cms/components/RichTextEditor.vue⁠，483 行）

contenteditable div + document.execCommand（已废弃 API）。工具栏：粗斜体下划线删除线、p/h2/h3、有序无序列表、插入链接、清除格式、插入图片（打开 AssetSelector，插入 <img src="/asset/{id}" data-asset-id="{id}">⁠）、Figma 导入。

defineExpose 暴露 getHtml / getFigmaUrl / setFigmaUrl / applyCssPreview⁠。父组件保存前调 syncContentEditorsBeforeSave() 主动从 DOM 拉一次 HTML——因为 @input/@blur 的双向绑定在某些编辑路径下会漏更新，这是个已知的补丁式修复，改编辑器时别删⁠。

Figma 导入流程：粘贴链接 → 校验必须是 figma.com 域名 → POST /figma/import 拿回 {html, css, css_url, asset_ids} → 按 replace/append/cursor 三种模式插入 HTML → CSS 优先以 <link> 外链方式注入（CSP 下 inline style 会被拦）→ emit('figma-imported') 把 CSS 暂存到父组件的 figmaCssZh/figmaCssEn → 保存内容时才调 /figma/css/persist 落盘成版本化 CSS 文件⁠。Figma 源链接同时写进 meta_json.figma_url_zh/en（mergeFigmaUrlsIntoMeta⁠）。编辑已有内容时会反查 /figma/css/versions 恢复预览，若查到 CSS 但正文为空会弹警告提示重新导入。

草稿 / 预览 / 发布交互

修订稿机制（composables/useContentEditDraft.js⁠）：编辑状态为 published / unpublished / expired 的内容时，不直接改线上，而是先 POST /content/{id}/draft 生成或复用一份修订稿，返回 draft_id 后编辑这份副本。列表行上有 edit_draft_id 字段标记存在未发布修订。

发布（composables/useContentPublish.js⁠）：canPublish 判断 content:publish 或 role === 'sys_admin'⁠；canPublishRow 判断——已发布的内容只有存在 edit_draft_id 时才可再发布（发布修订）。流程是确认弹窗 → 密码 → content_publish token → POST /publish/publish⁠。注意发布的是 edit_draft_id 而不是 row.id⁠。

删除修订（composables/useContentDeleteDraft.js⁠）：DELETE /content/{id}/draft⁠，只删修订不动线上。仅 Content.vue 接入，News.vue 没接⁠。

预览（utils/contentPreview.js⁠）：已发布且类型属于 page/faq_page/blog 且有 slug 的，直接开 https://demo.w2r.site/{slug}（英文加 /en 前缀）；否则 POST /preview/tokens 拿 token 后开 /preview/{token}⁠。官网域名 PUBLIC_SITE_ORIGIN 是硬编码常量⁠，换环境必须改代码。

DAM 选择器与分片上传

AssetSelector.vue（261 行）是弹窗式资产选择器，被封面、附件、富文本插图共 6 处复用，内嵌 DamUploader 支持边选边传。

composables/useDamUpload.js（263 行）是分片上传的全部逻辑，UI 无关：

• 分片 5 MB，单文件上限 5 GB
• 上传前先查 /dam/chunk-status/{uploadId} 拿 uploaded_chunks 做断点续传⁠，已传分片直接跳过
• upload_id 格式 upload_{timestamp}_{9位base36}⁠，随机数走 Web Crypto
• 进度条：分片阶段占 0-90%，合并占 95%，完成 100%
• 合并前用 crypto.subtle.digest('SHA-256') 在前端整文件算哈希传给后端做 final_hash 校验（大文件会把整个文件读进内存，5 GB 时有 OOM 风险）
• 暂停用抛 USER_PAUSED 异常中断循环实现
• 两种合并模式：新建主资产走 /dam/merge⁠，加高清变体走 /dam/assets/{id}/variants

DamUploader.vue 支持「主文件 + 高清版本」一次提交两步串行上传（第一步成功回调里自动发起第二步）。有个语义陷阱：开关叫「在列表中显示」，但 useDamUpload.js:77 的注释写明「打开=待审核(status=0)，关闭=已发布(status=2)」，且默认值是关闭。开关名称与实际语义完全不对应⁠。

---

六、专项核查：按钮好看但没接后端

全仓库 .vue 文件共 174 处 @click（含 @click.stop⁠）。分类结果：

1. 处于死代码中、生产环境永远点不到：10 处 — VisualEditor.vue 6 处、ComponentNode.vue 2 处、ComponentProperties.vue 2 处。其中 VisualEditor.vue:23 的「保存」按钮是最典型的假成功：handleSave() 只做 emit('save', componentTree.value) 然后弹 ElMessage.success('已保存')⁠，而没有任何父组件监听这个事件——弹窗说保存成功，实际什么都没存⁠。

2. 可达但不发任何请求、且会产生错误后果：2 处（均在 Users.vue）

• Users.vue:120 「注册MFA」→ handleEnrollMfa 只设三个 ref 打开弹窗，弹窗内容是纯图文步骤说明，全程零 API 调用
• Users.vue:244 「打开MFA注册页面」→ window.open('/AdM/mfa-enroll')⁠，该页面读的是当前管理员自己的会话，不是目标用户

3. 纯 UI 状态操作（合理，不算缺陷）：约 60 处 — 弹窗开关、取消、清除封面、增删表格行、树展开收起、富文本 execCommand、Tab 切换、预览设备切换等。

4. 正常调用后端：约 100 处。

真正的大问题不在 1-2 类，而在第 4 类⁠：这 100 个按钮里绝大多数没有权限判断，对无权角色而言就是「能点、走完一整套密码确认、最后拿 403」。editor 角色能看到删除内容、创建/删除栏目、删除资产等按钮。从用户视角这与「按钮没接后端」体验相同，但成因是权限门缺失（缺陷 3）。

另外还有一个非 @click 的非功能控件：AssetSelector.vue:40 声明了多选列复选框，但没有 @selection-change⁠，勾选它不会让「确定」按钮解禁（缺陷 14）。

全前端只有 1 处 TODO（AssetSelector.vue:225⁠），没有 FIXME/HACK，没有空函数体的 @click⁠。就「有没有假按钮」这个问题本身，代码是干净的——ElMessage.success 都出现在真实 await 之后。

---

七、死代码清单

js/cms/components/ 下有一整套可视化页面搭建器，没有任何视图或路由引用⁠：

registry.ts 的注释写明设计意图是「让 Editor 与 Runtime 共享同一套组件白名单」，说明这曾是个规划中的 JSON 化页面搭建方案，最后实际落地的是富文本 + Figma 导入路线，这套东西被弃用但没删。main.js:30 仍导入 components.ts 做副作用注册，把它和 registry.ts 打进了主包。

未被调用的 API 封装：publishApi.unpublish⁠、damApi.getAssetRefs⁠、authApi.mfaReset⁠、previewApi.listTokens⁠、channelApi.getDetail⁠。

---

八、接手后的建议顺序

1. 立刻把工作区提交进 GitLab（6 个未跟踪文件 + 8 个已改文件，发布/预览/修订三套核心流程全在里面，本地是唯一副本）
2. 修 api/audit.js:5 一行，恢复审计筛选与分页（改动最小、影响最大）
3. 给 RichTextEditor.sanitizeHtml 换成 DOMPurify 白名单
4. 决策工作流：要么补齐提交/审批 UI，要么明确废弃两级审核并清理相关权限点与状态筛选项
5. 建立按钮级权限指令（如 v-perm="'content:delete'"⁠），把 22 个权限点逐一落到按钮上
6. 删掉 VisualEditor 整套死代码，同时移除 main.js:30 的副作用导入
7. 把 CI 补上 build 与产物校验，终结「本机手工构建、产物提交进后端仓库」的现状

九、评级依据

理解难度 3/5⁠：技术栈主流、无自定义抽象层、<script setup> 扁平直白、单个 store 只有 25 行，读起来不费劲。扣分项是零文档（README 是模板原文）、1,890 行死代码误导、content_json 三种格式的隐式约定、修订稿（edit_draft_id⁠）流转规则只能从三个 composable 里反推、DamUploader「在列表中显示」开关名称与语义相反、Content/News 两份 600 行重复逻辑各自演化。

接手风险 3.5/5⁠：前端是薄层，鉴权与业务规则由后端兜底，误改的爆炸半径有限，这是减分项。加分项是——零测试零 lint、构建无 CI 且 build 脚本带 rm⁠、生产产物未入库、发布与删除直接作用于对外官网、富文本净化形同虚设、权限门缺失导致任何 UI 改动都可能扩大暴露面。

上手 6 人天⁠：读懂 18 个 API 模块与路由/守卫/store（1 天）、吃透 Content.vue + News.vue 共 2,800 行内容编辑器与 i18n 双份字段（2 天）、DAM 分片上传与断点续传（1 天）、RBAC 前后端映射与 confirm_token/MFA 二次确认流程（1 天）、摸清构建部署链路与 CSP nonce 约定（1 天）。

月维护 2 人天⁠：按 11 个视图的 CRUD 体量、无测试导致每次改动都需手工回归、Content/News 重复代码需双份同步、以及产物需手工构建部署估算。

主要风险

• 生产到底是 api.php 还是 app/Controllers 在服务 /api/menu、/api/news、/api/asset，仓库里没有 nginx/Apache vhost 配置可以证明，两边逻辑各有一份且不完全等价（错误码、日期对象处理）。接手第一天必须用 curl /api/ 的 data.framework 字段实测确认，否则修改可能完全不生效。
• api.php 把数据库故障一律翻译成「成功但没有数据」，站点会以「菜单消失、新闻列表空白」的形态静默降级，没有任何 5xx 触发告警。任何依赖告警发现问题的运维习惯在这里全部失效。
• shared/dam-writable 直连生产 CMS（w2r.site）的 writable 目录。demo 侧的部署脚本、清理脚本、权限批处理若跟随符号链接，会直接破坏生产 CMS 的媒体原始文件。本机该链接悬空，所有封面在本地一律 404，容易误判为代码 bug。
• 前端产物 dist/ 是提交进仓库并被网站根目录直接指向的，且当前产物 mtime 早于两个源文件。没有 CI，构建纪律只写在 .cursor/rules/frontend-build.mdc 里；接手者若只改源码不构建，线上不变；若构建环境 Node/Vite 版本不同，产物可能与线上现状产生大面积 diff。
• 站点只完成了首页与新闻详情两个页面，顶栏菜单指向的所有栏目页都不存在，且前端没有 catch-all 路由——点开即空白页而非 404。对外可见范围远小于导航暗示的范围，上线前必须先决定「隐藏导航」还是「补页面」。
• 无任何响应式实现，顶栏是 1440px 画布下的绝对定位像素坐标。移动端与窄屏笔记本上布局破坏，且改造成本（约 40 人天）远超其余所有缺陷之和。
• DAM 资产接口可按 id 枚举，未校验资产是否归属于已发布内容；资产整文件读入内存交付。既是信息泄露面，也是可被单请求打满内存的可用性风险。
• backend/.env 为 development 环境，CI4 入口出错会吐完整堆栈；writable/debugbar 已积累 424 个 json、logs 里已有含绝对路径的堆栈。

---

交接范围：/Volumes/ProjectsAPFS/VWCORP/demo.w2r.site 全部。首方代码约 10,822 行（frontend/src 3,781；backend PHP 6,997；构建配置 44），132 个源码/配置/文档文件，不含 backend/vendor（27MB）、frontend/node_modules⁠、frontend/dist⁠。

1. 这个系统是什么

demo.w2r.site 是大众汽车集团（中国）官网前台的重做版本，只读⁠。它不生产内容——内容由同机的 w2r.site CMS 生产，两边共用同一个 MySQL 库（backend/.env:12 的 database.default.database = vgc⁠）和同一份 DAM 媒体文件（通过符号链接 shared/dam-writable⁠）。demo 侧只做三件事：查 channels 表画导航、查 entries/entry_i18n 出新闻、按 id 吐 DAM 二进制。

目录关系：

根目录的 index.html⁠、404.html 是宝塔面板默认文件，不是站点内容；.user.ini:1 设了 open_basedir=/www/wwwroot/demo.w2r.site/:/tmp/⁠。

2. 前端：组件树与路由

入口链路：src/main.js:7-9 → App.vue（只有一个 <router-view>⁠）→ src/router/index.js⁠。

路由表（router/index.js:10-26⁠）只有四条半：

没有 catch-all，没有 NotFound 组件⁠。router 里 props: true（:18,:24）是无效声明——NewsDetailPage.vue 根本没有 defineProps⁠，uuid 是在 useNewsArticleDetail.js:34 里用 useRoute() 自取的。

组件树：

HomePage.vue:3-10
├── HeaderNav.vue           顶栏 + 三列 mega menu（621 行，本目录最复杂的组件）
├── HeroBanner.vue          首屏视频 + 标题/导语文案（文案硬编码 :54-56）
├── HomeIntroBandSection    空占位，只有 TODO 注释（13 行，实际什么都不渲染）
├── LatestReleaseSection    Latest Release 三卡 → ReleaseCard × N
├── FeatureAlternatingSections → FeatureSplitSection × 3 → FeatureCtaButton
├── BrandLogoGridSection    → BrandLogoCard × 12
├── SocialQrSection         三个二维码位
└── SiteFooter              页脚

NewsDetailPage.vue:2-6
├── HeaderNav.vue           复用
├── NewsArticleContent.vue  正文（样式在 styles/news-detail.scss，543 行，非 scoped）
└── SiteFooter.vue          复用

三个 composable 是全部的数据入口：

• useSiteMenu.js:27 → GET /api/menu?lang= → normalizeMenuApiResponse → capMegaMenuDepth(…, 3) 截断到三层 → resolveMegaState 算高亮态。
• useLatestNewsList.js:22-24 → GET /api/news?lang=&limit=3⁠。
• useNewsArticleDetail.js:47-49 → GET /api/news/{uuid}?lang= → adaptNewsDetailResponse → sanitizeArticleHtml（DOMParser 去 script/on* 属性/javascript: URL）→ enhanceArticleHtml（删空 <p>⁠、把连续两个图块包成双列 gallery）→ v-html⁠。

lib/ 下有四个文件是完全无引用的死代码⁠：lib/news/normalizeContentJson.js（后端已经做了同样的事）、normalizeMegaMenuNav.js:95 的 normalizeFromFlatMenuRows⁠、:142 的 megaMenuDepth⁠、articleUrl.js:20 的 parseNewsDetailFromLocation⁠。data/mockNewsArticle.js 182 行整个文件自述 deprecated（:2）。

3. api.php 逐端点：SQL 与返回结构

api.php 是纯过程式脚本，靠 preg_match($path) 分发（:12,:24,:31,:37,:43,:52），手写 .env 解析器（api_load_env :67-98），mysqli 直连。注意 DAM 分支必须在 JSON header 之前（:11-16 的注释解释了原因）。

GET /api/asset/{id}?quality=high

api.php:12-16 → demo_asset_delivery.inc.php:11-88⁠。

-- demo_asset_fetch_row :168-171
SELECT a.storage_key, a.mime, a.size_bytes, a.filename, a.category_id, c.access_level AS cat_access
FROM assets a LEFT JOIN asset_categories c ON c.id = a.category_id
WHERE a.id = ? LIMIT 1;
-- quality=high 时追加 :196
SELECT storage_key, mime, size_bytes, filename FROM asset_variants
WHERE asset_id = ? AND quality = 'high' LIMIT 1;

返回二进制。状态码：400（id<=0，:14）、401 JSON {code:4011}（分类 access_level='auth'，:50-53）、404（记录不存在 :43 / 文件不存在 :62）、403（realpath 越界 :71）、500（storageRoot 未配 :24 / DB 不可用 :31）。物理路径 = asset.storageRoot（.env:24⁠）+ storage_key⁠。

GET /api/menu?lang=zh|en

api.php:24-28 → api_menu_response :136-176。

SELECT id, parent_id, {name_zh|name_en} AS name, {slug_zh|slug_en} AS slug, sort_order
FROM channels
WHERE is_active = 1 AND show_in_menu = 1 AND menu_position = 'top'
ORDER BY sort_order ASC, id ASC;

api_build_menu_tree :103-131 递归组树，href = 前缀（'' 或 /en⁠）+ /slug⁠。返回 {success:true, data:[{id,name,slug,href,sort_order,children[]}]}⁠。三条失败路径（:142 未配库、:157 连接失败、:166 查询失败）全部返回 {success:true, data:[]}⁠。另有 :163 在 fetch_assoc()（:170）之前就 close() 的隐患。

GET /api/news?lang=&limit=&page=

api.php:37-40 → api_news_list_response :203-280。limit 钳在 1–20（:206），page ≥ 1。

-- 计数 :220-224
SELECT COUNT(*) AS c FROM entries e
INNER JOIN entry_i18n ei ON ei.entry_id = e.id AND ei.lang = ?
WHERE e.type='news' AND e.status='published';
-- 列表 :238-245
SELECT e.id, e.uuid, e.publish_at, e.published_at, ei.id AS entry_i18n_id, ei.title, ei.slug
FROM entries e INNER JOIN entry_i18n ei ON ei.entry_id = e.id AND ei.lang = ?
WHERE e.type='news' AND e.status='published'
ORDER BY COALESCE(e.published_at, e.publish_at) DESC, e.id DESC
LIMIT ? OFFSET ?;
-- 每行封面 :315
SELECT asset_id FROM asset_entry_i18n WHERE entry_i18n_id = ? AND role='thumbnail' LIMIT 1;

返回 {success:true, message:'ok', data:{list:[{id,uuid,title,slug,cover_url:'/api/asset/{id}'|null,date_display:'Y.m.d',date_iso:'Y-m-d'}], total, page, limit}}⁠。INNER JOIN 语言表是刻意的：英文首页不会混进中文标题。连接失败同样返回 success:true 空列表（:212-216）。

GET /api/news/{id|uuid}?lang=

api.php:31-34 → api_news_detail_response :360-383。先 api_news_resolve_published_id :385-410（纯数字走 id⁠，否则走 uuid⁠，都要求 type='news' AND status='published'⁠），再 api_news_build_payload :415-483。

用到的查询：entries 主行（:417）、entry_i18n 全字段（:299，含 content_json,files,seo_title,seo_desc,og_asset_id,schema_json⁠）、封面（:315）、面包屑栏目（api_channel_public :589）、上下篇（:628-631）。语言回退在 :430-432：目标语言缺失时退回 zh⁠，返回体里的 lang 是实际生效语言⁠。

返回体（:458-482）：id, uuid, channel_ids[], meta{}, lang, title, summary, slug, content_html, cover_asset_id, files[], tags[], publish_at, published_at, display_date('Y-n-j' 不补零), breadcrumb_channel{id,name,slug,href}, prev, next, seo{title,description,og_asset_id}⁠。

content_html 由 api_normalize_content_json :556-580 还原：先当 JSON 解，是字符串就直接用，是 [{type:'html',html:'…'}] 就取 html⁠，否则原样当 HTML。这是 CMS 富文本的存储约定，前端 lib/news/normalizeContentJson.js 有一份等价实现但没人调用。

上下篇（:619-651）把该栏目全部已发布文章 id 一次性拉回 PHP 再 array_search 定位，无 LIMIT、JSON_CONTAINS 不走索引。而前端 adaptNewsDetailResponse.js 根本没读 prev/next⁠。

失败一律 {success:false,message,data:null} 但 HTTP 200（:365,:371,:378）。

GET /api 与 /api/hello

api.php:43-59⁠，健康检查。data.framework 是 'CodeIgniter 4 (轻量入口)'⁠。

4. 两份并行实现对照，以及谁在生产生效

谁生效？仓库无法给出确定答案，这是本模块头号交接风险。 三份互相矛盾的证据：

1. backend/public/.htaccess:29 的 RewriteRule ^(hello|)$ api.php [L,QSA] 在 RewriteBase /api/ 下只把 /api/ 和 /api/hello 交给 api.php⁠，其余（menu/news/asset）落到 :36 的前端控制器 index.php → CI4。
2. app/Config/Routes.php:11 的注释与 :20-23 额外注册的裸路由（menu⁠、news⁠、asset/(:num)⁠）只有在 CI4 真的要处理 /api/menu 时才有必要写——说明作者当时认定 CI4 在处理这些路径。
3. frontend/README.md:24 却写「Nginx：将 location ^~ /api/ 转发到能执行 api.php 的配置（与现有 /api/menu 一致）」，暗示 nginx 把整段 /api/ 都给了 api.php。
4. 硬证据：backend/writable/logs/log-2026-03-23.log:1-3 和 log-2026-03-20.log:1-3 记录了线上 GET /api/exchangerateuserconfig!get.action 进入 CI4 Router 并抛 BadRequestException。也就是说线上确实有 /api/* 请求走到了 index.php⁠。

接手第一步⁠：curl -s https://demo.w2r.site/api/ | jq .data.framework⁠，再逐个 curl /api/menu⁠、/api/news?limit=1 并观察 writable/logs/ 与 writable/debugbar/ 是否新增文件（走 CI4 才会新增）。生产 nginx/Apache vhost 配置不在仓库里⁠，属于缺失交接物，必须从服务器上取回归档。

backend/README.md:5-8 记录了 api.php 存在的原因：服务器 PHP 禁用了 putenv⁠、未装 mbstring⁠。但 backend/public/index.php:7-9 已经加了 mbstring polyfill，前提条件可能已经部分消失——这也是收敛为单一实现的机会。

5. 前端：哪些来自接口，哪些是硬编码

来自接口的只有三块⁠：顶栏菜单树、首页 Latest Release 三张卡（标题/日期/封面/链接）、新闻详情正文（标题、日期、tags、正文 HTML、面包屑栏目、files[0] 的下载地址）。

其余全部硬编码在组件里⁠：

• 首屏大标题与英文导语：HeroBanner.vue:54-56（中英文页共用同一段英文）
• 三段 feature 文案（Mobility for Generations / Innovation / CSR）：FeatureAlternatingSections.vue:54-70
• 「Latest Release」「View All」：LatestReleaseSection.vue:5,7
• 12 个品牌 logo：assets/figma/brandLogos.js:5-7 读本地 logo1..12.svg⁠，无链接、无 CMS 来源
• 社媒区三个标签 ['Weibo','WeChat','WeChannel'] 且三个位共用同一张二维码图⁠：SocialQrSection.vue:29,10
• 页脚五条链接与备案号：SiteFooter.vue:43-49,52
• CSR 轮播的 5 个圆点是静态的，第一个永远高亮，没有轮播逻辑：FeatureSplitSection.vue:24-33
• 面包屑兜底中文「媒体中心」：adaptNewsDetailResponse.js:21-22
• 新闻详情三处图标是 Figma MCP 外链：mcp-assets.js:59-62

6. 完成度与死链清单

存在且接了真数据⁠：首页（/⁠、/en/⁠）、新闻详情（/news/:uuid⁠、/en/news/:uuid⁠）。就这两个。

占位/未完成⁠：HomeIntroBandSection.vue 是空 section（真正的 intro 在 HeroBanner.vue:42-45⁠）；详情页没有封面图、没有上下篇、没有 SEO 注入（frontend/index.html:6 标题恒定）；无搜索、无语言切换、无栏目列表页。

死链清单⁠：

7. shared/dam-writable 符号链接

shared/dam-writable -> /www/wwwroot/w2r.site/backend/writable⁠，作用见 shared/README.md:1-18⁠：让 demo 站直接读生产 CMS 的 DAM 物理文件，配合 .env:24 的 asset.storageRoot⁠。

本地影响⁠：本机没有 /www 目录，链接悬空。所有 /api/asset/{id} 在 demo_asset_delivery.inc.php:61-66 命中 is_file() 失败返回 404 File missing⁠，本地新闻封面一律裂图——这不是代码 bug，别去改代码。本地要验证封面，需 mkdir -p 一个目录并把 .env:24 指过去，再放几个符合 storage_key 路径的文件。

风险面⁠：这条链接直通生产 CMS 的写目录。任何在 demo 目录下跟随符号链接的 rsync -a --delete⁠、rm -rf⁠、chown -R⁠、备份脚本，都会直接作用到 w2r.site 的媒体原始文件。已知缺失交接物里包含 backend/writable/（DAM 媒体），意味着这批文件目前只存在于生产服务器上，没有第二份副本。

8. 接手第一周建议顺序

1. 取回并归档生产 nginx/Apache vhost 配置，用 /api/ 的 data.framework 实测确认 §4 的分发真相。在结论明确之前，任何后端改动都要两份一起改⁠。
2. 本地重新执行前端构建（禁止在本次审计中执行），diff frontend/dist 与仓库现有产物，确认线上是否包含 HeaderNav.vue 最后一次改动。
3. 把 .env:5 改成 production⁠，清 writable/debugbar/（424 个 json）。
4. 修 api.php 的错误伪装（:142,157,166,212-216 改成真实 5xx），否则后续任何故障都查不到。
5. 把 mcp-assets.js:59-62 三个 Figma 外链换成本地 SVG。
6. 给 router 加 catch-all → NotFound 页，先止住「点导航一片空白」。
7. demo_asset_delivery.inc.php 加「资产必须挂在已发布 entry 上」的校验，并改成流式输出。

不要做的事⁠：不要顺手删 app/Controllers/News.php「因为它没用」——在 §4 结论出来之前它很可能就是线上正在跑的那一份。

主要风险

• Sitecore 侧访问权限是单点依赖且很可能已随人员离职失效。三个抓取脚本（import_sitecore_files / import_sitecore_news / update_sitecore_channels_and_assets --update-import）都靠 backend/.env 里的 sitecore.LOGGING_URL / username / password 登录 cm.volkswagengroupchina.com.cn 后台，用 Playwright 填表拿 __RequestVerificationToken 再在页面上下文 fetch 内部接口。这套凭据、接口路径（/admin/FilesUpload/GetFilesList、/admin/AdminNews/GetNewsList、/admin/AdminNews/GetNews）和 7 个 channel GUID 只存在于本仓库文档里，Sitecore 侧没有任何契约保障。凭据一旦失效或对方改版，所有增量补抓能力立即归零，而原始数据（sitecore_files_import / sitecore_news_import 两张临时表）又不在交接的数据库导出里——导出本身也缺失。
• 文档体系与代码存在成代际的脱节，且脱节部分正好是最需要文档的部分。docs/import_sitecore_news.md 与 scripts/README.md 关于新闻导入的整章描述的是一个已被删除的脚本版本；scripts/README.md 详述了 4 个不存在的脚本；docs/import_sitecore_files.md 引用了不存在的 stats 脚本。相对地，docs/cms/ 下 26 份设计文档质量很高、changelog.md 更新到 2026-06-21，容易让接手者误以为整个文档体系都可信。判定规则应当是：docs/cms/ 的设计文档可信度高（可与 backend/app/Database/Migrations/ 的 51 个迁移逐条对上），docs/ 根目录下 6 份脚本说明必须逐条对着源码复核后才能用。
• 整条迁移链路没有任何回滚点。sitecore_files_import 每次导入前被 TRUNCATE；DAM 文件落在 backend/writable/uploads/dam/ 而该目录整个缺失；所有失败日志（migrate_sitecore_files_failures.log 等 5 个）都在 backend/writable/logs/ 下，同样缺失；数据库导出也没有。这意味着 migrate_video.log:132 记录的那 1 条失败视频（{E8EC3D5F-85F4-4BF2-84B8-124DEC08F983} 驭势而上 RISE UP）现在无法查明失败原因，--retry-failures 模式（migrate_sitecore_files_to_dam.py:878-886）因为读不到失败日志而完全不可用。
• 多个脚本把「环境相关的自增主键」当常量写死，任何库重建都会静默错配而不是报错。category_id 60（新闻封面）、2–8（7 个 Sitecore channel）都来自 asset_categories 的自增 id，而这些行是迁移 2026-03-04-100031 遍历 channels 表动态插入的。assets.category_id 没有外键约束，错配不会抛异常，只会让媒体库分类树看起来「差不多对」。已知迁移 2026-03-04-100031 在干净库上因硬编码 created_by=1 跑不通，一旦有人修复它并重建库，这些常量的对应关系就会整体偏移。
• reset_sitecore_dam_assets.py 与 update_sitecore_channels_and_assets.py --update-assets 是两颗生产环境地雷，且后者是文档推荐的常规操作。前者有 --confirm 保护但删除时不清理无外键的 poster_asset_id / cover_asset_id 引用；后者完全没有保护，一条命令即可把大批资产的 category_id 置空。交接后应立刻在这两个脚本入口加环境白名单或强制二次确认，在此之前应视为禁止执行。
• security-scan.sh（1236 行，其中 475-938 行是内嵌 HTML 报告模板）指向的项目根 /www/wwwroot/vgc 与实际部署路径 /www/wwwroot/w2r.site 不符，唯一一份扫描结果停留在 2026-01-25。加上 docs/software-bom.md 记录的生产栈（PHP 8.3.30 / MySQL 5.7.44 / CI4 4.7.2）与本机复现环境（PHP 8.2.33 / MySQL 8.0.46）不一致，合规材料（quickcheck 对照表、SBOM、日志清单 TSV）目前只能代表历史某一时点，不能作为当前系统的合规证据直接提交。

---

交接范围：/Volumes/ProjectsAPFS/VWCORP/w2r.site/scripts/ 全部 11 个 .py（5,325 行）、docs/ 全部文档（根目录 14 份 md + docs/cms/ 26 份 md + 2 份 .mmd + 1 个 .py + tsv/csv/docx/xlsx/png）、根级 README.md⁠、SECURITY-SCAN-README.md⁠、security-scan.sh（1,236 行）、migrate_video.log（220 行）、security-scan-results/（7 个文件）。

---

一、这个模块到底是什么

它不是「CMS 的一部分」，而是一次性的 Sitecore → 新 CMS 数据搬迁工程⁠，加上围绕它长出来的一整套设计与合规文档。搬迁已经基本做完（最后一次脚本改动是 migrate_sitecore_files_to_dam.py 的 2026-07-22），现在处于「跑完了但随时可能要补跑」的状态。

数据源是大众中国的 Sitecore 后台 https://cm.volkswagengroupchina.com.cn⁠。所有脚本都不走 Sitecore 官方 API，而是用 Playwright 无头浏览器登录后台、从页面上抓 __RequestVerificationToken⁠，再在页面 JS 上下文里 fetch 后台的内部接口（见 scripts/import_sitecore_files.py:234-258⁠）。这是个很脆的设计，但也是当时唯一能拿到数据的路子。

整条链路是「两张临时表 + 一组搬运脚本」：

Sitecore 后台
   │ Playwright 登录 + 页内 fetch
   ├─ /admin/FilesUpload/GetFilesList  ──► sitecore_files_import   (文件/图片/视频清单)
   └─ /admin/AdminNews/GetNewsList
      /admin/AdminNews/GetNews         ──► sitecore_news_import    (新闻正文清单)
                                              │
                          ┌───────────────────┴───────────────────┐
                          ▼                                       ▼
              assets / asset_variants                   entries / entry_i18n
              （HTTP 下载真实文件落盘）                   （封面、附件、正文关联）
                          │                                       │
                          └──────────► replace_sitecore_media ◄────┘
                                       （正文里的 Sitecore URL 改写成 /asset/{id}）

两张临时表只存清单不存二进制（docs/sitecore-files-import-plan.md:75 明确写了这一点），文件是后续脚本按 path_val 拼 URL 现下载的。

---

二、11 个脚本逐个说明

下面每条都给出：用途 / 调用 / 数据来源 / 写入目标 / 幂等性 / 破坏性。

1. import_sitecore_files.py（737 行）— 文件清单抓取

• 用途⁠：把 Sitecore「附件管理 / 图片管理 / 视频管理」三个模块的全部条目抓进 sitecore_files_import⁠。
• 调用⁠：python3 scripts/import_sitecore_files.py [--languages=zh-cn,en | --language zh-cn --language en]⁠，默认中英双抓。
• 来源⁠：POST {base}/admin/FilesUpload/GetFilesList⁠，表单参数 __RequestVerificationToken / pageIndex / pageSize / language / searchName / Status / channel / type⁠。type 取 Document|Image|Video⁠；Document 不传 channel，Image 循环 3 个 channel GUID（import_sitecore_files.py:141-145⁠），Video 循环 4 个（:146-151⁠）。token 优先从 /admin/FilesUpload/Index 取，被重定向时回退到 /admin/AdminNews/Index（:513-525⁠）。
• 写入⁠：MySQL 表 sitecore_files_import（30 列，建表语句内嵌在 :318-361⁠，也有对应迁移 2026-03-11-100034⁠）。调试快照写 writable/import_sitecore_files/getfileslist_debug.json⁠。
• 幂等⁠：否，而且是反的⁠。:493 在登录之前就 TRUNCATE TABLE⁠，中途任何失败都会留下空表或半表。Image/Video 阶段用 _insert_or_merge_channel（:408-451⁠）按 (sitecore_id, language_val) 合并 channel_ids，这一段是幂等的，但整体不是。
• 破坏性⁠：中（只动临时表，但会清空下游四个脚本唯一的数据源）。
• 实测规模⁠：writable/import_sitecore_files/getfileslist_debug.json 显示 Document/zh-cn 的 TotalCount=1650⁠；docs/import_sitecore_files.md:166 记录三类合计 4,205 条。

2. import_sitecore_news.py（494 行）— 新闻清单抓取

• 用途⁠：抓 Sitecore AdminNews 的中英文新闻列表 + 逐条详情，写 sitecore_news_import⁠。
• 调用⁠：python scripts/import_sitecore_news.py [--languages zh-cn,en]⁠。只有这两个参数⁠。
• 来源⁠：POST /admin/AdminNews/GetNewsList（分页，pageSize 默认 10，可用 SITECORE_NEWS_PAGESIZE 覆盖）+ 逐条 POST /admin/AdminNews/GetNews⁠。响应字段见 writable/import_sitecore_news/get_news_raw_sample.json（25 个字段，含 HtmlContent⁠、AllocaitedPosition⁠、ArticleImgID⁠、DocumentIDs⁠）。注意 Sitecore 侧字段名 AllocaitedPosition 是拼错的，脚本 :271 原样沿用。
• 写入⁠：sitecore_news_import⁠，UNIQUE KEY 是 (sitecore_id, language_val)⁠，写入用 INSERT ... ON DUPLICATE KEY UPDATE（:348-360⁠）。
• 幂等⁠：是（upsert）。这是全套里唯一真正可重复执行的抓取脚本。
• 破坏性⁠：低。
• ⚠️ 文档陷阱⁠：docs/import_sitecore_news.md 和 scripts/README.md:12-70 描述的是一个已被删除的旧版本⁠——那个版本有 --step=1..4⁠、--clear⁠、--dump-list-page⁠、list_zh.json/list_en.json 缓存、LIST_SELECTORS/DETAIL_SELECTORS⁠，而且直接写 entries + entry_i18n + asset_entry_i18n⁠。现有代码一样都没有。旧版本的产物还留在 writable/import_sitecore_news/newslist.json（636KB，zh 1,576 条 / en 327 条，字段 item_id/edit_url/cover_img⁠），这也是判断这个版本真实存在过的直接证据。这份文档不能用。

3. update_sitecore_channels_and_assets.py（336 行）— channel 刷新与回写

• 用途⁠：不重新全量导入的前提下，单独刷新 channel 归属。
• 调用⁠：--update-import（只刷临时表，需 Playwright）/ --update-assets（只回写 assets，只需数据库）/ 不传参数则两步都做。
• 来源⁠：同 1，复用 import_sitecore_files 的登录与请求函数（:53-63 直接 import）。
• 写入⁠：sitecore_files_import.channel_ids⁠；以及 assets.category_id 和 assets.publish_date⁠。
• 幂等⁠：--update-import 是（覆盖写）。
• 破坏性⁠：极高，见下方「地雷」一节⁠。

4. migrate_sitecore_files_to_dam.py（1,031 行）— 主力搬运脚本

• 用途⁠：把 sitecore_files_import 里的清单变成真实的 DAM 资产。
• 调用⁠：python scripts/migrate_sitecore_files_to_dam.py [--limit=N] [--dry-run] [--skip-existing] [--workers=N] [--type=Image|Video|Document] [--retry-failures]⁠。默认 workers=5⁠；--type=Video 会强制降为单线程并逐条打印（:898-901⁠）。
• 来源⁠：sitecore_files_import 全表；文件本体从 https://cm.volkswagengroupchina.com.cn/{path_val} HTTP 下载（视频 timeout 300s/重试 3 次，文档 180s/3 次，图片 120s/2 次，见 :712-717⁠）。
• 写入⁠：assets（主记录）、asset_variants（entity_list_json[0] 的高精度版，quality=high）、视频封面另建一条 type=image 的 assets 并回填 poster_asset_id（ensure_video_poster_asset⁠，:409-497⁠）。文件落 backend/writable/uploads/dam/YYYY/MM/sitecore_{ymd}_{guid}.{ext}⁠。
• 关键逻辑⁠：merge_rows_by_sitecore_id（:201-272⁠）把同一 GUID 的 zh-cn 与 en 两行合并成一条，分别填 title_zh/title_en⁠、description_zh/description_en⁠。这是为了修 docs/cms/sitecore-dam-migration-analysis.md:1321 记录的「title_en 从未写入」的老 bug。
• 幂等⁠：部分⁠。已存在 sitecore_id 时走「只更新元数据、不重新下载」分支（:686-700⁠），设计上可重跑。但文件先落盘后写库（:738 vs :745⁠），INSERT 失败会留孤儿文件。
• 破坏性⁠：中（会覆盖已有 assets 的 title/meta/category/status/publish_date）。

5. backfill_video_posters_from_sitecore.py（438 行）— 视频封面补全

• 用途⁠：给 2026-06-10 之前迁移的 196 条视频补 poster_asset_id（当时 4 号脚本还没有封面逻辑）。
• 调用⁠：[--limit=N] [--dry-run] [--skip-existing]⁠。注意 --skip-existing 语义是「封面资产不存在时跳过、不新建」，和别的脚本里同名参数含义不同。
• 来源⁠：assets JOIN sitecore_files_import 取 thumbnail_id/thumbnail（:217-264⁠），封面路径形如 /-/media/Asset/Thumbnails/*.ashx⁠，实际响应是 JPEG，靠 Content-Type/Content-Disposition 推扩展名（:141-161⁠）。
• 写入⁠：新增 assets（type=image）+ 回填视频行的 poster_asset_id⁠。
• 幂等⁠：是（:284-286 先查 sitecore_id，:377 的 UPDATE 带 poster_asset_id IS NULL OR = 0 条件）。
• 破坏性⁠：低。现已被 4 号脚本内置逻辑取代⁠，属于历史补丁。

6. sync_video_assets_status_from_sitecore.py（295 行）— 视频状态同步

• 用途⁠：把 Sitecore 的 status（1=已保存 / 2=已发布）和 publish_date 同步到 assets。
• 调用⁠：[--dry-run]⁠。范围硬限定 assets.mime = 'video/mp4'⁠。
• 来源/写入⁠：sitecore_files_import → assets.status / assets.publish_date⁠。同一 GUID 多行时优先 zh-cn，其次 en（:138-166⁠）。
• 幂等⁠：是（先 diff 再更新，无变化不写）。
• 破坏性⁠：低。docs/sync_video_assets_status.md:35-36 记录实际执行结果：status 195 条、publish_date 补 41 条。

7. migrate_news_covers_to_assets.py（521 行）— 新闻封面入 DAM

• 用途⁠：把 sitecore_news_import.article_img/article_img_id 的封面图下载入 assets。
• 调用⁠：[--limit=N] [--dry-run] [--skip-existing] [--no-cross-ref] [--workers=N]⁠。--workers 是假的（见缺陷 12）。
• 来源⁠：article_img 优先；为空时用 article_img_id 去 sitecore_files_import 反查 path_val/url_val（--no-cross-ref 关掉这个兜底）。
• 写入⁠：assets⁠，category_id 硬编码 60⁠、status 硬编码 2（已发布）。文件名 news_cover_{ymd}_{guid}.{ext}⁠。
• 幂等⁠：是（:322-326 sitecore_id 已存在则 skip）。
• 破坏性⁠：低。
• 边界⁠：明确不写 entries.cover_asset_id 也不写 asset_entry_i18n⁠，那是 8 号脚本的事（docs/migrate_news_covers_to_assets.md:66⁠）。

8. migrate_sitecore_news_to_entries.py（667 行）— 新闻正文入库

• 用途⁠：sitecore_news_import → entries + entry_i18n + asset_entry_i18n⁠。
• 调用⁠：[--limit=N] [--dry-run] [--skip-existing] [--clear]⁠。
• 关键映射⁠：
• entries.uuid = sitecore GUID 去大括号转小写（:365⁠）——注意这是把 uuid 字段征用成了 Sitecore 溯源键。
• entry_i18n.slug = news-{uuid}（zh）/ news-{uuid}-en（en）。
• entries.channel_id 是 JSON 数组⁠，由 allocated_position GUID 映射：{2FF9B990-…}→官网新闻、{CA41F3DD-…}→媒体新闻（:40-43⁠），优先读 config 表 sitecore.news_allocated_position_to_channel⁠，否则按 channels.name_zh 查。
• 状态一律 draft（:386⁠），要人工审核发布。
• document_ids 查 assets 组装成 entry_i18n.files 的 [{name,url:/asset/{id}}]⁠。
• 幂等⁠：是（slug 判重，:370-376⁠）。
• 破坏性⁠：--clear 会按 sitecore_news_import 的 GUID 删除 entries/entry_i18n/asset_entry_i18n（run_clear⁠，:573-638⁠），范围受控但不可撤销。
• 已知缺陷⁠：非事务，见缺陷 3。

9. replace_sitecore_media_in_content_json.py（371 行）— 正文 URL 改写

• 用途⁠：把 entry_i18n.content_json 里残留的 Sitecore 图片/视频地址换成本地 /asset/{id}⁠。
• 调用⁠：[--limit=N] [--dry-run] [--type=news]（文档里写的 --verbose 无效）。
• 匹配三条路⁠：URL 里的 sc_itemid={GUID} → assets.sitecore_id⁠；data-id="{GUID}" 属性 → 同上；否则按 /-/media/ 路径去 assets.sitecore_path 或 sitecore_files_import.path_val 反查（:119-179⁠）。
• 写入⁠：改写 <img src>（同时删掉 data-id⁠、加上 data-asset-id⁠）、<source src>⁠、<video src>⁠，回写 content_json⁠。会保留原本是 JSON 数组还是 JSON 字符串的格式（:326-329⁠）。
• 幂等⁠：是（改写后不再含 Sitecore 特征，二次运行直接 skip）。
• 破坏性⁠：中（直接改正文，无备份；正则替换 HTML 存在边界风险）。

10. reset_sitecore_dam_assets.py（274 行）— 回滚删除器

• 用途⁠：撤销 4 号脚本的成果。按 assets.meta_json 里的 "sitecore_migrate": true 标记找出记录，删数据库行 + 删磁盘文件。
• 调用⁠：默认 dry-run⁠，必须显式 --confirm 才真删。支持 --type=image|video|file 和 --category-id=N 过滤。
• 安全措施（已有的）⁠：_safe_abs_path（:95-109⁠）做了路径穿越校验，确保只删 backend/writable/ 底下的东西；删除前先打印命中统计。
• 安全缺口（缺的）⁠：不清理引用它的 entries.cover_asset_id 和 assets.poster_asset_id⁠——这两列都没有外键（迁移 2026-01-24-100017:80 只给 created_by 建了 FK），删完直接悬空；asset_entry_i18n 是 CASCADE，会被无声连带删掉。详见缺陷 5。
• 破坏性⁠：最高。这是整个仓库里唯一一个会主动删生产数据和文件的脚本。

11. gen_diagram_images.py（161 行）— 文档配图生成

• 与迁移无关。用 Pillow 画 5 张流程图 PNG 到 docs/images/⁠，给 project-introduction.md 转 Word 时插图用。字体路径全是 Linux 的（:12-16⁠），在 macOS 上会 fallback 到 ImageFont.load_default()⁠，中文会变方块。

附：docs/cms/gen_quickcheck_xlsx.py（119 行）

不在 scripts/ 下但同属本模块。把 quickcheck-corporate-website-0202.md 的 41 行合规对照表硬编码成 ROWS 常量再生成 xlsx，依赖 openpyxl。md 和这个 py 里的数据是两份拷贝⁠，改一处不会同步另一处。

---

三、迁移叙事：迁了什么、什么顺序、到哪一步了

推荐执行顺序（从代码交叉引用反推，文档里没有一处完整写出）

0. cd backend && php spark migrate      # 建两张临时表 + assets 的 sitecore 字段 + config 种子
1. import_sitecore_files.py             # → sitecore_files_import   (⚠️ 会 TRUNCATE)
2. update_sitecore_channels_and_assets.py --update-import   # 可选，仅刷 channel_ids
3. migrate_sitecore_files_to_dam.py     # → assets + asset_variants + 视频封面
4. sync_video_assets_status_from_sitecore.py                # → 视频 status/publish_date
5. import_sitecore_news.py              # → sitecore_news_import
6. migrate_news_covers_to_assets.py     # → 封面入 assets (category 60)
7. migrate_sitecore_news_to_entries.py  # → entries + entry_i18n
8. replace_sitecore_media_in_content_json.py                # → 正文 URL 改写

历史补丁：backfill_video_posters_from_sitecore.py（已被 3 内置取代）
回滚：reset_sitecore_dam_assets.py（撤销 3）
禁止：update_sitecore_channels_and_assets.py --update-assets（当前版本有数据损坏风险）

时间线（按文档变更记录 + 文件 mtime + 日志实证）

migrate_video.log 的读法

这是唯一一份保留下来的执行实证，值得逐条看：

• :2 — 共 197 条（已按 sitecore_id 合并中英行）| workers=1⁠，确认 --type=Video 触发了强制单线程。
• :3 起 — 每条打印 sitecore_id / title_zh / title_en -> OK⁠。可以直接看出双语合并生效了（如 :20 中文「进博会：今天的展览 明天的生活」对英文「CCTV Interview during CIIE」）。
• :132 — 唯一一条 FAIL⁠：{E8EC3D5F-85F4-4BF2-84B8-124DEC08F983} 「驭势而上 RISE UP」。有意思的是 :215 有一条同名但不同 GUID 的 {1BD64F23-85FE-429F-B380-5FBD13CF130E} 迁移成功了，说明是单个文件的下载问题而非逻辑问题。
• :13, :24, :35… — 进度行显示 约 0.0/s⁠、ETA 一度到 626 分钟。平均每条视频 3.4 分钟，主要是大文件下载 + 每条一次 HD 变体 + 一次封面共三次 HTTP 往返。
• :220 — 结尾暴露了生产部署路径 /www/wwwroot/w2r.site/backend/writable/logs/⁠，这条信息在别处没有。

现在处于什么状态

文件侧和新闻侧都已搬完，最后一次调整在 2026-07。但验证材料全部缺失⁠：backend/writable/（DAM 文件 + 5 份失败日志）整个目录不在交接包里，数据库导出也没有。所以「196 条视频的文件现在还在不在」「那 1 条失败的原因是什么」「新闻迁了多少条」这三个问题，目前无法从交接物里回答。--retry-failures 模式（migrate_sitecore_files_to_dam.py:878-886⁠）因为读不到失败日志而不可用。

---

四、两颗地雷（接手第一天就该处理）

地雷 A — update_sitecore_channels_and_assets.py --update-assets

run_update_assets 里 category_id = None 是初值（:273⁠），只有当 channel_ids 里有 GUID 命中映射时才被赋值。没命中就带着 None 进 UPDATE（:281-289⁠）。而 Document 类型天生没有 channel（docs/sitecore-files-import-plan.md:28 明说 channel 参数仅对 Image/Video 有效），新闻封面也没有。所以在当前生产库上执行这条文档推荐的常规命令⁠，会把 1,650+ 条文档资产和全部新闻封面的 category_id 置为 NULL。没有 --dry-run⁠，没有确认，没有日志，assets.category_id 也没有外键会拦。

地雷 B — reset_sitecore_dam_assets.py --confirm

删得干净但删得不够干净：删了 assets 行和磁盘文件，却不清 entries.cover_asset_id / assets.poster_asset_id（无外键，悬空），asset_entry_i18n 则被 CASCADE 静默清掉。带 --type=image 跑一次，所有视频的封面指针就都指向不存在的 id 了。

两个脚本在加保护之前都应视为禁止在生产执行⁠。

---

五、文档体系：哪些能信，哪些不能

40 份 Markdown 分成质量差异极大的三档。

可信（docs/cms/⁠，26 份）

这批是真正的资产。architecture.md（信任边界 + 5 张 Mermaid DFD）、requirements.md（范围与非目标写得很硬，明确「不做 PDF 全文检索 / 不做多码率流媒体 / 不做历史数据迁移」）、mysql-schema.md（v1.10，逐版变更记录）、field-dictionary.md（v1.8）、state-machine.md（9 个状态流转，每个都写清了权限点、前置条件、必记审计事件、字段更新）、security-model.md（7 角色 + 21 权限点）、dam-design.md（v1.4）、audit-logging.md + audit-gap-implementation.md（P0/P1/P2 差距清单，标注 2026-05-21 已完成）、data-model-diagrams.md（896 行，配 diagrams/*.mmd 可导出）。

与代码相符度：高。mysql-schema.md 的变更记录能和 backend/app/Database/Migrations/ 的 51 个迁移逐条对上——v1.3 对 2026-02-03-100026_AddPasswordChangedAtToUsers⁠、v1.4 对 …-100027_AddShowInMenuToChannels⁠、v1.5 对 …-100029_AddUuidToEntries⁠、v1.6 对 …-100030_ChangeEntriesChannelIdToJson⁠、v1.7 对 2026-02-25-100000_AddFilesToEntryI18n⁠、v1.8 对 …-100035_CreateAssetVariantsTable⁠、v1.10 对 2026-04-29-100050_CreateEntryCssVersionsTable + …-100051_AddFigmaImportPermission⁠。这种一一对应关系在离职交接里相当少见。

docs/changelog.md 维护到 2026-06-21，且每条都带模块和文件路径，是理解最近半年改了什么的最快入口。

小瑕疵：requirements.md:270 写「不做历史数据迁移」，而整个 scripts/ 目录就是历史数据迁移——这是需求边界后来被突破了但没回改文档。video-delivery-and-transcoding.md:20 倒是老实交代了另一处边界收窄（视频改成 720p/1080p 双精度）。

半可信（根级 docs/⁠，需逐条核）

project-introduction.md（465 行）、software-bom.md（169 行）、changelog.md 内容本身没问题，但环境信息已经漂移：

• project-introduction.md:44 写生产域名 https://vgc.digirepub.com/⁠；migrate_video.log:220 显示部署路径 /www/wwwroot/w2r.site⁠；security-scan.sh:9 又写 /www/wwwroot/vgc⁠。项目在生命周期里至少换过三个身份（vgc → w2r.site → vgc.digirepub.com 域名），文档没统一。
• software-bom.md:15-22 记录生产栈是 PHP 8.3.30 / MySQL 5.7.44 / CI4 4.7.2 / Node 18.19.1；而本机复现环境是 PHP 8.2.33 / MySQL 8.0.46。MySQL 大版本不同，JSON 函数和 utf8mb4 排序规则行为都有差异，entries.channel_id 的 JSON_CONTAINS 筛选值得实测。
• docs/cms/figma-import.md:5⁠、video-delivery-and-transcoding.md:4 引用 ../../../docs/*.md（workspace 级），checklist-implementation.md:3 引用 docs/checklist.xlsx 和 checklist-mapping.csv ——这 4 份文件都不在交接包内⁠。

不可信（脚本说明，6 份 + scripts/README.md⁠）

这是最需要提醒的部分。

__pycache__/import_vgc_news.cpython-312.pyc 还在（2026-02-09），必要时可以反编译找回那个脚本。

合规材料（security-scan.sh + 扫描结果 + quickcheck + 日志清单）

security-scan.sh 1,236 行，其中 :475-938 是一大块内嵌的 HTML 报告模板，实质逻辑只有几百行（npm audit / composer audit / 依赖树 / 许可证 / 文件统计）。:9 的 PROJECT_ROOT 写死 /www/wwwroot/vgc⁠，加上 :6 的 set -e⁠，在当前部署下跑不通。security-scan-results/ 里唯一一份结果是 2026-01-25 生成的，found 0 vulnerabilities⁠，项目名 vgc@1.0.0⁠，依赖版本（vue 3.5.26 / vite 7.3.1）与 software-bom.md:5 记的 2026-05-18 版本（vue 3.5.34 / vite 6.4.2）对不上——过去半年没有真正跑过扫描⁠。

docs/cms/quickcheck-corporate-website-0202.md（41 条大众集团 Measure 逐条对照，含 4 条明确「不满足」：应用内密级标注、导出文档密级、上传病毒扫描）和 docs/cms/log-inventory-excel-en.tsv（35 行英文日志清单，含 KSU 分级和留存期）质量很高，但同样属于「某个时点的快照」，作为当前合规证据前需要重新核。

---

六、运行这些脚本需要什么

Python 版本⁠：3.12（software-bom.md:22 与 __pycache__ 的 cpython-312 一致）。最低 3.9——多数脚本有 from __future__ import annotations⁠，但 reset_sitecore_dam_assets.py:143 等处在函数体内用了 list[object]⁠。

pip 依赖（按脚本）⁠：

⚠️ 随包 .venv 不能用⁠：里面是 x86_64-linux-gnu 的二进制（从生产服务器整体拷来），且只装了 pymysql 1.2.0 / bcrypt 5.0.0 / requests 2.34.2，没有 playwright⁠。macOS 上必须重建：

python3 -m venv .venv && .venv/bin/pip install pymysql bcrypt requests playwright pillow openpyxl
.venv/bin/playwright install chromium

配置来源⁠：所有脚本都自带一份几乎相同的 load_env()⁠，依次读 backend/.env 再读项目根 .env（根 .env 不存在），把 database.default. 映射成 DB_⁠、sitecore. 映射成 SITECORE_⁠。当前 backend/.env 里 4 个 sitecore 键和 7 个 database 键都在（值见 backend/.env⁠，不在此复述）。可选环境变量：IMPORT_USERNAME（默认 vgc_news⁠）、IMPORT_PASSWORD（默认值硬编码在各脚本约 :123 行，属于弱默认口令，应改）、SITECORE_GETFILESLIST_PAGESIZE⁠、SITECORE_NEWS_PAGESIZE⁠、SITECORE_GETFILESLIST_PARENTID/NODEID/YEAR⁠。

---

七、接手建议（按优先级）

1. 立刻给两颗地雷加锁⁠：给 update_sitecore_channels_and_assets.py --update-assets 加 --dry-run 和「无匹配则跳过而非置 NULL」；给 reset_sitecore_dam_assets.py 加引用检查。约 4 小时。
2. 补齐缺失物⁠：数据库导出、backend/writable/（DAM 文件 + 5 份失败日志）。没有这两样，任何数据核对都做不了。
3. 把硬编码的 category_id 挪进 config 表⁠：60 和 2–8 都应该从 config 读，且启动时校验分类是否存在，不存在就报错而不是静默错配。
4. 清理文档⁠：删掉 docs/import_vgc_news.md⁠，重写 docs/import_sitecore_news.md 和 scripts/README.md 的新闻章节，删掉 4 个不存在脚本的说明。这一步不做，下一个接手的人还会踩同样的坑。
5. 写一份 scripts/PIPELINE.md⁠：把第三节那张执行顺序图固化下来。现在这个顺序只能靠交叉阅读 8 个脚本的 docstring 反推。
6. 修 security-scan.sh 的路径并重跑一次⁠，让合规材料回到当前时点。