项目架构与技术地图

该 DOCX 包含不完整的 Office 元数据关系，已使用兼容模式恢复正文和媒体。

图示DOCXv1.0

图示DOCX下载原文件

> 该 DOCX 包含不完整的 Office 元数据关系，已使用兼容模式恢复正文和媒体。

ARCHITECTURE.md

项目架构与技术地图

文档版本： v1.0文档状态：持续维护最后更新： 2026-07-27文档性质：项目架构事实源适用对象：项目负责人、AI开发助手、代码审查AI、测试AI、后续维护人员

0. 本文件的作用

本文件用于回答：

这个项目到底是怎么组成的？

包括：

项目有哪些模块

前端在哪里

后端在哪里

页面在哪里

组件在哪里

API在哪里

数据库在哪里

登录在哪里

管理员系统在哪里

配置在哪里

字体在哪里

静态资源在哪里

数据怎么流动

权限怎么流动

AI修改某个功能时应该去哪几个文件

本文件不负责：

记录项目当前进度。

项目进度请查看：

PROJECT_STATUS.md

Bug详情请查看：

BUG_TRACKER.md

配置修改方式请查看：

CONFIGURATION.md

历史版本变化请查看：

CHANGELOG.md

部署方式请查看：

DEPLOYMENT.md

1. 架构文档最高原则

1.1 禁止猜测

任何AI更新本文件时：

必须以当前实际代码为依据。

如果无法确认：

使用：

【待确认】

禁止根据：

README猜测

历史聊天猜测

文件名猜测

常见项目习惯猜测

直接写成事实。

1.2 代码与文档不一致时

如果发现：

ARCHITECTURE.md

与

当前实际代码

不一致：

以真实代码为调查对象。

但不得直接默默修改文档。

应记录：

【架构文档漂移】文档描述：实际代码：影响：建议：

确认后再同步。

2. 当前项目整体架构

当前项目的目标架构抽象如下：

用户 │ ▼ ┌─────────────┐ │ 浏览器/UI │ │ Frontend │ └──────┬──────┘ │ ▼ ┌─────────────┐ │ 页面/组件层 │ │ Pages / UI │ └──────┬──────┘ │ ▼ ┌─────────────┐ │ 前端业务逻辑 │ │ State/Logic │ └──────┬──────┘ │ ▼ ┌─────────────┐ │ API Client │ │ 请求统一入口 │ └──────┬──────┘ │ HTTP / HTTPS │ ▼ ┌─────────────┐ │ 后端API │ │ Backend │ └──────┬──────┘ │ ▼ ┌─────────────┐ │ 业务服务层 │ │ Service │ └──────┬──────┘ │ ┌─────────┼─────────┐ ▼ ▼ ▼ 数据库文件系统第三方服务 Database Storage AI/API

⚠️ 上图属于目标结构抽象。

实际项目是否完全采用以上分层：

待真实代码扫描确认。

3. 项目核心结构关系

项目主要分为：

项目│├── AI治理体系│├── 前端系统│├── 后端系统│├── API系统│├── 用户与认证系统│├── 管理员系统│├── 数据系统│├── 配置系统│├── 设计系统│├── 静态资源│├── 日志系统│├── 测试系统│└── 部署系统

4. 当前项目根目录

本节必须在扫描真实目录后更新。

建议最终形成类似：

PROJECT_ROOT/│├── AI_START_HERE.md├── PROJECT_STATUS.md├── ARCHITECTURE.md├── CONFIGURATION.md├── BUG_TRACKER.md├── CHANGELOG.md├── DEPLOYMENT.md├── README.md│├── AI_RULES/│ ├── 01_REQUIREMENTS_RULES.md│ ├── 02_DESIGN_SYSTEM_RULES.md│ ├── 03_ENGINEERING_RULES.md│ ├── 04_SECURITY_RULES.md│ ├── 05_TESTING_RULES.md│ └── 06_RELEASE_OPERATIONS_RULES.md│├── frontend/│├── backend/│├── config/│├── assets/│├── tests/│└── scripts/

注意：

以上仅为推荐结构。

