Skip to content
ooofreePublic

About

为了工程问题而建

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

65 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Project O — 项目管理平台专业重构

目标:从零构建一个轻量、可即开即用、以插件扩展的建筑项目管理平台。功能覆盖现有系统,业务规则、计算结果、权限边界和流程语义保持不变。

本目录本身就是独立的新项目根目录,包含架构规范和新实现代码。旧系统 m 仅作为业务行为参考;在明确批准数据迁移和切换前,不覆盖、不删除、不修改旧系统代码或数据。

当前开发状态

新项目已实现最小 PHP/MySQL 运行骨架、首次管理员初始化、登录/退出、基础权限、插件清单发现/路由注册,以及 project.foundation 插件中的项目和楼栋/楼层/区域/房间管理。项目和空间支持受保护删除:无关联时删除,有关联时归档并可从回收站恢复。平台后台支持系统主题、默认国家/币种、用户与角色权限管理、插件启停和安全运行参数展示;管理权限由 manage_platform 授权,停用账号保留数据,必需/有依赖的插件不能停用;系统设置按左侧分区导航、右侧设置内容的两列布局呈现,平台名称可在此配置并用于顶栏、登录页和浏览器标题;员工可在个人设置中更改显示时区和自己的密码。货币代码从 ISO 4217 标准目录选择,默认币种为人民币 CNY;选择币种不自动换算或改写已有金额。document.management 首期提供项目内问题与 RFI 管理、列表与模态编辑、独立状态流转、关闭校验、后续事项和状态审计;问题/RFI 不提供硬删除;问题与 RFI 支持私有对象存储图片附件,沿用同一存储配置;问题台账可按当前项目导出 Excel(标题、统计、图片与固定高度布局,文件名使用表格名称+日期+当天序号)。material.management 的材料分类、材料、辅材、估算、样品、报价和招标清单按当前项目隔离;供应商、供应商材料和品牌为共享目录。材料管理列表支持导出 Excel:未选择分类时导出全部材料,选择分类时只导出该分类(与页面筛选一致);文件名使用「项目名材料_分类名_日期.xlsx」,未选择分类时为「项目名材料_全部_日期.xlsx」。样品、问题与 RFI 图片使用可选的私有对象存储适配器;样品列表可按当前项目导出 Excel,标题带项目名并附数量统计(品牌列需报价查看权限);列表显示图片缩略图,导出文件按固定高度(75px)嵌入首张可用样品图片、单元格在固定列宽内自动换行;页面图片经应用路由输出,导出文件名使用“表格名称+日期+当天序号”命名(如 材料样品信息表_20261107_1.xlsx)。招标清单按项目而非楼栋维护材料、数量、单价和币种;项目基准币种为 CNY,招标项默认 CNY,也可选择其他 ISO 4217 币种。全站页面共用现代化响应式视觉组件,覆盖项目、空间、材料、文档、后台及登录界面。现有全局材料/分类/辅材/报价记录不会由迁移自动分配到项目;需核实所有权后另行制定数据归属迁移。 目标设计见 ARCHITECTURE.md 和 FEATURES.md。采购、库存、BOM、成本公式、图纸/传递、文档文件附件及项目成员权限仍待后续开发。目标数据库必须是新建的空数据库,与旧系统数据库隔离;当前不导入或更改旧系统数据。

安装器只负责创建首位管理员;其后可在后台创建/停用用户并配置角色权限,但尚未实现项目成员分配。项目列表权限由角色权限控制。项目级成员隔离必须在核实旧系统实际授权规则后实现,当前版本不能据此宣称支持多租户隔离。

