初始化政体志子站

收录 zhengquan-site 前后端完整代码:24 朝数据、24 幅权力结构图、
5 条沿革(67 节点 / 269 条细释)、44 个词条,以及部署配置与接口测试。
This commit is contained in:
袁永志 committed 2026-11-19 11:59:51 +08:00
commit aa12b9f910
58 files changed
+16253

No files matched your search

+281
View File
@@ -0,0 +1,281 @@
# 舆纪历史 · 政体志
`incarnation.cn` 的第四个子站,主题是中国历代**国体、政体、政权组织架构与官制沿革**。从夏商到当代,按朝展示中央与地方的权力结构、各机构的职掌,并用五条专线串起制度在四千年间的因革。
- 站点建议域名:`zhengquan.incarnation.cn`
- 目录:`zhengquan-site/`(前后端同仓,后端直接托管前端)
- 内容:24 个朝代或时期(春秋/战国、三国/两晋/南北朝、五代/十国、北宋/南宋等分卷)、24 幅中央权力结构图(2–4 层、5–9 个分支)、239 处机构、5 条沿革(67 个节点、269 条细释)、44 个词条
## 功能
| 页面 | 说明 |
| --- | --- |
| 总目 `#/` | 竖排书名、朝代尺、八段二十四朝总目(按常规断代分卷:战国、新莽、三国、西晋、东晋、南北朝、十国、南宋等单列),五条沿革入口、凡例(编例说明并入首页第 04 节,不单设页签) |
| 朝代页 `#/dynasty/:slug` | 国体与政体、中央权力结构图(桌面 SVG / 窄屏纵向树)、机构职掌表、地方层级、选官/监察/军事、沿革要点、史料引文 |
| 沿革 `#/threads`、`#/thread/:slug` | 宰相、监察、地方行政、选官、军事五条时间轴,按朝代分节;每节点附分条细释与史料依据 |
| 词典 `#/glossary` | 按类筛选、检索职官与制度术语 |
| 检索 `#/search` | 跨朝代、沿革、词条全文检索,命中高亮 |
设计沿用主站的宣纸、朱印、宋体与细线体系:纸色 `#fdf9f3`、朱红 `#b8261f`、赭金 `#7c5a1f`。字体不加载中文 Web Font:正文走系统无衬线栈(macOS PingFang SC、Windows Microsoft YaHei),标题与机构名走宋体栈(Songti SC / SimSun)。全站响应式,移动端表格自动转为卡片,时间轴与朝代尺可横向滑动。
## 技术栈
- **前端**:原生 ES Modules + 手写 CSS,无构建步骤、无前端框架依赖。哈希路由,直接由后端托管。
- **后端**:Node.js 18+ / Express 4,启动时加载 JSON 数据并做引用校验;提供 REST API、全文检索、静态托管与 SPA 回退。
- **数据**:`backend/src/data/` 下的 JSON 文件,改完重启即可生效;不需要数据库。
## 目录
```
zhengquan-site/
├── package.json # 根级便捷脚本
├── backend/
│ ├── package.json
│ ├── src/
│ │ ├── index.js # 启动入口(PORT 默认 5180)
│ │ ├── app.js # 路由、静态托管、错误处理
│ │ ├── data.js # 数据加载、校验、摘要与统计
│ │ ├── search.js # 轻量全文检索
│ │ └── data/
│ │ ├── meta.json # 站点信息、八个时代
│ │ ├── charts.json # 24 朝组织架构图数据
│ │ ├── threads.json # 五条沿革(含战国、西晋、南北朝、十国、南宋等细化节点)
│ │ ├── glossary.json # 44 个词条
│ │ └── dynasties/*.json # 24 个朝代或时期
│ └── test/smoke.mjs # 接口冒烟测试
├── frontend/
│ ├── index.html
│ ├── favicon.svg
│ ├── og.png
│ └── assets/
│ ├── css/style.css
│ └── js/
│ ├── app.js # 路由与全局事件
│ ├── api.js # API 封装与缓存
│ ├── store.js # 启动数据
│ ├── layout.js # 书眉与页脚
│ ├── orgchart.js # 结构图布局与渲染,窄屏转纵向树
│ ├── util.js
│ └── views/ # 各页面视图
└── deploy/
├── nginx.conf.example
└── zhengquan-site.service
```
## 本地运行
```bash
cd zhengquan-site
npm run install:all # 安装后端依赖
npm start # 启动,默认 http://localhost:5180
```
开发时可用 `npm run dev`(`node --watch`,改后端代码自动重启;前端是静态文件,刷新即可)。
```bash
npm test # 8 项接口冒烟测试
```
环境变量:
| 变量 | 默认 | 说明 |
| --- | --- | --- |
| `PORT` | `5180` | 监听端口 |
| `HOST` | `0.0.0.0` | 监听地址,置于 Nginx 后可改为 `127.0.0.1` |
| `NODE_ENV` | — | 设为 `production` 可关闭请求日志 |
## 数据格式
每个朝代一个文件:`backend/src/data/dynasties/<slug>.json`。
```jsonc
{
"slug": "qin",
"name": "秦",
"fullName": "秦朝",
"subtitle": "皇帝制度、三公九卿与郡县制",
"period": "前221—前207",
"startYear": -221, // 用于排序与朝代尺,公元前为负
"endYear": -207,
"era": "qinhan", // 对应 meta.json 的 eras[].id
"capital": "咸阳",
"founder": "秦始皇嬴政",
"summary": "……",
"tags": ["皇帝制度", "三公九卿", "郡县制"],
"stateForm": { "label": "国体", "value": "……", "note": "……" },
"govForm": { "label": "政体", "value": "……", "note": "……" },
"org": {
"note": "架构说明",
"flow": ["皇帝", "丞相 · 太尉 · 御史大夫", "九卿", "郡", "县"],
"tiers": [
{
"label": "皇帝", "caption": "……",
"nodes": [
{ "name": "皇帝", "duty": "……", "note": "皇权世袭",
"children": [{ "name": "……", "duty": "……" }] }
]
}
]
},
"institutions": [
{ "name": "丞相", "chief": "丞相", "duty": "……", "note": "金印紫绶" }
],
"local": {
"system": "郡县制(郡—县—乡—亭—里)",
"summary": "……",
"levels": [{ "name": "郡", "chief": "郡守", "duty": "……" }],
"note": "……"
},
"selection": { "system": "……", "text": "……" },
"supervision": { "system": "……", "text": "……" },
"military": { "system": "……", "text": "……" },
"changes": [{ "title": "……", "text": "……" }],
"quotes": [{ "text": "……", "source": "《史记·秦始皇本纪》", "paraphrase": false }],
"sources": ["《史记》"],
"prev": "chunqiu", "next": "han-west"
}
```
新增一朝:
1. 复制一个结构相同的 JSON,改 `slug`、`startYear`、`endYear`、`era`。
2. 把相邻朝代的 `next` / `prev` 接上。
3. 若开启新时段,在 `meta.json` 的 `eras` 里加一项;数据按 `era` 字段自动归组。
4. 重启服务。`data.js` 会校验 slug 唯一性与前后引用,坏数据会在启动时报错。
### 组织架构图
`backend/src/data/charts.json` 按 slug 收录各朝架构图,与朝代正文分开维护,便于单独调整图形:
```json
"qin": {
"caption": "皇帝之下三公分权,九卿分理庶务……",
"root": {
"name": "皇帝",
"note": "总揽军政",
"tone": "root",
"children": [
{
"name": "丞相",
"note": "百官之长 · 领九卿",
"tone": "core",
"items": ["奉常", "郎中令", "卫尉", "太仆", "廷尉"]
}
]
}
}
```
- `tone`:`root` 朱红、`core` 金底、`watch` 绿底(监察)、`local` 虚线框(地方)。
- `items`:机构内部的下属职官或部门,渲染为节点内的小标签。
- `children`:下级机构。桌面端生成横向树状图,860px 以下自动切换为纵向缩进树。
- `dashed`:为 true 时连线用虚线,表示监察、派出或地方直隶。
- 每个朝代都必须在 `charts.json` 中有图;缺失会在服务启动时报错。
### 沿革与词条
`threads.json` 的节点结构按朝代分节:`year` 为朝代名(页面主标签),`era` 为大时段(夏商周、秦汉、魏晋南北朝、隋唐、宋元、明清、近现代),`when` 为具体年份或时期,显示在节点头部右侧。`details` 为分条细释,`source` 为主要史料;二者在服务启动时校验,每节点至少 2 条细释:
```json
{
"year": "明", "era": "明清", "when": "1380", "dynasty": "ming",
"title": "废除丞相", "text": "……",
"details": [
{ "label": "胡惟庸案", "text": "……" },
{ "label": "制度代价", "text": "……" }
],
"source": "《明太祖实录》《明史·职官志》"
}
```
`glossary.json` 的词条结构:
```json
{ "term": "军机处", "category": "中央", "definition": "……", "related": ["qing"] }
```
## API
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/bootstrap` | 站点信息、时代、统计、朝代摘要、沿革摘要、随机史料 |
| GET | `/api/dynasties` | 朝代摘要列表 |
| GET | `/api/dynasties/:slug` | 朝代详情(含前后朝与相关词条) |
| GET | `/api/threads` | 五条沿革全文 |
| GET | `/api/threads/:slug` | 单条沿革(节点补朝代名与年代) |
| GET | `/api/glossary?q=&category=` | 词条筛选 |
| GET | `/api/search?q=&limit=` | 跨三类内容检索 |
| GET | `/api/quote` | 随机一条史料 |
| GET | `/api/health` | 健康检查 |
除 `/api/*` 外的路径都会回退到 `frontend/index.html`,可直接支持哈希路由。
## 部署
后端同时托管前端,因此只需要一个 Node 进程,不需要额外的前端服务器。
```bash
# 服务器上
git clone <repo> /opt/zhengquan-site
cd /opt/zhengquan-site
npm --prefix backend ci --omit=dev
PORT=5180 NODE_ENV=production node backend/src/index.js
```
用 systemd 常驻:
```bash
sudo cp deploy/zhengquan-site.service /etc/systemd/system/
sudo chown -R www-data:www-data /opt/zhengquan-site
sudo systemctl daemon-reload
sudo systemctl enable --now zhengquan-site
```
Nginx 反向代理与 HTTPS 见 `deploy/nginx.conf.example`。要点:
- `proxy_pass http://127.0.0.1:5180;`
- `/assets/` 可加长缓存(后端已设 `Cache-Control: max-age=604800`)
- `index.html` 不缓存(后端已设 `no-cache`),保证发版后立即生效
- 证书可用 certbot 申请,把示例中的路径替换为实际证书路径
## 挂到主站
主站首页目前写着「凡三处」,需要改为「凡四处」,并在 `toc-list` 里追加一行。可直接使用主站现有的样式类:
```html
<li class="row">
<a class="row-link" href="https://zhengquan.incarnation.cn" target="_blank" rel="noopener">
<span class="row-no">04</span>
<span class="row-name">
政体志
<span class="row-desc">夏商至当代 · 国体政体 · 官制沿革</span>
<span class="row-detail"><b>16</b> 朝 · <b>162</b> 处机构 · <b>5</b> 条沿革</span>
</span>
<span class="row-lead" aria-hidden="true"></span>
<span class="row-num"><b>40</b> 词条</span>
<span class="row-go">
在线
<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
<path d="M7 17 17 7M8 7h9v9" />
</svg>
</span>
</a>
</li>
```
同时建议更新:
- 主站 `<title>` / `description` / `og:description` 中的「三处」「三处刊行」为「四处」;
- 首屏题记补一句制度卷的读法;
- 「摘录」区可加三条政体志的条目,链到 `#/dynasty/qin`、`#/thread/xiangquan`、`#/glossary?q=三省六部`。
## 口径与资料来源
- **国体**指国家的阶级性质,**政体**指政权的组织形式。古代部分采用中国史学界通行表述(夏商周为奴隶主阶级专政、秦汉至清为地主阶级专政),并对史料局限与学界讨论随文注明。
- 年代取通行说法;先秦年代多依夏商周断代工程。制度名称、官称从正史与政书,异说另注。
- 引文标出处;属于今人概括而非原文的,标「大意」。
- 主要依据:历代正史职官志/百官志、《周礼》《唐六典》《通典》《文献通考》《明会典》《清会典》、《中华民国临时约法》《中华人民共和国宪法》,以及钱穆《中国历代政治得失》、严耕望《中国地方行政制度史》等近人研究。
## 许可
内容与代码用于 `incarnation.cn` 及其子站。转载、引用请注明出处;史料引文请复核原书。