不得为了匹配本文件而强制重新整理现有项目。

实际目录：

【待扫描】

5. AI治理层

5.1 AI入口

AI_START_HERE.md

作用：

AI进入项目的统一导航入口。

负责告诉AI：

应先读什么

哪些规则必须遵守

哪些地方不能乱动

如何修改

如何测试

如何报告

5.2 永久规则

AI_RULES/

包括：

01_REQUIREMENTS_RULES.md02_DESIGN_SYSTEM_RULES.md03_ENGINEERING_RULES.md04_SECURITY_RULES.md05_TESTING_RULES.md06_RELEASE_OPERATIONS_RULES.md

这些属于：

项目治理层

而不是：

运行时代码。

6. 前端架构

当前技术栈

前端框架：

【待扫描】

版本：

【待扫描】

构建工具：

【待扫描】

包管理器：

【待扫描】

前端入口：

【待扫描】

开发启动命令：

【待扫描】

Production Build命令：

【待扫描】

7. 前端目标分层

原则上建议保持：

Pages ↓Components ↓State / Business Logic ↓Services ↓API Client

每一层职责：

7.1 Pages 页面层

负责：

路由页面

页面结构

页面组合

页面级状态

不应负责：

数据库连接

Secret

服务端权限验证

实际目录：

【待扫描】

7.2 Components 组件层

负责：

按钮

卡片

弹窗

导航

输入框

工具展示组件

实验器件

动画元素

实际目录：

【待扫描】

7.3 Layout 布局层

可能包括：

HeaderSidebarNavbarFooterMain LayoutAdmin LayoutAuth Layout

实际实现：

【待扫描】

8. 当前主要页面地图

需要扫描真实路由生成。

建议最终形成：

页面	路由	页面文件	权限	状态
入口页	待确认	待扫描	游客	待验证
首页	待确认	待扫描	待确认	待验证
登录页	待确认	待扫描	游客	待验证
注册页	待确认	待扫描	游客	待确认
用户中心	待确认	待扫描	用户	待确认
管理后台	待确认	待扫描	管理员	待验证
404	待确认	待扫描	全部	待验证

不得依据UI截图判断页面存在。

必须根据真实路由和文件确认。

9. 路由架构

路由系统：

【待扫描】

路由入口文件：

【待扫描】

目标结构：

用户请求URL │ ▼ Router │ ┌────┼────┐ ▼ ▼ ▼首页用户页管理页 │ ▼ 权限检查

重点确认：

公开路由用户路由管理员路由404路由错误路由重定向规则

10. 前端状态管理

当前状态管理方式：

【待扫描】

可能包括：

Local StateContextReduxZustandPiniaVuex其他

需要重点确认：

用户状态

登录状态

主题状态

页面状态

全局配置

缓存状态

是否有统一入口。

11. 前端请求架构

当前API调用方式：

【待扫描】

目标：

页面/组件 │ ▼Service │ ▼统一 API Client │ ▼Backend API

禁止形成：

Component A → fetch(…)Component B → axios(…)Component C → localhost…Component D → 另一个BaseURL

12. API Client

实际文件：

【待扫描】

应统一处理：

API Base URL

Token

Timeout

HTTP状态

错误

401

403

429

500

网络异常

13. 前端设计系统

当前设计系统入口：

【待扫描】

应至少管理：

字体颜色字号字重间距圆角阴影动画层级响应式断点

目标：

Design Token │ ▼全局主题 / CSS变量 │ ▼公共组件 │ ▼具体页面

14. 字体架构

已知历史上曾出现：

font-config.jsonfont-loader.js字体CSS

但实际最新结构：

【待扫描确认】

目标字体调用链：

字体配置 │ ▼字体加载器 │ ▼CSS Variables │ ▼全局样式 │ ▼页面 / 组件

原则：

页面不得各自重新定义字体来源。

15. 静态资源架构

资源类型包括：

图片图标SVG字体视频音频JSON视觉素材

实际目录：

【待扫描】

需要区分：

源码资源公共静态资源用户上传资源运行时生成资源

不得混为一处。

16. 动画系统

当前项目存在较强视觉和动画需求。