完成后可按下列步骤启动(需 PHP 8.2+、mbstring、PDO MySQL、Composer 和 MySQL):

  1. 在 MySQL 中创建专用空数据库和仅供新项目使用的账号,例如:
    CREATE DATABASE project_o CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
    CREATE USER 'project_o'@'localhost' IDENTIFIED BY 'replace-with-a-unique-secret';
    GRANT ALL PRIVILEGES ON project_o.* TO 'project_o'@'localhost';
    请替换示例密码,并按部署环境调整 MySQL 主机/账号。
  2. 复制 .env.example 为 .env,配置 APP_DSN、APP_DB_USER 和 APP_DB_PASSWORD;如需用到施工班组的身份证号加密存储,另需配置 APP_DATA_KEY(见下)。
  3. 运行 composer install。
  4. 运行 php bin/install.php;首次安装会交互式创建管理员,密码至少 12 个字符。
  5. 运行 php -S 127.0.0.1:8000 -t public 并打开 http://127.0.0.1:8000。

不要把 .env、真实密码或生产密钥提交到版本库。安装器拒绝对非空数据库首次建表;请勿把旧系统数据库用作新项目的安装目标。

施工班组与工种目录

labor.crew 插件提供施工班组负责人联系页(?page=labor-crews)与工种目录(?page=labor-crew-types)。每个项目的班组互相隔离(Labor_Crews.project_id 非空,业务口径为「班组只对项目负责」),工种目录跨项目共享。班组登记一位负责人:姓名与手机号必填,微信号、身份证号、紧急联系人(姓名与电话须成对)和备注选填;身份证号保存为 AES-256-GCM 密文加 HMAC 指纹,页面默认脱敏显示,完整号码需要单独的 view_labor_crew_id_numbers 权限,密文与指纹不进入审计明细。班组不提供硬删除,归档保留数据且可恢复。班组列表可按排序号手动调整顺序(0 至 9999;0 表示未指定,已指定排序号者按值从小到大排在前面,未指定者随后按「工种排序 → 工种名称 → 班组名称」排列;列表与导出使用同一顺序)。班组列表提供「导出 Excel」,版式与其他模块导出一致(合并标题行为“项目名+施工班组负责人联系表”、导出时间/记录总数/分工种统计三行元信息、空行后接表头),列为序号、工种、班组名称、负责人姓名、负责人电话、备注(工种与班组名称列加宽),只含在用班组且不导出身份证号和微信号;文件名使用「施工班组联系表_项目名称_日期_当天序号.xlsx」,项目名称中的非法字符替换为下划线。后续任务模块按 project_id + crew_type_id 引用该目录取班组与负责人联系方式。

班组联系人支持对外公开分享:具有 share_labor_crews 权限的用户在班组页「导出 Excel」旁的「分享链接」按钮中生成公开链接(固定地址 <站点>/s/<令牌>.html)。持有链接者无需登录即可查看该项目在用班组的联系人。公开页是预渲染的静态 HTML:连续磁贴网格(无分组标题、不留空位,工种显示在每块磁贴的彩色标签上,顶部工种导航点击直达对应班组),磁贴尺寸统一,整块磁贴点击即拨号;手机一律两列、隐藏号码只留电话图标,宽屏才多列;样式脚本全部内联、零外部请求,加载快。静态文件发布在 public/s/,地址固定不变,由 Apache 直接输出:访问不执行 PHP、不查数据库、不重新生成(原生 ETag/304)。只有数据真正变化时才重写:班组新增/编辑/归档/恢复、工种改名/删除、开启分享;停用分享、项目归档或删除、插件停用则删除文件,项目恢复与插件启用重新发布。跨插件通知走核心事件总线(清单 emits/subscribes),插件之间不互相引用类。旧链接 ?page=labor-crew-share&token=… 保留为 303 跳转到固定地址,已分享出去的链接不会失效。发布目录自动设为 web 服务器组可写(setgid),CLI 与 Apache 都能更新;禁止列目录与非 html/png 访问;安全与缓存头同时写入 .htaccess 和页面 meta,未启用 mod_headers 也生效。分享带链接卡片信息:页面输出标题(项目名 · 班组联系人)、摘要(班组/工种数量与主要工种)与 600×600 缩略图(og:/itemprop/twitter 元数据),并在 <body> 内放置同尺寸的真实 <img>(离屏定位、非 display:none),供微信/QQ 的链接预览抓取器取首图;缩略图由 GD 生成并发布为同目录固定文件 <令牌>.png(同样由 Apache 直出),图中只有项目名与数量、不含电话等个人信息(未装 GD/中文字体时自动省略图片,卡片仍有标题与摘要)。分享对话框提供「复制标题+链接」(消息自带项目名与数量,不再是裸链接)与「仅复制链接」,并预览卡片样式。

