gsfdc/server/AGENTS.md

服务端 AGENTS.md

本目录是门户和管理后台共用的唯一业务后端。不要再为 portal/ 或 admin/ 各建一套 Python 工程或各接一个数据库。教育平台若最终不采用 PlayEdu，课程与进度也放在这里；若采用 PlayEdu，它自带服务，账号标识仍与本服务对齐。仓库根目录 AGENTS.md 同时有效。

职责

• REST API。没有明确调用方时不做第二套 RPC。
• 账号、角色、菜单与按钮资源、强密码、账号注销。
• 敏感字段加密存储（AES-256 或 SM4）和接口脱敏。
• 附件：公开对象与私有对象分开。私有对象用鉴权或短期链接。上传大小可配置，禁止不限制大小。
• 全量接口访问日志。不记录密码、验证码、身份证号、完整手机号。
• 管理端接口必须登录，且只接受工作人员令牌。会员数据接口只允许本人，只接受会员令牌。两种令牌不能混用。公开接口与登录接口在 /api/site 下分开注册。
• 业务接口只有两个前缀：门户 /api/site，管理后台 /api/admin。不允许在这两个前缀之外新增业务接口。
• JSON 体支持应用层加解密，由环境变量开关控制，门户、管理端和本服务必须使用同一开关和同一算法。默认关闭，便于联调。生产是否开启在部署时同时打开。文件上传和下载不加密。算法用 AES-GCM。密钥放环境变量，不写进源码。这项不代替 HTTPS，也不代替登录鉴权。
• 内容审核与敏感词：未发布数据不能被门户读到。富文本来自 wangEditor-next，保存时按白名单过滤 HTML，去掉脚本、事件属性和非本站图片地址。
• IP 黑名单。

应用层 JSON 加解密按上一节的开关执行。传输加密始终使用 HTTPS。数据库里的身份证、手机号仍然用 AES-256 或 SM4 加密存储，与接口加解密无关。

数据

• MySQL、Redis、MinIO。
• 连接信息只放环境变量。提交 .env.example 时使用占位符，不要从 docs/理解/个人对需求的理解.md 抄真实口令。
• 开发测试库不是生产库。生产在天翼云，规格见根目录 AGENTS.md。

目录约定

栏目专篇未写完时，只允许公共能力进入代码，不按十一项栏目建业务包。

server/
  AGENTS.md
  .env.example
  app/
    api/
      site/       # 前缀 /api/site，其下再分 public 与 member
      admin/      # 前缀 /api/admin，全部要求工作人员登录
    core/         # 配置、鉴权、加解密、日志、脱敏
    models/
    services/

机构名录不要单独造一套与会员无关的机构主数据。报告查询只对照报告备案，不要做文件验真、核验码或报告审核的保存接口，见 docs/adr/0010-report-query-is-filing-lookup.md。数据挖掘、智能估价、中房学和住建厅的数据对接，不要建客户端或同步任务。

投诉时限、专家回复时限放配置，不写死。行业自律的投诉、警示案例、诚信档案和结果公示见 docs/adr/0012-industry-discipline-articles-and-complaint-code.md。

接口约定

• 路径与 JSON 字段使用英文，文档用中文说明业务含义。
• 脱敏在返回前完成，不依赖前端遮盖。需要脱敏的字段在模型或序列化处集中声明。
• 错误响应不回传 SQL、堆栈或内部路径。
• 批量导出和查看敏感数据要写审计日志。