包括可能的：

入场动画

呼吸动画

实验器件互动

人物动画

Hover

浮动效果

页面切换动画

实际动画实现：

【待扫描】

需要确认是否：

CSS AnimationJavaScript AnimationCanvasWebGLThree.jsGSAP其他

动画架构目标：

动画参数 ↓动画公共能力 ↓场景/组件

避免所有动画值散落在页面。

17. 后端架构

后端是否存在：

【待扫描确认】

后端框架：

【待扫描】

版本：

【待扫描】

入口：

【待扫描】

运行命令：

【待扫描】

监听端口：

【待扫描】

18. 后端目标分层

推荐结构：

Routes / Controller ↓Service ↓Repository / Data Layer ↓Database

并由中间件处理：

认证权限日志限流异常请求验证

19. 后端路由层

负责：

接收请求参数解析调用Service返回HTTP响应

不应承担：

大量复杂业务逻辑。

实际文件：

【待扫描】

20. Service业务层

负责：

用户业务登录业务管理员业务工具业务实验数据AI调用其他核心规则

实际实现：

【待扫描】

21. 数据访问层

目标：

业务层不要直接到处写数据库查询。

22. 中间件架构

需要确认是否存在：

Auth MiddlewareAdmin MiddlewareRate LimitCORSLoggingRequest ValidationError HandlerSecurity Headers

实际：

【待扫描】

23. API架构

后端API Base：

【待确认】

API版本：

【待确认】

例如：

/api/v1/

是否存在版本化：

【待确认】

24. API分类

应按真实项目整理。

例如：

/api/auth//api/users//api/admin//api/tools//api/files//api/ai/

实际接口：

【待扫描】

25. API完整调用链

典型结构：

用户点击 │ ▼前端组件 │ ▼前端Service │ ▼API Client │ ▼HTTP Request │ ▼Backend Route │ ▼Auth / Permission │ ▼Service │ ▼Database / External API │ ▼Response │ ▼Frontend │ ▼UI更新

任何功能异常，应按照这条链定位。

26. 用户认证架构

当前认证方式：

【待扫描】

可能：

SessionJWTCookieOAuth其他

目标认证流程：

用户提交登录 │ ▼后端验证身份 │ ▼生成认证状态 │ ▼返回Token/Cookie/Session │ ▼前端保存合理状态 │ ▼后续请求携带认证 │ ▼后端重新验证

27. 登录不是前端行为

真正登录认证必须发生在：

后端

前端：

只负责：

输入

请求

展示状态

不得自己判断：

“账号密码等于某个固定值，所以管理员登录成功。”

28. 用户权限架构

至少应区分：

GuestUserAdminSuper Admin（如存在）

实际角色：

【待扫描】

目标权限链：

Request │ ▼Authentication │ ▼身份确认 │ ▼Authorization │ ▼资源权限 │ ▼业务操作

29. 管理员架构

管理员入口：

【待扫描】

管理员认证：

【待扫描】

管理员API：

【待扫描】

管理员数据：

【待扫描】

必须保证：

前端管理员UI │ ▼管理员API │ ▼后端管理员权限验证 │ ▼业务操作

而不是：

隐藏菜单 = 安全

30. 数据库架构

数据库类型：

【待确认】

例如：

SQLiteMySQLPostgreSQLMongoDB其他

数据库连接文件：

【待扫描】

数据库配置：

【待扫描】

31. 数据模型

需要从真实代码/数据库生成。

建议最终记录：

UsersAdminsSessionsToolsProjectsExperimentsLogsUploads

但以上只是示例。

真实模型：

【待扫描】

32. 数据关系图

真实数据库确认后补充。

示例：

User │ ├── Session │ ├── Project │ │ │ └── Experiment │ └── Upload

不得凭业务想象补表。

33. 数据访问原则

数据库只能通过：

Backend

或安全服务层访问。

禁止：

Browser ↓Database

34. 数据环境

需明确区分：

Development DBTest DBProduction DB

实际状态：

【待确认】

35. 配置架构

当前配置位置：

【待扫描】

配置应按职责拆分，例如：

