gsfdc/AGENTS.md

AGENTS.md

甘肃省房地产价格评估行业协会网站升级改造。本文件是后续代理的工作约定。需求细节以文末文档为准，不要凭记忆扩范围。

项目是什么

整站重建协会官网（现站 http://www.gsrea.org.cn/），不是修补 2018 年阿里云模板站。交付源码、数据库和设计文件，无加密、无后门。等保二级。备案号沿用：陇ICP备19001227号、甘公网安备62010202001984号。

三个系统，共用账号与对象存储：

1. 门户网站：11 个栏目，PC 与手机同一套响应式页面，不单独做手机站。
2. Web 管理后台：站点配置、内容发布、名录、报告备案、投诉、诚信、会员与权限。不做公众版移动端。
3. 教育平台：只做继续教育的「学」（计划、课程、进度、学分）。考试报名和缴费链到现有甘肃省继续教育系统。

十一项栏目的页面、字段和流程尚未细化。没有专篇之前，不要自行补全表结构、接口和页面。

代码按系统分目录。进入子目录时，同时遵守该目录的 AGENTS.md。

目录	系统	约定
portal/	门户网站	Nuxt 4
admin/	Web 管理后台	Vue 3 + Vite + Element Plus，骨架用 art-design-pro 开源版
edu/	教育平台	选型未确认，禁止开工
server/	门户与管理端共用的一套 Python 服务	REST、账号、附件、审计。不要为两端各建一个后端

需求文档在 docs/，不放进上述代码目录。

先读什么

冲突时按此顺序：

1. docs/合同/甘肃房地价协网站升级合同技术需求（批注版）.pdf（含批注）
2. docs/分析/综合性需求分析.md
3. docs/理解/个人对需求的理解.md
4. docs/需求/甘肃省房地产价格评估行业协会网站需求.docx
5. docs/可研/甘肃省房地产价格评估行业协会网站升级改造项目可行性研究报告.pdf（背景、旧站现状、验收口径）

批注只有四处，必须遵守：机构名录带「名录信息」；报告核验先定文件格式、验真规则和结论依据；中房学与住建厅窗口本期只做可配置外链；专家服务旁的「智能体」范围未定，完整智能估价平台不在本期。

本地端口

本机 3000、3006、8000 已被其他工程占用，本地开发使用下面三个端口。

工程	端口	地址
门户 portal/	13000	http://127.0.0.1:13000
管理后台 admin/	13006	http://127.0.0.1:13006
后端 server/	18000	http://127.0.0.1:18000

门户和管理端请求后端时使用 18000。不要改回 3000、3006、8000。

技术栈

• 门户：Nuxt 4（Vue 3）。不要用已停止安全更新的 Nuxt 3，不要用 Quasar、Bootstrap 组件库或 art-design-pro。工程放在 portal/，页面放在该目录的 app/ 下。数据向仓库根目录的 Python server/ 请求，不要在 Nuxt 里另做一套业务接口。
• 管理后台：Vue 3、TypeScript、Vite，组件库 Element Plus，工程骨架用 art-design-pro 开源版（MIT）。不要用 Nuxt，不要改用 Quasar 或 Ant Design Vue。以官方仓库为准，不要从个人 Gitee 镜像开工程。清理演示页和演示接口后，登录、菜单和按钮权限对接 Python server/。保留仓库内的 MIT 版权声明。不使用该模板的商业版后端。
• 服务端：Python，前后端分离。正式接口用 REST。没有明确场景时不要并行做第二套 RPC。
• 数据：MySQL、Redis。附件用 MinIO。管理后台富文本用 wangEditor-next（@wangeditor-next/editor 与 @wangeditor-next/editor-for-vue），不要用已停更的 @wangeditor/editor 5.x，也不要改用 TipTap。图片和视频走自定义上传进 MinIO。保存正文时由 server/ 做 HTML 白名单过滤。门户只渲染过滤后的 HTML。
• 开发测试连接信息写在 docs/理解/个人对需求的理解.md。生产在天翼云甘肃-兰州（通用型 s7，4 核 8G，系统盘 100GB，数据盘 40GB，CentOS Stream 9，5Mbps），不要把开发库当成生产。

教育平台是否以 PlayEdu 为底，尚未确认。确认前不要克隆或改造该仓库。

本期不要做

• 数据挖掘的采集、清洗、建模和图表。首页数据看板与通知公告相同，发布文章用富文本展示说明或图片，不嵌示意图页面，不接真实指数，不采集数据。见 docs/adr/0005-homepage-dashboard-as-articles.md。
• 智能估价平台（个人/企业在线评估、价格参考报告）。
• 与中房学、住建厅窗口的数据对接、单点登录和回写。
• 报告审核做成审核引擎或接入模型。本期只做门户演示页，提交后提示尚未开通，不保存。见 docs/adr/0010-report-query-is-filing-lookup.md。
• 把报告查询做成文件验真或核验码。按该 ADR，只对照报告中心已发布的备案。
• 单独手机站、旧站修补、本地物理服务器。

两套模板都在管理端备好，每套模板只有一份首页。管理端指定当前启用的一套，门户只展示这一套。访客不能自己换肤。见 docs/adr/0001-one-active-template.md。

实现时必须守住

• 图片、图标、LOGO、Banner 从后台读取，不写死在前端。
• 公开接口与登录接口分开。门户接口前缀 /api/site，管理端接口前缀 /api/admin。报告真伪查询保持公开，不强制注册。/api/admin 必须校验工作人员登录；会员只能访问本人数据。工作人员令牌和会员令牌不能混用。菜单和按钮权限用「用户、角色、角色菜单」控制，不能代替接口鉴权。
• 身份证、手机号等敏感字段加密存储（AES-256 或 SM4），接口默认脱敏。投诉公示和诚信公示默认脱敏。
• 全站 HTTPS。防 SQL 注入、XSS、CSRF。发布内容走敏感词和审核，未发布内容不可公开读。
• 请求日志不记录密码、验证码、身份证号和完整手机号。
• MinIO 分公开桶与私有桶。证件、投诉证据、报告原件、未发布附件走私有桶和鉴权链接。上传大小要有可配置上限，禁止不限制大小。
• 应用层 JSON 加解密做成可配置开关，门户、管理端和 server/ 使用同一开关、同一 AES-GCM 算法。默认关闭。文件上传和下载不走该加密。密钥放环境变量。HTTPS 始终开启。接口加解密不代替登录鉴权。
• 隐私政策勾选和账号注销要做。注销后业务档案按监管需要保留并脱敏。
• 旧站迁移是验收项：政策法规、案例库、会员机构名录、继续教育记录。核心数据导入要可核对，不要只做演示数据。

安全与仓库

• 不要把数据库、Redis、MinIO 或其他口令写入源码、提交信息、日志或新的 Markdown。用环境变量，并提供不含真实口令的示例文件。
• 不要把 docs/理解/个人对需求的理解.md 里的连接串复制到其他文件。
• 源码保持可读，不混淆、不加密、不留后门。

改动范围

• 只做当前任务点名的系统。门户视觉任务不要改后台框架，后台任务不要改门户 UI 库。
• 栏目专篇未写时，可以搭工程骨架和公共能力（账号、权限、附件、审核发布、日志、脱敏、站点配置），不要提前实现某个栏目的业务规则。
• 合同示例时限（投诉约 30 个工作日、专家回复约 3 个工作日）做成配置，不写死。

文档索引

文件	用途
docs/分析/综合性需求分析.md	系统划分、范围、待确认项
docs/分析/管理端权限基础功能.md	第一批可建设功能：权限、登录安全、日志、附件、站点配置、敏感词与脱敏
docs/理解/个人对需求的理解.md	个人对三系统和技术选型的原始理解；含本地环境，勿扩散
docs/合同/ 合同技术需求（批注版）.pdf	验收与范围的第一依据
docs/需求/ 网站需求.docx	栏目清单，合同已覆盖的以合同为准
docs/可研/ 可行性研究报告.pdf	旧站问题、等保与验收指标、迁移红线

Agent skills

Issue tracker

Issues and specs live as markdown files under .scratch/<feature-slug>/. See docs/agents/issue-tracker.md.

Triage labels

Five default roles: needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix. See docs/agents/triage-labels.md.

Domain docs

Single-context: root GLOSSARY.md and docs/adr/. See docs/agents/domain.md.