SemanticLibrary 应按照系统运行基础 → 数据基础 → 核心业务功能 → 外部资源处理 → 动态语义构建 → 人工核验 → 查询与 API → 系统管理 → 集成验收的顺序开发。
开发顺序不能只考虑 PHP 文件的编写顺序,还要考虑每个文件的职责、依赖关系和验证条件。先把整个系统的功能文件规划确定下来,再逐个创建文件,避免前面写完后因后续功能衔接不上而反复重写。
一、SemanticLibrary 系统功能文件规划
第一阶段:系统运行基础
先建立系统能够启动、接收请求、分发功能的基础。
| 顺序 | 文件路径 | 文件职责 |
|---|---|---|
| 1 | public/index.php |
系统统一入口,请求接收、路由分发、统一响应 |
| 2 | config/app.php |
应用基本配置、项目运行参数 |
| 3 | app/Support/Response.php |
统一 HTTP 响应和 JSON 输出 |
| 4 | app/Support/Router.php |
原生 PHP 请求路由匹配与分发 |
| 5 | app/Support/Bootstrap.php |
加载配置、初始化系统基础组件 |
| 6 | config/smarty.php |
初始化 Smarty,配置模板及编译目录 |
| 7 | routes/web.php |
网页请求路由 |
| 8 | routes/api.php |
API 请求路由 |
| 9 | templates/layouts/main.tpl |
系统页面公共布局 |
| 10 | templates/pages/home.tpl |
系统首页模板 |
| 11 | public/assets/css/app.css |
系统基础样式 |
| 12 | public/assets/js/app.js |
系统基础交互脚本 |
阶段验收: 系统能够启动、访问首页、区分网页与 API 请求,错误路径能够返回正确的 HTTP 状态码。
注意:`public/index.php` 已经给出了初始代码,但尚未完成实际运行验证。后续应检查其与 Router.php、`Bootstrap.php` 的职责衔接,避免重复实现。
第二阶段:数据库与数据访问基础
先建立数据连接、数据库初始化和统一的数据访问方式,再开发依赖数据的业务功能。
| 顺序 | 文件路径 | 文件职责 |
|---|---|---|
| 13 | config/database.php |
数据库连接配置 |
| 14 | app/Support/Database.php |
创建和管理 PDO 数据库连接 |
| 15 | database/schema.sql |
初始化系统所需的数据表 |
| 16 | app/Repositories/BaseRepository.php |
数据访问的基础能力 |
| 17 | app/Support/Validator.php |
输入数据验证 |
| 18 | app/Support/ExceptionHandler.php |
统一异常处理与错误记录 |
| 19 | app/Support/Logger.php |
系统运行日志 |
阶段验收:
- PHP 能够连接实际使用的 MySQL 数据库。
- 数据表可以按确定的结构创建。
- 数据访问与业务处理分离。
- 数据库错误不会直接暴露敏感连接信息。
数据库表结构应根据后续确认的数据实体和关系设计,不能在缺乏业务依据时预先固定行业字段。
第三阶段:需求管理
这是动态语义字典的业务起点。
| 顺序 | 文件路径 | 文件职责 |
|---|---|---|
| 20 | app/Models/Demand.php |
需求数据实体 |
| 21 | app/Repositories/DemandRepository.php |
需求数据读写 |
| 22 | app/Services/DemandService.php |
需求创建、读取、更新等业务处理 |
| 23 | app/Controllers/DemandController.php |
接收需求管理请求 |
| 24 | templates/pages/demand/index.tpl |
需求列表页面 |
| 25 | templates/pages/demand/create.tpl |
需求输入页面 |
| 26 | templates/pages/demand/detail.tpl |
需求详情页面 |
| 27 | public/assets/js/demand.js |
需求页面交互 |
阶段验收: 用户能够提交需求、查看需求、编辑需求,并在后续语义处理过程中追踪需求来源。
第四阶段:语义单元拆分与人工确认
需求进入系统后,先进行语义单元拆分,再由用户编辑、增删和确认。
| 顺序 | 文件路径 | 文件职责 |
|---|---|---|
| 28 | app/Engines/SemanticUnitSplitter.php |
将需求文本拆分为语义单元 |
| 29 | app/Models/SemanticUnit.php |
语义单元数据实体 |
| 30 | app/Repositories/SemanticUnitRepository.php |
语义单元数据读写 |
| 31 | app/Services/SemanticUnitService.php |
拆分结果管理、编辑、增删和确认 |
| 32 | app/Controllers/SemanticUnitController.php |
语义单元操作请求 |
| 33 | templates/pages/semantic-units/index.tpl |
语义单元编辑与确认页面 |
| 34 | public/assets/js/semantic-units.js |
语义单元交互逻辑 |
阶段验收:
- 系统能够对需求文本进行初步拆分。
- 用户可以修改拆分结果。
- 用户可以增加或删除语义单元。
- 用户确认后,系统能够保存确认状态。
- 未确认的拆分结果不能被误当作已确认的语义定义。
这里的拆分是初步文本处理,不意味着系统已经完成语义理解。
第五阶段:外部搜索与资源管理
只有需求及语义单元经过必要确认后,才进入外部信息获取流程。
| 顺序 | 文件路径 | 文件职责 |
|---|---|---|
| 35 | config/search.php |
外部搜索服务的连接参数 |
| 36 | app/Services/SearchService.php |
调用已配置的公开搜索服务 |
| 37 | app/Services/ResourceFetcher.php |
获取用户选定的外部网页资源 |
| 38 | app/Engines/HtmlTextExtractor.php |
从网页 HTML 中提取文本 |
| 39 | app/Models/Resource.php |
外部资源数据实体 |
| 40 | app/Repositories/ResourceRepository.php |
资源及来源信息读写 |
| 41 | app/Services/ResourceService.php |
资源保存、读取和来源管理 |
| 42 | app/Controllers/ResourceController.php |
资源搜索、选择和管理请求 |
| 43 | templates/pages/resources/index.tpl |
搜索结果与资源管理页面 |
| 44 | public/assets/js/resources.js |
搜索结果选择与交互 |
阶段验收:
- 搜索服务必须有明确的实际配置,不能假装已经接通外部搜索。
- 系统能够记录资源来源和获取状态。
- 用户可以选择需要处理的资源。
- 网页提取失败时,能够记录失败情况。
- 外部资料不能未经核验就被视为真实结论。
第六阶段:文本处理与来源关联
对选定的外部资料进行文本整理,为后续动态语义构建提供材料。
| 顺序 | 文件路径 | 文件职责 |
|---|---|---|
| 45 | app/Engines/TextNormalizer.php |
文本规范化 |
| 46 | app/Engines/SentenceExtractor.php |
按文本边界提取句子 |
| 47 | app/Models/Sentence.php |
句子数据实体 |
| 48 | app/Repositories/SentenceRepository.php |
句子及来源关系读写 |
| 49 | app/Services/SentenceService.php |
句子保存、精确去重、出现次数统计 |
| 50 | app/Controllers/SentenceController.php |
句子查看和管理请求 |
| 51 | templates/pages/sentences/index.tpl |
句子及来源展示页面 |
| 52 | public/assets/js/sentences.js |
句子管理交互 |
阶段验收:
- 句子去重依据明确,不将意思相近的句子直接当成完全相同。
- 同一句子可以关联多个来源。
- 句子出现次数和来源关系可以追溯。
- 清理外部资料时,不得连带删除已经确认的语义定义。
第七阶段:动态语义字典核心
这是整个系统最关键的业务部分。
语义字典不预设行业、属性名称或属性值,而是根据具体需求、已获取的资料和已有概念,动态形成待核验的语义结构。
| 顺序 | 文件路径 | 文件职责 |
|---|---|---|
| 53 | app/Models/SemanticElement.php |
语义元素数据实体 |
| 54 | app/Models/SemanticAttribute.php |
语义属性数据实体 |
| 55 | app/Models/SemanticValue.php |
属性值数据实体 |
| 56 | app/Repositories/SemanticDictionaryRepository.php |
语义元素、属性及属性值的数据访问 |
| 57 | app/Engines/SemanticCandidateBuilder.php |
根据需求与外部资料构建语义候选 |
| 58 | app/Services/SemanticDictionaryService.php |
动态语义字典的核心业务处理 |
| 59 | app/Controllers/SemanticDictionaryController.php |
语义字典管理请求 |
| 60 | templates/pages/dictionary/index.tpl |
语义字典查看与编辑页面 |
| 61 | public/assets/js/dictionary.js |
语义字典交互 |
阶段验收:
- 语义元素不是通过固定行业列表限定的。
- 属性由当前需求和资料动态形成。
- 属性值有相应的来源和核验状态。
- 系统可以记录不同来源之间的冲突。
- 系统不会把未经核验的候选直接升级为确定事实。
- 用户可以编辑、增加、删除和确认语义内容。
- 语义定义能够与其适用的当前需求场景关联。
以上文件是职责规划,不代表必须机械地为每一个概念创建独立模型文件。实际编写时,应根据确认后的数据关系和现有代码,避免产生无必要的文件。
第八阶段:人工核验与语义定义版本管理
| 顺序 | 文件路径 | 文件职责 |
|---|---|---|
| 62 | app/Models/SemanticDefinitionVersion.php |
语义定义版本实体 |
| 63 | app/Repositories/SemanticDefinitionRepository.php |
定义与版本数据读写 |
| 64 | app/Services/SemanticVerificationService.php |
候选核验、确认、冲突处理 |
| 65 | app/Services/SemanticVersionService.php |
定义变更与版本记录 |
| 66 | app/Controllers/SemanticVerificationController.php |
核验和版本管理请求 |
| 67 | templates/pages/verification/index.tpl |
候选核验页面 |
| 68 | templates/pages/verification/history.tpl |
定义版本历史页面 |
| 69 | public/assets/js/verification.js |
核验操作交互 |
阶段验收:
- 机器生成的候选与人工确认的定义状态明确区分。
- 修改定义时保留必要的版本历史。
- 能够追溯定义所依据的资料。
- 删除外部资料不应直接删除已确认的定义。
- 对存在冲突的信息,不擅自选择一个结果作为事实。
第九阶段:语义查询与 API
让其他系统能够调用已经建立的语义字典。
| 顺序 | 文件路径 | 文件职责 |
|---|---|---|
| 70 | app/Services/SemanticQueryService.php |
语义查询、定义读取和匹配 |
| 71 | app/Models/ApiKey.php |
API 密钥数据实体 |
| 72 | app/Repositories/ApiKeyRepository.php |
API 密钥数据访问 |
| 73 | app/Services/ApiAuthenticationService.php |
API 身份验证 |
| 74 | app/Controllers/SemanticApiController.php |
语义查询 API |
| 75 | app/Controllers/ApiKeyController.php |
API 密钥管理请求 |
| 76 | templates/pages/api-keys/index.tpl |
API 密钥管理页面 |
| 77 | public/assets/js/api-keys.js |
API 密钥管理交互 |
阶段验收:
- API 能查询已确认的语义定义。
- API 密钥验证有效。
- 密钥不以明文形式存储。
- 未确认的候选不会被错误地作为正式定义返回。
- API 返回值能够区分无结果、未核验和已确认的语义信息。
第十阶段:来源材料、句子列表与导出
| 顺序 | 文件路径 | 文件职责 |
|---|---|---|
| 78 | app/Services/ImportService.php |
接收用户提供的文本或文件材料 |
| 79 | app/Services/ExportService.php |
导出指定的句子或语义数据 |
| 80 | app/Controllers/ImportController.php |
导入请求 |
| 81 | app/Controllers/ExportController.php |
导出请求 |
| 82 | templates/pages/import/index.tpl |
材料导入页面 |
| 83 | templates/pages/export/index.tpl |
数据导出页面 |
| 84 | public/assets/js/import.js |
导入交互 |
| 85 | public/assets/js/export.js |
导出交互 |
具体导入格式、导出格式和文件处理规则,应根据实际需求确定,不在没有依据的情况下自行添加限制。
二、最终的业务处理顺序
从用户输入需求到语义字典被其他系统调用,业务顺序应当是:
用户输入需求
↓
保存需求
↓
拆分语义单元
↓
用户编辑并确认
↓
根据需求和确认后的语义单元形成外部搜索内容
↓
调用已配置的外部搜索服务
↓
用户选择外部资源
↓
获取网页并记录来源
↓
提取网页文本
↓
提取句子、精确去重、统计次数并关联来源
↓
结合需求和外部资料动态构建语义候选
↓
用户核验、编辑并确认
↓
保存当前语义定义及版本历史
↓
提供语义查询、API 调用和数据导出
这条链路中,语义单元确认、外部资料来源记录、候选与正式定义的区分,以及定义版本管理,都是需要落实到实际代码和数据库结构中的功能,而不是仅在页面上展示的状态。
三、实际开发时的文件执行顺序
上面的编号是功能规划,不应直接理解为严格的代码编写顺序。例如,数据库访问组件必须在依赖它的业务服务之前完成;某些模型也可以与相应的数据表和 Repository 一起设计、验证。
建议实际开发分为以下批次:
| 批次 | 开发内容 | 完成标准 |
|---|---|---|
| 1 | 入口、路由、启动组件、统一响应 | 系统入口可运行,路由行为正确 |
| 2 | 数据库连接、数据表、基础数据访问 | 能连接数据库并验证数据读写 |
| 3 | 需求管理 | 需求能够完整保存和读取 |
| 4 | 语义单元拆分与确认 | 拆分、编辑、确认状态能够正确保存 |
| 5 | 外部搜索与资源获取 | 真实搜索和资源获取能够验证 |
| 6 | 文本提取、句子管理 | 句子和来源关系正确 |
| 7 | 动态语义候选构建 | 能形成待核验的元素、属性和值 |
| 8 | 人工核验和版本管理 | 确认、冲突和历史记录正确 |
| 9 | 查询 API 和密钥管理 | 外部系统能够安全查询 |
| 10 | 导入、导出与集成验收 | 全流程能够实际运行 |
每个批次都应经过语法检查、功能测试和数据验证,确认后再进入下一个批次。
当前进度: 本地目录结构已确认,Smarty 3.1.48 已找到;`public/index.php` 已提供初始代码,但还没有收到它的实际语法检查结果,也没有完成运行验证。因此,不能把第一批次标记为已完成。