环境配置API配置数据库配置字体配置设计配置安全配置功能开关AI配置

36. 配置加载关系

目标：

Environment │ ▼Configuration Layer │ ├── Frontend Config ├── Backend Config ├── Database Config ├── AI Config └── Security Config

而不是：

每个模块自己从环境变量或硬编码里找值。

37. 环境变量架构

实际 .env 体系：

【待扫描】

建议至少明确：

.env.exampledevelopmentproduction

真实Secret禁止记录在本文件。

38. Secret流向

正确：

环境变量 ↓后端 ↓第三方服务

错误：

环境变量 ↓前端Bundle ↓用户浏览器

39. AI服务架构

如果当前项目已经调用AI：

AI提供商：

【待确认】

调用入口：

【待扫描】

模型：

【待确认】

目标：

Frontend │ ▼Backend AI Endpoint │ ▼AI Service │ ▼Model Provider

API Key只能存在后端。

40. AI调用治理

如果存在AI调用，必须在架构中明确：

认证权限请求长度Token限制调用频率并发超时费用控制错误降级

实际状态：

【待审计】

41. 第三方服务架构

需要列出所有外部依赖服务。

例如：

AI对象存储邮箱短信地图登录分析平台CDN支付

实际：

【待扫描】

建议最终表格：

服务	用途	调用位置	Secret位置	超时	失败降级
待扫描

42. 文件系统架构

如存在文件上传或本地文件能力：

需要区分：

项目源码文件静态资源用户上传缓存临时文件生成文件日志备份

实际目录：

【待扫描】

禁止：

用户上传文件

直接混进：

源码目录。

43. 日志架构

当前日志系统：

【待扫描】

目标包括：

Application LogError LogAccess LogLogin LogAdmin Audit LogSecurity Log

日志流：

应用事件 ↓Logger ↓日志输出 ↓日志文件 / 服务 ↓监控 / 排查

44. 错误处理架构

前端：

API Error ↓统一处理 ↓Error UI / Toast / Fallback

后端：

Exception ↓Global Error Handler ↓安全错误响应 ↓日志

禁止：

每个API自己随意返回完全不同的错误格式。

45. 缓存架构

需检查：

Browser CacheLocalStorageSessionStorageIndexedDBService WorkerServer CacheCDN Cache

实际：

【待扫描】

如果缓存存储：

用户状态

Token

业务数据

必须在此说明。

46. Service Worker

是否存在：

【待确认】

如存在需记录：

文件：

【待扫描】

职责：

【待确认】

缓存策略：

【待确认】

47. 安全架构

安全不是单独一个文件。

而应该覆盖整个请求链：

客户端 │ ▼HTTPS │ ▼反向代理 │ ▼Rate Limit │ ▼Authentication │ ▼Authorization │ ▼Validation │ ▼Business Logic │ ▼Database

48. 安全边界

必须明确以下边界：

浏览器是不可信区域用户输入是不可信数据外部API是不稳定区域前端不能持有服务端Secret数据库不能直接暴露公网管理员接口必须额外保护

49. 请求限流架构

当前实现：

【待扫描】

需要至少评估：

用户登录管理员登录注册API上传AI调用昂贵操作

50. 异常用户检测架构

目标：

请求 │ ▼行为记录 │ ▼规则判断 │ ├── 正常 → 继续 │ └── 异常 │ ├── 限流 ├── 记录 ├── 告警 └── 必要时封禁

实际：

【待确认】

51. 前后端端口架构

需要生成真实端口表。

服务	开发端口	生产端口	配置位置	是否硬编码
Frontend	待扫描	待确认	待扫描	待检查
Backend	待扫描	待确认	待扫描	待检查
Database	待确认	待确认	待扫描	待检查

52. 网络请求关系

目标生产结构示例：

Browser │ HTTPS 443 │ ▼Domain │ ▼Reverse Proxy │ ├──── Static Frontend │ └──── /api/ │ ▼ Backend │ ▼ Database

实际生产架构：

【待确认】

53. 开发环境架构

实际开发环境待扫描。

目标类似：

Frontend Dev Server │ │ Proxy ▼Backend Dev Server │ ▼Development Database

禁止开发环境依赖：

某个开发者电脑的特殊隐藏配置。

54. 生产环境架构

当前生产结构：

【待确认】

需要最终明确：

服务器域名HTTPS反向代理FrontendBackendDatabaseStorageLogsBackup

55. Build架构

前端Build：

Source ↓Build Tool ↓Production Bundle ↓Static Assets

后端：

【根据实际技术栈补充】

Build相关文件：

【待扫描】

56. 测试架构

当前测试体系：

【待扫描】

需要识别：

LintType CheckUnit TestAPI TestIntegration TestE2ESecurity TestBuild Test

57. 自动化检查层

未来建议建立：

scripts/│├── check-hardcode├── check-secrets├── check-links├── check-api├── check-build└── check-security

实际存在：

【待扫描】

58. CI/CD

当前是否存在：

GitHub ActionsGitLab CI云平台流水线其他

状态：

【待确认】

目标流程：

代码提交 ↓Lint ↓Test ↓Build ↓Security Scan ↓通过 ↓Deploy

59. 核心业务数据流

需根据项目真实功能补充。

当前网站整体业务概念可以抽象为：

用户进入网站 │ ▼入口 / 首页 │ ▼实验室 / 展示空间 │ ▼点击实验器件 / 工具 / 项目 │ ▼详情 / Demo / 工具功能

如果涉及登录：

用户 │ ▼登录 │ ▼认证 │ ▼用户空间

真实流程：

【待扫描】

60. 个人网站内容架构

当前项目内容方向可能包括：

实验记录AI开发工具半成品失败案例漏洞分析开发日志Demo素材可回收项目个人成长记录

实际内容模块：

【待确认】

61. 前端功能与后端能力映射

需要最终建立完整表。

功能	前端模块	API	后端模块	数据表	权限
登录	待扫描	待扫描	待扫描	待确认	游客
用户信息	待扫描	待扫描	待扫描	待确认	用户
管理后台	待扫描	待扫描	待扫描	待确认	管理员

62. 关键公共模块

真实扫描后列出。

例如：

API ClientAuthRouterConfigThemeLoggerDatabasePermissions

这些模块一旦修改：

属于高影响修改。

必须扩大测试范围。

63. 高风险架构节点

以下类型模块默认属于高风险：

认证系统权限系统管理员系统数据库API Client全局配置公共布局Design Token全局路由文件上传AI工具调用Build配置

修改这些模块前：

必须先检查依赖。

64. 高耦合风险

需要扫描：

是否存在巨型文件是否多个页面直接依赖同一实现细节是否组件直接调用数据库是否前端直接硬编码API是否Service互相循环依赖是否配置散落是否业务与UI绑定

最终应记录实际高耦合模块：

【待审计】

65. 模块依赖图

真实项目扫描后补充。

格式建议：

Home Page │ ├── Navigation ├── Lab Scene │ ├── Device Card │ └── Animation │ └── API ServiceLogin Page │ ├── Auth Form └── Auth Service │ ▼ API Client

66. 禁止依赖关系

原则上禁止：

UI → DatabaseUI → Server SecretCSS → Business LogicPublic User → Admin ServiceFrontend → Private Third-party SecretDatabase → Frontend StateTest Code → Production Runtime

67. 配置依赖规则

任何模块需要可变值时：

优先：

配置层

而不是自己创造默认硬编码。

但必须避免：

所有东西都依赖一个超级全局配置对象。

68. 设计系统依赖规则

正确：

Design Token ↓公共组件 ↓页面

避免：

页面A自定义页面B自定义页面C自定义

造成视觉分叉。

69. 权限依赖规则

正确：

前端权限提示+后端真实权限验证

前端权限仅用于：

体验。

后端权限用于：

安全。

70. 数据依赖规则

用户资源应该：

Resource │ ▼Owner / Permission

不能仅通过知道ID访问。

71. 外部服务依赖风险

所有第三方服务应标记：

是否核心依赖失败是否影响主站是否有Fallback是否有Timeout是否有Retry是否产生费用

72. 单点故障

需要检查：

某个API挂了是否整个网站挂AI服务挂了是否首页挂数据库短暂异常是否服务崩溃字体CDN挂了是否页面不可读

实际风险：

【待审计】

73. 项目可替换性目标

项目架构应尽量做到：

换字体不改业务换AI模型不改UI换API域名不改组件换部署环境不大改源码换数据库影响范围可控

不是要求：

任何东西都零成本替换。

而是：

依赖关系明确且集中。

74. 新功能开发路径

新增普通功能时：

需求 ↓确认页面 ↓确认公共组件 ↓确认Service ↓确认API ↓确认Backend ↓确认Database ↓确认Permission ↓实现 ↓Test

75. 修改UI路径

需求 ↓Design Token? ↓公共组件? ↓页面局部? ↓修改 ↓响应式测试 ↓回归

优先修改最高可复用层。

76. 修改字体路径

CONFIGURATION.md ↓Font Config ↓Font Loader ↓CSS Variables ↓UI

原则上不应：

逐个页面换字体。

77. 修改API地址路径

目标：

Environment ↓API Config ↓API Client

不得：

全项目搜索localhost再逐个改。

78. 修改后端接口路径

修改API：

必须同时确认：

后端Route前端Service测试权限文档

79. 修改登录系统路径

登录修改属于高风险。

必须检查：

Frontend Login │ ▼Auth Service │ ▼API Client │ ▼Backend Auth │ ▼Session/Token │ ▼User

同时测试：

用户路由和管理员路由。

80. 修改管理员系统路径

必须检查：

Admin UIAdmin APIAdmin AuthAdmin PermissionAudit LogDatabase

不得只修改后台页面。

81. 修改数据库路径

Model / Schema ↓Migration ↓Repository ↓Service ↓API ↓Frontend

数据库修改不得只修改Schema。

82. 修改公共组件路径

修改公共组件后：

查找所有引用位置。

再执行相关页面回归。

83. 项目架构事实来源优先级

判断真实架构时优先：

当前实际运行代码2. 当前配置3. 当前数据库结构4. 当前路由/API5. ARCHITECTURE.md6. README7. 历史文档8. 历史对话

历史聊天不能作为当前架构最高依据。

84. 架构变更规则

以下变化必须更新本文件：

更换前端框架更换后端框架新增主要模块删除主要模块改变API架构改变认证体系改变权限体系改变数据库改变配置体系增加AI服务改变部署结构改变文件存储方式改变重要数据流

85. 小改动无需更新架构

例如：

改按钮文字调字体大小修单个页面CSS修局部Bug

如果没有改变系统关系：

不需要修改本文件。

86. 架构决策记录

重大技术选择建议记录：

ADR-001

决策

为什么

替代方案

最终选择

影响

日期

如果未来决策很多：

可以拆成：

/docs/adr/

87. 当前已知历史架构变化

字体体系

曾从：

字体样式直接写在CSS

向：

集中字体配置+字体加载器+CSS变量

方向调整。

当前最新实现需要重新扫描确认。

88. 当前架构成熟度

AI治理

🟢 已建立

前端结构

🟡 已有项目，需要扫描形成正式地图

后端结构

🟡 待完整确认

API

🟡 待生成映射表

数据库

⚪ 待确认

认证权限

🟠 高优先级待验证

配置体系

🟡 正在规范化

设计系统

🟡 已有基础，需要统一确认

测试

🟠 待加强

部署

🟡 有实践基础，当前结构待确认

89. 当前需要AI执行的架构扫描任务

AI在拥有项目文件读取能力后：

应执行：

STEP 1

扫描根目录。

STEP 2

识别技术栈。

STEP 3

识别前端入口。

STEP 4

识别后端入口。

STEP 5

识别所有路由。

STEP 6

识别所有主要页面。

STEP 7

识别所有公共组件。

STEP 8

识别API调用。

STEP 9

识别后端接口。

STEP 10

生成前后端接口映射。

STEP 11

识别数据库。

STEP 12

识别认证和权限。

STEP 13

识别配置系统。

STEP 14

识别字体和Design Token。

