122 lines
8.5 KiB
Markdown
122 lines
8.5 KiB
Markdown
# 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](https://github.com/Daymychen/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](https://gitee.com/playeduxyz/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`.
|
||
|