微信内分享的准确边界:微信对直接粘贴到聊天的链接只显示网址;在微信内打开页面后用「···→发送给朋友」要显示自定义卡片,微信官方要求认证服务号 + 已备案的 JS 接口安全域名(不支持 IP 与端口,故 localhost/局域网地址无法实现)+ JS-SDK 签名,仅靠 OG 标签无法控制该路径。因此本项目默认不加载任何微信 SDK,对话框如实说明并推荐「复制标题+链接」;配置 WECHAT_APPID/WECHAT_APPSECRET 后,发布时会自动注入 wx.config 与 updateAppMessageShareData/updateTimelineShareData(签名用的 access_token 与 jsapi_ticket 全局缓存、AppSecret 绝不进页面,SDK 失败不影响页面与拨号)。

复制可靠性:共享资源 app.css/app.js 带内容指纹版本号(?v=…),避免微信等内置浏览器缓存旧脚本与新页面错配(该错配曾导致复制到字面量 undefined)。复制取值按「按钮 data 属性 → 链接 href → 链接文本」多来源解析并逐项校验,只接受合法 http(s) 地址,任何情况下都不会写入 undefined/null;依次尝试异步剪贴板 API 与对话框内临时文本域 execCommand,两者都失败时显示已全选的可长按文本域并给出明确指引,绝不谎报成功。

公开地址基址:分享链接的绝对基址优先取 APP_PUBLIC_URL,否则由真实网页请求推导并记录到 public/s/.base-url(HTTP 访问被拒),供 CLI/安装器发布时复用,避免命令行下 SCRIPT_NAME 非网页路径而拼出错误主机。公开内容与导出同口径(工种、班组名称、负责人姓名、电话、备注),身份证号、微信号与紧急联系人不公开;令牌为 128 位随机串,每项目至多一枚有效令牌,可随时停用(停用后链接立即失效,重新分享生成新令牌,历史令牌记录保留)。项目归档后其公开页同样不可访问;插件停用时公开路由随之下线。开启/停用分享写入审计,审计不记录令牌本身。分享令牌存于 Labor_Crew_Shares 表(迁移 202611130001),升级需运行 php bin/install.php 执行新迁移并同步新权限。

身份证号加密依赖 APP_DATA_KEY(64 位十六进制,即 32 字节;用 php -r "echo bin2hex(random_bytes(32));" 生成)。未配置时其余联系方式仍可维护,但保存身份证号会明确报错而不是静默丢弃;密钥丢失后已保存的密文无法恢复,请纳入部署密钥备份。

时间与时区

系统内部统一以 UTC 存储时间(MySQL 会话时区固定为 +00:00,PHP 入口以 UTC 运行);项目默认显示时区在平台管理「系统配置」中设置(默认 Asia/Shanghai),每位员工可在「个人设置」中覆盖为自己的当地时间。页面上的问题/RFI 时间、RFI 答复截止时间输入,以及导出文件名与导出时间,均按当前生效时区换算。升级迁移会把问题/RFI 的 datetime 字段按原服务器本地时间(东八区)一次性换算为 UTC;执行前已把受影响记录备份到 storage/timezone-backup-*.json。

样品图片存储(可选)