STEP 15

识别日志、缓存、上传、AI服务。

STEP 16

识别Build和部署。

STEP 17

更新本文件中的：

【待扫描】【待确认】

90. AI更新本文件时禁止的行为

不得：

为了让架构“看起来更标准”

擅自：

移动目录创建新层删除旧模块重构代码更换框架

本轮任务如果只是：

更新架构文档，

就只能：

调查和记录。

91. 架构扫描结果格式

每个模块应记录：

模块名称：职责：文件路径：入口：依赖：被谁调用：数据来源：权限：配置：风险：

92. 项目最终架构图

完成真实扫描后，应将本节更新成真实版本。

目标形式：

Internet │ ▼ Domain │ ▼ HTTPS / Proxy │ ┌─────────┴─────────┐ ▼ ▼ Frontend /api │ │ ▼ ▼ Router Backend │ │ ┌──────┼──────┐ ┌────┼────┐ ▼ ▼ ▼ ▼ ▼ ▼ Home User Admin Auth User Admin │ │ ▼ ▼ API Client Service │ ┌──────┼──────┐ ▼ ▼ ▼ DB AI Storage

当前真实结构：

【待扫描后替换】

93. AI快速定位表

完成扫描后必须补齐：

我要修改	首先看哪里	可能影响哪里
字体	待扫描	全站UI
主色	待扫描	Design System
首页	待扫描	路由/组件
登录	待扫描	Auth/API/User
管理员	待扫描	Admin/Auth/Permission
API地址	待扫描	API Client/Env
后端端口	待扫描	Backend/Proxy/Env
数据库	待扫描	Backend/Service
AI模型	待扫描	AI Service/Config
上传限制	待扫描	Frontend/Backend/Security

这个表最终是项目负责人最实用的部分之一。

94. 不允许建立两个事实源

例如：

API Base URL真实位置只能有一个明确来源。

不能：

ARCHITECTURE.md说AREADME说BCONFIGURATION.md说C实际代码是D

职责应区分：

ARCHITECTURE.md

负责：

它在哪、怎么连接。

CONFIGURATION.md

负责：

怎么修改它。

95. 与 PROJECT_STATUS.md 的关系

PROJECT_STATUS.md

回答：

现在做到哪？

ARCHITECTURE.md

回答：

东西都在哪里？

例如：

PROJECT_STATUS：

管理员登录：待验证

ARCHITECTURE：

管理员UI：xxx管理员API：xxx管理员认证：xxx管理员权限中间件：xxx

96. 与 CONFIGURATION.md 的关系

ARCHITECTURE：

字体系统由 font-config → loader → CSS变量组成。

CONFIGURATION：

想换字体具体修改哪个字段。

两者不要重复。

97. 与 BUG_TRACKER.md 的关系

ARCHITECTURE：

记录系统结构。

BUG_TRACKER：

记录结构哪里坏了。

不要把大量Bug历史写进本文件。

98. 与 DEPLOYMENT.md 的关系

ARCHITECTURE：

记录生产系统由：

Browser → Proxy → Backend → DB

组成。

DEPLOYMENT：

记录：

具体怎么部署这些东西。

99. 架构健康目标

未来项目应逐渐达到：

模块职责清晰入口明确依赖关系可理解配置集中权限明确前后端映射明确可替换部分边界清晰公共能力不重复建设无明显循环依赖无严重跨层调用无隐藏关键依赖

100. 当前结论

当前项目已经建立：

AI治理层

下一步不是重新设计架构。

而是：

从当前真实代码中把现有架构完整“照出来”。

先知道：

现在真实是什么。

再决定：

什么需要优化。

101. 下一步

完成本文件真实扫描后：

下一份建立：

CONFIGURATION.md

它负责解决：

以后我想改字体、颜色、API、端口、域名、数据库、AI模型，到底应该去哪改？

END

本文件是：

项目技术结构与模块关系的主要事实源。

任何AI不得为了让架构图更漂亮而虚构不存在的模块。

任何标记为：

【待扫描】【待确认】

的内容，

在没有实际代码证据前：

不得修改为“已完成”。