AWS SDK(aws/aws-sdk-php)已列入 composer.json 依赖,由 composer install 安装;启用 R2 图片存储时,在文件模块「系统设置」(?page=document-settings;平台管理员 manage_platform,或获授 manage_document_settings)填写 Cloudflare R2 Account ID、私有存储桶名称和访问密钥;配置持久化在数据库 System_Settings 中,密钥只写(留空表示保留已保存密钥),变更写入审计;该配置同时用于材料样品与问题/RFI 图片附件。也可改用部署级环境变量 APP_R2_ACCOUNT_ID、APP_R2_BUCKET、APP_R2_ACCESS_KEY_ID、APP_R2_SECRET_ACCESS_KEY;已保存的数据库配置优先于环境变量,APP_OBJECT_STORAGE_ADAPTER 仍可指定其他对象存储实现。R2 bucket 应保持私有;页面图片由应用服务器按权限读取并输出(浏览器不直接访问私有桶),导出时服务器端通过 5 分钟签名 URL 读取图片。上传限制为 PNG/JPEG/GIF/BMP/WebP、单文件 5 MiB;PHP 部署的 upload_max_filesize 和 post_max_size 也应允许至少 5 MiB 请求。未配置适配器、凭据或 AWS SDK 时,样品、问题与 RFI 资料仍可维护,但图片上传/查看明确不可用。

测试:运行 composer test,覆盖认证、项目插件/服务、材料/空间/样品服务、施工班组目录(含身份证号加密/脱敏、同项目查重、跨项目隔离、归档恢复、审计不泄露与公开分享令牌的生成/停用/轮换)、文档问题/RFI 服务、后台设置/权限/插件启停和页面授权。迁移与服务行为测试使用 SQLite 等价结构;部署前应在专用测试 MySQL 验证迁移,不得直接对生产库执行未审阅迁移。

插件清单声明的迁移会在运行 php bin/install.php 时由核心迁移追踪器执行;插件停用不会删除已创建的数据表或记录。

开工必读

  1. 架构设计:运行时、插件边界、目录建议、依赖规则和迁移路线。
  2. 功能与业务基线:必须保留的功能、实体、自动化规则和验收条件。
  3. Agent 工作规范:Agent 的工作步骤、边界、交付与验证要求。

不可妥协的约束

  • 业务等价优先:重构代码和存储方式可以变化,业务规则及其可观察结果不能自行改变。
  • 项目是业务根上下文:先创建或选择项目,再开展该项目下的文档、图纸、RFI 和其他业务;项目归属与访问范围必须遵守旧系统的真实规则。
  • 插件化但不拆服务:采用模块化单体;插件在同一应用进程内运行,不引入微服务及其运维成本。
  • 核心小而完整:启动、配置、身份认证、权限、数据库访问/迁移、路由、插件注册、日志与错误处理属于平台核心;具体业务属于插件。
  • 按需启用:可选业务模块可安装、启用、停用;基础认证、项目上下文、数据库及插件管理等运行必需能力不得被误停。
  • 渐进迁移:每个模块均可独立实现、验证和交付;旧系统保持可用,直到新旧行为对照通过并完成有计划的切换。
  • 即开即用:新部署有明确、短路径的安装和首位管理员配置流程;不得把默认账号密码、生产凭据或危险的自动建库权限写入代码。

项目现状与技术基线

旧系统是 PHP 服务端渲染应用,composer.json 要求 PHP 8.2+,数据库逻辑使用 MySQL 表、视图、触发器和存储过程;现有依赖包含 PhpSpreadsheet、Dompdf 和 AWS SDK。它同时有传统 PHP 页面和 API。新项目可重新组织代码,但必须先审计实际在用的规则与数据,再决定如何封装或替换这些依赖。

本规范只定义目标和护栏,不预先假定所有遗留页面、迁移脚本、注释和数据库定义彼此完全一致。开发前应以正在运行的行为、有效数据库定义、样例数据和用户确认的流程为准,记录并解决差异。

推荐交付顺序

  1. 盘点遗留行为、权限、数据关系及数据库自动化,建立基线。
  2. 创建新项目骨架和最小核心,提供安装向导及一个可验证的示例插件。
  3. 先完成身份/权限与项目基础数据;所有项目业务插件都依赖项目上下文,再按 功能基线 的依赖顺序迁入。
  4. 每个插件通过行为对照、权限检查、迁移检查和回归验收后,才进入试运行。
  5. 备份、校验、演练回滚并获得明确批准后,再安排生产切换。

About

为了工程问题而建

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages